Skip to main content

People Search

People search is how a report is created. You describe the person (a name, an @handle, a phone number, and anything else you know), the API searches Instagram, Facebook, TikTok, X (Twitter) and, where enabled, LinkedIn, you choose the accounts that belong to them, and then you confirm the selection to build the report.

note

The older per-network flow (GET /create/{reportId}, POST /create/{reportId}/{source}/search, POST /create/{reportId}/{source}/add) is deprecated and unavailable on production. See Classic search (deprecated).

The flow at a glance​

1. Sign in                          POST /auth/signin
2. Create a report with `fields` POST /create
3. Run a search round POST /people-search/run/{reportId} (repeat to refine)
4. Pick accounts `picked` in the next round
5. Confirm the selection POST /create/{reportId}/confirm
6. Wait for the data GET /sse/{reportId} or GET /check/{reportId}
7. Read the report GET /report/{reportId}

Steps 3 and 4 repeat as often as needed: every round carries the whole context, so the client keeps nothing the server does not keep for it.

Before you start​

Sign in and send Authorization: Bearer <token> on every call (see Authentication). GET /auth/info tells you what this deployment offers:

User fieldMeaning
peopleSearchEnabledtrue when People search is available. A missing field means false.
peopleSearchLinkedinPaneltrue when li (LinkedIn) can be searched and picked as a fifth network. A missing field means false.
ttFollowsEnabledtrue when a TikTok account can be loaded into a report. A missing field means false.

When People search is unavailable every People search call answers 403 {"code":403,"message":"people search is not available"}.

Creating, searching and reading state also work for an unauthenticated (guest) session, but confirming a selection and dropping an account need a signed-in account (401 otherwise). An integration should always sign in first.

1. Create a report: POST /create​

Send the search fields in a fields object. A body without fields is the deprecated classic form.

curl -X POST https://dashboard.socialprofiler.com/api/v1/create \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{
"fields": {
"name": "Jane Doe",
"location": "Austin",
"work": "nurse"
}
}'
# → {"id": "68af01be012b843fd7bc2bf4"}

Save the id: every following call takes it as reportId.

fields keys (all optional, but one of name, username or phone is required):

KeyLimitMeaning
name100Full name. Needs a letter.
username200Up to 3 handles or profile links, comma or space separated; @ optional.
phone40One phone number. See Phone lookups.
location100Free-text place.
state, country64A place level, for example the answer to a refinement question.
info500Anything else, free text.
gender16male or female; anything else is dropped.
language16A language code (pt-BR) or name.
work, interests, life200Free text.
brand100Free text.

Text is normalized before use (invisible and control characters removed, whitespace collapsed), so a pasted invisible character is cleaned, not rejected.

Errors on POST /create:

StatusmessageMeaning
400nothing to search: a name, a username or a phone is requiredNone of name, username, phone is set.
400<code>:<field>, for example input_too_long:/fields/nameA field broke an input rule. Codes: input_too_long, input_empty, input_no_letters, username_too_many_handles, username_bad_handle, phone_bad_format, language_bad, input_invalid. The value is never echoed back.
402to continue please upgrade your subscriptionThe account has no report credits left.
402You have reached search limit. Please Sign up to continue.A guest session used its free searches.
403people search is not availablePeople search is off for this deployment.
413body_too_largeThe body is over 128 KiB.

Creating a report checks the credit but does not spend it; see Credits.

2. Run a search round: POST /people-search/run/{reportId}​

A round searches the networks and returns one ranked panel per network. Every request carries the full context (fields, picked, asked, …); the server stores it on the report so it can be restored later.

curl -X POST https://dashboard.socialprofiler.com/api/v1/people-search/run/$REPORT_ID \
-H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
-d '{
"fields": {"name": "Jane Doe", "location": "Austin", "work": "nurse"}
}'

Request body (fields is required):

KeyMeaning
fieldsThe search fields, as above.
pickedAccounts chosen so far: [{"source": "ig", "id": "…"}]. See Picks.
askedKinds of refinement questions already asked, so they are not asked again (at most 8).
interest_idsInterests the user tapped (at most 32 are kept).
sourcesNetworks to search in this request; default: every searchable network. li only where peopleSearchLinkedinPanel is true, otherwise 400.
textThe line the user typed (up to 600 characters), kept on the report so it can be restored.
fixesThe user's corrections to how text was read (see Parse a typed line).
seed_originThe account a seeded search started from; send it back while that query stands.
round_key, round_sources, stageSending a round in parts and the first look; see below.

The response​

{
"ok": true,
"round": 1,
"order": ["ig", "fb", "tw", "tt"],
"tiers": {"ig": 2, "fb": 3, "tw": 3, "tt": 4},
"panels": {
"ig": {
"ok": true,
"source": "ig",
"tier": 2,
"total": 37,
"results": [
{
"id": "123456789",
"source": "ig",
"username": "janedoe",
"fullname": "Jane Doe",
"image": "https://…",
"link": "https://instagram.com/janedoe",
"pinned": false,
"picked": false,
"matched": ["name", "place"]
}
],
"pins": [],
"basic": false
}
},
"picked": [],
"search_state": {"fields": {"name": "Jane Doe"}, "rounds": 1, "rounds_left": 29, "picked": []}
}
  • order lists the networks with the most useful panel first. li is never first.
  • A panel's tier runs from 1 (a card is pinned) to 4 (empty or failed). total is the number of matches; total_is_lower_bound says it is a floor.
  • results is already ranked; do not re-rank it.
  • A panel that failed has ok: false and an error_code naming the failure class (for example unsupported_network or gateway_unavailable). The other panels are still good.
  • search_state is the context the server holds for the report, including how many rounds were used (rounds) and are left (rounds_left).
  • es_spare (optional) is the number of free full-search slots; a client that defers some networks can send them while it is above 0.

Cards​

A card is the account identity (id, source, username, fullname, image, link) plus what the search knows about its place in this round:

FieldMeaning
badReasonWhy a report cannot be built from the account: unloaded, private, zeroFollows, unmapped, notFound, followsPrivate (TikTok hid the following list; the account itself is not private), optOut. Absent: a report can be built. badReasonConfirmed: true means a loader has already seen the problem.
pinnedThe card was put on top by an exact lookup (@handle, phone) or by the identity graph.
pickedThis is the account the user picked in this network.
matchedNames of the query fields the card matched: name, place, bio, work, interests, gender, age, language, friends, phone, handle. Names only, never values.
confidenceCONFIRMED, SURE or STRONG: how sure the identity graph is that this account belongs to the same person, present only on a card the graph placed. It is a band, never a number: do not show it as a percentage.
seed_originThe account a seeded search started from.
linked_to, lifted_byPresent in a phone-mask search and on a card lifted by a LinkedIn match (see below).

A card with optOut or badReasonConfirmed: true cannot be picked. A TikTok card with any badReason cannot be picked while ttFollowsEnabled is false.

Refinement questions​

A panel may carry one question: {kind, question, options: [{value, label}]}. The option with a null value is "not sure". Put the answer into the matching fields key (for a place question, state or country), add the question's kind to asked, and run another round.

Refinement rounds are free but capped per report: when the cap is reached the call answers 429 too many refinements for this report (rounds_left in search_state shows how many remain). A client that sends rounds too fast gets 429 too many people search requests, slow down; wait for Retry-After.

Rounds in parts (round_key)​

To fill the first network's tab without waiting for the slowest network, send one request per network, in parallel, all with the same round_key (a UUID you mint for each round, 8 to 64 characters of A-Z a-z 0-9 _ -):

{
"fields": {"name": "Jane Doe"},
"round_key": "0b1f6a7e-6e3a-4c5b-9c1c-3a1d7f2b8a10",
"round_sources": ["ig", "fb", "tw", "tt"],
"sources": ["ig"]
}
  • All parts with one key are one round: one count against the refinement cap, one stored state.
  • sources of a part must be among the round's round_sources, otherwise 400.
  • The first part to arrive fixes the round's query; later parts search that query for their own networks, whatever their own body says.
  • A part's answer lists pending: the networks of the round that have no panel yet.
  • A part of a round that has already ended changes nothing and answers superseded: true with no panels.
  • A network that has not answered yet can still be sent later (for example when its tab is opened) for a while after the round started.
  • A part answers 503 for its own networks if the search service is unavailable; the round is given back (not counted) only if none of its networks answered.

First look (stage: "quick")​

Beside each full part you may send a quick request with the same round_key, sources and body: "stage": "quick". It returns up to about 50 cards in a few seconds, for the people whose full name contains the whole typed name, with no question. Show those panels while the full answer is on its way, and replace them with it, never merge.

  • A first look needs a round_key (400 stage quick needs a round_key otherwise).
  • It is not a part of the round: it counts nothing, stores no state and is never pending. Its panels carry stage: "quick".
  • It may return no panels (panels is {}): nothing to preview, for example no name, or a phone lookup.
  • Its cards are accounts the report has shown, so they can be picked.
  • A first look that fails costs nothing; ignore it and wait for the full part.

3. Read the state: GET /people-search/state/{reportId}​

Restores the last search of a report: its panels and search_state. Use it after a reload.

  • stale: true means the stored panels expired: run the search again with the returned search_state.
  • When the last round was sent in parts and can still be resumed, the answer has round_key and pending. Ask the pending networks again with that key; that is not a new round.
  • 429 means too many restores from this client; honour Retry-After.
  • 400 means the report was not made by People search.

4. Pick accounts​

A pick says "this account is them". Send picks in picked of the next round:

{
"fields": {"name": "Jane Doe"},
"picked": [{"source": "ig", "id": "123456789"}]
}
  • Up to 3 accounts per network, up to 15 in total; they keep the order you send. A fourth account in one network is 400 too_many_picks.
  • A pick pins the accounts the identity graph ties to it on top of the other networks' panels (pinned: true, with a confidence band). The reason is never sent.
  • A pick must be an account the report has shown (a card, an account you resolved by hand, a seed origin); otherwise 404.
  • An opted-out account cannot be picked: 422 with a message starting opted_out.
  • A LinkedIn card (li) can be picked where peopleSearchLinkedinPanel is true. Its graph partners are pinned too, but a LinkedIn account is never a report subject.

Seed a search from a card: POST /people-search/seed/{reportId}​

"Find their other accounts": a fresh round seeded from one result card.

{"source": "ig", "id": "123456789", "pick": true}

The server reads the card and fills search_state.fields itself (name, place, interests, gender, language), drops the previous picks and questions, and marks the card seed_origin. pick: true also keeps the card as the pick of its network. The body also accepts sources, round_key, round_sources, stage and from_report (the report the card was shown in, when the seeded search is a new report). It counts as a refinement round. Errors: 404 (a card the report never showed, or an account the index does not hold), 422 (the card has no name to search by), 429, 503.

Give an exact account: POST /people-search/account/{reportId}​

The user knows one account exactly ("their Instagram is @this"):

{"source": "ig", "handle": "janedoe"}

The answer has status (exact, renamed, loaded, unknown, error) and, when found, a card. No round is spent: send card.id in picked of the next round. loaded means the account was read from the network on demand (Instagram, Facebook, X). li is 400; a LinkedIn profile is given by its link (below). A phone lookup answers 403.

Look a handle up everywhere: POST /people-search/lookup/handle​

{"handle": "janedoe", "sources": ["ig", "fb", "tw", "tt"]}

Returns by_source: per network a status (exact, renamed, id_only, fuzzy, unknown, error) and a card or candidates. It needs no report and spends no quota. sources never contains li.

Parse a typed line: POST /people-search/parse​

{"text": "Jane Doe nurse Austin @janedoe"} reads one line into fields. The answer has fields, ready (false while there is no name, handle or phone), reading (which part of the line became what), questions to ask before searching, and linkedin (LinkedIn links found in the line). Send the user's corrections in fixes ({start, end, tag}; tag: "O" means "not a fact") and repeat the call. 503 means the parse service is unavailable.

LinkedIn by link: POST /people-search/linkedin/{reportId}​

{"url": "https://www.linkedin.com/in/jane-doe-1a2b3c"}

The profile is looked up in our LinkedIn database and the answer gives a name (and often a place) to search by. Write fullname, location, state and country into fields and run a round.

statusMeaning
indexOur database holds the profile. Its name and place are used, and it becomes the origin of the search: later rounds pin the accounts the identity graph ties to it.
slugThe profile is not in our database; the name is what the link spells. No origin.
profileThe profile was read directly (used only when the lookup service could not be asked).

fullname is empty when nothing gives a name: ask the user. A link that is not linkedin.com/in/<name> is 400. No round is spent. The LinkedIn origin and a LinkedIn pick are never the subject of the report.

Other accounts of a profile: GET /people-search/matches/{source}/{profileId}​

Query: report (required; the report whose results showed the profile), limit, min_p (a floor between 0 and 1). Returns matches: {source, id, name, username, link, image} for other accounts of the same person. A match says nothing about how it was decided. 403 for a phone lookup (masked results), 404 if the profile is not one of the report's cards.

History: GET /people-search/history​

Lists the caller's searches, newest first (limit up to 100, default 50). Each item has id, label, sub, created, generated, confirmed, phoneOrigin, fields and picked.

5. Confirm: POST /create/{reportId}/confirm​

Confirm locks the selection and starts loading what the report needs. A signed-in account is required. The body is the array of accounts to build the report from:

curl -X POST https://dashboard.socialprofiler.com/api/v1/create/$REPORT_ID/confirm \
-H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
-d '[{"source": "ig", "id": "123456789"}, {"source": "fb", "id": "987654321"}]'

Rules:

  • The report is built from one account per network: the first account of a network in the body is its subject. The others are kept as the report's "selected" accounts.
  • At most 3 accounts per network (400 too_many_picks) and 160 in all.
  • LinkedIn accounts may be in the body; they are never subjects and come back in not_in_report. A selection of LinkedIn accounts only is 422 linkedin_only: nothing is confirmed or charged, ask the user for an Instagram, Facebook, TikTok or X account.
  • An opted-out account anywhere in the body is 422 (opted_out: …); nothing is confirmed.
  • An account the report never showed is 404.
  • ?no_subject=ig&no_subject=tw lists networks the user deliberately left without a subject. Their accounts stay on the selection and none is loaded. A confirm that leaves no subject at all is 400.
  • A repeat confirm is 409 report profiles were already confirmed, unless the confirm was undone with drop.
  • 503 gateway_unavailable (with Retry-After): the search service could not answer. Nothing was confirmed or charged; ask again.

Response:

{
"estimatedTime": 240,
"loadTimeout": 150,
"loads": [
{"type": "follows", "status": "inprogress", "id": "123456789", "source": "ig"}
],
"not_in_report": []
}
  • estimatedTime and loadTimeout are in seconds. estimatedTime: 0 means nothing is left to wait for and the report can be opened now.
  • loads has one entry per confirmed account that cannot be used yet: inited / inprogress (its data is loading; the outcome arrives on the SSE stream as a follows event), done, or error with the reason in error (an account the report cannot be built from: remove it with drop and confirm again).
  • not_in_report lists the confirmed LinkedIn accounts.

Confirming does not spend a report credit.

Undo a confirm or remove an account: POST /people-search/drop/{reportId}​

{"source": "tt", "id": "5550001"}

Takes an account out of the report: for example one whose load failed with error. Needs a signed-in account.

  • id removes only that account from a network that keeps another pick. Without id (or when it is the network's only account) the whole network leaves.
  • After a confirm, a drop that leaves the network another account, or removes the last account, reopens the search (reopened: true): confirm again with the accounts you want.
  • {"source": "ig", "keep": true} undoes the confirm and removes nothing, for a user who moves the subject of a network after confirming.
  • The answer is {source, confirmed, remaining, reopened}.
  • No round is spent, nothing is searched, and repeating the call is harmless.
  • A report can be confirmed up to 5 times; a drop that would reopen it past that is 422 confirm_limit: start a new search.
  • Errors: 400 for li (a LinkedIn pick is never in the report; un-pick it) or a report not made by People search, 401 without a signed-in account, 403 when the report is already built or is a phone lookup, 404, 429.

6. After confirm​

From here the flow is the same for every report: follow the progress with SSE or GET /check/{reportId}, then read the report. See the Report Pipeline.

Phone lookups​

A full phone number in fields.phone, whether at create or in any later round, turns the report into a phone lookup for good (it is never undone, even if the number is removed later):

  • Only the number is searched. A name and facts sent with it stay on the report but are not searched, and no picks are applied.
  • Results are masked from that round on: panels have blurred: true, names are cut to their first letters, username and link are empty and image is blurred. The paywall applies: the real identity shows only on the report page of an account entitled to it.
  • A phone lookup is of one number. A round with another full number is 409 this report is a phone lookup of another number: a new number is a new search. Create a new report instead.
  • The routes that read a single account (matches, seed, account, linkedin, drop) answer 403 not available for a phone lookup: its results are masked.
  • Confirm the whole answer: a phone lookup keeps every account it found.
  • The last digits alone are not a phone number; they are dropped and never mask anything.
  • 403 phone search is not available from this entry point means phone search is turned off for this entry point.

When an exact lookup finds nobody, the number may still narrow to a pool of Instagram accounts (search_state.phone_mask.count). A round with a name then searches among them, masked. The Instagram panel's lead says one (very likely one person), few (up to three) or none; cards of other networks carry linked_to, the Instagram card of the same person.

Credits​

StepWhat happens
POST /createChecks the account's search quota. 402 when none is left.
Search rounds, picks, confirmDo not spend a report credit.
First GET /report/{reportId} by the ownerSpends the report credit once, when the report has built. A second read spends nothing.

A guest who creates a report and then signs in is attached to it; the credit is still taken only when the owner reads the built report.

Errors​

All errors are {"code": <status>, "message": "<text>"}.

StatusWhereMeaning
400anyA bad fields value (<code>:<field>), a malformed round_key, a source that is not among the round's networks, a bad profile id, too_many_picks, stage quick needs a round_key, a report not made by People search.
401confirm, dropNo signed-in account.
402POST /createNo credits left; for a guest also guest_daily_limit: … (see below).
403anyPeople search is off, the report is not yours, the report is already built, or it is a phone lookup.
404rounds, picks, seed, confirmThe report was not found, or the account was never shown by this report.
408roundsrequest can not be completed. Please try again later: retry.
409rounds, confirmA phone lookup of another number; a repeat confirm. A round or part that reaches a report already confirmed is also 409.
422see belownothing to search: a name, a username or a phone is required (on a round), linkedin_only, opted_out: …, confirm_limit: …, a seed card with no name.
428POST /create (guest)captcha_required: …
429rounds, state, dropThe refinement cap, or too many requests from this client: honour Retry-After.
502rounds, lookupsthe search service could not answer — please try again, with a short code in brackets. Retry.
503rounds, lookups, confirmthe search service is busy — please try again in a moment, or on confirm gateway_unavailable. Honour Retry-After and retry.

402 guest_daily_limit: … (with Retry-After) and 428 captcha_required: … apply only to a guest session creating a new search. A client that sends a Bearer token for a signed-in account does not meet them.