Skip to main content
An exemption certificate shows that a customer doesn’t owe sales tax on their purchases, for example because they buy for resale. Numeral applies active certificates to the customer’s calculations.Three objects cover certificates:
  • A certificate request asks one of your customers for a certificate.
  • A certificate is the certificate itself, with its validity in each jurisdiction and a link to the document.
  • A certificate upload is a document you send through the API. Numeral processes it and creates certificates from it.
Where certificates come from
Every certificate endpoint is live-only. A test API key (sk_test_*) returns TESTMODE_NOT_SUPPORTED.

The Certificate request object

A certificate request asks a customer for an exemption certificate. It’s opened when you, or an integration acting for you, trigger one for a customer. It stays pending until the customer submits a certificate, you cancel it, or it expires.

Attributes

string
The ID of the certificate request, cert_req_….
string, value is "tax.certificate_request"
String representing the object’s type.
enum
pending, fulfilled, canceled, or invalid. See Statuses.
object
The Customer record linked to this request. null when no live customer is linked yet. A buyer may still be set in linked_buyer.
string
The Numeral customer ID, cust_….
string
Your customer ID, as sent when the customer was created. Can be null.
string
The customer’s name. Falls back to the buyer’s legal_name when the customer has no name. null only when neither is set.
object
The buyer that owns this request. Set whenever the request has a buyer, even when no Customer record is linked yet. Use this field to show who owns the request. Can be null.
string
Stable numeric ID of the buyer.
The buyer’s legal name. Can be null.
string
The cert_… ID of the submitted certificate. Set only when status is fulfilled, otherwise null. Retrieve the certificate to read it.
string
Identifier of the requested certificate type, e.g. US-CA-CDTFA-230. Can be null.
array of strings
Jurisdictions the request covers, e.g. US-CA.
string
ISO 8601 timestamp when the request was created. updated_at follows the same pattern.
string
ISO 8601 timestamp when the request expires if it isn’t fulfilled. null if it doesn’t expire.
boolean
Always true.

Request statuses

fulfilled, canceled, and invalid are final.
The Certificate request object
Request lifecycle

List certificate requests

Returns your certificate requests. Fulfilled and canceled requests are included, so filter by status to narrow the list. Try it in the API reference.Use it to show customers’ outstanding requests, or to check which buyers still owe a certificate.

Parameters

enum
pending, fulfilled, canceled, or invalid.
string
Only requests for this customer. Read as the type set by id_type. If the customer can’t be found, the list is empty (no 404).
enum
default:"id"
id for the Numeral cust_… ID, or reference_customer_id for your own ID. Any other value returns INVALID_REQUEST, even without customer_id.
string
Only requests for this certificate type. Takes the identifier (US-CA-CDTFA-230) or the numeric type ID (12).
string
ISO 8601 timestamp. created_before, updated_after, and updated_before work the same way.
integer
default:"10"
Items per page, 1 to 100.
string
The next_cursor from the previous page.

Returns

An object with a certificate_requests array of Certificate request objects and has_more. When there are more pages, next_cursor is the last ID on this page. It’s left out (not null) on the last page.
GET /tax/certificate-requests
Response

Retrieve a certificate request

Returns a certificate request by its id. Try it in the API reference.
string
required
The request’s id, cert_req_….

Returns

A Certificate request object. A request that doesn’t exist, or belongs to another account, returns CERTIFICATE_REQUEST_NOT_FOUND.
GET /tax/certificate-requests/:id

Cancel a certificate request

Cancels a pending request, for example when you no longer need the exemption. Reminder emails stop and the request leaves the customer’s outstanding list. Try it in the API reference.Canceling is final and safe to repeat: canceling a request that’s already canceled returns 200 and the same body.
  • A fulfilled request returns 409 REQUEST_ALREADY_FULFILLED. Retrieve the certificate instead.
  • An invalid request returns 409 REQUEST_INVALID.
string
required
The request’s id, cert_req_….

Returns

The Certificate request object with status: "canceled".
DELETE /tax/certificate-requests/:id
Response

The Certificate object

A certificate is an exemption certificate from one of your customers. Use it to show exemption status in your own app, sync validity and expiration dates into your systems, and link to the original document.

Attributes

string
The ID of the certificate, cert_…. Always the top-level certificate ID, so it’s safe to store.
string, value is "tax.exemption_certificate"
String representing the object’s type.
enum
Status of the certificate as a whole: processing, needs_info, active, expiring, expired, or invalid. See Statuses.
object
The type of certificate. Can be null.
string
Stable numeric ID of the type, e.g. 12.
string
Name of the type, e.g. California Resale Certificate (CDTFA-230).
string
Stable, readable identifier, e.g. US-CA-CDTFA-230. Use this in filters and references.
object
The Customer record linked to this certificate: id, reference_customer_id, and name, as on the certificate request. null when no live customer is linked yet.
object
The buyer that owns this certificate: id and legal_name. Set even when no Customer record is linked yet. Use this field to show who owns the certificate. Can be null.
array of objects
One entry per jurisdiction the certificate covers.
string
The jurisdiction, e.g. US-CA.
enum
Status in this jurisdiction. Same values as the top-level status. A certificate can be active in one state and expired in another. Use this one to decide whether a buyer is exempt in a given state.
string
YYYY-MM-DD date the certificate takes effect here. Can be null.
string
YYYY-MM-DD date the certificate expires here. Can be null.
string
YYYY-MM-DD date the certificate takes effect. expiration_date follows the same pattern. Both can be null.
string
ISO 8601 timestamp when the certificate was created. updated_at follows the same pattern.
boolean
Always true.
string
Link to the original document. Expires one hour after the response. Retrieve the certificate again for a fresh link. null until a document is attached, which is common while the certificate is processing. Only returned when you retrieve a single certificate.
Treat download_url as confidential. Anyone with the link can read the certificate until it expires. Don’t log it, cache it past one hour, or show it on a public page.

Certificate statuses

expiring and expired are separate from invalid, so you can tell a lapsed certificate that can be renewed from one that was rejected or revoked.
The Certificate object
Multi-state jurisdictions

List certificates

Returns your certificates. Archived, deleted, and revised (child) certificates aren’t included. Try it in the API reference.

Parameters

enum
processing, needs_info, active, expiring, expired, or invalid.
string
Only certificates for this customer. Read as the type set by id_type.
enum
default:"id"
id for the Numeral cust_… ID, or reference_customer_id for your own ID. Any other value returns INVALID_REQUEST, even without customer_id.
string
Only certificates that cover this jurisdiction, e.g. US-CA. A multi-state certificate is returned if any of its jurisdictions match.
string
Only certificates of this type. Takes the identifier (US-CA-CDTFA-230) or the numeric type ID (12).
string
ISO 8601 timestamp. created_before, updated_after, and updated_before work the same way.
integer
default:"10"
Items per page, 1 to 100.
string
The next_cursor from the previous page.

Returns

An object with a certificates array of Certificate objects, without download_url, and has_more. When there are more pages, next_cursor is the last ID on this page. It’s left out (not null) on the last page.
GET /tax/certificates
Response

Retrieve a certificate

Returns a certificate by its id, with a download_url for the original document. Try it in the API reference.When download_url is null, the certificate still exists and the response is 200. Retrieve it again later to get the link.
string
required
The certificate’s id, cert_….

Returns

A Certificate object. A certificate that doesn’t exist, or belongs to another account, returns CERTIFICATE_NOT_FOUND.
GET /tax/certificates/:id

Submit a certificate

Sends a certificate document you already have to Numeral. Numeral downloads it from your URL, stores it, and works out the certificate type and jurisdiction from the document. There’s no certificate_type_id input. Try it in the API reference.Processing happens in the background. The response is a certificate upload, not a certificate. Retrieve the upload until its status leaves processing, then read certificate_ids. For the full flow, see Submit Certificates via API.

Parameters

string
required
An https URL Numeral’s servers can download without a session or cookie, usually a presigned URL to your own storage.
  • PDF, PNG, or JPEG, detected from the file content, not the extension or Content-Type.
  • 10 MB max.
  • Up to 3 redirects, each also https.
Share links (Google Drive, Dropbox, and similar) return an HTML page instead of the file and fail with UNSUPPORTED_FILE_TYPE. Use a direct download link.
string
Name for the document, 1 to 255 characters. Defaults to the URL’s file name when it has an extension, otherwise to a name based on the file type.
object
The customer the certificate belongs to. Send at least one of id or reference_customer_id. Without customer, Numeral matches the certificate to a buyer during processing, and the response customer is null.
string
An existing Numeral customer ID. An unknown ID returns CUSTOMER_NOT_FOUND.
string
Your customer ID. An unknown value creates the customer, so you can send a certificate before the customer exists in Numeral.
If customer.id and customer.reference_customer_id point to different customers, the request fails with BUYER_IDENTITY_CONFLICT and nothing is saved.
Send reference_customer_id. Once the certificate is active, Numeral applies the exemption to that customer’s calculations automatically.
Sending the same file again with the same file_name doesn’t reprocess it. The response has status: "duplicate" and empty certificate_ids, so use your original upload’s ID to find its certificates. If the original upload failed, error_message says why.

Returns

201 with a Certificate upload object. status is processing or duplicate, and certificate_ids is empty.
POST /tax/certificates
Response

The Certificate upload object

A certificate upload is a document you sent with Submit a certificate. It’s a processing job, not a certificate: one document can produce several certificates, or none.

Attributes

string
The ID of the upload, upl_<number>. Endpoints that take an upload ID also accept the number alone.
string, value is "tax.certificate_upload"
String representing the object’s type.
enum
processing, completed, failed, or duplicate. These are different from certificate statuses. See Statuses.
object
The customer sent with the upload. null when the upload was sent without one.
string
The Numeral customer ID.
string
Your customer ID. Can be null.
array of strings
cert_… IDs of the certificates created from this upload. Empty while processing. Filled in when completed.
string
Why processing failed. Also set on a duplicate upload when the original upload failed. Otherwise null.
string
ISO 8601 timestamp when the upload was created. Can be null.
boolean
Always true.
string
Link to the document you sent. Expires one hour after the response. Can be set while status is still processing. null when no document is attached. Only returned when you retrieve a single upload.
Treat document_url as confidential. Anyone with the link can download the document until it expires.

Upload statuses

processing is the only status that changes. Once an upload is completed, failed, or duplicate, it stays that way.
A completed upload doesn’t mean an active certificate. Each certificate in certificate_ids has its own status, such as processing or needs_info, while Numeral reviews it. Retrieve each certificate before relying on the exemption.
The Certificate upload object
Upload lifecycle

List certificate uploads

Returns your certificate uploads, oldest first (by ID). Uploads in every status are included, so filter by status to narrow the list. Try it in the API reference.

Parameters

enum
processing, completed, failed, or duplicate. Any other value returns INVALID_REQUEST.
string
Only uploads for this customer. Read as the type set by id_type. Only live-mode customers match.
enum
default:"id"
id for the Numeral customer ID, or reference_customer_id for your own ID. Any other value returns INVALID_REQUEST.
integer
default:"10"
Items per page, 1 to 100.
string
The next_cursor from the previous page, as upl_… or the number alone. Returns uploads with a higher ID. A malformed value returns INVALID_REQUEST.

Returns

An object with a certificate_uploads array of Certificate upload objects, without document_url, and has_more. next_cursor is the last ID on this page, and is only present when has_more is true. Retrieve an upload to get its document_url.
GET /tax/certificate-uploads
Response

Retrieve a certificate upload

Returns an upload by its id, with a document_url for the document you sent. Call it after submitting a certificate until status leaves processing, then retrieve each certificate in certificate_ids. Try it in the API reference.
string
required
The upload’s id (upl_4471) or the number alone (4471).

Returns

A Certificate upload object. An unknown ID, a malformed ID, and an upload in another account all return CERTIFICATE_UPLOAD_NOT_FOUND.
GET /tax/certificate-uploads/:id

Errors

Errors return code, type, and message. Handle them by type. Full list in Error Codes.