Lists

Static or rule-based segments of objects — contacts, companies, deals, tickets, activities.

Static lists are explicit membership; active lists re-evaluate against the criteria on every read. objectType is one of CONTACT, COMPANY, DEAL, TICKET, ACTIVITY. Operators in conditions: eq, ne, gt, lt, contains.

POST/api/listsBearer token

Create a list

Create a new list. Pass criteria with at least one condition (an empty active list matches everything — usually not what you want).

Required scopes:contacts.write

Request body

Name	Type	Description
`name`required	`string`	List name.
`objectType`required	`string`	Object type the list holds.
`kind`	`string`	STATIC \| ACTIVE. Defaults to STATIC.
`criteria`required	`object`	{ conditions: [{ field, op, value }] }.

Request body

JSON

{ "name": "New patients", "objectType": "CONTACT", "kind": "ACTIVE", "criteria": { "conditions": [{ "field": "lifecycle", "op": "eq", "value": "PATIENT" }] } }

Responses

201 CreatedCreated.

example

{
  "id": "lst_9k2j3p…",
  "name": "New patients — last 30 days",
  "objectType": "CONTACT",
  "kind": "ACTIVE",
  "criteria": {
    "conditions": [
      { "field": "lifecycle", "op": "eq", "value": "PATIENT" }
    ]
  },
  "memberCount": 42,
  "createdAt": "2026-05-18T14:00:00Z"
}

Code samples

Shell

curl -X POST https://app.contactfollowup.com/api/lists \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New patients", "objectType": "CONTACT", "kind": "ACTIVE", "criteria": { "conditions": [{ "field": "lifecycle", "op": "eq", "value": "PATIENT" }] } }'

GET/api/listsBearer token

List lists

Every list in the workspace.

Required scopes:contacts.read

Responses

200 OKLists.

example

{ "lists": [{
  "id": "lst_9k2j3p…",
  "name": "New patients — last 30 days",
  "objectType": "CONTACT",
  "kind": "ACTIVE",
  "criteria": {
    "conditions": [
      { "field": "lifecycle", "op": "eq", "value": "PATIENT" }
    ]
  },
  "memberCount": 42,
  "createdAt": "2026-05-18T14:00:00Z"
}] }

Code samples

Shell

curl -X GET https://app.contactfollowup.com/api/lists \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json"