Customs ISF

Endpoints relating to Customs ISF objects

Create or update an ISF Worksheet

Create or update an ISF worksheet. Worksheet will be attached to an existing shipment or a new shipment will be created. Note that filing the ISF and creating a shipment if necessary is an asynchronous process that will be completed after the API call concludes.

Request
Request Body schema: application/json
required
required
object (IsfWorksheetHeader)

Context related to an Importer Security Filing

bond_holder
string

Identification number of the party whose bond is being obligated for the ISF

bond_activity_code
string
Default: "IMPORTER_OR_BROKER"

The activity of the bond being used

Enum: "IMPORTER_OR_BROKER" "CUSTODIAN_OF_BONDED_MERCHANDISE" "INTERNATIONAL_CARRIER" "FOREIGN_TRADE_ZONE_OPERATOR" "ISF_BOND"
bond_type
string
Default: "CONTINUOUS"

The type of the bond being used

Enum: "CONTINUOUS" "SINGLE_TRANSACTION"
mode_of_transport
string

The mode of transport that this shipment will be arriving upon

Enum: "VESSEL_NON_CONTAINER" "VESSEL_CONTAINER"
shipment_type
string

The type of shipment this ISF refers to

Enum: "STANDARD_OR_REGULAR_FILINGS" "TO_ORDER_SHIPMENTS" "HOUSEHOLD_GOODS_PERSONAL_EFFECTS_HHG_PE" "MILITARY_GOVERNMENT" "DIPLOMATIC_SHIPMENT" "CARNET" "US_GOODS_RETURNED" "FTZ_SHIPMENTS" "INTERNATIONAL_MAIL_SHIPMENTS" "OUTER_CONTINENTAL_SHELF_SHIPMENTS" "INFORMAL"
submission_type
string
Default: "ISF_10"

The type of ISF being submitted. Currently Flexport only supports ISF-10

Value: "ISF_10"
scac
string

The SCAC of the vessel operator that is transporting the container

required
object or object (IsfWorksheetBillNumbers)
One of:

Bill numbers

regular_bill_of_lading_number
required
string^[A-Z]{4}[\s\-]*[0-9A-Z]{6,12}$

Ocean carrier issued bill number, must start with the carrier SCAC code. Whitespace and dashes will be ignored, must be max 16 characters excluding whitespace and special characters.

required
object (IsfWorksheetReferenceIdentifiers)

List of additional identifiers associated with this ISF. Refer to CBP's documentation for the full definitions and requirements for each identifier.

us_cbp_entry_number
string^[A-Z]{3}[0-9]{8}$

Must be normalized and formatted as follows: FFFNNNNNNNN

carnet_issuing_country_code_and_carnet_number
string

2-digit Country code (carnet issuing country) followed by carnet cumber

bond_reference_number
string

Note that this is NOT the bond number

surety_code
string

3-digit CBP surety code.

user_defined_reference_number
string

User defined reference number. Can be any string.

full_name_of_isf_filer
string

The full legal name of the ISF filer, using the "Last, First, M Initial" format

object (IsfWorksheetShipmentInformation)

Shipment information

object (IsfWorksheetCargoDetails)

Cargo details

object (IsfWorksheetOceanFreightDetails)

Ocean freight details

purchase_order_numbers
Array of strings

List of purchase order numbers

shipment_sub_type
string

Refer to CBP's ISF spec for the definitions of each value

Enum: "SECTION_321" "INFORMAL" "GENERAL_NOTE_3E"
skus
Array of strings

List of product skus

object
incoterm
string

The international commercial terms used for the shipment

Enum: "CFR" "CIF" "CIP" "CPT" "DAP" "DAT" "DDP" "DPU" "EXW" "FAS" "FCA" "FOB"
required
Array of objects (IsfWorksheetEntity)

List of entities associated with this ISF

Array
name
required
string

The name of an entity

entity_type
required
string

Type of an entity

Value: "MANUFACTURER_SUPPLIER"
object or object or object or object or object or object or object or object or object (IsfWorksheetEntityIdentifier)
required
object (IsfWorksheetAddressDetails)

An address

required
Array of objects (IsfWorksheetHarmonizedTariffSchedule) non-empty
object (IsfWorksheetAdditionalServices)

Which additional services Flexport needs to provide for this shipment. If this API is called, Flexport will always perform the importer security filing service. Services not explicitly set will fall back to the defaults as configured in your preferences.

import_customs
boolean
Default: null

Whether Flexport should perform the Customs Import Clearance Filings

object (IsfWorksheetMetadata)

Metadata for an ISF worksheet

source_type
string
Default: "API"

Specifying 'FLEXPORT_TEMPLATE' or 'NON_FLEXPORT_TEMPLATE' allows for relaxed validations when submitting or updating an ISF Worksheet. Relaxed validations disables specific validation and formatting requirements for some fields, causing the request to be rejected with a 400 bad_request less often when there are data problems. Using relaxed validations require additional permission to access and may incur additional costs. Please contact your Flexport Sales representative if you are interested in using this functionality.

Enum: "API" "EDI" "FLEXPORT_TEMPLATE" "NON_FLEXPORT_TEMPLATE"
request_id
string <uuid> (RequestMetadataRequestId)

Optional request ID for the request. Can also be passed as X-Request-ID header. If not given, one will be generated. This mainly is useful for correlating webhook responses to the original request.

webhook_id
string <uuid> (RequestMetadataWebhookId)

Optional Webhook-ID to be notified on when order creation has finished. Webhooks can be configured in Flexport App under 'Your Business' -> 'Settings' -> 'Webhooks'. Webhook will only be sent for a single request.

external_ref
string <= 2048 characters

Your reference for the ISF Worksheet

Responses
200

Success

Response Schema: application/json
_object
string
self
string
version
integer
object (IsfWorksheetUpsertResponse)

Response for a successfully upserted ISF worksheet

id
required
string <uuid>

Unique identifier for the upserted ISF worksheet

fid
string

Flexport identifier for the upserted ISF worksheet

400

Bad Request

500

Internal Server Error

post/customs_documents/isf
Request samples
application/json
{
  • "header": {
    • "bond_holder": "10-1860000012",
    • "bond_activity_code": "IMPORTER_OR_BROKER",
    • "bond_type": "CONTINUOUS",
    • "mode_of_transport": "VESSEL_NON_CONTAINER",
    • "shipment_type": "STANDARD_OR_REGULAR_FILINGS",
    • "submission_type": "ISF_10",
    • "scac": null
    },
  • "bill_numbers": {
    • "regular_bill_of_lading_number": "ABCD1234567"
    },
  • "reference_identifiers": {
    • "us_cbp_entry_number": "CHQ12345678",
    • "carnet_issuing_country_code_and_carnet_number": "US 89/09-SAMPLE",
    • "bond_reference_number": "5469846315",
    • "surety_code": "016",
    • "user_defined_reference_number": "my-reference",
    • "full_name_of_isf_filer": "Smith, John, J."
    },
  • "shipment_information": {
    • "cargo_details": {
      • "estimated_value": 0,
      • "estimated_quantity": {
        },
      • "estimated_weight": {
        }
      },
    • "ocean_freight_details": {
      • "containers": [
        ],
      • "port_of_loading": {
        },
      • "transshipment_ports": [
        ],
      • "port_of_unloading": {
        },
      • "scac": "MAEU",
      • "vessel": {
        },
      • "voyage_tracking_number": "012"
      },
    • "purchase_order_numbers": [
      • "PO123456"
      ],
    • "shipment_sub_type": "SECTION_321",
    • "skus": [
      • "ABC-DEF-123456"
      ],
    • "forwarding_agent": {
      • "name": "Flexport International LLC",
      • "address_details": {
        }
      },
    • "incoterm": "CFR"
    },
  • "entities": [
    • {
      • "name": "Flexport",
      • "entity_type": "MANUFACTURER_SUPPLIER",
      • "entity_identifier": {
        },
      • "address_details": {
        }
      }
    ],
  • "additional_services": {
    • "import_customs": null
    },
  • "request_metadata": {
    • "source_type": "API",
    • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
    • "webhook_id": "a47606a1-5b39-4a81-9480-c2cb738ff675",
    • "external_ref": "isf_worksheet_SCAC123456789.pdf"
    }
}
Response samples
application/json
{}
➔ Next to Invoices