Create User

Creates a new end user in VaultsPay.

POST/v1/users

Body parameters

Field	Type	Description
`email`required	string	Unique email address for the user.
`first_name`required	string	Legal first name.
`last_name`required	string	Legal last name.
`mobile`required	string	E.164 phone number, e.g. +971501234567.
`date_of_birth`	string (YYYY-MM-DD)	Required before KYC can be initiated.
`nationality`	ISO 3166-1 alpha-2	e.g. AE, IN, GB.
`address`	object	Postal address. See sub-fields below.
`metadata`	object	Up to 20 string key/value pairs for your own use.

`address` sub-fields

Field	Type	Description
`line1`required	string	Street line 1.
`line2`	string	Street line 2 (apt, suite, etc).
`city`required	string	City.
`country`required	ISO 3166-1 alpha-2	e.g. AE.
`postal_code`	string	Postal/ZIP code if applicable.

Request

curl -X POST https://api.vaultspay.ae/v1/users \
  -H "Authorization: Bearer sk_test_yourApiKeyHere" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "email": "ali@example.com",
    "first_name": "Ali",
    "last_name": "Hassan",
    "mobile": "+971501234567",
    "date_of_birth": "1993-05-14",
    "nationality": "AE",
    "address": {
      "line1": "Sheikh Zayed Road",
      "city": "Dubai",
      "country": "AE"
    }
  }'

const user = await vp.users.create({
  email: 'ali@example.com',
  first_name: 'Ali',
  last_name: 'Hassan',
  mobile: '+971501234567',
  date_of_birth: '1993-05-14',
  nationality: 'AE',
  address: {
    line1: 'Sheikh Zayed Road',
    city: 'Dubai',
    country: 'AE'
  }
})

user = vaultspay.User.create(
    email='ali@example.com',
    first_name='Ali',
    last_name='Hassan',
    mobile='+971501234567',
    date_of_birth='1993-05-14',
    nationality='AE',
    address={
        'line1': 'Sheikh Zayed Road',
        'city': 'Dubai',
        'country': 'AE'
    }
)

$user = \VaultsPay\User::create([
  'email'         => 'ali@example.com',
  'first_name'    => 'Ali',
  'last_name'     => 'Hassan',
  'mobile'        => '+971501234567',
  'date_of_birth' => '1993-05-14',
  'nationality'   => 'AE',
  'address'       => [
    'line1'   => 'Sheikh Zayed Road',
    'city'    => 'Dubai',
    'country' => 'AE',
  ],
]);

Response

201 Created

{
  "id": "usr_01HX71YM6FJ3A8W7T5K6NRB2DN",
  "object": "user",
  "email": "ali@example.com",
  "first_name": "Ali",
  "last_name": "Hassan",
  "mobile": "+971501234567",
  "date_of_birth": "1993-05-14",
  "nationality": "AE",
  "kyc": { "status": "pending", "level": "basic" },
  "status": "active",
  "created_at": "2026-04-24T14:52:03.182Z"
}

Errors

HTTP	Code	Description
400	`invalid_email`	`email` is malformed.
400	`invalid_phone`	`mobile` is not in E.164 format.
409	`duplicate_email`	An existing user already has that email.
422	`validation_failed`	One or more fields are missing or invalid.

Overview Retrieve User

Create User

Body parameters

address sub-fields

Request

Response

Errors

`address` sub-fields