Skip to main content
GET
/
api
/
v1
/
users
curl -X GET "http://localhost:3000/api/v1/users?programId=prog_123abc&limit=25&offset=0" \
  -H "Authorization: Bearer sk_your_secret_key_here"

{
  "users": [
    {
      "id": "user_123abc",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "user_456def",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-16T14:20:00Z"
    }
  ]
}
Retrieve a list of all students who are ambassadors in your programs. This endpoint supports filtering and pagination to help you manage large directories of student ambassadors.

​
Overview

The List Users endpoint returns a paginated list of all student ambassadors enrolled in your referral programs. Use this endpoint to:
  • View all ambassadors across your programs
  • Filter ambassadors by program
  • Implement pagination for large datasets
  • Build dashboards showing ambassador statistics

​
Authentication

This endpoint requires authentication using a Bearer token in the Authorization header: 
Authorization: Bearer sk_your_secret_key_here

​
Query Parameters

​
programId
string
Filter results to only include users from a specific program. This is useful when you want to see ambassadors for a particular program.Example: programId=prog_123abc
​
limit
integer
default:"50"
Maximum number of results to return per page. The default is 50, and the maximum is typically 100. Use this parameter along with offset to implement pagination.Example: limit=25 returns 25 users per page
​
offset
integer
default:"0"
Number of results to skip before starting to return results. Use this for pagination - if you’re on page 2 with a limit of 50, set offset to 50.Example: offset=50 skips the first 50 results

​
Request Example

curl -X GET "http://localhost:3000/api/v1/users?programId=prog_123abc&limit=25&offset=0" \
  -H "Authorization: Bearer sk_your_secret_key_here"

​
Response

The API returns a JSON object containing an array of user objects:
​
users
array
required
Array of user objects, each containing information about a student ambassador.
Each user object in the array contains:
​
id
string
required
Unique identifier for the user (student ambassador).
​
first_name
string
required
First name of the student ambassador.
​
last_name
string
required
Last name of the student ambassador.
​
email
string
required
Email address of the student ambassador.
​
program_id
string
required
ID of the program this user belongs to.
​
created_at
string
required
ISO 8601 timestamp of when the user was created.

​
Response Example

{
  "users": [
    {
      "id": "user_123abc",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "user_456def",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "program_id": "prog_123abc",
      "created_at": "2024-01-16T14:20:00Z"
    }
  ]
}

​
Pagination

To paginate through results, use the limit and offset parameters: Page 1 (first 50 users): 
GET /api/v1/users?limit=50&offset=0
Page 2 (next 50 users): 
GET /api/v1/users?limit=50&offset=50
Page 3 (next 50 users): 
GET /api/v1/users?limit=50&offset=100
Continue incrementing the offset by the limit value for each subsequent page.

​
Error Responses

​
401
object
Unauthorized - Invalid or missing API key
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

​
Use Cases

​
Building an Ambassador Dashboard

Use this endpoint to fetch all ambassadors and display them in a dashboard: 
async function fetchAllAmbassadors(programId) {
  const response = await fetch(
    `http://localhost:3000/api/v1/users?programId=${programId}&limit=100`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  const data = await response.json();
  return data.users;
}

​
Implementing Pagination

For large datasets, implement pagination to improve performance: 
async function fetchUsersPage(page = 1, pageSize = 50) {
  const offset = (page - 1) * pageSize;
  const response = await fetch(
    `http://localhost:3000/api/v1/users?limit=${pageSize}&offset=${offset}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  return await response.json();
}

​
Best Practices

  1. Use pagination - Always use limit and offset for large datasets to avoid timeouts
  2. Filter by program - Use programId to narrow results when you only need users from specific programs
  3. Cache results - User lists don’t change frequently, so consider caching responses
  4. Handle errors - Always check for 401 errors and prompt users to refresh their API key

​
Rate Limits

This endpoint is subject to rate limiting. Check the response headers for rate limit information:
  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Remaining requests in current window
  • X-RateLimit-Reset - Time when the rate limit resets

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
programId
string

Filter by program ID

​
limit
integer
default:50

Maximum number of results to return

​
offset
integer
default:0

Number of results to skip

Response

List of users

​
users
object[]