Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trycollate.ai/llms.txt

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

A manual handoff lets your user take control of a payer-channel session after Collate has stopped mutating automation for that interaction. Create a handoff only when the authorization returns status = requires_action and nextAction.type = complete_payer_interaction. During processing, live-session access is read-only. Interactive grants are available only from an active manual handoff.

​
Create a handoff

Read the latest authorization first. Use its version in If-Match. 
POST /v1/prior-authorizations/auth_123/manual-handoffs
If-Match: "17"
Idempotency-Key: handoff-auth-123-17
Content-Type: application/json

{}
If the current action covers a review snapshot, render submission.reviewSnapshot and send the accepted snapshot ID: 
{ "acceptedReviewSnapshotId": "rev_456" }
The response is a durable ManualHandoff: 
{
  "id": "mhand_123",
  "version": 1,
  "priorAuthorizationId": "auth_123",
  "state": "active",
  "result": null,
  "accessAvailable": true,
  "finalSubmitCapable": false,
  "createdAt": "2026-05-11T12:00:00Z",
  "activatedAt": "2026-05-11T12:00:00Z",
  "closedAt": null,
  "message": null
}

​
Create an interactive grant

When accessAvailable = true, create a short-lived grant: 
POST /v1/prior-authorizations/auth_123/manual-handoffs/mhand_123/access-grants
Idempotency-Key: handoff-grant-mhand-123
Grant URLs are bearer capabilities. Store them only in memory, refresh them before expiresAt, and discard them when the handoff closes. Opening a grant URL validates the active handoff and redirects to the live payer-channel session; it is not a durable case URL. The handoff itself does not have a separate hidden interaction expiry. It stays active until it is completed, revoked, canceled, the backing channel session is lost, or Collate expires it under an abandonment policy because access grants were not refreshed.

​
Close the handoff

Report what happened in the payer session. Use POST /complete when the human finished the payer interaction: 
{
  "reportedOutcome": "submitted",
  "observedReferenceNumber": "ABC123",
  "operatorNotes": "Submitted in the payer portal."
}
Use POST /unable-to-complete when the human could not finish: 
{
  "reason": "credential_or_mfa_issue",
  "operatorNotes": "MFA was required for the payer account."
}
Use POST /revoke to close an active handoff and invalidate its grants when the user should no longer control the session. After a close, read the authorization again. Collate returns the case to processing while it reconciles payer evidence.

​
Safety rules

  • Do not create a manual handoff during processing.
  • Do not use /live-session/access-grants for interactive control.
  • Do not submit a review-backed handoff until your user has reviewed submission.reviewSnapshot and accepted its current id.
  • Do not treat a handoff result as payer truth. The authorization remains the resource you poll for receipt, decision, and terminal outcome.