---
title: "Initiate a new Identity Document Verification"
method: POST
path: "/verifications/identity_documents"
tags: ["Identity Document Verification"]
---

# Initiate a new Identity Document Verification

`POST /verifications/identity_documents`

Verify a person's Identity Document by sending the file containing their Identity Document (identity card, passport, residence permit or driving license).

An Image Identity Verification can be requested as follows:
- **Verification with names**: This option checks both the validity of the ID document and the coherence between the names provided and those on the document.
- **Verification without names**: This option only checks the validity of the ID document.

Related guide: [Image Identity Verification](https://developers.youtrust.com/docs/identity-document-verification)

**ℹ️ This endpoint accepts two request body formats — pick the one that matches your use case:**
- 📁 `multipart/form-data` — upload a binary file containing the Identity Document.
- 📝 `application/json` — reference an existing Workflow Session Applicant by ID.

**🔓 Endpoint access**
- Environments: `production`, `sandbox`
- API key scopes: `organization`, `workspace`
- Plans: `pro`, `scale`
- Add-ons (for production access): `Verify - Image identity verification`

## Request body

- InitiateIdentityDocumentFromApplicant
  - `applicant_id` string, uuid, required — The Applicant ID linked to the Workflow Session.

## Response `201`

Created

- IdentityDocumentFull
  - `id` string, uuid, required — The unique identifier for a resource.
  - `workspace_id` string, uuid, required — The Workspace ID in which the verification has been created.
  - `created_at` string, date-time, required — Creation date of the Identity Document Verification.
  - `updated_at` string, date-time, required — Update date of the Identity Document Verification.
  - `status` 'pending' | 'awaiting_data' | 'verified' | 'failed' | 'inconclusive', required — Status of the Identity Document Verification
  - `status_codes` string[], required — List of status codes. Indicates the cause when the status is `failed` or `inconclusive`.
  - `data_anonymized` boolean, required — Indicates if the personal data extracted from the document has been anonymized. If set to `true`, the personal data has been anonymized and most fields will be NULL.
  - `workflow_session_id` string, uuid, nullable, required — Unique identifier of a Workflow Session. When provided, an Action is created in the Workflow Session, and this resource is associated with that Action.
  - `previous_attempt_id` string, uuid, nullable, required — ID of the previous attempt within the same `workflow_session_id`. Allows continuity between multiple attempts of the same Action. Null if this is the first attempt.
  - `applicant_id` string, uuid, nullable, required — Unique identifier of an Applicant.
  - `data` IdentityDocumentFullAllOfData, required
    - `extracted_from_document` IdentityDocumentFullAllOfDataExtractedFromDocument, required — Information extracted from the verified identity document
      - `first_name` string, nullable, required — The document holder's first name as it appears on the identity document
      - `birth_name` string, nullable, required — The document holder's birth name (family name at birth)
      - `last_name` string, nullable, required — The document holder's current last name (may differ from birth name)
      - `born_on` string, date, nullable, required — The document holder's date of birth as it appears on the document
      - `birth_location` string, nullable, required — The holder's place of birth as it appears on the document
      - `gender` 'f' | 'm' | 'x' | 'null', nullable, required — The holder's gender as it appears on the document. "m" for Male, "f" for Female, "x" for Non-binary or unspecified.
      - `full_address` string, nullable, required — The holder's complete postal address as it appears on the document
      - `type` 'id_card' | 'passport' | 'residence_permit' | 'ita_ts_cns' | 'null', nullable, required — The type of identity document that was verified
      - `issuing_country_code` string, ISO 3166-1 alpha-2, nullable, required — The country that issued the document (ISO 3166-1 alpha-2 code)
      - `issued_on` string, date, nullable, required — The date when the document was issued
      - `expired_on` string, date, nullable, required — The date when the document legally expires
      - `document_number` string, nullable, required — Document identifier number (may contain letters)
      - `mrz` IdentityDocumentFullAllOfDataExtractedFromDocumentMrz, required — Machine Readable Zone content
        - `line1` string, nullable, required — MRZ line 1
        - `line2` string, nullable, required — MRZ line 2
        - `line3` string, nullable, required — MRZ line 3
      - `national_identification_number` string, nullable, required — Some documents may contain a national identification number. For example, Italian ID cards contain the Codice Fiscale on the back of the document. When this data is available on the document, it will be returned here, otherwise it will be NULL. Consult our [guide](https://developers.youtrust.com/docs/identity-document-verification) for more details and examples.

## Other responses

- `400` — Bad request
- `401` — Access unauthorized
- `403` — Access forbidden
- `405` — This method is not allowed
- `415` — UnsupportedMediaType
- `429` — Too Many Requests, please try again later.
- `500` — Internal Server Error

---

[API](https://skmtc.net/yousign/apis/public-api-v3.md) · [All operations](https://skmtc.net/yousign/apis/public-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yousign/public-api-v3/revisions/8d258c0b45d6/schema)