---
title: "List customers (v3)"
method: GET
path: "/api/v1/business/customers-v3"
tags: ["business"]
---

# List customers (v3)

`GET /api/v1/business/customers-v3`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/business/customers-v3`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

List the organization's customers (active ones by default), optionally for one business profile or one of its stores (locationKey), newest first unless sorted: each one's name, its table attributes under the customer model's keys (a category, a band as <key>.band, the Product and the Buyer type each as its id and label; Location as one line), audiences, sources, and latest Discovery outcome, with the pool's status counts and audience facets. Filter by lifecycle status, name search, audience names and field conditions; page with nextCursor.

## Query parameters

- `limit` integer
- `cursor` string
- `businessProfileId` string, uuid: Only this business profile's customers; omit for every profile
- `locationKey` string: Only the customers generated for this store: a store profile's location key, as business_store_profile_summaries_get_v1 lists them under its businessProfileId
- `lifecycleStatus` 'active' | 'archived' | 'all'
- `search` string: Match the customer's name
- `audienceNames` string[]: Source and label names: only customers in any named source and in any named label (system audiences are labels); a kind none names narrows nothing
- `customerIds` string[]: Only these customers, under every other filter
- `includeEditable` boolean: Also answer the page's customers as business_customers_update_v4 edits them (edits): each one's version, editable fields and their options
- `sort` 'createdAt' | 'customerId' | 'name' | 'profile' | 'performance' | 'audiences' | 'sources' | 'status' | 'gender' | 'age' | 'language' | 'location' | 'householdIncome' | 'employer' | 'companySize' | 'annualRevenue' | 'intentStage' | 'trigger'
- `direction` 'asc' | 'desc'
- `filters` string[]: Field conditions, each `<field>:<operator>:<value>`. Text fields (location, employer, trigger) take contains, does_not_contain, is or starts_with and the words. Number fields (age, householdIncome, companySize, annualRevenue) take gt, gte, lt, lte or eq and a number, or between and `min..max`. Classification fields, each band under its fact's key as <key>.band (gender, age.band, language, market, areaType, education, lifeStage, householdIncome.band, occupation, seniority, companySize.band, buyerType, audience, product, channel, buyerRole, intentStage, job, triggerType), take is_any_of or is_none_of and comma-separated ids from business_customer_filter_options_get_v2 (buyerType takes consumer or organization), `none` for a customer with no value. createdAt takes on_or_after or on_or_before and an ISO date, or between and `from..to`, read in UTC. performance (the latest Discovery outcome) takes is_any_of or is_none_of and won, lost or `none`.
- `filterMatch` 'all' | 'any': Whether a customer matches every condition (all, the default) or any one

## Headers

- `Point11-Organization` string, uuid

## Response `200`

Success.

- BusinessCustomersListV3Response
  - `data` object[], required
    - `id` string, uuid, required
    - `customerKey` string, nullable, required
    - `label` string, required
    - `businessProfileId` string, uuid, required
    - `businessProfileKey` string, nullable, required
    - `profileName` string, nullable, required
    - `profileUrl` string, required
    - `profileBusinessSummary` string, nullable, required
    - `source` 'generated' | 'manual' | 'connected', required
    - `poolStatus` 'active' | 'retired', required
    - `retiredAt` string, date-time, nullable, required
    - `forecastSeeded` boolean, required
    - `audiences` string[], required
    - `systemAudiences` string[], required
    - `userAudiences` string[], required
    - `userAudienceIds` string[], required
    - `sources` string[], required
    - `jobTitle` string, nullable, required
    - `gender` object, nullable, required: Gender
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `age` number, nullable, required: Age
    - `age.band` object, nullable, required: Age band
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `language` object, nullable, required: Language
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `location` string, nullable, required: Location
    - `market` object, nullable, required: Market
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `areaType` object, nullable, required: Area type
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `education` object, nullable, required: Education
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `lifeStage` object, nullable, required: Life stage
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `householdIncome` number, nullable, required: Household income
    - `householdIncome.band` object, nullable, required: Income band
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `occupation` object, nullable, required: Occupation
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `seniority` object, nullable, required: Seniority
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `employer` string, nullable, required: Employer
    - `companySize` number, nullable, required: Company size
    - `companySize.band` object, nullable, required: Size band
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `annualRevenue` number, nullable, required: Annual revenue
    - `buyerType` object, nullable, required: Buyer type
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `audience` object, nullable, required: Audience
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `product` object, nullable, required: Product
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `channel` object, nullable, required: Channel
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `buyerRole` object, nullable, required: Buyer role
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `intentStage` object, nullable, required: Intent stage
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `job` object, nullable, required: Job to be done
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `triggerType` object, nullable, required: Trigger type
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `trigger` string, nullable, required: Trigger
    - `createdAt` string, date-time, required
    - `generationRunId` string, uuid, nullable, required
    - `latestDiscoveryOutcome` DiscoveryItemLatestDiscoveryOutcome, nullable, required
      - `result` 'won' | 'lost', required
      - `brand` string, required
      - `color` string, nullable
      - `source` object, nullable
        - `url` string, nullable, required
        - `label` string, required
        - `faviconUrl` string, nullable, required
        - `faviconTone` 'dark' | 'light' | 'mixed' | 'unknown', nullable
        - `faviconTransparent` boolean, nullable
        - `faviconNeedsLightBackplate` boolean, nullable
        - `faviconNeedsDarkBackplate` boolean, nullable
        - `color` string, nullable
  - `nextCursor` string, nullable, required
  - `totalCount` integer, required
  - `statusCounts` object, required
    - `active` integer, required
    - `archived` integer, required
    - `all` integer, required
  - `audienceFacets` object[], required
    - `id` string, uuid, required
    - `name` string, required
    - `label` string, required
    - `count` integer, required
    - `kind` 'source' | 'system-audience' | 'user-audience', required
  - `audienceFacetTotal` integer, required
  - `generation` object, nullable, required
    - `state` 'generating' | 'failed' | 'cancelled', required
    - `targetCount` integer, required
  - `interviewEligibleCustomerIds` string[], required
  - `audienceTypes` string[], required: The audience types of the customers this list draws from, each read as a Buyer type (b2c is B2C; b2b, prosumer and mixed are B2B); a column only another Buyer type carries is not a column.
  - `edits` BusinessEdits: Answered with includeEditable: the page's customers as an edit takes them
    - `customers` object[], required
      - `id` string, uuid, required
      - `version` integer, required: The current version, which an edit names as expectedVersion
      - `buyerType` 'consumer' | 'organization', nullable, required
      - `editable` BusinessEditable, required: The fields as business_customers_update_v4 edits them: a category as its id, a banded attribute as its value and band id, the household as its counts, the place as its codes and names
        - `name` string, nullable, required
        - `gender` string, nullable, required
        - `age` object, required
          - `value` string, nullable, required
          - `band` string, nullable, required
        - `language` string, nullable, required
        - `location` object, required
          - `countryCode` string, nullable, required
          - `subdivisionCode` string, nullable, required
          - `locality` string, nullable, required
          - `postalCode` string, nullable, required
          - `country` string, nullable, required
          - `subdivision` string, nullable, required
        - `market` string, nullable, required
        - `areaType` string, nullable, required
        - `education` string, nullable, required
        - `lifeStage` string, nullable
        - `household` object, nullable
          - `adults` integer, nullable, required
          - `children` integer, nullable, required
          - `pets` integer, nullable, required
        - `householdIncome` object
          - `value` string, nullable, required
          - `band` string, nullable, required
        - `jobTitle` string, nullable, required
        - `occupation` string, nullable
        - `seniority` string, nullable
        - `employer` string, nullable, required
        - `yearsInRole` string, nullable, required
        - `companySize` object
          - `value` string, nullable, required
          - `band` string, nullable, required
        - `annualRevenue` string, nullable
        - `audience` string, nullable, required
        - `product` string, nullable, required
        - `channel` string, nullable, required
        - `buyerRole` string, nullable, required
        - `stakeholders` string, nullable, required
        - `intentStage` string, nullable, required
        - `budget` string, nullable, required
        - `constraints` string, nullable, required
        - `job` string, nullable, required
        - `situation` string, nullable, required
        - `triggerType` string, nullable, required
        - `trigger` string, nullable, required
        - `functionalNeed` string, nullable, required
        - `emotionalNeed` string, nullable, required
        - `socialNeed` string, nullable, required
        - `desiredOutcome` string, nullable, required
      - `options` string, required: The key of this customer's options in bucketOptions
    - `bucketOptions` object, required: Each category's options and each banded attribute's bands, once per profile that names the page's customers' buckets, by the key its customers name; an attribute a customer's buyer type lacks is absent from its editable fields

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/36a84c7aca11?raw)