Build

Manual handoffs

Use manual handoffs when Collate explicitly asks your user to operate an active payer-channel session. Handoffs are not a general way to interrupt processing.

Create a handoff only when the authorization has status = requires_action, nextAction.type = complete_payer_interaction, and nextAction.resolution.kind = manual_handoff.

Handoff flow

1

Read the latest authorization

Confirm the current action is still complete_payer_interaction and use the latest authorization version in If-Match.

2

Accept the offered handoff

1POST /v1/prior-authorizations/auth_123/manual-handoffs
2Authorization: Bearer <API_KEY>
3If-Match: "17"
4Content-Type: application/json
5
6{}

If nextAction.covers.reviewSnapshotId is present, your user must review the current submission.reviewSnapshot and send the accepted ID.

1{
2  "acceptedReviewSnapshotId": "rev_123"
3}

If an active handoff already exists, the create call returns the existing active handoff.

3

Create an interactive grant

1POST /v1/prior-authorizations/auth_123/manual-handoffs/mhand_123/access-grants
2Authorization: Bearer <API_KEY>
1{
2  "id": "rag_456",
3  "url": "https://api.trycollate.ai/runtime/access/rag_456",
4  "expiresAt": "2026-05-22T18:30:00Z"
5}

Each call creates a fresh short-lived grant. Store grant URLs only in memory and discard them when the handoff closes.

4

Close the handoff

Close the handoff as soon as the human is done. Choose the close endpoint that matches what happened.

Use POST /complete when the human finished the payer interaction or observed an outcome.

1{
2  "reportedOutcome": "submitted",
3  "observedReferenceNumber": "ABC123",
4  "operatorNotes": "Submitted in the payer portal."
5}

Supported reportedOutcome values are submitted, decision_observed, not_required_observed, and follow_up_required_observed.

Use POST /unable-to-complete when the human could not finish.

1{
2  "reason": "credential_or_mfa_issue",
3  "operatorNotes": "MFA was required for the payer account."
4}

Supported reasons include channel_blocked, missing_information, credential_or_mfa_issue, channel_outage, operator_abandoned_case, wrong_route, and other.

Use POST /revoke when the user should no longer control the session.

1{
2  "reason": "user_closed_task",
3  "notes": "Reviewer canceled the handoff."
4}
5

Poll while Collate reconciles

The close response includes an authorization reference and may include a reconciliation pointer.

1{
2  "manualHandoffId": "mhand_123",
3  "state": "closing",
4  "result": null,
5  "authorization": {
6    "id": "auth_123",
7    "version": 18,
8    "status": "processing"
9  },
10  "reconciliation": {
11    "id": "recon_123",
12    "state": "pending"
13  }
14}

A handoff report is not payer truth by itself. Collate reconciles evidence and projects receipt, decision, and outcome on the authorization.

Safety rules

  • Do not create a handoff during processing.
  • Do not use live-session grants for interactive control.
  • Do not bypass submission.reviewSnapshot when the action covers a review snapshot ID.
  • Do not edit answers or attachments while an active handoff owns payer interaction.
  • Do not build a handoff-back control for the same payer interaction.