---
title: "Create a Legal User"
method: POST
path: "/v2.01/{ClientId}/users/legal"
tags: ["Users"]
---

# Create a Legal User

`POST /v2.01/{ClientId}/users/legal`

<Warning icon="fa-regular fa-triangle-exclamation">
**Caution - Deprecated endpoint**

The legacy User endpoints are deprecated. This endpoint will stop working and return an error after **Dec 15, 2025**.

These endpoints were made redundant by the equivalent SCA-enabled endpoints during the introduction of SCA. 

Instead of calling this endpoint for user creation, your platform must call [POST Create a Legal User (SCA)](/api-reference/users/create-legal-user-sca).
</Warning>

<Note icon="fa-regular fa-circle-info">
**Note – Country-based restrictions apply to users**

Due to Mangopay's [country restrictions](/guides/users/country-restrictions), it is not possible to use blocked countries as the following:
- `HeadquartersAddress.Country`
- `LegalRepresentativeNationality`
- `LegalRepresentativeCountryOfResidence`
- `LegalRepresentativeAddress.Country`
</Note>

Create a Legal User

## Path parameters

- `ClientId` string, required

## Headers

- `Authorization` string, required

## Request body

- CreateALegalUserRequest
  - `UserCategory` string, required — **Allowed values:** `PAYER`, `OWNER` The [category](/guides/users/categories) of the user: - `PAYER` – User who can only make pay-ins to their wallets and transfers to other wallets (as well as refunds for pay-ins and transfers). - `OWNER` – User who can also receive transfers to their wallets. Owners are able to request [KYC verification](/guides/users/verification), which if successful gives them the `KYCLevel` of `REGULAR` and the ability to request payouts.
  - `TermsAndConditionsAccepted` boolean, required — Whether the user has accepted Mangopay's terms and conditions (as defined by your contract, see the [T&Cs guide](/guides/users/terms) for details). Must be `true` if `UserCategory` is `OWNER`.
  - `LegalPersonType` string, required — **Allowed values:** BUSINESS, PARTNERSHIP, ORGANIZATION, SOLETRADER The type of legal user. For information on which `LegalPersonType` to use for a particular local legal structure, see the <a href="/guides/users/verification/requirements" target="_blank">verification requirements</a>. **Caution:** Modification of the `LegalPersonType` may result in a <a href="/guides/users/verification/downgrade" target="_blank">verification downgrade</a>.
  - `Name` string, required — Max. length: 255 characters The registered legal name of the entity. The `Name` value should be the one registered with the relevant national authority.
  - `Email` string, required — Format: A valid email address The email address for the entity.
  - `HeadquartersAddress` AddressSubPropsRequired — The postal address.
    - `AddressLine1` string, required — The first line of the address.
    - `AddressLine2` string — The second line of the address.
    - `City` string, required — The city of the address.
    - `Region` string — Required if `Country` is US, CA, or MX. The region of the address.
    - `PostalCode` string, required — The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.
    - `Country` string, required — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address.
  - `CompanyNumber` string — Required if `UserCategory` is `OWNER` and `LegalPersonType` is `BUSINESS`. Returned `null` if `UserCategory` is `PAYER`. The registration number of the entity, assigned by the relevant national authority. For information on the expected format for a specific country, see the [Company number](/guides/users/verification/company-number) guide. To validate the format of a number before submitting documents for verification, use [POST Validate the format of User data](/api-reference/user-data-format/validate-user-data-format).
  - `LegalRepresentativeFirstName` string, required — _Min length: 1; max. length: 100_ The first name of the entity's legal representative.
  - `LegalRepresentativeLastName` string, required — _Min length: 1; max. length: 100_ The last name of the entity's legal representative.
  - `LegalRepresentativeEmail` string — Format: A valid email address The email address of the entity’s legal representative. Returned `null` if `UserCategory` is `PAYER`.
  - `LegalRepresentativeBirthday` integer — Required if `UserCategory` is `OWNER`. Returned `null` if `UserCategory` is `PAYER`. The date of birth of the entity’s legal representative. **Note:** This is a Unix timestamp in UTC. Ensure you convert your timezone to UTC to avoid midnight being interpreted as the day before.
  - `LegalRepresentativeNationality` string — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) Required if `UserCategory` is `OWNER`. Returned `null` if `UserCategory` is `PAYER`. The nationality of the entity’s legal representative.
  - `LegalRepresentativeCountryOfResidence` string — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) Required if `UserCategory` is `OWNER`. Returned `null` if `UserCategory` is `PAYER`. The country of residence of the entity’s legal representative.
  - `LegalRepresentativeAddress` AddressSubPropsRequired — The postal address.
    - `AddressLine1` string, required — The first line of the address.
    - `AddressLine2` string — The second line of the address.
    - `City` string, required — The city of the address.
    - `Region` string — Required if `Country` is US, CA, or MX. The region of the address.
    - `PostalCode` string, required — The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.
    - `Country` string, required — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address.
  - `Tag` string — Max. length: 255 characters Custom data that you can add to this object.

## Response `200`

Success

- LegalUserResponse
  - `HeadquartersAddress` Address — The postal address.
    - `AddressLine1` string — The first line of the address.
    - `AddressLine2` string — The second line of the address.
    - `City` string — The city of the address.
    - `Region` string — Required if `Country` is US, CA, or MX. The region of the address.
    - `PostalCode` string — The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.
    - `Country` string — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address.
  - `LegalRepresentativeAddress` Address — The postal address.
    - `AddressLine1` string — The first line of the address.
    - `AddressLine2` string — The second line of the address.
    - `City` string — The city of the address.
    - `Region` string — Required if `Country` is US, CA, or MX. The region of the address.
    - `PostalCode` string — The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.
    - `Country` string — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address.
  - `Name` string — Max. length: 255 characters The registered legal name of the entity. The `Name` value should be the one registered with the relevant national authority.
  - `LegalPersonType` string — **Returned values:** BUSINESS, PARTNERSHIP, ORGANIZATION, SOLETRADER The type of legal user. For information on which `LegalPersonType` to use for a particular local legal structure, see the <a href="/guides/users/verification/requirements" target="_blank">verification requirements</a>. **Caution:** Modification of the `LegalPersonType` may result in a <a href="/guides/users/verification/downgrade" target="_blank">verification downgrade</a>.
  - `LegalRepresentativeFirstName` string — Min. length: 1; max. length: 100 The first name of the entity’s legal representative.
  - `LegalRepresentativeLastName` string — Min. length: 1; max. length: 100 The last name of the entity’s legal representative.
  - `LegalRepresentativeEmail` string — Format: A valid email address The email address of the entity’s legal representative. Returned `null` if `UserCategory` is `PAYER`.
  - `LegalRepresentativeBirthday` integer — The date of birth of the entity’s legal representative. Returned `null` if `UserCategory` is `PAYER`. **Note:** This is a Unix timestamp in UTC. Ensure you convert your timezone to UTC to avoid midnight being interpreted as the day before.
  - `LegalRepresentativeNationality` string — Returned `null` if `UserCategory` is `PAYER`. The nationality of the entity’s legal representative.
  - `LegalRepresentativeCountryOfResidence` string — Returned `null` if `UserCategory` is `PAYER`. The country of residence of the entity’s legal representative.
  - `ProofOfRegistration` string — The `Id` of the KYC Document whose `Type` is `REGISTRATION_PROOF` if validated for the user. If no registration proof is validated, then this value is `null`.
  - `ShareholderDeclaration` string — The `Id` of the KYC Document whose `Type` is `SHAREHOLDERS_DECLARATION` if validated for the user. If no Shareholder Declaration is validated, then this value is `null`.
  - `Statute` string — The `Id` of the KYC Document whose `Type` is `ARTICLES_OF_ASSOCIATION` if validated for the user. If no articles of association document is validated, then this value is `null`.
  - `LegalRepresentativeProofOfIdentity` string — The `Id` of the KYC Document whose `Type` is `IDENTITY_PROOF` if validated for the user. If no identity proof is validated, then this value is `null`.
  - `CompanyNumber` string — Required if `UserCategory` is `OWNER` and `LegalPersonType` is `BUSINESS`. Returned `null` if `UserCategory` is `PAYER`. The registration number of the entity, assigned by the relevant national authority. For information on the expected format for a specific country, see the [Company number](/guides/users/verification/company-number) guide. To validate the format of a number before submitting documents for verification, use [POST Validate the format of User data](/api-reference/user-data-format/validate-user-data-format).
  - `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.
  - `PersonType` string — **Returned values:** NATURAL, LEGAL The type of the user: - `NATURAL` – Natural users are individuals (natural persons). - `LEGAL` – Legal users are legal entities (legal persons) like companies, non-profits, and sole proprietors. The `PersonType` is defined by the endpoint used to create the user and can’t be modified.
  - `Email` string — Format: A valid email address The email address for the entity.
  - `KYCLevel` string — **Default value:** `LIGHT` **Returned values:** `LIGHT`, `REGULAR` The verification status of the user set by Mangopay: - `LIGHT` – Unverified, assigned by default to all users. - `REGULAR` – Verified, meaning the user has successfully completed the verification process and had the necessary documents validated by Mangopay. Only users whose `UserCategory` is `OWNER` can submit verification documents for validation. Only users whose `KYCLevel` is `REGULAR` can request payouts.
  - `TermsAndConditionsAccepted` boolean — Whether the user has accepted Mangopay's terms and conditions (as defined by your contract, see the [T&Cs guide](/guides/users/terms) for details). Must be `true` if `UserCategory` is `OWNER`.
  - `TermsAndConditionsAcceptedDate` integer — Unix timestamp (UTC) of the date and time the `TermsAndConditionsAccepted` value was set to `true`. Returned `null` if `UserCategory` is `PAYER`.
  - `UserCategory` string — **Possible values:** `PAYER`, `OWNER`, `PLATFORM` The [category](/guides/users/categories) of the user: - `PAYER` – User who can only make pay-ins to their wallets and transfers to other wallets (as well as refunds for pay-ins and transfers). - `OWNER` – User who can also receive transfers to their wallets. Owners are able to request [KYC verification](/guides/users/verification), which if successful gives them the `KYCLevel` of `REGULAR` and the ability to request payouts. - `PLATFORM` – Single specific user that represents the platform. The `PLATFORM` value is only assigned by Mangopay and may be used as part of the validated workflow implemented by the platform.
  - `UserStatus` string — **Returned values:** ACTIVE, CLOSED Internal use only. This field can only be used and updated by Mangopay teams.

---

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