> ## 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 Certificates > Retrieve a paginated list of exemption certificates 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: | Value | Description | | ------------ | -------------------------------------------------------------------------- | | `processing` | Numeral's review pipeline is still working on the certificate. | | `needs_info` | Additional information is required before the certificate can be approved. | | `active` | The certificate is valid and in effect. | | `expiring` | The certificate will expire soon. | | `expired` | The certificate has lapsed but may still be renewable. | | `invalid` | The 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. ## OpenAPI ````yaml GET /tax/certificates 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/certificates: get: summary: List Certificates description: >- Retrieve a paginated list of exemption certificates. Filter by customer, jurisdiction, status, certificate type, and time windows. Live-only. operationId: listCertificates_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/CertificateStatus' - name: customer_id in: query required: false schema: type: string - 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: jurisdiction in: query required: false schema: type: string description: Jurisdiction identifier, e.g. `US-CA`. - 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 - name: cursor in: query required: false schema: type: string responses: '200': description: Certificate list content: application/json: schema: $ref: '#/components/schemas/CertificateListResponse' '400': description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CertificateStatus: type: string enum: - processing - needs_info - active - expiring - expired - invalid description: >- 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. CertificateListResponse: type: object description: A paginated list of exemption certificates. properties: object: type: string enum: - list certificates: type: array items: $ref: '#/components/schemas/CertificateResponse' has_more: type: boolean next_cursor: type: string required: - object - certificates - 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 CertificateResponse: type: object description: A single exemption certificate. properties: id: type: string example: cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e object: type: string description: 'The type of object: `tax.exemption_certificate`' example: tax.exemption_certificate status: $ref: '#/components/schemas/CertificateStatus' certificate_type: allOf: - $ref: '#/components/schemas/CertificateType' nullable: true customer: allOf: - $ref: '#/components/schemas/CustomerLink' nullable: true jurisdictions: type: array items: $ref: '#/components/schemas/CertificateJurisdictionEntry' effective_date: type: string format: date nullable: true expiration_date: type: string format: date nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time livemode: type: boolean enum: - true required: - id - object - status - certificate_type - customer - jurisdictions - effective_date - expiration_date - created_at - updated_at - livemode CertificateType: type: object description: The type of an exemption certificate. properties: id: type: string description: Stable numeric identifier of the certificate type. example: '12' name: type: string example: California Resale Certificate (CDTFA-230) certificate_identifier: type: string description: >- Stable, human-readable identifier — use this in filters and references. example: US-CA-CDTFA-230 required: - id - name - certificate_identifier 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 CertificateJurisdictionEntry: type: object description: Per-jurisdiction validity for a certificate. properties: jurisdiction_id: type: string example: US-CA status: $ref: '#/components/schemas/CertificateStatus' effective_date: type: string format: date nullable: true expiration_date: type: string format: date nullable: true required: - jurisdiction_id - status - effective_date - expiration_date securitySchemes: bearerAuth: type: http scheme: bearer ````