API reference

This page covers the shared conventions for the Prior Auth API. Use the generated OpenAPI pages in the sidebar for route-level request and response schemas.

Base URLs

Environment	Base URL	Credential
Sandbox	`https://api.sandbox.trycollate.ai`	Sandbox bearer token
Production	`https://api.trycollate.ai`	Production bearer token

The Quickstart uses sandbox because it includes /v1/sandbox/* testing calls.

Authentication

All /v1/* endpoints use bearer authentication. GET /health is public.

Authorization: Bearer your-token

Use:

a WorkOS organization API key or WorkOS session token for /v1/prior-auth/*, /v1/files/*, /v1/payers/*, and /v1/sandbox/*

Requests without a valid bearer token return 401 unauthorized.

Use the same base URL and bearer token for both the core integration routes and /v1/sandbox/* within sandbox. Sandbox and production use separate credentials, even when both credentials belong to the same WorkOS organization.

https://api.trycollate.ai does not expose /v1/sandbox/*. A valid production credential cannot be used to call sandbox-only routes.

Endpoint groups

Prior authorization

Method	Endpoint	Purpose
GET	`/v1/prior-auth/authorizations`	List authorizations with cursor pagination and filters.
POST	`/v1/prior-auth/authorizations`	Create a draft authorization and resolve the matching questionnaire internally.
GET	`/v1/prior-auth/authorizations/{authorizationId}`	Read the current authorization state.
PATCH	`/v1/prior-auth/authorizations/{authorizationId}`	Update mutable case data.
POST	`/v1/prior-auth/authorizations/{authorizationId}/preview`	Generate the current preview documents.
POST	`/v1/prior-auth/authorizations/{authorizationId}/attachments`	Attach a previously uploaded file.
DELETE	`/v1/prior-auth/authorizations/{authorizationId}/attachments/{attachmentId}`	Remove an attachment while the authorization is mutable.
POST	`/v1/prior-auth/authorizations/{authorizationId}/submit`	Submit the authorization.
POST	`/v1/prior-auth/authorizations/{authorizationId}/cancel`	Cancel the authorization.
GET	`/v1/prior-auth/authorizations/{authorizationId}/events`	List lifecycle events.
GET	`/v1/prior-auth/authorizations/{authorizationId}/artifacts`	List generated and payer-provided artifacts.
POST	`/v1/prior-auth/authorizations/{authorizationId}/actions/{actionId}/resolve`	Resolve a payer request for information.

Files

Method	Endpoint	Purpose
POST	`/v1/files`	Create a file upload session.
PUT	`/v1/files/{fileId}/content`	Upload file bytes.
POST	`/v1/files/{fileId}/complete`	Mark the uploaded file ready for use.
GET	`/v1/files/{fileId}`	Read file metadata and the `downloadUrl` once the file is ready.

Sandbox

Method	Endpoint	Purpose
POST	`/v1/sandbox/prior-auth/authorizations/{authorizationId}/payer-events`	Inject an approval, denial, or payer request for information for testing.

Payer catalog

Method	Endpoint	Purpose
GET	`/v1/payers`	List supported payers.

System

Method	Endpoint	Purpose
GET	`/health`	Health check.

Request conventions

JSON

Requests and responses use JSON unless the endpoint is uploading binary content or returning no response body.

Idempotency

POST /v1/prior-auth/authorizations and POST /v1/prior-auth/authorizations/{authorizationId}/submit accept an optional Idempotency-Key header.

Idempotency-Key: create-auth-abc123

Behavior:

same create key + same request body: returns the existing authorization
same create key + different request body: returns 409 idempotency_key_reused_with_different_request
same submit key + same authorization: returns the current submission result without duplicating artifacts
same submit key + different authorization: returns 409 idempotency_key_reused_for_different_authorization

Files

Supporting documents and sandbox payer documents are uploaded through the file API. The sequence is:

POST /v1/files
PUT /v1/files/{fileId}/content
POST /v1/files/{fileId}/complete
reference the resulting fileId from an authorization attachment request or sandbox payer event

The public contract does not require raw Blob URLs in request payloads. When you upload content with PUT /v1/files/{fileId}/content, set Content-Type to exactly the value you used when you created the file session.

Patch semantics

PATCH /v1/prior-auth/authorizations/{authorizationId} uses explicit merge rules:

patient, coverage, and requestedBy merge by field
locations.servicing and locations.referring replace the provided slot object
providers replaces the full provider collection
questionnaireResponse merges by linkId
incoming answers for disabled questionnaire items are rejected with questionnaire_item_not_enabled
previously stored answers are cleared automatically when an upstream answer disables their branch

Requirement-defining inputs are not mutable on the authorization. If payer coverage context or the coded service changes, create a new authorization.

Error shape

Every error response uses the same envelope:

{
  "code": "validation_error",
  "message": "Request validation failed.",
  "details": {
    "...": "..."
  },
  "issues": [
    {
      "field": "workflowState",
      "code": "invalid_enum",
      "message": "..."
    }
  ]
}

details is optional
issues is optional

Validation, query parsing, header parsing, and domain errors all use this shape.

Common errors

Status	Code	Meaning
400	`validation_error`	Request body, query parameters, or headers failed validation.
400	`invalid_cursor`	The supplied pagination cursor is invalid.
400	`questionnaire_item_not_enabled`	A request tried to write an answer for a questionnaire item that is currently disabled.
401	`unauthorized`	Missing or invalid bearer token.
403	`insufficient_permissions`	The credential is valid, but it does not have access to the target environment.
404	`unsupported_case`	No requirement template matches the provided coverage and service case.
404	`authorization_not_found`	Authorization ID not found.
404	`action_not_found`	Action ID not found.
404	`attachment_not_found`	Attachment ID not found.
404	`file_not_found`	File ID not found.
409	`validation_failed`	Submit detected blocking validation issues and created `validation_issue` actions.
409	`authorization_not_submittable`	Submit was attempted in the wrong state or while blocking actions were open.
409	`authorization_not_updatable`	Update was attempted in an immutable state.
409	`authorization_attachments_not_mutable`	Attachment mutation was attempted in an immutable state.
409	`authorization_not_cancellable`	Cancel was attempted in a disallowed state.
409	`authorization_not_previewable`	Preview was attempted in a disallowed state.
409	`idempotency_key_reused_with_different_request`	Create idempotency key was reused with a different request body.
409	`idempotency_key_reused_for_different_authorization`	Submit idempotency key was reused for a different authorization.
409	`action_already_resolved`	The action was already resolved.
409	`action_not_resolvable`	The action is system-managed and cannot be resolved manually.
409	`file_not_ready`	A file was referenced before upload completion.
409	`file_not_uploaded`	File completion was requested before bytes were uploaded.
409	`file_upload_already_completed`	Upload content was sent again for a file that is already ready.
409	`file_content_type_mismatch`	Uploaded file bytes used a `Content-Type` that does not match the file session.
409	`file_purpose_mismatch`	A file was used for the wrong operation, such as using a sandbox payer document as an authorization attachment.
409	`unsupported_attachment_mime_type`	An authorization attachment used an unsupported MIME type.
409	`inbound_event_not_allowed_for_state`	A sandbox payer event was sent while the authorization was not `pending_payer`.

Pagination

List endpoints use cursor pagination.

Parameter	Type	Default	Description
`limit`	integer	25	Number of items to return, from 1 to 100.
`cursor`	string	—	Opaque cursor returned from a previous list response.

Response shape:

{
  "data": [],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAzLTEyVDA5OjAwOjAwLjAwMFoiLCJpZCI6ImNt..."
  }
}

Pass nextCursor back unchanged.

Filters

GET /v1/prior-auth/authorizations supports:

repeated workflowState query parameters
repeated decisionState query parameters
payerId
memberId
urgency
createdAfter
createdBefore

Example:

?workflowState=needs_input&workflowState=ready_to_submit&decisionState=pending

Invalid filter or cursor values return 400.

Previews, artifacts, and events

POST /v1/prior-auth/authorizations/{authorizationId}/preview is the pre-submit generation step. It returns:

submittable
validationIssues
contextRequirements
questionStates
activeRequirementGroups
supportingDocumentRequests
mappingSummary
documents.filledForm
documents.draftPacket

Authorization responses also include static supportingDocumentationGuidance, while preview exposes the currently active supportingDocumentRequests for the case in its present state. After submit, use the authorization, events, and artifacts endpoints to track lifecycle state and preserve the documents correlated to the case.

OpenAPI

The generated OpenAPI document on this site is the schema source of truth for:

request and response bodies
enum values
required fields
route-specific status codes

Guides

Authorizations

Payers

Files

Sandbox API

System

Base URLs

Authentication

Endpoint groups

Prior authorization

Files

Sandbox

Payer catalog

System

Request conventions

JSON

Idempotency

Files

Patch semantics

Error shape

Common errors

Filters

Previews, artifacts, and events

OpenAPI

Guides

Authorizations

Payers

Files

Sandbox API

System

​Base URLs

​Authentication

​Endpoint groups

​Prior authorization

​Files

​Sandbox

​Payer catalog

​System

​Request conventions

​JSON

​Idempotency

​Files

​Patch semantics

​Error shape

​Common errors

​Pagination

​Filters

​Previews, artifacts, and events

​OpenAPI

Base URLs

Authentication

Endpoint groups

Prior authorization

Files

Sandbox

Payer catalog

System

Request conventions

JSON

Idempotency

Files

Patch semantics

Error shape

Common errors

Pagination

Filters

Previews, artifacts, and events

OpenAPI