> For the complete documentation index, see [llms.txt](https://docs.terminal.africa/tship/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terminal.africa/tship/regulatory-documents/analyze-regulatory-documents.md).

# Analyze Regulatory Documents

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

`/regulatory-documents/analyze`

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | Set value to `Bearer SECRET_KEY` |
| Content-Type<mark style="color:red;">\*</mark>  | 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

```json
{
    "shipment_id": "SH-ABC1234567"
}
```

#### Analyze from invoice

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

{% tabs %}
{% tab title="200: OK Regulatory documents analyzed successfully" %}

```json
{
    "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": "+2348000000000",
                "email": "ada@example.com"
            },
            "delivery_address": {
                "first_name": "John",
                "last_name": "Doe",
                "line1": "123 Main St",
                "city": "New York",
                "state": "NY",
                "country": "US",
                "zip": "10001",
                "phone": "+15550100",
                "email": "john@example.com"
            },
            "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"
    }
}
```

{% endtab %}
{% endtabs %}

#### 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`:

```json
{
    "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}      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.terminal.africa/tship/regulatory-documents/analyze-regulatory-documents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.