Get a list of all customers

The GET {URI}/customers endpoint allows you to retrieve a complete list of all customers associated with your platform or master account in the Tango platform. This is especially useful for platforms that manage multiple clients, departments, or business units under a single integration.

Use case

Acme is a corporate wellness provider that uses Tango API to distribute digital rewards to employees and clients as part of health challenges, incentive programs, and engagement campaigns. Acme may have multiple sub-clients or departments such as HR, Marketing, etc. each set up as a separate customer in the Tango system.

Use the following endpoint to list all customer profiles under their master account:

Endpoint	Purpose
`GET {URI}/customers`	Get a list of all customers on this platform.

Use the query parameters to filter the payload and improve the results. The following query parameters can be used with this endpoint:

Query params	Data type	Description
displayName	string	A human-readable name used to identify a customer in a more user-friendly way than using a system-generated ID. This field is helpful in queries where you want to locate a customer by name rather than by a UUID or when the customerIdentifier is not known.
status	string	To filter results based on the status of a group or customer. You can query only those entities that match the following group or customer status: -ACTIVE -INACTIVE
customerMinDateCreatedAt	date-time	To filter customer records based on their creation date. It specifies the earliest createdAt timestamp for customers you want to include in your query results. The value must follow the RFC 3339 date-time format, which supports both date-only and full timestamp formats as in this example: "2025-01-01" or "2025-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
customerMaxDateCreatedAt	date-time	To filter customer records based on their creation date. It specifies the latest createdAt timestamp for customers you want to include in your query results. The value must follow the RFC 3339 date-time format, which supports both date-only and full timestamp formats as in this example: "2025-01-01" or "2025-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt>
accountStatus	string	Specify the account status to be queried. See Account status for more information. ACTIVE -INACTIVE -DISABLED -FROZEN -DELETED
accountIdentifier	string	Specify the account identifier to be queried.
accountNumber	string	Specify the account number to be queried.
accountDisplayName	string	Specify the account display name to be queried.
accountMinDateCreatedAt	date-time	To filter account records based on their creation date. It specifies the earliest createdAt timestamp an account must have to be included in the query results. The value must follow the RFC 3339 date-time format, which supports both date-only and full timestamp formats as in this example: "2025-01-01" or "2025-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
accountMaxDateCreatedAt	date-time	To filter account records based on their creation date. It specifies the latest createdAt timestamp an account can have to be included in the query results. The value must follow the RFC 3339 date-time format, which supports both date-only and full timestamp formats as in this example: "2025-01-01" or "2025-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
paginate	boolean	Paginated payload helps managing the payload and prevents API timeout. Select to paginate the results: -true:paginate the results. -false: not to paginate the results. False is the default.
prevCursor	string	The cursor to use for the previous page of results. This will be ignored if paginate is false.
nextCursor	string	The cursor to use for the next page of results. This will be ignored if paginate is false.
maxResults	int32	The maximum number of results to return. The default is 10, and the maximum is 200. This will be ignored if paginate is false.

The following payload is an example for when you use GET {URI}/customers\:


 [
  {
    "customerIdentifier": "string", (5-100 chars)
    "displayName": "string",(100 chars)
    "status": "string",
    "createdAt": "2024-03-11T19:30:55.706Z",
    "accounts": [
      {
        "accountIdentifier": "string", (5-100 chars)
        "accountNumber": "string",
        "displayName": "string", (100 chars)
        "createdAt": "2024-03-11T19:30:55.706Z",
        "status": "string",
        "currencyCode": "string"
      }
    ]
  }
]

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
200	The request was successful.
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.
422	The server understands the request but cannot process it due to semantic errors.
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.