Analyze Regulatory Documents

Create a draft document request by analyzing a shipment or commercial invoice.

/regulatory-documents/analyze

POST https://api.terminal.africa/v1/regulatory-documents/analyze

Matches line items to required regulatory documents by HS code and destination country. Returns a draft request with available_documents priced in the user's wallet currency.

Provide either shipment_id or file_url — not both.

Headers

Name	Type	Description
Authorization*	String	Set value to Bearer SECRET_KEY
Content-Type*	String	Set value to application/json

Request Body

Name	Type	Description
shipment_id	String	Terminal shipment id. e.g. SH-ABC123. Use for shipment-sourced requests.
file_url	String	Public URL of a commercial invoice PDF. Use for invoice-sourced requests.
currency	String	Optional 3-letter currency override for document pricing. Defaults to the user's wallet currency.

Analyze from shipment

{
    "shipment_id": "SH-ABC1234567"
}

Analyze from invoice

{
    "file_url": "https://cdn.example.com/invoices/commercial-invoice-001.pdf"
}

200: OK Regulatory documents analyzed successfully

{
    "status": true,
    "message": "Regulatory documents analyzed successfully",
    "data": {
        "request_id": "DRQ-ABC1234567",
        "user_id": "USR-1234567890",
        "source": "invoice",
        "status": "draft",
        "file_url": "https://cdn.example.com/invoices/commercial-invoice-001.pdf",
        "currency": "USD",
        "carrier_slug": "dhl-ng",
        "carrier_logo": "https://cdn.terminal.africa/carriers/dhl.png",
        "tracking_number": "1234567890",
        "context": {
            "pickup_address": {
                "first_name": "Ada",
                "last_name": "Obi",
                "line1": "1 Marina",
                "city": "Lagos",
                "state": "Lagos",
                "country": "NG",
                "zip": "100001",
                "phone": "[phone]",
                "email": "[e-mail]"
            },
            "delivery_address": {
                "first_name": "John",
                "last_name": "Doe",
                "line1": "123 Main St",
                "city": "New York",
                "state": "NY",
                "country": "US",
                "zip": "10001",
                "phone": "[phone]",
                "email": "[e-mail]"
            },
            "items": [
                {
                    "item_id": "DRI-ITEM001",
                    "description": "Roasted coffee",
                    "hs_code": "0901.21",
                    "value": 10,
                    "currency": "USD",
                    "quantity": 1,
                    "weight": 1,
                    "weight_unit": "kg",
                    "manufacturer_country": "NG",
                    "document_types": ["FDA"]
                }
            ]
        },
        "validation": {
            "ok": true,
            "items_missing_hs_codes": []
        },
        "available_documents": [
            {
                "type": "FDA",
                "name": "FDA Prior Notice",
                "logo": "https://cdn.terminal.africa/regulatory/fda.png",
                "description": "Required for food shipments to the US",
                "amount": 1.67,
                "currency": "USD",
                "free": false,
                "automated": true,
                "sample_document": "",
                "hs_codes": ["0901"],
                "required_countries": ["US"]
            }
        ],
        "purchased_documents": [],
        "payment": {},
        "generation": {},
        "extraction": {},
        "created_at": "2026-09-01T10:00:00.000Z",
        "updated_at": "2026-09-01T10:00:00.000Z"
    }
}

Draft with missing HS codes

Analyze does not fail when items are missing HS codes. The request is still returned as draft with validation.ok: false:

{
    "status": true,
    "message": "Regulatory documents analyzed successfully",
    "data": {
        "request_id": "DRQ-ABC1234567",
        "status": "draft",
        "validation": {
            "ok": false,
            "items_missing_hs_codes": [
                { "index": 1, "item_id": "DRI-ITEM002", "description": "Gift box" }
            ]
        },
        "error": "One or more items are missing HS codes"
    }
}

Fix items via Update Document Request Items, then purchase.

Common errors

Status	Message
400	Shipment delivery address country is required
400	Failed to parse commercial invoice
403	You are not authorized to analyze this shipment
404	Shipment not found for id - {shipment_id}