> ## 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.

# Create a Natural User

export const Aml = ({content}) => <Tooltip tip="Regulations which require companies like Mangopay to implement measures that help ensure the money transacting through their system is legitimate.">
        {content}
    </Tooltip>;

<Warning>
  **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 Natural User (SCA)](/api-reference/users/create-natural-user-sca).
</Warning>

<Note>
  **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>

### Body parameters

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

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

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

  The first name of the individual.
</ParamField>

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

  The last name of the individual.
</ParamField>

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

  The email address of the user.
</ParamField>

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

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

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

<ParamField body="Address" type="object">
  The postal address of the user.

  <Expandable title="properties">
    <ParamField body="AddressLine1" type="string" required>
      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" required>
      Max. length: 255 characters

      The city of the address.
    </ParamField>

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

      The region of the address. This field is optional except if the `Country` is US, CA, or MX.
    </ParamField>

    <ParamField body="PostalCode" type="string" required>
      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" required>
      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="Occupation" type="string">
  Max. length: 255 characters

  Returned `null` if `UserCategory` is `PAYER`.

  The occupation of the individual.
</ParamField>

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

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

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

### Responses

<AccordionGroup>
  <Accordion title="200">
    <ResponseField name="Address" type="object">
      The postal address of the user.

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

          The first line of the address.
        </ResponseField>

        <ResponseField name="AddressLine2" type="string">
          Max. length: 255 characters

          The second line of the address.
        </ResponseField>

        <ResponseField name="City" type="string">
          Max. length: 255 characters

          The city of the address.
        </ResponseField>

        <ResponseField name="Region" type="string">
          Max. length: 255 characters

          The region of the address. This field is optional except if the `Country` is US, CA, or MX.
        </ResponseField>

        <ResponseField name="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.
        </ResponseField>

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

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

    <ResponseField name="FirstName" type="string">
      Min. length: 1; max. length: 100

      The first name of the individual.
    </ResponseField>

    <ResponseField name="LastName" type="string">
      Min. length: 1; max. length: 100

      The last name of the individual.
    </ResponseField>

    <ResponseField name="Birthday" type="Unix timestamp">
      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.
    </ResponseField>

    <ResponseField name="Nationality" type="string">
      Returned `null` if `UserCategory` is `PAYER`.

      The nationality of the individual.
    </ResponseField>

    <ResponseField name="CountryOfResidence" type="string">
      Returned `null` if `UserCategory` is `PAYER`.

      The country of residence of the individual.
    </ResponseField>

    <ResponseField name="Occupation" type="string">
      Max. length: 255 characters

      The occupation of the individual.

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

    <ResponseField name="IncomeRange" type="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
    </ResponseField>

    <ResponseField name="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`.
    </ResponseField>

    <ResponseField name="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`.
    </ResponseField>

    <ResponseField name="Capacity" type="string">
      This is a deprecated parameter.
    </ResponseField>

    <ResponseField name="Id" type="string">
      Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)

      The unique identifier of the object.
    </ResponseField>

    <ResponseField name="Tag" type="string">
      Max. length: 255 characters

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

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

    <ResponseField name="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.
    </ResponseField>

    <ResponseField name="Email" type="string">
      Format: A valid email address

      The email address of the user.
    </ResponseField>

    <ResponseField name="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.
    </ResponseField>

    <ResponseField name="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`.
    </ResponseField>

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

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

    <ResponseField name="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 validated workflow implemented by the platform.
    </ResponseField>

    <ResponseField name="UserStatus" type="string">
      **Returned values:** ACTIVE, CLOSED

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

<AccordionGroup>
  <Accordion title="400 - Data doesn't comply with anti-fraud policy">
    ```json theme={null}
    {
        "Message": "The data you provided does not comply with our anti-fraud policy",
        "Type": "fraud_policy",
        "Id": "51876239-4814-422e-8f4b-6986520414bb#1750420019",
        "Date": 1750420020,
        "errors": null
    }
    ```

    Read more about Mangopay's [AML rules on user data](/guides/users/types#rules-on-user-data) **→**
  </Accordion>

  <Accordion title="400 - Invalid email">
    ```json theme={null}
    {
        "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type": "param_error",
        "Id": "864a164a-cbb9-4e9d-b140-2b83c720e729",
        "Date": 1690291065.0,
        "errors": {
            "Email": "The field Email must match the regular expression '([a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*)@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?'."
        }
    }  
    ```
  </Accordion>

  <Accordion title="400 - Restricted country">
    ```json theme={null}
    {
        "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type": "param_error",
        "Id": "31746ec8-51e6-4cd3-bf35-339b6646f3f4#1750669238",
        "Date": 1750669239,
        "errors": {
            "CountryOfResidence": "The CountryOfResidence used is blocked"
        }
    }
    ```

    Read more about [country restrictions](/guides/users/country-restrictions) **→**
  </Accordion>

  <Accordion title="403 - TermsAndConditionsAccepted must be true if OWNER">
    ```json theme={null}
    {
        "Message": "User must accept the terms and conditions before account creation or modification.",
        "Type": "user_hasnt_accepted_terms_and_conditions",
        "Id": "dbbc752b-6f9f-4248-a4bb-04ee0ba7b4b7",
        "Date": 1730810728,
        "errors": null
    }  
    ```
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json REST - Payer theme={null}
  {
      "Address": {
          "AddressLine1": "3 rue de la Cité",
          "AddressLine2": "Appartement 7",
          "City": "Paris",
          "Region": "Île-de-France",
          "PostalCode": "75004",
          "Country": "FR"
      },
      "FirstName": "Alex",
      "LastName": "Smith",
      "Birthday": null,
      "Nationality": null,
      "CountryOfResidence": null,
      "Occupation": null,
      "IncomeRange": null,
      "ProofOfIdentity": null,
      "ProofOfAddress": null,
      "Capacity": "NORMAL",
      "PhoneNumber": null,
      "PhoneNumberCountry": null,
      "Id": "user_m_01JHX2YFX51HSR8R2HJ8ABSEFF",
      "Tag": "Created using Mangopay API Postman collection",
      "CreationDate": 1737216704,
      "PersonType": "NATURAL",
      "Email": "alex.smith@example.com",
      "KYCLevel": "LIGHT",
      "TermsAndConditionsAccepted": false,
      "TermsAndConditionsAcceptedDate": null,
      "UserCategory": "PAYER",
      "UserStatus": "ACTIVE"
  }
  ```

  ```json REST - Owner theme={null}
  {
      "Address": {
          "AddressLine1": "3 rue de la Cité",
          "AddressLine2": "Appartement 7",
          "City": "Paris",
          "Region": "Île-de-France",
          "PostalCode": "75004",
          "Country": "FR"
      },
      "FirstName": "Alex",
      "LastName": "Smith",
      "Birthday": 652117514,
      "Nationality": "FR",
      "CountryOfResidence": "FR",
      "Occupation": null,
      "IncomeRange": null,
      "ProofOfIdentity": null,
      "ProofOfAddress": null,
      "Capacity": "NORMAL",
      "PhoneNumber": null,
      "PhoneNumberCountry": null,
      "Id": "user_m_01JHX332D775R1784M4SK4SFMS",
      "Tag": "Created using Mangopay API Postman collection",
      "CreationDate": 1737216854,
      "PersonType": "NATURAL",
      "Email": "alex.smith@example.com",
      "KYCLevel": "LIGHT",
      "TermsAndConditionsAccepted": true,
      "TermsAndConditionsAcceptedDate": 1737216854,
      "UserCategory": "OWNER",
      "UserStatus": "ACTIVE"
  }
  ```
</ResponseExample>

<RequestExample>
  ```json REST - Payer theme={null}
  {
      "UserCategory": "PAYER",
      "TermsAndConditionsAccepted": false,
      "Address": {
          "AddressLine1": "3 rue de la Cité",
          "AddressLine2": "Appartement 7",
          "City": "Paris",
          "Region": "Île-de-France",
          "PostalCode": "75004",
          "Country": "FR"
      },
      "FirstName": "Alex",
      "LastName": "Smith",
      "Email": "alex.smith@example.com",
      "Tag": "Created using Mangopay API Postman collection"
  }
  ```

  ```json REST - Owner theme={null}
  {
      "UserCategory": "OWNER",
      "TermsAndConditionsAccepted": true,
      "Address": {
          "AddressLine1": "3 rue de la Cité",
          "AddressLine2": "Appartement 7",
          "City": "Paris",
          "Region": "Île-de-France",
          "PostalCode": "75004",
          "Country": "FR"
      },
      "FirstName": "Alex",
      "LastName": "Smith",
      "Email": "alex.smith@example.com",
      "Birthday": 652117514,
      "Nationality": "FR",
      "CountryOfResidence": "FR",
      "Tag": "Created using Mangopay API Postman collection"
  }
  ```

  ```php PHP theme={null}
  <?php 

  require_once 'vendor/autoload.php';

  use MangoPay\MangoPayApi;
  use MangoPay\Libraries\ResponseException as MGPResponseException;
  use MangoPay\Libraries\Exception as MGPException;

  $api = new MangoPayApi();

  $api->Config->ClientId = 'your-client-id';
  $api->Config->ClientPassword = 'your-api-key';
  $api->Config->TemporaryFolder = 'tmp/';

  try {
      $user = new \MangoPay\UserNatural();

      $user->FirstName = 'Alex';
      $user->LastName = 'Smith';
      $user->Email = "asmith@example.com";
      
      $user->Address = new \MangoPay\Address();
      $user->Address->AddressLine1 = 'Rue des plantes';
      $user->Address->AddressLine2 = 'Building A';
      $user->Address->City = 'Paris';
      $user->Address->Country = 'FR';
      $user->Address->PostalCode = '75000';
      $user->Address->Region = 'IDF';
      $user->Tag = 'Created using Mangopay PHP SDK';
      
      $user->TermsAndConditionsAccepted = true;
      $user->UserCategory = 'Payer';
      
      $response = $api->Users->Create($user);

      print_r($response);
  } catch(MGPResponseException $e) {
      print_r($e);
  } catch(MGPException $e) {
      print_r($e);
  }  
  ```

  ```javascript NodeJS   theme={null}
  const mangopayInstance = require('mangopay4-nodejs-sdk');
  const mangopay = new mangopayInstance({
      clientId: "your-client-id",
      clientApiKey: "your-api-key",
  })

  let naturalUser = {
    Address: {
      AddressLine1: '2795 Edgewood Road',
      AddressLine2: null,
      City: 'Little Rock',
      Region: 'Arkansas',
      PostalCode: '72212',
      Country: 'US',
    },
    FirstName: 'John',
    LastName: 'Doe',
    Birthday: 655772400,
    Nationality: 'FR',
    CountryOfResidence: 'US',
    Tag: 'My first user',
    Email: 'john.doe@mangopay.com',
    TermsAndConditionsAccepted: true,
    UserCategory: 'OWNER',
    PersonType: 'NATURAL',
    NaturalSca: false,
  }

  const createUser = async (userObject) => {
    return await mangopay.Users.create(userObject)
      .then((response) => {
        console.info(response)
        return response
      })
      .catch((err) => {
        console.log(err)
        return false
      })
  }

  createUser(naturalUser)
    
  ```

  ```ruby Ruby   theme={null}
  require 'mangopay'

  MangoPay.configure do |client|
      client.preproduction = true
      client.client_id = 'your-client-id'
      client.client_apiKey = 'your-api-key'
      client.log_file = File.join(Dir.pwd, 'mangopay.log')
  end

  def createNaturalUser(naturalUserObject)
      begin
          response = MangoPay::NaturalUser.create(naturalUserObject)
          puts response
          return response
      rescue MangoPay::ResponseError => error
          puts "Failed to create User: #{error.message}"
          puts "Error details: #{error.details}"
          return false
      end
  end

  myNaturalUser = {
      Tag: 'Created using Mangopay Ruby SDK',
      Email: 'john.ruby@test.com',
      FirstName: 'John',
      LastName: 'Doe',
      Address: {
          AddressLine1: '2795 Edgewood Road',
          City: 'Little Rock',
          Region: 'Arkansas',
          PostalCode: '72212',
          Country: 'US'
      },
      Birthday: 655772400,
      Nationality: 'FR',
      CountryOfResidence: 'US',
      TermsAndConditionsAccepted: true,
      UserCategory: 'OWNER'
  }

  createNaturalUser(myNaturalUser)  
  ```

  ```java Java   theme={null}
  import com.mangopay.MangoPayApi;
  import com.mangopay.core.Address;
  import com.mangopay.entities.User;
  import com.mangopay.entities.UserNatural;
  import com.mangopay.core.enumerations.UserCategory;
  import com.mangopay.core.enumerations.CountryIso;

  import java.lang.reflect.Field;

  public class CreateNaturalUser {
      public static void main(String[] args) throws Exception {
          MangoPayApi mangopay = new MangoPayApi();
          mangopay.getConfig().setClientId("your-client-id");
          mangopay.getConfig().setClientPassword("your-api-key");

          UserNatural user = new UserNatural();
          Address address = new Address();

          address.setAddressLine1("27 Rue de Rivoli");
          address.setCity("Paris");
          address.setRegion("Île-de-France");
          address.setPostalCode("75001");
          address.setCountry(CountryIso.FR);

          user.setFirstName("Alex");
          user.setLastName("Smith");
          user.setEmail("alex.smith@mgp.com");
          user.setAddress(address);
          user.setBirthday(655772400);
          user.setNationality(CountryIso.FR);
          user.setCountryOfResidence(CountryIso.FR);
          user.setTermsAndConditionsAccepted(true);
          user.setTag("Created using the Mangopay Java SDK");
          user.setUserCategory(UserCategory.PAYER);

          User createUser = mangopay.getUserApi().create(user);  
          
          System.out.println(String.format("id: %s", createUser.getId()));
          printObjectFields(createUser);
      }

      private static void printObjectFields(Object obj) {
          Class<?> objClass = obj.getClass();
          Field[] fields = objClass.getDeclaredFields();
          for (Field field : fields) {
              field.setAccessible(true);
              try {
                  Object value = field.get(obj);
                  if (value instanceof Address) {
                      System.out.println(field.getName() + ": ");
                      printObjectFields(value); 
                  } else {
                      System.out.println(field.getName() + ": " + value);
                  }
              } catch (IllegalAccessException e) {
                  e.printStackTrace();
              }
          }
      }
  }  
  ```

  ```python Python   theme={null}
  from pprint import pprint
  import mangopay

  mangopay.client_id = 'your-client-id'
  mangopay.apikey = 'your-api-key'

  from mangopay.api import APIRequest
  handler = APIRequest(sandbox=True)

  from mangopay.resources import NaturalUser
  from mangopay.utils import Address

  natural_user = NaturalUser(
      address = Address(
          address_line_1 = '42 Maple Road',
          city = 'London',
          postal_code = 'WC1X 0AA',
          country = 'GB'
      ),
      first_name = 'Olivia',
      last_name = 'Turner',
      birthday = 655772400,
      nationality = 'GB',
      country_of_residence = 'GB',
      person_type = 'NATURAL',
      tag = 'Created with Mangopay Python SDK',
      email = 'olivia.turner@test.com',
      terms_and_conditions_accepted = True, 
      user_category = 'OWNER' 
  )

  create_natural_user = natural_user.save()

  pprint(create_natural_user)

    
  ```

  ```csharp .NET  theme={null}
  using MangoPay.SDK;
  using MangoPay.SDK.Entities;
  using MangoPay.SDK.Core.Enumerations;
  using MangoPay.SDK.Entities.POST;
  using Newtonsoft.Json;

  class Program
  {
      static async Task Main(string[] args)
      {
          MangoPayApi api = new MangoPayApi();

          api.Config.ClientId = "your-client-id";
          api.Config.ClientPassword = "your-api-key";

          var myUser = new UserNaturalOwnerPostDTO
          {
              FirstName = "Dolly",
              LastName = "Tester", 
              Email = "dolly.nelson@example.com",
              Address = new Address {
                  AddressLine1 = "17 Rue de la République",
                  City = "Paris",
                  PostalCode = "75001",
                  Country = CountryIso.FR
              },
              Birthday = new DateTime(1985, 3, 15),
              Nationality = CountryIso.FR,
              CountryOfResidence = CountryIso.FR,
              Tag = "Created using the Mangopay .NET SDK"
          };

          var createNaturalUser = await api.Users.CreateOwnerAsync(myUser);

          string prettyPrint = JsonConvert.SerializeObject(createNaturalUser, Formatting.Indented);
          Console.WriteLine(prettyPrint);
      }
  }
  ```
</RequestExample>