Skip to main content
GET
List a list's contacts (with ids and column values)

Authorizations

​
Authorization
string
header
required

Your API token (af_…) as the Basic-auth username, with an empty password.

Path Parameters

​
listId
string
required

24-character hex id of the list (from GET /business/lists).

Query Parameters

​
limit
integer
default:100

Page size: how many rows to return per page (1-1000, default 100).

Required range: 1 <= x <= 1000
​
pageNum
integer
default:1

1-based page number (default 1).

Required range: x >= 1
​
sortBy
string

Field to sort rows by; it is IGNORED unless sortOrder is sent with it. Contact lists: any field on the contact record — the index-backed and therefore fast ones are firstName, lastName, jobTitle, createdAt, address.city and address.country (updatedAt carries NO index on the contact collection, so it is accepted but sorts as a blocking in-memory sort); a company field prefixed with company., where the accepted values are exactly company.name, company.domain, company.industry, company.country, company.type, company.revenue, company.linkedInHeadCount, company.address.city, company.address.state and company.address.country; or customColumns_ for a custom/smart column. Company lists: a company field by its own name (name, domain, industry, revenue, linkedInHeadCount) or customColumns_. An unrecognised key is accepted and falls back to the list's default order rather than erroring.

Required string length: 1 - 100
​
sortOrder
enum<string>

Sort direction: asc (ascending) or desc (descending). Required for sortBy to take effect — without it the rows keep their default order.

Available options:
asc,
desc
​
filters
string

URL-encoded JSON object (max 8000 characters) narrowing which rows are returned, e.g. {"companyName":["pomelo"]} or {"country":["argentina"]}. Text keys (name, title, dept, level, industryName, country, state, personalLocation, companyName, companyIndustry, companyHeadQuartersCountry, companyLocation, website, campaignEngagement, otherLists) take an array of accepted values, e.g. {"companyName":["pomelo"]} or {"country":["argentina"]}, or {"include":[...],"exclude":[...]} — otherLists takes list NAMES, not ids; numberOfEmployees takes headcount ranges the same way but as STRINGS ("51-200", "10001+" or a bare head count "500" — an unquoted JSON number answers 500) and revenue a plain number; keywords (a wildcard match on the job title only) and linkedinUrl take one string; enrichedEmail, enrichedPhone and emailValidity take {"include":[...]} of their statuses; icpMatch takes ["yes"] or ["no"]; customColumns maps a column id to {"dataType":"string","include":[...]}, {"dataType":"boolean","value":true} or {"dataType":"number","rangeMin":1,"rangeMax":10}. Company lists honour companyName, companyIndustry, companyHeadQuartersCountry, website, numberOfEmployees, campaignEngagement and customColumns. Every key is optional; an unknown key or a wrong value shape is rejected rather than ignored. Values inside one key are OR-joined and different keys are AND-ed. VALUES ARE NOT VALIDATED: level, industryName, country, state, website and companyHeadQuartersCountry are matched as whole values and campaignEngagement, icpMatch and enum cells as exact strings, so a value in the wrong vocabulary is accepted and silently matches nothing — each key's own description names its vocabulary and the endpoint that serves it. Malformed JSON, an unknown key or a wrong value shape answers 422 INVALID_ROW_FILTERS.

Maximum string length: 8000

Response

Success

​
entityType
enum<string>
required
Available options:
contactList,
companyList
​
data
object[]
required

Contact rows when entityType is contactList, company rows when it is companyList.

​
pagination
object
required