Quickstart

1. Get a key. Sign up at the developer portal. Your account starts on the Free plan with a test key (fapi_test_…). Copy it when it’s shown: keys are displayed once.

2. Set two environment variables.

   export FIRMSAPI_URL=https://api.firmsapi.com/v1
   export FIRMSAPI_KEY=fapi_test_your_key_here

3. Look up a code. E430 is Maher Terminal in Elizabeth, NJ.

   curl

   curl "$FIRMSAPI_URL/firms/E430" -H "x-api-key: $FIRMSAPI_KEY"

   JavaScript

   const res = await fetch(`${process.env.FIRMSAPI_URL}/firms/E430`, {
     headers: { 'x-api-key': process.env.FIRMSAPI_KEY },
   });
   const body = await res.json();
   if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
   console.log(body.data.name, body.meta.data_as_of);

   Python

   import os
   import requests
   
   res = requests.get(
       f"{os.environ['FIRMSAPI_URL']}/firms/E430",
       headers={"x-api-key": os.environ["FIRMSAPI_KEY"]},
       timeout=10,
   )
   body = res.json()
   res.raise_for_status()
   print(body["data"]["name"], body["meta"]["data_as_of"])

4. Search by name. Paperwork rarely has the code. Search takes free text:

   curl -G "$FIRMSAPI_URL/search" --data-urlencode "q=maher terminal elizabeth" \
     -H "x-api-key: $FIRMSAPI_KEY"

5. Validate before you file. Check a code against the port on your filing and what you’re using it for:

   curl "$FIRMSAPI_URL/validate" -H "x-api-key: $FIRMSAPI_KEY" \
     -H "content-type: application/json" \
     -d '{"code": "E430", "port": "4601", "use": "location_of_goods"}'

   The response says whether the code is valid and lists checks_passed, checks_failed and checks_not_possible: things public data can’t settle, such as bond status. See Validate before you file.

6. Go live. Create a live key (fapi_live_…) in the portal and swap it in. Nothing else changes.

Test keys vs live keys

Test keys return fixture data (a small sample of real FIRMS rows, E430 included) and never count toward your quota, so use them in CI and local development. Every response says which you used in meta.mode (test or live).

Every response

• JSON, under /v1, authenticated with the x-api-key header.
• meta.data_as_of: the date of the CBP list the answer came from.
• meta.source and meta.mode (live or test).
• Errors use one shape: {"error": {"code": "...", "message": "...", "links": {...}}}. See errors.

Next

• FIRMS codes explained: facility types, deleted codes and why a regex is the wrong check.
• API overview and the API reference: every endpoint and parameter.
• Plans and limits: prices, quotas and what counts as a call.