---
title: "Generic Document Import"
method: POST
path: "/v1/webhook/document-import"
tags: ["Use case / Document import", "Webhooks / Inbound"]
---

# Generic Document Import

`POST /v1/webhook/document-import`

Webhook for importing documents and attaching them to existing orders in Qargo.

## How it works

1. An external system sends a file to this endpoint with metadata as query parameters.
2. The system matches the document to an order in Qargo using the provided query parameters.
3. The document is created and attached to the matched order.

## Query parameters

The `filename` parameter is always required. Additional query parameters are **configurable
per integration** during setup and are used to pass metadata about the file and to match
the document to an order.

Query parameters can carry two types of information:

### File metadata

Information about the document itself, for example:
- `filename` (required) — Name of the uploaded file including extension
- `document_type` — The type of document, see the **Document types** section below
- `document_name` — Display name for the document in Qargo

### Matching to Qargo orders

Information used to resolve which order the document should be attached to.
The following order fields can be matched against:

- `customer_reference_number` — The customer reference number on the order
- `name` — The order name (e.g. `OR-12345`)
- `id` — The order UUID

The match must resolve to **exactly one order**. If no order or multiple orders match,
the import will be discarded.

The actual set of query parameters and how they map to the above is configured per integration.

## Document types

The `document_type` parameter must be one of the following values:

| Document type |
|---|
| `ADDRESS_LABEL` |
| `ANALYSIS_CERTIFICATE` |
| `ANNEX_VII_WASTE_SHIPMENT` |
| `APPROVAL_LOADING_LIST` |
| `ATR` |
| `AUTHORIZATION_PREFERENTIAL_ORIGIN` |
| `BILL_OF_LADING_INSTRUCTIONS` |
| `CATTLE_TRANSPORT_JOURNAL` |
| `CERTIFICATE_OF_ORIGIN` |
| `CERTIFICATE_OF_SHIPMENT` |
| `CLAIM` |
| `CMR_INSURANCE` |
| `COMMERCIAL_INVOICE` |
| `CONFIRMATION_TARIFF_SHIPPING_LINE` |
| `CONSIGNEE_SIGNATURE` |
| `CONSIGNOR_SIGNATURE` |
| `CONTAINER_CLEANING_CERTIFICATE` |
| `CUSTOMER_PAPERWORK` |
| `CUSTOMS_DECLARATION_INSTRUCTIONS` |
| `CUSTOMS_DOCUMENT` |
| `CUSTOMS_INVOICE` |
| `DANGEROUS_GOODS_DECLARATION` |
| `DEFENSE_MUNITIONS_VEHICLE_STABLING_REQUEST_FORM` |
| `DISPATCH_CONFIRMATION` |
| `DRAFT_BILL_OF_LADING` |
| `DRIVER_SIGNATURE` |
| `DUTCH_CUSTOMS_RELEASE` |
| `EQUIPMENT_INTERCHANGE_RECEIPT` |
| `EUR1` |
| `EUR_MED` |
| `EXPORT_ACCOMPANYING_DOCUMENT` |
| `EXPORT_DECLARATION` |
| `EXPORT_DOCUMENT` |
| `EXTRA_COST_CONFIRMATION` |
| `EXTRA_PERMITTED_WEIGHT` |
| `EX_A_EXPORT_DECLARATION` |
| `FINAL_BILL_OF_LADING` |
| `GOODS_IN` |
| `GOODS_OUT` |
| `GPS_TRACKER_REPORT` |
| `IFP` |
| `IMDG` |
| `IMPORT_DECLARATION` |
| `IMPORT_DOCUMENT` |
| `IM_A` |
| `INSURANCE_DOCUMENT` |
| `LOCATION_INFO` |
| `LUMPER_RECEIPT` |
| `MANIFEST` |
| `MULTIMODAL_DANGEROUS_GOODS_DECL` |
| `ORDER_ACCEPTANCE` |
| `ORDER_CONFIRMATION` |
| `ORIGINAL_CMR` |
| `OTHER_ADMINISTRATION` |
| `PALLET_LABEL` |
| `PALLET_LABEL_EXTERNAL` |
| `PALLET_NOTE` |
| `PHOTO_DAMAGED_GOODS` |
| `PHOTO_OF_GOODS_DELIVERY` |
| `PHOTO_OF_GOODS_PICKUP` |
| `PHOTO_SEAL_NUMBER` |
| `PICKUP_CMR` |
| `PICKUP_NOTE` |
| `PREFILLED_CMR` |
| `PRICE_OFFER_CUSTOMER` |
| `PROOF_OF_DELIVERY` |
| `PROOF_OF_DELIVERY_DRIVER_APP` |
| `PROOF_OF_DELIVERY_SIGNED` |
| `PROOF_OF_PICKUP` |
| `PROOF_OF_PICKUP_SIGNED` |
| `QUOTE` |
| `RECEIPT` |
| `SAFETY_SECURITY_DECLARATION` |
| `SECURITY_PLAN_FORM` |
| `SINGLE_ADMINISTRATIVE_DOCUMENT` |
| `STANDARD_OPERATING_PROCEDURE` |
| `STICKER_LABEL` |
| `T1_DOCUMENT` |
| `T2_DOCUMENT` |
| `TEMPERATURE_REPORT` |
| `TIMESLOT_CONFIRMATION` |
| `TRANSIT_DOCUMENT` |
| `UK_EXPORTER_DRA` |
| `UK_IMPORTER_DRA` |
| `VGM_CONTAINER` |
| `VISITOR_SAFETY_INSTRUCTION` |
| `WAITING_HOURS_INFORMATION` |
| `WASTE` |
| `WAYBILL` |
| `WEIGHING_TICKET` |

## Content encoding

| Content format | Content-Type header | Behavior |
|---|---|---|
| Binary (e.g. PDF, image) | `application/pdf`, `image/png`, etc. | Passed through as-is |
| Text | `text/plain`, `text/xml`, etc. | Encoded as UTF-8 bytes |
| Base64-encoded string | Non-text or no header | Base64 decode attempted; raw string used on failure |

Please provide the `Content-Type` header matching the file format.

## Error handling

| Scenario | Behavior |
|----------|----------|
| No order matches the provided criteria | Import is discarded |
| Multiple orders match the criteria | Import is discarded  |
| Document metadata not provided | Import is discarded |

## Query parameters

- `filename` string, required

## Request body

- union — The document content as binary file data or a JSON message.
  - string, binary
  - object
  - unknown[]
    - unknown
  - string
  - integer
  - number
  - boolean

## Response `200`

Successful Response

- DocumentImportResponse — Response schema for the document import webhook. This schema is used to return errors or success messages.
  - `errors` ErrorStatus[], nullable — List of errors that occurred during the webhook processing. If empty/omitted, the webhook was processed successfully.
    - `error_type` 'USER_INPUT_ERROR' | 'INTERNAL_ERROR' | 'NOT_SUPPORTED', required
    - `error_message` string, nullable — (User visible) error message

## Other responses

- `400` — Bad Request — invalid input or malformed request
- `401` — Unauthorized — missing or invalid authentication credentials
- `403` — Forbidden — insufficient permissions for this operation
- `422` — Validation Error
- `429` — Too Many Requests — rate limit exceeded. See the `Retry-After` header
- `500` — Internal Server Error
- `503` — Service Unavailable — temporarily unable to handle the request

---

[API](https://skmtc.dev/qargo/apis/qargo-tms-api.md) · [All operations](https://skmtc.dev/qargo/apis/qargo-tms-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qargo/qargo-tms-api/revisions/17297902e7ce/schema)