Skip to main content
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. 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

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.
Like every list, the contact list pages with a cursor. See Pagination. A sort or a filter value the list doesn’t take returns 400 with PUB-001-004 for that parameter.

Add a contact

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.
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.

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:
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:
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 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.
Last modified on November 15, 2026