List Certificate Requests

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

import requests

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

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-requests', 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-requests",
  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-requests"

	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-requests")
  .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-requests")

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_requests": [
    {
      "id": "cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d",
      "object": "tax.certificate_request",
      "status": "fulfilled",
      "customer": {
        "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
        "reference_customer_id": "20506"
      },
      "certificate_id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e",
      "certificate_type_id": "US-CA-CDTFA-230",
      "jurisdictions": [
        "US-CA"
      ],
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-02T09:30:00Z",
      "expires_at": null,
      "livemode": true
    },
    {
      "id": "cert_req_7d3c9e18-4a2b-4f6c-9e1d-8b0a5c2f3e4d",
      "object": "tax.certificate_request",
      "status": "pending",
      "customer": {
        "id": "cust_9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
        "reference_customer_id": "20507"
      },
      "certificate_id": null,
      "certificate_type_id": "US-TX-01-339",
      "jurisdictions": [
        "US-TX"
      ],
      "created_at": "2026-03-04T08:15:00Z",
      "updated_at": "2026-03-04T08:15:00Z",
      "expires_at": "2026-04-03T08:15:00Z",
      "livemode": true
    }
  ],
  "has_more": true,
  "next_cursor": "cert_req_7d3c9e18-4a2b-4f6c-9e1d-8b0a5c2f3e4d"
}

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

GET

tax

certificate-requests

List Certificate Requests

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

import requests

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

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-requests', 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-requests",
  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-requests"

	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-requests")
  .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-requests")

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_requests": [
    {
      "id": "cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d",
      "object": "tax.certificate_request",
      "status": "fulfilled",
      "customer": {
        "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
        "reference_customer_id": "20506"
      },
      "certificate_id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e",
      "certificate_type_id": "US-CA-CDTFA-230",
      "jurisdictions": [
        "US-CA"
      ],
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-02T09:30:00Z",
      "expires_at": null,
      "livemode": true
    },
    {
      "id": "cert_req_7d3c9e18-4a2b-4f6c-9e1d-8b0a5c2f3e4d",
      "object": "tax.certificate_request",
      "status": "pending",
      "customer": {
        "id": "cust_9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
        "reference_customer_id": "20507"
      },
      "certificate_id": null,
      "certificate_type_id": "US-TX-01-339",
      "jurisdictions": [
        "US-TX"
      ],
      "created_at": "2026-03-04T08:15:00Z",
      "updated_at": "2026-03-04T08:15:00Z",
      "expires_at": "2026-04-03T08:15:00Z",
      "livemode": true
    }
  ],
  "has_more": true,
  "next_cursor": "cert_req_7d3c9e18-4a2b-4f6c-9e1d-8b0a5c2f3e4d"
}

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

Retrieve a paginated list of certificate requests for your account. Filter by status, customer, certificate type, and creation / update windows. Canceled and fulfilled requests are included — filter by status to narrow.

Remember to include the X-API-Version: 2026-03-01 header in your request to use this API version. Certificate-request endpoints are live-only — using a sk_test_* key returns TESTMODE_NOT_SUPPORTED.

Filtering by status

status accepts the public certificate-request vocabulary:

Value	Description
`pending`	Awaiting a response from the customer.
`fulfilled`	The customer submitted a certificate and it was accepted.
`canceled`	The request was canceled before fulfillment.
`invalid`	The request expired or could not be fulfilled.

Filtering by customer

Pass customer_id together with id_type to narrow by buyer:

id_type=id (default) — match against the Numeral-issued cust_* id.
id_type=reference_customer_id — match against your reference id.

If the customer cannot be resolved, an empty list is returned (the endpoint does not 404 on filter misses).

Pagination

Responses use cursor pagination. The next_cursor field is the last id of the current page — pass it back as cursor to fetch the next page. next_cursor is omitted (not null) on the final page.

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

Available options:

2026-03-01

Query Parameters

status

enum<string>

Filter by public status. Public lifecycle state of a certificate request. The internal status enum is narrower in the public vocabulary on purpose — processing collapses to pending, failed collapses to invalid.

Available options:

pending,

fulfilled,

canceled,

invalid

customer_id

string

Filter by customer. Pair with id_type to choose Numeral id vs. reference id.

id_type

enum<string>

default:id

How to interpret customer_id. Use id (the default) for the Numeral cust_* id, or reference_customer_id for your own id. Validated whenever present — passing an unknown value returns INVALID_REQUEST (400) even if customer_id is not also supplied.

Available options:

id,

reference_customer_id

certificate_type_id

string

Filter by certificate type. Accepts either the stable identifier (e.g. US-CA-CDTFA-230) or the numeric type id (e.g. 12).

created_after

string<date-time>

created_before

string<date-time>

updated_after

string<date-time>

updated_before

string<date-time>

limit

integer

default:10

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

Required range: 1 <= x <= 100

cursor

string

Pagination cursor — pass next_cursor from the previous response.

Response

Certificate request list

A paginated list of certificate requests.

object

enum<string>

required

Available options:

list

certificate_requests

object[]

required

Show child attributes

has_more

boolean

required

Whether there are more certificate requests to fetch.

next_cursor

string

Pass as cursor on the next request. Omitted (not null) on the final page.

Getting Started

API Reference

List Certificate Requests

Filtering by status

Filtering by customer

Authorizations

Headers

Query Parameters

Response