List contacts

Contacts API · contacts.list

URL · Fields · Example · Response · Try it

URL and authentication

POST https://YOUR-BACKEND/api/automation/v1/execute

Send Authorization: Bearer <connection key>, Accept: application/json and Content-Type: application/json. Create a connection.

This operation requires read access and CRM permission view_contacts. The gateway invokes GET /api/v1/app/lead-contacts internally. Use the POST URL above with your automation key, including for read and delete operations.

Request parameters

Key	Type	Requirement
`operation`	string	Required; exactly `contacts.list`
`data`	object	Optional; see fields below

Fields

Fields below belong inside data. Dot paths describe nested objects; * means each array item. nullable permits null and sometimes validates a supplied field. in: lists allowed values; min: and max: limit the value, length or item count. exists: and exists_in_company: require a valid record ID. Conditional rules such as required_if and required_with refer to other fields in the same payload. Use YYYY-MM-DD for date-only values and timestamps with timezone offsets for follow-ups.

Field	Type	Requirement	Format / validation
`searchText`	string	Optional	— Search term for filtering contacts by first name, last name, email, primary phone, or secondary phone. Example: john@example.com
`created_by`	integer	Optional	— Filter by user ID who added the contact. Example: 1
`source_id`	integer	Optional	— Filter by lead source ID. Example: 1
`priority`	string	Optional	— Filter by contact priority (high, medium, low). Example: high
`start_date`	string	Optional	— Filter contacts created from this date (Y-m-d format). Example: 2025-01-01
`end_date`	string	Optional	— Filter contacts created until this date (Y-m-d format). Example: 2025-12-31
`contact_created_date_preset`	string	Optional	— Optional rolling preset for created-at range (today\|yesterday\|tomorrow\|last_month). Expands to start_date/end_date in company TZ. Used by smart filters.
`follow_up_date_preset`	string	Optional	— Optional rolling preset for follow-up date range (today\|yesterday\|tomorrow\|last_month). Expands to follow_up_start_date/follow_up_end_date.
`assigned_to`	integer\|string\|array	Optional	— Filter by assigned user ID(s). Use single ID, array of IDs, or “null” for unassigned. Example: [1,2,3] or 1
`preferred_languages`	array	Optional	— Filter by preferred languages. Example: [“en”,“ar”]
`communication_preferences`	array	Optional	— Filter by communication preferences (email, phone, whatsapp, sms). Example: [“email”,“whatsapp”]
`interactions`	string	Optional	— Filter by interaction status (untouched, pending, overdue, stale). Example: untouched
`relationship_tier`	string	Optional	— Filter by contact relationship segment (all, owners, buyers, tenants, owner_and_counterparty, standard). Legacy aliases supported: owner, client, clients, client_owner. Example: owners
`sort_type`	string	Optional	— Field to sort by (default: created_at). Options: created_at, updated_at, first_name, last_name, email, primary_phone, secondary_phone, priority, assigned_to, added_by. Example: first_name
`sort`	string	Optional	— Direction of sort (ASC, DESC) — default: DESC. Example: DESC
`per_page`	integer	Optional	integer; min:1; max:100 — Gateway default 25; clamped to 1–100.
`page`	integer	Optional	integer; min:1 — Default 1.

Example request

Replace the example IDs and values with records in your installation. Supply any additional custom fields required by your company.

{
  "operation": "contacts.list",
  "data": {
    "page": 1,
    "per_page": 25
  }
}

Response

Returns matching records in data. Paginated results include meta.current_page, meta.last_page, meta.per_page, meta.total and meta.has_more_pages. Increment the request’s data.page while more pages remain. Related fields depend on record visibility and the resource.

The gateway preserves the underlying HTTP status and JSON body. Successful requests return HTTP 200. A response may also include localized message fields.

Illustrative response excerpt (additional fields may be returned):

{
  "status": "success",
  "data": [],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 0,
    "has_more_pages": false
  }
}

Errors

HTTP status	Meaning
400	A CRM business rule rejected the action.
401	Missing, invalid, expired or revoked connection key.
403	Connection access or CRM permissions do not allow this action.
404	Operation or record unavailable.
413	Request or result exceeds its size limit; reduce payload or page size.
422	Missing or invalid fields, or a CRM business rule rejected the operation.
429	Rate limit exceeded; wait before retrying.
500	The server could not complete the operation.

Validation failures may return message / errors, or an error string with an optional fields array. The tester shows the actual HTTP status and full body. Read about limits and retries.

Try it

Brixit API v1

Try this request

contacts.list

Requests run from your browser to your installation. Enter the backend URL shown in Brixit. Your connection key stays in this component’s memory and is cleared when you leave this page.

Request format

curl --request POST 'https://crm.example.com/api/automation/v1/execute' \
  --header "Authorization: Bearer $BRIXIT_CONNECTION_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "operation": "contacts.list",
  "data": {
    "page": 1,
    "per_page": 25
  }
}'

Code uses a connection-key variable; your entered key is never included in copied examples.