API reference

Search people and companies

Filter the graph and page through matches. The endpoint behind list building inside your product.

Planned — not callable yet

POST/api/v1/public/search

One credit per result actually returned. A query that matches nothing is free, and so is a page you never request. A person who has opted out is not returned by any endpoint. The call answers as a no-match and is not billed. There is no flag to include them. NOT CALLABLE YET, for the same reason as person enrichment: a public read of the person graph has no suppression-list coverage today.

Parameters

Name	Type		Description
entity	"person" \| "company"	Required	What the filters describe and what the results are.
filters	object	Required	Field predicates — industry, headcount range, country, title keywords, seniority. Unknown keys are rejected rather than ignored, so a typo fails loudly instead of quietly widening your query.
limit	number	Optional	Results per page, 1–100. Defaults to 25. You are billed for what a page returns, so page deliberately.
cursor	string	Optional	Opaque cursor from a previous response's `next_cursor`. Cursor paging, not offsets — results stay stable while the graph changes underneath you.

Returns

Field	Type	Description
results	array	Matching records, in the same shape the enrich endpoints return.
next_cursor	string \| null	Pass back as `cursor` for the next page. Null on the last page.
credits_charged	number	Credits spent on this page. Equal to the number of results returned.

Example

bash

curl -X POST https://api.truepoint.in/api/v1/public/search \
  -H "Authorization: Bearer $TRUEPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "entity": "company",
        "filters": { "country": "IN", "headcount_min": 50, "industry": "Software" },
        "limit": 25
      }'

json

{
  "results": [
    { "id": "cmp_2b81", "name": "Acme", "domain": "acme.com", "headcount": 312 }
  ],
  "next_cursor": "c2Vhcm5jaDo0Mg",
  "credits_charged": 1
}

Errors

Status	Type	Meaning
422	validation_error	The request failed validation — a missing identifier, or a value we could not parse. 422 rather than 400: the request was well-formed, its contents were not.
401	invalid_token	Missing, malformed, unknown or revoked API key. All four answer identically on purpose — the endpoint must not confirm which keys exist.
403	insufficient_scope	The key is valid but was not minted with the scope this endpoint requires.
402	insufficient_credits	The balance cannot cover this call. Nothing was charged and nothing was returned. Carries `balance` and `required`.
429	rate_limited	Too many requests for this key. Carries `retryAfterSeconds`. Retries are safe and are not billed.
500	internal	Something failed on our side. Nothing was charged. Retry with backoff.