Developer API

Build on top of DeclareHQ

Integrate UK customs workflows directly into your ERP, WMS, or accounting system. All AI features available via REST.

Quickstart

# Classify a product description into a UK commodity code
curl -X POST https://declarehq.com/api/ai/commodity-classify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "men plain cotton t-shirts, basic crew neck", "countryOfOrigin": "VN"}'

# Response
# {
#   "suggestions": [
#     { "code": "6109100010", "description": "T-shirts of cotton",
#       "confidence": 0.95, "dutyExpression": "12.00%", "validated": true }
#   ]
# }

Authentication

Bearer-token auth using API keys generated in Settings → API.

Each key is org-scoped — all requests are restricted to the originating org's data.

Rate limits

Standard endpoints: 1,000 req/min per org

AI endpoints: 100 req/min per org

Public endpoints: 10 req/hour per IP

Headers: X-RateLimit-*

Webhooks

Subscribe to events: declaration submitted, HMRC accepted, cleared, tax assessed, rejection received.

Signed with HMAC-SHA256 (header: X-DeclareHQ-Signature).

Endpoint reference

Base URL: https://declarehq.com

Declarations

GET/api/declarationsBearer

List declarations for your organisation

→ { declarations: [...] }

POST/api/declarationsBearer

Create a new declaration

Body: { shipmentId, declarationType, items, documents, ... }

→ { id, lrn, status, ... }

POST/api/cds/submitBearer

Submit a declaration to HMRC CDS

Body: { declarationId }

→ { conversationId, status }

AI

POST/api/ai/commodity-classifyBearer

AI commodity-code classifier — plain English → 10-digit code

Body: { description, countryOfOrigin? }

→ { suggestions: [{ code, confidence, ... }] }

POST/api/ai/extract-documentBearer

Extract structured data from an invoice or BoL PDF

Body: multipart/form-data { file, documentType }

→ { document, confidence, notes }

POST/api/ai/analyse-declarationBearer

AI anomaly detection on a draft declaration

Body: { declarationId }

→ { findings, hasBlockers, ... }

POST/api/ai/explain-rejectionBearer

Plain-English explanation of HMRC DMSREJ errors

Body: { declarationId } or { errors: [...] }

→ { errors: [{ plainEnglish, suggestedFix, ... }] }

Shipments

GET/api/shipmentsBearer

List shipments

→ { shipments: [...] }

POST/api/shipmentsBearer

Create a shipment

Body: { clientId, portOfEntry, transportMode, ... }

→ { id, reference, ... }

Clients

GET/api/clientsBearer

List clients

→ { clients: [...] }

GVMS

GET/api/gvms/movementsBearer

List GVMS goods-movement records (requires GVMS Hub)

→ { movements: [...] }

POST/api/gvms/movementsBearer

Create a GMR draft

Body: { routeFrom, routeTo, vehicleReg, crossingDate }

→ { id, gmrId, status }

EMCS

GET/api/emcs/movementsBearer

List excise movements (requires EMCS Hub)

→ { movements: [...] }

POST/api/emcs/movementsBearer

Create a DRAFT e-AD

Body: { category, movementType, dispatcherExciseNumber, ... }

→ { movement }

POST/api/emcs/movements/{id}/reviewBearer

AI risk scoring of an excise movement

→ { review: { riskScore, findings, ... } }

POST/api/emcs/movements/{id}/submitBearer

Submit e-AD (mock ARC assigned)

→ { movement, note }

TSS

GET/api/tss/declarationsBearer

List TSS (NI Protocol) declarations (requires TSS Hub)

→ { declarations: [...] }

POST/api/tss/declarationsBearer

Create a DRAFT TSS declaration

Body: { movementType, traderEori, riskCategorisation, ukimsAuthNumber, ... }

→ { declaration }

POST/api/tss/declarations/{id}/reviewBearer

AI categorisation review (UKIMS, at-risk, UK-origin checks)

→ { review: { riskScore, findings, ... } }

POST/api/tss/declarations/{id}/submitBearer

Submit to TSS (mock MRN assigned)

→ { declaration, note }

CBAM

GET/api/cbam/importsBearer

List CBAM-relevant imports (requires CBAM Hub)

→ { imports: [...] }

POST/api/cbam/importsBearer

Log import — AI estimates embedded emissions if not supplied

Body: { category, commodityCode, countryOfOrigin, netMassKg, ... }

→ { id, embeddedEmissionsKgCo2, emissionsSource }

POST/api/cbam/reportsBearer

Generate (or refresh) a DRAFT quarterly report

Body: { quarter? }

→ { report }

POST/api/cbam/reports/{id}/reviewBearer

AI compliance review of a report

→ { review: { findings, hasBlockers, summary } }

POST/api/cbam/reports/{id}/submitBearer

Lock + submit a CBAM report

→ { report, chargeable, note }

GET/api/cbam/reports/{id}/export.xmlBearer

Download report as EU-CBAM-style XML

→ application/xml

ICS2

GET/api/ics2/filingsBearer

List ENS pre-arrival filings (requires ICS2 Hub)

→ { filings: [...] }

POST/api/ics2/filingsBearer

Create a DRAFT ENS filing

Body: { filingType, carrierName, transportDocNumber, ... }

→ { filing }

POST/api/ics2/filings/{id}/reviewBearer

AI risk scoring of an ENS filing

→ { review: { riskScore, findings, ... } }

POST/api/ics2/filings/{id}/submitBearer

Submit ENS to ICS2 (mock MRN assigned)

→ { filing, note }

Tax

GET/api/tax/periodsBearer

List VAT obligations / periods (requires Tax Hub)

→ { periods: [...] }

POST/api/tax/returnsBearer

Generate or refresh DRAFT — auto-reconciles import VAT from Customs Hub

Body: { periodId, box1..box9 }

→ { return }

POST/api/tax/returns/{id}/reviewBearer

AI compliance review of a VAT return

→ { review: { findings, hasBlockers, summary } }

POST/api/tax/returns/{id}/submitBearer

Lock + submit a VAT return (mock HMRC ID assigned)

→ { return, note }

GET/api/tax/returns/{id}/export.xmlBearer

Download VAT return as XML

→ application/xml

Audit

GET/api/auditBearer

Cross-Hub forensic audit log with filters + cursor pagination

→ { events: [...], hasMore, nextCursor }

Bulk import

POST/api/import/clients/previewBearer

AI-mapped CSV preview for client import

Body: multipart/form-data { file }

→ { headers, rows, mapping }

POST/api/import/clients/commitBearer

Commit a CSV client import

Body: { mapping, rows }

→ { created, skipped, errors }

Export

GET/api/export/declarationsBearer

Download all declarations as CSV

→ text/csv

Webhooks

GET/api/webhooks/endpointsBearer

List your webhook endpoints

→ { endpoints: [...] }

POST/api/webhooks/endpointsBearer

Create endpoint — signing secret returned ONCE, store it on receipt

Body: { url, events?: string[], description? }

→ { endpoint }

PATCH/api/webhooks/endpoints/{id}Bearer

Update url / subscribed events / pause-or-resume

Body: { url?, events?, active? }

→ { endpoint }

DELETE/api/webhooks/endpoints/{id}Bearer

Remove an endpoint + its delivery log

→ { success: true }

GET/api/webhooks/endpoints/{id}/deliveriesBearer

Inspect delivery attempts

→ { deliveries: [...] }

POST/api/webhooks/endpoints/{id}/testBearer

Fire a webhook.ping event to verify your receiver

→ { delivery }

POST/api/webhooks/endpoints/{id}/deliveries/{deliveryId}/resendBearer

Re-fire a past delivery with the same payload (useful for replays)

→ { delivery, originalId }

POST/api/cds/webhookOAuth

Inbound webhook from HMRC CDS (signed)

Body: WCO 3.6 XML

→ 200 OK

OpenAPI 3.1 spec — live

Import directly into Postman, Insomnia, or your favourite OpenAPI generator.

GET /api/openapi.jsonDownload spec

TypeScript SDK — live

Fully typed, retries on transient errors, idempotency keys, works in Node and the browser. MIT licensed.

npm install @declarehq/sdk

# Usage
import { DeclareHQ } from "@declarehq/sdk";
const dq = new DeclareHQ({ apiKey: process.env.DECLAREHQ_API_KEY! });

// Classify a product description into a UK commodity code
const [top] = await dq.ai.classifyCommodity({
  description: "men plain cotton t-shirts",
  countryOfOrigin: "VN",
});
console.log(top.code); // "6109100010"

npm install @declarehq/sdkREADME

Coming soon

Python SDK — pip install declarehq
Zapier + Make connectors — no-code automation
Pre-built integrations for Xero, QuickBooks, NetSuite, SAP

Need API access for your team? Get started with a free trial.

Start free trial Email developers@declarehq.com