Endpoints

Company records

Fetch full company records by internal id, or resolve raw domains, LinkedIn URLs and names.

POST/v1/entities/companies

Look up companies by id

Scope: dsp.entities.read

RequestPOST /v1/entities/companies

curl -X POST "https://api.sproutsdata.ai/v1/entities/companies" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "adyen.com",
         "checkout.com"
       ],
       "by": "domain",
       "fields": [
         "account_name",
         "industry",
         "employee_count"
       ]
     }'

Response200

{
  "attribution": [
    {
      "as_of": "2026-10-01T12:00:00Z",
      "domain": "<string>",
      "quote": "<string>",
      "source_corpus": "gtm_index",
      "url": "<string>"
    }
  ],
  "columns": [
    {}
  ],
  "coverage": {
    "audited": false,
    "constraints_unmet": [
      "<string>"
    ],
    "criteria": [
      {}
    ],
    "enumerated": 123,
    "enumeration_recall": 123,
    "linkage": [
      {}
    ],
    "linkage_coverage": 123,
    "linkage_coverage_is_lower_bound": false,
    "similarity": [
      {}
    ],
    "truncated_by": "<string>",
    "universe": 123,
    "universe_exhausted": false,
    "universe_is_exact": true
  },
  "degradation": [
    {
      "detail": "<string>",
      "impact": "recall",
      "reason": "vector_coverage_incomplete",
      "source_corpus": "gtm_index"
    }
  ],
  "has_more": true,
  "meta": {
    "as_of": "2026-10-01T12:00:00Z",
    "credential": "api_key",
    "credits_charged": 123,
    "environment": "live",
    "request_id": "<string>"
  },
  "next_cursor": "<string>",
  "resolved_search": {
    "category": "company",
    "conflicts": [
      {}
    ],
    "filters": {},
    "filters_source": "none",
    "mode": "fast",
    "overrides": [
      {}
    ],
    "parser_version": "<string>",
    "query": "<string>",
    "semantic_query": "<string>",
    "semantic_scope": "company",
    "sort": [
      {}
    ]
  },
  "results": [
    {
      "category": "company",
      "found": true,
      "id": "<string>",
      "matches": [
        {
          "account_name": "<string>",
          "acquired_by": [
            {}
          ],
          "acquisitions": [
            {}
          ],
          "business_classification": "<string>",
          "business_models": [
            "<string>"
          ],
          "city": "<string>",
          "clients": [
            "<string>"
          ],
          "company_keyword": [
            "<string>"
          ],
          "company_types": [
            "<string>"
          ],
          "country": "<string>",
          "department_headcount": {},
          "description": "<string>",
          "domain": "<string>",
          "employee_count": 123,
          "employee_range": {
            "max": 123,
            "min": 123
          },
          "employees_by_country": {},
          "facebook_url": "<string>",
          "founded_year": 123,
          "funding_rounds": [
            {}
          ],
          "funding_stage": "<string>",
          "global_presence": {
            "countries": [
              "<string>"
            ],
            "country_count": 0,
            "hq_country": "<string>"
          },
          "govt_non_govt": "<string>",
          "growth_stage": "<string>",
          "id": "<string>",
          "industry": "<string>",
          "investors": [
            "<string>"
          ],
          "ipo_status": "<string>",
          "job_openings": "<string>",
          "last_funding_amount": 123,
          "last_funding_date": "<string>",
          "latitude": 123,
          "legal_name": "<string>",
          "linkedin_followers": 123,
          "linkedin_url": "<string>",
          "location": "<string>",
          "logo": "<string>",
          "longitude": 123,
          "naics": [
            "<string>"
          ],
          "office_locations": [
            {}
          ],
          "operating_status": "<string>",
          "other_industries": [
            "<string>"
          ],
          "ownership": "<string>",
          "parent_organization": {
            "name": "<string>",
            "type": "<string>"
          },
          "partnerships": [
            "<string>"
          ],
          "postal_code": "<string>",
          "products": [
            {}
          ],
          "profit_non_profit": "<string>",
          "region": [
            "<string>"
          ],
          "revenue": 123,
          "revenue_range": {
            "max": 123,
            "min": 123
          },
          "short_description": "<string>",
          "sic": [
            "<string>"
          ],
          "state": "<string>",
          "street_address": "<string>",
          "sub_industry": "<string>",
          "subsidiaries": [
            {}
          ],
          "suppliers": [
            "<string>"
          ],
          "technology": [
            "<string>"
          ],
          "total_funding": 123,
          "twitter_url": "<string>",
          "website": "<string>"
        }
      ]
    }
  ],
  "suggestion": {
    "category": "company",
    "kind": "search",
    "message": "<string>"
  },
  "total": 123,
  "total_is_estimate": true
}

Shape of a successful response. Values are placeholders.

Use it when you already know which companies you want (by internal id, domain, LinkedIn URL, or name) and need their full records. Outcome: one result per id you sent, in order. Found records sit under matches; misses are reported as found: false with an empty list rather than dropped. Worked use cases: Record Lookup guide.

Two ways to call it, distinguished by by:

`by`	`ids` are
omitted	The platform's own internal (prism) ids
`domain`	Company domains
`li_url`	LinkedIn URLs
`name`	Company names
`auto`	Classified entry by entry (the same detection `/v1/similar` applies to anchors)

The id on a search or similar hit is not an internal id: it is the company's domain or an opaque hash, so it does not resolve with by omitted. Look a hit up by its own fields instead: a company with by: "domain" and its domain, a person (on /v1/entities/persons) with by: "li_url" and its linkedin_url. For documents, see Document records.

Request#

by"auto" | "domain" | "li_url" | "name" | null

When set, ids are raw identifier values instead of prism's internal id: auto classifies each one independently (mirrors the anchor detection /v1/similar uses); any other value forces every entry to that one kind. Omit for the default: ids are prism ids. The id on a search or similar hit is not a prism id (it is the company's domain or an opaque 16-hex hash), so look a hit up by its own fields instead: a company with by: domain and its domain, a person with by: li_url and its linkedin_url.

fieldsarray of string | null

Restrict the returned fields. Omit for the full record.

idsarray of string, ≥ 1, ≤ 1000required

Headers

Idempotency-Keystring

Makes a retry safe. Send a unique value per request and reuse it when you retry that same request: with the same body and credential, on the same UTC day, rows already charged are not charged again.

Idempotency-Key is optional. Send it when you might retry: the same key, on the same request, from the same credential, on the same UTC day is not charged again for records already paid for. See Retries.

Response#

Each results[] row is an EntityHit: the echoed input (id), whether it resolved (found), and the company records under matches — restricted to your fields projection when you sent one, the full record otherwise.

matches is always a list, and for companies it holds at most one record:

A company id or domain is unique by construction, so an id or by: "domain" lookup returns exactly one match and a miss returns none.
by: "name" returns the best-ranked match for each name. A name is not a unique key, so check the record you get back (its domain, for instance) before you rely on it.

The list shape is shared with the document routes, where a name lookup can return several records, so a caller never branches on which route it called.

attributionarray of Attribution

as_ofstring | null

domainstring | null

quotestring | null

RESERVED for per-fact citation. Always null in v1.

source_corpusSourceCorpus

Where content came from. Closed set — it appears in attribution[]. The first four are the GTM entity graph. The rest are the document corpora behind the non-entity categories, each a distinct index with its own refresh cadence — which is the reason they are named separately rather than lumped under one label: attribution[].as_of means nothing if two corpora updated a month apart share a name.

urlstring | null

RESERVED for per-fact citation. Always null in v1.

columnsarray of object | null

The answer table's columns, in order, when a run carries extra columns beyond the entity's own fields -- a job-opening link, a value joined from another dataset. Each entry is {name, description, source}; the value for each sits on every row in results keyed by the column name. Null means a plain entity table. Additive, so it breaks no existing client.

coverageCoverage | null

How much of the addressable set this answer represents. Null means coverage was not measured for this request -- fast and auto do not enumerate -- and never that coverage was zero. Additive, so it breaks no existing client.

auditedbooleandefault: false

Whether the query was checked against the executed filter for dropped requirements. Reported because an empty constraints_unmet only means something if something looked.

constraints_unmetarray of string

Requirements in your query that the search could not express, in your own words. Non-empty means part of the question was not answered -- most often because it needs a dataset this search cannot reach (job postings, employment history, patents, news, funding dates). When this is non-empty, universe_exhausted is withheld: 'we returned everything that matches' cannot be true of a question that was never asked.

criteriaarray of object

Per criterion: evaluated, passed, success_rate, and whether it was *proven* by the query or *judged* by a model. Without this a thin result leaves the caller guessing which requirement thinned it.

enumeratedinteger

How many of them this answer carries. ≥ 0.

enumeration_recallnumber | null

enumerated / universe. Null when the universe was not exact, because a ratio over an estimate is not a recall figure. Note this measures coverage of the *resolved query*, not of the user's intent -- a wrong predicate can be exhaustively enumerated. ≥ 0, ≤ 1.

linkagearray of object

One entry per other dataset this answer joined against: corpus, join_key, observable, of_constrained, ratio, is_lower_bound. ratio is the fraction of your matching accounts that dataset can even see -- measured at 5-60% depending on the dataset and how large the companies are, and never 100%. Non-empty therefore means universe_exhausted is withheld by construction: we returned everything reachable, and a dataset cannot see the rest.

linkage_coveragenumber | null

The joins combined, as a product rather than a minimum: two datasets seeing 27% and 24% of your accounts jointly see about 6.5%, not 24%. Null when no join was performed or when any leg's coverage is unknown.

linkage_coverage_is_lower_boundbooleandefault: false

True when a key set was capped or coverage was estimated rather than measured, making linkage_coverage a floor. Narrowing the question makes it exact.

similarityarray of object

Narrowings done by ranking rather than by predicate. Each entry carries the concept, how many ids it resolved to, the k asked for, whether the list was cut at that ceiling, and the fraction of candidates that could be compared at all. Non-empty means universe_exhausted is withheld on purpose: a cosine is a degree, so a top-k ranking has no complete state, and 2.9% of companies carry no embedding to compare.

truncated_bystring | null

Which limit stopped the enumeration short, when one did.

universeinteger

Records matching the resolved query, counted, not sampled. ≥ 0.

universe_exhaustedbooleandefault: false

Every matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.

universe_is_exactboolean

False when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.

degradationarray of Degradation

detailstring

impact"recall" | "precision" | "freshness" | "fields"

reasonDegradationReason

Why an answer is less than it should be. Closed, because a client that cannot branch on the reason can only show the user a shrug. These are the honest constraints — partial vector coverage, smry mapped as keyword so it cannot be scored lexically, a federated corpus being unreachable — surfaced at runtime instead of in a footnote.

source_corpusSourceCorpus | null

has_moreboolean

metaResponseMeta

Present on every 2xx, including the ones that are not paginated.

as_ofstring

credential"api_key" | "session"default: api_key

Which credential produced this response. session means the dashboard playground ran it as the signed-in user rather than as an API key — so it is billed to the user, subject to interactive rate limits, and carries no integration compatibility guarantee. Additive and defaulted, so it breaks no existing client.

credits_chargednumber | null

What this request cost, in credits, to at most three decimals. 0 when it cost nothing: a Basic or AI search that found nothing, rows this search already paid for (a cursor sent again, or a request repeated with the same Idempotency-Key on the same UTC day), or a test key. A request without a cursor or a repeated key is a new search, so keep the first page rather than asking for it again. null on a free endpoint.

environment"live" | "test"

Echoed on every response so a developer can never mistake a test-key result for a live one.

request_idstring

next_cursorstring | null

Opaque and signed. Invariant: has_more == (next_cursor is not None). There is no page or offset parameter — not accepted, not deprecated, never present.

resolved_searchResolvedSearch | null

categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

conflictsarray of object

filtersFilters

filters_source"caller" | "parser" | "caller+parser" | "none"default: none

mode"fast" | "auto" | "deep"

How hard to work on the query. The distinction is *what the words mean*, not how many results come back: - fast — match my words. The query is matched by meaning (vector retrieval, falling back to keywords where vectors are unavailable); no LLM in the path, so nothing is extracted into filters. - auto — understand my intent. The parser extracts filters. - deep — reason about it. Multi-step, slowest, most expensive. fast was very nearly defined as "filters only, no LLM", which would have made query — the primary parameter — silently inert. A parameter that does nothing is worse than one that is missing.

overridesarray of object

parser_versionstring

querystring | null

semantic_querystring | null

semantic_scope"company" | "person" | null

sortarray of object

resultsarray of EntityHit[CompanyRecord]

categoryEntityCategory

foundboolean

idstring

matchesarray of CompanyRecord

account_namestring | null

acquired_byarray of Deal

amount_usdnumber | null

announced_onstring | null

companystring | null

acquisitionsarray of Deal

amount_usdnumber | null

announced_onstring | null

companystring | null

business_classificationstring | null

business_modelsarray of string

citystring | null

clientsarray of string

company_keywordarray of string

company_typesarray of string

countrystring | null

department_headcountobject | null

descriptionstring | null

domainstring | null

employee_countinteger | null

employee_rangeEmployeeRange | null

maxinteger | null

mininteger | null

employees_by_countryobject | null

facebook_urlstring | null

founded_yearinteger | null

funding_roundsarray of FundingRound

amount_usdnumber | null

announced_onstring | null

investorsarray of string

typestring | null

funding_stagestring | null

global_presenceGlobalPresence | null

countriesarray of string

country_countintegerdefault: 0

hq_countrystring | null

govt_non_govtstring | null

growth_stagestring | null

idstring | null

industrystring | null

investorsarray of string

ipo_statusstring | null

job_openingsstring | integer | null

last_funding_amountnumber | null

last_funding_datestring | null

latitudenumber | null

legal_namestring | null

linkedin_followersinteger | null

linkedin_urlstring | null

locationstring | null

logostring | null

longitudenumber | null

naicsarray of string

office_locationsarray of OfficeLocation

addressstring | null

citystring | null

countrystring | null

operating_statusstring | null

other_industriesarray of string

ownershipstring | null

parent_organizationOrganisation | null

namestring | null

typestring | null

partnershipsarray of string

postal_codestring | null

productsarray of Product

descriptionstring | null

namestring | null

profit_non_profitstring | null

regionarray of string

revenuenumber | null

revenue_rangeRevenueRange | null

maxnumber | null

minnumber | null

short_descriptionstring | null

sicarray of string

statestring | null

street_addressstring | null

sub_industrystring | null

subsidiariesarray of Organisation

namestring | null

typestring | null

suppliersarray of string

technologyarray of string

total_fundingnumber | null

twitter_urlstring | null

websitestring | null

suggestionSearchSuggestion | null

A better way to have asked this question -- a different category (kind: search), or agentic search via POST /v1/agents (kind: agentic). Advisory: these results came from the search that was asked for, whatever this says. Null when there is nothing worth suggesting, which is the common case. Additive, so it breaks no existing client.

categoryEntityCategory | null

The category to search instead. Set iff kind is search.

kind"search" | "agentic"

search — a different category fits. agentic — no single search fits; use POST /v1/agents.

messagestring

One ready-to-show sentence.

totalinteger

≥ 0.

total_is_estimateboolean

Always serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.

Errors#

Status	Code	Summary
401	`auth.unauthorized`	No usable credential (cause deliberately unspecified)
402	`credits.insufficient`	The allocation cannot fund this action
403	`auth.browser_origin`	A secret key was used from a browser
403	`auth.insufficient_scope`	The credential does not hold the required scope
422	`pagination.cursor_invalid`	The cursor could not be read (e.g. a filter changed mid-pagination)
422	`request.invalid`	A field failed validation (`extra.errors` has the detail)
429	`quota.burst_exceeded`	Interactive burst limit hit — wait `Retry-After` seconds
503	`credits.unavailable`	The billing service could not confirm the charge; retry with the same Idempotency-Key
503	`upstream.unavailable`	The retrieval engine is unreachable (not charged)
504	`upstream.timeout`	The retrieval engine did not answer in time (not charged)