Skip to main content
POST
/
v3
/
id-verification
/
cURL
curl -X POST 'https://verification.didit.me/v3/id-verification/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'front_image=@./id_front.jpg' \
  -F 'back_image=@./id_back.jpg' \
  -F 'perform_document_liveness=true' \
  -F 'save_api_request=true' \
  -F 'vendor_data=user-123'
{
  "request_id": "11d219ed-d59c-4b1d-8d65-9b933f12d5b8",
  "id_verification": {
    "status": "Approved",
    "document_type": "Identity Card",
    "document_subtype": "ID_CARD_GENERIC",
    "document_number": "CBX164224",
    "personal_number": "20446581H",
    "portrait_image": "https://<media-host>/ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=...",
    "front_image": "https://<media-host>/ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=...",
    "back_image": "https://<media-host>/ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=...",
    "front_image_camera_front": null,
    "back_image_camera_front": null,
    "front_image_camera_front_face_match_score": null,
    "back_image_camera_front_face_match_score": null,
    "front_image_quality_score": {
      "focus_score": 78,
      "brightness_score": 83.2,
      "brightness_issue": "ok",
      "is_document_fully_visible": true,
      "resolution_score": 40.7,
      "overall_score": 70.2
    },
    "back_image_quality_score": {
      "focus_score": 100,
      "brightness_score": 95.6,
      "brightness_issue": "ok",
      "is_document_fully_visible": true,
      "resolution_score": 43,
      "overall_score": 84.4
    },
    "date_of_birth": "1980-01-13",
    "age": 46,
    "expiration_date": "2032-03-31",
    "date_of_issue": "2022-03-31",
    "issuing_state": "ESP",
    "issuing_state_name": "Spain",
    "first_name": "Julio Francisco",
    "last_name": "Fores Sena",
    "full_name": "Julio Francisco Fores Sena",
    "gender": "M",
    "address": "Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife",
    "formatted_address": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain",
    "place_of_birth": "Valencia, Valencia",
    "marital_status": "UNKNOWN",
    "nationality": "ESP",
    "extra_fields": {
      "first_surname": "Fores",
      "second_surname": "Sena"
    },
    "mrz": {
      "surname": "FORES SENA",
      "name": "JULIO FRANCISCO",
      "country": "ESP",
      "nationality": "ESP",
      "birth_date": "800113",
      "expiry_date": "320331",
      "sex": "M",
      "document_type": "ID",
      "document_number": "CBX164224",
      "optional_data": "20446581H",
      "optional_data_2": "",
      "birth_date_hash": "9",
      "expiry_date_hash": "8",
      "document_number_hash": "3",
      "final_hash": "3",
      "personal_number": "20446581H",
      "warnings": [],
      "errors": [],
      "mrz_type": "TD1",
      "mrz_string": "IDESPCBX164224320446581H<<<<<<\n8001139M3203318ESP<<<<<<<<<<<3\nFORES<SENA<<JULIO<FRANCISCO<<<",
      "mrz_key": "CBX164224380011393203318"
    },
    "parsed_address": {
      "street_1": "Avenida el Cardonal 52",
      "street_2": "b",
      "city": "La Laguna",
      "region": "Canarias",
      "country": "ES",
      "postal_code": "38108",
      "address_type": "Avenida",
      "formatted_address": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain",
      "raw_results": {
        "address_components": [
          {
            "long_name": "b",
            "short_name": "b",
            "types": [
              "subpremise"
            ]
          },
          {
            "long_name": "52",
            "short_name": "52",
            "types": [
              "street_number"
            ]
          },
          {
            "long_name": "Avenida el Cardonal",
            "short_name": "Av. el Cardonal",
            "types": [
              "route"
            ]
          },
          {
            "long_name": "La Laguna",
            "short_name": "La Laguna",
            "types": [
              "locality",
              "political"
            ]
          },
          {
            "long_name": "Spain",
            "short_name": "ES",
            "types": [
              "country",
              "political"
            ]
          },
          {
            "long_name": "38108",
            "short_name": "38108",
            "types": [
              "postal_code"
            ]
          }
        ],
        "formatted_address": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain",
        "geometry": {
          "location": {
            "lat": 28.4501161,
            "lng": -16.3004407
          },
          "location_type": "ROOFTOP"
        },
        "types": [
          "street_address",
          "subpremise"
        ]
      },
      "document_location": {
        "latitude": 28.4501161,
        "longitude": -16.3004407
      },
      "label": "Spain Identity Card Address",
      "is_verified": true,
      "category": "Residential"
    },
    "warnings": [],
    "barcodes": []
  },
  "vendor_data": "user-123",
  "metadata": {
    "flow": "onboarding"
  },
  "created_at": "2026-06-12T02:21:56.013573+00:00"
}

Authorizations

​
x-api-key
string
header
required

Body

multipart/form-data
​
front_image
file
required

Front side of the identity document. Allowed extensions: tiff, jpg, jpeg, png, webp, pdf. Maximum upload size: 10 MB (larger files are rejected with 400). PDFs are rendered to an image before OCR; encrypted PDFs require front_image_password. Images are automatically compressed to ~0.5 MB and EXIF orientation is applied. Upload the full, uncropped capture with all four corners of the document visible.

​
front_image_password
string
write-only

Password to decrypt front_image when it is an encrypted PDF. Sending an encrypted PDF without (or with a wrong) password returns 400.

​
back_image
file

Back side of the document — send it whenever the document has one (many ID cards carry the MRZ or a barcode on the back; omitting it simply leaves the MRZ and back-side fields empty in the response — this endpoint does not raise a missing-MRZ warning). Same format and size limits as front_image. When omitted, back_image and back-side fields are null in the response.

​
back_image_password
string
write-only

Password to decrypt back_image when it is an encrypted PDF.

​
perform_document_liveness
boolean
default:false

When true, also screens both images for presentation fraud: screen replays (SCREEN_CAPTURE_DETECTED), printed copies (PRINTED_COPY_DETECTED), and portrait manipulation (PORTRAIT_MANIPULATION_DETECTED). Any of these auto-declines. Adds latency, so enable it only when you need fraud screening.

Example:

true

​
minimum_age
integer | null

Accepted and validated (1–120) but currently not applied by this endpoint — it never produces a MINIMUM_AGE_NOT_MET warning from this field. Enforce age rules from the returned date_of_birth/age, or use a verification-session workflow with age restrictions.

Required range: 1 <= x <= 120
​
expiration_date_not_detected_action
enum<string>
default:NO_ACTION

What to do when no expiration date can be read (EXPIRATION_DATE_NOT_DETECTED). Default NO_ACTION because many identity documents print no expiry date. Note: a detected and past expiry date always declines (DOCUMENT_EXPIRED), regardless of this option.

Available options:
NO_ACTION,
DECLINE
​
invalid_mrz_action
enum<string>
default:DECLINE

What to do when the extracted MRZ fails check-digit validation (MRZ_VALIDATION_FAILED). A missing MRZ raises no warning on this endpoint. Only relevant for documents that carry an MRZ. REVIEW is not supported on this endpoint and returns 400.

Available options:
NO_ACTION,
DECLINE
​
inconsistent_data_action
enum<string>
default:DECLINE

What to do when extracted data is internally inconsistent: DATA_INCONSISTENT, MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME (visual zone disagrees with the MRZ), or DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS.

Available options:
NO_ACTION,
DECLINE
​
preferred_characters
enum<string>
default:latin

Preferred script for name/address fields on documents that print both Latin and non-Latin text (Arabic, Cyrillic, CJK, …). latin returns transliterated/Latin values; non_latin prefers the native script.

Available options:
latin,
non_latin
​
save_api_request
boolean
default:true

When true (default), persists the call as an API-type session — visible in the Business Console, retrievable via GET /v3/session/{sessionId}/decision/ using the returned request_id, announced through a status.updated webhook, and with document images returned as media URLs. When false, nothing is stored, request_id is a transient UUID, and images are returned inline as base64 JPEG strings.

Example:

true

​
vendor_data
string

Optional opaque string (your internal user id, email, UUID…) stored on the persisted session and echoed back in the response. Use it to correlate API calls with your own records and to filter sessions later.

Example:

"user-123"

​
metadata
object

Optional JSON object stored with the session (when save_api_request=true) and echoed back in the response. In multipart requests, send it as a JSON-encoded string field (e.g. metadata={"flow":"onboarding"}) — it is parsed into an object.

Example:
{ "flow": "onboarding" }

Response

Document processed. id_verification.status is Approved or Declined; every detected issue is itemized in id_verification.warnings. A problematic document still returns 200 with status: "Declined" — inspect the body, not just the HTTP code. When save_api_request=true, request_id is the persisted session id and image fields are short-lived media URLs; with save_api_request=false they are inline base64 JPEG strings.

​
request_id
string<uuid>

Persisted session id when save_api_request=true (usable with GET /v3/session/{sessionId}/decision/); otherwise a transient correlation UUID.

​
id_verification
object
​
vendor_data
string | null

Echo of the vendor_data you sent, or null.

​
metadata
object

Echo of the metadata object you sent, or null.

​
created_at
string<date-time>

ISO 8601 timestamp (UTC) of when the response was generated.