V3 Contacts

Returns 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:

dataTypeoperators
stringin, eq, ne, contains, notContains, startsWith, endsWith, isSet, isNotSet
numberin, eq, ne, gt, gte, lt, lte, isSet, isNotSet
dategte, 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.

get/api/v3/contacts

Request

  • Base URL
    https://app.formbricks.com
  • URL
    https://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

workspaceIdstring cuid2 required

Workspace identifier.

limitinteger

Page size (max 250).

cursorstring

Opaque cursor returned as meta.nextCursor from the previous page.

includeTotalCountboolean

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.

searchstring

Case-insensitive substring match over any attribute value of the contact, or its id.

sortBy'-createdAt' | 'createdAt'

-createdAt (newest first, default) or createdAt (oldest first).

filter[createdAt][gte]string date-time

Only contacts created at or after this instant (ISO 8601 with offset).

filter[createdAt][lte]string date-time

Only contacts created at or before this instant (ISO 8601 with offset).

Response

Contacts retrieved successfully

Changes