Write a filing in the AESTIR format

POST/v1/aes/aestir$0.05 per call

Returns the filing as CBP's AESTIR commodity format: 80-character fixed records (A, B, SC1, SC2, SC3, N01-N03, CL1, CL2, Y, Z), back to back with no line breaks, as AESDirect's EDI file upload takes. Self-filed: the filer is the exporter itself, so the filer ID is the exporter's EIN. Long text is cut to the field length and listed in warnings. Not produced yet, and refused with 422 and the reasons: DDTC/ITAR lines, used vehicles, PGA data, and replace, change and cancel. X12 601 is a different format and is not produced. CBP's own test process (AESDirect Bulk Upload Test Process) is the check that AES accepts a file.

Send an Idempotency-Key header to retry safely.

Request body

Field	Type	Description
usppiNameoptional	string	min length 1 · max length 70
usppirequired	object
usppi.companyNamerequired	string	min length 1 · max length 70
usppi.einrequired	string	Employer identification number, XX-XXXXXXX
usppi.addressrequired	object
usppi.address.line1required	string	min length 1 · max length 60
usppi.address.line2optional	string	max length 60
usppi.address.cityrequired	string	min length 1 · max length 30
usppi.address.staterequired	string	min length 2 · max length 2
usppi.address.ziprequired	string
usppi.contactNamerequired	string	min length 1 · max length 45
usppi.phonerequired	string	min length 7 · max length 20
usppi.emailoptional	string	format email
ultimateConsigneerequired	object
ultimateConsignee.companyNamerequired	string	min length 1 · max length 70
ultimateConsignee.addressrequired	object
ultimateConsignee.address.line1required	string	min length 1 · max length 60
ultimateConsignee.address.line2optional	string	max length 60
ultimateConsignee.address.cityrequired	string	min length 1 · max length 30
ultimateConsignee.address.stateProvinceoptional	string	max length 30
ultimateConsignee.address.postalCodeoptional	string	max length 12
ultimateConsignee.address.countryrequired	string	min length 2 · max length 2
ultimateConsignee.typerequired	string	min length 1 · max length 1
intermediateConsigneeoptional	object
intermediateConsignee.companyNamerequired	string	min length 1 · max length 70
intermediateConsignee.addressrequired	object
intermediateConsignee.address.line1required	string	min length 1 · max length 60
intermediateConsignee.address.line2optional	string	max length 60
intermediateConsignee.address.cityrequired	string	min length 1 · max length 30
intermediateConsignee.address.stateProvinceoptional	string	max length 30
intermediateConsignee.address.postalCodeoptional	string	max length 12
intermediateConsignee.address.countryrequired	string	min length 2 · max length 2
forwardingAgentoptional	object
forwardingAgent.companyNamerequired	string	min length 1 · max length 70
forwardingAgent.einoptional	string
forwardingAgent.addressrequired	object
forwardingAgent.address.line1required	string	min length 1 · max length 60
forwardingAgent.address.line2optional	string	max length 60
forwardingAgent.address.cityrequired	string	min length 1 · max length 30
forwardingAgent.address.staterequired	string	min length 2 · max length 2
forwardingAgent.address.ziprequired	string
portOfExportrequired	string	Schedule D port code (4 to 5 characters). See GET /v1/aes/reference/ports min length 4 · max length 5
portOfUnladingrequired	string	Schedule K port code (4 to 5 characters) min length 4 · max length 5
countryOfUltimateDestinationrequired	string	ISO 3166-1 alpha-2 country of ultimate destination. Embargoed destinations are flagged; see GET /v1/aes/reference/embargoed-countries min length 2 · max length 2
modeOfTransportrequired	string	Mode of transport code: 10 vessel, 20 rail, 30 truck, 40 air, 50 mail, 60 pipeline, 70 passenger. See GET /v1/aes/reference/transport-modes
carrierIdentificationoptional	string	SCAC code, 2 to 4 uppercase letters. Required for air shipments
conveyanceNameoptional	string	max length 30
dateOfExportrequired	string	Date of export, YYYY-MM-DD
relatedPartyTransactionrequired	boolean
routedExportTransactionrequired	boolean
hazardousMaterialsrequired	boolean
filingTyperequired	string	predeparture or postdeparture one of "predeparture", "postdeparture"
inBondCodeoptional	string	In-bond code: 36, 37, 67, 68 or 70. See GET /v1/aes/reference/in-bond-codes
entryNumberoptional	string	max length 15
ftzIdentifieroptional	string	max length 6
shipperReferenceoptional	string	max length 30
stateOfOriginoptional	string	min length 2 · max length 2
commoditiesrequired	array of object	min 1 items · max 99 items
commodities[].scheduleBNumberrequired	string	Ten-digit Schedule B number, digits only
commodities[].descriptionrequired	string	min length 1 · max length 2500
commodities[].quantity1required	number	min 0
commodities[].unitOfMeasure1required	string	min length 1 · max length 5
commodities[].quantity2optional	number	min 0
commodities[].unitOfMeasure2optional	string	max length 5
commodities[].shippingWeightKgrequired	number	min 0
commodities[].valuerequired	number	min 0
commodities[].exportInformationCoderequired	string	Export information code, for example OS. See GET /v1/aes/reference/export-info-codes
commodities[].eccnoptional	string	ECCN such as EAR99 or 5A002
commodities[].licenseTyperequired	string	License code, for example C33 (no licence required). See GET /v1/aes/reference/license-types
commodities[].licenseNumberoptional	string	max length 40
commodities[].licenseValueoptional	number	min 0
commodities[].originStaterequired	string	Two-letter US state of origin min length 2 · max length 2
commodities[].dfIndicatorrequired	string	one of "D", "F"
commodities[].vehicleIdNumberoptional	string	max length 25
commodities[].ddtcRegistrationNumberoptional	string	max length 15
commodities[].ddtcSignificantMilitaryEquipmentoptional	boolean
commodities[].eligiblePartyCertificationoptional	boolean
exemptionCodeoptional	string

Response fields

The spec does not describe this response yet, and there is no captured example. Run the request with your sandbox key to see its shape.

Errors

400 invalid request
401 missing or bad key
403 not in your plan
429 rate limited, see Retry-After
402 payment required
422 validation failed
5xx retry with backoff

Error bodies and codes are described in Error codes and troubleshooting.

curl -X POST "https://api.compliancegrid.ai/v1/aes/aestir" \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usppi": {
      "companyName": "Test Exporter Inc",
      "ein": "12-3456789",
      "address": {
        "line1": "1 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701"
      },
      "contactName": "Pat Doe",
      "phone": "5125550100"
    },
    "ultimateConsignee": {
      "companyName": "Berlin GmbH",
      "address": {
        "line1": "Strasse 1",
        "city": "Berlin",
        "country": "DE"
      },
      "type": "R"
    },
    "portOfExport": "5501",
    "portOfUnlading": "4101",
    "countryOfUltimateDestination": "DE",
    "modeOfTransport": "40",
    "carrierIdentification": "FDEG",
    "dateOfExport": "2026-11-02",
    "relatedPartyTransaction": false,
    "routedExportTransaction": false,
    "hazardousMaterials": false,
    "filingType": "predeparture",
    "commodities": [
      {
        "scheduleBNumber": "8517130000",
        "description": "Smartphones",
        "quantity1": 10,
        "unitOfMeasure1": "NO",
        "shippingWeightKg": 2,
        "value": 5000,
        "exportInformationCode": "OS",
        "licenseType": "C33",
        "originState": "TX",
        "dfIndicator": "D"
      }
    ]
  }'

Try it in the sandbox

Runs against sandbox.api.compliancegrid.ai with your own sandbox key, which stays in this browser. Sandbox responses are mock data. Get a free key.

Sandbox key

Remember for this tab

Request body (JSON)

{
  "usppi": {
    "companyName": "Test Exporter Inc",
    "ein": "12-3456789",
    "address": {
      "line1": "1 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701"
    },
    "contactName": "Pat Doe",
    "phone": "5125550100"
  },
  "ultimateConsignee": {
    "companyName": "Berlin GmbH",
    "address": {
      "line1": "Strasse 1",
      "city": "Berlin",
      "country": "DE"
    },
    "type": "R"
  },
  "portOfExport": "5501",
  "portOfUnlading": "4101",
  "countryOfUltimateDestination": "DE",
  "modeOfTransport": "40",
  "carrierIdentification": "FDEG",
  "dateOfExport": "2026-11-02",
  "relatedPartyTransaction": false,
  "routedExportTransaction": false,
  "hazardousMaterials": false,
  "filingType": "predeparture",
  "commodities": [
    {
      "scheduleBNumber": "8517130000",
      "description": "Smartphones",
      "quantity1": 10,
      "unitOfMeasure1": "NO",
      "shippingWeightKg": 2,
      "value": 5000,
      "exportInformationCode": "OS",
      "licenseType": "C33",
      "originState": "TX",
      "dfIndicator": "D"
    }
  ]
}