Get Contacts

get

https://api.campaignrefinery.com/rest/contacts/get_contacts

Returns a paginated list of contacts in the authenticated account. Each row is identified by contact_uuid. Optional with_attributes=true adds a nested custom_attributes map per contact (default omits, opt-in). Pagination uses the standard paginated response envelope inside data ({current_page, data: [...], total, per_page, last_page, ...}).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

string

length ≤ 255

Substring search on contact name or email.

page

integer

≥ 1

Defaults to 1

Page number (1-indexed). Default 1.

per_page

integer

1 to 100

Defaults to 25

Page size. Default 25, capped at 100.

sort_field

string

enum

Field to sort by. Whitelist enforced.

Allowed:

sort_order

string

enum

Defaults to desc

Sort direction. Default desc (newest first).

Allowed:

contact_add_start

string

ISO 8601 UTC datetime. Filter to contacts created after this time.

contact_add_end

string

ISO 8601 UTC datetime. Filter to contacts created before this time.

contact_upd_start

string

ISO 8601 UTC datetime. Filter to contacts updated after this time.

contact_upd_end

string

ISO 8601 UTC datetime. Filter to contacts updated before this time.

with_attributes

boolean

Defaults to false

When true, each contact in the response includes a nested custom_attributes: {key: value} map. Default false (omitted).

offer_uuids

array of uuids

Offer UUIDs from get_offers to filter by engagement. Comma-separated or repeated. Unknown or another account's offer UUID fails validation. Omit to skip offer filtering entirely.

offer_uuids

offer_flag

string

enum

Defaults to both

Engagement type to match against the offers in offer_uuids. Default both.

Allowed:

offer_mode

string

enum

Defaults to has

has matches contacts who engaged as specified by offer_flag; hasnt matches contacts who did not. Default has.

Allowed:

offer_within

string

ISO 8601 duration (e.g. P30D, PT12H, P3M) bounding the engagement window to the last X; omitted means unbounded.

points_balance

string

^(eq|lt|gt)~-?\d+$

Points balance condition: lt~<int>, gt~<int> (strict), or eq~<int>.

Responses

401

Missing or invalid bearer token.

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Contacts retrieved.

422Validation error (e.g. per_page greater than 100, sort_field not in the whitelist).