Skip to main content
POST
/
v1
/
identity
/
verify
Verify Identity
curl --request POST \
  --url https://api.deepidv.com/v1/identity/verify
{
  "verified": true,
  "document": {
    "documentType": "drivers_license",
    "fullName": "JANE Q PUBLIC",
    "firstName": "JANE",
    "lastName": "PUBLIC",
    "dateOfBirth": "1990-04-12",
    "gender": "F",
    "nationality": "USA",
    "documentNumber": "D1234567",
    "expirationDate": "2030-04-12",
    "issuingCountry": "USA",
    "address": "123 MAIN ST, SPRINGFIELD, IL 62701",
    "confidence": 97
  },
  "faceDetection": {
    "faceDetected": true,
    "confidence": 99
  },
  "faceMatch": {
    "isMatch": true,
    "confidence": 96.4,
    "threshold": 80
  },
  "overallConfidence": 95
}

POST /v1/identity/verify
Submit one document image and one selfie image. The endpoint runs /v1/document/scan, /v1/face/detect on the selfie, and /v1/face/compare between the document photo and the selfie — in parallel — and returns a single aggregated response with an overallConfidence score. Use this when you have both images already and want one round-trip instead of orchestrating three calls yourself. If you only have one of the two images, call the individual endpoints directly.

​
Request

​
Headers

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

​
Body parameters

ParameterTypeRequiredDescription
documentImagebinary | stringYesImage of the document. Multipart file part or JSON base64/base64url/S3-key string.
faceImagebinary | stringYesSelfie image. Same input rules as documentImage.
documentTypestringNoOne of passport, drivers_license, national_id, auto. Defaults to auto.
You can mix input modes — for example, send documentImage as a JSON S3 key (from an earlier presigned upload) and faceImage as fresh multipart bytes. See the overview for the shared image rules.

​
Example request

curl -X POST https://api.deepidv.com/v1/identity/verify \
  -H "x-api-key: YOUR_API_KEY" \
  -F "documentImage=@/path/to/id.jpg" \
  -F "faceImage=@/path/to/selfie.jpg" \
  -F "documentType=drivers_license"

​
Response

​
200 — Success

All confidence and threshold values on this response are reported on a 0–100 scale.
FieldTypeDescription
verifiedbooleanOverall pass/fail derived from the three sub-results
documentobjectSubset of /v1/document/scan response
faceDetectionobjectResult of /v1/face/detect on the selfie
faceMatchobjectComparison between document photo and selfie
overallConfidencenumber (0–100)Weighted aggregate confidence across all three sub-results

​
document

FieldTypeDescription
documentTypestringNormalized document type
fullNamestringFull name as printed on the document
firstNamestringFirst name
lastNamestringLast name
dateOfBirthstringDate of birth
genderstringGender
nationalitystringNationality
documentNumberstringDocument number
expirationDatestringDocument expiration date
issuingCountrystringIssuing country
addressstringAddress (when present)
confidencenumber (0–100)Average document-extraction confidence

​
faceDetection

FieldTypeDescription
faceDetectedbooleanTrue when a face was detected in the selfie
confidencenumber (0–100)Detection confidence for the top face

​
faceMatch

FieldTypeDescription
isMatchbooleanTrue when confidence >= threshold
confidencenumber (0–100)Best face-match similarity
thresholdnumber (0–100)Match threshold

​
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 S3 key is not readable by this organization
429Rate limit exceeded
500Unexpected server error — safe to retry with backoff
{
  "verified": true,
  "document": {
    "documentType": "drivers_license",
    "fullName": "JANE Q PUBLIC",
    "firstName": "JANE",
    "lastName": "PUBLIC",
    "dateOfBirth": "1990-04-12",
    "gender": "F",
    "nationality": "USA",
    "documentNumber": "D1234567",
    "expirationDate": "2030-04-12",
    "issuingCountry": "USA",
    "address": "123 MAIN ST, SPRINGFIELD, IL 62701",
    "confidence": 97
  },
  "faceDetection": {
    "faceDetected": true,
    "confidence": 99
  },
  "faceMatch": {
    "isMatch": true,
    "confidence": 96.4,
    "threshold": 80
  },
  "overallConfidence": 95
}

​
How overallConfidence is calculated

overallConfidence is a fixed weighted blend of the three sub-results:
ComponentWeight
Document extraction confidence0.4
Face-detection confidence (selfie)0.2
Face-match confidence (document photo vs selfie)0.4
The weights are fixed today. If you need to apply your own policy on top of the individual signals, use the per-block fields and ignore overallConfidence.

​
Partial failures

The three sub-calls run in parallel and are independent. If one fails (for example, no face detected in the selfie), the others still run and the corresponding block reports the failure in-band rather than 4xx-ing the whole request. Always inspect each block before acting on overallConfidence.