> ## Documentation Index > Fetch the complete documentation index at: https://docs.numeral.com/llms.txt > Use this file to discover all available pages before exploring further. # List Certificate Requests > Retrieve a paginated list of certificate requests 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: | Value | Description | | ----------- | --------------------------------------------------------- | | `pending` | Awaiting a response from the customer. | | `fulfilled` | The customer submitted a certificate and it was accepted. | | `canceled` | The request was canceled before fulfillment. | | `invalid` | The 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. ## OpenAPI ````yaml GET /tax/certificate-requests openapi: 3.0.1 info: title: Numeral API description: >- API for sales tax calculations - Version 2026-03-01. This version adds IP-based tax resolution for calculations and platform calculations, in addition to Merchant management and Platform Calculations. license: name: MIT version: '2026-03-01' servers: - url: https://api.numeralhq.com/ security: - bearerAuth: [] paths: /tax/certificate-requests: get: summary: List Certificate Requests description: >- 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`. operationId: listCertificateRequests_v20260301 parameters: - name: X-API-Version in: header required: true schema: type: string enum: - '2026-03-01' - name: status in: query required: false schema: $ref: '#/components/schemas/CertificateRequestStatus' description: Filter by public status. - name: customer_id in: query required: false schema: type: string description: >- Filter by customer. Pair with `id_type` to choose Numeral id vs. reference id. - name: id_type in: query required: false schema: type: string enum: - id - reference_customer_id default: id description: >- 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. - name: certificate_type_id in: query required: false schema: type: string description: >- Filter by certificate type. Accepts either the stable identifier (e.g. `US-CA-CDTFA-230`) or the numeric type id (e.g. `12`). - name: created_after in: query required: false schema: type: string format: date-time - name: created_before in: query required: false schema: type: string format: date-time - name: updated_after in: query required: false schema: type: string format: date-time - name: updated_before in: query required: false schema: type: string format: date-time - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 10 description: Max items per page (1–100). Defaults to 10. - name: cursor in: query required: false schema: type: string description: Pagination cursor — pass `next_cursor` from the previous response. responses: '200': description: Certificate request list content: application/json: schema: $ref: '#/components/schemas/CertificateRequestListResponse' '400': description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CertificateRequestStatus: type: string enum: - pending - fulfilled - canceled - invalid description: >- 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`. CertificateRequestListResponse: type: object description: A paginated list of certificate requests. properties: object: type: string enum: - list certificate_requests: type: array items: $ref: '#/components/schemas/CertificateRequestResponse' has_more: type: boolean description: Whether there are more certificate requests to fetch. next_cursor: type: string description: >- Pass as `cursor` on the next request. Omitted (not `null`) on the final page. required: - object - certificate_requests - has_more Error: type: object description: Standard error response format for API version 2026-01-01 properties: code: type: integer description: HTTP status code example: 400 type: type: string description: Machine-readable error type example: MISSING_FIELD message: type: string description: Human-readable error message example: Required field 'address_country' is missing required: - code - type - message CertificateRequestResponse: type: object description: A single certificate request. properties: id: type: string description: The ID of the certificate request example: cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d object: type: string description: 'The type of object: `tax.certificate_request`' example: tax.certificate_request status: $ref: '#/components/schemas/CertificateRequestStatus' customer: allOf: - $ref: '#/components/schemas/CustomerLink' nullable: true description: >- The customer this request is for. `null` if the underlying buyer record has been removed. certificate_id: type: string nullable: true description: >- Populated only when `status === "fulfilled"`. The `cert_*` id of the submitted certificate. example: cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e certificate_type_id: type: string nullable: true description: >- Stable identifier of the requested certificate type, e.g. `US-CA-CDTFA-230`. example: US-CA-CDTFA-230 jurisdictions: type: array items: type: string description: Jurisdiction identifiers covered by the request. example: - US-CA created_at: type: string format: date-time updated_at: type: string format: date-time expires_at: type: string format: date-time nullable: true description: >- When the request will auto-expire if not fulfilled. `null` if the request does not auto-expire. livemode: type: boolean enum: - true description: Always `true` — these endpoints are live-only. required: - id - object - status - customer - certificate_id - certificate_type_id - jurisdictions - created_at - updated_at - expires_at - livemode CustomerLink: type: object description: >- 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). properties: id: type: string example: cust_6126acaf-7379-411a-8ada-00005bac0715 reference_customer_id: type: string nullable: true example: '20506' required: - id - reference_customer_id securitySchemes: bearerAuth: type: http scheme: bearer ````