---
title: "List Certificates"
method: GET
path: "/tax/certificates"
---

# List Certificates

`GET /tax/certificates`

Retrieve a paginated list of exemption certificates. Filter by customer, jurisdiction, status, certificate type, and time windows. Live-only.

## Query parameters

- `status` 'processing' | 'needs_info' | 'active' | 'expiring' | 'expired' | 'invalid' — Public lifecycle state of an exemption certificate. `expiring` and `expired` are distinct from `invalid` so a renewable lapse is distinguishable from a revoked or rejected certificate.
- `customer_id` string
- `id_type` 'id' | 'reference_customer_id'
- `jurisdiction` string
- `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 list

- CertificateListResponse — A paginated list of exemption certificates.
  - `object` 'list', required
  - `certificates` CertificateResponse[], required
    - `id` string, required
    - `object` string, required — The type of object: `tax.exemption_certificate`
    - `status` 'processing' | 'needs_info' | 'active' | 'expiring' | 'expired' | 'invalid', required — Public lifecycle state of an exemption certificate. `expiring` and `expired` are distinct from `invalid` so a renewable lapse is distinguishable from a revoked or rejected certificate.
    - `certificate_type` CertificateType, required — The type of an exemption certificate.
      - `id` string, required — Stable numeric identifier of the certificate type.
      - `name` string, required
      - `certificate_identifier` string, required — Stable, human-readable identifier — use this in filters and references.
    - `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
    - `jurisdictions` CertificateJurisdictionEntry[], required
      - `jurisdiction_id` string, required
      - `status` 'processing' | 'needs_info' | 'active' | 'expiring' | 'expired' | 'invalid', required — Public lifecycle state of an exemption certificate. `expiring` and `expired` are distinct from `invalid` so a renewable lapse is distinguishable from a revoked or rejected certificate.
      - `effective_date` string, date, nullable, required
      - `expiration_date` string, date, nullable, required
    - `effective_date` string, date, nullable, required
    - `expiration_date` string, date, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `livemode` true, required
  - `has_more` boolean, required — Whether there are more certificates 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)