Skip to main content

Document Upload

Some carriers and products allows certain documents to be uploaded in advance and included in the shipment data we forward to the carrier.

Examples of these kinds of documents include certificates of origin, import permits or if you want to attach your own commercial invoice instead of the one we can generate in Shipmondo. The valid document types vary depending on the carrier in question.

Initiate Direct Upload​

To add documents to shipment request you first need to upload the document to our data storage.
To do this you first request a direct upload URL by making a POST request to the endpoint "/api/public/v3/documents/upload" with the following payload structure:

{
    "file_name": "test_file.pdf",
    "byte_size": 52658,
    "content_type": "application/pdf",
    "checksum": "5kGrrr/5/PAiVq5rA5efuw=="
}

file_name: The document name as it will appear when uploaded to data storage.
byte_size: The precise byte size of the file in bytes.
content_type: The content type of the document - currently only "application/pdf" is allowed.
checksum: The checksum of the file to be uploaded, calculated as a base64 encoded MD5 hash.

The response of this request will look like this:

{
    "signed_id": "eyJ0ZXN0IjoidGVzdCJ9",
    "direct_upload": {
        "url": "https://example.com/eyJ0ZXN0IjoidGVzdCJ9",
        "headers": {
            "Content-Type": "application/pdf",
            "Content-MD5": "5kGrrr/5/PAiVq5rA5efuw==",
            "Content-Disposition": "inline; filename=\"test_file.pdf\"; filename*=UTF-8''test_file.pdf"
        }
    }
}

The signed_id should be saved and later used in the actual create-shipment-request.
The url should be used to perform a PUT request to the exact returned URL, with the actual document file attached.
Any headers present in the above response should be included in this PUT request as well.

When the PUT request has been performed the document has been uploaded, and the signed_id can be used in shipment requests.

Creating Shipments with documents​

To actually attach an uploaded document to a shipment you will need to add the following to your requests to "/api/public/v3/shipments":

...
    "documents": [
        {
            "document_type": "commercial_invoice",
            "signed_id": "eyJ0ZXN0IjoidGVzdCJ9"
        }
    ],
...

Multiple documents can be attached to a single shipment, but only one of each type.
An uploaded document and its associated signed_id can be reused and shared between multiple shipments. This means that in the case of static documents, you only need to upload the document once and you can then keep using the same signed_id.

Valid Document Types​

As mentioned previously, the valid document types varies by carrier.

UPS: commercial_invoice, auth_form, certificate_of_origin, export_accompanying_document, export_license, import_permit, one_time_usmca, other, power_of_attorney, packing_list, sed_document, shippers_letter_of_instruction, declaration
DHL Express: proforma_invoice, commercial_invoice, certificate_of_origin, nafta_certificate_of_origin, air_waybill, invoice customs_declaration
FedEx: TBD
Link Logistics: other, proforma_invoice, commercial_invoice, consignment_note, bill_of_lading

Note: It is not possible to attach your own proforma_invoice/commercial_invoice when creating shipments using Shipmondo's agreements.