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.Endpoints
List certificate requestsGET/tax/certificate-requestsRetrieve a certificate requestGET/tax/certificate-requests/:idCancel a certificate requestDELETE/tax/certificate-requests/:idList certificatesGET/tax/certificatesRetrieve a certificateGET/tax/certificates/:idSubmit a certificatePOST/tax/certificatesList certificate uploadsGET/tax/certificate-uploadsRetrieve a certificate uploadGET/tax/certificate-uploads/:idThe 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 stayspending 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.
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.object
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 bystatus 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 acertificate_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 itsid. 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, returnsCERTIFICATE_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 returns200 and the same body.- A
fulfilledrequest returns409 REQUEST_ALREADY_FULFILLED. Retrieve the certificate instead. - An
invalidrequest returns409 REQUEST_INVALID.
string
required
The request’s
id, cert_req_….Returns
The Certificate request object withstatus: "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
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.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 acertificates 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 itsid, 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, returnsCERTIFICATE_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 nocertificate_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.
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.customer.id and customer.reference_customer_id point to different customers, the request fails with BUYER_IDENTITY_CONFLICT and nothing is saved.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
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.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 bystatus 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 acertificate_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 itsid, 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 returnCERTIFICATE_UPLOAD_NOT_FOUND.GET /tax/certificate-uploads/:id