---
title: "Create an IDV Session"
method: POST
path: "/v2.01/{ClientId}/users/{UserId}/identity-verifications"
tags: ["idvSessions"]
---

# Create an IDV Session

`POST /v2.01/{ClientId}/users/{UserId}/identity-verifications`

Initiate a hosted KYC/KYB session and obtain a unique URL for the hosted frontend experience.

By default, the returned `HostedUrl` must be completed and submitted within 7 days of creation. If the session contains a liveness step and that step has been started (the QR code was generated), the session instead expires 1 hour after the liveness step started.

The steps presented to the user depend on their [User type](/guides/users/types): [Natural](/guides/users/verification/hosted/natural), [Soletrader](/guides/users/verification/hosted/soletrader), and [Business and Organization](/guides/users/verification/hosted/business) (or [Business - Legacy](/guides/users/verification/hosted/business-legacy) / [Organization - Legacy](/guides/users/verification/hosted/organization-legacy)).
If the user already has an IDV Session with a `Status` of `PENDING`, that existing session is returned instead of creating a new one.

[Read more about hosted KYC/KYB](/guides/users/verification/hosted) **→**

## Path parameters

- `ClientId` string, required
- `UserId` string, required

## Headers

- `Authorization` string, required

## Request body

- CreateAnIDVSessionRequest
  - `ReturnUrl` string, required — Max. length: 50 The URL to which the user is returned after the hosted identity verification session, regardless of the outcome.
  - `Tag` string — Max. length: 255 characters Custom data that you can add to this object.

## Response `200`

Success

- CreateAnIDVSessionResponse
  - `Id` string — Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details) The unique identifier of the object.
  - `Tag` string — Max. length: 255 characters Custom data that you can add to this object.
  - `CreationDate` integer — Unix timestamp (UTC) of the date and time the object was created.
  - `HostedUrl` string — The URL to redirect the user to for the hosted identity verification session.
  - `Status` string — The status of the overall IDV Session: - `PENDING` – Session created. The `HostedUrl` is valid for completion, regardless of whether the user has started or submitted the session. - `REVIEW` – One or more automated checks was neither successful nor refused, so the session was sent for manual review by Mangopay's teams. This temporary state is only applicable to Legal users and can transition to `REFUSED` or `VALIDATED`. - `VALIDATED` – - The session was validated and the User became KYC/KYB verified (indicated by the User object's `KYCLevel`). When the `Status` changes to `VALIDATED`, the [verified data](/guides/users/verification/hosted/natural#verified-data) in `Checks.Data` is used to replace existing data in the User object. - `REFUSED` – The session was refused and the User is not KYC/KYB verified. The `Checks.CheckStatus` shows which checks were `REFUSED` and the `Checks.Reasons` shows the [refused reason types](/guides/users/verification/hosted/refusals) and comment (which is custom text in the case of manual review for Legal users). - `EXPIRED` – The IDV Session expired and can no longer be used. By default, this happens 7 days after the `CreationDate`. However, if the IDV Session contains the liveness step and that step has been started (the QR code was generated), the session instead expires 1 hour after the liveness step started. The IDV Session contains the liveness step for Natural users, Soletrader users, and Business/Organization users on the legacy integrated flow. In the multi-session PSC flow, the main IDV Session never contains the liveness step (so it always follows the 7-day rule) – the liveness check is performed in each PSC Session instead, which follows the same 7-day/1-hour rule independently. - `OUT_OF_DATE` – The IDV Session is not valid because the user's KYC/KYB verification status was [downgraded](/guides/users/verification/downgrade) by Mangopay.
  - `ReturnUrl` string — The URL to which the user is returned after the hosted identity verification session, regardless of the outcome.

## Other responses

- `400` — Bad Request
- `403` — Forbidden

---

[API](https://skmtc.dev/mangopay/apis/api-reference.md) · [All operations](https://skmtc.dev/mangopay/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mangopay/api-reference/revisions/fafbd0c69654/schema)