Skip to main content

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.

namestring

Possible values: <= 100 characters

usernamestring

@handle, with or without the @; up to 3 handles or profile links, comma or space separated

Possible values: <= 200 characters

phonestring

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

locationstring

Possible values: <= 100 characters

statestring

Possible values: <= 64 characters

countrystring

Possible values: <= 64 characters

infostring

Anything else, free text — the pieces of several turns, ; -separated.

Possible values: <= 500 characters

genderstring

male or female (any case); anything else is dropped.

Possible values: <= 16 characters

languagestring

Possible values: <= 16 characters

workstring

Possible values: <= 200 characters

interestsstring

Possible values: <= 200 characters

lifestring

Possible values: <= 200 characters

brandstring

Possible values: <= 100 characters

askedstring[]

Kinds of refinement questions already asked, so the core does not ask them again.

Possible values: <= 8

exclude_idsobjectdeprecated

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

  • Array [
  • sourceSource (string)required

    source social network of profile

    Possible values: [ig, fb, tt, tw, li]

    Default value: tw
    idProfileId (string)required

    id of profile

  • ]
  • interest_idsinteger<int64>[]

    The interests the user tapped — distinct, at most 32 are kept.

    Possible values: <= 32

    modePeopleSearchMode (string)

    det is the only mode the platform runs; llm is accepted and downgraded to det.

    Possible values: [det, llm]

    sourcesSource (string)[]

    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

    round_keyPeopleSearchRoundKey (string)

    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}$

    round_sourcesSource (string)[]

    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

    textstring

    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

  • Array [
  • startintegerrequired

    Possible values: >= 0 and <= 200

    endintegerrequired

    Possible values: >= 0 and <= 200

    tagstringrequired

    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.

    sourceSource (string)required

    source social network of profile

    Possible values: [ig, fb, tt, tw, li]

    Default value: tw
    idProfileId (string)required

    id of profile

    stagePeopleSearchStage (string)

    quick — a first look at this part's networks (PeopleSearchStage); needs round_key. Absent or full — the part itself.

    Possible values: [quick, full]

    Default value: full
    PeopleSearchRequest
    {
    "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"
    }