MatchesResponse
Thumbnail of the uploaded photo used for search
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.
items object[]required
Array of matches for this source
Unique match ID
Partially visible name and username (e.g., "O*** Black"). Both name and username are blurred, showing only first letter followed by blur symbols
Whether the name is blurred. Note: consensusName is only available after matches are selected (see SearchResultsResponse)
Social network source identifier
Possible values: [fb, ig, tt, tw]
fbThumbnail image URL
Username on the social network
Whether this match is selected
Match confidence score 0–1 (included only for admin role)
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]
When true, account is excluded from search results by law (e.g. GDPR). Only present when true.
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.
Total number of items available. Optional field, may be omitted in additional pagination requests to reduce response size and improve performance.
Social network source identifier
Possible values: [fb, ig, tt, tw]
fbWhen true, the current user is an admin viewing another user's search; UI should be read-only (no select/delete/actions).
Total number of matches across all sources. If no matches found, this will be 0 and groups array will be empty.
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.
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.
When true, frontend should show restriction icon (e.g. ⚠️) for matches with excludedByLaw.
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.
When true, the current user is an admin viewing another user's search; UI should be read-only (no select/delete/actions).
{
"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
}