User Onboarding

Manage the full lifecycle of your end users: create them, read and update their profile, activate or deactivate access, and soft-delete them. A user must be created here before you can issue a token, open wallets, or transact on their behalf.

Authentication: every endpoint on this page requires your Owner API Key. Only owner clients can call them; anything else returns 403 Forbidden.

x-api-key: YOUR_OWNER_API_KEY

All requests accept an optional x-trace-id header for request tracking; if omitted, one is generated.

Create User

POSThttps://api.sandbox.sovera.io/sovx/v1/users

Register a new end user under your customer account. This is the first step in the user lifecycle—it creates the record that wallets, tokens, and transactions attach to. The new user starts in a PENDING state; activate them once they're ready to transact. Email and phone number must each be unique within your customer account—reusing either returns a 409 Conflict.

Request Body

Field	Type	Required	Description
user_id	string (uuid v4)	No	Caller-supplied UUID for the user. If omitted, one is generated. Must be unique.
account_type	string	Yes	Type of account. One of `individual`, `business`.
account_role	string	Yes	Role of the account. Must be `third`.
account_purpose	string	Yes	Primary purpose. One of `trading`, `investing`.
first_name	string	Yes	First name of the account holder (max 100).
last_name	string	Yes	Last name of the account holder (max 100).
email	string	Yes	Primary email address. Must be unique within your customer account.
phone_country_code	string	Yes	Country code for the phone number (ISO 3166-1 alpha-2).
phone_number	string	Yes	Phone number (max 20). Must be a valid mobile number for the country. Must be unique within your customer account.
individual	object	Yes	Individual account holder KYC information (see below).

`individual` object

Field	Type	Required	Description
dob	string	Yes	Date of birth in `YYYY-MM-DD` format. The holder must be at least 18 years old.
residential_country_code	string	Yes	Country code of the residential address (ISO 3166-1 alpha-2).
residential_address	string	Yes	Street address of residence.
residential_city	string	Yes	City of residence.
residential_state	string	Yes	State or province of residence.
residential_postal_code	string	Yes	Postal code of residence.
id_type	string	Yes	Type of identification document. One of `ssn`, `passport`.
id_number	string	Yes	Identification document number.
id_country_code	string	Yes	Country code where the ID was issued (ISO 3166-1 alpha-2).

first_name, last_name, residential_city, and residential_state are sanitized, and residential_address is sanitized as an address — unsafe or script-like characters are rejected, not just truncated.

{
  "account_type": "individual",
  "account_role": "third",
  "account_purpose": "investing",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone_country_code": "US",
  "phone_number": "2252542523",
  "individual": {
    "dob": "1990-10-15",
    "residential_country_code": "US",
    "residential_address": "123 Sovera Lane",
    "residential_city": "Cheyenne",
    "residential_state": "WY",
    "residential_postal_code": "82001",
    "id_type": "ssn",
    "id_number": "123456789",
    "id_country_code": "US"
  }
}

Success Response (201 Created):

{
  "success": true,
  "data": {
    "account_type": "individual",
    "account_role": "third",
    "account_purpose": "investing",
    "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_country_code": "US",
    "phone_number": "2252542523",
    "status": "PENDING",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z",
    "individual": {
      "dob": "1990-10-15",
      "residential_country_code": "US",
      "residential_address": "123 Sovera Lane",
      "residential_city": "Cheyenne",
      "residential_state": "WY",
      "residential_postal_code": "82001",
      "id_type": "ssn",
      "id_number": "123456789",
      "id_country_code": "US"
    }
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OWNER_API_KEY" \
  -d '{
    "account_type": "individual",
    "account_role": "third",
    "account_purpose": "investing",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_country_code": "US",
    "phone_number": "2252542523",
    "individual": {
      "dob": "1990-10-15",
      "residential_country_code": "US",
      "residential_address": "123 Sovera Lane",
      "residential_city": "Cheyenne",
      "residential_state": "WY",
      "residential_postal_code": "82001",
      "id_type": "ssn",
      "id_number": "123456789",
      "id_country_code": "US"
    }
  }'

Errors: 400 missing/invalid fields · 401 invalid key · 403 not an owner client · 409 email, phone, or user_id already exists · 422 validation failed · 500 server error.

List Users

GEThttps://api.sandbox.sovera.io/sovx/v1/users

List the users in your customer account, newest first. Page through large sets, filter by status or type, or search by name or email. Soft-deleted users are excluded automatically.

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number (default: 1).
limit	number	No	Items per page (default: 20, max: 100).
status	string	No	Filter by user status. One of `PENDING`, `VERIFIED`, `SUSPENDED`.
user_type	string	No	Filter by user type. One of `individual`, `business`.
verification_status	string	No	Filter by verification status. One of `verified`, `unverified`, `pending`.
is_active	boolean	No	Filter by active flag.
search	string	No	Search by first name, last name, or email.

GET https://api.sandbox.sovera.io/sovx/v1/users?page=1&limit=20

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "account_type": "individual",
      "account_role": "third",
      "account_purpose": "investing",
      "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_country_code": "US",
      "phone_number": "2252542523",
      "status": "VERIFIED",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-01-15T10:30:00.000Z",
      "individual": {
        "dob": "1990-10-15",
        "residential_country_code": "US",
        "residential_address": "123 Sovera Lane",
        "residential_city": "Cheyenne",
        "residential_state": "WY",
        "residential_postal_code": "82001",
        "id_type": "ssn",
        "id_number": "123456789",
        "id_country_code": "US"
      }
    }
  ],
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f",
    "pagination": {
      "records": { "skip": 0, "has_next": false, "has_previous": false, "total": 1, "limit": 20 },
      "navigation": {
        "first": "/users?filter[limit]=20&filter[skip]=0",
        "last": "/users?filter[limit]=20&filter[skip]=0",
        "previous": null,
        "next": null
      }
    }
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/users?page=1&limit=20" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 invalid key · 403 not an owner client · 429 rate limit · 500 server error.

Get User

GEThttps://api.sandbox.sovera.io/sovx/v1/users/:id

Retrieve a single user by their user_id, including profile details and current lifecycle status. Only users within your customer account are returned; anything else responds with 404 Not Found.

GET https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "account_type": "individual",
    "account_role": "third",
    "account_purpose": "investing",
    "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_country_code": "US",
    "phone_number": "2252542523",
    "status": "VERIFIED",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z",
    "individual": {
      "dob": "1990-10-15",
      "residential_country_code": "US",
      "residential_address": "123 Sovera Lane",
      "residential_city": "Cheyenne",
      "residential_state": "WY",
      "residential_postal_code": "82001",
      "id_type": "ssn",
      "id_number": "123456789",
      "id_country_code": "US"
    }
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 invalid key · 403 not an owner client · 404 user not found · 500 server error.

Update User

PUThttps://api.sandbox.sovera.io/sovx/v1/users/:id

Update an existing user's profile details. Send only the fields you want to change—omitted fields keep their current values. A changed email or phone number must remain unique within your customer account, or the request returns 400 Bad Request. Returns the full updated record.

Request Body

All fields are optional. Include only the fields you want to change.

Field	Type	Required	Description
first_name	string	No	User's first name (max 100).
last_name	string	No	User's last name (max 100).
email	string	No	User's email address. Must remain unique within your customer account.
phone_country_code	string	No	Country code for the phone number (ISO 3166-1 alpha-2).
phone_number	string	No	Phone number (max 20). Must be a valid mobile for the country and unique within your account.
account_purpose	string	No	Account purpose. One of `trading`, `investing`.
dob	string	No	Date of birth in `YYYY-MM-DD` format (must be 18+).
residential_country_code	string	No	Country code of residence (ISO 3166-1 alpha-2).
residential_address	string	No	Street address of residence.
residential_city	string	No	City of residence.
residential_state	string	No	State or province of residence.
residential_postal_code	string	No	Postal code of residence.
id_type	string	No	Type of ID document. One of `ssn`, `passport`.
id_number	string	No	Identification document number.
id_country_code	string	No	Country code where the ID was issued (ISO 3166-1 alpha-2).

A user's lifecycle status is managed only through Activate User and Deactivate User — status, verification_status, and is_active can't be set here, and account_type and account_role can't be changed.

{
  "first_name": "Jane",
  "phone_number": "9876543210"
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "account_type": "individual",
    "account_role": "third",
    "account_purpose": "investing",
    "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_country_code": "US",
    "phone_number": "9876543210",
    "status": "VERIFIED",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z",
    "individual": {
      "dob": "1990-10-15",
      "residential_country_code": "US",
      "residential_address": "123 Sovera Lane",
      "residential_city": "Cheyenne",
      "residential_state": "WY",
      "residential_postal_code": "82001",
      "id_type": "ssn",
      "id_number": "123456789",
      "id_country_code": "US"
    }
  },
  "meta": {
    "timestamp": "2026-01-15T12:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X PUT "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OWNER_API_KEY" \
  -d '{
    "first_name": "Jane",
    "phone_number": "9876543210"
  }'

Errors: 400 invalid format or email/phone already in use · 401 invalid key · 403 not an owner client · 404 user not found · 422 validation failed · 500 server error.

Delete User

DELETEhttps://api.sandbox.sovera.io/sovx/v1/users/:id

Soft-delete a user. The record is marked as deleted but never erased, so wallets and transaction history stay intact and the user drops out of List Users. To temporarily block access instead, use Deactivate User, which can be reversed.

DELETE https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}

Success Response (204 No Content) — empty body, no JSON.

curl -X DELETE "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 invalid key · 403 not an owner client · 404 user not found · 500 server error.

Activate User

POSThttps://api.sandbox.sovera.io/sovx/v1/users/:id/activate

Activate a user so they can transact. This moves the user to the VERIFIED state and marks the account as active—the green light for issuing a token and opening wallets. Use it on a newly created PENDING user, or to restore one you previously deactivated. Activating an already-verified user is a safe no-op.

POST https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/activate

No request body.

Success Response (200 OK):

{
  "success": true,
  "data": { "message": "User has been activated" },
  "meta": {
    "timestamp": "2026-01-15T12:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/activate" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 invalid key · 403 not an owner client · 404 user not found · 500 server error.

Deactivate User

POSThttps://api.sandbox.sovera.io/sovx/v1/users/:id/deactivate

Deactivate a user to block their access without deleting them. This moves the user to the SUSPENDED state and marks the account inactive, so their tokens can no longer transact. All data, wallets, and history are preserved—bring them back with Activate User.

POST https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/deactivate

No request body.

Success Response (200 OK):

{
  "success": true,
  "data": { "message": "User has been deactivated" },
  "meta": {
    "timestamp": "2026-01-15T12:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/deactivate" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 invalid key · 403 not an owner client · 404 user not found · 500 server error.

Next Steps

Generate a user token so the user can call the User APIs.
Create a wallet for the user.

User Onboarding

On this page