Skip to content
FIRMSapi Docs

Batch

Pro and Enterprise. Send up to 100 requests; each is one of:

  • {"op": "lookup", "code": "E430"}, like GET /firms/{code}
  • {"op": "validate", "code": "E430", "port": "4601", "use": "warehouse_entry"}, like POST /validate
  • {"op": "search", "q": "lbct long beach", "state": "CA", "port": "2704", "limit": 5}, like GET /search (limit up to 20)
Terminal window
curl https://api.firmsapi.com/v1/batch -H "x-api-key: $FIRMSAPI_KEY" -H "content-type: application/json" -d '{
  "requests": [
    {"op": "lookup", "code": "E430"},
    {"op": "lookup", "code": "ZZZ9"},
    {"op": "validate", "code": "F577", "port": "4601"}
  ]
}'

Results come back in order, each with the status the same request would get on its own endpoint, and either data or error:

{
  "data": [
    { "status": 200, "data": { "code": "E430", "...": "..." }, "error": null },
    { "status": 404, "data": null, "error": { "code": "not_found", "message": "ZZZ9 is not on the CBP FIRMS list.", "links": { "...": "..." } } },
    { "status": 200, "data": { "code": "F577", "valid": true, "...": "..." }, "error": null }
  ],
  "meta": { "...": "..." }
}

Counting

Section titled “Counting”

Each request in the batch counts as one call, whatever its result. The whole batch is counted up front: if your remaining calls (plan, packs and overage cap together) cannot cover it, nothing runs and you get 429 quota_exceeded. A malformed batch (400) is not counted.