List Certificate Uploads

curl --request GET \
  --url https://api.numeralhq.com/tax/certificate-uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Version: <x-api-version>'

import requests

url = "https://api.numeralhq.com/tax/certificate-uploads"

headers = {
    "X-API-Version": "<x-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Version': '<x-api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://api.numeralhq.com/tax/certificate-uploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.numeralhq.com/tax/certificate-uploads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-API-Version: <x-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.numeralhq.com/tax/certificate-uploads"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Version", "<x-api-version>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.numeralhq.com/tax/certificate-uploads")
  .header("X-API-Version", "<x-api-version>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.numeralhq.com/tax/certificate-uploads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Version"] = '<x-api-version>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "certificate_uploads": [
    {
      "id": "upl_4469",
      "object": "tax.certificate_upload",
      "status": "failed",
      "customer": null,
      "certificate_ids": [],
      "error_message": "Document could not be classified as an exemption certificate.",
      "created_at": "2026-09-15T16:41:37.000Z",
      "livemode": true
    },
    {
      "id": "upl_4470",
      "object": "tax.certificate_upload",
      "status": "completed",
      "customer": {
        "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
        "reference_customer_id": "20506"
      },
      "certificate_ids": [
        "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e"
      ],
      "error_message": null,
      "created_at": "2026-09-15T16:58:02.000Z",
      "livemode": true
    },
    {
      "id": "upl_4471",
      "object": "tax.certificate_upload",
      "status": "processing",
      "customer": {
        "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
        "reference_customer_id": "20506"
      },
      "certificate_ids": [],
      "error_message": null,
      "created_at": "2026-09-15T17:04:11.000Z",
      "livemode": true
    }
  ],
  "has_more": true,
  "next_cursor": "upl_4471"
}

{
  "code": 400,
  "type": "MISSING_FIELD",
  "message": "Required field 'address_country' is missing"
}

GET

tax

certificate-uploads

List Certificate Uploads

curl --request GET \
  --url https://api.numeralhq.com/tax/certificate-uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Version: <x-api-version>'

import requests

url = "https://api.numeralhq.com/tax/certificate-uploads"

headers = {
    "X-API-Version": "<x-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Version': '<x-api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://api.numeralhq.com/tax/certificate-uploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.numeralhq.com/tax/certificate-uploads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-API-Version: <x-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.numeralhq.com/tax/certificate-uploads"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Version", "<x-api-version>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.numeralhq.com/tax/certificate-uploads")
  .header("X-API-Version", "<x-api-version>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.numeralhq.com/tax/certificate-uploads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Version"] = '<x-api-version>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "certificate_uploads": [
    {
      "id": "upl_4469",
      "object": "tax.certificate_upload",
      "status": "failed",
      "customer": null,
      "certificate_ids": [],
      "error_message": "Document could not be classified as an exemption certificate.",
      "created_at": "2026-09-15T16:41:37.000Z",
      "livemode": true
    },
    {
      "id": "upl_4470",
      "object": "tax.certificate_upload",
      "status": "completed",
      "customer": {
        "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
        "reference_customer_id": "20506"
      },
      "certificate_ids": [
        "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e"
      ],
      "error_message": null,
      "created_at": "2026-09-15T16:58:02.000Z",
      "livemode": true
    },
    {
      "id": "upl_4471",
      "object": "tax.certificate_upload",
      "status": "processing",
      "customer": {
        "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
        "reference_customer_id": "20506"
      },
      "certificate_ids": [],
      "error_message": null,
      "created_at": "2026-09-15T17:04:11.000Z",
      "livemode": true
    }
  ],
  "has_more": true,
  "next_cursor": "upl_4471"
}

{
  "code": 400,
  "type": "MISSING_FIELD",
  "message": "Required field 'address_country' is missing"
}

Retrieve a paginated list of certificate uploads for your account, ordered by id ascending. Filter by status and customer. Uploads in every status are included — filter by status to narrow.

Remember to include the X-API-Version: 2026-03-01 header — older versions return INVALID_REQUEST (400). Certificate endpoints are live-only — using a sk_test_* key returns TESTMODE_NOT_SUPPORTED (400).

Filtering by status

status accepts the certificate-upload vocabulary. This is a separate vocabulary from certificate statuses — an upload is a processing job, a certificate is its output.

Value	Description
`processing`	Numeral is still downloading or classifying the document. `certificate_ids` is empty.
`completed`	Processing finished. `certificate_ids` lists the resulting certificates.
`failed`	Processing failed. `error_message` explains why.
`duplicate`	The same document bytes and filename were already submitted. The document was not reprocessed.

Any other value returns INVALID_REQUEST (400).

Filtering by customer

Pass customer_id together with id_type to narrow by buyer:

id_type=id (default) — match against the Numeral customer id.
id_type=reference_customer_id — match against your reference id.

Only live, live-mode customers match. An unknown id_type returns INVALID_REQUEST (400) with the message “Invalid id_type. Must be one of: id, reference_customer_id”.

Pagination

Responses use cursor pagination. next_cursor is the last id of the current page and is present only when has_more is true — pass it back as cursor to fetch rows with a greater id. A malformed cursor returns INVALID_REQUEST (400) with the message “Invalid cursor.”

No `document_url` on list items

List items deliberately omit document_url — presigned links are expensive to mint. Fetch GET /tax/certificate-uploads/{upload_id} for the document.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Version

enum<string>

required

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

Available options:

2026-03-01

Query Parameters

status

enum<string>

Filter by upload status. Any other value returns INVALID_REQUEST (400). 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.

Available options:

processing,

completed,

failed,

duplicate

customer_id

string

Filter to one customer. Interpreted per id_type. Matches only live, live-mode customers.

id_type

enum<string>

default:id

How to interpret customer_id. Use id (the default) for the Numeral customer id, or reference_customer_id for your own id. Any other value returns INVALID_REQUEST (400).

Available options:

id,

reference_customer_id

cursor

string

Pagination cursor — pass next_cursor from the previous response (an upl_* id; the bare numeric form is also accepted). Returns rows with an id greater than the cursor. Malformed values return INVALID_REQUEST (400).

limit

integer

default:10

Max items per page (1–100). Defaults to 10.

Required range: 1 <= x <= 100

Response

Certificate upload list

A paginated list of certificate uploads.

object

enum<string>

required

Available options:

list

certificate_uploads

object[]

required

Show child attributes

has_more

boolean

required

Whether there are more uploads to fetch.

next_cursor

string

Pass as cursor on the next request. Present only when has_more is true.

Example:

"upl_4471"

Getting Started

API Reference

List Certificate Uploads

Filtering by status

Filtering by customer

No `document_url` on list items

Authorizations

Headers

Query Parameters

Response

Filtering by status

Filtering by customer

Pagination

No document_url on list items

Authorizations

Headers

Query Parameters

Response

No `document_url` on list items