How to Add FIRMS Code Lookup to a TMS

A useful FIRMS integration starts where a user chooses a facility. Your application can help them find a candidate by name, retrieve its record, and review supported checks before continuing with the workflow.

This guide describes the integration sequence. Use the API reference for exact parameters, response fields, and plan limits.

1. Decide where facility selection belongs

Identify the forms where users currently type or paste a FIRMS code. Decide which details they need to choose confidently: facility name, street address, type, status, and registered CBP port.

Show these details together. Two results with similar names may refer to different locations or facility types. Avoid automatically selecting the first search result.

2. Search and let the user select a record

Use search for a submitted query or autocomplete for suggestions as the user types. Debounce autocomplete input, ignore stale responses, and give users a clear way to revise their query when there is no useful match.

Call the API through your backend so production credentials are not exposed in browser code. Follow the documented endpoint limits and error behavior.

3. Retrieve the selected code

Use the lookup endpoint to retrieve the selected record. Display the dataset date where freshness matters to the user’s decision. Distinguish a deleted record from a code that cannot be found.

The lookup endpoint follows this pattern:

curl "https://api.firmsapi.com/v1/firms/E430" \
  -H "x-api-key: $FIRMSAPI_KEY"

This is an illustrative request. Use your own authorized key and consult the quickstart for test fixtures.

4. Check the supported filing context

When your application knows the relevant port and supported intended use, pass them to the validation endpoint. Treat these as explicit inputs; do not infer filing context from the facility’s city.

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

Show failed checks, skipped checks, and checks that are not possible as different outcomes. A result with no failed checks does not mean every possible condition has been verified.

5. Design exception handling

Handle API unavailability and quota errors separately from an invalid facility result. A failed network request should not become “this FIRMS code is invalid.”

Work with the filing team to decide when an issue requires review and how users document that review. In particular, a registered-port mismatch is a reason to investigate; the public dataset does not establish every port exception.

6. Plan for record updates

If your product stores facility details, establish a refresh policy consistent with your agreement and the product documentation. Eligible plans provide a changes feed that lists additions, updates, and deletions since your last sync. Watchlists keep the set of codes you monitor on eligible plans; webhook notifications for watched codes are not available yet.

Decide how a status or address change should appear for existing shipments and saved facilities. Updating a record should not silently rewrite the historical context of a completed transaction.

7. Test before going live

Use fixture-based test keys to exercise supported scenarios. Include a successful lookup, no search results, a deleted record, a failed validation, missing validation inputs, and an API error. Confirm that test and live mode are clearly distinguished in your application.

Start your integration

Read the quickstart, review the API reference, and confirm the usage rules for your plan. If you’re evaluating an integration for multiple customers, discuss your data and volume requirements with the FIRMSapi team.