Get shipment documents
Learn how to retrieve customs documents and other shipment documents, including CN22s, invoices, and hazard labels.
Shipment documents
The Shipments platform can automatically generate customs documentation, and hazard labels for shipments.
Once a shipment is allocated, Shipments will automatically determine what documentation is required for it. Shipments API can generate the following document types:
cn22- Customs documentation. Only generated for applicable international shipments.cn23- Customs documentation. Only generated for applicable international shipments.commercial_invoice- Customs documentation. Only generated for applicable international shipments.hazard_label- Generated for shipments containing dangerous goods.collection_note- A driver’s manifest for the shipment. Generated for all shipments.
The Shipments platform also generates delivery labels, which have the same data structure as shipment documents and are also created after allocation. However, labels are managed through their own dedicated endpoints, and cannot be returned through Shipment’s Documents endpoints. For information on using delivery labels in the Shipments platform, see the Getting Shipment Labels page.
Shipments API offers two endpoints to retrieve documents once they have been generated:
- Get Document retrieves a specific document.
- Get Customs Documents retrieves all customs documents (that is, CN22, CN23, and commercial invoice documents) that have been generated for a particular shipment.
The Shipment platform’s auto-generated documents should not be confused with paperless documents. Paperless documents are documents that are attached to a shipment prior to allocation and transmitted to a carrier as part of that shipment’s data. Auto-generated documents are created by Shipments at the point of allocation and are intended to be printed before the carrier picks the shipment up. For more information on using paperless documents in the Shipments API, see the Adding Paperless Documents page.
Getting a specific shipment document
To call Get Document, send a GET request to https://api.sorted.com/pro/documents/{shipment_reference}/{document_type}, where {shipment_reference} is the unique reference of the shipment that the document belongs to and {document_type} is the type of document you want to return for that shipment.
If the specified shipment has a document of the specified type, then Shipments returns a document object representing that document. Otherwise, an error is returned.
If you use the Get Document endpoint to get a collection_note for a shipment, then the Shipments platform returns a collection note for the contents of that shipment only. If you need collection notes for multiple shipments being picked up by the same carrier (as part of a scheduled collection, for example), you should use one of Shipment API’s dedicated Collection Notes endpoints instead.
For more information on using collection notes in the Shipments API, see the Getting Collection Notes page.
For full reference information on the Get Document endpoint, see the Shipments API reference.
Getting all of a shipment’s customs documents
To call Get Customs Documents, send a GET request to https://api.sorted.com/pro/documents/{shipment_reference}, where {shipment_reference} is the unique reference of the shipment that you want to get customs documents for.
If the specified shipment has customs documents (that is, it is an international shipment), then Shipments returns a list of document objects representing those documents. Otherwise, an error is returned.
For full reference information on the Get Customs Documents endpoint, see the Shipments API reference.
The document response
Both Documents endpoints return document objects. Get Document returns a single document, while Get Customs Documents returns a list.
The document object has four properties:
file- A base64-encoded byte array representing the file content.content_type- The document’s format (e.g. application/pdf).document_type- The type of document (e.g. commercial_invoice).dpi- The document’s resolution in DPI.
404 - Not Found error if you attempt to get documents for an unallocated shipment. This code signifies that the request passed validation but there are no documents available for the specified shipment.Examples
The example below shows a successful Get Document request for the cn22 document associated with shipment sp_00670175533382557003917067812864. Shipments returns a document object representing that document. In this example, the Base64 data returned has been removed for clarity.
GET https://api.sorted.com/pro/documents/sp_00670175533382557003917067812864/cn22
{
"file": {Base64 file contents},
"content_type": "application/pdf",
"document_type": "cn22",
"dpi": 203
}
The example below shows a successful Get Customs Documents request for all customs documents associated with shipment sp_00670175533382557003917067812864. Shipments returns a list of document objects representing the cn22, cn23, and commercial_invoice documents associated with that shipment. In this example, the Base64 data returned has been removed for clarity.
GET https://api.sorted.com/pro/documents/sp_00670175533382557003917067812864
Get customs documents response
[
{
"file": {Base64 file contents},
"content_type": "application/pdf",
"document_type": "cn22",
"dpi": 203
},
{
"file": {Base64 file contents},
"content_type": "application/pdf",
"document_type": "cn23",
"dpi": 203
},
{
"file": {Base64 file contents},
"content_type": "application/pdf",
"document_type": "commercial_invoice",
"dpi": 203
}
]
Using the label data
Once you have downloaded the file data, you will need to decode the file’s Base64 in order to view the label itself. If you are unsure how to do so, see the MDN docs for more information.
Next steps
- Learn how to add shipments to a carrier manifest at the Manifesting shipments page.
- Learn how to retrieve a shipment’s labels at the Get shipment labels page.
- Learn how to work with shipment groups at the Managing shipment groups page.