Create a new customer

The POST {URI}/customers endpoint allows you to create a new customer within your platform’s environment. This is essential for platforms that manage multiple clients, departments, or business units, as it enables each customer to have their own accounts, balances, and reward activity—ensuring clean separation and easier management.

Use case

Acme Wellness is expanding its wellness rewards program and has just signed a new corporate client, called Zanzibar Health Group. Each client needs to be tracked separately for reporting, funding, and reward distribution. Using this endpoint, Acme adds ZHG as a new customer in the Tango Card platform so they can have their own accounts, balances, and reward activity. Acme keeps their client data and reward activity segmented, enables custom funding, reporting, and alerts per customer and supports multi-client management under one platform—Acme Wellness.

Use the following endpoint to create a new customer:

Endpoint	Purpose
`POST {URI}/customers`	Create a new customer on this platform.

Use the following query parameters with this endpoint to create a new customer on this platform:

Query params	Data type	Description
customerIdentifier	string	A unique identifier for this customer. It must be between 5-100 characters and accepts the following: 0-9, a-z, and A-Z in any sequence.
displayName	string	A friendly name for this customer. The string must be between 5-100 characters. Emojis are not accepted for `displayName` or any text entry.

The following payload is an example for this endpoint:

{
  "customerIdentifier": "string", (5-100 chars)
  "displayName": "string", (100 chars)
}

Here's an example payload for when you receive an error:

{
  "timestamp": "2025-02-21T23:23:13.930Z",
  "requestId": "string",
  "path": "string",
  "httpCode": 0,
  "httpPhrase": "string",
  "i18nKey": "string",
  "message": "The error message will show here for error codes ",
  "errors": [
    {}
  ]
}

The possible response codes for this endpoint are as follows. For details, see i18nkey codes and their error messages:

Response code	Meaning
201	New resource has been successfully created as a result of the request.
400	The server could not understand the request due to invalid syntax.
401	Authentication is required and has either not been provided or failed.
403	The server understood the request but refuses to authorize it.
409	The request could not be completed because it would cause a conflict with the current state of the resource.
500	Something went wrong on the server, but the server cannot be more specific about what the exact problem is.
503	The server is currently unable to handle the request due to temporary overload or maintenance.