Download ESX Files

Every accepted upload returns stable links for both generated ESX profiles:

{
  "download_url": "https://api.capout.ai/doc_123.esx",
  "contractor_download_url": "https://api.capout.ai/doc_123.esx?profile=contractor",
  "carrier_download_url": "https://api.capout.ai/doc_123.esx?profile=carrier"
}

The links are safe to store in your application. The private S3 signatures behind them are not.

Choose a profile

Link	ESX profile
`/{document_id}.esx`	Contractor (`8D`), the default
`/{document_id}.esx?profile=contractor`	Contractor (`8D`)
`/{document_id}.esx?profile=carrier`	Carrier (`5L`)

CapOut records the profile_code supplied with your upload. Use the download URL’s profile parameter to select the Contractor or Carrier file.

Download from an authenticated client

Send the same organization-scoped capout-api-key used for upload, status, and document history. Do not put the key in the URL or a query parameter.

# Contractor (default)
curl -L "https://api.capout.ai/doc_123.esx" \
  -H "capout-api-key: $CAPOUT_API_KEY" \
  -o estimate-contractor.esx

# Carrier
curl -L "https://api.capout.ai/doc_123.esx?profile=carrier" \
  -H "capout-api-key: $CAPOUT_API_KEY" \
  -o estimate-carrier.esx

The URL alone does not grant access. A valid key for the document’s organization is required each time CapOut issues a fresh signed redirect.

Re-download without another claim

Downloading an existing export is free. Request the same stable .esx URL with a valid API key for the document’s organization whenever you need the file again. Downloading both Contractor and Carrier files does not consume additional claims. If a signed S3 URL expires, request the stable CapOut URL again to receive a fresh signature. This does not start another conversion or charge another claim. Do not re-upload the PDF just to retrieve an existing export. Use the upload response document_id in the URL, not an internal workflow or ESX task ID. A bare browser link cannot authenticate: the request needs the capout-api-key header.

Test-key downloads

New successful test-key exports generate real Contractor and Carrier ESX files with zero claims consumed and no XactNet delivery. Download them through the same authenticated URLs. Historical mock test exports have no generated artifact and may return ESX_PROFILE_NOT_AVAILABLE; they do not become real files retroactively.

How the stable redirect works

Your integration stores the clean api.capout.ai URL returned by CapOut.
The client requests the link with capout-api-key.
CapOut validates the key and verifies that the durable document belongs to its organization.
CapOut prepares a signed download URL for the selected Contractor or Carrier artifact.
The route returns a non-cached 307 redirect to a signed private S3 URL.
The S3 signature expires after 15 minutes, while the original CapOut link remains stable and can issue another fresh redirect later.

Do not copy the redirected S3 URL into your database or send it as the durable link. Always retain the clean CapOut URL.

Readiness and errors

The clean links are returned immediately after upload so you can store them with the job. They become downloadable only after ESX generation completes.

Status	Meaning
`307`	Export is ready; follow the redirect to download it
`401`	`capout-api-key` is missing or invalid
`404`	Document is unknown or inaccessible, or the requested profile artifact was not found
`409`	Export is still processing or otherwise not ready
`422`	`profile` is not `contractor` or `carrier`
`502`	CapOut could not refresh a valid signed artifact URL
`503`	Durable download lookup is temporarily unavailable

Wait for export.completed, or for GET /status/{document_id} to report a completed export, before presenting the link as ready. A client that opens it early can retry after receiving 409.

Where the links appear

The same stable URLs are available from:

POST /upload
GET /status/{document_id} under export
GET /documents under each document’s export
realtime export.completed events
CapOut MCP processing, status, and waiting tools

Get Started

Workflows

MCP

Choose a profile

Download from an authenticated client

Re-download without another claim

Test-key downloads

How the stable redirect works

Readiness and errors

Where the links appear

​Choose a profile

​Download from an authenticated client

​Re-download without another claim

​Test-key downloads

​How the stable redirect works

​Readiness and errors

​Where the links appear

Choose a profile

Download from an authenticated client

Re-download without another claim

Test-key downloads

How the stable redirect works

Readiness and errors

Where the links appear