Users

User management is essential for controlling access and permissions within your customer account. On this page, we will dive into the different user management endpoints you can use to manage users programmatically. We will look at how to query, create, update roles and permissions, and delete users.

The user model

The user model contains all the information about users in your customer account, including their profile details, roles, permissions, and account status.

Properties

Name
user_id
Type
uuid
Description
Primary Key - Unique identifier for the user.
Name
email
Type
string
Description
Unique - User's email address (max 100 characters).
Name
password
Type
string
Description
Hashed password for authentication (max 255 characters).
Name
is_active
Type
boolean
Description
Account activation status (default: true).
Name
account_locked
Type
boolean
Description
Account lock status for security (default: false).
Name
deleted_at
Type
timestamp
Description
Soft delete timestamp (nullable).
Name
first_name
Type
string
Description
User's first name (max 100 characters, nullable).
Name
last_name
Type
string
Description
User's last name (max 100 characters, nullable).
Name
phone_number
Type
string
Description
User's phone number (max 25 characters, nullable).
Name
phone_number_country
Type
string
Description
Country code for phone number (max 10 characters, nullable).
Name
profile_image_url
Type
string
Description
URL to user's profile image (nullable).
Name
created_at
Type
timestamp
Description
Record creation timestamp (default: now()).
Name
updated_at
Type
timestamp
Description
Last record update timestamp (default: now()).

GET/customers/{customerSlug}/users

List all users

This endpoint allows you to retrieve a paginated list of all users under the specified customer account. By default, a maximum of ten users are shown per page.

Path parameters

Name
customerSlug
Type
string
Description
The unique slug identifier for the customer account.

Query parameters

Name
page
Type
integer
Description
Page number for pagination (default: 1, min: 1).
Name
limit
Type
integer
Description
Number of users per page (default: 10, min: 1).
Name
search
Type
string
Description
Search term to filter users by email, first name, or last name.
Name
status
Type
string
Description
Filter users by status. Options: 'all', 'active', 'inactive', 'locked' (default: 'all').

Request

GET

/customers/{customerSlug}/users

curl -G https://api.xnumbers.io/customers/acme-corp/users \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d page=1 \
  -d status=active \
  -d search="john"

Response

{
  "data": [
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "roles": ["customer_admin"],
      "status": "active",
      "last_login": "2024-01-15T14:30:00.000Z",
      "account_locked": false,
      "email_verified": true,
      "customer_role": "admin",
      "is_primary": false
    },
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440001",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "roles": ["customer_user"],
      "status": "active",
      "last_login": null,
      "account_locked": false,
      "email_verified": true,
      "customer_role": "user",
      "is_primary": true
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 10,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

POST/users

Create a user

This endpoint allows you to create a new user in your customer account. You must provide basic user information and can optionally assign roles and permissions.

Required attributes

Name
email
Type
string
Description
The email address for the user (max 100 characters).
Name
password
Type
string
Description
The password for the user (will be hashed).

Optional attributes

Name
first_name
Type
string
Description
User's first name (max 100 characters).
Name
last_name
Type
string
Description
User's last name (max 100 characters).
Name
phone_number
Type
string
Description
User's phone number (max 25 characters).
Name
phone_number_country
Type
string
Description
Country code for phone number (max 10 characters).
Name
profile_image_url
Type
string
Description
URL to user's profile image.
Name
is_active
Type
boolean
Description
Account activation status (defaults to true).

Request

POST

/users

curl https://api.xnumbers.io/users \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@example.com",
    "password": "securePassword123",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone_number": "+1234567890",
    "phone_number_country": "US",
    "is_active": true
  }'

Response

{
  "user_id": "550e8400-e29b-41d4-a716-446655440002",
  "email": "jane.smith@example.com",
  "is_active": true,
  "account_locked": false,
  "deleted_at": null,
  "first_name": "Jane",
  "last_name": "Smith",
  "phone_number": "+1234567890",
  "phone_number_country": "US",
  "profile_image_url": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

PATCH/users/{user_id}

Update user

This endpoint allows you to update user profile information and account settings for a specific user.

Optional attributes

Name
email
Type
string
Description
User's email address (max 100 characters).
Name
first_name
Type
string
Description
User's first name (max 100 characters).
Name
last_name
Type
string
Description
User's last name (max 100 characters).
Name
phone_number
Type
string
Description
User's phone number (max 25 characters).
Name
phone_number_country
Type
string
Description
Country code for phone number (max 10 characters).
Name
is_active
Type
boolean
Description
Account activation status.

Request

PATCH

/users/550e8400-e29b-41d4-a716-446655440002

curl -X PATCH https://api.xnumbers.io/users/550e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith-Johnson",
    "phone_number": "+1987654321",
    "is_active": true
  }'

Response

{
  "user_id": "550e8400-e29b-41d4-a716-446655440002",
  "email": "jane.smith@example.com",
  "is_active": true,
  "account_locked": false,
  "deleted_at": null,
  "first_name": "Jane",
  "last_name": "Smith-Johnson",
  "phone_number": "+1987654321",
  "phone_number_country": "US",
  "profile_image_url": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-16T14:22:00Z"
}

DELETE/users/{user_id}

Delete a user

This endpoint allows you to soft delete a user from the account by setting the deleted_at timestamp. The user record is preserved but marked as deleted.

Request

DELETE

/users/550e8400-e29b-41d4-a716-446655440002

curl -X DELETE https://api.xnumbers.io/users/550e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer {token}"

Status: 204 No Content