List Users in a Group API

Overview

Returns the paginated list of customers in a Manage Users group along with each customer's pass creation status. This is the same endpoint the Manage Users dashboard uses to render the users table, so the data you see in the UI is exactly what this endpoint returns.

Base URL

https://app.addtowallet.co

GET/api/manage-users/groups/:groupId/customers

Path Parameters

groupId (string, required): The ID of the user group attached to your dynamic pass template.

Query Parameters

Name	Type	Required	Description
page	`number`	No	Page number (1-indexed). Defaults to 1.
limit	`number`	No	Number of customers per page. Defaults to 50.
sortField	`string`	No	Field to sort by (for example createdAt, updatedAt). Defaults to createdAt.
sortDirection	`string`	No	Sort order: asc or desc. Defaults to desc.

Authentication

All API requests must include your API key in the request headers:

"apikey": "your-api-key-here"

Request Example

curl 'https://app.addtowallet.co/api/manage-users/groups/66b6005bb7bddce8f05a3392/customers?page=1&limit=50&sortField=createdAt&sortDirection=desc' \
  -H 'apikey: your-api-key-here'

Response

The API returns a paginated list of customer records, each with its pass creation status:

Top-Level Fields

success (boolean): True on success.
data (array): Array of customer objects.
pagination (object): { total, page, limit, pages } describing the page slice.

Customer Object Fields

_id (string): Customer ID. Use this as customerId when calling Update User or Delete User.
groupId (string): The user group this customer belongs to.
hasPass (boolean): true once the pass has been created.
passId (string | null): The pass ID once created.
passCreationStatus (string): One of not_started, queued, pending, created, or failed.
lastExecution (object): { status: "success" | "failed" | "pending", error?: string } — outcome of the most recent pass creation or update attempt.
passRetryCount (number): Number of times the pass creation has been retried.
lastPassAttempt (ISO date, optional): Timestamp of the most recent pass creation attempt.
createdAt, updatedAt (ISO date): Timestamps.
...dynamicFields (various): All the user-provided fields that were sent when the customer was added (for example employeeName, email, phone).

Tracking Pass Creation Status

• Right after Add User, the customer appears with passCreationStatus: "pending" and hasPass: false.
• Once the pass is generated, hasPass flips to true, passId is set and passCreationStatus becomes created.
• If pass generation fails, passCreationStatus is failed and lastExecution.error contains the reason.

Response Example

{
  "success": true,
  "data": [
    {
      "_id": "686d10e7c2f0bc5cdf25c84b",
      "groupId": "66b6005bb7bddce8f05a3392",
      "companyName": "Tech Corp Inc.",
      "employeeName": "John Smith",
      "position": "Software Engineer",
      "department": "Engineering",
      "phone": "+1-555-0123",
      "email": "[email protected]",
      "employeeId": "EMP001",
      "websiteUrl": "https://techcorp.com",
      "hasPass": true,
      "passId": "686d10e7c2f0bc5cdf25c84e",
      "passCreationStatus": "created",
      "lastExecution": {
        "status": "success",
        "error": null
      },
      "createdAt": "2026-03-20T14:22:01.000Z",
      "updatedAt": "2026-03-20T14:22:03.000Z"
    },
    {
      "_id": "686d10e7c2f0bc5cdf25c84d",
      "groupId": "66b6005bb7bddce8f05a3392",
      "companyName": "Tech Corp Inc.",
      "employeeName": "Sarah Johnson",
      "position": "Product Manager",
      "department": "Product",
      "phone": "+1-555-0124",
      "email": "[email protected]",
      "employeeId": "EMP002",
      "websiteUrl": "https://techcorp.com",
      "hasPass": false,
      "passId": null,
      "passCreationStatus": "pending",
      "lastExecution": {
        "status": "pending",
        "error": null
      },
      "createdAt": "2026-03-20T14:22:01.000Z",
      "updatedAt": "2026-03-20T14:22:01.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

Error Code	Description
400	Bad Request - Invalid groupId or query parameter.
401	Unauthorized - Missing or invalid API key.
403	Forbidden - Insufficient permissions to access the group.
404	Not Found - Group with the specified ID does not exist.
429	Too Many Requests - API rate limit exceeded. Please wait before making additional requests.
500	Internal Server Error - Unexpected server error while retrieving customers. Please contact support.