> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Usertick runs surveys on websites, by link, by QR code and by email, and collects every response in one inbox with reports, dashboards and workflows. The REST API lives at https://app.usertick.com/api/public/v1 and uses Bearer API keys or OAuth access tokens; the JavaScript SDK is the @usertick/snippet package on npm.

# Contacts and lists

> List, add, change and delete Usertick contacts through the REST API, manage contact lists and who is on them, and erase a contact with their responses.

The contacts endpoints work with the people in **Contacts** and their lists. Contacts exist on every plan, so API keys (Pro and above), apps and AI assistants can all use them.

| Endpoint | Scopes | Does |
| - | - | - |
| [`GET /contacts`](https://docs.usertick.com/developers/api/reference/list-contacts) | `contacts:read` | Lists contacts, searched and filtered |
| [`GET /contacts/{contactId}`](https://docs.usertick.com/developers/api/reference/get-contact) | `contacts:read` | Returns one contact |
| [`POST /contacts`](https://docs.usertick.com/developers/api/reference/create-contact) | `contacts:write`, `contacts:read` | Adds a contact |
| [`PATCH /contacts/{contactId}`](https://docs.usertick.com/developers/api/reference/update-contact) | `contacts:write`, `contacts:read` | Changes a contact or unsubscribes it |
| [`DELETE /contacts/{contactId}`](https://docs.usertick.com/developers/api/reference/delete-contact) | `contacts:write` | Deletes a contact |
| [`POST /contacts/{contactId}/erase`](https://docs.usertick.com/developers/api/reference/erase-contact) | `responses:delete`, `contacts:write` | Erases a contact and every response of the person |
| [`GET /contacts/lists`](https://docs.usertick.com/developers/api/reference/list-contact-lists) | `contacts:read` | Lists contact lists |
| [`GET /contacts/lists/{listId}`](https://docs.usertick.com/developers/api/reference/get-contact-list) | `contacts:read` | Returns one list |
| [`POST /contacts/lists`](https://docs.usertick.com/developers/api/reference/create-contact-list) | `contacts:write`, `contacts:read` | Creates a list |
| [`PATCH /contacts/lists/{listId}`](https://docs.usertick.com/developers/api/reference/update-contact-list) | `contacts:write`, `contacts:read` | Renames a list or changes its description or icon |
| [`DELETE /contacts/lists/{listId}`](https://docs.usertick.com/developers/api/reference/delete-contact-list) | `contacts:write` | Deletes a list; its contacts stay |
| [`GET /contacts/lists/{listId}/members`](https://docs.usertick.com/developers/api/reference/list-contact-list-members) | `contacts:read` | Lists the contacts on a list |
| [`POST /contacts/lists/{listId}/members`](https://docs.usertick.com/developers/api/reference/add-contact-list-members) | `contacts:write`, `contacts:read` | Puts contacts on a list |
| [`POST /contacts/lists/{listId}/members/remove`](https://docs.usertick.com/developers/api/reference/remove-contact-list-members) | `contacts:write`, `contacts:read` | Takes contacts off a list |

An app or an AI assistant acts as the person who connected it, so, as in Usertick, reading requires the **View surveys and results** permission and changes require **Manage contacts**. An API key acts for the organization. Every change appears in the activity log as made through the credential.

## The contact

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "77777777-7777-4777-8777-777777777777",
  "email": "maya@example.com",
  "name": "Maya Patel",
  "attributes": { "plan": "Pro", "company": "Example" },
  "externalId": "user_8271",
  "source": null,
  "unsubscribedAt": null,
  "listIds": ["88888888-8888-4888-8888-888888888888"],
  "createdAt": "2026-10-01T09:00:00.000Z",
  "updatedAt": null
}
```

| Field | Meaning |
| - | - |
| `email` | The address, stored lowercased. It never changes. |
| `name` | The person's name, or `null`. |
| `attributes` | Text details that emails can insert, such as company or plan: each a name of up to 64 characters and a text value of up to 500. `{}` when there are none. |
| `externalId` | Your own user ID for the person, the one your site sends to [`identify()`](https://docs.usertick.com/installation/identify). It is unique in the organization. |
| `source` | `identify` or `hubspot` when a verified identity or a HubSpot workflow made the contact, otherwise `null`. |
| `unsubscribedAt` | When the contact unsubscribed or was unsubscribed, otherwise `null`. |
| `listIds` | The lists the contact is on. |

## Find contacts

`GET /contacts` lists contacts newest first and takes these filters:

* `search` matches part of the name or the address, up to 200 characters.
* `listId` keeps one list's contacts, the same as `GET /contacts/lists/{listId}/members`.
* `status` keeps the `subscribed` or the `unsubscribed` contacts.
* `addedAfter` keeps the contacts added at or after a time.
* `emails` keeps the contacts with exactly these addresses, in any case. Repeat the parameter or separate the addresses with commas, up to 100.
* `sort` takes `added`, `name` or `email`, with `:asc` or `:desc`, such as `name:asc`. A field alone sorts `added` newest first and the others from A to Z.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://app.usertick.com/api/public/v1/contacts?emails=maya@example.com&emails=ben@example.com" \
  -H "Authorization: Bearer utk_live_your_key_here"
```

Like every list, the contact list pages with a cursor. See [Pagination](https://docs.usertick.com/developers/api/pagination.md). A sort or a filter value the list doesn't take returns `400` with `PUB-001-004` for that parameter.

## Add a contact

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://app.usertick.com/api/public/v1/contacts" \
  -H "Authorization: Bearer utk_live_your_key_here" \
  -H "Idempotency-Key: contact-maya-2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{ "email": "maya@example.com", "name": "Maya Patel", "attributes": { "plan": "Pro" }, "listIds": ["88888888-8888-4888-8888-888888888888"] }'
```

You can put a new contact on up to 100 lists at once, and Usertick skips an ID that isn't one of your lists. The request returns `201` with the contact and its address in the `Location` header. Two refusals are common:

* An address that a contact already has returns `409` with `CNT-001-006`. To find that contact, call `GET /contacts` with `emails`.
* An external ID that another contact has returns `409` with `CNT-001-008`.

An address that unsubscribed from your organization's email, or marked one as spam, starts unsubscribed, even if the earlier contact was deleted, so a person who objected isn't emailed again.

## Change a contact

`PATCH /contacts/{contactId}` changes only the fields it sends:

* `name`, where `""` clears the name;
* `attributes`, which replaces every stored detail with the ones sent;
* `externalId`, where `""` clears it;
* `unsubscribed: true`, which unsubscribes the contact.

Usertick doesn't subscribe a contact again, so `unsubscribed: false` returns `400` with `CNT-002-004`. The address can't change either, so to use another address, add a new contact. A body without any of these fields returns `400` with `PUB-001-006`.

## Delete or erase a contact

You can remove a contact in two ways, which differ in what happens to the person's responses.

| | `DELETE /contacts/{contactId}` | `POST /contacts/{contactId}/erase` |
| - | - | - |
| The contact and its list memberships | Deleted | Deleted |
| The address in your email send history | Blanked, the counts stay | Blanked, the counts stay |
| The person's responses | Stay, without their link to the contact | Erased, with their files |
| The address in your unsubscribes | Stays | Stays |
| Runs | At once, `204` | In the background, `202` with a job |

> [!WARNING]
>
> A delete removes the contact's links to its responses, so a later erasure by email or user ID can no longer find the responses that only those links pointed to. To remove a person and their data, erase the contact instead of deleting it. See [Erase personal data](https://docs.usertick.com/developers/api/erasure.md#erase-a-contact).

## Manage lists

Each list has a `name` of 1 to 120 characters that no other list of yours has, a `description` of up to 500 characters and an `icon`, which is a key from the dashboard's icon set such as `rocket`. Its `memberCount` says how many contacts are on it.

`PATCH /contacts/lists/{listId}` changes only the fields it sends, and `"description": null` clears the description. A name another list has returns `409` with `CNT-004-006`.

When email sends scheduled for a list haven't gone out, Usertick refuses to delete the list, because those sends would reach nobody:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "statusCode": 409,
  "success": false,
  "code": "PUB-012-003",
  "message": "The list wasn't deleted because email sends scheduled for it haven't gone out. To delete it and stop those sends, send the request again with force=true.",
  "data": { "scheduledSends": 2 }
}
```

To delete the list anyway, send `DELETE /contacts/lists/{listId}?force=true`. The scheduled sends then stop when their time comes.

## Manage who is on a list

`POST /contacts/lists/{listId}/members` puts 1 to 500 contacts on a list:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://app.usertick.com/api/public/v1/contacts/lists/88888888-8888-4888-8888-888888888888/members" \
  -H "Authorization: Bearer utk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["77777777-7777-4777-8777-777777777777"] }'
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "added": 1, "skipped": 0 }
```

`skipped` counts the IDs that were already on the list or aren't your contacts. `POST /contacts/lists/{listId}/members/remove` takes 1 to 500 contacts off a list and returns `{ "removed": 1 }`, while the contacts themselves stay.

## Errors

[Errors](https://docs.usertick.com/developers/api/errors.md#contacts) lists the contact and list codes, such as `CNT-001-006` for an address another contact has. Invalid fields return `400` with each field and its code in `errors`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.