Skip to main content
The Grand Charter public API gives your integration org-scoped access to the platform: cases and leads, clients and contacts, documents and folders (including presigned uploads), notes, tasks, calendar items, deadlines, intake survey data, e-sign, billing and settlement funds, referrals, communications logging, medical records retrieval (with an elevated-access posture), saved reports and bulk exports, and a unified event feed with webhook wakeups. Every request is authenticated with an integration API key (a service account credential) and authorized by an explicit scope per endpoint. Resource requests default to the organization that issued the key. Supported resource endpoints let an authorized HQ key select one descendant with organizationId; saved report runs also support multi-organization organizationIds. See HQ authorization. The full endpoint list lives in the API Reference tab. Paths, methods, required scopes, and request schemas are generated directly from the API’s route handlers and the validation schemas they parse with. For changes to API routes, request-schema dependencies, or the generator, CI rebuilds the reference and fails if the generated output no longer matches the committed artifact. Response bodies are documented as the standard success envelope with a per-operation payload description; the core domains (cases, leads, tasks, events, /me) additionally carry full response models.

​
Base URL

All paths are under /api/v1 on the production origin:

​
Conventions

These conventions hold across the entire /api/v1 surface:
  • Paths are lowercase kebab-case; JSON bodies and responses are camelCase. One casing, everywhere.
  • Envelope: successful responses are { "success": true, "<resource>": ... }; errors are { "success": false, "error": "<message>", "code": "<ERROR_CODE>" }. Server errors (5xx) are always scrubbed to a generic message with code INTERNAL_ERROR.
  • Pagination uses opaque keyset cursors: pass ?after=<cursor>&limit=<1..500> and read nextCursor from the response. There is no offset paging.
  • Timestamps are ISO-8601 UTC. Money is always integer cents.
  • Soft delete + restore: domains that soft-delete expose DELETE plus a POST .../restore endpoint, and their list endpoints accept includeDeleted=true for sync consumers.
  • Idempotency: most mutations require an X-Idempotency-Key header — each operation’s reference entry says so. The first response is stored and replayed for identical retries; reusing a key with a different request returns 409 IDEMPOTENCY_CONFLICT. Exceptions: POST /leads, PATCH /leads/{leadId}, and PATCH /cases/{caseId} do not consume the header — a blind retry there can create duplicates, so confirm the outcome with a read before retrying.
  • Optimistic concurrency: revisioned entities (documents, folders) require If-Match: "<revision>" on writes and return an ETag; a stale revision returns 409 STALE_REVISION.
  • State transitions are sub-endpoints (/complete, /cancel, /transitions, /restore), never mutable status fields. Supported transitions rejected by the resource’s current state return 409 INVALID_STATE_TRANSITION; target values outside a request schema’s enum return 400 VALIDATION_FAILED.
  • Financial records are void-not-delete: checks, disbursements, and related money records are never hard-deleted through the API.

​
Rate limits

Requests are rate limited per API key with a Redis sliding window. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a 429 response includes Retry-After. Report execution (POST /reports/{reportId}/run) additionally enforces a dedicated 5 runs/min budget. Each operation in the API Reference names its tier via the x-rate-limit-tier extension.

​
Sensitive data (PII/PHI)

The platform stores protected health information and high-sensitivity PII. The API exposes it only behind hard guardrails:
  1. Isolated, admin-granted scopes. medical:read, medical:write, and the field-gating pii:read are never bundled or implied by any other scope, and can only be granted by platform administrators after compliance verification. They cannot be added through self-serve key management.
  2. A responsible human. Keys holding elevated scopes must have an acting attorney configured, so every access is attributable to a person as well as a service account.
  3. Audited reads. Every request to a PHI-gated endpoint — and every response that includes pii:read fields — writes a HIPAA audit entry. Reads are audited, not just writes.
  4. No PHI in events or webhooks. Webhook payloads are wakeup-only by design. Feed events for medical entities carry IDs and event type only, and all feed payloads pass sensitive-field redaction. Full records are only available via authenticated GETs.
  5. Tighter operational limits. The sensitive rate tier applies, presigned URLs for medical document content expire in 60 seconds (vs. 300 standard), keys holding elevated scopes have a shorter maximum lifetime (1 year), and all PHI/PII responses are served with Cache-Control: private, no-store.
Without pii:read, gated fields (SSN, date of birth, and other sensitive fields) are omitted from responses — not blanked — so their absence is detectable.

​
A first request

GET /me is the canonical credential health-check: any valid key may call it, no scope required.
Next: Authentication covers credentials in detail, and Scopes lists the full permission vocabulary.