Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.have-foresight.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Request format

  • Transport: HTTPS only (TLS 1.2+). Plain HTTP is rejected.
  • Methods: GET, POST, PUT, PATCH, DELETE.
  • Body encoding: application/json; charset=utf-8. The API does not accept application/x-www-form-urlencoded or multipart/form-data except on file-upload endpoints (see Documents).
  • Headers:
    • X-API-Key: fsk_... (required) — see Authentication.
    • Content-Type: application/json (required for write methods).
    • Idempotency-Key: <uuid> (recommended for write methods) — see Idempotency.
    • X-Request-Id: <uuid> (optional) — echoed in the response and in our logs for traceability.

​
JSON conventions

  • Field names are camelCase.
  • Identifiers are URL-safe strings prefixed with the resource type (e.g. pat_... for patients, clm_... for claims, pa_... for prior authorizations).
  • Dates without a time are YYYY-MM-DD (ISO 8601).
  • Date-times are RFC 3339 / ISO 8601 with timezone, always serialized in UTC: 2026-05-03T19:42:11.402Z.
  • Monetary values are integer cents (USD), never floats. 12345 means $123.45.
  • Enum values are lowercase snake_case strings.
  • Nullable fields are explicitly null, not omitted.

​
Response envelope

Every successful response is wrapped in a consistent envelope: 
{
  "data": { ... },
  "meta": {
    "requestId": "req_01J5KA3XQR9V2W4Y6Z8B0D2F4H"
  }
}
For list endpoints: 
{
  "data": [ ... ],
  "meta": {
    "requestId": "req_...",
    "pagination": {
      "limit": 50,
      "nextCursor": "eyJ..."
    }
  }
}
See Pagination for the cursor format. Errors use a different envelope — see Errors.

​
Status codes

CodeMeaning
200OK — request succeeded; response body present.
201Created — resource created; response body has new resource.
202Accepted — work queued (e.g. async eligibility check).
204No Content — request succeeded; no response body.
400Bad Request — validation failed; see error body.
401Unauthorized — invalid or missing API key.
403Forbidden — key valid but lacks scope or org access.
404Not Found — resource does not exist (or you can’t see it).
409Conflict — idempotency-key reuse, or business-rule clash.
422Unprocessable — request was valid JSON but semantically wrong.
429Too Many Requests — see Rate limits.
5xxServer error — retry with exponential backoff.

​
Field expansion

Some endpoints support an expand query parameter that hydrates referenced objects in-line instead of returning just IDs: 
GET /v1/claims/clm_abc?expand=patient,insurancePolicy
Where supported, the documented endpoint reference lists the expandable fields. Expansion is bounded — you cannot deeply nest expansions or expand through more than two relationships.

​
Sparse fieldsets

You can request only specific fields with fields: 
GET /v1/claims?fields=id,status,totalCharges
This reduces payload size and is useful when polling list endpoints. Always include id.