# Use case / Document import This section provides an overview of all available methods to import documents into Qargo. ![Document import paths overview](/docs/static/document_import_overview.svg) ## Upload Document Content - [POST /v1/documents/document/upload_content](https://api-docs.qargo.com/docs/use-case-document-import/upload_document_content_v1_documents_document_upload_content_post.md): Upload document content. ## Generic Document Import - [POST /v1/webhook/document-import](https://api-docs.qargo.com/docs/use-case-document-import/document-import-webhook.md): 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 | | 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 | ## External Document Upload From A Fleet Application - [POST /v1/webhook/fleet-document-upload](https://api-docs.qargo.com/docs/use-case-document-import/fleet-document-upload-webhook.md): Upload a document to a specific stop or stop group on a fleet-dispatched trip. This webhook uses Basic Auth (webhook credentials), not the OAuth credentials used for the API. Contact integrations@qargo.com to request credentials. --- ## Query parameters | Parameter | Required | Description | |-----------|----------|-------------| | question_path_key | Yes | Maps the file to a document type in Qargo (e.g. CMR, POD, WEIGHT_NOTE) | | stop_id | No* | The Qargo UUID of the stop to attach the document to | | stop_group_id | No* | The Qargo UUID of the stop group to attach the document to | *Provide either stop_id or stop_group_id to identify where to attach the document. ## Headers | Header | Required | Description | |--------|----------|-------------| | Content-Type | Yes | MIME type of the file (e.g. application/pdf, image/jpeg) | | Content-Disposition | No | Provides the filename: attachment; filename="POD.pdf" | ## Filename handling The uploaded file's name in Qargo is determined by: 1. If Content-Disposition includes a filename — that value is used, combined with the question path key default. For example: filename="pod1234.pdf" with question path key default POD.pdf → stored as pod1234_POD.pdf. 2. If no Content-Disposition is provided — the default filename from the question path key configuration is used. ## Example curl -X POST \ "https://api.qargo.com/v1/webhook/fleet-document-upload\ ?question_path_key=POD&stop_id=" \ -u ":" \ -H "Content-Type: application/pdf" \ -H "Content-Disposition: attachment; filename=POD.pdf" \ --data-binary @/path/to/document.pdf ## External Document Update With Payload - [POST /v1/webhook/subco-document-upload](https://api-docs.qargo.com/docs/use-case-document-import/subcontractor-document-upload-webhook.md): Upload a document to a specific stop on a subcontracted trip. This webhook uses Basic Auth (webhook credentials), not the OAuth credentials used for the API. Contact integrations@qargo.com to request credentials. --- ## Query parameters | Parameter | Required | Description | |-----------|----------|-------------| | question_path_key | Yes | Maps the file to a document type in Qargo (e.g. CMR, POD, WEIGHT_NOTE) | | stop_id | Yes | The Qargo UUID of the stop to attach the document to | ## Headers | Header | Required | Description | |--------|----------|-------------| | Content-Type | Yes | MIME type of the file (e.g. application/pdf, image/jpeg) | | Content-Disposition | No | Provides the filename: attachment; filename="POD.pdf" | ## Filename handling The uploaded file's name in Qargo is determined by: 1. If Content-Disposition includes a filename — that value is used, combined with the question path key default. For example: filename="pod1234.pdf" with question path key default POD.pdf → stored as pod1234_POD.pdf. 2. If no Content-Disposition is provided — the default filename from the question path key configuration is used. ## Example curl -X POST \ "https://api.qargo.com/v1/webhook/subco-document-upload\ ?question_path_key=POD&stop_id=" \ -u ":" \ -H "Content-Type: application/pdf" \ -H "Content-Disposition: attachment; filename=POD.pdf" \ --data-binary @/path/to/document.pdf ## External Document Upload From A Fleet Application - [POST /v1/webhook/fleet-document-upload](https://api-docs.qargo.com/docs/use-case-fleet-dispatch/fleet-document-upload-webhook.md): Upload a document to a specific stop or stop group on a fleet-dispatched trip. This webhook uses Basic Auth (webhook credentials), not the OAuth credentials used for the API. Contact integrations@qargo.com to request credentials. --- ## Query parameters | Parameter | Required | Description | |-----------|----------|-------------| | question_path_key | Yes | Maps the file to a document type in Qargo (e.g. CMR, POD, WEIGHT_NOTE) | | stop_id | No* | The Qargo UUID of the stop to attach the document to | | stop_group_id | No* | The Qargo UUID of the stop group to attach the document to | *Provide either stop_id or stop_group_id to identify where to attach the document. ## Headers | Header | Required | Description | |--------|----------|-------------| | Content-Type | Yes | MIME type of the file (e.g. application/pdf, image/jpeg) | | Content-Disposition | No | Provides the filename: attachment; filename="POD.pdf" | ## Filename handling The uploaded file's name in Qargo is determined by: 1. If Content-Disposition includes a filename — that value is used, combined with the question path key default. For example: filename="pod1234.pdf" with question path key default POD.pdf → stored as pod1234_POD.pdf. 2. If no Content-Disposition is provided — the default filename from the question path key configuration is used. ## Example curl -X POST \ "https://api.qargo.com/v1/webhook/fleet-document-upload\ ?question_path_key=POD&stop_id=" \ -u ":" \ -H "Content-Type: application/pdf" \ -H "Content-Disposition: attachment; filename=POD.pdf" \ --data-binary @/path/to/document.pdf ## External Document Update With Payload - [POST /v1/webhook/subco-document-upload](https://api-docs.qargo.com/docs/use-case-subcontractor-dispatch/subcontractor-document-upload-webhook.md): Upload a document to a specific stop on a subcontracted trip. This webhook uses Basic Auth (webhook credentials), not the OAuth credentials used for the API. Contact integrations@qargo.com to request credentials. --- ## Query parameters | Parameter | Required | Description | |-----------|----------|-------------| | question_path_key | Yes | Maps the file to a document type in Qargo (e.g. CMR, POD, WEIGHT_NOTE) | | stop_id | Yes | The Qargo UUID of the stop to attach the document to | ## Headers | Header | Required | Description | |--------|----------|-------------| | Content-Type | Yes | MIME type of the file (e.g. application/pdf, image/jpeg) | | Content-Disposition | No | Provides the filename: attachment; filename="POD.pdf" | ## Filename handling The uploaded file's name in Qargo is determined by: 1. If Content-Disposition includes a filename — that value is used, combined with the question path key default. For example: filename="pod1234.pdf" with question path key default POD.pdf → stored as pod1234_POD.pdf. 2. If no Content-Disposition is provided — the default filename from the question path key configuration is used. ## Example curl -X POST \ "https://api.qargo.com/v1/webhook/subco-document-upload\ ?question_path_key=POD&stop_id=" \ -u ":" \ -H "Content-Type: application/pdf" \ -H "Content-Disposition: attachment; filename=POD.pdf" \ --data-binary @/path/to/document.pdf ## Upload Document Content - [POST /v1/documents/document/upload_content](https://api-docs.qargo.com/docs/api-document/upload_document_content_v1_documents_document_upload_content_post.md): Upload document content. ## Generic Document Import - [POST /v1/webhook/document-import](https://api-docs.qargo.com/docs/webhooks-inbound/document-import-webhook.md): 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 | | 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 | ## External Document Upload From A Fleet Application - [POST /v1/webhook/fleet-document-upload](https://api-docs.qargo.com/docs/webhooks-inbound/fleet-document-upload-webhook.md): Upload a document to a specific stop or stop group on a fleet-dispatched trip. This webhook uses Basic Auth (webhook credentials), not the OAuth credentials used for the API. Contact integrations@qargo.com to request credentials. --- ## Query parameters | Parameter | Required | Description | |-----------|----------|-------------| | question_path_key | Yes | Maps the file to a document type in Qargo (e.g. CMR, POD, WEIGHT_NOTE) | | stop_id | No* | The Qargo UUID of the stop to attach the document to | | stop_group_id | No* | The Qargo UUID of the stop group to attach the document to | *Provide either stop_id or stop_group_id to identify where to attach the document. ## Headers | Header | Required | Description | |--------|----------|-------------| | Content-Type | Yes | MIME type of the file (e.g. application/pdf, image/jpeg) | | Content-Disposition | No | Provides the filename: attachment; filename="POD.pdf" | ## Filename handling The uploaded file's name in Qargo is determined by: 1. If Content-Disposition includes a filename — that value is used, combined with the question path key default. For example: filename="pod1234.pdf" with question path key default POD.pdf → stored as pod1234_POD.pdf. 2. If no Content-Disposition is provided — the default filename from the question path key configuration is used. ## Example curl -X POST \ "https://api.qargo.com/v1/webhook/fleet-document-upload\ ?question_path_key=POD&stop_id=" \ -u ":" \ -H "Content-Type: application/pdf" \ -H "Content-Disposition: attachment; filename=POD.pdf" \ --data-binary @/path/to/document.pdf ## External Document Update With Payload - [POST /v1/webhook/subco-document-upload](https://api-docs.qargo.com/docs/webhooks-inbound/subcontractor-document-upload-webhook.md): Upload a document to a specific stop on a subcontracted trip. This webhook uses Basic Auth (webhook credentials), not the OAuth credentials used for the API. Contact integrations@qargo.com to request credentials. --- ## Query parameters | Parameter | Required | Description | |-----------|----------|-------------| | question_path_key | Yes | Maps the file to a document type in Qargo (e.g. CMR, POD, WEIGHT_NOTE) | | stop_id | Yes | The Qargo UUID of the stop to attach the document to | ## Headers | Header | Required | Description | |--------|----------|-------------| | Content-Type | Yes | MIME type of the file (e.g. application/pdf, image/jpeg) | | Content-Disposition | No | Provides the filename: attachment; filename="POD.pdf" | ## Filename handling The uploaded file's name in Qargo is determined by: 1. If Content-Disposition includes a filename — that value is used, combined with the question path key default. For example: filename="pod1234.pdf" with question path key default POD.pdf → stored as pod1234_POD.pdf. 2. If no Content-Disposition is provided — the default filename from the question path key configuration is used. ## Example curl -X POST \ "https://api.qargo.com/v1/webhook/subco-document-upload\ ?question_path_key=POD&stop_id=" \ -u ":" \ -H "Content-Type: application/pdf" \ -H "Content-Disposition: attachment; filename=POD.pdf" \ --data-binary @/path/to/document.pdf