List User Groups API

Overview

Returns every user group in your account. Each dynamic pass template has an associated user group; this endpoint is how you discover the groupId needed by Add User, Update User, Delete User and List Users.

Base URL

https://app.addtowallet.co

GET/api/manage-users/groups

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' \
  -H 'apikey: your-api-key-here'

Response

The API returns an array of group objects in data.

Group Object Fields

_id (string): The group ID. Use this as groupId in the other endpoints.
name (string): Group name.
description (string | null): Group description.
dynamicPassId (string | null): The dynamic pass template this group is linked to. Use it to match a group to the template you created.
source (string | null): api_auto_created if the group was created automatically by an API call, otherwise null (created in the dashboard).
totalUsers (number): Number of customers in the group.
passesCreated, passUpdateCount (number): Lifetime counters.
activeBatches (array): In-flight batches touching this group. Each item has { requestId, type, total, startedAt }.
createdAt, updatedAt (ISO date): Timestamps.

Response Example

{
  "success": true,
  "data": [
    {
      "_id": "69ff3943f0ea7006bf84b7db",
      "name": "Group-455",
      "description": null,
      "dynamicPassId": "69ff3944f0ea7006bf84b7dd",
      "source": null,
      "totalUsers": 5,
      "passesCreated": 5,
      "passUpdateCount": 0,
      "activeBatches": [],
      "createdAt": "2026-05-09T13:40:19.722Z",
      "updatedAt": "2026-05-18T11:37:37.680Z"
    }
  ]
}

Finding the group for a template

Match the group to your template by comparing dynamicPassId in the group object to the dynamicPassId you received from Create Template. Use that group's _id as groupId in the user endpoints.

Caveat for API-only flows

Groups created automatically the first time you call an Add User flow on a template may currently appear with dynamicPassId: null and source: "api_auto_created". If you only interact via API, the recommended pattern is to call List Groups before creating your first user, save the_id of the group you want to use, and pass it to Add User. If you can't find the matching group, contact support.

Error Code	Description
401	Unauthorized - Missing or invalid API key.
429	Too Many Requests - API rate limit exceeded. Please wait before making additional requests.
500	Internal Server Error - Unexpected server error while retrieving groups. Please contact support.