Users API

The Users API allows you to manage user profiles and accounts in your TraderPal Connect integration.

Endpoints

Create User

POST /v1/users

Create a new user account.

Request Body

{
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-01",
  "country": "US",
  "phoneNumber": "+1234567890"
}

Response

{
  "userId": "usr_123456789",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "status": "pending_verification",
  "createdAt": "2024-01-01T00:00:00Z"
}

Get User

GET /v1/users/{userId}

Retrieve user information by ID.

Response

{
  "userId": "usr_123456789",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "status": "active",
  "createdAt": "2024-01-01T00:00:00Z",
  "verificationStatus": {
    "email": "verified",
    "identity": "verified",
    "address": "pending"
  }
}

Update User

PATCH /v1/users/{userId}

Update user information.

Request Body

{
  "firstName": "John",
  "lastName": "Smith",
  "phoneNumber": "+1987654321"
}

Response

{
  "userId": "usr_123456789",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "status": "active",
  "updatedAt": "2024-01-01T01:00:00Z"
}

List Users

GET /v1/users

List all users with pagination.

Query Parameters

Parameter	Type	Description
limit	integer	Number of records to return (default: 100, max: 1000)
offset	integer	Number of records to skip (default: 0)
status	string	Filter by user status (active, pending, suspended)

Response

{
  "users": [
    {
      "userId": "usr_123456789",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Smith",
      "status": "active",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "metadata": {
    "total": 150,
    "limit": 100,
    "offset": 0
  }
}

User Statuses

Status	Description
pending_verification	User created but not verified
active	User verified and active
suspended	User account suspended
closed	User account closed

Error Codes

Code	Description
400	Invalid request parameters
404	User not found
409	Email already exists
422	Invalid user data

Examples

Create a New User

const response = await client.users.create({
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-01-01',
  country: 'US',
  phoneNumber: '+1234567890'
});

console.log(response.userId);

Update User Information

const userId = 'usr_123456789';
const response = await client.users.update(userId, {
  firstName: 'John',
  lastName: 'Smith'
});

console.log(response.updatedAt);

List Active Users

const response = await client.users.list({
  status: 'active',
  limit: 50
});

console.log(response.users.length);

Best Practices

1. Data Validation

   • Validate email format
   • Verify phone number format
   • Check date of birth is valid

2. Error Handling

   • Handle duplicate email errors
   • Implement retry logic for network errors
   • Log validation errors for debugging

3. User Management

   • Implement user deactivation flow
   • Handle user data updates securely
   • Monitor user status changes

Next Steps

• Authentication API - Learn about user authentication
• Best Practices - Follow our recommended practices
• Error Handling - Learn how to handle API errors