Why we built this
Most prior auth integrations treat the payer questionnaire as a static form. Your system renders it, collects answers, and sends the packet. If the answers are complete, it looks ready. But payer forms aren’t static. They branch. A “No” on question 3 disables questions 4 through 7 and activates an entirely different set of follow-ups. A change to the provider’s specialty makes a field required that wasn’t before. A answer to a parent question invalidates three downstream answers that were already filled in. When your system doesn’t understand these rules, submissions look complete but aren’t. A single incorrectly filled field — an answer left over from the wrong branch, a clinical criterion that was required but never asked — is enough for a payer to deny the request. One bad field, and the patient waits longer for care. This API doesn’t let that happen. It understands the form:- When an upstream answer changes, stale downstream answers are automatically cleared.
- Answers to questions that aren’t currently active are rejected.
- Submission is blocked until every required field, contextual dependency, and grouped validation rule is satisfied.
- At every step, the API tells you exactly what’s still needed to reach a clean submission.
Integration flow
Create the authorization
Send payer coverage context, a coded service, diagnoses, and your case metadata. The API creates a draft authorization and returns the resolved FHIR R4
Questionnaire immediately.Complete the case data
Patch questionnaire answers on the authorization and attach any supporting files you want included in the submission packet.
Generate a preview
Call the preview endpoint to render the current filled form and draft packet. Use
submittable, validationIssues, contextRequirements, and activeRequirementGroups to decide whether the case is ready.Core resources
| Resource | Purpose |
|---|---|
| Authorization | Durable work item for data collection, preview, submission, and lifecycle tracking. |
| File | Uploadable file resource used for supporting documents and sandbox payer documents. |
| Action | Blocking work that must be resolved before the authorization can continue. |
| Artifact | Generated or payer-provided document correlated to an authorization. |
| Event | Immutable audit record for lifecycle changes. |
State model
Each authorization exposes two independent state fields:| Field | Values | Meaning |
|---|---|---|
workflowState | needs_input, ready_to_submit, submitting, pending_payer, action_required, completed, cancelled | Operational state of the case. |
decisionState | unknown, pending, approved, denied | Current payer decision, if any. |
Payer catalog
Use the catalog endpoint to determine what the API currently supports: Use the returnedpayerId in authorization creation. If the coverage and service combination is not available, authorization creation returns unsupported_case.
Environments and authentication
| Environment | Base URL | What to use |
|---|---|---|
| Sandbox | https://api.sandbox.trycollate.ai | Sandbox credential for integration testing, including /v1/sandbox/* |
| Production | https://api.trycollate.ai | Production credential for live traffic |
Next steps
Quickstart
Create, preview, submit, and test a full authorization flow with curl.
Authorization lifecycle
Review workflow states, actions, submission semantics, and idempotency.
Sandbox testing
Use the sandbox endpoint to inject payer approvals, denials, and requests for information.
API reference
Review authentication, files, errors, pagination, and endpoint conventions.