Exemption (Resale) Certificates

Numeral’s exemption certificate management (ECM) surface covers two related objects:

certificate_request — an outstanding ask for an exemption certificate from one of your customers. Trigger one, read its state, cancel it.
exemption_certificate — the submitted certificate itself, with per-jurisdiction validity, expiration, and a short-lived download URL.

Both objects carry two related links to the owning entity:

customer — the specific Customer record linked to the object. null when no live Customer has been associated yet.
linked_buyer — the master buyer entity. Populated whenever the object has a master-buyer reference, even when no Customer record is linked yet. Prefer this field for rendering “who owns this certificate.”

Both surfaces are live-only. Using a sk_test_* key returns TESTMODE_NOT_SUPPORTED.

Certificate Requests

The certificate_request object represents an outstanding ask for an exemption certificate from one of your customers. A request is opened when you (or an integration acting on your behalf) trigger one for a customer; it closes when the customer submits a valid certificate, the request is canceled, or it expires.

Lifecycle

                ┌─────────────────┐
                │     pending     │  ← initial state
                │   (awaiting     │
                │    customer)    │
                └────────┬────────┘
                         │
       ┌─────────────────┼──────────────────┐
       │                 │                  │
   customer            cancel           request
   submits cert       via DELETE     expires or is
       │                 │            rejected
       │                 │                  │
       ▼                 ▼                  ▼
  ┌──────────┐      ┌──────────┐      ┌──────────┐
  │fulfilled │      │ canceled │      │ invalid  │
  │(terminal)│      │(terminal)│      │(terminal)│
  └──────────┘      └──────────┘      └──────────┘

Status	Meaning
`pending`	The request is open and the customer has not yet responded.
`fulfilled`	The customer submitted a certificate. `certificate_id` is populated.
`canceled`	The request was canceled before fulfillment.
`invalid`	The request expired or could not be fulfilled.

pending and fulfilled are the only non-terminal-on-creation outcomes clients typically observe.

When to read certificate requests

Render a customer-facing dashboard of outstanding requests.
Reconcile your CRM / sales system with which buyers still owe a cert.
Stop a campaign when your sales team no longer needs the exemption (call DELETE /tax/certificate-requests/{id}).

Triggering a certificate request

POST /tax/customers/{customer_id}/certificate-requests opens a new request for an existing customer. Full reference documentation for the trigger endpoint ships in an upcoming release.

Reading a fulfilled request’s certificate

Once status flips to fulfilled, the certificate_id field is populated with the cert_* id of the submitted certificate. Fetch it via GET /tax/certificates/{certificate_id} to read its status, jurisdictions, and download URL.

Example

curl https://api.numeralhq.com/tax/certificate-requests?status=pending&limit=5 \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-API-Version: 2026-03-01"

{
  "object": "list",
  "certificate_requests": [
    {
      "id": "cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d",
      "object": "tax.certificate_request",
      "status": "pending",
      "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": null,
      "certificate_type_id": "US-CA-CDTFA-230",
      "jurisdictions": ["US-CA"],
      "created_at": "2026-06-10T18:24:09.123Z",
      "updated_at": "2026-06-10T18:24:09.123Z",
      "expires_at": "2026-07-10T18:24:09.123Z",
      "livemode": true
    }
  ],
  "has_more": false
}

Exemption Certificates

The exemption_certificate object represents a tax exemption certificate submitted by one of your customers. Use the certificate endpoints to render exemption state in your own UI, sync validity / expiration into your system of record, and offer a download link to the original document.

Public status vocabulary

The status field uses a deliberately narrow public vocabulary — Numeral’s review pipeline runs many internal states that are not surfaced.

Status	Meaning
`processing`	Numeral’s review pipeline is still working on the certificate.
`needs_info`	Additional information is required before approval.
`active`	The certificate is valid and in effect.
`expiring`	The certificate will expire soon.
`expired`	The certificate has lapsed. May be renewable depending on jurisdiction.
`invalid`	The certificate was rejected, revoked, or could not be validated.

expiring and expired are kept distinct from invalid so you can differentiate a lapsed but renewable certificate from a revoked or rejected one. A top-level status reflects the certificate as a whole. Each entry in jurisdictions[] carries its own status — a certificate may be active in one jurisdiction and expired in another.

Per-jurisdiction validity

Multi-state certificates expose one entry per covered jurisdiction:

{
  "jurisdictions": [
    {
      "jurisdiction_id": "US-CA",
      "status": "active",
      "effective_date": "2026-01-01",
      "expiration_date": "2027-01-01"
    },
    {
      "jurisdiction_id": "US-TX",
      "status": "expiring",
      "effective_date": "2026-01-01",
      "expiration_date": "2026-07-15"
    }
  ]
}

Treat the per-jurisdiction status as authoritative when calculating whether a buyer is exempt in a specific state — the top-level status is a summary view.

Downloading the document

GET /tax/certificates/{certificate_id} returns a pre-signed download_url that expires one hour after issuance. Re-fetch the certificate to mint a fresh URL. download_url is null until the certificate is fully ingested (a processing certificate may have no document attached yet).

Treat download_url as confidential. Anyone with the URL can read the certificate until it expires.

Example

curl https://api.numeralhq.com/tax/certificates/cert_a8f3d2c1-... \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-API-Version: 2026-03-01"

{
  "id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e",
  "object": "tax.exemption_certificate",
  "status": "active",
  "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",
    "name": "Acme Co"
  },
  "linked_buyer": {
    "id": "12345",
    "legal_name": "Acme Co"
  },
  "jurisdictions": [
    {
      "jurisdiction_id": "US-CA",
      "status": "active",
      "effective_date": "2026-01-01",
      "expiration_date": "2027-01-01"
    }
  ],
  "effective_date": "2026-01-01",
  "expiration_date": "2027-01-01",
  "created_at": "2026-01-02T10:15:23.456Z",
  "updated_at": "2026-01-05T11:00:00.000Z",
  "livemode": true,
  "download_url": "https://signed.example.com/...?X-Amz-Expires=3600&..."
}

Get Started

AI help

Integration FAQs

Essentials

Objects

API Reference

Exemption (Resale) Certificates

Certificate Requests

Lifecycle

When to read certificate requests

Triggering a certificate request

Reading a fulfilled request’s certificate

Example

Exemption Certificates

Public status vocabulary

Per-jurisdiction validity

Downloading the document

Example

​Certificate Requests

​Lifecycle

​When to read certificate requests

​Triggering a certificate request

​Reading a fulfilled request’s certificate

​Example

​Exemption Certificates

​Public status vocabulary

​Per-jurisdiction validity

​Downloading the document

​Example

Certificate Requests

Lifecycle

When to read certificate requests

Triggering a certificate request

Reading a fulfilled request’s certificate

Example

Exemption Certificates

Public status vocabulary

Per-jurisdiction validity

Downloading the document

Example