> ## 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 Legal User object

<Warning>
  **Caution - Deprecated endpoints**

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

  These endpoints were made redundant by the equivalent [SCA-enabled endpoints](/api-reference/users/legal-user-object-sca) during the introduction of SCA.
</Warning>

The Legal User object represents a legal entity (legal person) like a company, non-profit or sole proprietor (read more about user [types](/guides/users/types)).

Mangopay users have one of two [categories](/guides/users/categories), indicated by `UserCategory`:

* `PAYER` – User who can only make pay-ins to their wallets and transfers to other wallets.
* `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.

### Attributes

<ParamField body="HeadquartersAddress" type="object">
  The legally registered address of the entity’s administrative center.\
  This object’s sub-parameters are `null` if the `UserCategory` is `PAYER`.

  <Expandable title="properties">
    <ParamField body="AddressLine1" type="string">
      Max. length: 255 characters

      The first line of the address.
    </ParamField>

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

      The second line of the address.
    </ParamField>

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

      The city of the address.
    </ParamField>

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

      Required if `Country` is US, CA, or MX.

      The region of the address.
    </ParamField>

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

      The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.
    </ParamField>

    <ParamField body="Country" type="string">
      Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))

      The country of the address.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="LegalRepresentativeAddress" type="object">
  The address of the entity’s legal representative.

  <Expandable title="properties">
    <ParamField body="AddressLine1" type="string">
      Max. length: 255 characters

      The first line of the address.
    </ParamField>

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

      The second line of the address.
    </ParamField>

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

      The city of the address.
    </ParamField>

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

      Required if `Country` is US, CA, or MX.

      The region of the address.
    </ParamField>

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

      The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.
    </ParamField>

    <ParamField body="Country" type="string">
      Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))

      The country of the address.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="Name" type="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.
</ParamField>

<ParamField body="LegalPersonType" type="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>.
</ParamField>

<ParamField body="LegalRepresentativeFirstName" type="string">
  *Min length: 1; max. length: 100*

  The first name of the entity's legal representative.
</ParamField>

<ParamField body="LegalRepresentativeLastName" type="string">
  *Min length: 1; max. length: 100*

  The last name of the entity's legal representative.
</ParamField>

<ParamField body="LegalRepresentativeEmail" type="string">
  Format: A valid email address

  The email address of the entity’s legal representative.

  Returned `null` if `UserCategory` is `PAYER`.
</ParamField>

<ParamField body="LegalRepresentativeBirthday" type="Unix timestamp">
  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.
</ParamField>

<ParamField body="LegalRepresentativeNationality" type="string">
  Returned `null` if `UserCategory` is `PAYER`.

  The nationality of the entity’s legal representative.
</ParamField>

<ParamField body="LegalRepresentativeCountryOfResidence" type="string">
  Returned `null` if `UserCategory` is `PAYER`.

  The country of residence of the entity’s legal representative. 
</ParamField>

<ParamField body="ProofOfRegistration" type="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`.
</ParamField>

<ParamField body="ShareholderDeclaration" type="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`.
</ParamField>

<ParamField body="Statute" type="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`.
</ParamField>

<ParamField body="LegalRepresentativeProofOfIdentity" type="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`.
</ParamField>

<ParamField body="CompanyNumber" type="string">
  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).

  Returned `null` if `UserCategory` is `PAYER`.
</ParamField>

<ParamField body="Id" type="string">
  The unique identifier of the object.
</ParamField>

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

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

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

<ParamField body="PersonType" type="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.
</ParamField>

<ParamField body="Email" type="string">
  Format: A valid email address

  The email address for the entity.
</ParamField>

<ParamField body="KYCLevel" type="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.
</ParamField>

<ParamField body="TermsAndConditionsAccepted" type="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`.
</ParamField>

<ParamField body="TermsAndConditionsAcceptedDate" type="Unix timestamp">
  The date and time at which the `TermsAndConditionsAccepted` value was set to `true`.

  Returned `null` if `UserCategory` is `PAYER`.
</ParamField>

<ParamField body="UserCategory" type="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 approved and validated workflow implemented by the platform.
</ParamField>

<ParamField body="UserStatus" type="string">
  **Returned values:** ACTIVE, CLOSED

  Internal use only. This field can only be used and updated by Mangopay teams.
</ParamField>

### Related resources

<CardGroup cols={2}>
  <Card title="Guide" href="/guides/users/types">
    Users – Introduction and types
  </Card>

  <Card title="Guide" href="/guides/users/categories">
    Users – Categories
  </Card>
</CardGroup>