Skip to main content
The /v1/sandbox/* route exists to test payer outcomes against a real authorization without changing the core integration model. Outside the sandbox route, you continue to work against:
  • the authorization
  • blocking actions
  • artifacts
  • events
The sandbox route gives you a deterministic way to inject payer behavior during development and demos.
Within sandbox, use the same base URL and bearer token as the rest of the sandbox API. There is no separate credential for /v1/sandbox/*.
Sandbox and production use separate credentials. Production does not expose /v1/sandbox/*, even if the credential belongs to the same WorkOS organization.

​
Authentication

Sandbox routes use the same bearer token as the rest of the sandbox API: 
Authorization: Bearer your-token

​
Endpoint

MethodEndpointPurpose
POST/v1/sandbox/prior-auth/authorizations/{authorizationId}/payer-eventsInject an approval, denial, or request for information.

​
Supported event types

​
Approval

Use this to complete an authorization with an approved decision. Required fields:
  • type = approval
  • documentFileId
  • certificationNumber
  • approvedStartDate
  • approvedEndDate
  • approvalExpiresAt

​
Denial

Use this to complete an authorization with a denied decision. Required fields:
  • type = denial
  • documentFileId
  • denialReasonCode
  • denialReasonMessage

​
Request for information

Use this to move a submitted authorization back into action_required. Required fields:
  • type = more_info_request
  • documentFileId
  • message
  • requestedDocuments

​
Files

Sandbox payer events reference a file that was uploaded through the public file API with: 
{
  "purpose": "sandbox_payer_document"
}
That keeps payer letters and requests consistent with the same file model used elsewhere in the API.

​
Typical test sequence

1

Create and submit an authorization

Use the public API to create the authorization, attach any supporting files, preview it, and submit it.
2

Upload a sandbox payer document

Create a file with purpose = sandbox_payer_document, upload the content, and complete the file.
3

Inject the payer event

Call the sandbox payer-event route with the authorization ID and the uploaded documentFileId.
4

Read the authorization normally

After the sandbox event, continue using the normal authorization, action, artifact, and event endpoints.

​
Design boundary

The sandbox route is intentionally simple:
  • it uses authorizationId
  • it is documented
  • it is safe for customer testing
Transport inspection, correlation internals, and debugging surfaces are not part of the customer contract and are not included in these docs.