User Management

This guide will take you through the journey of managing users within your betting application using our API.

Creating a User

Once you have authenticated, you can create users who will be placing bets on your platform. To create a user, you need to send a POST request to our API with the user's details. The reference field is optional and will be generated if not provided. The preferences field is also optional.

cURL

# Using token authentication
curl -X POST "$baseUrl/account/user" \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "danny_user",  # Optional
    "name": "User 3",
    "preferences": {}  # Optional
  }'

# Or using API key authentication
curl -X POST "$baseUrl/account/user" \
  -H "Authorization: Basic $base64_encoded" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "danny_user",  # Optional
    "name": "User 3",
    "preferences": {}  # Optional
  }'

JavaScript

const createUser = async (auth) => {
  try {
    // Determine authentication method
    let authHeader;
    if (auth.token) {
      authHeader = `Bearer ${auth.token}`;
    } else if (auth.apiKeys) {
      authHeader = `Basic ${auth.apiKeys.base64_encoded}`;
    }

    const response = await fetch(`${baseUrl}/account/user`, {
      method: "POST",
      headers: {
        Authorization: authHeader,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        reference: "danny_user", // Optional
        name: "User 3",
        preferences: {}, // Optional
      }),
    });

    const data = await response.json();
    console.log("User created:", data);
  } catch (error) {
    console.error("Error creating user:", error);
  }
};

// Usage
const auth = await getAuthentication();
createUser(auth);

Python

import requests
import json

def create_user(auth):
    url = f"{base_url}/account/user"

    headers = {
        'Content-Type': 'application/json'
    }

    # Determine authentication method
    if 'token' in auth:
        headers['Authorization'] = f"Bearer {auth['token']}"
    elif 'apiKeys' in auth:
        headers['Authorization'] = f"Basic {auth['apiKeys']['base64_encoded']}"

    payload = {
        "reference": "danny_user",  # Optional
        "name": "User 3",
        "preferences": {}  # Optional
    }

    response = requests.post(url, headers=headers, data=json.dumps(payload))

    if response.status_code == 201:
        print('User created:', response.json())
    else:
        print('Error creating user:', response.text)

# Usage
auth = get_authentication()
create_user(auth)

Rust

use reqwest::Client;
use serde::{Deserialize, Serialize};

#[derive(Serialize)]
struct UserRequest {
  reference: Option<String>,
  name: String,
  preferences: Option<serde_json::Value>,
}

enum AuthMethod {
  Token(String),
  ApiKeys(ApiKeys),
}

async fn create_user(client: &Client, base_url: &str, auth: &AuthMethod)
-> Result<serde_json::Value, Box<dyn std::error::Error>> {

  let mut request_builder = client
      .post(&format!("{}/account/user", base_url))
      .header("Content-Type", "application/json");

  // Apply authentication header
  match auth {
      AuthMethod::Token(token) => {
          request_builder = request_builder.header("Authorization", format!("Bearer {}", token));
      },
      AuthMethod::ApiKeys(api_keys) => {
          request_builder = request_builder.header("Authorization", format!("Basic {}", api_keys.base64_encoded));
      }
  }

  let user_request = UserRequest {
      reference: Some("danny_user".to_string()), // Optional
      name: "User 3".to_string(),
      preferences: Some(serde_json::json!({})), // Optional
  };

  let response = request_builder
      .json(&user_request)
      .send()
      .await?;

  if response.status().is_success() {
      let user_data = response.json::<serde_json::Value>().await?;
      println!("User created: {:?}", user_data);
      Ok(user_data)
  } else {
      let error_message = response.text().await?;
      println!("Error creating user: {:?}", error_message);
      Err(Box::new(std::io::Error::new(std::io::ErrorKind::Other, error_message)))
  }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new();

  // First get authentication (token or API keys)
  // ...

  // Create user with token
  let auth = AuthMethod::Token(token);
  let user_data = create_user(&client, base_url, &auth).await?;

  // Or create user with API keys
  // let auth = AuthMethod::ApiKeys(api_keys);
  // let user_data = create_user(&client, base_url, &auth).await?;

  Ok(())
}

Upon successful creation, the API will respond with the user's details:

{
  "data": {
    "id": 2,
  "reference": "a2_user_Xhwz442NTj74z6F0",
  "created_at": "2025-09-08T12:05:10.000Z"
  },
  "message": "User created successfully"
}

Flow of Creating a User

Here is a visual representation of the flow for creating a user:

This diagram shows the complete sequence of API calls to create an account, authenticate, and then create a user.

Getting User Details

You can retrieve the details of a specific user by sending a GET request to our API with either the user's ID or reference.

By User ID

cURL

# Using token authentication
curl -X GET "$baseUrl/account/user/$userId" \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json"

# Or using API key authentication
curl -X GET "$baseUrl/account/user/$userId" \
  -H "Authorization: Basic $base64_encoded" \
  -H "Content-Type: application/json"

JavaScript

const getUserDetailsById = async (auth, userId) => {
  try {
    // Determine authentication method
    let authHeader;
    if (auth.token) {
      authHeader = `Bearer ${auth.token}`;
    } else if (auth.apiKeys) {
      authHeader = `Basic ${auth.apiKeys.base64_encoded}`;
    }

    const response = await fetch(`${baseUrl}/account/user/${userId}`, {
      method: "GET",
      headers: {
        Authorization: authHeader,
        "Content-Type": "application/json",
      },
    });

    const data = await response.json();
    console.log("User details:", data);
  } catch (error) {
    console.error("Error getting user details:", error);
  }
};

// Usage
const auth = await getAuthentication();
const userId = "1"; // Replace with actual user ID
getUserDetailsById(auth, userId);

Python

import requests

def get_user_details_by_id(auth, user_id):
    url = f"{base_url}/account/user/{user_id}"

    headers = {
        'Content-Type': 'application/json'
    }

    # Determine authentication method
    if 'token' in auth:
        headers['Authorization'] = f"Bearer {auth['token']}"
    elif 'apiKeys' in auth:
        headers['Authorization'] = f"Basic {auth['apiKeys']['base64_encoded']}"

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        print('User details:', response.json())
    else:
        print('Error getting user details:', response.text)

# Usage
auth = get_authentication()
user_id = '1' # Replace with actual user ID
get_user_details_by_id(auth, user_id)

Rust

use reqwest::Client;
use serde_json::Value;

enum AuthMethod {
  Token(String),
  ApiKeys(ApiKeys),
}

async fn get_user_details_by_id(client: &Client, base_url: &str, auth: &AuthMethod, user_id: &str)
-> Result<Value, Box<dyn std::error::Error>> {

  let mut request_builder = client
      .get(&format!("{}/account/user/{}", base_url, user_id))
      .header("Content-Type", "application/json");

  // Apply authentication header
  match auth {
      AuthMethod::Token(token) => {
          request_builder = request_builder.header("Authorization", format!("Bearer {}", token));
      },
      AuthMethod::ApiKeys(api_keys) => {
          request_builder = request_builder.header("Authorization", format!("Basic {}", api_keys.base64_encoded));
      }
  }

  let response = request_builder.send().await?;
  let user_data = response.json::<Value>().await?;
  println!("User details: {:?}", user_data);

  Ok(user_data)
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new();

  // First get authentication (token or API keys)
  // ...

  // Get user details with token
  let auth = AuthMethod::Token(token);
  let user_data = get_user_details_by_id(&client, base_url, &auth, "1").await?;

  // Or get user details with API keys
  // let auth = AuthMethod::ApiKeys(api_keys);
  // let user_data = get_user_details_by_id(&client, base_url, &auth, "1").await?;

  Ok(())
}

By User Reference

cURL

# Using token authentication
curl -X GET "$baseUrl/account/user/$reference/reference" \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json"

# Or using API key authentication
curl -X GET "$baseUrl/account/user/$reference/reference" \
  -H "Authorization: Basic $base64_encoded" \
  -H "Content-Type: application/json"

JavaScript

const getUserDetailsByReference = async (auth, reference) => {
  try {
    // Determine authentication method
    let authHeader;
    if (auth.token) {
      authHeader = `Bearer ${auth.token}`;
    } else if (auth.apiKeys) {
      authHeader = `Basic ${auth.apiKeys.base64_encoded}`;
    }

    const response = await fetch(
      `${baseUrl}/account/user/${reference}/reference`,
      {
        method: "GET",
        headers: {
          Authorization: authHeader,
          "Content-Type": "application/json",
        },
      },
    );

    const data = await response.json();
    console.log("User details:", data);
  } catch (error) {
    console.error("Error getting user details:", error);
  }
};

// Usage
const auth = await getAuthentication();
const reference = "danny_user"; // Replace with actual user reference
getUserDetailsByReference(auth, reference);

Python

import requests

def get_user_details_by_reference(auth, reference):
    url = f"{base_url}/account/user/{reference}/reference"

    headers = {
        'Content-Type': 'application/json'
    }

    # Determine authentication method
    if 'token' in auth:
        headers['Authorization'] = f"Bearer {auth['token']}"
    elif 'apiKeys' in auth:
        headers['Authorization'] = f"Basic {auth['apiKeys']['base64_encoded']}"

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        print('User details:', response.json())
    else:
        print('Error getting user details:', response.text)

# Usage
auth = get_authentication()
reference = 'danny_user' # Replace with actual user reference
get_user_details_by_reference(auth, reference)

Rust

use reqwest::Client;
use serde_json::Value;

enum AuthMethod {
  Token(String),
  ApiKeys(ApiKeys),
}

async fn get_user_details_by_reference(client: &Client, base_url: &str, auth: &AuthMethod, reference: &str)
-> Result<Value, Box<dyn std::error::Error>> {

  let mut request_builder = client
      .get(&format!("{}/account/user/{}/reference", base_url, reference))
      .header("Content-Type", "application/json");

  // Apply authentication header
  match auth {
      AuthMethod::Token(token) => {
          request_builder = request_builder.header("Authorization", format!("Bearer {}", token));
      },
      AuthMethod::ApiKeys(api_keys) => {
          request_builder = request_builder.header("Authorization", format!("Basic {}", api_keys.base64_encoded));
      }
  }

  let response = request_builder.send().await?;
  let user_data = response.json::<Value>().await?;
  println!("User details: {:?}", user_data);

  Ok(user_data)
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new();

  // First get authentication (token or API keys)
  // ...

  // Get user details with token
  let auth = AuthMethod::Token(token);
  let user_data = get_user_details_by_reference(&client, base_url, &auth, "danny_user").await?;

  // Or get user details with API keys
  // let auth = AuthMethod::ApiKeys(api_keys);
  // let user_data = get_user_details_by_reference(&client, base_url, &auth, "danny_user").await?;

  Ok(())
}

Upon successful retrieval, the API will respond with the user's details:

{
  "data": {
    "id": 1,
    "reference": "a1_user_FclirLc2MJecJqsi",
    "name": "User 3",
  "preferences": {},
  "created_at": "2025-09-08T12:00:00.000Z"
  },
  "message": "User details retrieved successfully"
}

The API will respond with the user's details:

{
  "data": {
    "id": 1,
    "account_id": 2,
    "reference": "a2_user_4lH6u7hayvaqs6Ix",
    "name": "Jane Dodde",
    "role": "user",
    "preferences": {
      "allow_negative_balance": true
    },
    "balance": 0,
  "exposure": 0,
  "created_at": "2025-09-08T12:00:00.000Z"
  },
  "message": "User fetched successfully"
}

The API will respond with the updated user's preferences:

{
  "message": "account preference updated successfully"
}

Get Paginated Users

Retrieve a list of users for your account. Supports pagination, optional search, and sorting.

Parameters (query string):

• page (default 1) – Page number (min 1)
• per_page (default 20) – Results per page (1–100)
• search – Partial match on name or reference (case-insensitive)
• sort_by (default created_at) – One of: id, name, reference, created_at, balance, exposure
• sort_order (default desc) – asc or desc

cURL

# Using token authentication
curl -X GET "$baseUrl/account/user?page=1&per_page=2" \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json"

# Or using API key authentication
curl -X GET "$baseUrl/account/user?page=1&per_page=2" \
  -H "Authorization: Basic $base64_encoded" \
  -H "Content-Type: application/json"

JavaScript

const listUsers = async (auth, params = {}) => {
  let authHeader;
  if (auth.token) authHeader = `Bearer ${auth.token}`;
  else if (auth.apiKeys) authHeader = `Basic ${auth.apiKeys.base64_encoded}`;

  const q = new URLSearchParams(params).toString();
  const response = await fetch(`${baseUrl}/account/user${q ? `?${q}` : ''}`, {
    method: 'GET',
    headers: {
      Authorization: authHeader,
      'Content-Type': 'application/json'
    }
  });
  return response.json();
};

// Usage
const auth = await getAuthentication();
listUsers(auth, { page: 1, per_page: 2 }).then(console.log);

Python

import requests

def list_users(auth, params=None):
    params = params or {"page": 1, "per_page": 2}
    url = f"{base_url}/account/user"
    headers = { 'Content-Type': 'application/json' }

    if 'token' in auth:
        headers['Authorization'] = f"Bearer {auth['token']}"
    elif 'apiKeys' in auth:
        headers['Authorization'] = f"Basic {auth['apiKeys']['base64_encoded']}"

    response = requests.get(url, headers=headers, params=params)
    print(response.json())

# Usage
auth = get_authentication()
list_users(auth, {"page": 1, "per_page": 2})

Rust

use reqwest::Client;
use serde_json::Value;

enum AuthMethod { Token(String), ApiKeys(ApiKeys) }

async fn list_users(client: &Client, base_url: &str, auth: &AuthMethod) -> Result<Value, Box<dyn std::error::Error>> {
    let mut req = client
        .get(&format!("{}/account/user?page=1&per_page=2", base_url))
        .header("Content-Type", "application/json");

    match auth {
        AuthMethod::Token(t) => req = req.header("Authorization", format!("Bearer {}", t)),
        AuthMethod::ApiKeys(k) => req = req.header("Authorization", format!("Basic {}", k.base64_encoded)),
    }

    let resp = req.send().await?;
    let data = resp.json::<Value>().await?;
    println!("Users: {:?}", data);
    Ok(data)
}

Sample response:

{
  "data": {
    "items": [
      {
        "id": 1,
        "account_id": 2,
        "reference": "a2_user_4lH6u7hayvaqs6Ix",
        "name": "Jane Doe",
        "role": "user",
        "preferences": { "allow_negative_balance": true },
        "balance": 0,
        "exposure": 0,
        "created_at": "2025-09-08T12:00:00.000Z"
      },
      {
        "id": 2,
        "account_id": 2,
        "reference": "a2_user_Xhwz442NTj74z6F0",
        "name": "John Doe",
        "role": "user",
        "preferences": {},
        "balance": 0,
        "exposure": 0,
        "created_at": "2025-09-08T12:05:10.000Z"
      }
    ],
    "page": 1,
    "per_page": 2,
    "total": 12,
    "total_pages": 6
  },
  "message": "Users fetched successfully"
}