Skip to main content
POST
/
v3
/
face-search
Face Search
curl --request POST \
  --url https://verification.didit.me/v3/face-search/ \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form user_image='@example-file' \
  --form search_type=most_similar \
  --form rotate_image=false \
  --form save_api_request=true \
  --form 'vendor_data=<string>'
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 100,
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Alejandro Rosás",
          "document_type": "ID",
          "document_number": "CA00000000"
        },
        "match_image_url": "https://example.com/image.jpg",
        "status": "Declined",
        "is_blocklisted": true
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [
            40,
            40,
            120,
            120
          ],
          "confidence": 0.717775046825409
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}

Authorizations

​
x-api-key
string
header
required

Body

multipart/form-data
​
user_image
file
required

User's face image to be searched for similarities in previous approved sessions. Allowed formats: JPEG, PNG, WebP, TIFF. Maximum file size: 5MB.

​
search_type
enum<string>
default:most_similar

Search type for face search. Must be between most_similar or blocklisted_or_approved.

Available options:
most_similar,
blocklisted_or_approved
​
rotate_image
boolean
default:false

If true, attempts to rotate the input images in 90-degree increments (0, 90, 180, 270) to ensure the detected face is upright before performing the face match. Note: This is only recommended if you are unsure about the orientation of the face.

​
save_api_request
boolean
default:true

Whether to save this API request. If true, then it will appear on the Manual Checks section in the Business Console.

​
vendor_data
string

A unique identifier for the vendor or user, such as a UUID or email. This field enables proper session tracking and user data aggregation across multiple verification sessions.

Response

​
request_id
string<uuid>
​
face_search
object
​
created_at
string<date-time>