---
title: "Update a Natural User"
method: PUT
path: "/v2.01/{ClientId}/users/natural/{UserId}"
tags: ["Users"]
---

# Update a Natural User

`PUT /v2.01/{ClientId}/users/natural/{UserId}`

<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 to change the `UserCategory` from `PAYER` to `OWNER`, your platform must call [PUT Categorize a Natural User](/api-reference/users/categorize-natural-user). You must also redirect the user on the `PendingUserAction.RedirectUrl` returned so they can [enroll in SCA](/guides/sca/users#transition-a-payer-to-owner).

If you are not changing the `UserCategory`, then call the [PUT Update a Natural User (SCA)](/api-reference/users/update-natural-user-sca) endpoint instead of this deprecated endpoint. [SCA re-enrollment](/guides/sca/users#re-enroll-an-enrolled-owner) is required if your platform changes the `Email`, `PhoneNumber`, or `PhoneNumberCountry`.
</Warning>

<Warning icon="fa-regular fa-triangle-exclamation">
**Caution – Modification may cause KYC/B verification downgrade** 

If `KYCLevel` is `REGULAR`, modifying the following values triggers a [verification downgrade](/guides/users/verification/downgrade) to `LIGHT`: 
- `FirstName`
- `LastName`
- `Birthday`
- `Nationality`
</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:
- `Nationality`
- `CountryOfResidence`
- `Address.Country`
</Note>

Update a Natural User

## Path parameters

- `ClientId` string, required
- `UserId` string, required

## Headers

- `Authorization` string, required

## Request body

- UpdateANaturalUserRequest
  - `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`.
  - `FirstName` string — Min. length: 1; max. length: 100 The first name of the individual.
  - `LastName` string — Min. length: 1; max. length: 100 The last name of the individual.
  - `Email` string — Format: A valid email address The email address of the user.
  - `Birthday` integer — Required if `UserCategory` is `OWNER`. Returned `null` if `UserCategory` is `PAYER`. The date of birth of the individual. **Note:** This is a Unix timestamp in UTC. Ensure you convert your timezone to UTC to avoid midnight being interpreted as the day before.
  - `Nationality` 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 individual.
  - `CountryOfResidence` 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 individual.
  - `Address` 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.
  - `Occupation` string — Max. length: 255 characters Returned `null` if `UserCategory` is `PAYER`. The occupation of the individual.
  - `IncomeRange` integer — **Allowed values:** `1`, `2`, `3`, `4`, `5`, `6`, `null` Returned `null` if `UserCategory` is `PAYER`. The bracket indicating the income of the individual. The brackets are: - 1: < 18K - 2: 18K - 30K - 3: 30K - 50K - 4: 50K - 80K - 5: 80K - 120K - 6: > 120K
  - `Tag` string — Max. length: 255 characters Custom data that you can add to this object.

## Response `200`

Success

- NaturalUserResponse
  - `Address` 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.
  - `FirstName` string — Min. length: 1; max. length: 100 The first name of the individual.
  - `LastName` string — Min. length: 1; max. length: 100 The last name of the individual.
  - `Birthday` integer — Returned `null` if `UserCategory` is `PAYER`. The date of birth of the individual. **Note:** This is a Unix timestamp in UTC. Ensure you convert your timezone to UTC to avoid midnight being interpreted as the day before.
  - `Nationality` string — Returned `null` if `UserCategory` is `PAYER`. The nationality of the individual.
  - `CountryOfResidence` string — Returned `null` if `UserCategory` is `PAYER`. The country of residence of the individual.
  - `Occupation` string — Max. length: 255 characters The occupation of the individual. Returned `null` if `UserCategory` is `PAYER`.
  - `IncomeRange` integer — Returned `null` if `UserCategory` is `PAYER`. The bracket indicating the income of the individual. The brackets are: - 1: < 18K - 2: 18K - 30K - 3: 30K - 50K - 4: 50K - 80K - 5: 80K - 120K - 6: > 120K
  - `ProofOfIdentity` 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`.
  - `ProofOfAddress` 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`.
  - `Capacity` string — This is a deprecated parameter.
  - `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 of the user.
  - `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.

## Other responses

- `400` — Bad Request

---

[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)