NUnumeral-com

Submit Certificate

Changed on

Submit a certificate document for asynchronous processing. Numeral downloads the document from the https URL you provide, stores it, and classifies the certificate type and jurisdiction from the document itself. Returns a tax.certificate_upload you can poll. Live-only — sk_test_* keys are rejected with TESTMODE_NOT_SUPPORTED.

post/tax/certificates

Request

  • Base URL
    https://api.numeralhq.com
  • URL
    https://api.numeralhq.com/tax/certificates
  • Auth
    HTTP bearer

Headers

X-API-Version'2026-03-01' required

Must be 2026-03-01 or later. Older versions return INVALID_REQUEST (400).

Request body

document_urlstring uri required

An https URL that Numeral's servers can GET — typically a presigned URL to your own storage. Fetched server-side. The file must be a PDF, PNG, or JPEG (detected from content, not extension or Content-Type), at most 10 MB, reachable within 3 redirects (each hop must also be https).

file_namestring

Display name for the document (1–255 characters). Defaults to the URL's basename when it has an extension, otherwise to a generic name derived from the detected file type.

Example request

{
  "document_url": "https://your-bucket.s3.amazonaws.com/certs/resale.pdf?X-Amz-Signature=...",
  "file_name": "resale.pdf",
  "customer": {
    "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
    "reference_customer_id": "20506"
  }
}

Response

Upload accepted. status is processing or duplicate; certificate_ids is always empty at this point — poll GET /tax/certificate-uploads/{upload_id} for results.

idstring required

Upload id, upl_<number>. Endpoints that accept an upload id also accept the bare numeric form.

objectstring required

The type of object: tax.certificate_upload

status'processing' | 'completed' | 'failed' | 'duplicate' required

Processing state of a certificate upload. This is a separate vocabulary from certificate status — an upload is a processing job, a certificate is its output. processing is the only non-terminal state; completed (certificates produced), failed (see error_message), and duplicate (same document already submitted) are terminal.

certificate_idsstring[] required

Certificates produced by this upload, usable with the certificate endpoints. Empty while status is processing; populated at completed. One document can yield multiple certificates.

error_messagestring nullable required

Human-readable reason processing failed. Also set on duplicate uploads when the original upload had failed, so you can see why re-submitting the same bytes will not help.

created_atstring date-time nullable required
livemodetrue required

Always true — these endpoints are live-only.

Example response

{
  "id": "upl_4471",
  "object": "tax.certificate_upload",
  "customer": {
    "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
    "reference_customer_id": "20506"
  },
  "certificate_ids": [
    "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e"
  ]
}

Changes