API Reference

Authentication

Every request requires your API key as a Bearer token in the Authorization header. Generate keys from your dashboard → API Keys.

curl "https://firml.ink/search?name=Apple+Inc" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

Keys are prefixed fl_live_. Keep them secret — rotate immediately if compromised.

Tiers & Limits

Results per search and monthly caps vary by plan. Upgrade anytime in Plans & Billing.

Tier	Results per search	Monthly searches
Trial	5	5 total
Individual	25	2,000
Pro	100	Unlimited

Quick Start

Search any U.S. business entity in three lines of code.

curl "https://firml.ink/search?name=Apple+Inc&state=FL" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

import requests

resp = requests.get(
    "https://firml.ink/search",
    params={"name": "Apple Inc", "state": "FL"},
    headers={"Authorization": "Bearer fl_live_xxxxxxxxxxxx"},
)
data = resp.json()
print(data["results"])

const res = await fetch(
  "https://firml.ink/search?name=Apple+Inc&state=FL",
  { headers: { Authorization: "Bearer fl_live_xxxxxxxxxxxx" } }
);
const data = await res.json();
console.log(data.results);

GET

/search

Search entities by name, registered agent, address, state, or status. At least one of name, agent, or address is required.

Parameter	Type	Required	Description
name	string	optional	Full-text entity name search
agent	string	optional	Registered agent name (partial match)
address	string	optional	Principal address (partial match)
state	string	optional	2-letter state code (e.g. `FL`, `TX`)
status	string	optional	Entity status — `active`, `inactive`
page	integer	optional	Page number, default `1`

Example request

curl "https://firml.ink/search?name=Sunshine+Realty&state=FL" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

Example response

{
  "page": 1,
  "per_page": 25,
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "SUNSHINE REALTY GROUP LLC",
      "state": "FL",
      "status": "active",
      "entity_type": "LLC"
    },
    {
      "id": "8d2a9b3c-1e4f-47da-a9c2-5e8f0d1b2c3a",
      "name": "SUNSHINE REALTY PARTNERS INC",
      "state": "FL",
      "status": "active",
      "entity_type": "CORP"
    }
  ]
}

GET

/entity/{entity_id}

Full detail for a single entity by its UUID. Returns all available fields including registered agent, principal address, and filing metadata.

Parameter	Type	Required	Description
entity_id	UUID	required	Entity UUID (from `/search`)

Example request

curl "https://firml.ink/entity/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "SUNSHINE REALTY GROUP LLC",
  "source_state": "FL",
  "status": "active",
  "entity_type": "LLC",
  "filing_date": "2019-03-15",
  "principal_address": {
    "street": "1200 Brickell Ave",
    "city": "Miami",
    "state": "FL",
    "zip": "33131"
  },
  "registered_agent": {
    "name": "CORPORATE CREATIONS NETWORK INC",
    "address": "11380 Prosperity Farms Rd, Palm Beach Gardens, FL 33410"
  }
}

GET

/entity/{entity_id}/officers

Returns all officers, directors, and managers on record for a given entity. Useful for ownership research and due diligence.

Parameter	Type	Required	Description
entity_id	UUID	required	Entity UUID

Example request

curl "https://firml.ink/entity/3fa85f64-5717-4562-b3fc-2c963f66afa6/officers" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

Example response

[
  {
    "id": 10482,
    "name": "JAMES MICHAEL THORNTON",
    "first_name": "JAMES",
    "last_name": "THORNTON",
    "middle_initial": "M",
    "title": "REGISTERED AGENT",
    "officer_type": "RA",
    "address": "1200 Brickell Ave",
    "city": "Miami",
    "state_addr": "FL",
    "zip": "33131"
  },
  {
    "id": 10483,
    "name": "SARAH ELIZABETH CHEN",
    "first_name": "SARAH",
    "last_name": "CHEN",
    "middle_initial": "E",
    "title": "MANAGER",
    "officer_type": "MGR",
    "address": "1200 Brickell Ave",
    "city": "Miami",
    "state_addr": "FL",
    "zip": "33131"
  }
]

GET

/officers/search

Search officers across all states by last name or title. At least one of name or title is required.

Parameter	Type	Required	Description
name	string	optional	Last name (case-insensitive partial match)
title	string	optional	Officer title — e.g. `MANAGER`, `PRESIDENT`
state	string	optional	2-letter entity state code
page	integer	optional	Page number, default `1`

Example request

curl "https://firml.ink/officers/search?name=Johnson&state=TX" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

Example response

{
  "page": 1,
  "per_page": 25,
  "results": [
    {
      "officer_id": 58271,
      "entity_id": "7c4e1f2a-9b3d-4e6f-a1c2-8d5e0f3b9a7c",
      "name": "ROBERT ALLEN JOHNSON",
      "first_name": "ROBERT",
      "last_name": "JOHNSON",
      "title": "PRESIDENT",
      "officer_type": "OFF",
      "city": "Austin",
      "state_addr": "TX",
      "entity_state": "TX"
    }
  ]
}

GET

/states

Returns all U.S. states currently indexed in the FirmLink database. Use the code field as the state filter in other endpoints.

No query parameters required. Authentication still required.

Example request

curl "https://firml.ink/states" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

Example response

[
  { "code": "FL", "name": "Florida",  "last_ingested_at": null },
  { "code": "CO", "name": "Colorado", "last_ingested_at": null },
  { "code": "NY", "name": "New York", "last_ingested_at": null },
  { "code": "TX", "name": "Texas",    "last_ingested_at": null }
]

GET

/address/{address}

Look up all entities registered at a given address. The address is normalized before matching, so minor formatting differences are handled automatically.

Parameter	Type	Required	Description
address	string	required	Street address — URL-encoded path segment

Example request

curl "https://firml.ink/address/1200%20Brickell%20Ave%20Miami%20FL" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

Example response

{
  "address": "1200 Brickell Ave Miami FL",
  "entities": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "SUNSHINE REALTY GROUP LLC",
      "state": "FL"
    },
    {
      "id": "9b1c4d2e-7f8a-4b5c-a3d6-0e2f1c8b7a9d",
      "name": "BRICKELL CAPITAL PARTNERS LLC",
      "state": "FL"
    }
  ]
}

GET

/agent/{name}

Find all entities whose registered agent matches the given name. Uses full-text search, so common stop words and variations are handled automatically.

Parameter	Type	Required	Description
name	string	required	Registered agent name — URL-encoded path segment

Example request

curl "https://firml.ink/agent/Corporate%20Creations%20Network" \
  -H "Authorization: Bearer fl_live_xxxxxxxxxxxx"

Example response

{
  "name": "Corporate Creations Network",
  "entities": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "SUNSHINE REALTY GROUP LLC",
      "state": "FL"
    },
    {
      "id": "4cb7e3f1-8a2b-4d5e-b6c9-1f3a2d4e5c6b",
      "name": "MIAMI TECH VENTURES INC",
      "state": "FL"
    }
  ]
}

Error Responses

All errors return JSON with a detail field describing the problem.

401

Unauthorized

Missing or invalid API key. Check your Authorization header.

{"detail": "Not authenticated"}

403

Forbidden — Quota Exceeded

You've hit your monthly search limit. Upgrade in Plans & Billing.

{"detail": "Monthly search quota exceeded"}

422

Unprocessable Entity

A required parameter is missing or invalid. See each endpoint's parameter table.

{"detail": "At least one of name, agent, or address is required"}

404

Not Found

The requested entity UUID does not exist in the database.

{"detail": "Entity not found"}

Authentication

Tiers & Limits

Quick Start

/search

Example request

Example response

/entity/{entity_id}

Example request

Example response

/entity/{entity_id}/officers

Example request

Example response

/officers/search

Example request

Example response

/states

Example request

Example response

/address/{address}

Example request

Example response

/agent/{name}

Example request

Example response

Error Responses

Ready to integrate?