Lists

Lists

Lists API offers a new way to save contacts.

Through the entries associated with a list, you can generate the behavior of a series of contacts which can be accessed by users who have different permissions or ownership over the entries.

Schema

Schema for a match list

KeyDescriptionTypeDefaultRequiredSupport Level
descriptionA friendly list descriptionstring(1..128)false
nameA friendly match list namestring(1..128)true
orgFull legal name of the organizationstring()false
owner_idUserId owner of the liststring()false

Fetch

GET /v2/accounts/{ACCOUNT_ID}/lists

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists

Fetch lists by User Id

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists

Add new list (beware: no entries)

PUT /v2/accounts/{ACCOUNT_ID}/lists

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"name": "list name"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists

Add new list which has an owner (beware: no entries)

PUT /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"name": "list name"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists

Delete list and its entries

This method can only be executed by an admin or by the owner of the lists, remember that the entries associated with the list will also be deleted

DELETE /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}

DELETE /v2/accounts/{ACCOUNT_ID}/lists/users/{USER_ID}/{LIST_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{LIST_ID}

Get list properties (doesn’t return entries)

If you want to get a list with an owner id the list needs to belong to the USER_ID or be triggered by an admin user

GET /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}

GET /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{LIST_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{LIST_ID}

Updating list (without entries)

If you want to update a list with an owner id the list needs to belong to the USER_ID or be triggered by an admin user

PATCH /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"description": "desc"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}

PATCH /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{LIST_ID}

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"description": "desc"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{LIST_ID}

Rewrite list

If you want to rewrite a list with an owner id the list needs to belong to the USER_ID or be triggered by an admin user

POST /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"name": "New List name"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}

POST /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{LIST_ID}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"name": "New List name"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{LIST_ID}

List Entries

Schema for list entries

KeyDescriptionTypeDefaultRequiredSupport Level
contacts.contactThe phone number or email associated with the contactstring(1..128)true
contacts.contact_typeThe type of contact this is”`string(‘phone_number’‘email’‘sms’)`
conacts.defaultIf this is the default for this contact typebooleanfalse
conacts.descriptionThe description of the contactstring(1..128)false
descriptionA description of the list entitystring()false
history.contact.contactThe contact that was usedobject()false
history.notesNotes from the communicationstring()false
list_idThe document id of the list document this list entry belongs tostring()false
nameThe name of the list entitystring()false
organizationThe organization this entity belongs tostring()false

If you want to access an entry and the list has an owner id, the user must be an admin or owner of that list

Delete all entries from list

DELETE /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries

Get list entries

GET /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries

Add an entry to a list

PUT /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"number": "0123", "displayname" : "List Entry"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries

Delete entry from the list

DELETE /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}

List entry properties

GET /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}

Update list entry

PATCH /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"firstname" : "First name"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}

Replace list entry

POST /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"number": "0123", "displayname" : "New List Entry"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}

Add photo to List entry

POST /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}/photo

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}/photo

List entry vcard

GET /v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}/vcard

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{LIST_ID}/entries/{LIST_ENTRY_ID}/vcard