Validate before you file

POST /v1/validate checks a FIRMS code against the published CBP list before you put it on a filing.

curl https://api.firmsapi.com/v1/validate -H "x-api-key: $FIRMSAPI_KEY" -H "content-type: application/json" \
  -d '{"code": "E430", "port": "4601", "use": "warehouse_entry"}'

Field
code	required	The code to check, as it appears in your system. A malformed code is a failed check, not an error.
port	optional	The 4-digit port of entry of the filing. Enables the port check.
use	optional	warehouse_entry, ftz_admission, exam_site or location_of_goods. Enables the facility-type check.

Checks

Checks run in this order. When one fails, the checks that depend on it are skipped.

Check	ACE reject it catches	Passes when
format		The code is four letters or digits
exists	158	The code is on the CBP FIRMS list
active	159	The code is not deleted
port	164	The code is in port
type_for_use	028 for FTZ admission	The facility type fits use: warehouse entry needs a bonded warehouse (04), FTZ admission an FTZ (02), exam site a CES (09); location of goods cannot be a DP site (07) or CBP administrative (08)
not_junk		The code is not a “DO NOT USE” placeholder or a CBP test record

Response

A code that fails is still a 200, with valid: false. It counts as a call.

{
  "data": {
    "code": "E430",
    "valid": false,
    "checks_passed": [
      { "id": "format", "title": "Code format", "ace_code": null, "message": "E430 is four letters or digits." },
      { "id": "exists", "title": "Code is on the FIRMS list", "ace_code": "158", "message": "E430 is on the CBP FIRMS list." },
      { "id": "active", "title": "Code is active", "ace_code": "159", "message": "E430 is active." },
      { "id": "port", "title": "Code is in the stated port", "ace_code": "164", "message": "E430 is in port 4601." },
      { "id": "not_junk", "title": "Not a placeholder or test code", "ace_code": null, "message": "E430 is a real facility record." }
    ],
    "checks_failed": [
      { "id": "type_for_use", "title": "Facility type fits the intended use", "ace_code": null, "message": "E430 is a Pier or terminal, which does not fit Warehouse entry." }
    ],
    "checks_skipped": [],
    "checks_not_possible": [
      { "id": "bond_status", "title": "Bond status", "message": "The FIRMS list does not publish bond status. Confirm the facility's bond is active in ACE." },
      { "id": "ftz_zone_id", "title": "FTZ zone ID", "message": "…" },
      { "id": "direct_delivery", "title": "Direct delivery", "ace_code": "238", "message": "…" },
      { "id": "port_clusters", "title": "Port clusters", "message": "…" }
    ],
    "facility": { "code": "E430", "name": "MAHER TERMINAL", "...": "..." },
    "note": "FIRMSapi checks the published CBP FIRMS code list only. Confirm the code, bond status and port eligibility in ACE before you file."
  },
  "meta": { "...": "..." }
}

• checks_skipped lists checks you did not ask for (no port or use) or that depend on a failed check.
• checks_not_possible is always there: bond status, FTZ zone ID, direct delivery eligibility and port clusters are not in the FIRMS list. Some ports accept codes from neighboring ports, so a failed port check can still be accepted.
• valid: true means no check failed. Always confirm in ACE before you file.