Skip to main content

MatchesResponse

thumbnailstring<uri>

The searched face cropped from the uploaded photo, or the whole uploaded photo when no face crop is available. Never blurred. Omitted when this search was created without uploaded-photo retention; clients must not request a replacement photo.

groups object[]required

Matches grouped by social network sources. Each group contains first page of matches (default limit). To load more matches for a specific group, use GET /search/{searchId}/matches/{source} endpoint with cursor-based pagination. Each group has its own nextCursor field indicating if there are more matches available.

  • Array [
  • items object[]required

    Array of matches for this source

  • Array [
  • idstringrequired

    Unique match ID

    partialNamestringrequired

    Partially visible name and username (e.g., "O*** Black"). Both name and username are blurred, showing only first letter followed by blur symbols

    isBlurredbooleanrequired

    Whether the name is blurred. Note: consensusName is only available after matches are selected (see SearchResultsResponse)

    sourceSource (string)required

    Social network source identifier. For li (LinkedIn) the match/profile id is face-vector-search's own sequential user id, not a LinkedIn id: the LinkedIn handle is the profile username (public_id).

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

    Example: fb
    thumbnailstring<uri>required

    Thumbnail image URL

    usernamestring

    Username on the social network

    selectedboolean

    Whether this match is selected

    scorenumber<float>nullable

    Match confidence score 0–1 (included only for admin role)

    qualitystringnullable

    Derived match-confidence tier. best when score > 0.7, likely when 0.55 <= score <= 0.7, absent/null below 0.55. Computed server-side; available to ALL roles (unlike score, admin-only).

    Possible values: [best, likely]

    excludedByLawboolean

    When true, account is excluded from search results by law (e.g. GDPR). Only present when true.

  • ]
  • nextCursorstringnullable

    Cursor for the next page. If null, there are no more items available. Use this cursor in the next request with the same endpoint and limit parameter.

    totalinteger<uint32>

    Total number of items available. Optional field, may be omitted in additional pagination requests to reduce response size and improve performance.

    sourceSource (string)required

    Social network source identifier. For li (LinkedIn) the match/profile id is face-vector-search's own sequential user id, not a LinkedIn id: the LinkedIn handle is the profile username (public_id).

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

    Example: fb
    read_onlyboolean

    When true, the current user is an admin viewing another user's search; UI should be read-only (no select/delete/actions).

  • ]
  • totalCountinteger<uint32>required

    Total number of matches across all sources. If no matches found, this will be 0 and groups array will be empty.

    maxSelectableinteger<uint32>

    Maximum number of matches selectable in POST /search/{searchId}/select for this search: max(anyQualitySelectable, count of best+likely matches). Search-wide, not page-wide — it is NOT repeated on GET /search/{searchId}/matches/{source}, so clients keep the value from this response.

    anyQualitySelectableinteger<uint32>

    Number of matches the user may select regardless of quality. Selections beyond this count must be best or likely matches. Comes from the backend's search_by_image.min_selectable_matches config value and is the floor maxSelectable is computed from. Search-wide, not page-wide — like maxSelectable it is NOT repeated on GET /search/{searchId}/matches/{source}, so clients keep the value from this response.

    showRestrictionIconboolean

    When true, frontend should show restriction icon (e.g. ⚠️) for matches with excludedByLaw.

    lowConfidenceboolean

    True when the search produced no match with score >= 0.55 (including zero matches). Drives the "results may be limited by image quality" warning in the UI.

    read_onlyboolean

    When true, the current user is an admin viewing another user's search; UI should be read-only (no select/delete/actions).

    MatchesResponse
    {
    "thumbnail": "string",
    "groups": [
    {
    "items": [
    {
    "id": "match_001",
    "partialName": "O*** Black",
    "isBlurred": true,
    "source": "fb",
    "thumbnail": "https://cdn.face2social.com/thumbs/match_001.jpg",
    "username": "o.black",
    "selected": false
    }
    ],
    "nextCursor": "string",
    "total": 0,
    "source": "fb",
    "read_only": true
    }
    ],
    "totalCount": 0,
    "maxSelectable": 0,
    "anyQualitySelectable": 0,
    "showRestrictionIcon": true,
    "lowConfidence": true,
    "read_only": true
    }