SavvyIQ
v3 (preview)
You're viewing the v3 (preview) edition of the API. View the current version →

Entity Resolution

Poll a resolution job

GET /v3/jobs/{job_id}

Returns 202 while the job is running and 200 once it finishes. Read-only: polling never starts or repeats work.

Accepts either the job_id or the request_id from the kickoff.

Path parameters

  • job_idstring required
    The job_id or the reqa_ request_id returned by the kickoff.

Query parameters

  • includestring (enum)
    basis
    Set to basis to receive the provenance plane. Required here to get it in the body, and it only works if the kickoff also asked for basis. Provenance is stored with the result, so polling never re-runs research to produce it.

Responses

200 The job finished. A failed resolution is also a `200`, so check `status`.
  • statusstring (enum)
    matchedpartial_matchinconclusiveno_matchnot_foundmergedfailed
  • match_confidenceinteger
    How certain we are this is the entity you asked for.
  • typestring (enum)
    businessnonprofitgovernmentpersonotherunknown
  • subtypestring (enum)
    Show 9 possible valuesHide possible values
    incorporated_entityunincorporated_entitynonprofit_entitygovernment_entitynatural_personcomplex_business_structuretrading_name_onlyother_entityunknown
  • entityobject
    Show 13 nested fieldsHide nested fields
    • idstring
    • display_namestring
      The brand or common name.
    • legal_namestring
      The registered name, as it appears on the government record.
    • statusstring (enum)
      activeinactive
    • descriptionstring
    • websitestring
    • headquartersobject
      The headquarters address, always as the nested address object — there are no flat alias fields. Every key below is always present; unknown values are null rather than omitted, so the key set is stable across responses and endpoints.
      Show 1 nested fieldHide nested fields
      • addressobject
        Show 10 nested fieldsHide nested fields
        • street_addressstring
        • street_numberstring
        • sub_premisestring
        • citystring
        • statestring
          Subdivision as written ("California"), when we hold it.
        • state_codestring
          ISO-3166-2 subdivision code ("CA"). Derived from state when we can map it confidently; null rather than guessed when we cannot.
        • postal_codestring
        • countrystring
        • country_codestring
        • formatted_addressstring
          Single-line rendering of the parts above. Composed from them when we hold no stored formatting.
    • primary_legal_entityobject
      The government registration that anchors this entity.
      Show 5 nested fieldsHide nested fields
      • idstring
      • jurisdictionstring
      • country_codestring
      • state_codestring
      • registration_authorityobject
        The government register this entity is recorded in.
        Show 7 nested fieldsHide nested fields
        • idinteger
        • codestring
        • namestring
        • organizationstring
        • jurisdictionstring
        • country_codestring
        • websitestring
    • identifiersarray<object>
      Typed external identifiers, in a stable order.
      Show 3 nested fieldsHide nested fields
      • typestring (enum)
        registration_idciksec_cikleibiceindunsticker
      • valuestring
        Canonicalized for its type on the resolution and record endpoints. See Codes & enums.
      • jurisdictionstring
        ISO jurisdiction, where the identifier type is jurisdictional. Absent entirely on /v3/domain-intelligence.
    • matching_branchobject
      Set when the query matched a specific branch or foreign registration rather than the entity's home registration.
    • facetsobject
      Ownership and legal form, not industry. Industry codes live under industry.schemes.
      Show 2 nested fieldsHide nested fields
      • sectorstring (enum)
        privatepublicgovernmentnonprofit
      • legal_formstring (enum)
        Show 16 possible valuesHide possible values
        llccorporationc_corps_corplpllpgpsole_proprietorshipnonprofit_corppllcpccooperativemunicipal_agencygovernment_entitytrustunknown
    • industryobject
      Industry codes keyed by scheme. A scheme that was not classified is absent; an empty key is never returned.
      Show 1 nested fieldHide nested fields
      • schemesobject
        Show 2 nested fieldsHide nested fields
        • naics_2022array<object>
          Show 4 nested fieldsHide nested fields
          • codestring
          • labelstring
          • is_primaryboolean
            One code per scheme is primary. Primary codes are returned first.
          • confidenceinteger
        • sicarray<object>
          Show 4 nested fieldsHide nested fields
          • codestring
          • labelstring
          • is_primaryboolean
            One code per scheme is primary. Primary codes are returned first.
          • confidenceinteger
    • parent_entityobject
      Show 1 nested fieldHide nested fields
      • namestring
  • candidateobject
    Our best hypothesis when an entity could not be confirmed. A response populates entity or candidate, never both.
    Show 6 nested fieldsHide nested fields
    • namestring
    • legal_namestring
    • jurisdictionstring
    • statusstring
    • descriptionstring
    • primary_addressobject
      Show 3 nested fieldsHide nested fields
      • full_addressstring
      • state_codestring
      • country_codestring
  • factorsarray<object>
    Show 4 nested fieldsHide nested fields
    • codestring
      Stable code. See Codes & enums.
    • typestring (enum)
      strengthlimitation
    • descriptionstring
    • impactstring
  • actionsarray<object>
    Show 2 nested fieldsHide nested fields
    • codestring
    • descriptionstring
  • merged_intostring
    Set when status is merged. The canonical entity ID to store instead.
  • basisarray<object>
    Present only when the request was made with include=basis.
    Show 4 nested fieldsHide nested fields
    • fieldstring
      Dot-path into entity, for example legal_name, facets.sector, primary_legal_entity.jurisdiction, or identifiers.0.value.
    • confidencestring (enum)
      highmediumlow
    • reasoningstring
    • citationsarray<object>
      Show 4 nested fieldsHide nested fields
      • urlstring
      • excerptstring
      • source_typestring (enum)
        government_registrycompany_websitepublic_profileweb
      • authority_tierinteger (enum)
        123
        1 government registry, 2 public profile, 3 company website or general web.
  • request_idstring
  • metadataobject
    Show 5 nested fieldsHide nested fields
    • queryobject
      The query as we interpreted it.
      Show 5 nested fieldsHide nested fields
      • namestring
      • locationstring
      • contextstring
      • classificationstring
        How we judged the query itself, for example ambiguous when the name alone could match several companies. Useful for deciding whether to retry with more context.
      • modestring
        Internal echo. Always standard on /v3; carried for parity with older surfaces. Do not branch on it.
    • resolved_atstring <date-time>
      When this resolution ran.
    • updated_atstring <date-time>
      When the underlying record was last updated.
    • from_cacheboolean
      Whether the response came from the response cache.
    • cache_hit_typestring
      Which cache served the response, or null when none did.
202 Still running. Poll again.
  • statusstring (enum)
    pending
  • job_idstring
    Job identifier, accepted by GET /v3/jobs/{job_id}.
  • request_idstring
    The reqa_ form of the same job. Also accepted by GET /v3/jobs/{job_id}, and useful as a correlation ID in support requests.
400 Invalid or missing parameters.
  • errorobject
    Show 2 nested fieldsHide nested fields
    • typestring
      Stable, machine-readable error code.
    • messagestring
      Human-readable explanation. Do not match on this.
401 Missing or invalid API key.
  • errorobject
    Show 2 nested fieldsHide nested fields
    • typestring
      Stable, machine-readable error code.
    • messagestring
      Human-readable explanation. Do not match on this.
404 Unknown job ID, or a job belonging to another account.
  • errorobject
    Show 2 nested fieldsHide nested fields
    • typestring
      Stable, machine-readable error code.
    • messagestring
      Human-readable explanation. Do not match on this.
429 Rate limit exceeded.
  • errorobject
    Show 2 nested fieldsHide nested fields
    • typestring
      Stable, machine-readable error code.
    • messagestring
      Human-readable explanation. Do not match on this.
500 Something went wrong on our side.
  • 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/v3/jobs/019fe975-186e-707c-b59a-b0a6c9914221' \
  --header 'apikey: YOUR_API_KEY'

Example response

Datadog resolved by name and location, with include=basis200
{
  "type": "business",
  "basis": [
    {
      "field": "description",
      "citations": [
        {
          "url": "https://www.linkedin.com/company/datadog",
          "excerpt": "Datadog is the essential monitoring platform for cloud applications. We bring together data from servers, containers, databases, and third-party services to make your stack entirely observable. These capabilities help DevOps teams avoid downtime, resolve performance issues, and ensure customers are getting the best user experience.",
          "source_type": "public_profile",
          "authority_tier": 2
        },
        {
          "url": "https://datadoghq.com",
          "excerpt": "Datadog, Inc. provides software solutions. The Company offers cloud-based monitoring and analytics platform which integrates and automates infrastructure monitoring, application performance monitoring, and log management for real-time observability of customers. Datadog operates worldwide.",
          "source_type": "public_profile",
          "authority_tier": 2
        },
        {
          "url": "https://www.crunchbase.com/organization/datadog",
          "excerpt": "Datadog is an observability and security platform that offers infrastructure, applications, software development, and monitoring services. It brings together data from servers, containers, databases, and third-party services to make your stack entirely observable. These capabilities help DevOps teams avoid downtime, resolve performance issues, and ensure customers are getting the best user experience.",
          "source_type": "public_profile",
          "authority_tier": 2
        },
        {
          "url": "https://en.wikipedia.org/wiki/Datadog",
          "excerpt": "Datadog, Inc. is an American company that provides an observability service for cloud-scale applications, providing monitoring of servers, databases, tools, ...",
          "source_type": "web",
          "authority_tier": 3
        },
        {
          "url": "kg:Datadog",
          "excerpt": "Software company",
          "source_type": "web",
          "authority_tier": 3
        },
        {
          "url": "sec-registrant:1561550",
          "excerpt": "SEC EDGAR: \"Datadog, Inc.\" is the registered public-company name (CIK 1561550, ticker DDOG), incorporated in NV, USA. If resolving this registrant, the legal identity and home jurisdiction above are authoritative; a same-name registration in another state is a different entity unless it is this company's own filing.",
          "source_type": "web",
          "authority_tier": 3
        }
      ],
      "reasoning": "Corroborated by the cited public sources below.",
      "confidence": "high"
    },
    {
      "field": "facets.legal_form",
      "citations": [
        {
          "url": "https://corp.delaware.gov/",
          "excerpt": "DATADOG, INC. — Delaware registration 4832851, status ACTIVE",
          "source_type": "government_registry",
          "authority_tier": 1
        }
      ],
      "reasoning": "Mapped from the resolved entity's legal-structure classification.",
      "confidence": "high"
    },
    {
      "field": "facets.sector",
      "citations": [],
      "reasoning": "Public: a public-markets identifier (CIK / ticker) is present on the resolved entity.",
      "confidence": "medium"
    },
    {
      "field": "identifiers.0.value",
      "citations": [
        {
          "url": "https://corp.delaware.gov/",
          "excerpt": "DATADOG, INC. — Delaware registration 4832851, status ACTIVE",
          "source_type": "government_registry",
          "authority_tier": 1
        }
      ],
      "reasoning": "Registration number from the matched government registry record.",
      "confidence": "high"
    },
    {
      "field": "industry",
      "citations": [
        {
          "url": "https://www.linkedin.com/company/datadog",
          "excerpt": "Datadog is the essential monitoring platform for cloud applications. We bring together data from servers, containers, databases, and third-party services to make your stack entirely observable. These capabilities help DevOps teams avoid downtime, resolve performance issues, and ensure customers are getting the best user experience.",
          "source_type": "public_profile",
          "authority_tier": 2
        },
        {
          "url": "https://datadoghq.com",
          "excerpt": "Datadog, Inc. provides software solutions. The Company offers cloud-based monitoring and analytics platform which integrates and automates infrastructure monitoring, application performance monitoring, and log management for real-time observability of customers. Datadog operates worldwide.",
          "source_type": "public_profile",
          "authority_tier": 2
        },
        {
          "url": "https://www.crunchbase.com/organization/datadog",
          "excerpt": "Datadog is an observability and security platform that offers infrastructure, applications, software development, and monitoring services. It brings together data from servers, containers, databases, and third-party services to make your stack entirely observable. These capabilities help DevOps teams avoid downtime, resolve performance issues, and ensure customers are getting the best user experience.",
          "source_type": "public_profile",
          "authority_tier": 2
        },
        {
          "url": "https://en.wikipedia.org/wiki/Datadog",
          "excerpt": "Datadog, Inc. is an American company that provides an observability service for cloud-scale applications, providing monitoring of servers, databases, tools, ...",
          "source_type": "web",
          "authority_tier": 3
        },
        {
          "url": "kg:Datadog",
          "excerpt": "Software company",
          "source_type": "web",
          "authority_tier": 3
        },
        {
          "url": "sec-registrant:1561550",
          "excerpt": "SEC EDGAR: \"Datadog, Inc.\" is the registered public-company name (CIK 1561550, ticker DDOG), incorporated in NV, USA. If resolving this registrant, the legal identity and home jurisdiction above are authoritative; a same-name registration in another state is a different entity unless it is this company's own filing.",
          "source_type": "web",
          "authority_tier": 3
        }
      ],
      "reasoning": "Industry classification: NAICS from the cited business activity; SIC (when present) derived from NAICS via crosswalk.",
      "confidence": "medium"
    },
    {
      "field": "legal_name",
      "citations": [
        {
          "url": "https://corp.delaware.gov/",
          "excerpt": "DATADOG, INC. — Delaware registration 4832851, status ACTIVE",
          "source_type": "government_registry",
          "authority_tier": 1
        },
        {
          "url": "https://datadoghq.com",
          "excerpt": "Datadog, Inc. provides software solutions. The Company offers cloud-based monitoring and analytics platform which integrates and automates infrastructure monitoring, application performance monitoring, and log management for real-time observability of customers. Datadog operates worldwide.",
          "source_type": "public_profile",
          "authority_tier": 2
        },
        {
          "url": "https://en.wikipedia.org/wiki/Datadog",
          "excerpt": "Datadog, Inc. is an American company that provides an observability service for cloud-scale applications, providing monitoring of servers, databases, tools, ...",
          "source_type": "web",
          "authority_tier": 3
        },
        {
          "url": "sec-registrant:1561550",
          "excerpt": "SEC EDGAR: \"Datadog, Inc.\" is the registered public-company name (CIK 1561550, ticker DDOG), incorporated in NV, USA. If resolving this registrant, the legal identity and home jurisdiction above are authoritative; a same-name registration in another state is a different entity unless it is this company's own filing.",
          "source_type": "web",
          "authority_tier": 3
        }
      ],
      "reasoning": "Government records provide a clear legal name and jurisdiction. Multiple web sources corroborate the legal name and provide detailed business activity descriptions. The primary legal name 'DATADOG, INC.' is consistently found in authoritative government records with active status. Delaware is identified as the formation jurisdiction in multiple sources. While some SEC filings mention NV, Delaware is more consistently cited as the primary incorporation state in the provided government records. The business activity is well-described across multiple high-confidence web sources. The presence of a branch in Massachusetts is noted.",
      "confidence": "high"
    },
    {
      "field": "primary_legal_entity.jurisdiction",
      "citations": [
        {
          "url": "https://corp.delaware.gov/",
          "excerpt": "DATADOG, INC. — Delaware registration 4832851, status ACTIVE",
          "source_type": "government_registry",
          "authority_tier": 1
        }
      ],
      "reasoning": "Formation jurisdiction from the matched government registry record.",
      "confidence": "high"
    },
    {
      "field": "status",
      "citations": [
        {
          "url": "https://corp.delaware.gov/",
          "excerpt": "DATADOG, INC. — Delaware registration 4832851, status ACTIVE",
          "source_type": "government_registry",
          "authority_tier": 1
        }
      ],
      "reasoning": "Status taken from the matched government registry record.",
      "confidence": "high"
    }
  ],
  "entity": {
    "id": "siq_33d67jj0wJESjEdFHMhuQ",
    "facets": {
      "sector": "public",
      "legal_form": "corporation"
    },
    "status": "active",
    "website": "https://www.datadoghq.com/",
    "industry": {
      "schemes": {
        "sic": [
          {
            "code": "7372",
            "label": "Prepackaged Software",
            "confidence": 95,
            "is_primary": true
          }
        ],
        "naics_2022": [
          {
            "code": "513210",
            "label": "Software Publishers",
            "confidence": 95,
            "is_primary": true
          },
          {
            "code": "541511",
            "label": "Custom Computer Programming Services",
            "confidence": 80,
            "is_primary": false
          },
          {
            "code": "51",
            "label": "Information",
            "confidence": 90,
            "is_primary": false
          }
        ]
      }
    },
    "legal_name": "DATADOG, INC.",
    "description": "Datadog is a leading cloud monitoring and security platform that provides AI-powered observability solutions for cloud-scale applications. Its SaaS-based data analytics platform enables businesses to gain comprehensive visibility into their entire technology stack, from infrastructure to applications, helping DevOps teams prevent downtime, resolve performance issues, and ensure optimal user experience.",
    "identifiers": [
      {
        "type": "registration_id",
        "value": "4832851",
        "jurisdiction": "US-DE"
      },
      {
        "type": "cik",
        "value": "0001561550",
        "jurisdiction": null
      },
      {
        "type": "lei",
        "value": "549300F6JNO0KRPO1K63",
        "jurisdiction": null
      }
    ],
    "display_name": "Datadog",
    "headquarters": {
      "address": {
        "street_address": "620 8th Ave, 45th Floor",
        "street_number": null,
        "sub_premise": null,
        "city": "New York",
        "state": "New York",
        "state_code": "NY",
        "postal_code": "10018",
        "country": "United States",
        "country_code": "US",
        "formatted_address": "620 8th Ave, 45th Floor, New York, New York 10018, United States"
      }
    },
    "matching_branch": null,
    "primary_legal_entity": {
      "id": "le_2Zp3Yy6S7O6Btccq56WOH",
      "state_code": "DE",
      "country_code": "US",
      "jurisdiction": "US-DE",
      "registration_authority": {
        "id": 1024,
        "code": "RA000602",
        "name": "Division of Corporations, Department of State",
        "website": "https://corp.delaware.gov/",
        "country_code": "US",
        "jurisdiction": "Delaware",
        "organization": "Division of Corporations, Department of State"
      }
    }
  },
  "status": "matched",
  "actions": [],
  "factors": [
    {
      "code": "name_exact_match",
      "type": "strength",
      "impact": "Strong identifier for the correct entity.",
      "description": "The name 'Datadog' provided in the query exactly matches the entity's common name."
    },
    {
      "code": "headquarters_match",
      "type": "strength",
      "impact": "Confirms this is the primary legal entity location.",
      "description": "The requested location 'New York, NY' precisely matches the entity's registered headquarters."
    },
    {
      "code": "legal_entity_confirmed",
      "type": "strength",
      "impact": "Confirms a valid legal entity through official sources.",
      "description": "This has been definitively confirmed as the primary legal entity through official registration sources."
    },
    {
      "code": "registry_identifier_anchored",
      "type": "strength",
      "impact": "Safe to use for deterministic record matching and deduplication.",
      "description": "The match is anchored by a stable government registry identifier."
    }
  ],
  "subtype": "incorporated_entity",
  "metadata": {
    "query": {
      "mode": "standard",
      "name": "Datadog",
      "context": null,
      "location": "New York, NY",
      "classification": "specific"
    },
    "from_cache": true,
    "updated_at": "2026-07-31T19:22:05.042Z",
    "cache_hit_type": "exact"
  },
  "candidate": null,
  "request_id": "reqa_344tSxhAVACWbuENINJ9D",
  "match_confidence": 100
}