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.

Endpoint

Use the following endpoint to create a new customer:

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.

Parameters

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

Examples

The following payload is an example for this endpoint:

Here it shows how to send a POST request with a unique customerIdentifier and a displayName such as "customerIdentifier": "zanzibarhealthgroup" and "displayName": "Zanzibar Health Group". A successful request returns 201 Created.

POST {URI}/customers
{
  "customerIdentifier": "string", (5-100 chars)
  "displayName": "string", (100 chars)
}

The API returns 400 Bad Request when a field does not meet its requirements. For example, this request uses an identifier that is shorter than five characters: "customerIdentifier": "zhg", "displayName": "Zanzibar Health Group".

POST {URI}/customers

{
  "timestamp": "2025-02-21T23:23:13.930Z",
  "requestId": "example-request-id",
  "path": "/customers",
  "httpCode": 400,
  "httpPhrase": "Bad Request",
  "i18nKey": "string",
  "message": "The customerIdentifier must contain 5–100 characters.",
  "errors": []
}

Response codes

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