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:
searchmatches part of the name or the address, up to 200 characters.listIdkeeps one list’s contacts, the same asGET /contacts/lists/{listId}/members.statuskeeps thesubscribedor theunsubscribedcontacts.addedAfterkeeps the contacts added at or after a time.emailskeeps the contacts with exactly these addresses, in any case. Repeat the parameter or separate the addresses with commas, up to 100.sorttakesadded,nameoremail, with:ascor:desc, such asname:asc. A field alone sortsaddednewest first and the others from A to Z.
400 with PUB-001-004 for that parameter.
Add a contact
201 with the contact and its address in the Location header. Two refusals are common:
- An address that a contact already has returns
409withCNT-001-006. To find that contact, callGET /contactswithemails. - An external ID that another contact has returns
409withCNT-001-008.
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.
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.Manage lists
Each list has aname 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:
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 asCNT-001-006 for an address another contact has. Invalid fields return 400 with each field and its code in errors.