If you are using Flexport as your import-customs broker, you can use the Flexport API to fetch the status of a US-CBP customs entry on one of your shipments. The Customs Entry endpoint allows you to know the release status of an entry as soon as Flexport is notified of any changes. The Flexport Customs Entry API is available here.

Endpoints

GET /customs_entries
GET /customs_entries/id

The Customs JSON Object has some important elements that need to be taken into consideration. Before we get going, take a look at the elements from the document.

To retrieve a complete set of your custom entries with shipment information, make an HTTP GET request to the List customs entry objects endpoint:

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

Make sure you set your headers to those shown above. You can use pagination (the page parameter) to indicate the page number you desire, and the number of items per page returned in the response, with the per parameter. In our example, we’re looking for Page 1 with a maximum of 10 items.

The response you receive will contain data specific to you but it will contain the same elements as shown in the following sample:

{
  "_object": "/api/response",
  "self": "https://api.sb.flexport.com/customs_entries?page=1",
  "version": 2,
  "data": {
    "_object": "/api/collections/paginated",
    "prev": null,
    "next": "https://api.sb.flexport.com/customs_entries?page=2&per=10",
    "total_count": 14,
    "data": [
      {
        "_object": "/customs_entry",
        "id": "MpG7GULQbuvaVHKeQ-pvEg",
        "entry_number": "283989829",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/23481",
          "id": 23481
        }
      },
      {
        "_object": "/customs_entry",
        "id": "cAtxIaOUxurK4NBG2mgBKA",
        "entry_number": "CHQ-49813874",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/23458",
          "id": 23458
        }
      },
      {
        "_object": "/customs_entry",
        "id": "qwadg7a2vipKyXAfaazGIA",
        "entry_number": "829183811",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/16524",
          "id": 16524
        }
      },
      {
        "_object": "/customs_entry",
        "id": "dhnj1dv_8YGSnCh7-i-xYQ",
        "entry_number": "98E9898",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/23445",
          "id": 23445
        }
      },
      {
        "_object": "/customs_entry",
        "id": "P8nv7Dvexn3tZ2lNTYqo4Q",
        "entry_number": "CHQ-23819212",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/24866",
          "id": 24866
        }
      },
      {
        "_object": "/customs_entry",
        "id": "IxKamajPZ7PYg26iuk36Yg",
        "entry_number": "CHQ-238918313",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/24870",
          "id": 24870
        }
      },
      {
        "_object": "/customs_entry",
        "id": "RaaawbxP5ctvREioGC3WXw",
        "entry_number": "CHQ-1491813189",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/24871",
          "id": 24871
        }
      },
      {
        "_object": "/customs_entry",
        "id": "mZscVsFTleczn-sAWXgU4Q",
        "entry_number": "39849283",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/23456",
          "id": 23456
        }
      },
      {
        "_object": "/customs_entry",
        "id": "UgbTsPGicLgg8FDg33cgRA",
        "entry_number": "FLX-I2U312",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/29283",
          "id": 29283
        }
      },
      {
        "_object": "/customs_entry",
        "id": "gGEI8lad8W2jf4ktR2Y34A",
        "entry_number": "CHQ-34321938918",
        "release_status": null,
        "release_date": null,
        "shipment": {
          "_object": "/api/refs/object",
          "ref_type": "/shipment",
          "link": "https://api.flexport.com/shipments/29370",
          "id": 29370
        }
      }
    ]
  },
  "error": null
}

The response contains a top-level element entitled data which itself contains an element named data. That top-level element data contains links to previous and next pages which can come in handy when you want to quickly navigate backwards and forwards through your custom_entry objects. Notice too that there’s a total_count element containing - no surprise - the count of all custom_entry objects.

The lower-level data element encapsulates summary information of each custom_entry object. Because we set the per argument to 10 in our request, we’ve only received 10 of 14 custom_entry objects. You can get the remaining four custom_entry objects by either making another HTTP GET request with the value of the next element, or simply change the page parameter value of your original request to 2.

The custom_entry object contains summary elements including entry_number, release_status and release_date, as well as a link to the related shipment information in the shipment object:

{
  "shipment": {
    "_object": "api/refs/object",
    "ref_type": "/shipment",
    "link": "https://api.flexport.com/shipments/29370",
    "id": 29370
  }
}

Let’s drill into the specifics of an example. The following is a sample GET request:

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

Notice the endpoint contains a custom entry ID (gGEI8lad8W2jf4ktR2Y34A):

https://api.flexport.com/customs_entries/gGEI8lad8W2jf4ktR2Y34A. Using it, we get back:

{
  "_object": "/api/response",
  "self": "https://api.sb.any.com/customs_entries/cAtxIaOUxurK4NBG2mgBKA",
  "version": 2,
  "data": {
    "_object": "/customs_entry",
    "id": "cAtxIaOUxurK4NBG2mgBKA",
    "entry_number": "CHQ-49813874",
    "release_status": null,
    "release_date": null,
    "shipment": {
      "_object": "/api/refs/object",
      "ref_type": "/shipment",
      "link": "https://api.any.com/shipments/23458",
      "id": 23458
    }
  },
  "error": null
}

with the details of just that ID.

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