What are paperless documents?

Paperless documents are customer-generated documents that are transmitted to carriers as part of a shipment’s data, as opposed to being generated separately by the carrier. This page explains how to add paperless documents to a shipment, retrieve a shipment’s paperless documents, and remove a paperless document from a shipment.

Paperless documents are intended to make your workflows more efficient. You can upload paperless documents using the Add Paperless Documents endpoint.

You can only add paperless documents to an unallocated shipment.

The Shipments platform supports the following paperless document types:

  • Commercial invoice documents
  • Certificates of origin
  • NAFTA certificates of origin
  • Pro-forma invoices
  • Authorisation forms
  • Export documents
  • Export licences
  • Import permits
  • Power of attorney documents
  • Packing lists
  • Shipper’s export (SED) documents
  • Letters of instruction
  • Customs declarations
  • Air waybills
  • Invoices
  • Other

Documents must be uploaded as an image in one of the Shipment platform’s supported formats (PDF, PNG, JPG or GIF), and must be less than 5MB in size. For larger documents you may need to optimise your files (for example, removing fonts and embedded data from a PDF or reducing quality on a JPG) to bring your files under the size limit.

Adding paperless documents to shipments

The Add Paperless Document endpoint enables you to add paperless documents to an existing unallocated shipment. To call Add Paperless Document, send a POST request to https://api.sorted.com/pro/documents/paperless/{reference}, where {reference} is the unique reference of the shipment you want to add the document to.

The body of the request should contain the following information:

  • A file_format property indicating the format of the file being uploaded.
  • A document_type property indicating the type of document being uploaded. This must be a valid Shipments paperless document type. See the Shipments data contract for a list of valid document types.
  • A file_content property containing the document file itself as a base64-encoded byte array.

Optionally, the request body can also include:

  • An expiration property indicating the date and time that the document expires.
  • A usage property indicating the document’s intended usage. If provided, this property must contain a valid Shipments paperless_document_usage value. See the Shipments data contract for a list of valid document usages. If this property is not provided then Shipments defaults to a usage of electronic_trade for the document.

Once it has received the request, the Shipments platform attaches the document to the specified shipment and returns a unique reference for the paperless document.

Example add paperless document call

The example shows a successful request to add a commercial_invoice paperless document to shipment sp_00595452779180472847666078547968. Shipments API has responded with a paperless document reference of pd_00797582543150236528252876881920.

Example add paperless document request

POST https://api.sorted.com/pro/documents/paperless/sp_00595452779180472847666078547968

  {
  "file_format": "pdf",
  "document_type": "commercial_invoice",
  "expiration": "2021-09-01T06:00:00+00:00",
  "file_content": (Base64 document data),
  "usage": "electronic_trade"
}

Example add paperless document response

  {
    "reference": "pd_00797582543150236528252876881920",
    "message": "Paperless Document pd_00797582543150236528252876881920 added successfully",
    "_links": [
        {
            "href": "https://api-int.sorted.com/pro/documents/paperless/pd_00797582543150236528252876881920",
            "rel": "self",
            "reference": "pd_00797582543150236528252876881920",
            "type": "paperless_document"
        },
        {
            "href": "https://api-int.sorted.com/pro/shipments/sp_00797580869643167594270016798720",
            "rel": "shipment",
            "reference": "sp_00797580869643167594270016798720",
            "type": "shipment"
        }
    ]
}

Getting paperless documents

The Get Paperless Document endpoint takes a paperless document reference and returns details of the relevant paperless document. To call Get Paperless Document, send a GET request to https://api.sorted.com/pro/documents/paperless/{document_reference}.

Once it has received the request, the Shipments platform returns a paperless_document object. This object details all of the information that was supplied when the paperless document was added to the shipment.

Example get paperless document call

The example shows a successful Get Paperless Document request for the paperless document added in the previous example, pd_00797582543150236528252876881920.

Example get paperless document request

GET https://api.sorted.com/pro/documents/paperless/pd_00797582543150236528252876881920

Example get paperless document response

  
{
    "file_content": (Base64 document data),
    "expiration": "2021-09-01T06:00:00+00:00",
    "file_format": "pdf",
    "document_type": "commercial_invoice",
    "usage": "electronic_trade"
}

Next steps