> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # List Customers > Returns a list of customers. ## OpenAPI ````yaml /openapi/customers.json get /v1/customers openapi: 3.0.1 info: title: Voucherify API - Customers version: v2018-08-01 description: >- Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details. contact: name: Voucherify Team url: https://www.voucherify.io/contact-support email: support@voucherify.io termsOfService: https://www.voucherify.io/legal/subscription-agreement license: name: MIT url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE servers: - url: https://{cluster}.voucherify.io description: Base URL variables: cluster: default: api enum: - api - us1.api - as1.api - download - us1.download - as1.download security: [] paths: /v1/customers: get: tags: - Customers summary: List Customers description: Returns a list of customers. operationId: list-customers parameters: - $ref: '#/components/parameters/limit' - name: page in: query required: false schema: $ref: '#/components/schemas/ParameterPage99' description: >- Which page of results to return. The lowest value is `1`, the highest value is `99`. - schema: $ref: '#/components/schemas/ParameterString' in: query name: email description: >- Limit the customers to the ones that have this specific email address. - schema: $ref: '#/components/schemas/ParameterString' in: query description: >- Limit the customers to the ones that are located in the specified city. name: city - schema: $ref: '#/components/schemas/ParameterString' in: query description: Filter customers by the name property. name: name - schema: $ref: '#/components/schemas/ParameterString' in: query description: >- Filter customers by the segment ID. Warning: Passing additional query parameter filters that are in conflict with the segment filters may return unexpected results. name: segment_id - schema: $ref: '#/components/schemas/ParameterDate' in: query description: Filter customers by date customer was created. name: created_at[before] - schema: $ref: '#/components/schemas/ParameterDate' in: query description: Filter customers by date customer was created. name: created_at[after] - schema: $ref: '#/components/schemas/ParameterDate' in: query description: Filter customers by date customer was updated last time. name: updated_at[before] - schema: $ref: '#/components/schemas/ParameterDate' in: query description: Filter customers by date customer was updated last time. name: updated_at[after] - schema: $ref: '#/components/schemas/ParameterOrderListCustomers' in: query name: order description: >- 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. - schema: $ref: '#/components/schemas/ParameterDate' in: query name: starting_after description: > 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. | **Option** | **Format** | **Sorting** | |:---|:---|:---| | Return customers **before** a specific creation date | - set `starting_after` parameter to the breakpoint date | Sorting 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`
- set `starting_after` to the breakpoint date | Sorting order is **ascending**; the least recent dates first and the most recent dates last. | responses: '200': description: >- Returns a dictionary with customer objects. The customers are returned sorted by creation date, with the most recent customers appearing first. content: application/json: schema: $ref: '#/components/schemas/CustomersListResponseBody' examples: Example: value: 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 security: - X-App-Id: [] X-App-Token: [] - X-Voucherify-OAuth: - api - customers components: parameters: limit: name: limit in: query required: false schema: $ref: '#/components/schemas/ParameterLimit' description: >- 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. schemas: ParameterPage99: type: integer minimum: 1 maximum: 99 ParameterString: type: string ParameterDate: type: string example: '2023-12-22T10:13:06.487Z' format: date-time ParameterOrderListCustomers: type: string enum: - created_at - '-created_at' - updated_at - '-updated_at' - source_id - '-source_id' CustomersListResponseBody: title: Customers List Response Body description: Response body schema for **GET** `v1/customers`. properties: object: type: string default: list description: >- The type of the object represented by JSON. This object stores information about customers in a dictionary. data_ref: type: string default: customers description: >- Identifies the name of the attribute that contains the array of customer objects. customers: type: array description: Contains array of customer objects. items: $ref: '#/components/schemas/CustomerWithSummaryLoyaltyReferrals' total: type: integer description: Total number of customers. has_more: type: boolean description: >- 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. required: - object - data_ref - customers - total ParameterLimit: type: integer maximum: 100 minimum: 1 CustomerWithSummaryLoyaltyReferrals: title: Customer With Summary Loyalty Referrals allOf: - type: object title: Customer Response Data properties: id: type: string description: >- The ID of an existing customer that will be linked to redemption in this request. source_id: type: string description: >- A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored. summary: nullable: true allOf: - $ref: '#/components/schemas/CustomerSummary' loyalty: nullable: true allOf: - $ref: '#/components/schemas/CustomerLoyalty' referrals: nullable: true allOf: - $ref: '#/components/schemas/CustomerReferrals' system_metadata: type: object description: Object used to store system metadata information. created_at: type: string description: >- Timestamp representing the date and time when the customer was created. The value is shown in the ISO 8601 format. example: '2022-08-30T06:32:07.380Z' format: date-time updated_at: type: string description: >- Timestamp representing the date and time when the customer was updated. The value is shown in the ISO 8601 format. example: '2022-08-31T06:32:07.380Z' format: date-time assets: type: object description: >- Contains information about the customer's cockpit. ⚠️ Warning: Customer cockpits were removed. The customer cockpit URLs redirect to customer preference center. properties: cockpit_url: type: string description: >- URL address to customer preference center. Previously, a customer's cockpit URL address. cockpit_preference_center_url: type: string description: URL address to customer preference center. object: type: string description: The type of the object represented by JSON. default: customer enum: - customer required: - summary - loyalty - referrals - object - $ref: '#/components/schemas/CustomerBase' CustomerSummary: title: Customer Summary type: object properties: redemptions: $ref: '#/components/schemas/CustomerSummaryRedemptions' orders: $ref: '#/components/schemas/CustomerSummaryOrders' required: - redemptions - orders CustomerLoyalty: title: Customer Loyalty type: object properties: points: type: integer description: >- Customer's loyalty points minus expired for all loyalty cards which the customer has. referred_customers: type: integer description: Total number of customers referred by the customer. campaigns: type: object description: >- Contains campaigns with details about point balances and how many customers were referred by the customer. additionalProperties: type: object description: >- Contains details about the point balances left on loyalty cards and the number of referred customers in each campaign. properties: points: type: integer description: Remaining point balance in campaign. loyalty_tier: type: string example: ltr_UJ5Q54Q0OvEhua87Qfv2Ki5x description: Customer's loyalty tier within the campaign. referred_customers: type: integer description: Number of customers referred by the customer in campaign. required: - points - referred_customers - campaigns CustomerReferrals: title: Customer Referrals type: object description: >- Summary of customer's referrals, in this case, the customer being the referee, i.e. information about the source of referrals and number of times the customer was referred by other customers. properties: total: type: integer description: >- Total number of times this customer received a referral, i.e. was referred by another customer. campaigns: type: array description: >- Contains an array of campaigns that served as the source of a referral for the customer. items: title: Customer Referrals Campaigns Item type: object description: Contains information about the source of the referral. properties: campaign_id: type: string description: Unique campaign ID, assigned by Voucherify. example: camp_rRsfatlwN7unSeUIJDCYedal referrer_id: type: string example: cust_sehkNIi8Uq2qQuRqSr7xn4Zi description: >- Unique referrer ID, assigned by Voucherify. This is the customer ID of a customer that is referring this customer. related_object_id: type: string description: Related object id example: r_0b9d4cc4aa164dd073 related_object_type: type: string description: Related object type, i.e. `redemption`. date: type: string format: date-time example: '2022-08-30T10:19:39.196Z' description: >- Timestamp representing the date and time when the customer was referred in ISO 8601 format. required: - campaign_id - referrer_id - related_object_id - related_object_type - date required: - total - campaigns CustomerBase: title: Customer Base type: object properties: name: type: string description: Customer's first and last name. description: type: string description: An arbitrary string that you can attach to a customer object. email: type: string description: Customer's email address. phone: type: string description: >- Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel. birthday: type: string description: '`Deprecated`. ~~Customer''s birthdate; format YYYY-MM-DD~~.' format: date birthdate: type: string description: Customer's birthdate; format YYYY-MM-DD. format: date address: type: object nullable: true description: Customer's address. properties: city: type: string description: City state: type: string description: State line_1: type: string description: First line of address. line_2: type: string description: Second line of address. country: type: string description: Country. postal_code: type: string description: Postal code. metadata: type: object description: >- A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. CustomerSummaryRedemptions: title: Customer Summary Redemptions type: object properties: total_redeemed: type: integer description: Total number of redemptions made by the customer. total_failed: type: integer description: Total number of redemptions that failed. total_succeeded: type: integer description: Total number of redemptions that succeeded. total_rolled_back: type: integer description: Total number of redemptions that were rolled back for the customer. total_rollback_failed: type: integer description: Total number of redemption rollbacks that failed. total_rollback_succeeded: type: integer description: Total number of redemption rollbacks that succeeded. gift: type: object description: Summary of gift card credits. required: - redeemed_amount - amount_to_go properties: redeemed_amount: type: integer description: >- Total amount of gift card credits redeemed by customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. default: 0 amount_to_go: type: integer description: >- Remaining gift card balance across all gift cards. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. default: 0 loyalty_card: type: object description: Summary of loyalty points. required: - redeemed_points - points_to_go properties: redeemed_points: type: integer description: Total number of loyalty points redeemed by the customer. points_to_go: type: integer description: >- Sum of remaining available point balance across all loyalty cards. required: - total_redeemed - total_failed - total_succeeded - total_rolled_back - total_rollback_failed - total_rollback_succeeded - gift - loyalty_card CustomerSummaryOrders: title: Customer Summary Orders description: >- Lists details about orders related to the customer. Lists only data for orders with the `PAID` or `FULFILLED` status. Data from orders with a `CREATED` or `CANCELED` status are not included. The data is updated also when an order changes status. type: object properties: total_amount: type: integer description: >- The total amount spent by the customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. total_count: type: integer description: Total number of orders made by the customer. average_amount: type: integer description: >- Average amount spent on orders. `total_amount` ÷ `total_count`. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. last_order_amount: type: integer description: >- Amount spent on last order. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. last_order_date: type: string format: date-time example: '2022-08-30T11:51:08.029Z' description: >- Timestamp representing the date and time of the customer's last order in ISO 8601 format. required: - total_amount - total_count - average_amount - last_order_amount securitySchemes: X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header X-Voucherify-OAuth: type: oauth2 flows: implicit: authorizationUrl: https://api.voucherify.io/v1/oauth/token scopes: api: Gives access to whole server-side API. vouchers: >- Gives access to all endpoints and methods starting with `v1/vouchers`. client_api: Gives access to whole client-side API. client_vouchers: >- Gives access to all endpoints and methods starting with `/client/v1/vouchers`. promotions: >- Gives access to all endpoints and methods starting with `/v1/promotions`. client_promotions: >- Gives access to all endpoints and methods starting with `/client/v1/promotions` campaigns: >- Gives access to all endpoints and methods starting with `v1/campaigns`. client_publish: >- Gives access to all endpoints and methods starting with `/client/v1/publish`. exports: >- Gives access to all endpoints and methods starting with `/v1/exports`. publications: >- Gives access to all endpoints and methods starting with `/v1/publications`. client_validate: >- Gives access to all endpoints and methods starting with `/client/v1/validate`. validations: >- Gives access to all endpoints and methods starting with `/v1/validations`. client_validations: >- Gives access to all endpoints and methods starting with `/client/v1/validations`. qualifications: >- Gives access to all endpoints and methods starting with `/v1/qualifications`. client_qualifications: >- Gives access to all endpoints and methods starting with `/client/v1/qualifications`. client_redeem: >- Gives access to all endpoints and methods starting with `/client/v1/redeem redemptions: >- Gives access to all endpoints and methods starting with `/v1/redemptions`. client_redemptions: >- Gives access to all endpoints and methods starting with `/client/v1/redemptions` customers: >- Gives access to all endpoints and methods starting with `/v1/customers`. client_customers: >- Gives access to all endpoints and methods starting with `/client/v1/customers`. orders: >- Gives access to all endpoints and methods starting with `/v1/orders`. products: >- Gives access to all endpoints and methods starting with `/v1/products`. skus: >- Gives access to all endpoints and methods starting with `/v1/SKUs`. validation-rules: >- Gives access to all endpoints and methods starting with `/v1/validation-rules`. validation-rules-assignments: >- Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments segments: >- Gives access to all endpoints and methods starting with `/v1/segments`. events: >- Gives access to all endpoints and methods starting with `/v1/events`. client_events: >- Gives access to all endpoints and methods starting with `client/v1/events`. rewards: >- Gives access to all endpoints and methods starting with `/v1/rewards`. assets: >- Gives access to all endpoints and methods starting with `/v1/assets`. task-results: >- Gives access to all endpoints and methods starting with `/v1/task-results`. loyalties: >- Gives access to all endpoints and methods starting with `/v1/loyalties`. client_consents: >- Gives access to all endpoints and methods starting with `client/v1/consents`. consents: >- Gives access to all endpoints and methods starting with `/v1/consents`. async-actions: >- Gives access to all endpoints and methods starting with `/v1/async-actions`. product-collections: >- Gives access to all endpoints and methods starting with `/v1/product-collections`. categories: >- Gives access to all endpoints and methods starting with `/v1/categories`. metadata-schemas: >- Gives access to all endpoints and methods starting with `/v1/metadata-schemas`. locations: >- Gives access to all endpoints and methods starting with `/v1/locations`. referrals: >- Gives access to all endpoints and methods starting with `/v1/referrals`. trash-bin: >- Gives access to all endpoints and methods starting with `/v1/trash-bin`. templates: >- Gives access to all endpoints and methods starting with `/v1/templates`. ````