Documents API Tutorial

Table of contents

Overview

The Flexport Documents API returns a list of all documents associated with shipments, retrieves the details of a single document, and retrieves the contents of a specified file.

Endpoints

 GET /documents
POST /documents
 GET /documents/id
 GET /documents/id/download

Initial Set Up

The documents API does not require any pre-configuration.

Creating a document

You may post a document using the following parameters:

  • file_name: The name of the uploaded file
  • mime_type: The media type (per RFC 6838)
  • document_type: one of the supported types (below)
  • memo: optional note for the document
  • document: the file encoded as base64
  • shipment_id: the Flexport identifier for the shipment (Flex ID)
curl -X "POST" "https://api.flexport.com/documents/" \
     -H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Flexport-Version: 3" \
     -H "Content-Type: application/json" \
     -d $'{
        "document": "aGVsbG8=",
        "memo": "colorless green ideas sleep furiously",
        "document_type": "commercial_invoice",
        "file_name": "HELLO.TXT",
        "mime_type": "text/plain",
        "shipment_id": 693350
      }'

Sample Response:

{
  "_object": "/api/response",
  "self": "https://api.flexport.com/documents/",
  "version": 2,
  "data": {
    "_object": "/document",
    "id": "FTP-VvpjRpWWFSgArOO7eQ",
    "file_name": "HELLO.TXT",
    "document_type": "commercial_invoice",
    "memo": "colorless green ideas sleep furiously",
    "file_link": "https://api.flexport.com/documents/FTP-VvpjRpWWFSgArOO7eQ/download",
    "archived_at": null,
    "file_metadata": {
      "_object": "/file/metadata",
      "size": 5,
      "uploaded_at": "2021-09-24T19:13:25.328Z"
    },
    "shipment": {
      "_object": "/api/refs/object",
      "ref_type": "/shipment",
      "link": "https://api.flexport.com/shipments/693350",
      "id": 693350
    }
  },
  "error": null
}

The document types supported for uploading(POST) are:

  • warehouse_packaging_slip
  • air_certification_for_safe_transport
  • bank_slip
  • booking_sheet
  • booking_sheet
  • certificate_of_origin
  • client_shipment_request
  • commercial_invoice
  • commercial_invoice_packing_list
  • customs_fda_document
  • customs_footwear_declaration
  • customs_hs7_for_us_department_of_transportation
  • customs_lacey_declaration
  • customs_toxic_substance_control_act_declaration
  • customs_us_fish_and_wildlife_service_form_3_177
  • draft_commercial_invoice
  • draft_commercial_invoice_packing_list
  • draft_dangerous_goods_declaration
  • draft_packing_list
  • eu_customs_duties_bill
  • eu_customs_release_sad
  • exporter_s_statement_of_origin
  • isf_worksheet
  • letter_of_indemnity_loi_for_non_dg
  • lithium_battery_declaration
  • magnetic_testing_report
  • material_safety_data_sheet_msds
  • packing_list
  • product_list
  • pro_forma_invoice
  • purchase_order
  • sea_certification_for_safe_transport
  • shipper_s_declaration_for_dangerous_goods
  • shipper_s_letter_of_instructions_sli
  • shipping_instructions
  • shipping_labels
  • trucking_bill_of_lading
  • un_38_3
  • verified_gross_mass_declaration
  • warehouse_packaging_slip

Retrieving Your Documents

To retrieve a document, you may do a GET over the document's endpoint.

curl -X "GET" "https://api.flexport.com/documents" \
     -H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Flexport-Version: 3" \
     -H "Content-Type: application/json" \

Response:

{
  "_object": "/api/response",
  "self": "https://api.flexport.com/documents",
  "version": 2,
  "data": {
    "_object": "/api/collections/paginated",
    "prev": null,
    "next": null,
    "total_count": 8,
    "data": [
      {
        "_object": "/document",
        "id": "bRBBQN2wQteNKaVcDPB2fg",
        "file_name": "FLEX-1211233_Quote-1557748_20210627T022556.pdf",
        "document_type": "freight_forwarder_quote",
        "memo": null,
        "file_link": "https://api.flexport.com/documents/bRBBQN2wQteNKaVcDPB2fg/download",
        "archived_at": null,
        "file_metadata": {
          "_object": "/file/metadata",
          "size": 35297,
          "uploaded_at": "2021-06-27T02:25:59.211Z"
        },
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/1211233",
          "id": 1211233
        }
      },
      {
        "_object": "/document",
        "id": "HyuzxL6qToCPcGAbAkEgwA",
        "file_name": "FINAL_FMA210881.pdf",
        "document_type": "air_waybill",
        "memo": null,
        "file_link": "https://api.flexport.com/documents/HyuzxL6qToCPcGAbAkEgwA/download",
        "archived_at": null,
        "file_metadata": {
          "_object": "/file/metadata",
          "size": 160093,
          "uploaded_at": "2021-06-27T11:25:35.650Z"
        },
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/1211233",
          "id": 1211233
        }
      },
      {
        "_object": "/document",
        "id": "xK75xvuxRWaPWMl5AhuJ0Q",
        "file_name": "Flexport-Cargo-Receipt.pdf",
        "document_type": "origin_warehouse_receipt",
        "memo": null,
        "file_link": "https://api.flexport.com/documents/xK75xvuxRWaPWMl5AhuJ0Q/download",
        "archived_at": null,
        "file_metadata": {
          "_object": "/file/metadata",
          "size": 55448,
          "uploaded_at": "2021-06-27T11:28:40.808Z"
        },
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/1211233",
          "id": 1211233
        }
      },
      {
        "_object": "/document",
        "id": "nXXR5leUSImkU5axcRl5Cg",
        "file_name": "generate.7512.FCABFA210881.pdf",
        "document_type": "transportation_entry_and_manifest_of_goods_subject_to_cbp_inspection_and_permit_form_7512",
        "memo": null,
        "file_link": "https://api.flexport.com/documents/nXXR5leUSImkU5axcRl5Cg/download",
        "archived_at": null,
        "file_metadata": {
          "_object": "/file/metadata",
          "size": 20553,
          "uploaded_at": "2021-07-01T01:09:00.526Z"
        },
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/1211233",
          "id": 1211233
        }
      },
      {
        "_object": "/document",
        "id": "jxDZGcI8ToOp1ZrY8g4Z_A",
        "file_name": "ACESOASEP.PDF",
        "document_type": "other_customs_documents",
        "memo": null,
        "file_link": "https://api.flexport.com/documents/jxDZGcI8ToOp1ZrY8g4Z_A/download",
        "archived_at": null,
        "file_metadata": {
          "_object": "/file/metadata",
          "size": 2596,
          "uploaded_at": "2021-07-06T18:11:17.990Z"
        },
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/1211233",
          "id": 1211233
        }
      },
      {
        "_object": "/document",
        "id": "iOJsnwhoT5C3WjHIK4HjYQ",
        "file_name": "CF3461P_(5).PDF",
        "document_type": "customs_release_3461",
        "memo": null,
        "file_link": "https://api.flexport.com/documents/iOJsnwhoT5C3WjHIK4HjYQ/download",
        "archived_at": null,
        "file_metadata": {
          "_object": "/file/metadata",
          "size": 49204,
          "uploaded_at": "2021-07-06T18:11:27.589Z"
        },
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/1211233",
          "id": 1211233
        }
      },
      {
        "_object": "/document",
        "id": "bul5OdwYStulkzT88nIeBQ",
        "file_name": "CF3461P.PDF",
        "document_type": "customs_release_3461",
        "memo": null,
        "file_link": "https://api.flexport.com/documents/bul5OdwYStulkzT88nIeBQ/download",
        "archived_at": null,
        "file_metadata": {
          "_object": "/file/metadata",
          "size": 49204,
          "uploaded_at": "2021-07-06T18:42:32.434Z"
        },
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/1211233",
          "id": 1211233
        }
      },
      {
        "_object": "/document",
        "id": "4MNaxfCIS1Wj9VxDX_kd5Q",
        "file_name": "TapScanner_07-09-2021-15.37(1)_(2).pdf",
        "document_type": "proof_of_delivery_pod",
        "memo": null,
        "file_link": "https://api.flexport.com/documents/4MNaxfCIS1Wj9VxDX_kd5Q/download",
        "archived_at": null,
        "file_metadata": {
          "_object": "/file/metadata",
          "size": 403335,
          "uploaded_at": "2021-07-12T17:21:25.070Z"
        },
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/1211233",
          "id": 1211233
        }
      }
    ]
  },
  "error": null
}

In order to retrieve your document, you will need to follow the file_link using GET.

curl -X "GET" "https://api.flexport.com/documents/4MNaxfCIS1Wj9VxDX_kd5Q/download" \
     -H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Flexport-Version: 3" \
     -H "Content-Type: application/json" \

Note that updating a document via API is not supported.

In order to use the /documents endpoint, you must know the Flexport shipment id (Flex ID) for which you want to upload a document. The maximum supported size of an uploaded file (before base64 conversion is 10mb).

It is recommended that you filter by the doc type you are interested in when querying the endpoint.

Filtering Returned

The /documents endpoint allows you to filter using the following parameters.

Error Handling

On occasion, things don’t always proceed as you expect. Naturally, various HTTP error codes, along with an exception JSON object, are returned to help you build your exception handling routines.

An example of an error response on POST is shown below.

{
  "_object": "/api/response",
  "self": "https://api.flexport.com/documents/",
  "version": null,
  "data": null,
  "error": {
    "_object": "/api/error",
    "status": 422,
    "code": "unprocessable_entity",
    "message": "Unable to decode document. Make sure document has a base64 string encoding."
  }
}

An example of an error response on GET is shown below.

{
  "_object": "/api/error",
  "status": 400,
  "code": "invalid_pagination",
  "message": "Invalid Sort Direction. allowed values: desc, asc"
}

You’ll want to use the status and message fields to handle exceptions. Let’s take a look at possible values in those fields:

  • Status 422 is returned if there is a problem with the payload on POST
  • Status 400 is returned if there is a parameter issue on GET
  • HTTP 404 is returned if the entity in question does not exist (invalid document_id on get, invalid shipment_id on POST).