> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Certificate
> Retrieve a single certificate by id, including a short-lived `download_url`. Live-only.
## Get Certificate (2026-03-01)
Retrieve a single exemption certificate by id, including a short-lived
`download_url` for the original document.
Remember to include the `X-API-Version: 2026-03-01` header. Certificate
endpoints are live-only — using a `sk_test_*` key returns
`TESTMODE_NOT_SUPPORTED`. Certificates outside your account return
`CERTIFICATE_NOT_FOUND` (404).
## The `download_url` field
`download_url` is a pre-signed URL pointing to the original certificate
document. It expires **one hour** after the response is issued — re-fetch
the certificate to mint a fresh URL.
`download_url` is `null` (not omitted) when no document is attached to the
certificate yet — typical for `processing` certificates that haven't finished
ingestion. The certificate itself still exists; the response is `200`, not
`404`. Poll the certificate until a `download_url` appears, or wait for the
`certificate.processing_completed` webhook (coming in a future release).
Treat `download_url` as confidential. Anyone with the URL can download the
certificate document until the URL expires. Do not log, cache past the TTL,
or expose the URL on a public page.
## OpenAPI
````yaml GET /tax/certificates/{certificate_id}
openapi: 3.0.1
info:
title: Numeral API
description: >-
API for sales tax calculations - Version 2026-03-01. This version adds
IP-based tax resolution for calculations and platform calculations, in
addition to Merchant management and Platform Calculations.
license:
name: MIT
version: '2026-03-01'
servers:
- url: https://api.numeralhq.com/
security:
- bearerAuth: []
paths:
/tax/certificates/{certificate_id}:
get:
summary: Get Certificate
description: >-
Retrieve a single certificate by id, including a short-lived
`download_url`. Live-only.
operationId: getCertificate_v20260301
parameters:
- name: X-API-Version
in: header
required: true
schema:
type: string
enum:
- '2026-03-01'
- name: certificate_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Certificate detail (includes pre-signed `download_url`)
content:
application/json:
schema:
$ref: '#/components/schemas/CertificateDetailResponse'
'400':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
CertificateDetailResponse:
allOf:
- $ref: '#/components/schemas/CertificateResponse'
- type: object
properties:
download_url:
type: string
format: uri
nullable: true
description: >-
Pre-signed URL to download the original certificate document.
Expires one hour after issuance — refetch the certificate to
mint a new URL. `null` (response still `200`) when no document
is attached yet. Treat as confidential.
required:
- download_url
Error:
type: object
description: Standard error response format for API version 2026-01-01
properties:
code:
type: integer
description: HTTP status code
example: 400
type:
type: string
description: Machine-readable error type
example: MISSING_FIELD
message:
type: string
description: Human-readable error message
example: Required field 'address_country' is missing
required:
- code
- type
- message
CertificateResponse:
type: object
description: A single exemption certificate.
properties:
id:
type: string
example: cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e
object:
type: string
description: 'The type of object: `tax.exemption_certificate`'
example: tax.exemption_certificate
status:
$ref: '#/components/schemas/CertificateStatus'
certificate_type:
allOf:
- $ref: '#/components/schemas/CertificateType'
nullable: true
customer:
allOf:
- $ref: '#/components/schemas/CustomerLink'
nullable: true
jurisdictions:
type: array
items:
$ref: '#/components/schemas/CertificateJurisdictionEntry'
effective_date:
type: string
format: date
nullable: true
expiration_date:
type: string
format: date
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
livemode:
type: boolean
enum:
- true
required:
- id
- object
- status
- certificate_type
- customer
- jurisdictions
- effective_date
- expiration_date
- created_at
- updated_at
- livemode
CertificateStatus:
type: string
enum:
- processing
- needs_info
- active
- expiring
- expired
- invalid
description: >-
Public lifecycle state of an exemption certificate. `expiring` and
`expired` are distinct from `invalid` so a renewable lapse is
distinguishable from a revoked or rejected certificate.
CertificateType:
type: object
description: The type of an exemption certificate.
properties:
id:
type: string
description: Stable numeric identifier of the certificate type.
example: '12'
name:
type: string
example: California Resale Certificate (CDTFA-230)
certificate_identifier:
type: string
description: >-
Stable, human-readable identifier — use this in filters and
references.
example: US-CA-CDTFA-230
required:
- id
- name
- certificate_identifier
CustomerLink:
type: object
description: >-
The customer this object is linked to. `id` is the Numeral `cust_*` id;
`reference_customer_id` is the value you supplied when the customer was
created (may be null).
properties:
id:
type: string
example: cust_6126acaf-7379-411a-8ada-00005bac0715
reference_customer_id:
type: string
nullable: true
example: '20506'
required:
- id
- reference_customer_id
CertificateJurisdictionEntry:
type: object
description: Per-jurisdiction validity for a certificate.
properties:
jurisdiction_id:
type: string
example: US-CA
status:
$ref: '#/components/schemas/CertificateStatus'
effective_date:
type: string
format: date
nullable: true
expiration_date:
type: string
format: date
nullable: true
required:
- jurisdiction_id
- status
- effective_date
- expiration_date
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````