---
title: "List Certificate Uploads"
method: GET
path: "/tax/certificate-uploads"
---

# List Certificate Uploads

`GET /tax/certificate-uploads`

## Request

- Base URL: `https://api.numeralhq.com`
- URL: `https://api.numeralhq.com/tax/certificate-uploads`
- Auth: HTTP bearer

Retrieve a paginated list of certificate uploads, ordered by id ascending. Filter by status and customer. List items omit `document_url` — fetch a single upload for the document link. Live-only.

## Query parameters

- `status` 'processing' | 'completed' | 'failed' | 'duplicate': 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.
- `customer_id` string
- `id_type` 'id' | 'reference_customer_id'
- `cursor` string
- `limit` integer

## Headers

- `X-API-Version` '2026-03-01', required

## Response `200`

Certificate upload list

- CertificateUploadListResponse: A paginated list of certificate uploads.
  - `object` 'list', required
  - `certificate_uploads` CertificateUploadResponse[], required
    - `id` string, required: Upload id, `upl_<number>`. Endpoints that accept an upload id also accept the bare numeric form.
    - `object` string, required: The type of object: `tax.certificate_upload`
    - `status` 'processing' | 'completed' | 'failed' | 'duplicate', 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.
    - `customer` CertificateUploadCustomer, required: The customer the upload was attributed to at submission.
      - `id` string, required
      - `reference_customer_id` string, nullable, required
    - `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, nullable, 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, nullable, required
    - `livemode` true, required: Always `true` — these endpoints are live-only.
  - `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`.

## Other responses

- `400`: `INVALID_REQUEST` (bad `status`, `id_type`, `cursor`, or API version below 2026-03-01) or `TESTMODE_NOT_SUPPORTED`

## Changes

- **2026-11-03** `f4650eaed11f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/numeral-com/apis/numeral-api/changes/tax/certificate-uploads/get.md)

---

[API](https://skmtc.dev/numeral-com/apis/numeral-api.md) - [All operations](https://skmtc.dev/numeral-com/apis/numeral-api/llms.txt) - [OpenAPI document](https://skmtc.dev/numeral-com/apis/numeral-api/revisions/f4650eaed11f?raw)