> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an IDV Session

> Initiate a hosted KYC/KYB session and obtain a unique URL for the hosted fronted experience

The redirection link (`HostedUrl`) for the hosted KYC/KYB session must be completed and submitted within 7 days of creation.

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

### Path parameters

<ParamField path="UserId" type="string" required>
  The unique identifier of the user.
</ParamField>

### Body parameters

<ParamField body="ReturnUrl" type="string" required>
  Max. length: 50

  The URL to which the user is returned after the hosted identity verification session, regardless of the outcome.
</ParamField>

<ParamField body="Tag" type="string">
  Max. length: 255 characters

  Custom data that you can add to this object.
</ParamField>

### Responses

<AccordionGroup>
  <Accordion title="200 - Response parameters">
    <ResponseField name="Id" type="string">
      Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)

      The unique identifier of the object.
    </ResponseField>

    <ResponseField name="Tag" type="string">
      Max. length: 255 characters

      Custom data that you can add to this object.
    </ResponseField>

    <ResponseField name="CreationDate" type="Unix timestamp">
      The date and time at which the object was created.
    </ResponseField>

    <ResponseField name="HostedUrl" type="string">
      The URL to redirect the user to for the hosted identity verification session.
    </ResponseField>

    <ResponseField name="Status" type="string">
      The status of the overall IDV Session:

      * `PENDING` – The unique `HostedUrl` for the session has not yet been submitted by the user. This temporary state can transition to `VALIDATED`, `REFUSED`, `REVIEW`, or `EXPIRED`.
      * `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#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 session was not submitted within 7 days of the `CreationDate` and no longer can be. Note however that the `HostedUrl` link remains accessible.
      * `OUT_OF_DATE` – The session is not valid because the user’s KYC/KYB verification status was [downgraded](/guides/users/verification/downgrade) by Mangopay.
    </ResponseField>

    <ResponseField name="ReturnUrl" type="string">
      The URL to which the user is returned after the hosted identity verification session, regardless of the outcome.
    </ResponseField>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="403 - Feature not activated">
    ```json theme={null}
    {
        "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
        "title": "Forbidden",
        "status": 403,
        "traceId": "00-046605fe21abece0903b78483c6dc5dd-099f889c8e09309c-01"
    }
    ```
  </Accordion>

  <Accordion title="400 - User ID not valid">
    ```json theme={null}
    {
        "Message": "Missing or incorrect required parameter",
        "Type": "param_error",
        "Id": "6b5b73cd-6d4c-4ea5-8859-9447dfe2c5b2",
        "Date": 1746458497.0,
        "errors": {
            "UserId": "UserId is not valid"
        }
    }
    ```
  </Accordion>

  <Accordion title="400 - User must be OWNER">
    ```json theme={null}
    {
        "Message": "This feature is only available for users categorised as Owner.",
        "Type": "invalid_action",
        "Id": "49377b80-01b4-4b68-ba8b-99920aaf47a9",
        "Date": 1736344654.0,
        "errors": null
    }
    ```
  </Accordion>

  <Accordion title="400 - Hosted solution not available for PARTNERSHIP user type">
    ```json PARTNERSHIP theme={null}
    {
        "Message": "The LegalUserType PARTNERSHIP is not currently supported in the identity verification process. An event will be skipped. PartnerId: {ClientId}/ UserExternalId: {UserId}",
        "Type": "invalid_action",
        "Id": "58148aa4-57bb-4d61-94e6-c1450116606e",
        "Date": 1746458611.0,
        "errors": null
    }
    ```
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
      "Id": "idnver_01JH2ZK1MKAMG5H2Q20M5K6020",
      "Tag": "Created using the Mangopay API Postman collection",
      "CreationDate": 1736340768,
      "HostedUrl": "https://user-verification.sandbox.mangopay.com/66ebfacebd780d434e8e6a9d?sessionId=677e75212400002f00a6edd0&redirectURL=https%3A%2F%2Fexample.com",
      "Status": "PENDING",
      "ReturnUrl": "https://example.com"
  }
  ```
</ResponseExample>

<RequestExample>
  ```json REST theme={null}
  {
      "ReturnUrl": "https://example.com",
      "Tag": "Created using the Mangopay API Postman collection"
  }
  ```

  ```java Java theme={null}
  import com.mangopay.MangoPayApi;
  import com.mangopay.entities.IdentityVerification;

  public class CreateIdentityVerification {
      public static void main(String[] args) throws Exception {
          MangoPayApi mangopay = new MangoPayApi();
          mangopay.getConfig().setClientId("your-client-id");
          mangopay.getConfig().setClientPassword("your-api-key");

          String userId = "user_m_01KMD8QZHCVY2VPYV020RDBZGA";
          IdentityVerification dto = new IdentityVerification()
              .setReturnUrl("https://example.com");
          
          // optional Tag
          dto.setTag("Created by the Java SDK");

          IdentityVerification result = mangopay.getIdentityVerificationApi().create(dto, userId);
      }
  }
  ```

  ```javascript NodeJS theme={null}
  const mangopayInstance = require('mangopay4-nodejs-sdk');
  const mangopay = new mangopayInstance({
      clientId: 'your-client-id',
      clientApiKey: 'your-api-key',
  });

  const dto = {
      "ReturnUrl": "https://example.com",
      // optional Tag
      "Tag": "Created using the NodeJS SDK"
  };

  const userId = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA';

  const createIdentityVerification = async (userId) => {
      return await mangopay.IdentityVerifications.create(userId, dto)
          .then((response) => {
              console.info(response);
              return response;
          })
          .catch((err) => {
              console.log(err);
              return false;
          });
  };

  createIdentityVerification(userId);
  ```

  ```ruby Ruby theme={null}
  require 'mangopay'

  MangoPay.configure do |client|
    client.preproduction = true
    client.client_id = 'your-client-id'
    client.client_apiKey = 'your-api-key'
    client.log_file = File.join(Dir.pwd, 'mangopay.log')
  end

  def create_identity_verification(dto, user_id)
    begin
      response = MangoPay::IdentityVerification.create(dto, user_id)
      puts response
      return response
    rescue MangoPay::ResponseError => error
      puts "Failed to create IdentityVerification: #{error.message}"
      puts "Error details: #{error.details}"
      return false
    end
  end

  user_id = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'

  dto = {
    ReturnUrl: 'https://example.com',
    # optional Tag
    Tag: 'created by the Ruby SDK'
  }

  create_identity_verification(dto, user_id)
  ```

  ```python Python theme={null}
  import mangopay

  mangopay.client_id='your-client-id'
  mangopay.apikey='your-api-key'

  from mangopay.api import APIRequest
  handler = APIRequest(sandbox=True)

  from mangopay.resources import IdentityVerification

  user_id = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA'

  dto = IdentityVerification(
      return_url = "https://example.com",
      # optional Tag
      tag = "created by the Python SDK"
  )

  result = dto.create(user_id)
  ```

  ```php PHP theme={null}
  <?php

  require_once 'vendor/autoload.php';

  use MangoPay\IdentityVerification;
  use MangoPay\Libraries\Exception as MGPException;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\MangoPayApi;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';

  try {
      $userId = 'user_m_01KMD8QZHCVY2VPYV020RDBZGA';

      $dto = new IdentityVerification();
      $dto->ReturnUrl = "https://example.com";
      // optional Tag
      $dto->Tag = "Created by the PHP SDK";

      $response = $api->IdentityVerifications->Create($dto, $userId);

      print_r($response);
  } catch (MGPResponseException $e) {
      print_r($e);
  } catch (MGPException $e) {
      print_r($e);
  }
  ```

  ```csharp .NET theme={null}
  using System.Threading.Tasks;
  using MangoPay.SDK;
  using MangoPay.SDK.Entities.POST;

  class CreateIdentityVerification
  {
      static async Task Main(string[] args)
      {
          MangoPayApi api = new MangoPayApi();

          api.Config.ClientId = "your-client-id";
          api.Config.ClientPassword = "your-api-key";

          var userId = "user_m_01KMD8QZHCVY2VPYV020RDBZGA";

          IdentityVerificationPostDto postDto = new IdentityVerificationPostDto
          {
              ReturnUrl = "https://example.com",
              // optional Tag
              Tag = "Created by the .NET SDK"
          };

          var result = await api.IdentityVerifications.CreateAsync(postDto, userId);
      }
  }
  ```
</RequestExample>