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.
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 field | Meaning |
|---|---|
peopleSearchEnabled | true when People search is available. A missing field means false. |
peopleSearchLinkedinPanel | true when li (LinkedIn) can be searched and picked as a fifth network. A missing field means false. |
ttFollowsEnabled | true 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):
| Key | Limit | Meaning |
|---|---|---|
name | 100 | Full name. Needs a letter. |
username | 200 | Up to 3 handles or profile links, comma or space separated; @ optional. |
phone | 40 | One phone number. See Phone lookups. |
location | 100 | Free-text place. |
state, country | 64 | A place level, for example the answer to a refinement question. |
info | 500 | Anything else, free text. |
gender | 16 | male or female; anything else is dropped. |
language | 16 | A language code (pt-BR) or name. |
work, interests, life | 200 | Free text. |
brand | 100 | Free 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:
| Status | message | Meaning |
|---|---|---|
400 | nothing to search: a name, a username or a phone is required | None of name, username, phone is set. |
400 | <code>:<field>, for example input_too_long:/fields/name | A 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. |
402 | to continue please upgrade your subscription | The account has no report credits left. |
402 | You have reached search limit. Please Sign up to continue. | A guest session used its free searches. |
403 | people search is not available | People search is off for this deployment. |
413 | body_too_large | The 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):
| Key | Meaning |
|---|---|
fields | The search fields, as above. |
picked | Accounts chosen so far: [{"source": "ig", "id": "…"}]. See Picks. |
asked | Kinds of refinement questions already asked, so they are not asked again (at most 8). |
interest_ids | Interests the user tapped (at most 32 are kept). |
sources | Networks to search in this request; default: every searchable network. li only where peopleSearchLinkedinPanel is true, otherwise 400. |
text | The line the user typed (up to 600 characters), kept on the report so it can be restored. |
fixes | The user's corrections to how text was read (see Parse a typed line). |
seed_origin | The account a seeded search started from; send it back while that query stands. |
round_key, round_sources, stage | Sending 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": []}
}
orderlists the networks with the most useful panel first.liis never first.- A panel's
tierruns from 1 (a card is pinned) to 4 (empty or failed).totalis the number of matches;total_is_lower_boundsays it is a floor. resultsis already ranked; do not re-rank it.- A panel that failed has
ok: falseand anerror_codenaming the failure class (for exampleunsupported_networkorgateway_unavailable). The other panels are still good. search_stateis 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:
| Field | Meaning |
|---|---|
badReason | Why 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. |
pinned | The card was put on top by an exact lookup (@handle, phone) or by the identity graph. |
picked | This is the account the user picked in this network. |
matched | Names of the query fields the card matched: name, place, bio, work, interests, gender, age, language, friends, phone, handle. Names only, never values. |
confidence | CONFIRMED, 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_origin | The account a seeded search started from. |
linked_to, lifted_by | Present 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.
sourcesof a part must be among the round'sround_sources, otherwise400.- 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: truewith 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
503for 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(400stage quick needs a round_keyotherwise). - It is not a part of the round: it counts nothing, stores no state and is never
pending. Its panels carrystage: "quick". - It may return no panels (
panelsis{}): 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: truemeans the stored panels expired: run the search again with the returnedsearch_state.- When the last round was sent in parts and can still be resumed, the answer has
round_keyandpending. Ask the pending networks again with that key; that is not a new round. 429means too many restores from this client; honourRetry-After.400means 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
400too_many_picks. - A pick pins the accounts the identity graph ties to it on top of the other networks' panels
(
pinned: true, with aconfidenceband). 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:
422with a message startingopted_out. - A LinkedIn card (
li) can be picked wherepeopleSearchLinkedinPanelistrue. 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.
status | Meaning |
|---|---|
index | Our 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. |
slug | The profile is not in our database; the name is what the link spells. No origin. |
profile | The 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 (
400too_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 is422linkedin_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=twlists 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 is400.- A repeat confirm is
409report profiles were already confirmed, unless the confirm was undone with drop. 503gateway_unavailable(withRetry-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": []
}
estimatedTimeandloadTimeoutare in seconds.estimatedTime: 0means nothing is left to wait for and the report can be opened now.loadshas one entry per confirmed account that cannot be used yet:inited/inprogress(its data is loading; the outcome arrives on the SSE stream as afollowsevent),done, orerrorwith the reason inerror(an account the report cannot be built from: remove it with drop and confirm again).not_in_reportlists 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.
idremoves only that account from a network that keeps another pick. Withoutid(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
422confirm_limit: start a new search. - Errors:
400forli(a LinkedIn pick is never in the report; un-pick it) or a report not made by People search,401without a signed-in account,403when 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,usernameandlinkare empty andimageis 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
409this 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) answer403not 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.
403phone search is not available from this entry pointmeans 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
| Step | What happens |
|---|---|
POST /create | Checks the account's search quota. 402 when none is left. |
| Search rounds, picks, confirm | Do not spend a report credit. |
First GET /report/{reportId} by the owner | Spends 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>"}.
| Status | Where | Meaning |
|---|---|---|
400 | any | A 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. |
401 | confirm, drop | No signed-in account. |
402 | POST /create | No credits left; for a guest also guest_daily_limit: … (see below). |
403 | any | People search is off, the report is not yours, the report is already built, or it is a phone lookup. |
404 | rounds, picks, seed, confirm | The report was not found, or the account was never shown by this report. |
408 | rounds | request can not be completed. Please try again later: retry. |
409 | rounds, confirm | A phone lookup of another number; a repeat confirm. A round or part that reaches a report already confirmed is also 409. |
422 | see below | nothing 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. |
428 | POST /create (guest) | captcha_required: … |
429 | rounds, state, drop | The refinement cap, or too many requests from this client: honour Retry-After. |
502 | rounds, lookups | the search service could not answer — please try again, with a short code in brackets. Retry. |
503 | rounds, lookups, confirm | the 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.