PeopleSearchRequest
One round of the chat search. Every request carries the FULL context (fields, picks,
exclusions, questions already asked) — nothing is remembered between rounds except what
the server stores on the report as search_state.
fields objectrequired
What the user knows about the person. Every key is optional; a search needs one
of name / username / phone. state / country are the place LEVELS a refinement
question resolved — separate slots, never glued onto location.
Input policy (also CreateRequest.name / username / state and the typed text of
run and parse). maxLength counts Unicode code points. The server first normalizes
every value: NFC; invisible characters removed (zero-width, bidi controls, BOM, soft
hyphen, tag characters; ZWJ / ZWNJ kept); a line break becomes a space (; in info /
work / interests / life, one newline in text), any other control character a
space; { } [ ] < > ` \ $ ^ * " and their full-width forms become a space;
whitespace collapsed and trimmed, empty = unset. Then name needs a letter; username
is at most 3 distinct handles [a-z0-9._-]{1,50} (a link is read down to its handle,
@ dropped, lowercased), sent on as "h1, h2"; phone is one number (digits, spaces,
+ ( ) - . /, dashes; a + only in front or right after a leading ( — (+34) 612…;
at most 15 digits; full-width digits, +, brackets and dashes and the … of smart
punctuation are folded to their ASCII forms first, and the cap counts the folded
number); gender other than male / female is dropped; language is a code
(pt-BR) or a name. No patterns or enums here on purpose: normalization runs first, so
a pasted invisible character is removed, not a 400. maxLength itself is checked on the
value as sent, before normalization: a value over its cap only because of invisible
characters is still a 400, and phone's 40 applies both to the value as sent and to the
folded number.
Errors: 400 with GeneralError.message = <code>:<field> (the field's name or JSON
pointer, e.g. input_too_long:/fields/name). Stable codes: input_too_long,
input_empty (a blank text), input_no_letters, username_too_many_handles,
username_bad_handle, phone_bad_format, language_bad; input_invalid for any
other schema violation. A pointer names only properties declared here and array
indexes — any other key (a map key) is *. A body key that differs from a declared
property only in case (Username) is input_invalid:<pointer to that property>; a body
that passes the schema but does not decode (a number beyond its integer type) is
input_invalid:/. A body over 128 KiB is 413 body_too_large. The rejected value is
never echoed back or logged.
Possible values: <= 100 characters
@handle, with or without the @; up to 3 handles or profile links, comma or space separated
Possible values: <= 200 characters
A full number ALWAYS makes the report a phone lookup, wherever it arrives (at create or in a later round): the number ALONE is searched — a name and facts sent with it are kept on the report, not searched — and the results are masked from that round on. There is no combined "name + phone" search. The last two digits alone are not a phone number: such a value is dropped and never masks anything.
Possible values: <= 40 characters
Possible values: <= 100 characters
Possible values: <= 64 characters
Possible values: <= 64 characters
Anything else, free text — the pieces of several turns, ; -separated.
Possible values: <= 500 characters
male or female (any case); anything else is dropped.
Possible values: <= 16 characters
Possible values: <= 16 characters
Possible values: <= 200 characters
Possible values: <= 200 characters
Possible values: <= 200 characters
Possible values: <= 100 characters
Kinds of refinement questions already asked, so the core does not ask them again.
Possible values: <= 8
Ignored — the platform no longer keeps exclusions.
picked object[]
The accounts chosen so far, up to 3 per network across the 5 networks that can be
picked (create.MaxPicksPerNetwork). A pick does not have to be one of the
ranked cards: an account the user gave by hand (POST /people-search/account/{reportId})
is picked the same way, and the server puts its card on top of its network's panel
(picked: true) when the ranking did not return it. A LinkedIn card (li, where
User.peopleSearchLinkedinPanel) is picked like any other: its identity-graph partners
are pinned into the other panels, as the report's LinkedIn origin's are; it is never a
report subject (confirm lists it in not_in_report).
Possible values: <= 15
source social network of profile
Possible values: [ig, fb, tt, tw, li]
twid of profile
The interests the user tapped — distinct, at most 32 are kept.
Possible values: <= 32
det is the only mode the platform runs; llm is accepted and downgraded to det.
Possible values: [det, llm]
Networks to search in THIS request; default — every searchable network. li is a
searchable network only where the LinkedIn panel is enabled
(User.peopleSearchLinkedinPanel): its cards come from our LinkedIn database, by
the name (+ work, + place); elsewhere li is a 400. With round_key: this part's
networks (the platform's client sends one), each of them one of round_sources — else
400.
Possible values: [ig, fb, tt, tw, li], <= 5
The key of a round sent in PARTS — one request per network, in parallel, each answered as
soon as its network is searched. The client mints one key per round (a UUID) and sends it
with every part. Every part of one key is ONE round: the refinement cap and the rate limit
count it once; it has one search_state and one set of stored panels.
The first part of a key to reach the server fixes the round's query (fields, picks,
questions asked, interests, typed line, seed origin; for /seed the card); a later part of
the same key searches THAT query for its own networks, whatever its own body says.
The round becomes the report's search (its search_state, the stored panels, the history
row, a phone lookup's paywall) when the first of its networks answers. A round none of
whose networks answered is given back exactly like a single round the search service
failed: not counted, the report's previous search kept. A part of a
round that has ended (all its networks answered, a newer round replaced it, it failed, or
its time to resume — twice the search timeout — has passed) changes nothing and is
answered superseded: true.
LATE FILL (the lazy full wave): once a round is the report's search (one of its networks
answered), a part for one of its networks that has not answered yet is admitted for longer
— while the round is still the report's current one and within a limited time of its
start (30 minutes). So a client may send a
network's full part only when that network's tab is opened, or in the background while
the search service has spare capacity (es_spare): it joins the round like any other part —
no count, the round's fixed query. GET /people-search/state offers those networks as
pending for as long.
Possible values: >= 8 characters and <= 64 characters, Value must match regular expression ^[A-Za-z0-9_-]{8,64}$
With round_key: every network of the round — all its parts together; default — every
searchable network (li as in sources). Read from the part that opens the round only.
Possible values: [ig, fb, tt, tw, li], <= 5
The line the user typed, kept on the report for restore. Its links are shortened by the
client (no scheme, www. or query) and do not count towards the 200 characters of prose;
600 is the hard cap of the whole line.
Possible values: <= 600 characters
fixes object[]
Possible values: <= 8
Possible values: >= 0 and <= 200
Possible values: >= 0 and <= 200
Possible values: <= 16 characters
seed_origin object
The account a seeded search ("find other their accounts") started from — sent back while that query stands, so the server keeps marking that card in its panel.
source social network of profile
Possible values: [ig, fb, tt, tw, li]
twid of profile
quick — a first look at this part's networks (PeopleSearchStage); needs round_key.
Absent or full — the part itself.
Possible values: [quick, full]
full{
"fields": {
"name": "string",
"username": "string",
"phone": "string",
"location": "string",
"state": "string",
"country": "string",
"info": "string",
"gender": "string",
"language": "string",
"work": "string",
"interests": "string",
"life": "string",
"brand": "string"
},
"asked": [
"string"
],
"picked": [
{
"source": "tw",
"id": "string"
}
],
"interest_ids": [
0
],
"mode": "det",
"sources": [
"tw"
],
"round_key": "string",
"round_sources": [
"tw"
],
"text": "string",
"fixes": [
{
"start": 0,
"end": 0,
"tag": "string"
}
],
"seed_origin": {
"source": "tw",
"id": "string"
},
"stage": "full"
}