> ## 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 Natural 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/natural-user-object-sca) during the introduction of SCA.
</Warning>

The Natural User object represents an individual (natural person).

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="Address" type="object">
  The postal address of the user.

  <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="FirstName" type="string">
  Min. length: 1; max. length: 100

  The first name of the individual.
</ParamField>

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

  The last name of the user.
</ParamField>

<ParamField body="Birthday" type="Unix timestamp">
  The date of birth of the user.

  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="Nationality" type="string">
  The nationality of the user. 

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

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

  The country of residence of the user.
</ParamField>

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

  The occupation of the user.

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

<ParamField body="IncomeRange" type="integer">
  The bracket indicating the income of the user. The brackets are:

  * 1: \< 18K
  * 2: 18K - 30K
  * 3: 30K - 50K
  * 4: 50K - 80K
  * 5: 80K - 120K
  * 6: > 120K

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

<ParamField body="ProofOfIdentity" 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="ProofOfAddress" type="string">
  The `Id` of the KYC Document whose `Type` is `ADDRESS_PROOF` if validated for the user. If no address proof is validated, then this value is `null`.
</ParamField>

<ParamField body="Capacity" type="string">
  This is a deprecated parameter.
</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 of the user.
</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>