Skip to main content
GET
/
tax
/
certificates
List Certificates
curl --request GET \
  --url https://api.numeralhq.com/tax/certificates \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Version: <x-api-version>'
{
  "object": "list",
  "certificates": [
    {
      "id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e",
      "object": "tax.exemption_certificate",
      "certificate_type": {
        "id": "12",
        "name": "California Resale Certificate (CDTFA-230)",
        "certificate_identifier": "US-CA-CDTFA-230"
      },
      "customer": {
        "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
        "reference_customer_id": "20506"
      },
      "jurisdictions": [
        {
          "jurisdiction_id": "US-CA",
          "effective_date": "2023-12-25",
          "expiration_date": "2023-12-25"
        }
      ],
      "effective_date": "2023-12-25",
      "expiration_date": "2023-12-25",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "livemode": true
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}
Retrieve a paginated list of exemption certificates for your account. Filter by customer, jurisdiction, status, certificate type, and creation / update windows.
Remember to include the X-API-Version: 2026-03-01 header. Certificate endpoints are live-only — using a sk_test_* key returns TESTMODE_NOT_SUPPORTED.

​
Filtering by status

status accepts the public certificate vocabulary:
ValueDescription
processingNumeral’s review pipeline is still working on the certificate.
needs_infoAdditional information is required before the certificate can be approved.
activeThe certificate is valid and in effect.
expiringThe certificate will expire soon.
expiredThe certificate has lapsed but may still be renewable.
invalidThe certificate was rejected or revoked.
expiring and expired are kept distinct from invalid so you can differentiate a lapsed but renewable certificate from a rejected one.

​
Filtering by customer

Pass customer_id together with id_type to narrow by buyer:
  • id_type=id (default) — match against the Numeral-issued cust_* id.
  • id_type=reference_customer_id — match against your reference id.

​
Filtering by jurisdiction

Pass jurisdiction (a jurisdiction identifier like US-CA) to return only certificates that cover that jurisdiction. Multi-state certificates are returned if any of their covered jurisdictions match.

​
Pagination

Responses use cursor pagination. The next_cursor field is the last id of the current page — pass it back as cursor to fetch the next page. next_cursor is omitted (not null) on the final page.

​
Excluded from results

The list endpoint hides archived, deleted, and revision (child) certificates. The id returned for any certificate is always the canonical, top-level certificate id — safe to store as a stable reference.

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
Available options:
2026-03-01

Query Parameters

​
status
enum<string>

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.

Available options:
processing,
needs_info,
active,
expiring,
expired,
invalid
​
customer_id
string
​
id_type
enum<string>
default:id

How to interpret customer_id. Use id (the default) for the Numeral cust_* id, or reference_customer_id for your own id. Validated whenever present — passing an unknown value returns INVALID_REQUEST (400) even if customer_id is not also supplied.

Available options:
id,
reference_customer_id
​
jurisdiction
string

Jurisdiction identifier, e.g. US-CA.

​
certificate_type_id
string

Filter by certificate type. Accepts either the stable identifier (e.g. US-CA-CDTFA-230) or the numeric type id (e.g. 12).

​
created_after
string<date-time>
​
created_before
string<date-time>
​
updated_after
string<date-time>
​
updated_before
string<date-time>
​
limit
integer
default:10
Required range: 1 <= x <= 100
​
cursor
string

Response

Certificate list

A paginated list of exemption certificates.

​
object
enum<string>
required
Available options:
list
​
certificates
object[]
required
​
has_more
boolean
required
​
next_cursor
string