Workflow

1. Create a draft PA request with patient, payer, provider, and service details.
2. Attach documents and call validation until no open tasks remain.
3. Finalize the request to lock its core clinical fields and start packet preparation.
4. Track lifecycle updates by polling the request or consuming signed webhooks.

Create a request

Provide an Idempotency-Key header when creating a request. Retrying with the same key and body returns the original result; reusing the key with a different body returns HTTP 409. The key is separate from external_id, which remains your business reference.

{
  "external_id": "ehr_pa_case_4821",
  "patient": {
    "first_name": "Maya",
    "last_name": "Patel",
    "date_of_birth": "1984-07-19",
    "member_id": "W123456789"
  },
  "payer": {
    "id": "payer_anthem_bcbs"
  },
  "requesting_provider": {
    "npi": "1234567890"
  },
  "service": {
    "date": "2026-08-12",
    "type": "botulinum_toxin_injection",
    "procedures": [
      { "code": "J0585", "code_system": "HCPCS" },
      { "code": "64615", "code_system": "CPT" }
    ],
    "diagnoses": [
      { "code": "G43.719", "code_system": "ICD-10-CM" }
    ]
  }
}

A successful create returns HTTP 201.

{
  "id": "pa_01K2Q03TSPV5ND4X7M9J8C2R6A",
  "external_id": "ehr_pa_case_4821",
  "status": "draft",
  "decision": null,
  "documents": [],
  "created_at": "2026-07-28T11:10:03Z",
  "updated_at": "2026-07-28T11:10:03Z",
  "trace_id": "tr_01K2Q03TT73B5F0Y6WP9G4N8CM"
}

Identifiers

Attach documents

1. Create the document and request an upload

Send document metadata as JSON. Kairos validates the declared file type and size, creates the durable document resource, and returns temporary presigned upload instructions. A successful request returns HTTP 201.

{
  "type": "clinical_note",
  "file_name": "visit-note.pdf",
  "content_type": "application/pdf",
  "size_bytes": 482113,
  "supersedes_document_id": null
}

{
  "document": {
    "id": "doc_01K2Q0A7S9V3N6M8R4T1C5B2FH",
    "type": "clinical_note",
    "file_name": "visit-note.pdf",
    "content_type": "application/pdf",
    "size_bytes": 482113,
    "status": "awaiting_upload",
    "supersedes_document_id": null,
    "created_at": "2026-08-03T16:20:00Z"
  },
  "upload": {
    "url": "https://presigned-upload-url",
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    },
    "expires_at": "2026-08-03T16:30:00Z"
  },
  "trace_id": "tr_01K2Q0A7T6F8D3P5X9W1M4R2VC"
}

2. Upload the file bytes

Send the raw file bytes using the returned method and headers exactly as supplied. Do not send a Kairos API credential to the upload URL; the short-lived URL authorizes only that upload.

3. Confirm completion

No request body is required. Kairos verifies that the uploaded object exists and its size matches before accepting completion. The operation is safe to repeat after a network timeout; a repeat returns the document's current status.

{
  "document": {
    "id": "doc_01K2Q0A7S9V3N6M8R4T1C5B2FH",
    "status": "processing"
  },
  "trace_id": "tr_01K2Q0B9E7Y4H2N6K8M3P5R1VA"
}

Document statuses

Retrieve the PA resource to observe the latest status of its documents. Clients must tolerate additional document status values introduced within v1.

Documents are append-only after finalization. To correct a document, upload the replacement with supersedes_document_id; Kairos preserves both versions and uses the newer one. Additional supporting documents may be added until the PA reaches completed.

Validate, resolve tasks, and finalize

Validation may be called repeatedly. It recalculates readiness and reconciles task state without advancing the lifecycle. The response's tasks array contains only tasks whose status is currently open.

{
  "ready": false,
  "tasks": [
    {
      "id": "task_01K2Q0NW3E0Z5PTJ9R8M2C7B4A",
      "message": "Upload a clinical note documenting prior treatment response.",
      "status": "open"
    }
  ],
  "trace_id": "tr_01K2Q0NW4F6C8DT3V1Y7M5P9RA"
}

Resolve a task with a written response, supporting document IDs, or both. At least one of response or document_ids is required. Resolving a task preserves it in the request's task history with a status of resolved.

{
  "response": "This is continuation therapy after a documented prior response.",
  "document_ids": ["doc_01K2Q0A7S9V3N6M8R4T1C5B2FH"]
}

{
  "id": "task_01K2Q0NW3E0Z5PTJ9R8M2C7B4A",
  "message": "Clarify whether this is initial or continuation therapy.",
  "status": "resolved",
  "trace_id": "tr_01K2Q0P8C4V7H9M3N6R1T5B2FA"
}

Finalization succeeds only when ready is true. It locks patient, payer, provider, and service fields, moves the request into preparation, and returns the current PA resource with HTTP 200. Repeating finalization after a successful response safely returns the current PA instead of applying the transition twice.

If required information or open tasks prevent finalization, Kairos returns HTTP 422 with error code INCOMPLETE_REQUEST and the current open tasks. HTTP 409 with INVALID_STATE is reserved for a lifecycle state that does not permit finalization. Create a new request when locked core details need to change.

Retrieve a request

Retrieve the resource for its current lifecycle, payer reference, and decision. The tasks endpoint returns actionable requirements and clarification questions. Each task contains an immutable id, a message, and a status of open or resolved.

By default, the endpoint returns tasks in either status. Filter with ?status=open or ?status=resolved. Repeat the parameter to request multiple statuses.

{
  "id": "pa_01K2Q03TSPV5ND4X7M9J8C2R6A",
  "external_id": "ehr_pa_case_4821",
  "status": "completed",
  "decision": {
    "outcome": "approved",
    "payer_reference": "AUTH-66018",
    "valid_from": "2026-08-01",
    "valid_to": "2027-01-31",
    "message": "Approved for 200 units every 12 weeks."
  },
  "updated_at": "2026-08-03T16:22:40Z",
  "trace_id": "tr_01K2Z56SRXP3H8F7M4W9C1J0VA"
}

Lifecycle and decision

status describes operational progress. Payer outcome lives in decision.outcome; clients should not infer a decision from workflow status. decision applies only to completed PAs and is always present when status is completed.

Decision outcomes are approved, denied, and partially_approved. A decision always includes outcome, payer_reference, valid_from, valid_to, and message. The outcome is always non-null; the other fields may be null. New workflow status values may be added within v1, so clients must handle unknown status values without failing.

Webhooks

Kairos sends pa.request.updated when lifecycle, tasks, payer reference, or decision changes. Deliveries are at least once: acknowledge with any 2xx response and deduplicate using event_id.

{
  "schema_version": "1.0",
  "event_id": "evt_01K2Z56T91Y3B8K4D7MP0X6QFC",
  "event_type": "pa.request.updated",
  "created_at": "2026-08-03T16:22:41Z",
  "data": {
    "pa_request": {
      "id": "pa_01K2Q03TSPV5ND4X7M9J8C2R6A",
      "external_id": "ehr_pa_case_4821",
      "status": "completed",
      "decision": {
        "outcome": "approved",
        "payer_reference": "AUTH-66018",
        "valid_from": "2026-08-01",
        "valid_to": "2027-01-31",
        "message": "Approved for 200 units every 12 weeks."
      }
    }
  }
}

Each request includes X-Kairos-Signature: sha256=<hex-hmac>. The signature is the HMAC-SHA256 of the exact raw request body using your webhook secret. Verify it before processing the event. Webhook schema changes follow schema_version, independently of the API URL version.

Multiple services

The v1 request accepts one service containing multiple procedures and diagnoses. Each coded item identifies its code_system. A future additive extension may accept a services array while continuing to support service as the one-service shorthand. Requests must not send both fields.