Skip to main content

PeopleSearchResponse

okbooleanrequired

True when at least one panel is ok.

took_msinteger
roundintegerrequired
orderSource (string)[]required

The networks sorted by tier — the panel to show first comes first. A round in parts lists every network of the round: a standing pick's previous order first, then those with a panel by tier, then the pending ones. li is sorted like the others but is never first: the first panel is a network a report can be built from.

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

tiers objectrequired
property name*integer
panels objectrequired
property name* PeopleSearchPanel

One network's ranked panel. The order of results is the search core's and is never re-ranked by the platform.

okbooleanrequired
sourceSource (string)required

source social network of profile

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

Default value: tw
tierintegerrequired

1 — has a pinned card; 2 — the top card matched two or more signals; 3 — non-empty; 4 — empty or failed.

Possible values: >= 1 and <= 4

totalinteger<int64>required
total_is_lower_boundboolean
Default value: false
results object[]required
  • Array [
  • imagestringrequired
    idProfileId (string)required

    id of profile

    usernamestringrequired
    fullnamestringrequired
    imageNotLoadedboolean
    sourceSource (string)required

    source social network of profile

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

    Default value: tw
    linkstringrequired
    badReasonProfileBadReason (string)

    followsPrivate means TikTok has hidden its following list; it does not imply that the account itself is private.

    Possible values: [unloaded, unmapped, zeroFollows, private, notFound, optOut, unexpected, followsPrivate]

    badReasonConfirmedboolean
    pinnedbooleanrequired

    Pinned to the top by an exact lookup (@handle, phone) or the identity graph.

    Default value: false
    pickedbooleanrequired

    The account the user picked in this network.

    Default value: false
    pin_rankintegernullable

    Order among the pinned cards (unique within a panel).

    panel_rankintegernullable

    Where the core's ranking had this card (null when it came from a lookup, not from retrieval).

    matchedstring[]required

    Which fields of the query this card matched — NAMES ONLY, never values: name, place, bio, work, interests, gender, age, language, friends (the place or the interests of the people they follow — not their own), phone, handle. This is the whole of what a card may say about why it is here; the client renders each name from its own closed dictionary and drops a name it does not know. A masked (phone-lookup) card carries an empty array.

    confidencestring

    How sure the identity graph is that this account belongs to the same person, when it is the graph that put the card in this panel: one of CONFIRMED, SURE, STRONG — the graph's own bands, the only three that make an account a pin. Absent on every other card. It is a BAND, never a number: it is not a threshold on a probability and must not be rendered as one, and no percent is computed anywhere. WHY the graph is sure — which pick, on what evidence, how crowded the decision was — is not sent.

    seed_originboolean

    The account this seeded search started from ("find other their accounts").

    linked_to object

    A phone mask search's PERSON: on a card of another network's panel, the Instagram account of the same person — a card of this report's Instagram panel, by the report's own id. One person is that Instagram card plus every card whose linked_to names it; the client draws them as one row and ticks them together. Only the identity graph's certain partners get one (the pins' rule), at most one per network per person. An exception (with lifted_by) to "no pointer to where a card came from" above: it says WHOSE account this is, never why or how sure. Absent on every other card.

    sourceSource (string)required

    source social network of profile

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

    Default value: tw
    idProfileId (string)required

    id of profile

    lifted_by object

    The card was LIFTED by a LinkedIn hit (PeopleSearchLiftedBy) — like linked_to, an exception to "no pointer to where a card came from": it names the network and the typed facts, never the LinkedIn profile, why or how sure. Kept with the stored panels, so a restore shows it again. Absent on every other card, a pinned card included (a pin is never re-marked as lifted).

    sourceSource (string)required

    The network of the hit that lifted the card — li.

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

    Default value: tw
    signalsstring[]required

    The typed facts the LinkedIn hit matched — names from matched's closed vocabulary: work, place. The client drops a name it does not know.

  • ]
  • pins object[]required
  • Array [
  • idProfileId (string)required

    id of profile

    in_indexbooleanrequired

    False when the partner is not among that network's search results — it is listed, not shown as a card.

  • ]
  • question object

    The one refinement question the core suggests for this panel (the ladder).

    kindstringrequired

    state, country, state_pick, topic, language, gender, …

    questionstringrequired
    options object[]required
  • Array [
  • valuestringnullable

    null = the "not sure" option.

    labelstringrequired
  • ]
  • degradedstring[]

    Channels that failed while building this panel; the ranking is not comparable with a healthy one.

    error_codestring

    Set when the network could not be searched: unsupported_network, unsupported_fields, gateway_unavailable (the search service answered nothing for this network), or a short code naming how the search failed. No free-text message is returned.

    basicbooleanrequired

    True when this panel came from the legacy search template (no matched, no pins, no question).

    blurredboolean

    Same contract as ProfilesPage.blurred — every card is masked behind the phone-search paywall. On a phone mask search (PeopleSearchState.phone_mask.searched) a card's fullname keeps the words of the name the user typed (its first three words) as they are written in the account's name, and every other word is its first letter followed by *** — never its length; username and link are empty; image is the blurred avatar. On a phone-origin report a masked card's id is the report's own: it names the account in this report's picks and confirm only, and is not the id the same account has anywhere else.

    Default value: false
    took_msinteger
    stagePeopleSearchStage (string)

    quick — a first look (PeopleSearchStage): shown until the full answer of this network replaces it; total is its own card count. Absent — the answer.

    Possible values: [quick, full]

    Default value: full
    leadstring

    A phone mask search's verdict, on its Instagram panel: one — the number most likely belongs to the one person of results (the only account carrying every typed word of the name, 10 % ahead of every other); few — up to three people could be them (the page asks for their city to narrow it down); none — nobody in the pool carries the typed name, results is empty. Absent on every other panel.

    Possible values: [one, few, none]

    default_sortstring

    Which of the two card orders this panel should OPEN on, as the search core decided it from the query: panel — the order of results (the name spine; a name of two or more words); signals — by the number of matched signals (matched), a one-word name, where every card matches the name completely and only the evidence tells them apart. A hint for the initial sort only: both orders stay available, and results keeps the core's order either way. Absent — an older search service, a failed panel, or a value the platform does not know; open on panel. Kept with the stored panels, so a restore opens on the same order.

    Possible values: [panel, signals]

    picked object[]required
  • 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

    error_codestring

    Set when the graph could not be read for this pick.

  • ]
  • search_state objectrequired

    The search state the server keeps on the report — what a client needs to restore the chat.

    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[]required
    exclude_idsobjectrequireddeprecated

    Always {} — the platform no longer keeps exclusions (PeopleSearchRequest.exclude_ids is ignored).

    picked object[]required
  • 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>[]required
    textstring
    fixes object[]
  • Array [
  • startintegerrequired

    Possible values: >= 0 and <= 200

    endintegerrequired

    Possible values: >= 0 and <= 200

    tagstringrequired

    Possible values: <= 16 characters

  • ]
  • roundsintegerrequired
    rounds_leftintegerrequired
    orderSource (string)[]

    The last round's PeopleSearchResponse.order (li never first).

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

    tiers object
    property name*integer
    last_search_atstring<date-time>
    seed_origin object

    The account the current query was seeded from, when it was.

    sourceSource (string)required

    source social network of profile

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

    Default value: tw
    idProfileId (string)required

    id of profile

    phone_mask object

    Set on a phone lookup whose exact lookup bound the number to nobody while the Instagram password-recovery mask (country code, length, the last two digits) fits count accounts. A round with a NAME on such a report searches by it among them, masked, the typed name readable (PeopleSearchPanel.blurred); a round without a name is the lookup of the number again. Absent on every other report.

    Its answer is a PERSON: only Instagram's accounts carry the mask, so only Instagram is searched and its panel is cut to one, a few (≤ 3) or nobody (PeopleSearchPanel.lead); the round's other networks — send every network, in ONE part — answer the identity graph's certain partners of those Instagram accounts, each saying whose it is (PeopleSearchCard.linked_to). No refinement question is asked. count is the size of the pool, about half a million for any US number — not a figure to show.

    countinteger<int64>required

    The Instagram accounts whose recovery mask fits the number.

    Possible values: >= 1

    searchedboolean

    The stored panels are a search by name among them (the last round had a name).

    Default value: false
    linkedin_origin object

    The LinkedIn profile this search started from (POST /people-search/linkedin/{reportId} answered status: index). It is the report's, not a pick: the client never sends it, a round does not change it and un-picking a card does not drop it — every round of the report (run or seed; not a phone lookup's) pins on top of the panels the accounts the identity graph ties to it, as any pin — the card never says which pick pinned it. The next LinkedIn read of the report replaces it, or removes it when that read is not index. Absent otherwise.

    slugstringrequired
    fullnamestringrequired

    The name as our database holds it (may be empty — the search then runs by fullname of the answer).

    linkstringrequired

    https://www.linkedin.com/in/<slug>.

    staleboolean

    GET only: the stored panels expired; the client should run the search again with search_state.

    Default value: false
    round_keyPeopleSearchRoundKey (string)

    The round's key — echoed by every part. On GET: set only while the report's last round was sent in parts and can still be resumed (not every network answered, within twice the search timeout of its start, the report not confirmed): re-ask its pending networks with it (that is not a new round).

    Possible values: >= 8 characters and <= 64 characters, Value must match regular expression ^[A-Za-z0-9_-]{8,64}$

    pendingSource (string)[]

    Networks of the round (round_sources) that have no panel yet — on a part's answer, after this part's merge; on GET, under the same conditions as round_key. While none of the round's networks has answered, GET answers the round's query in search_state with no panels.

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

    supersededboolean

    This part belongs to a round that has ended (see PeopleSearchRoundKey): it changed nothing and carries no panels (panels is {}, order []); round and search_state are the report's current ones.

    Default value: false
    stagePeopleSearchStage (string)

    quick on the answer of a first look (PeopleSearchStage): round and search_state are what the round would search, nothing was stored; panels may be {} (nothing to preview). Absent on every other answer.

    Possible values: [quick, full]

    Default value: full
    es_spareinteger

    Free full-search capacity of the search service when this answer was built. A client that defers the full parts of the networks whose tab is not open (see PeopleSearchRoundKey "late fill") sends them in the background only while this is above 0. Absent when no limit is known (send them) or the answer did not come from a live search (stored panels, superseded).

    Possible values: >= 0

    PeopleSearchResponse
    {
    "ok": true,
    "took_ms": 0,
    "round": 0,
    "order": [
    "tw"
    ],
    "tiers": {},
    "panels": {},
    "picked": [
    {
    "source": "tw",
    "id": "string",
    "error_code": "string"
    }
    ],
    "search_state": {
    "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
    ],
    "text": "string",
    "fixes": [
    {
    "start": 0,
    "end": 0,
    "tag": "string"
    }
    ],
    "rounds": 0,
    "rounds_left": 0,
    "order": [
    "tw"
    ],
    "tiers": {},
    "last_search_at": "2024-07-29T15:51:28.071Z",
    "seed_origin": {
    "source": "tw",
    "id": "string"
    },
    "phone_mask": {
    "count": 0,
    "searched": false
    },
    "linkedin_origin": {
    "slug": "string",
    "fullname": "string",
    "link": "string"
    }
    },
    "stale": false,
    "round_key": "string",
    "pending": [
    "tw"
    ],
    "superseded": false,
    "stage": "full",
    "es_spare": 0
    }