Turn a person's or a company's name into ranked candidate accounts on Instagram, TikTok, X and LinkedIn (Threads on request), with a match level and a match confidence per platform, for human review.
Runs the existing account searches for name on each platform (instagram/search/profiles, tiktok/search/users, twitter/search/users, and linkedin/search/people for a person or linkedin/search/companies for a company), keeps the top candidates public accounts of each (private accounts are dropped), and ranks them. Each platform returns candidates (rank, handle, display name, profile URL, followers, verified flag, a bio excerpt and choice_probability, the judged probability that this account is the target's own) and one match: handle is the leading candidate, level is same, possible (connected but not shown to be the target's own, such as a fan or regional account), different, uncertain (the ranking was flat or the check was unsure), or none (none of the candidates is the target's own account, or the search found nothing), with confidence (the weaker of the ranking and the check), basis and evidence (website_match, cross_link, bio_consistent, fan_or_parody). The leading candidate is always checked a second time against the name and context you sent; a ranking alone is never a match. With website, an account that links to that site and is platform-verified is taken as the match without judging (basis: exact_link); an unverified account linking to it is judged like the rest. employer (person only) and location give the judgment context. These are automated labels for a human reviewer, not an identification: automated_decision is false and the response never states who runs an account. If the judgment is unavailable, candidates come back in search order with match.level null, _warnings says why, and the judging credits are refunded. LinkedIn is included by default for a company only, because its search costs 10 credits. Threads (threads/search/users) is searched only when named in platforms. Each platform's match also carries match_confidence (0 to 1, null when there is no candidate), how sure the response is that handle is the target's own account, and accepted, true when match_confidence is at or above match_confidence_floor (0.6). data.items lists the accepted accounts, one per platform at most, as canonical author rows with their match; a platform below the floor lists no item, so a reader of items gets no match rather than a guess. With website, match.evidence adds domain (the site checked), domain_match and domain_source (external_url or bio): whether the leading account's own website, or else a link or a domain in its bio, is that domain or a subdomain of it. The account's own website is the strong evidence: it lifts a flat ranking (uncertain) or a same to at least 0.9. A link or domain in the bio is weaker, because a reseller or a fan names the site too: it lifts only a same, to at least 0.75. An email address at the domain is not a domain match, an own website on another domain overrules the bio, and a possible or different account is never lifted. A profile, link-in-bio or site-builder page given as website (LinkedIn, a Google Site, a link page) is not checked. With profile_check=true, the leading candidate on Instagram, TikTok, Threads and (for a company) LinkedIn, whose search results carry no bio or website, is looked up on its profile before the check, so the domain check and the check read its bio and website; X search results already carry both.
Request
- Base URL: https://www.socialcrawl.dev/v1
- URL: https://www.socialcrawl.dev/v1/prism/find-accounts
- Auth: API key in header x-api-key
Query parameters
The person's or the company's name, 2 to 120 characters.
person (default) or company. Sets the default platforms and the LinkedIn search used.
Comma-separated subset of linkedin, instagram, tiktok, twitter, threads. Default: instagram, tiktok, twitter for a person; linkedin, instagram, tiktok, twitter for a company. Threads is searched only when named. An unknown member is a 400.
Optional current employer of the person, used only as context for the judgment (type=person only).
Optional city or country, used only as context for the judgment.
Optional official website or domain (e.g. ogilvy.com). A platform-verified account linking to it is taken as the match without judging.
Accounts judged per platform, 1 to 5 (default 5), taken from the top of each search.
Optional, default false. When true, the leading candidate on Instagram, TikTok, Threads and (for a company) LinkedIn is looked up on its profile before the check, so the domain check reads its bio and website: 1 credit a lookup (5 for a LinkedIn company page), refunded when it fails.
Headers
Send no-cache to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the no-cache directive triggers this. See the Response Schema guide for details.
Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives 409 IDEMPOTENCY_IN_PROGRESS with a Retry-After of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: credits_used becomes 0, idempotent_replay becomes true, and credits_remaining is refreshed to the current balance. A known current balance appears in both the body and X-Credits-Remaining header; no balance row resolves to 0. On a transient lookup failure, body credits_remaining is null and X-Credits-Remaining is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use Accept: application/json when sending this header. The unsupported key-plus-SSE combination is rejected before billing.
Response
Successful response
Example response
{
"success": true,
"platform": "prism",
"endpoint": "/v1/prism/find-accounts",
"credits_used": 1,
"credits_remaining": 4999,
"request_id": "req-abc123",
"idempotent_replay": true,
"meta": {
"hint": {
"code": "search_multi",
"message": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged.",
"method": "GET",
"path": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube"
}
}
}Changes
No recorded changes to this operation across all 1 revision of this API.