Add User to Dynamic Pass Template API

Overview

The Add User API creates a customer record in the Manage Users group attached to your dynamic pass template and issues the corresponding digital pass in a single synchronous call. This is the same endpoint the Manage Users dashboard uses when you add a user from the UI, so the behavior is identical across API and dashboard.

Base URL

https://app.addtowallet.co

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

Path Parameters

groupId (string, required): The ID of the user group attached to your dynamic pass template. The groupId is returned by Create Template and can be looked up any time via List User Groups.

Authentication

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

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

Request Body

Send a single JSON object whose keys are the dynamic fields declared on the template. There is no fixed schema — the accepted keys are exactly the field names you passed in the dynamicFields array when you created the template. To add multiple users, call this endpoint once per user.

Request Body (shape)

Name	Type	Required	Description
...dynamicFields	`object`	Yes	Key/value pairs matching the dynamic fields declared on the template. Every field declared on the template should be provided. Keys not declared on the template are stored on the customer record but ignored by the pass renderer.

For the Employee Business Card Template created on the Create Template page, the dynamic fields are the following. Every example on this page uses these exact keys:

Example: Employee Business Card fields

Name	Type	Required	Description
companyName	`string`	Yes	Company name — rendered as the pass title.
employeeName	`string`	Yes	Full name of the employee — rendered as the pass header.
position	`string`	Yes	Job title shown on the pass.
department	`string`	Yes	Department shown on the pass.
phone	`string`	Yes	Phone number — also powers the "Call" link on the pass.
email	`string`	Yes	Email address — also powers the "Email" link on the pass.
employeeId	`string`	Yes	Employee identifier encoded into the QR / barcode.
websiteUrl	`string`	Yes	Company website opened from the pass link.

Dynamic Field Mapping

Field keys are case-sensitive and must match the dynamic field names declared when the template was created. A value you send for phone replaces every {phone} placeholder in the template; a key the template doesn't declare simply has no placeholder to fill, so it never appears on the pass.

Manage Users Integration

This endpoint is the same one used by the Manage Users dashboard:

• Creates a customer record in the template's user group
• Issues the pass synchronously and links it to the customer
• Updates the group's total user count automatically
• Customer can later be updated or deleted, and tracked via List Users

Request Example

curl -X POST 'https://app.addtowallet.co/api/manage-users/groups/66b6005bb7bddce8f05a3392/customers' \
  -H 'apikey: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
  "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"
}'

Response

On success the API returns a JSON object containing:

Success Response Fields

success (boolean): True when the user was added and the pass was issued.
message (string): Human-readable status message.
passId (string | null): The ID of the pass that was created for this customer.
customerId (string | null): The ID of the customer record created in the group.

Response Example

{
  "success": true,
  "message": "User added to the group, pass creation completed",
  "passId": "686d10e7c2f0bc5cdf25c84e",
  "customerId": "686d10e7c2f0bc5cdf25c84b"
}

What to keep from the response

• Store customerId — you'll need it to Update or Delete this user later.
• Store passId — it identifies the issued wallet pass and appears again in List Users.

Error Code	Description
400	Bad Request - Missing required dynamic fields or invalid data format.
401	Unauthorized - Missing or invalid API key.
403	Forbidden - Insufficient permissions for the requested group.
404	Not Found - Group with the specified ID does not exist or is not accessible.
429	Too Many Requests - API rate limit exceeded. Please wait before making additional requests.
500	Internal Server Error - Pass creation failed for the new customer. Please contact support.