FIRMSapi

Get the CBP FIRMS record for one code: facility name, status (active or deleted), facility type, address, CBP port, location, and the other codes registered at the same address. Deleted codes and "DO NOT USE" placeholders (junk: true) are returned with warnings. A code that is not on the list returns a not_found error, which still counts as a call. Wraps GET /v1/firms/{code}. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{4}$",
      "description": "4-character FIRMS code, e.g. E430."
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

Find FIRMS codes from a facility name and/or street address, e.g. 'maher terminal elizabeth' or '231 tyler st newark'. Typo-tolerant; returns ranked matches with a 0-100 score. Active codes only unless include_deleted is true. One call per search, however many results. Wraps GET /v1/search. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200,
      "description": "Name and/or address."
    },
    "state": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "2-letter state, e.g. NJ."
    },
    "port": {
      "type": "string",
      "pattern": "^[0-9]{4}$",
      "description": "4-digit CBP port code, e.g. 4601."
    },
    "types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "01",
          "02",
          "03",
          "04",
          "05",
          "06",
          "07",
          "08",
          "09",
          "10",
          "11"
        ]
      },
      "description": "Only these facility types: 01 Container freight station (CFS), 02 Foreign trade zone (FTZ), 03 Pier or terminal, 04 Bonded warehouse, 05 Inspection facility, 06 Importer premises, 07 DP site, 08 CBP administrative, 09 Centralized examination station (CES), 10 Rail or air terminal (inferred), 11 CBP test."
    },
    "include_deleted": {
      "type": "boolean",
      "default": false,
      "description": "Include deleted codes (ranked after active ones)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

List FIRMS facilities within radius_km, nearest first. Pass exactly one origin: lat and lon; code (another FIRMS facility, left out of the results); or address (a US street address, geocoded unless it is a FIRMS facility's own address). meta.origin says which point was used. Facilities whose address could not be geocoded are not included. Test keys use approximate coordinates. Wraps GET /v1/nearby. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "code": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{4}$",
      "description": "Search around this FIRMS code."
    },
    "address": {
      "type": "string",
      "minLength": 3,
      "maxLength": 200,
      "description": "Search around this US street address, e.g. 231 Tyler St, Newark, NJ 07114."
    },
    "radius_km": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 100,
      "default": 10
    },
    "types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "01",
          "02",
          "03",
          "04",
          "05",
          "06",
          "07",
          "08",
          "09",
          "10",
          "11"
        ]
      },
      "description": "Only these facility types: 01 Container freight station (CFS), 02 Foreign trade zone (FTZ), 03 Pier or terminal, 04 Bonded warehouse, 05 Inspection facility, 06 Importer premises, 07 DP site, 08 CBP administrative, 09 Centralized examination station (CES), 10 Rail or air terminal (inferred), 11 CBP test."
    },
    "include_deleted": {
      "type": "boolean",
      "default": false,
      "description": "Include deleted codes (ranked after active ones)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    }
  },
  "additionalProperties": false
}

Pre-filing checks of a FIRMS code against the published CBP list, in order: format, exists (catches ACE reject 158), active (159), in the stated port (164), facility type fits the use (warehouse_entry: bonded warehouse 04; ftz_admission: FTZ 02; exam_site: CES 09; location_of_goods: not 07 or 08), not a placeholder. Returns valid, checks_passed, checks_failed, checks_skipped, checks_not_possible (bond status, FTZ zone ID, direct delivery, port clusters: not in the FIRMS list) and a note. valid: true is not ACE acceptance: FIRMSapi has no ACE connection, so confirm in ACE before filing. A failing code is a normal result (valid: false) and counts as a call. Wraps POST /v1/validate. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "description": "The code as it appears in your system. A malformed code is a failed check."
    },
    "port": {
      "type": "string",
      "maxLength": 8,
      "description": "4-digit CBP port of entry of the filing."
    },
    "use": {
      "type": "string",
      "enum": [
        "warehouse_entry",
        "ftz_admission",
        "exam_site",
        "location_of_goods"
      ],
      "description": "How the code will be used; enables the facility type check."
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

Every CBP port that has FIRMS codes, with name, state, region, facility_count and active_count, in one call. Wraps GET /v1/ports. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

One CBP port with a page of its FIRMS facilities, ordered by code. Placeholders are left out; active codes only unless include_deleted is true. For the next page pass cursor = meta.next_cursor (null on the last page); each page is one call. Wraps GET /v1/ports/{port}. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

{
  "type": "object",
  "properties": {
    "port": {
      "type": "string",
      "pattern": "^[0-9]{4}$",
      "description": "4-digit CBP port code, e.g. 4601."
    },
    "types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "01",
          "02",
          "03",
          "04",
          "05",
          "06",
          "07",
          "08",
          "09",
          "10",
          "11"
        ]
      },
      "description": "Only these facility types: 01 Container freight station (CFS), 02 Foreign trade zone (FTZ), 03 Pier or terminal, 04 Bonded warehouse, 05 Inspection facility, 06 Importer premises, 07 DP site, 08 CBP administrative, 09 Centralized examination station (CES), 10 Rail or air terminal (inferred), 11 CBP test."
    },
    "include_deleted": {
      "type": "boolean",
      "default": false,
      "description": "Include deleted codes (ranked after active ones)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 100
    },
    "cursor": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{4}$",
      "description": "meta.next_cursor."
    }
  },
  "required": [
    "port"
  ],
  "additionalProperties": false
}