Skip to main content
POST
/
v1
/
document
/
scan
Scan Document
curl --request POST \
  --url https://api.deepidv.com/v1/document/scan
{
  "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",
  "rawFields": {
    "FIRST_NAME": "JANE",
    "LAST_NAME": "PUBLIC",
    "DATE_OF_BIRTH": "04/12/1990"
  },
  "confidence": 0.97
}

POST /v1/document/scan
Submit a single image of a government-issued ID. The response contains the extracted text fields (name, date of birth, document number, address, expiry, etc.), a normalized documentType, and an average extraction confidence score.

​
Request

​
Headers

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

​
Body parameters

The endpoint accepts the image either as raw multipart bytes or as a JSON string (base64, base64url, or an S3 key from an earlier presigned upload). See the overview for the shared image rules — accepted formats, the 15 MB limit, and when to prefer one over the other.
ParameterTypeRequiredDescription
imagebinary | stringYesThe image. For multipart, the file part. For JSON, a base64, base64url, or S3-key string.
documentTypestringNoOne of passport, drivers_license, national_id, auto. Defaults to auto.

​
Example request

curl -X POST https://api.deepidv.com/v1/document/scan \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image=@/path/to/id.jpg" \
  -F "documentType=drivers_license"

​
Response

​
200 — Success

FieldTypeDescription
documentTypestringNormalized document type extracted from the image
fullNamestringFull name as printed on the document
firstNamestringFirst / given name
lastNamestringLast / family name
dateOfBirthstringDate of birth as printed on the document
genderstringGender as printed on the document
nationalitystringNationality as printed on the document
documentNumberstringDocument number
expirationDatestringDocument expiration date
issuingCountrystringIssuing country
addressstringAddress as printed on the document (when present)
mrzDatastringMachine-readable zone, raw (passports / some IDs)
rawFieldsobjectAll fields returned by AWS Textract, keyed by Textract field name
confidencenumber (0–1)Average extraction confidence across all detected fields

​
Error responses

StatusDescription
400Invalid body, unsupported image format, or image larger than 15 MB
401Missing or invalid x-api-key
402Insufficient token balance
403The supplied image S3 key is not readable by this organization
429Rate limit exceeded
500Unexpected server error — safe to retry with backoff
{
  "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",
  "rawFields": {
    "FIRST_NAME": "JANE",
    "LAST_NAME": "PUBLIC",
    "DATE_OF_BIRTH": "04/12/1990"
  },
  "confidence": 0.97
}

​
When to use /v1/identity/verify instead

If you also have a selfie and want a single round-trip that runs document scan + face detect + face compare in parallel, call /v1/identity/verify instead — it returns one aggregated payload with an overallConfidence score.