# FIRMSapi Docs

> Docs for FIRMSapi, the developer API for U.S. CBP FIRMS facility codes: lookup, fuzzy search, nearby search and pre-filing validation. API base URL https://api.firmsapi.com/v1, `x-api-key` header auth. OpenAPI 3.1.0 spec: https://docs.firmsapi.com/openapi.json.

## How to look up a FIRMS code programmatically

1. Get an API key: sign up at https://app.firmsapi.com/signup?plan=free (Free plan: $0, 20 live calls/month). Test keys (`fapi_test_...`) return fixture data and never count.
2. Look up a code: `curl https://api.firmsapi.com/v1/firms/E430 -H "x-api-key: $FIRMSAPI_KEY"` returns `data.name`, `data.status` (`active` or `deleted`), `data.type`, `data.address`, `data.port` and `data.same_address` (other codes at the same address), plus `meta.data_as_of`. A code that is not on the list returns `404 not_found`.
3. Find the code for a facility name or address: `GET /v1/search?q=maher+terminal+elizabeth` returns ranked, typo-tolerant matches with a 0-100 `score` (optional filters: `state`, `port`, `type`).
4. Check a code before filing: `POST /v1/validate` with `{"code": "E430", "port": "4601", "use": "warehouse_entry"}` returns `valid`, `checks_passed`, `checks_failed`, `checks_skipped` and `checks_not_possible`. Its `exists`, `active` and `port` checks map to 158, 159 and 164, the rejects CBP lists for truck in-bond arrivals; other transactions use other error numbers ([ACE errors by transaction](https://firmsapi.com/guides/ace-firms-code-errors/)). A passing result is not ACE acceptance, and bond status is not in the FIRMS list, so confirm it in ACE.
5. Machine-readable contract: the OpenAPI 3.1.0 spec at https://docs.firmsapi.com/openapi.json.

## Start here

- [FIRMS codes explained](https://docs.firmsapi.com/concepts/firms-codes/): What a FIRMS code is, the facility types, deleted and junk codes, and how to validate the format.
- [FIRMSapi docs](https://docs.firmsapi.com/): FIRMSapi REST API docs: look up, search and validate U.S. CBP FIRMS codes. Quickstart, endpoint guides, OpenAPI reference and changelog.
- [Use FIRMSapi from AI agents (MCP)](https://docs.firmsapi.com/mcp/): Connect Claude, Cursor, the OpenAI API and other MCP clients to the FIRMSapi MCP server to look up, search and validate CBP FIRMS codes with your API key.
- [Plans and limits](https://docs.firmsapi.com/plans/): Monthly quotas, call packs, metered overage, and what counts as a call.
- [Quickstart](https://docs.firmsapi.com/quickstart/): Make your first FIRMSapi call with a test key, then switch to a live key.

## API

- [Batch](https://docs.firmsapi.com/api/batch/): POST /v1/batch runs up to 100 lookups, validations and searches in one request (Pro and Enterprise).
- [Changes feed](https://docs.firmsapi.com/api/changes/): GET /v1/changes lists codes added, removed, updated or with a status change in the CBP FIRMS list (Pro and Enterprise).
- [Errors](https://docs.firmsapi.com/api/errors/): The FIRMSapi error JSON shape and every error code with its HTTP status: missing_api_key, plan_required, invalid_request, not_found, quota_exceeded and more.
- [Look up a code](https://docs.firmsapi.com/api/lookup/): GET /v1/firms/{code} returns a FIRMS facility, deleted and placeholder codes included, plus the other codes at the same address.
- [Ports](https://docs.firmsapi.com/api/ports/): GET /v1/ports lists CBP ports with FIRMS codes; GET /v1/ports/{port} returns one port and its facilities.
- [Search, autocomplete and nearby](https://docs.firmsapi.com/api/search/): GET /v1/search, /v1/autocomplete and /v1/nearby: find FIRMS codes by facility name, street address, name prefix, or distance from a point, facility or address.
- [Usage and quotas](https://docs.firmsapi.com/api/usage/): What counts as a call, the order calls are drawn from your plan, call packs and metered overage, and quota headers.
- [Validate before you file](https://docs.firmsapi.com/api/validate/): POST /v1/validate runs pre-filing checks on a FIRMS code for your port and intended use.
- [Watchlists](https://docs.firmsapi.com/api/watchlists/): GET, PUT and DELETE /v1/watchlists: keep the list of FIRMS codes your product depends on (Enterprise). Webhook notifications are not available yet.

## AI agents (MCP)

- MCP server: https://api.firmsapi.com/mcp (Streamable HTTP, stateless). Send the same API key in the `x-api-key` header, or as `Authorization: Bearer <key>`. Setup for Claude, Cursor and the OpenAI API: [Use FIRMSapi from AI agents](https://docs.firmsapi.com/mcp/)
- Tools: `lookup_firms_code`, `search_firms_facilities`, `find_nearby_firms_facilities`, `validate_firms_code`, `list_cbp_ports`, `get_cbp_port`. Each wraps one REST endpoint and counts exactly like it; test keys return fixture data and never count.
- FIRMSapi has no connection to ACE: a passing validation is not ACE acceptance. Webhooks are not available.

## API reference (generated from the OpenAPI spec)

- [OpenAPI 3.1.0 spec (JSON)](https://docs.firmsapi.com/openapi.json): the whole contract, for client generators and tools
- `GET /v1/firms/{code}`: Look up a FIRMS code. [Reference](https://docs.firmsapi.com/reference/operations/getfacility/)
- `GET /v1/ports/{port}`: Get a port and its facilities. [Reference](https://docs.firmsapi.com/reference/operations/getport/)
- `GET /v1/watchlists/{code}`: Get a watched code (Enterprise). [Reference](https://docs.firmsapi.com/reference/operations/getwatch/)
- `PUT /v1/watchlists/{code}`: Watch a code (Enterprise). [Reference](https://docs.firmsapi.com/reference/operations/putwatch/)
- `DELETE /v1/watchlists/{code}`: Stop watching a code (Enterprise). [Reference](https://docs.firmsapi.com/reference/operations/deletewatch/)
- `GET /v1/search`: Search facilities. [Reference](https://docs.firmsapi.com/reference/operations/search/)
- `GET /v1/autocomplete`: Autocomplete facility names. [Reference](https://docs.firmsapi.com/reference/operations/autocomplete/)
- `GET /v1/nearby`: Find facilities near a point, a facility or an address. [Reference](https://docs.firmsapi.com/reference/operations/nearby/)
- `POST /v1/validate`: Check a FIRMS code before you file. [Reference](https://docs.firmsapi.com/reference/operations/validate/)
- `POST /v1/batch`: Run up to 100 lookups, validations and searches (Pro and Enterprise). [Reference](https://docs.firmsapi.com/reference/operations/batch/)
- `GET /v1/ports`: List CBP ports. [Reference](https://docs.firmsapi.com/reference/operations/listports/)
- `GET /v1/changes`: Feed of FIRMS list changes (Pro and Enterprise). [Reference](https://docs.firmsapi.com/reference/operations/listchanges/)
- `GET /v1/watchlists`: List watched codes (Enterprise). [Reference](https://docs.firmsapi.com/reference/operations/listwatchlist/)

## Limits and counting

- Base URL https://api.firmsapi.com/v1; send the key in the `x-api-key` header.
- `POST /v1/batch` takes up to 100 requests; each counts as one call, and the batch is counted up front.
- Search returns up to 50 results per request.
- Nearby searches up to 100 km.
- Counted: live-key answers, including failed validations (`valid: false`) and `404 not_found`.
- Not counted: test keys, `400 invalid_request`, auth and plan errors, `429`, `5xx`, autocomplete, and adding or removing watchlist codes.
- Monthly calls come from the plan quota, then call packs, then capped metered overage (paid plans); after that, `429 quota_exceeded`.

## Plans

- Free: $0/month, 20 live calls/month
- Pro: $50/month, 200 live calls/month; Batch lookups and validation, Changes feed
- Enterprise: $200/month, 2,000 live calls/month; Batch lookups and validation, Changes feed, Watchlists
- Call packs (any plan, one-time): 100 calls for $25
- Metered overage (paid plans, opt-in, with a monthly cap you set): $0.25 per call
- Test keys (`fapi_test_...`) return fixture data and never count. Details: https://firmsapi.com/pricing/

## More

- [Changelog](https://docs.firmsapi.com/changelog/)

## Optional

- [Full docs as plain text](https://docs.firmsapi.com/llms-full.txt)
- [FIRMSapi home](https://firmsapi.com/llms.txt), with the [guides](https://firmsapi.com/guides/) and [their full text](https://firmsapi.com/llms-full.txt)