Skip to main content
GET
/
v1
/
customers
List Customers
curl --request GET \
  --url https://{cluster}.voucherify.io/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>'
{
  "object": "list",
  "data_ref": "customers",
  "customers": [
    {
      "id": "cust_CSnYd37MXmrbS19XCrghjBsv",
      "source_id": "source_123",
      "name": "Bob Smith",
      "description": "A frequent customer",
      "email": "bob.smith@email.com",
      "phone": "+1 933 222 3333",
      "birthdate": "2022-01-01",
      "address": {
        "city": "New York",
        "state": "NY",
        "line_1": "123 Main St.",
        "line_2": "APT 3 BLG 5",
        "country": "United States",
        "postal_code": "10001"
      },
      "summary": {
        "redemptions": {
          "total_redeemed": 1,
          "total_failed": 0,
          "total_succeeded": 1,
          "total_rolled_back": 0,
          "total_rollback_failed": 0,
          "total_rollback_succeeded": 0,
          "gift": {
            "redeemed_amount": 0,
            "amount_to_go": 0
          },
          "loyalty_card": {
            "redeemed_points": 0,
            "points_to_go": 4200
          }
        },
        "orders": {
          "total_amount": 1600,
          "total_count": 1,
          "average_amount": 1600,
          "last_order_amount": 1600,
          "last_order_date": "2022-08-30T10:17:39.220Z"
        }
      },
      "loyalty": {
        "points": 2200,
        "referred_customers": 0,
        "campaigns": {
          "Christmas Campaign": {
            "points": 1000,
            "referred_customers": 0
          },
          "Fall Campaign": {
            "points": 75,
            "referred_customers": 0
          },
          "Winter Campaign": {
            "points": 75,
            "referred_customers": 0
          },
          "Summer Campaign": {
            "points": 50,
            "referred_customers": 0
          },
          "Spring Campaign": {
            "points": 1000,
            "referred_customers": 0
          }
        }
      },
      "referrals": {
        "total": 1,
        "campaigns": [
          {
            "campaign_id": "camp_rRsfatlwN7unSeUIJDCYedal",
            "referrer_id": "cust_sehkNIi8Uq2qQuRqSr7xn4Zi",
            "related_object_id": "r_0b9d4c5121d64dd01d",
            "related_object_type": "redemption",
            "date": "2022-08-30T10:17:41.089Z"
          }
        ]
      },
      "metadata": {
        "lang": "en",
        "test": true
      },
      "system_metadata": {},
      "created_at": "2022-08-30T06:32:07.380Z",
      "updated_at": "2022-08-30T10:17:58.049Z",
      "object": "customer"
    },
    {
      "id": "cust_X0hU04x7FeisPnD5lctZcQkI",
      "source_id": "jane.smith@email.com",
      "name": "Jane Smith",
      "description": "A nice customer",
      "email": "jane.smith@email.com",
      "phone": "+1 933 222 3333",
      "birthdate": "2022-01-02",
      "address": {
        "city": "New Yorke",
        "state": "NY",
        "line_1": "123 Main Ste.",
        "line_2": "APT 3 BLG 4e",
        "country": "United Statese",
        "postal_code": "10001e"
      },
      "summary": {
        "redemptions": {
          "total_redeemed": 4,
          "total_failed": 0,
          "total_succeeded": 4,
          "total_rolled_back": 1,
          "total_rollback_failed": 0,
          "total_rollback_succeeded": 1,
          "gift": {
            "redeemed_amount": 0,
            "amount_to_go": 0
          },
          "loyalty_card": {
            "redeemed_points": 0,
            "points_to_go": 15549
          }
        },
        "orders": {
          "total_amount": 210000,
          "total_count": 3,
          "average_amount": 70000,
          "last_order_amount": 70000,
          "last_order_date": "2022-08-30T11:51:08.029Z"
        }
      },
      "loyalty": {
        "points": 15399,
        "referred_customers": 0,
        "campaigns": {
          "Christmas Campaign": {
            "points": 7000,
            "referred_customers": 0
          },
          "Fall Campaign": {
            "points": 2299,
            "referred_customers": 0
          },
          "Winter Campaign": {
            "points": 25,
            "referred_customers": 0
          },
          "Summer Campaign": {
            "points": 75,
            "referred_customers": 0
          },
          "Spring Campaign": {
            "points": 6000,
            "referred_customers": 0
          }
        }
      },
      "referrals": {
        "total": 2,
        "campaigns": [
          {
            "campaign_id": "camp_rRsfatlwN7unSeUIJDCYedal",
            "referrer_id": "cust_sehkNIi8Uq2qQuRqSr7xn4Zi",
            "related_object_id": "r_0b9d4cc4aa164dd073",
            "related_object_type": "redemption",
            "date": "2022-08-30T10:19:39.196Z"
          },
          {
            "campaign_id": "camp_YDsFdX8TgFtT0RUuKEFyhqs3",
            "referrer_id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv",
            "related_object_id": "r_0b9d61b6484ead0324",
            "related_object_type": "redemption",
            "date": "2022-08-30T11:51:10.445Z"
          }
        ]
      },
      "metadata": {
        "lang": "en",
        "test": false
      },
      "system_metadata": {},
      "created_at": "2022-08-09T09:50:53.620Z",
      "updated_at": "2022-08-30T11:51:24.327Z",
      "object": "customer"
    }
  ],
  "total": 2
}

Authorizations

​
X-App-Id
string
header
required
​
X-App-Token
string
header
required
​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
limit
integer

Limits the number of objects to be returned. The limit can range between 1 and 100 items. If no limit is set, it returns 10 items.

Required range: 1 <= x <= 100
​
page
integer

Which page of results to return. The lowest value is 1, the highest value is 99.

Required range: 1 <= x <= 99
​
email
string

Limit the customers to the ones that have this specific email address.

​
city
string

Limit the customers to the ones that are located in the specified city.

​
name
string

Filter customers by the name property.

​
segment_id
string

Filter customers by the segment id.

​
created_at[before]
string<date-time>

Filter customers by date customer was created.

Example:

"2023-12-22T10:13:06.487Z"

​
created_at[after]
string<date-time>

Filter customers by date customer was created.

Example:

"2023-12-22T10:13:06.487Z"

​
updated_at[before]
string<date-time>

Filter customers by date customer was updated last time.

Example:

"2023-12-22T10:13:06.487Z"

​
updated_at[after]
string<date-time>

Filter customers by date customer was updated last time.

Example:

"2023-12-22T10:13:06.487Z"

​
order
enum<string>

This is a property that controls the sorting direction of the results. Sort the results using one of the filtering options, where the dash - preceding a sorting option means sorting in a descending order.

Available options:
created_at,
-created_at,
updated_at,
-updated_at,
source_id,
-source_id
​
starting_after
string<date-time>

A cursor for pagination. This is a date-time value that defines your place in the list based on created_at property from the customer object. For instance, if you make a list request and receive 100 objects, ending with an object created at 2020-05-24T13:43:09.024Z, your subsequent call can include starting_after=2020-05-24T13:43:09.024Z in order to fetch the next page of the list.

<!-- title: Options -->
OptionFormatSorting
Return customers before a specific creation date- set starting_after parameter to the breakpoint dateSorting order is descending; the most recent dates first and least recent dates last.
Return customers after a specific create or update date- include the order parameter set to created_at or updated_at<br>- set starting_after to the breakpoint dateSorting order is ascending; the least recent dates first and the most recent dates last.
Example:

"2023-12-22T10:13:06.487Z"

Response

200 - application/json

Returns a dictionary with customer objects. The customers are returned sorted by creation date, with the most recent customers appearing first.

Response body schema for GET v1/customers.

​
object
string
default:list
required

The type of the object represented by JSON. This object stores information about customers in a dictionary.

​
data_ref
string
default:customers
required

Identifies the name of the attribute that contains the array of customer objects.

​
customers
Customer Response Data · object[]
required

Contains array of customer objects.

​
total
integer
required

Total number of customers.

​
has_more
boolean

As query results are always limited (by the limit parameter), the has_more flag indicates if there are more records for given filter parameters. This lets you know if you can run another request (with a different end date filter) to get more records returned in the results.

⌘I