Quickstart

Every request needs an apikey header. The base URL is https://api.savvyiq.ai.

API key

1. Sign up or log in
2. Open API keys in the dashboard and copy your key

# API key format:
S6yS02QKbzUyR4Uyihut2f7qNf2bJBLZQ

1. Resolve a name

Resolution runs real research, so it is asynchronous: the kickoff returns a run_id immediately and the result arrives one to five minutes later. Add location to narrow an ambiguous name and context to say which company you mean. "include": "basis" asks for per-field citations.

curl -X POST 'https://api.savvyiq.ai/v3/entity-resolution/async' \
-H 'apikey: YOUR_API_KEY' \
-H 'content-type: application/json' \
-d '{"name": "Datadog", "location": "New York, NY", "include": "basis"}'

const res = await fetch('https://api.savvyiq.ai/v3/entity-resolution/async', {
method: 'POST',
headers: { apikey: 'YOUR_API_KEY', 'content-type': 'application/json' },
body: JSON.stringify({ name: 'Datadog', location: 'New York, NY', include: 'basis' }),
});
const { run_id } = await res.json();

import requests

res = requests.post(
  'https://api.savvyiq.ai/v3/entity-resolution/async',
  json={'name': 'Datadog', 'location': 'New York, NY', 'include': 'basis'},
  headers={'apikey': 'YOUR_API_KEY'},
)
run_id = res.json()['run_id']

{
  "status": "pending",
  "run_id": "run_344tSxhAVACWbuENINJ9D"
}

2. Poll for the result

Poll with the run_id. 202 means still running, 200 means finished. Repeat include=basis here: the kickoff records the provenance, the poll asks for it in the body. Polls are free and limited to 100 per minute; every 10 seconds is plenty. To skip polling, pass webhook_url on the kickoff instead and the result is delivered to you. See Webhooks.

curl -G 'https://api.savvyiq.ai/v3/runs/run_344tSxhAVACWbuENINJ9D' \
--data-urlencode 'include=basis' \
-H 'apikey: YOUR_API_KEY'

let result;
while (true) {
const res = await fetch(`https://api.savvyiq.ai/v3/runs/${run_id}?include=basis`, {
  headers: { apikey: 'YOUR_API_KEY' },
});
if (res.status === 200) { result = await res.json(); break; }
await new Promise((r) => setTimeout(r, 10_000));
}

import time

while True:
  res = requests.get(
      f'https://api.savvyiq.ai/v3/runs/{run_id}',
      params={'include': 'basis'},
      headers={'apikey': 'YOUR_API_KEY'},
  )
  if res.status_code == 200:
      result = res.json()
      break
  time.sleep(10)

A matched result, trimmed from the reference capture:

{
  "run_id": "run_344tSxhAVACWbuENINJ9D",
  "status": "matched",
  "match_confidence": 100,
  "type": "business",
  "subtype": "incorporated_entity",
  "entity": {
    "id": "siq_33d67jj0wJESjEdFHMhuQ",
    "display_name": "Datadog",
    "legal_name": "DATADOG, INC.",
    "status": "active",
    "website": "https://www.datadoghq.com/",
    "primary_legal_entity": {
      "id": "le_2Zp3Yy6S7O6Btccq56WOH",
      "jurisdiction": "US-DE",
      "registration_authority": { "name": "Division of Corporations, Department of State" }
    },
    "identifiers": [
      { "type": "registration_id", "value": "4832851", "jurisdiction": "US-DE" },
      { "type": "cik", "value": "0001561550" },
      { "type": "lei", "value": "549300F6JNO0KRPO1K63" }
    ]
  },
  "candidate": null,
  "factors": [
    { "type": "strength", "code": "registry_identifier_anchored", "impact": "Safe to use for deterministic record matching and deduplication." }
  ],
  "basis": [
    { "field": "legal_name", "citations": [ { "url": "https://datadoghq.com", "source_type": "public_profile", "authority_tier": 2 } ] }
  ]
}

What to read:

• status: "matched" and a non-null entity: a verified record. candidate is populated instead when we could not commit to one. See Understanding API responses.
• entity.id: the stable siq_ ID. Store it; it is the key to every other endpoint.
• primary_legal_entity: the government registration the record is anchored to.
• basis[]: per-field citations, present because you asked for them.

3. Read the record

Fetch the full record by siq_ ID: firmographics, industry codes, operational presence, social profiles. This endpoint never blocks. If the record has not been enriched yet, enrichment.status says building and the build starts in the background; poll until it is complete.

curl 'https://api.savvyiq.ai/v3/entities/siq_33d67jj0wJESjEdFHMhuQ' \
-H 'apikey: YOUR_API_KEY'

const res = await fetch('https://api.savvyiq.ai/v3/entities/siq_33d67jj0wJESjEdFHMhuQ', {
headers: { apikey: 'YOUR_API_KEY' },
});
const record = await res.json();

res = requests.get(
  'https://api.savvyiq.ai/v3/entities/siq_33d67jj0wJESjEdFHMhuQ',
  headers={'apikey': 'YOUR_API_KEY'},
)
record = res.json()

{
  "status": "matched",
  "merged_into": null,
  "entity": {
    "id": "siq_33d67jj0wJESjEdFHMhuQ",
    "display_name": "Datadog",
    "legal_name": "DATADOG, INC.",
    "attributes": { "employee_range": "1K-5K", "revenue_range": "$1B-$10B", "is_public": true, "stock_ticker": "DDOG" },
    "industry": {
      "schemes": {
        "naics_2022": [ { "code": "513210", "label": "Software Publishers", "is_primary": true, "confidence": 95 } ],
        "sic": [ { "code": "7372", "label": "Prepackaged Software", "is_primary": true, "confidence": 95 } ]
      }
    },
    "facets": { "sector": "public", "legal_form": "corporation" },
    "...": "..."
  },
  "enrichment": { "status": "complete", "updated_at": "2026-07-31T19:22:05.042Z" }
}

Starting from a domain

Domain lookups return the operating entity and what we know about the domain itself. A domain we already hold answers in seconds; a new one returns status: "building" and completes in a few minutes. domain accepts a bare domain, a full URL, or an email address.

curl 'https://api.savvyiq.ai/v3/domain-intelligence?domain=datadoghq.com' \
  -H 'apikey: YOUR_API_KEY'

{
  "domain": "datadoghq.com",
  "status": "complete",
  "data": {
    "status": "matched",
    "confidence": 98,
    "entity": { "id": "siq_33GtdRpeJrG8n7orm8iI2", "display_name": "Datadog", "legal_name": "DATADOG, INC." },
    "domain_intelligence": { "tranco_rank": 739, "domain_context": { "domain_type": "corporate_website", "domain_relationship": "direct_owner" } }
  }
}

Complete workflow

const API = 'https://api.savvyiq.ai';
const headers = { apikey: 'YOUR_API_KEY' };

async function resolve(name, location) {
const kick = await fetch(`${API}/v3/entity-resolution/async`, {
  method: 'POST',
  headers: { ...headers, 'content-type': 'application/json' },
  body: JSON.stringify({ name, location, include: 'basis' }),
});
const { run_id } = await kick.json();
while (true) {
  const res = await fetch(`${API}/v3/runs/${run_id}?include=basis`, { headers });
  if (res.status === 200) return res.json();
  await new Promise((r) => setTimeout(r, 10_000));
}
}

const result = await resolve('Datadog', 'New York, NY');
if (!result.entity) throw new Error(`No verified entity: ${result.status}`);
const record = await (await fetch(`${API}/v3/entities/${result.entity.id}`, { headers })).json();
console.log(record.entity.legal_name, record.entity.industry.schemes.naics_2022[0].code);

import time, requests

API = 'https://api.savvyiq.ai'
HEADERS = {'apikey': 'YOUR_API_KEY'}

def resolve(name, location):
  kick = requests.post(f'{API}/v3/entity-resolution/async',
                       json={'name': name, 'location': location, 'include': 'basis'}, headers=HEADERS)
  run_id = kick.json()['run_id']
  while True:
      res = requests.get(f'{API}/v3/runs/{run_id}', params={'include': 'basis'}, headers=HEADERS)
      if res.status_code == 200:
          return res.json()
      time.sleep(10)

result = resolve('Datadog', 'New York, NY')
if not result.get('entity'):
  raise SystemExit(f"No verified entity: {result['status']}")
record = requests.get(f"{API}/v3/entities/{result['entity']['id']}", headers=HEADERS).json()
print(record['entity']['legal_name'], record['entity']['industry']['schemes']['naics_2022'][0]['code'])

Errors

Next steps

• Understanding API responses: entity versus candidate, status, factors and actions
• Webhooks: get results delivered instead of polling
• Batch processing: thousands of names with custom_id
• Handling messy data: names with tax IDs, legal boilerplate, other scripts
• Codes & enums: every status, type, factor and action code