Adding Paperless Documents

  • Ship
  • api
  • 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.

What are Paperless Documents?

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.

Caution

Not all carriers support paperless trade.

Ship 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.

Documents must be uploaded as an image in one of Ship'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.

Note

Ship's paperless document functionality should not be confused with Ship's customs documents functionality. Paperless documents are added to the shipment before allocation and transmitted as part of that shipment's data, while customs documents are generated post-allocation and are intended to be printed before dispatch. For more information on working with customs documents in PRO, see the Getting Shipment Documents page.

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.

Note

It is only possible to add a paperless document to a shipment prior to allocation (i.e. when the shipment is in a state of either unallocated or allocation_failed). If you attempt to add a paperless document to an allocated shipment then Ship returns an error.

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 Ship 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 Ship paperless_document_usage value. See the Shipments data contract for a list of valid document usages. If this property is not provided then Ship defaults to a usage of electronic_trade for the document.

Once it has received the request, Ship 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. Ship has responded with a paperless document reference of pd_00797582543150236528252876881920.

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"
}
Note

For full reference information on the Add Paperless Document endpoint, see the Ship API reference

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, Ship 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.

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

Note

For full reference information on the Get Paperless Document endpoint, see the Ship API reference

Next Steps