Skip to main content
GET
Get Certificate Upload
Retrieve a single certificate upload by id, including a short-lived document_url for the originally submitted document. This is the polling endpoint — after POST /tax/certificates, call it until status leaves processing, then read certificate_ids. upload_id accepts the upl_* form (upl_4471) or the bare numeric form (4471).
Remember to include the X-API-Version: 2026-03-01 header — older versions return INVALID_REQUEST (400). Certificate endpoints are live-only — using a sk_test_* key returns TESTMODE_NOT_SUPPORTED (400). Uploads outside your account return CERTIFICATE_UPLOAD_NOT_FOUND (404) — unknown, malformed, and other-account ids are indistinguishable by design.

Polling

processing is the only non-terminal status. completed populates certificate_ids, failed populates error_message, and duplicate is assigned at submit time. Once the status is terminal it will not change, so you can stop polling. Each id in certificate_ids is a cert_* id usable with GET /tax/certificates/{certificate_id} to read the certificate’s own status, jurisdictions, and download URL.

The document_url field

document_url is a pre-signed URL pointing to the document you submitted. It expires one hour after the response is issued — re-fetch the upload to mint a fresh URL. It may be non-null while status is still processing. document_url is null (not omitted) when no document is attached to the upload. The upload metadata is still returned — the response is 200, not 404.
Treat document_url as confidential. Anyone with the URL can download the document until the URL expires. Do not log, cache past the TTL, or expose the URL on a public page.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Version
enum<string>
required

Must be 2026-03-01 or later. Older versions return INVALID_REQUEST (400).

Available options:
2026-03-01

Path Parameters

upload_id
string
required

The upload id (upl_4471) or its bare numeric form (4471).

Response

Certificate upload detail (includes pre-signed document_url)

A certificate upload — the asynchronous processing job created by POST /tax/certificates.

id
string
required

Upload id, upl_<number>. Endpoints that accept an upload id also accept the bare numeric form.

Example:

"upl_4471"

object
string
required

The type of object: tax.certificate_upload

Example:

"tax.certificate_upload"

status
enum<string>
required

Processing state of a certificate upload. This is a separate vocabulary from certificate status — an upload is a processing job, a certificate is its output. processing is the only non-terminal state; completed (certificates produced), failed (see error_message), and duplicate (same document already submitted) are terminal.

Available options:
processing,
completed,
failed,
duplicate
customer
object | null
required

The customer supplied at submission. null when the upload was submitted without a customer — attribution then happens during processing.

certificate_ids
string[]
required

Certificates produced by this upload, usable with the certificate endpoints. Empty while status is processing; populated at completed. One document can yield multiple certificates.

error_message
string | null
required

Human-readable reason processing failed. Also set on duplicate uploads when the original upload had failed, so you can see why re-submitting the same bytes will not help.

created_at
string<date-time> | null
required
livemode
enum<boolean>
required

Always true — these endpoints are live-only.

Available options:
true
document_url
string<uri> | null
required

Pre-signed URL to the originally submitted document. Valid for one hour — refetch the upload to mint a new URL. May be non-null while status is still processing. null (response still 200) when no document is attached. Not returned by the list endpoint. Treat as confidential.