prism

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.

get/prism/find-accounts

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

namestring required

The person's or the company's name, 2 to 120 characters.

type'person' | 'company'

person (default) or company. Sets the default platforms and the LinkedIn search used.

platformsstring

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.

employerstring

Optional current employer of the person, used only as context for the judgment (type=person only).

locationstring

Optional city or country, used only as context for the judgment.

websitestring

Optional official website or domain (e.g. ogilvy.com). A platform-verified account linking to it is taken as the match without judging.

candidatesinteger

Accounts judged per platform, 1 to 5 (default 5), taken from the top of each search.

profile_checkboolean

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

Cache-Controlstring

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.

Idempotency-Keystring

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

successboolean required

Whether the request succeeded

platformstring required

Platform name

endpointstring required

API endpoint path

credits_usedinteger required

Number of credits consumed

credits_remaininginteger nullable required

Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.

request_idstring required

Unique request identifier for support

cachedboolean required

Whether the response was served from cache

idempotent_replayboolean

True only when this response is an idempotency replay

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.