> ## 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.

# The IDV Session object

> Container for Mangopay's hosted KYC/KYB solution

### Description

Mangopay relies on the IDV Session object to provide its hosted KYC/KYB verification solution. The object contains the unique session URL for the hosted frontend experience where the user can provide all the necessary data and documents for verification. [Read more](/guides/users/verification/hosted) **→**

### Attributes

<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="HostedUrl" type="string">
  The URL to redirect the user to for the hosted identity verification session.
</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>

<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="UserId" type="string">
  The unique identifier of the user.
</ResponseField>

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

<ResponseField name="LastUpdate" type="Unix timestamp">
  The date and time at which the session was last updated.
</ResponseField>

<ResponseField name="Checks" type="array (object)" defaultOpen>
  The checks performed automatically during the session.

  This array is empty when `Status` is `PENDING` and may contain any number of objects depending on the outcome.

  <Expandable title="properties">
    <ResponseField name="CheckId" type="string">
      The unique identifier of the verification check.
    </ResponseField>

    <ResponseField name="Type" type="string">
      Type of check carried out during the session depending on the user type:

      * `IDENTITY_DOCUMENT_VERIFICATION` - Verifies the authenticity of the identity document, the liveness of the selfie, and that the selfie matches the identity document photo.
      * `IDV_AGE_CHECK` - Checks whether the individual on the identity document meets the minimum age requirement for Mangopay users (age 18).
      * `BUSINESS_VERIFICATION` - Looks up the business details entered by the user during the session in the national registry to find a match.
      * `IDV_NAME_MATCH_CHECK` - Checks whether the first name, last name and date of birth of the identity document match the `FirstName`, `LastName`, and `Birthday` of the Natural user object or `LegalRepresentative` of the Legal user object.
      * `BUSINESS_NAME_MATCH` - Checks whether the name on the identity document is present in the name of the registered sole proprietor in the relevant national registry.
      * `BUSINESS_INSIGHTS_MATCH` - Checks whether the name on the identity document matches one of the directors listed in the national registry, and whether the PSC data declared in the session is coherent with the PSC data in the registry.

      For information on which checks are performed for which user type and in which cases, see the dedicated guides: [Natural](/guides/users/verification/hosted/natural), [Soletrader](/guides/users/verification/hosted/soletrader), [Business](/guides/users/verification/hosted/business), [Organization](/guides/users/verification/hosted/organization).
    </ResponseField>

    <ResponseField name="CheckStatus" type="string">
      **Returned values:** `VALIDATED`, `REFUSED`

      The status of the verification check.
    </ResponseField>

    <ResponseField name="Reasons" type="array (object)">
      The reasons that the check was refused, which may be returned if `CheckStatus` was `REFUSED` (depending on the check type).

      <Expandable title="properties">
        <ResponseField name="Type" type="string">
          The type of the reason. For more details, see [refusals](/guides/users/verification/hosted#refusals).
        </ResponseField>

        <ResponseField name="Value" type="string">
          The explanation of the reason. If the refusal was automatic, this is a preset string. For Legal users, if the refusal follows a manual review, this is a custom explanation from the person who conducted the review.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

    <ResponseField name="LastUpdate" type="Unix timestamp">
      The date and time at which the check was last updated.
    </ResponseField>

    <ResponseField name="Data" type="array (object)">
      The data extracted and verified during the check.

      This array may be empty if no data was extracted or is not applicable for the check.

      <Expandable title="properties">
        <ResponseField name="Type" type="string">
          The type of the data.

          For a Natural user:

          * `FIRST_NAME`
          * `LAST_NAME`
          * `BIRTHDATE`

          For a Legal user:

          * `COMPANY_NAME`
          * `COMPANY_NUMBER`
          * `LEGAL_REPRESENTATIVE_FIRST_NAME`
          * `LEGAL_REPRESENTATIVE_LAST_NAME`
          * `LEGAL_REPRESENTATIVE_BIRTHDATE`
        </ResponseField>

        <ResponseField name="Value" type="string">
          The value of the data. The value may be `null` or an empty string if data extraction was not possible but the check was still carried out.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>