Skip to main content
POST
/
v1
/
face
/
compare
Compare Faces
curl --request POST \
  --url https://api.deepidv.com/v1/face/compare
{
  "isMatch": true,
  "confidence": 96.4,
  "threshold": 80,
  "sourceFaceDetected": true,
  "targetFaceDetected": true
}

POST /v1/face/compare
Submit two images and receive a similarity score plus a boolean isMatch decision. Typical use: comparing a selfie to the photo on a scanned ID.

​
Request

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key
Content-TypeYesmultipart/form-data or application/json

​
Body parameters

ParameterTypeRequiredDescription
sourcebinary | stringYesThe first image. For multipart, the file part. For JSON, a base64, base64url, or S3-key string.
targetbinary | stringYesThe second image. Same input rules as source.
You can mix input modes within a single call — for example, send source as raw multipart bytes and target as a JSON S3 key in a multipart body. See the overview for the shared image rules.

​
Example request

curl -X POST https://api.deepidv.com/v1/face/compare \
  -H "x-api-key: YOUR_API_KEY" \
  -F "source=@id-photo.jpg" \
  -F "target=@selfie.jpg"

​
Response

​
200 — Success

FieldTypeDescription
isMatchbooleanTrue when confidence >= threshold
confidencenumberRaw similarity score from AWS Rekognition, 0–100 (not normalized)
thresholdnumberServer-side similarity threshold used for isMatch, 0–100
sourceFaceDetectedbooleanTrue when a face was detected in source
targetFaceDetectedbooleanTrue when a face was detected in target

​
Error responses

StatusDescription
400Invalid body, unsupported image format, or image larger than 15 MB
401Missing or invalid x-api-key
402Insufficient token balance
403A supplied source/target S3 key is not readable by this organization
429Rate limit exceeded
500Unexpected server error — safe to retry with backoff
{
  "isMatch": true,
  "confidence": 96.4,
  "threshold": 80,
  "sourceFaceDetected": true,
  "targetFaceDetected": true
}

​
Telling failure modes apart

The response shape lets you distinguish three distinct isMatch: false outcomes without a second API call:
OutcomeconfidencesourceFaceDetectedtargetFaceDetected
Both faces found, similarity too low> 0truetrue
No face in source0falsetrue/false
No face in target0truefalse
No face in either image0falsefalse
Surface a “retake your selfie” prompt when sourceFaceDetected is false, a “retake the ID photo” prompt when targetFaceDetected is false, and a “doesn’t match” outcome when both booleans are true but isMatch is false.