v1

latestOpenAPI 3.0.1MIT2026-07-26286592.7 KB

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

get/tax/certificate-requests

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.

Filter by public status.

customer_idstring

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

id_type'id' | 'reference_customer_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.

certificate_type_idstring

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

created_afterstring date-time

created_beforestring date-time

updated_afterstring date-time

updated_beforestring date-time

limitinteger

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

cursorstring

Pagination cursor — pass next_cursor from the previous response.

Headers

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

Response

Certificate request list

object'list' required

has_moreboolean required

Whether there are more certificate requests to fetch.

next_cursorstring

Pass as cursor on the next request. Omitted (not null) on the final page.

Example response

{
  "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",
        "name": "Acme Co"
      },
      "linked_buyer": {
        "id": "12345",
        "legal_name": "Acme Co"
      },
      "certificate_id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e",
      "certificate_type_id": "US-CA-CDTFA-230",
      "jurisdictions": [
        "US-CA"
      ]
    }
  ]
}