> ## Documentation Index > Fetch the complete documentation index at: https://dev.smile.io/llms.txt > Use this file to discover all available pages before exploring further. # List customers > Retrieves a list of customers based on a set of provided filters. export const scope_0 = "customer:read" This endpoint requires the **{scope_0}** scope. Results are sorted by `id` in descending order. To lookup customers by email, include the `email` query parameter. Note however that Smile does not enforce uniqueness on email, so multiple customer records may be returned if they have the same email address. ## OpenAPI ````yaml schemas/rest-api.json GET /customers openapi: 3.1.0 info: title: Smile.io REST API version: 1.0.0 description: A RESTful interface for interacting with Smile.io loyalty programs. servers: - url: https://api.smile.io/v1 security: - bearerAuth: [] paths: /customers: get: tags: - Customers summary: List customers description: Retrieves a list of customers based on a set of provided filters. operationId: get__customers parameters: - name: email in: query required: false schema: type: string description: Filter results to only customers with the provided email address. description: Filter results to only customers with the provided email address. - name: state in: query required: false schema: type: string description: Filter results to only customers with the provided state. enum: - candidate - member - disabled description: Filter results to only customers with the provided state. - name: updated_at_min in: query required: false schema: type: string description: >- Filter results to only customers updated after the provided date and time. format: date-time example: '2024-04-04T15:10:42.030Z' description: >- Filter results to only customers updated after the provided date and time. - name: limit in: query required: false schema: type: integer description: The maximum number of customers to retrieve. example: 1 minimum: 1 maximum: 250 default: 50 description: The maximum number of customers to retrieve. - name: cursor in: query required: false schema: type: string description: Cursor for the page of customers to retrieve. description: Cursor for the page of customers to retrieve. - name: include in: query required: false schema: type: string description: >- A comma-separated list of related objects to include in the response. enum: - vip_status description: >- A comma-separated list of related objects to include in the response. responses: '200': description: The customers were successfully retrieved. content: application/json: schema: type: object properties: customers: type: array items: $ref: '#/components/schemas/Customer' metadata: $ref: '#/components/schemas/PaginationMetadata' components: schemas: Customer: type: object properties: id: type: integer example: 304169228 description: Unique identifier for the customer in Smile. first_name: type: - string - 'null' example: Jane description: The customer's first name. last_name: type: - string - 'null' example: Doe description: The customer's last name. email: type: string example: jane@doe.com description: The customer's email address. state: type: string enum: - candidate - member - disabled example: member description: The customer's state in the loyalty program. date_of_birth: type: - string - 'null' format: date example: '1004-05-27' description: >- The customer's birthday. A year value of `1004` means only the customer's birth day and month was entered. points_balance: type: integer example: 300 description: The customer's current points balance. referral_url: type: string example: http://i.refs.cc/9qr5Pw description: >- The customer's unique referral URL. Used to share with friends as part of the referral program. vip_tier_id: type: - integer - 'null' example: 426715794 deprecated: true description: >- The ID of the customer's current VIP tier. This field is now deprecated, use the nested `vip_status.vip_tier_id` instead. vip_status: type: object properties: vip_tier_id: type: - integer - 'null' example: 426715794 description: The ID of the customer's current VIP tier. vip_tier_expires_at: type: - string - 'null' format: date-time example: '2026-12-31T23:59:59.999Z' description: >- The date the customer's current VIP tier expires. For all-time VIP programs, this will be `null` because tiers do not expire. progress_value: type: - number - 'null' format: float example: 300 description: >- The amount the customer has already spent or earned within the current VIP period. current_vip_period_end: type: - string - 'null' format: date-time example: '2025-12-31T23:59:59.999Z' description: >- The end date for the current VIP period. For calendar-year VIP programs, this will be the end of the current calendar year. For all-time VIP programs, this will be `null`. delta_to_retain_vip_tier: type: - number - 'null' format: float description: >- The additional amount the customer must spend or earn before the end of the current VIP period to retain their VIP tier until the end of the next VIP period. For all-time VIP programs or if the customer has already spent or earned enough this period to retain their current VIP tier, this will be `null`. next_vip_tier_id: type: - integer - 'null' example: 426715799 description: >- The ID of the next VIP tier that the customer will move into if they meet the minimum spending or earning requirement. If the customer is already in the highest tier, this will be `null`. delta_to_next_vip_tier: type: - number - 'null' format: float example: 200 description: >- The amount the customer must spend or earn within the current VIP period to reach the next VIP tier. If the customer is already in the highest tier, this will be `null`. description: >- An object containing details about the customer's status within the VIP program. created_at: type: string format: date-time example: '2024-04-04T15:10:42.030Z' description: The date and time when the customer was created. updated_at: type: string format: date-time example: '2025-04-04T15:10:42.030Z' description: The date and time when the customer was last updated. PaginationMetadata: type: object properties: next_cursor: type: - string - 'null' example: aWQ6MixkaXJlY3Rpb246bmV4dA== description: >- A cursor value that when present, can be used to retrieve the next page of results. previous_cursor: type: - string - 'null' example: '' description: >- A cursor value that when present, can be used to retrieve the previous page of results. securitySchemes: bearerAuth: type: http scheme: bearer ````