Skip to main content
GET
/
tax
/
certificate-requests
List Certificate Requests
curl --request GET \
  --url https://api.numeralhq.com/tax/certificate-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Version: <x-api-version>'
{
  "object": "list",
  "certificate_requests": [
    {
      "id": "cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d",
      "object": "tax.certificate_request",
      "customer": {
        "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
        "reference_customer_id": "20506"
      },
      "certificate_id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e",
      "certificate_type_id": "US-CA-CDTFA-230",
      "jurisdictions": [
        "US-CA"
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "livemode": true
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}
Retrieve a paginated list of certificate requests for your account. Filter by status, customer, certificate type, and creation / update windows. Canceled and fulfilled requests are included — filter by status to narrow.
Remember to include the X-API-Version: 2026-03-01 header in your request to use this API version. Certificate-request endpoints are live-only — using a sk_test_* key returns TESTMODE_NOT_SUPPORTED.

​
Filtering by status

status accepts the public certificate-request vocabulary:
ValueDescription
pendingAwaiting a response from the customer.
fulfilledThe customer submitted a certificate and it was accepted.
canceledThe request was canceled before fulfillment.
invalidThe request expired or could not be fulfilled.

​
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.
If the customer cannot be resolved, an empty list is returned (the endpoint does not 404 on filter misses).

​
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.

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>

Filter by public status. 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.

Available options:
pending,
fulfilled,
canceled,
invalid
​
customer_id
string

Filter by customer. Pair with id_type to choose Numeral id vs. reference id.

​
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
​
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

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

Required range: 1 <= x <= 100
​
cursor
string

Pagination cursor — pass next_cursor from the previous response.

Response

Certificate request list

A paginated list of certificate requests.

​
object
enum<string>
required
Available options:
list
​
certificate_requests
object[]
required
​
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.