DeclareHQ
LoginGet Started
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: [...] }

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

POST/api/cds/webhookOAuth

Inbound webhook from HMRC CDS (signed)

Body: WCO 3.6 XML
→ 200 OK

Coming soon

  • OpenAPI 3.1 spec — auto-generated, downloadable
  • TypeScript SDK — npm install @declarehq/sdk
  • 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 trialEmail developers@declarehq.com