---
title: "List Certificate Requests"
method: GET
path: "/tax/certificate-requests"
---

# List Certificate Requests

`GET /tax/certificate-requests`

Retrieve a paginated list of certificate requests. Filter by status, customer, certificate type, and time windows. Live-only — `sk_test_*` keys are rejected with `TESTMODE_NOT_SUPPORTED`.

## Query parameters

- `status` 'pending' | 'fulfilled' | 'canceled' | 'invalid' — Public lifecycle state of a certificate request. The internal status enum is narrower in the public vocabulary on purpose — `processing` collapses to `pending`, `failed` collapses to `invalid`.
- `customer_id` string
- `id_type` 'id' | 'reference_customer_id'
- `certificate_type_id` string
- `created_after` string, date-time
- `created_before` string, date-time
- `updated_after` string, date-time
- `updated_before` string, date-time
- `limit` integer
- `cursor` string

## Headers

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

## Response `200`

Certificate request list

- CertificateRequestListResponse — A paginated list of certificate requests.
  - `object` 'list', required
  - `certificate_requests` CertificateRequestResponse[], required
    - `id` string, required — The ID of the certificate request
    - `object` string, required — The type of object: `tax.certificate_request`
    - `status` 'pending' | 'fulfilled' | 'canceled' | 'invalid', required — Public lifecycle state of a certificate request. The internal status enum is narrower in the public vocabulary on purpose — `processing` collapses to `pending`, `failed` collapses to `invalid`.
    - `customer` CustomerLink, required — The customer this object is linked to. `id` is the Numeral `cust_*` id; `reference_customer_id` is the value you supplied when the customer was created (may be null); `name` is the customer's display name (falls back to the linked master buyer's legal name when the customer record has no name of its own).
      - `id` string, required
      - `reference_customer_id` string, nullable, required
      - `name` string, nullable, required — Display name for the linked customer. Populated from `Customer.name`; falls back to the master buyer's `legal_name` if the customer record has no name of its own. `null` only when neither is set.
    - `linked_buyer` LinkedBuyer, required — The master buyer entity that owns this certificate or request. Distinct from `customer` (which is a specific `Customer` record) — `linked_buyer` is populated whenever the object has a master-buyer reference, even when no `Customer` record has been linked yet. Clients rendering "who owns this cert" should prefer this field.
      - `id` string, required — Stable numeric id of the master buyer.
      - `legal_name` string, nullable, required
    - `certificate_id` string, nullable, required — Populated only when `status === "fulfilled"`. The `cert_*` id of the submitted certificate.
    - `certificate_type_id` string, nullable, required — Stable identifier of the requested certificate type, e.g. `US-CA-CDTFA-230`.
    - `jurisdictions` string[], required — Jurisdiction identifiers covered by the request.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `expires_at` string, date-time, nullable, required — When the request will auto-expire if not fulfilled. `null` if the request does not auto-expire.
    - `livemode` true, required — Always `true` — these endpoints are live-only.
  - `has_more` boolean, required — Whether there are more certificate requests to fetch.
  - `next_cursor` string — Pass as `cursor` on the next request. Omitted (not `null`) on the final page.

## Other responses

- `400` — Unexpected error

---

[API](https://skmtc.net/numeral-com/apis/numeral-api.md) · [All operations](https://skmtc.net/numeral-com/apis/numeral-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral-com/numeral-api/versions/f0af51c3f9b9/schema)