Skip to main content

PeopleSearchParseResponse

The typed line read into search fields. ready is false while fields has no name, @handle or phone — then questions[0].ask is NAME and the client asks before searching.

okbooleanrequired
took_msinteger
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

readybooleanrequired
reading object[]required
  • Array [
  • tagstringrequired
    textstringrequired
    startintegerrequired
    endintegerrequired
    confidencenumber<float>required
    sourcestring

    model, user (from a fix) or regex.

  • ]
  • dropped object[]
  • Array [
  • tagstringrequired
    textstringrequired
    startintegerrequired
    endintegerrequired
    confidencenumber<float>required
    sourcestring

    model, user (from a fix) or regex.

  • ]
  • residuestring
    questions object[]required
  • Array [
  • kindstringrequired

    pair, tag or yesno.

    textstringrequired
    startintegerrequired
    endintegerrequired
    readstring
    altstring
    askstring

    The tag the question is about (NAME for the name law).

    whystring
    pnumber<float>
    options object[]required
  • Array [
  • answerstringrequired
    tagstringrequired
    labelstring
    fix objectrequired

    The user's answer to a parse question or a tap on a chip: {start, end, tag}; tag: "O" = not a fact. start / end are code-point offsets into the NORMALIZED line (what POST /people-search/parse read). The schema's own caps — at most 8 fixes, tag at most 16 code points, start / end at most 200 — are checked first and are a 400 (input_too_long / input_invalid). Within them, a fix is kept only when its tag is a tagger tag ([A-Z_]{1,16}: O, NAME, LOC, …) and 0 ≤ start < end ≤ the normalized line's length — any other is dropped, not refused (a stale fix of an edited line must not fail the request).

    startintegerrequired

    Possible values: >= 0 and <= 200

    endintegerrequired

    Possible values: >= 0 and <= 200

    tagstringrequired

    Possible values: <= 16 characters

  • ]
  • default object

    The user's answer to a parse question or a tap on a chip: {start, end, tag}; tag: "O" = not a fact. start / end are code-point offsets into the NORMALIZED line (what POST /people-search/parse read). The schema's own caps — at most 8 fixes, tag at most 16 code points, start / end at most 200 — are checked first and are a 400 (input_too_long / input_invalid). Within them, a fix is kept only when its tag is a tagger tag ([A-Z_]{1,16}: O, NAME, LOC, …) and 0 ≤ start < end ≤ the normalized line's length — any other is dropped, not refused (a stale fix of an edited line must not fail the request).

    startintegerrequired

    Possible values: >= 0 and <= 200

    endintegerrequired

    Possible values: >= 0 and <= 200

    tagstringrequired

    Possible values: <= 16 characters

  • ]
  • fixes object[]
  • Array [
  • startintegerrequired

    Possible values: >= 0 and <= 200

    endintegerrequired

    Possible values: >= 0 and <= 200

    tagstringrequired

    Possible values: <= 16 characters

  • ]
  • negative_topicsstring[]
    linkedinstring[]

    LinkedIn profile links found in the line (with or without a scheme, any subdomain). They are never read as an @handle or a place; a client opens the LinkedIn by-link flow (POST /people-search/linkedin/{reportId}) for them.

    truncated_tokensinteger
    PeopleSearchParseResponse
    {
    "ok": true,
    "took_ms": 0,
    "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"
    },
    "ready": true,
    "reading": [
    {
    "tag": "string",
    "text": "string",
    "start": 0,
    "end": 0,
    "confidence": 0,
    "source": "string"
    }
    ],
    "dropped": [
    {
    "tag": "string",
    "text": "string",
    "start": 0,
    "end": 0,
    "confidence": 0,
    "source": "string"
    }
    ],
    "residue": "string",
    "questions": [
    {
    "kind": "string",
    "text": "string",
    "start": 0,
    "end": 0,
    "read": "string",
    "alt": "string",
    "ask": "string",
    "why": "string",
    "p": 0,
    "options": [
    {
    "answer": "string",
    "tag": "string",
    "label": "string",
    "fix": {
    "start": 0,
    "end": 0,
    "tag": "string"
    }
    }
    ],
    "default": {
    "start": 0,
    "end": 0,
    "tag": "string"
    }
    }
    ],
    "fixes": [
    {
    "start": 0,
    "end": 0,
    "tag": "string"
    }
    ],
    "negative_topics": [
    "string"
    ],
    "linkedin": [
    "string"
    ],
    "truncated_tokens": 0
    }