> ## Documentation Index > Fetch the complete documentation index at: https://developers.bspk.com/llms.txt > Use this file to discover all available pages before exploring further. # List Clients > List clients ## OpenAPI ````yaml get /api/extraction/v1/clients openapi: 3.0.3 info: title: EXTRACTION API V1 version: 1.0.0 contact: name: BSPK API Support email: bspk-support@bspk.com description: >- # Introduction The BSPK RESTful JSON API gives you access to your company's BSPK data. For all BSPK API related questions please email: *bspk-support@bspk.com* ### Authentication BSPK uses Token-Based API Authentication. API keys can be managed from the API Keys section in your admin interface. All unauthenticated requests will return an HTTP 401 response. **Important:** Developers with BSPK API keys will be granted full access to the data in each endpoint. Access to this data is binary: everything or nothing. **Authorization header** Your `Authorization` header should be in the following format: ``` Authorization: Bearer [API_KEY] ``` ### Filter params `client_ids`: Accept multiple ids in a comma separated way, eg.: `client_ids=CLI1,CLI2` and can't be combined with `sales_associate_ids` filter param. Example: To filter messages by Sales Associates CL1 and CL2 you should do `https://api.bspk.com/api/extraction/v1/messages?client_ids=CLI1,CLI2`. `sales_associate_ids`: Accept multiple ids in a comma separated way, eg.: `sales_associate_ids=SA1,SA2` and can't be combined with `client_ids` filter param. Example: To filter messages by Sales Associates SA1 and SA2 you should do `https://api.bspk.com/api/extraction/v1/messages?sales_associate_ids=SA1,SA2`. `from`: Accepts date-time value (YYYY-MM-DDTHH:MM:SS) to filter records created after the specified value (boundaries included). Example: To filter messages by a Sales Associate from July 16, 2020 till the present date you should do `https://api.bspk.com/api/extraction/v1/messages?sales_associate_ids=SA1&from=2020-07-16T00:00:00`. `to`: Accepts date-time value (YYYY-MM-DDTHH:MM:SS) to filter records created before the specified value (boundaries included). Example: To filter messages by a Sales Associate since the begining till July 16, 2020 (inclusive) you should do `https://api.bspk.com/api/extraction/v1/messages?sales_associate_ids=SA1&from=2020-07-16T23:59:59`. `page`: Accepts a page number to filter records, defaults to `1`. Example: To return the second page of messages created you should do `https://api.bspk.com/api/v1/messages?page=2`. `per_page`: Accepts a number of records per page to filter records, defaults to `100` (maximum of `1000`). Example: To return the `30` messages per page you should do `https://api.bspk.com/api/extraction/v1/messages?per_page=30`. ### Pagination information We basically expose the pagination information all via header attributes, as follows: - Information about the total records the query will return in total (all pages) you can find the attribute `x-total-count` in the header. - Information about pagination is provided in the [Link header](https://datatracker.ietf.org/doc/html/rfc5988) of an API call. For example, let's make a curl request to the messages API, to find out how many message we have for the client CLI1: `$ curl -I "https://api.bspk.com/api/extraction/v1/messages?client_ids=CLI1"` The `-I` parameter indicates that we only care about the headers, not the actual content. In examining the result, you'll notice some information in the Link header that looks like this: ``` Link: ; rel="next", ; rel="last" ``` Since by default, all paginated queries start at page 1. rel="last" provides some more information, stating that the last page of results is on page 30. Thus, we have 29 more pages of information about messages from client CLI1 that we can consume. Always rely on these link relations provided to you. Don't try to guess or construct your own URL. ### Throttling API requests are limited to the amount specified in the returned `X-RateLimit-Limit` header (per 10 seconds). Exceeding that limit will cause BSPK to return an `HTTP 429` response. Check the `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers to see how many more requests you are allowed until throttling kicks in. ### Error Codes - 400 - Bad Request. - 401 - Unauthorized – Invalid BSPK API key. - 404 - Not Found – Resource not found. - 422 - Unprocessable entity. - 429 - Throttle Limit reached. - 500 - BSPK Internal Server Error ### Validation Methods that take input will validate all parameters. Any parameter that fails validation will trigger an error response with status HTTP 422. The response body will be a JSON object like the example below which includes a list of fields that failed validation. `{'errors':[{'title': 'No clients found with IDs: [NON_EXISTING_ID, OTHER_NON_EXISTING_ID]','code':'not_found'}]}` ### Additional Information - Fields without a value will return null - Timestamps are rendered in ISO-8601 format (e.g. 2018-07-21T17:32:28Z) - BSPK reserves the right to add more properties to objects, but will never change or remove them. Any breaking changes will result in a major API version update. servers: - url: https://api.bspk.com description: Production security: - BearerAuth: [] paths: /api/extraction/v1/clients: get: tags: - Clients summary: List Clients description: List clients operationId: listClients parameters: - name: client_ids in: query required: false description: Client id owned by the brand schema: type: string - name: sales_associate_ids in: query required: false description: Sales Associate id owned by the brand schema: type: string - name: from in: query required: false description: >- Only show clients updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. schema: type: string - name: to in: query required: false description: >- Combined with the `from` parameter, only show clients updated whitin the given range (from..to) time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. schema: type: string - name: page in: query required: false description: 'Page number of the results to fetch. Default: 1' schema: type: string - name: per_page in: query required: false description: 'Results per page (max 100). Default: 30' schema: type: string responses: '200': description: Successful response, returns array of clients content: application/json: example: - bspk_id: 12345 current_sales_associate_id: SA_01 current_sales_associate_name: FirstName-84 LastName-84 current_store_id: null current_store_name: null client_id: EXTERNAL_ID_150 name: FirstName-85 LastName-85 first_name: FirstName-85 last_name: LastName-85 email: someone92@example.com mobile_phone: '+14153400067' other_phone: '+14153400067' birthday: null gender: null nationality: null passport_number: null language: null title: null address: '' addresses: - address: null address_2: null address_3: null address_4: null city: null state: null zip: null country_code: null preferred_contact_channel: null communication_preferences: chat_opt_in: true email_opt_in: true phone_opt_in: true whatsapp_opt_in: false wechat_opt_in: false line_opt_in: false opt_out: false preferences: [] interests: [] preferred_journey: null segment: null referred_by_client_id: null referred_at: null consent: false notify_of_new_collection: false last_contacted_at: '2024-08-02T12:29:24.068Z' created_at: '2024-08-07T12:29:24.099Z' updated_at: '2024-08-07T12:29:24.099Z' schema: $ref: '#/components/schemas/client' security: - BearerAuth: [] components: schemas: client: type: array items: type: object properties: bspk_id: type: integer description: BSPK internal unique identifier of the client client_id: type: string description: Unique identifier of the client name: type: string nullable: true description: Full name of the client deprecated: true first_name: type: string nullable: true description: First name of the client last_name: type: string nullable: true description: Last name of the client title: type: string nullable: true description: Title of the client address: type: string nullable: true description: Address of the client consolidated deprecated: true addresses: type: array items: type: object properties: address: type: string nullable: true description: Address street of the client address_2: type: string nullable: true description: Address street of the client address_3: type: string nullable: true description: Address street of the client address_4: type: string nullable: true description: Address street of the client city: type: string nullable: true description: City of the client state: type: string nullable: true description: State of the client country_code: type: string nullable: true description: Country code of the client required: - address - address_2 - address_3 - address_4 - city - state - country_code email: type: string nullable: true description: Email of the client mobile_phone: type: string nullable: true description: Mobile phone of the client other_phone: type: string nullable: true description: Other phone of the client birthday: type: string format: date_time nullable: true description: Birthday of the client gender: type: string nullable: true enum: - M - F - NB - null description: Gender of the client nationality: type: string nullable: true description: Nationality of the client passport_number: type: string nullable: true description: Passport Number of the client language: type: string nullable: true description: Language of the client preferred_contact_channel: type: string nullable: true enum: - chat - email - line - whastapp - wechat - call - null description: The preferred channel of the client current_sales_associate_id: type: string nullable: true description: Unique identifier of the associate that the client is assigned to current_sales_associate_name: type: string nullable: true description: Full name of the associate that the client is assigned to current_store_id: type: string nullable: true description: Unique identifier of the store that the client is assigned to current_store_name: type: string nullable: true description: Name of the store that the client is assigned to communication_preferences: type: object properties: chat_opt_in: type: boolean description: >- Whether or not the client has enabled being contacted by Chat or Messages email_opt_in: type: boolean description: Whether or not the client has enabled being contacted by Email phone_opt_in: type: boolean description: >- Whether or not the client has enabled being contacted by Phone Call whatsapp_opt_in: type: boolean description: >- Whether or not the client has enabled being contacted by WhatsApp wechat_opt_in: type: boolean description: >- Whether or not the client has enabled being contacted by WeChat line_opt_in: type: boolean description: Whether or not the client has enabled being contacted by Line opt_out: type: boolean description: Whether or not the client has opted-out of being contacted required: - chat_opt_in - email_opt_in - phone_opt_in - whatsapp_opt_in - wechat_opt_in - line_opt_in - opt_out preferences: type: array items: type: object properties: name: type: string description: Name of the preference value: type: array items: type: string description: Value of the preference required: - name - value segment: type: string nullable: true description: The Segmentention which the client is assigned to preferred_journey: type: string nullable: true description: The Journey which the client is assigned to referred_by_client_id: type: string nullable: true description: Unique identifier of the client that referred this client referred_at: type: string nullable: true description: The date when the client referral was recorded in BSPK consent: type: boolean description: Whether or not the client has given consent notify_of_new_collection: type: boolean description: Whether or not the client wants to be notified of new collections last_contacted_at: type: string format: date_time nullable: true description: The last date the client was contacted by a Sales Associate created_at: type: string format: date_time description: Timestamp of when the client was created updated_at: type: string format: date_time description: Timestamp of when the client was updated required: - bspk_id - client_id - name - title - address - addresses - email - mobile_phone - other_phone - birthday - gender - nationality - passport_number - language - preferred_contact_channel - current_sales_associate_id - current_sales_associate_name - current_store_id - current_store_name - communication_preferences - preferences - segment - preferred_journey - referred_by_client_id - referred_at - consent - notify_of_new_collection - last_contacted_at - created_at - updated_at securitySchemes: BearerAuth: type: http scheme: bearer ````