Skip to content
Qrona Newsletter
Sign inCreate an account

Reference / Contacts

List contacts

GET/api/v1/contacts

The contacts the key is allowed to see, in ID order, one page at a time.

The response contains the workspace's own contacts and those shared with it from a level above (shared: true), limited by the contact rules of the person behind the key.

Fetch the next page with cursor=next_cursor until has_more is false. For ongoing sync: save the time before you start and then fetch with updated_since.

Scope

  • contacts:read Read contacts – the person behind the key must be all members.

Query parameters

limitinteger
The maximum number of items in the response (1–500, default 100).at least 1 · at most 500 · default 100
cursorstring
next_cursor from the previous response, for the next page. Omit for the first page.
statusstring
Only contacts with this status. If omitted: all except deleted.activeunsubscribedbouncedcomplaineddeleted
list_idstring
Only contacts who are on the list (regardless of the membership's status).
segment_idstring
Only contacts in the distribution list.
tagstring
Only contacts with this tag (exact spelling).
updated_sincestring
Only contacts changed since then (ISO 8601). Useful for sync: save the time of the previous fetch.
originstring
own: only the workspace's own · shared: only those shared from a level above.ownshared

Response

200 A page of contacts.

dataarray<object>required
data[].idstringrequired
The contact's ID.
data[].emailstringrequired
The email address (lower case). Never changes: consents and suppressions apply to the address.
data[].first_namestring | nullrequired
data[].last_namestring | nullrequired
data[].companystring | nullrequired
data[].phonestring | nullrequired
In international format (E.164), e.g. +46701234567.
data[].statusstringrequired
active: can receive mailings · unsubscribed: has unsubscribed from everything · bounced: the address bounces · complained: has reported spam · deleted: erased (GDPR), the personal data is gone.activeunsubscribedbouncedcomplaineddeleted
data[].fieldsobject<string | number | boolean>required
Custom fields by key (see GET /fields). Sensitive fields, such as personal identity numbers, are never sent out.
data[].tagsarray<string>required
data[].sourcestringrequired
How the contact was added: manual, import, form, api …
data[].consentobjectrequired
data[].consent.atstring (time, ISO 8601) | nullrequired
When consent was given.
data[].consent.sourcestring | nullrequired
How the person consented, in your own words.
data[].suppressionobject | nullrequired
The workspace's suppression of the address. A suppressed address never receives mailings, regardless of status.
data[].suppression.reasonstringrequired
unsubscribed, bounced, complained, manual or imported.
data[].suppression.created_atstring (time, ISO 8601)required
When the address was suppressed.
data[].sharedbooleanrequired
Shared from a level above in the organisation: can be read and receive mailings from here, but can only be changed where it belongs.
data[].created_atstring (time, ISO 8601)required
When the contact was created.
data[].updated_atstring (time, ISO 8601)required
When the contact was last changed.
data[].unsubscribed_atstring (time, ISO 8601) | nullrequired
When the person unsubscribed.
has_morebooleanrequired
There are more: fetch the next page with cursor=next_cursor.
next_cursorstring | nullrequired
Send as cursor for the next page. null on the last page.

Errors

401
unauthenticatedinvalid_keykey_revokedkey_expiredkey_inactive
402
payment_required
403
insufficient_scopeforbiddenworkspace_suspended
422
validation_failed
429
rate_limited
500
internal_error