--- title: "View a User's Verified Identity" method: GET path: "/v2.01/{ClientId}/users/{UserId}/verified-identity" tags: ["verifiedIdentity"] --- # View a User's Verified Identity `GET /v2.01/{ClientId}/users/{UserId}/verified-identity` Retrieve the identity information and verification documents validated by Mangopay for a user, based on their `UserId`. The payload returned depends on the user's `UserType`, so always branch on this value rather than on the presence of an optional property. The endpoint returns a verified identity only if all the following conditions are met: - The Underwriting API is activated for the `ClientId`. - The user exists for the `ClientId`. - The user's KYC/KYB verification is validated. A user whose verification is not validated returns a 400 error rather than a partial or declared identity. **Note – Feature activation required** This endpoint is available only to platforms for which the Underwriting API is activated, and requires an access token with the `underwriting.user.kyc` read permission. Contact Mangopay to request access. ## Path parameters - `ClientId` string, required - `UserId` string, required ## Headers - `Authorization` string, required ## Response `200` Success - union - NaturalUserVerifiedIdentityResponse — Response if the user's `UserType` is `NATURAL`. Identity properties can be returned `null` even for a user whose KYC/KYB verification is validated, because the data available depends on the verification received for that user. - `ClientId` string — Platform's API account identifier, as sent in the request. - `UserId` string — The unique identifier of the user, as sent in the request. - `UserType` string — **Returned value:** `NATURAL` The type of the user, which determines the payload returned. - `FirstName` string, nullable — The verified first name of the user. - `LastName` string, nullable — The verified last name of the user. - `BirthdayDate` string, nullable — Format: ISO 8601 date-time (for example, `1990-01-01T00:00:00Z`) The verified date of birth of the user. - `Nationality` string, nullable — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The verified nationality of the user. - `CountryOfResidence` string, nullable — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The verified country of residence of the user. - `Address` VerifiedIdentityAddress — The verified postal address. This property is omitted from the response if no usable verified address is available. - `AddressLine1` string, nullable — The first line of the address. - `AddressLine2` string, nullable — The second line of the address. - `City` string, nullable — The city of the address. - `Region` string, nullable — The state, region, or province of the address. - `PostalCode` string, nullable — The postal code of the address. - `Country` string, nullable — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address. - `Documents` VerifiedIdentityDocument[] — The non-expired verification documents of the user. The array is empty if no document is returned. - `DocumentType` string — **Example value:** `IDENTITY_PROOF` The type of the verification document. Treat this as an extensible value, because further values can be returned. - `Status` string — **Example value:** `VALIDATED` The status returned for the document. Treat this as an extensible value, because further values can be returned. - `DocumentExpiryDate` string, nullable — Format: ISO 8601 date-time (for example, `2030-06-30T00:00:00Z`) The expiry date of the document, if applicable. - `DocumentUrls` string[] — The signed download URLs of the pages of the document, in page order. Each URL is generated when the endpoint is called and grants access for a limited validity period only, which is not returned as a separate property. Download the document before the URL expires, and call the endpoint again to obtain a new URL if you need access afterwards. Do not cache, persist, or share these URLs, and do not use them as document identifiers. - LegalUserVerifiedIdentityResponse — Response if the user's `UserType` is `LEGAL_BUSINESS`, `LEGAL_ORGANIZATION`, `LEGAL_PARTNERSHIP`, or `LEGAL_SOLETRADER`. Identity properties can be returned `null` even for a user whose KYC/KYB verification is validated, because the data available depends on the verification received for that user. - `ClientId` string — Platform's API account identifier, as sent in the request. - `UserId` string — The unique identifier of the user, as sent in the request. - `UserType` string — **Returned values:** `LEGAL_BUSINESS`, `LEGAL_ORGANIZATION`, `LEGAL_PARTNERSHIP`, `LEGAL_SOLETRADER` The type of the user, which determines the payload returned. - `CompanyName` string, nullable — The verified name of the company. - `CompanyNumber` string — The verified registration number of the company. This property is omitted from the response if the company number is unavailable. - `HeadquartersAddress` VerifiedIdentityAddress — The verified postal address. This property is omitted from the response if no usable verified address is available. - `AddressLine1` string, nullable — The first line of the address. - `AddressLine2` string, nullable — The second line of the address. - `City` string, nullable — The city of the address. - `Region` string, nullable — The state, region, or province of the address. - `PostalCode` string, nullable — The postal code of the address. - `Country` string, nullable — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address. - `LegalRepresentatives` VerifiedIdentityLegalRepresentative[] — The verified legal representatives of the company, returned for users verified with [KYC Documents](/api-reference/kyc-documents/kyc-document-object). It represents the legal representative verified in the main verification session, and currently contains zero or one legal representative. Users verified with the [hosted KYC/KYB solution](/guides/users/verification/hosted) return their persons with significant control (PSCs) in `Pscs` instead, so do not rely on `LegalRepresentatives` being populated for them. - `FirstName` string, nullable — The verified first name of the legal representative. - `LastName` string, nullable — The verified last name of the legal representative. - `BirthdayDate` string, nullable — Format: ISO 8601 date-time (for example, `1985-05-15T00:00:00Z`) The verified date of birth of the legal representative. - `Nationality` string, nullable — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The verified nationality of the legal representative. - `CountryOfResidence` string, nullable — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The verified country of residence of the legal representative. - `Documents` VerifiedIdentityDocument[] — The non-expired documents of the main verification session, which for a Legal User is the legal representative's session. The array is empty if no document is returned. - `DocumentType` string — **Example value:** `IDENTITY_PROOF` The type of the verification document. Treat this as an extensible value, because further values can be returned. - `Status` string — **Example value:** `VALIDATED` The status returned for the document. Treat this as an extensible value, because further values can be returned. - `DocumentExpiryDate` string, nullable — Format: ISO 8601 date-time (for example, `2030-06-30T00:00:00Z`) The expiry date of the document, if applicable. - `DocumentUrls` string[] — The signed download URLs of the pages of the document, in page order. Each URL is generated when the endpoint is called and grants access for a limited validity period only, which is not returned as a separate property. Download the document before the URL expires, and call the endpoint again to obtain a new URL if you need access afterwards. Do not cache, persist, or share these URLs, and do not use them as document identifiers. - `Pscs` VerifiedIdentityPSC[] — The verified persons with significant control (PSCs) of the company and their documents, returned for users verified with the [hosted KYC/KYB solution](/guides/users/verification/hosted). The array is empty if no PSC is returned. Do not use `LegalRepresentatives` as a substitute for the data returned in `Pscs`. - `PscExternalId` string — The unique identifier of the PSC. - `PscType` string — **Example values:** `DIRECTOR`, `SHAREHOLDER` The role or type of the PSC. Treat this as an extensible value, because further values can be returned. - `FirstName` string, nullable — The verified first name of the PSC. - `LastName` string, nullable — The verified last name of the PSC. - `BirthdayDate` string, nullable — Format: ISO 8601 date-time (for example, `1978-09-20T00:00:00Z`) The verified date of birth of the PSC. - `Nationality` string, nullable — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The verified nationality of the PSC. - `CountryOfResidence` string, nullable — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The verified country of residence of the PSC. - `Documents` VerifiedIdentityDocument[] — The non-expired verification documents of the PSC. The array is empty if no document is returned. - `DocumentType` string — **Example value:** `IDENTITY_PROOF` The type of the verification document. Treat this as an extensible value, because further values can be returned. - `Status` string — **Example value:** `VALIDATED` The status returned for the document. Treat this as an extensible value, because further values can be returned. - `DocumentExpiryDate` string, nullable — Format: ISO 8601 date-time (for example, `2030-06-30T00:00:00Z`) The expiry date of the document, if applicable. - `DocumentUrls` string[] — The signed download URLs of the pages of the document, in page order. Each URL is generated when the endpoint is called and grants access for a limited validity period only, which is not returned as a separate property. Download the document before the URL expires, and call the endpoint again to obtain a new URL if you need access afterwards. Do not cache, persist, or share these URLs, and do not use them as document identifiers. ## Other responses - `400` — Bad Request Returned if the `ClientId` or `UserId` is incorrect, or if the user's KYC/KYB verification is not validated. - `403` — Forbidden Returned if the access token does not have the `underwriting.user.kyc` permission, or if the Underwriting API is not activated for the platform. - `404` — Not Found Returned if the user cannot be found for the platform, or if the user's verification documents cannot be retrieved. ## Changes - **2026-08-21** `0ace9cb630b1` — 1 info - endpoint added [Change history](https://skmtc.dev/mangopay/apis/api-reference/changes/v2.01/:ClientId/users/:UserId/verified-identity/get.md) --- [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)