Look up a FIRMS code

GET

/firms/{code}

const url = 'https://api.firmsapi.com/v1/firms/E430';
const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.firmsapi.com/v1/firms/E430 \
  --header 'x-api-key: <x-api-key>'

Returns the facility, including deleted codes and flagged placeholders, plus the other codes registered at the same address.

Authorizations

apiKey

Parameters

Path Parameters

code

required

Code

4-character FIRMS code.

string

/^[A-Za-z0-9]{4}$/

4-character FIRMS code.

Responses

200

application/json

FacilityResponse

object

data

required

FacilityDetail

object

code

required

Code

4-character FIRMS code.

string

name

required

Name

string

status

required

Status

Deleted codes stay in the data so you can tell why a filing failed.

string

Allowed values: active deleted

type

required

Any of:

FacilityType
null

FacilityType

object

code

required

Code

string

label

required

Label

string

address

required

Address

object

street

required

Any of:

string
null

string

city

required

Any of:

string
null

string

state

required

Any of:

string
null

string

zip

required

Any of:

string
null

string

port

required

Any of:

PortRef
null

PortRef

object

code

required

Code

string

name

required

Any of:

string
null

string

region

required

Any of:

string
null

string

location

required

Any of:

Location
null

Location

object

lat

required

Lat

number

lon

required

Lon

number

quality

required

Any of:

string
null

string

junk

required

Junk

True for “DO NOT USE” placeholders and CBP test records.

boolean

first_seen

required

Any of:

string
null

string

last_changed

required

Any of:

string
null

string

same_address

required

Same Address

Other FIRMS codes at the same physical address.

Array<object>

FacilitySummary

object

code

required

Code

string

name

required

Name

string

status

required

Status

string

Allowed values: active deleted

type

required

Any of:

FacilityType
null

FacilityType

object

code

required

Code

string

label

required

Label

string

city

required

Any of:

string
null

string

state

required

Any of:

string
null

string

port

required

Any of:

string
null

string

warnings

required

Warnings

Array<string>

meta

required

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "data": {
    "code": "E430",
    "name": "MAHER TERMINAL",
    "status": "active",
    "type": {
      "code": "03",
      "label": "Pier or terminal"
    },
    "port": {
      "code": "4601",
      "name": "Newark/Elizabeth"
    },
    "same_address": [
      {
        "status": "active",
        "type": {
          "code": "03",
          "label": "Pier or terminal"
        }
      }
    ]
  },
  "meta": {
    "mode": "live"
  }
}

400

Invalid request (not counted).

application/json

ErrorResponse

object

error

required

ErrorBody

object

code

required

Code

Stable, machine-readable error code.

string

message

required

Message

string

links

required

Links

docs always; billing, buy_pack, upgrade when they help.

object

key

additional properties

string

details

Details

meta

Any of:

Meta
null

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "error": {
    "code": "quota_exceeded"
  },
  "meta": {
    "mode": "live"
  }
}

401

Missing, invalid or revoked API key.

application/json

ErrorResponse

object

error

required

ErrorBody

object

code

required

Code

Stable, machine-readable error code.

string

message

required

Message

string

links

required

Links

docs always; billing, buy_pack, upgrade when they help.

object

key

additional properties

string

details

Details

meta

Any of:

Meta
null

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "error": {
    "code": "quota_exceeded"
  },
  "meta": {
    "mode": "live"
  }
}

404

Not found (counted: it is a lookup result).

application/json

ErrorResponse

object

error

required

ErrorBody

object

code

required

Code

Stable, machine-readable error code.

string

message

required

Message

string

links

required

Links

docs always; billing, buy_pack, upgrade when they help.

object

key

additional properties

string

details

Details

meta

Any of:

Meta
null

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "error": {
    "code": "quota_exceeded"
  },
  "meta": {
    "mode": "live"
  }
}

429

Monthly quota, call packs and overage cap used up (quota_exceeded).

application/json

ErrorResponse

object

error

required

ErrorBody

object

code

required

Code

Stable, machine-readable error code.

string

message

required

Message

string

links

required

Links

docs always; billing, buy_pack, upgrade when they help.

object

key

additional properties

string

details

Details

meta

Any of:

Meta
null

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "error": {
    "code": "quota_exceeded"
  },
  "meta": {
    "mode": "live"
  }
}