discovery

List roster candidates (v4)

List the customers a Discovery campaign can add: only those who can join by default, or with listing every customer, those already added, or those not added, each with why it cannot join. Searched by name, narrowed to audiences, and sorted; also answers whether the roster can be changed now (and why not) and the audiences to narrow by.

get/api/v1/discovery/roster-candidates-v4

Request

  • Base URL: https://point11.ai
  • URL: https://point11.ai/api/v1/discovery/roster-candidates-v4
  • 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)

Query parameters

limitinteger

Number of customers to return (1–100)

cursorstring

Opaque cursor returned as nextCursor by the previous page

campaignIdstring required

The Discovery campaign's id, or its campaign key.

searchstring

Words a customer's name contains.

audiencesstring[]

Source and label names: a customer in any named source and in any named label (system audiences are labels) is listed; a kind none names narrows nothing.

sortColumn'customerId' | 'name' | 'profile' | 'performance' | 'employer' | 'location' | 'audiences' | 'sources' | 'status' | 'membershipStatus' | 'conversations' | 'brandShare' | 'brandWinRate' | 'age' | 'householdIncome' | 'headcount' | 'annualRevenue' | 'trigger' | 'intentStage' | 'language' | 'createdAt'

Default createdAt.

sortDirection'asc' | 'desc'

Default desc.

filtersstring[]

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.

filterMatch'all' | 'any'

Whether a customer matches every condition (all, the default) or any one

listing'joinable' | 'all' | 'added' | 'not_added'

joinable (default) lists only customers who can join; all, added and not_added list others too, each with why it cannot.

Headers

Point11-Organizationstring uuid

Organization to act in. Required for OAuth bearers; an API key acts in the organization that owns it.

Response

Success.

nextCursorstring nullable required
totalCountinteger required

Customers the search and audiences keep.

pageIndexinteger required

How many whole pages of this limit sort before the page answered.

facetTotalCountinteger required
querystring required

The search as the roster read it.

editableboolean required

Whether the roster can change now.

editBlockedReasonstring nullable required

Why it cannot, when it cannot.

audienceTypesstring[] 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.

campaignIdstring uuid required
includedinteger required

Customers on the roster now.

Changes

No recorded changes to this operation across all 1 revision of this API.