Skip to main content
GET
List Certificate Uploads
Retrieve a paginated list of certificate uploads for your account, ordered by id ascending. Filter by status and customer. Uploads in every status are included — filter by status to narrow.
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).

Filtering by status

status accepts the certificate-upload vocabulary. This is a separate vocabulary from certificate statuses — an upload is a processing job, a certificate is its output. Any other value returns INVALID_REQUEST (400).

Filtering by customer

Pass customer_id together with id_type to narrow by buyer:
  • id_type=id (default) — match against the Numeral customer id.
  • id_type=reference_customer_id — match against your reference id.
Only live, live-mode customers match. An unknown id_type returns INVALID_REQUEST (400) with the message “Invalid id_type. Must be one of: id, reference_customer_id”.

Pagination

Responses use cursor pagination. next_cursor is the last id of the current page and is present only when has_more is true — pass it back as cursor to fetch rows with a greater id. A malformed cursor returns INVALID_REQUEST (400) with the message “Invalid cursor.”

No document_url on list items

List items deliberately omit document_url — presigned links are expensive to mint. Fetch GET /tax/certificate-uploads/{upload_id} for the document.

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

Query Parameters

status
enum<string>

Filter by upload status. Any other value returns INVALID_REQUEST (400). 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_id
string

Filter to one customer. Interpreted per id_type. Matches only live, live-mode customers.

id_type
enum<string>
default:id

How to interpret customer_id. Use id (the default) for the Numeral customer id, or reference_customer_id for your own id. Any other value returns INVALID_REQUEST (400).

Available options:
id,
reference_customer_id
cursor
string

Pagination cursor — pass next_cursor from the previous response (an upl_* id; the bare numeric form is also accepted). Returns rows with an id greater than the cursor. Malformed values return INVALID_REQUEST (400).

limit
integer
default:10

Max items per page (1–100). Defaults to 10.

Required range: 1 <= x <= 100

Response

Certificate upload list

A paginated list of certificate uploads.

object
enum<string>
required
Available options:
list
certificate_uploads
object[]
required
has_more
boolean
required

Whether there are more uploads to fetch.

next_cursor
string

Pass as cursor on the next request. Present only when has_more is true.

Example:

"upl_4471"