API Reference

This page is the canonical reference for the SAVHN REST API — authentication, request/response conventions, and the categorized list of API domains available across the platform. Read Developer Portal Overview first if you haven't obtained a bearer token yet.

Authentication

Every API domain uses the same bearer token scheme. There is no per-domain authentication variant.

POST /api/auth/login
Content-Type: application/json

{
  "email": "you@yourorg.com",
  "password": "••••••••"
}

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600,
    "user": {
      "id": "usr_2f9c1a",
      "email": "you@yourorg.com",
      "orgId": "org_7b21d4",
      "roles": ["org_admin"]
    }
  }
}

Attach the returned token to every subsequent request:

GET /api/crm/deals
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Requests without a valid token receive 401 Unauthorized. Requests with a valid token but insufficient role permission for the target resource receive 403 Forbidden. Requests targeting a module that isn't enabled for the organization receive 404 Not Found.

REST conventions

These conventions are consistent across every domain listed below.

• Base structure: resources are namespaced by domain and follow standard REST pluralization, e.g. /api/crm/leads, /api/crm/leads/{id}, /api/hrms/employees/{id}/leave-requests.
• Methods: GET (read), POST (create), PATCH (partial update), PUT (full replace, used sparingly), DELETE (remove or archive, depending on the resource's retention rules).
• Response envelope: successful responses wrap the payload in a consistent shape:

{
  "success": true,
  "data": { "...": "..." },
  "meta": { "page": 1, "pageSize": 25, "total": 118 }
}

• Error shape: errors follow a consistent shape with a machine-readable code and human-readable message:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'email' is required.",
    "field": "email"
  }
}

• Pagination: list endpoints accept page and pageSize query parameters (or cursor-based pagination on high-volume domains like Timeline and Chat) and return pagination metadata in meta.
• Filtering & sorting: list endpoints generally accept filter[field]=value style query parameters and a sort parameter (e.g. sort=-createdAt for descending).
• Idempotency: write endpoints that are safe to retry generally accept an Idempotency-Key header; consult the specific domain's guidance for endpoints where this matters most (e.g. Finance transactions).
• Multi-tenancy: every record is implicitly scoped to the authenticated token's organization — there is no orgId parameter to pass on requests; it is derived from the token, and cross-tenant reads are structurally impossible through the API, not just permission-denied.
• Versioning: breaking changes are introduced under a new path segment (e.g. /api/v2/...) rather than mutating existing behavior in place; unversioned paths (/api/crm/...) represent the current stable surface.

Illustrative example: creating a CRM lead

POST /api/crm/leads
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "firstName": "Priya",
  "lastName": "Nair",
  "email": "priya.nair@example.com",
  "company": "Example Retail Pvt Ltd",
  "source": "website_form",
  "ownerId": "usr_2f9c1a"
}

{
  "success": true,
  "data": {
    "id": "lead_9c31af",
    "firstName": "Priya",
    "lastName": "Nair",
    "email": "priya.nair@example.com",
    "company": "Example Retail Pvt Ltd",
    "source": "website_form",
    "status": "new",
    "ownerId": "usr_2f9c1a",
    "createdAt": "2026-07-30T09:02:11Z"
  }
}

This is representative of the request/response style used across all business-object endpoints; exact field names and required fields vary by resource and are documented per-domain within the Developer Portal's live schema explorer.

API domain catalog

The table below groups every API domain by category. All domains sit under /api/ and follow the conventions above.

Authentication & Identity

Domain	Purpose
/api/auth	Login, token refresh, logout, password reset
/api/users	User profile and account management
/api/orgs	Organization profile, departments, locations, calendar

Core Business

Domain	Purpose
/api/crm	Leads, deals, contacts, pipelines
/api/hrms	Employees, attendance, leave, org chart
/api/payroll	Pay runs, payslips, compensation structures
/api/finance	Invoices, expenses, accounts, payments
/api/projects	Projects, tasks, milestones, timesheets
/api/tickets	Support/internal tickets, SLAs, escalations
/api/meetings	Scheduling, agendas, notes, recordings metadata
/api/chat	Channels, direct messages
/api/documents	File storage, folders, sharing
/api/reports	Dashboards and report definitions/results
/api/client-portal	External client-facing project/invoice/ticket views

AI & Intelligence

Domain	Purpose
/api/ai-studio	Custom AI agent/workflow configuration
/api/ai-assistant	Conversational assistant sessions and actions
/api/manager-copilot	Manager-facing team insight and action surfaces
/api/business-brain	Cross-module knowledge and Q&A over org data
/api/revenue-intelligence	Pipeline and revenue analytics (built on CRM + Finance)
/api/journey-orchestrator	Customer/lead journey definitions and execution
/api/workforce-intelligence	Workforce analytics (built on HRMS)

Industry Clouds

Domain pattern	Purpose
/api/industries/{industry-slug}/...	Industry-specific resources (e.g. construction, healthcare, real-estate, legal-services) layered on top of core domains

Industry Cloud endpoints reuse core domain resources (a construction Industry Cloud's site visits still live under /api/projects) and add industry-specific resources only where the workflow doesn't map cleanly onto a core module.

Platform & Marketing Content

Domain	Purpose
/api/knowledge	Knowledge Center articles
/api/docs	Documentation Portal pages (this content)
/api/modules	Module Marketplace catalog and per-org enablement state

Platform Operations

Domain	Purpose
/api/developer	Developer Portal: API credentials, webhook registration, delivery logs
/api/superadmin	Platform-operator-only endpoints (cross-tenant administration, not available to org-level tokens)

Common query parameters across list endpoints

While exact filterable fields vary by resource, the following query parameter patterns are consistent wherever a list endpoint supports them:

Parameter	Example	Behavior
page, pageSize	?page=2&pageSize=50	Offset-style pagination
cursor	?cursor=eyJpZCI6MTIzfQ	Cursor-based pagination, used on high-volume domains
filter[field]	?filter[status]=open	Exact-match filtering on a given field
sort	?sort=-createdAt	Sort ascending by default, prefix - for descending
include	?include=owner,tags	Expand related resources inline rather than requiring a follow-up request
q	?q=priya	Free-text search where the resource supports it

Not every list endpoint supports every parameter above — consult the Developer Portal's live schema explorer for the authoritative set per resource, since some high-cardinality domains (like Chat messages) restrict filtering more tightly than low-volume ones (like Departments) for performance reasons.

Working with nested and related resources

Many resources reference others — a Project task references a Project and an assignee; an Invoice references a Client and, in some Industry Cloud configurations, an Enrollment. Two general patterns apply across the API:

• Foreign keys are returned as IDs by default (e.g. "ownerId": "usr_2f9c1a"), keeping payloads lean for list views.
• Use include to expand a related resource inline when you need more than the ID in a single round trip, rather than issuing a follow-up request per record — this matters most when rendering a list of many records that each reference a related object you need to display.

HTTP status codes you'll encounter

Code	Meaning
200	Success
201	Resource created
400	Malformed request / validation error
401	Missing or invalid bearer token
403	Valid token, insufficient permission
404	Resource or module not found/not enabled
409	Conflict (e.g. duplicate unique field)
422	Semantically invalid request (passes schema validation, fails business rules)
429	Rate limit exceeded
500	Unexpected server error

Where to go next

• Developer Portal Overview for how to obtain and manage credentials.
• Building Integrations with SAVHN for webhook patterns and integration design guidance.
• The Developer Portal's live schema explorer for the authoritative, per-endpoint field list for your organization's enabled modules.