Entity search

Search across legal and master entities

GET /v2/search

View as markdown Open in ChatGPT Open in Claude

Dual-index search that searches both legal entity registrations (200M+ records, exact name matching) and master entity profiles (curated enriched records, fuzzy/phonetic matching) in parallel.

Dual-ID pattern: Every result has an id (always a legal entity ID, le_xxx) and an entity_id (master entity ID, siq_xxx) when the entity has been consolidated into the master graph. Results with a non-null entity_id are enriched profiles sourced from the master entities index and are returned first. Legal-entity-only results (null entity_id) follow.

If entity_id is null, trigger Entity Resolution to create a master record.

Graceful degradation: If the master entities index is temporarily unavailable, the endpoint silently falls back to legal entities only.

Also accepts POST with the same parameters as a JSON body.

Query parameters

namestring required
Entity name to search for (minimum 2 characters)
country_codestring
Filter by ISO country code (e.g., US, GB, CA). Also filters master entities by primary legal entity jurisdiction and headquarters country.
region_codestring
Filter by region/state/province code for US state-level filtering (e.g., CA, NY, DE)
limitinteger
Maximum number of results to return (1–10, default 10)
bypass_cacheboolean
Bypass the response cache and force a fresh query

Responses

200 OK

resultsarray<object>
Array of matching entities. Master entity results (non-null entity_id) are returned first (higher quality curated matches), followed by legal-entity-only results.
Show 6 nested fieldsHide nested fields
- idstring
  Legal entity ID. Always an le_xxx identifier.
- entity_idstring
  Master entity ID (siq_xxx). Non-null when this entity has been consolidated into the master graph. Null for legal-entity-only results.
- namestring
  Entity name
- statusstring
  Current status
- is_branchboolean
  Indicates if this is likely a branch/foreign qualification of another entity
- jurisdictionobject
  Show 3 nested fieldsHide nested fields
  countrystring
  country_codestring
  jurisdiction_codestring
  Combined country/state jurisdiction code (e.g. us_de for Delaware)
metadataobject
Show 3 nested fieldsHide nested fields
- totalinteger
  Total number of results returned
- returnedinteger
  Number of results in this response
- query_time_msinteger
  Query execution time in milliseconds
request_idstring
Unique request identifier

400 Bad Request

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

401 Unauthorized

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

500 Internal Server Error

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

Example request

cURL

curl --request GET \
  --url 'https://api.savvyiq.ai/v2/search?name=Google%20LLC&country_code=US&region_code=DE&limit=10&bypass_cache=false' \
  --header 'apikey: YOUR_API_KEY'

Example response

Entity search results for Google LLC200

{
  "results": [
    {
      "id": "le_2Zp3YaC1I4wgYZpQDPgx8",
      "entity_id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
      "name": "Google",
      "status": "active",
      "is_branch": false,
      "jurisdiction": {
        "country": "United States of America",
        "country_code": "US",
        "jurisdiction_code": "us_de"
      }
    },
    {
      "id": "le_2ZoQ891RD9mDRM1E8bnDf",
      "entity_id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
      "name": "Google LLC",
      "status": "active",
      "is_branch": true,
      "jurisdiction": {
        "country": "United States of America",
        "country_code": "US",
        "jurisdiction_code": "us_sc"
      }
    },
    {
      "id": "le_2ZARUQAF1lba0EhCFyRfl",
      "entity_id": null,
      "name": "GOOGLE LLC",
      "status": "active",
      "is_branch": false,
      "jurisdiction": {
        "country": "United States of America",
        "country_code": "US",
        "jurisdiction_code": "us_ct"
      }
    }
  ],
  "metadata": {
    "total": 5,
    "returned": 5,
    "query_time_ms": 42
  },
  "request_id": "req_31ffecAT4FNPZDDVD1gZw"
}