List contacts
Changed onReturns a workspace's contacts, filtered, searched, sorted and counted on the server. Requires the Contacts entitlement (403 without it). Session cookie, x-api-key, or a Bearer token.
Attribute filters use filter[attribute.<key>][<operator>]=<value>, where <key> is a ContactAttributeKeyResource.key of the workspace (an unknown key → 400). The operators depend on the key's dataType; an operator the type does not support → 400:
| dataType | operators |
|---|---|
| string | in, eq, ne, contains, notContains, startsWith, endsWith, isSet, isNotSet |
| number | in, eq, ne, gt, gte, lt, lte, isSet, isNotSet |
| date | gte, lte (ISO 8601 date-time with offset, inclusive), isSet, isNotSet |
Text comparisons are case-insensitive. in matches any of its values: repeat the key once per value (filter[attribute.plan][in]=Pro&filter[attribute.plan][in]=Team). String values are taken verbatim — never split on commas, since a value can contain one; a number in also accepts comma-separated values. ne, contains, notContains, startsWith and endsWith may also be repeated, and then every value must hold (AND). Every other operator takes exactly one value (repeating it → 400). isSet / isNotSet ignore their value (send true). A value is set when the attribute row exists and carries a value (non-empty text, or a non-null number/date). ne and notContains match only contacts whose value is set and differs — use isNotSet for contacts without one. All filters combine with AND. At most 50 distinct filter parameters per request and at most 100 values per in.
The cursor is bound to sortBy and to the search and filter set; changing any of them while paging → 400 naming cursor. Unknown query parameters → 400.
Request
- Base URLhttps://app.formbricks.com
- URLhttps://app.formbricks.com/api/v3/contacts
- Auth
- API key in cookie next-auth.session-token
- or API key in header x-api-key
- or HTTP bearer
Query parameters
Workspace identifier.
Page size (max 250).
Opaque cursor returned as meta.nextCursor from the previous page.
Whether to calculate meta.totalCount. Send true on the first page to get the count; when omitted or false the count query is skipped and meta.totalCount is null.
Case-insensitive substring match over any attribute value of the contact, or its id.
-createdAt (newest first, default) or createdAt (oldest first).
Only contacts created at or after this instant (ISO 8601 with offset).
Only contacts created at or before this instant (ISO 8601 with offset).
Response
Contacts retrieved successfully
Changes
- info
endpoint added
- info