Skip to main content
POST
/
v2.01
/
{ClientId}
/
users
/
{UserId}
/
identity-verifications
{
    "ReturnUrl": "https://example.com",
    "Tag": "Created using the Mangopay API Postman collection"
}

{
    "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"
}
Note – Activation requiredThe hosted KYC/KYB verification feature must be activated by Mangopay. Contact our teams via the Dashboard to get started.
Note – Available for Natural, Soletrader, and BusinessAn IDV Session can only be created for Natural and Legal Users whose UserCategory is OWNER.For Legal users, the feature is only available for LegalPersonType values BUSINESS and SOLETRADER.

​
Path parameters

​
UserId
string
required
The unique identifier of the user.

​
Body parameters

​
ReturnUrl
string
required
Max. length: 500The URL to which the user is returned after the hosted identity verification session, regardless of the outcome.
​
Tag
string
Max. length: 255 charactersCustom data that you can add to this object.

​
Responses

​
Id
string
Max length: 128 characters (see data formats for details)The unique identifier of the object.
​
Tag
string
Max. length: 255 charactersCustom data that you can add to this object.
​
CreationDate
Unix timestamp
The date and time at which 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 – The unique HostedUrl for the session has not yet been submitted by the user. This temporary state can transition to VALIDATED, REFUSED, or REVIEW.
  • 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 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 and comment (which is custom text in the case of manual review for Legal users).
  • OUT_OF_DATE – The session is not valid because the user’s KYC/KYB verification status was downgraded by Mangopay.
​
ReturnUrl
string
Max. length: 500The URL to which the user is returned after the hosted identity verification session, regardless of the outcome.
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
    "title": "Forbidden",
    "status": 403,
    "traceId": "00-046605fe21abece0903b78483c6dc5dd-099f889c8e09309c-01"
}

{
    "Message": "Missing or incorrect required parameter",
    "Type": "param_error",
    "Id": "6b5b73cd-6d4c-4ea5-8859-9447dfe2c5b2",
    "Date": 1746458497.0,
    "errors": {
        "UserId": "UserId is not valid"
    }
}

{
    "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
}

{
    "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"
}

{
    "ReturnUrl": "https://example.com",
    "Tag": "Created using the Mangopay API Postman collection"
}