> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.mangopay.com/api-reference/users/natural-user-object/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server. # 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. 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 ### Schema (`NaturalUserResponse`) ```yaml components: schemas: Address: type: object properties: AddressLine1: type: string description: The first line of the address. AddressLine2: type: string description: The second line of the address. City: type: string description: The city of the address. Region: type: string description: Required if `Country` is US, CA, or MX. The region of the address. PostalCode: type: string description: >- The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces. Country: type: string description: >- Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address. description: The postal address. title: Address Id: type: string description: >- Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details) The unique identifier of the object. title: Id Tag: type: string description: >- Max. length: 255 characters Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: `"{\"id_1\":AB123,\"id_2\":DE456}"`. title: Tag CreationDate: type: integer description: Unix timestamp (UTC) of the date and time the object was created. title: CreationDate NaturalUserResponse: type: object properties: Address: $ref: '#/components/schemas/Address' FirstName: type: string description: |- Min. length: 1; max. length: 100 The first name of the individual. LastName: type: string description: |- Min. length: 1; max. length: 100 The last name of the individual. Birthday: type: integer description: >- 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: type: string description: |- Returned `null` if `UserCategory` is `PAYER`. The nationality of the individual. CountryOfResidence: type: string description: |- Returned `null` if `UserCategory` is `PAYER`. The country of residence of the individual. Occupation: type: string description: |- Max. length: 255 characters The occupation of the individual. Returned `null` if `UserCategory` is `PAYER`. IncomeRange: type: integer description: >- 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: type: string description: >- 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: type: string description: >- 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: type: string description: This is a deprecated parameter. Id: $ref: '#/components/schemas/Id' Tag: $ref: '#/components/schemas/Tag' CreationDate: $ref: '#/components/schemas/CreationDate' PersonType: type: string description: >- **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: type: string description: |- Format: A valid email address The email address of the user. KYCLevel: type: string description: >- **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: type: boolean description: >- 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: type: integer description: >- Unix timestamp (UTC) of the date and time the `TermsAndConditionsAccepted` value was set to `true`. Returned `null` if `UserCategory` is `PAYER`. UserCategory: type: string description: >- **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: type: string description: >- **Returned values:** ACTIVE, CLOSED Internal use only. This field can only be used and updated by Mangopay teams. title: NaturalUserResponse ``` ### Related resources #### [Guide](/guides/users/types) Users – Introduction and types #### [Guide](/guides/users/categories) Users – Categories