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

As an example, in the callflows when looking up a contact to set the caller id, if a contact matches then the caller id returned is of type: voice and primary: true unless there are no primary voice entries in which case its just the first voice entry.

Examples

Sample contact list document

{
    "data": {
        "first_name": "User",
        "contacts": [
            {
                "type": "voice",
                "contact": "4156546297",
                "primary": false,
                "device_type": "mobile"
            },
            {
                "type": "voice",
                "contact": "4158867903",
                "primary": true,
                "device_type": "work"
            },
            {
                "type": "email",
                "contact": "bitbashing@gmail.com",
                "primary": false,
                "email_type": "home"
            },
            {
                "type": "email",
                "contact": "user@2600hz.com",
                "primary": false,
                "email_type": "work"
            },
            {
                "type": "email",
                "contact": "user@ooma.com",
                "primary": true,
                "email_type": "work"
            }
        ]
    }
}

Sample Response for the given document

{
    "data": [
        {
            "id": "ffd5db89a6d91d95c482d9f2408c3727",
            "first_name": "User",
            "contacts": [
                {
                    "voice": "4158867903"
                },
                {
                    "email": "user@ooma.com"
                }
            ],
            "favorite": false
        }
    ]
}

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

Schema for a list of contacts

KeyDescriptionTypeDefaultRequiredSupport Level
capture_group.keyThe number which is used to select this contact, length should be same as capture_group_lengthstring()false
capture_group.lengthLength of the numbers in the contacts for which it used to select desire Caller IDinteger()false
capture_groupThe capture group informationobject(){}false
contactsA list of contact informationarray([#/definitions/contacts](#contacts))true
favoriteWhether the contact is a favoriteboolean()falsefalse
first_nameThe first name of the contactstring()true
historyThe history of contact usagearray([#/definitions/history](#history))[]false
last_nameThe last name of the contactstring()false
organization.nameThe name of the organizationstring()false
organizationThe organization this entity belongs toobject(){}false
patternMatch patternstring()false
tags.[]string()false
tagsTags that contact belong toarray(string())false

contacts

Schema for a contact.

KeyDescriptionTypeDefaultRequiredSupport Level
contactThe phone number or email associated with the contact (Ex: +14158867903, user@2600hz.com)string()true
device_typeThe type of the devicestring('work', 'home', 'mobile', 'personal', 'fax')false
email_typeThe type of the emailstring('work', 'home')false
extThe extension of the user (Ex: 356, 622)string()false
primaryIf this is the primary contact for this contact type.boolean()true
typeThe type of this contactstring('voice', 'email', 'sms')true

There is only one primary contact (primary: true) for a given contact type. Otherwise, it will result 400 Validation Error HTTP response status with response payload like this:

{
    "data": {
        "contacts": {
            "primary": {
                "message": "more than one primary contact for a contact type"
            }
        }
    },
    "error": "400",
    "message": "validation error",
    "status": "error"
}

history

Schema for a history.

KeyDescriptionTypeDefaultRequiredSupport Level
contactThe contact that was used#/definitions/contactstrue
notesNotes from the communicationstring()false
timestampThe gregorian timestampinteger()false

Company Contact (No associated Owner ID)

Company contact does not contain an owner_id and these endpoints do not associate with users/user_id.

If auth token does not belong to an admin, only GET requests are continued. If you perform a request other than GET and the auth token does not belong to an admin, the request is stopped. It will result in 403 Forbidden HTTP response status with response payload like this:

{
    "data": {
        "message": "only admins have permissions for this operation"
    },
    "error": "403",
    "message": "forbidden",
    "status": "error"
}

Fetch

Lists all contacts in the account that have no/empty owner_id

GET /v2/accounts/{ACCOUNT_ID}/lists

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{CONTACT_ID}",
            "name": "User",
            "contacts": [
                {
                    "voice": "1234567890"
                },
                {
                    "email": "user@2600hz.com"
                },
                {
                    "sms": "1234567891"
                }
            ],
            "favorite": false
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Fetch contact lists by Tag

Lists all contacts in the account that have no/empty owner_id and the document has a tag that matches the tag in the URL (without the prefix “tag-“)

GET /v2/accounts/{ACCOUNT_ID}/lists/tag-{tag}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/tag-{TAG1}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{CONTACT_ID}",
            "name": "User",
            "contacts": [
                {
                    "voice": "1234567890"
                },
                {
                    "email": "user@2600hz.com"
                },
                {
                    "sms": "1234567891"
                }
            ],
            "favorite": false,
            "tags": [
                "{TAG1}",
                "{TAG2}"
            ]
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Fetch a contact list

Fetches the contact of given contact_id, if it has no/empty owner_id

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

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{CONTACT_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "favorite": false,
        "history": [],
        "organization": {},
        "first_name": "User",
        "contacts": [
            {
                "type": "voice",
                "contact": "1234567890",
                "primary": true
            },
            {
                "type": "email",
                "contact": "user@2600hz.com",
                "primary": true
            },
            {
                "type": "sms",
                "contact": "1234567891",
                "primary": true
            }
        ],
        "id": "{CONTACT_ID}"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Create a new contact list

Creates a new company contact only if the auth token belongs to an admin

PUT /v2/accounts/{ACCOUNT_ID}/lists

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{
            "data": {
                "first_name": "User",
                "contacts": [
                    {
                        "type": "voice",
                        "contact": "1234567890",
                        "primary": true
                    },
                    {
                        "type": "email",
                        "contact": "user@2600hz.com",
                        "primary": true
                    },
                    {
                        "type": "sms",
                        "contact": "1234567891",
                        "primary": true
                    }
                ]
            }
        }' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists

Response is the full contact list doc, same as fetching a contact list by contact ID.

Replace contact list

Replaces an existing company contact, only if the auth token belongs to an admin

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

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{
            "data": {
                "first_name": "User",
                "contacts": [
                    {
                        "type": "voice",
                        "contact": "1234567890",
                        "primary": true
                    },
                    {
                        "type": "email",
                        "contact": "user@2600hz.com",
                        "primary": false
                    },
                    {
                        "type": "sms",
                        "contact": "1234567891",
                        "primary": false
                    }
                ]
            }
        }' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/lists/{CONTACT_ID}

Request and response are same as create API.

Delete contact list

Deletes an existing company contact only if auth token belongs to an admin

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

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

Update contact list

Patches an existing company contact only if the auth token belongs to an admin

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

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

Response is the full contact list doc, same as fetching a contact list by contact ID.

Personal Contact (With Owner ID)

Personal contact contains an owner_id and these endpoints associate with users/user_id.

  • If the auth token belongs to an admin, allows the request to continue.
  • If the auth token does not belong to an admin,
    • The owner_id of the auth token must match the user_id in the URL.

    • Otherwise, the request is stopped and it will result in 403 Forbidden HTTP response status with response payload like this:

      {
          "data": {
              "message": "auth token user and requested user doesn't match"
          },
          "error": "403",
          "message": "forbidden",
          "status": "error"
      }
      

If the auth token does not belong to an admin, auth token owner_id must match the user_id in the URL

  • For entity URLS which contains {CONTACT_ID} like GET, POST, PATCH, DELETE
    • The owner_id of the given contact must match the user_id in the URL.

    • Otherwise, the request is stopped and it will result in 400 Validation Error HTTP response status with response payload like this:

      {
          "data": {
              "owner_id": {
                  "missmatch": {
                      "message": "request userid token and contact owner_id doesn't match"
                  }
              }
          },
          "error": "400",
          "message": "validation error",
          "status": "error"
      }
      

For entity URLs, contact owner_id must match the user_id in the URL

Fetch contact lists by User Id

Lists all contacts in the account where the owner_id is empty or matches the user_id in the URL.

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
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{CONTACT_ID}",
            "name": "User",
            "contacts": [
                {
                    "voice": "1234567890"
                },
                {
                    "email": "user@2600hz.com"
                },
                {
                    "sms": "1234567891"
                }
            ],
            "favorite": false
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Fetch contact lists by Tag and User Id

Lists all contacts in the account that match the tag (whithout the prefix “tag-“) and the owner_id is empty or matches the user_id in the URL.

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

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/tag-{TAG1}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{CONTACT_ID}",
            "name": "User",
            "contacts": [
                {
                    "voice": "1234567890"
                },
                {
                    "email": "user@2600hz.com"
                },
                {
                    "sms": "1234567891"
                }
            ],
            "favorite": false,
            "tags": [
                "{TAG1}",
                "{TAG2}"
            ]
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Fetch a contact list by User Id

Fetches the contact of given contact_id, if the user_id in the URL matches owner_id of the contact.

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

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{CONTACT_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "favorite": false,
        "history": [],
        "organization": {},
        "first_name": "User",
        "contacts": [
            {
                "type": "voice",
                "contact": "1234567890",
                "primary": true
            },
            {
                "type": "email",
                "contact": "user@2600hz.com",
                "primary": true
            },
            {
                "type": "sms",
                "contact": "1234567891",
                "primary": true
            }
        ],
        "id": "{CONTACT_ID}"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Create a new contact list with User Id

Creates a new contact with user_id in the URL as the owner_id of the contact.

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

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{
            "data": {
                "first_name": "User",
                "contacts": [
                    {
                        "type": "voice",
                        "contact": "1234567890",
                        "primary": true
                    },
                    {
                        "type": "email",
                        "contact": "user@2600hz.com",
                        "primary": true
                    },
                    {
                        "type": "sms",
                        "contact": "1234567891",
                        "primary": true
                    }
                ]
            }
        }' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists

Response is the full contact list doc, same as fetching a contact list by contact ID.

Replace contact list with User Id

Replaces an existing contact, only if the user_id in the URL matches owner_id of the contact.

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

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{
            "data": {
                "first_name": "User",
                "contacts": [
                    {
                        "type": "voice",
                        "contact": "1234567890",
                        "primary": true
                    },
                    {
                        "type": "email",
                        "contact": "user@2600hz.com",
                        "primary": false
                    },
                    {
                        "type": "sms",
                        "contact": "1234567891",
                        "primary": false
                    }
                ]
            }
        }' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/lists/{CONTACT_ID}

Request and response are same as create API.

Delete contact list with User Id

Deletes an existing contact, only if the user_id in the URL matches owner_id of the contact.

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

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

Update contact list with User Id

Patches an existing contact, only if the user_id in the URL matches owner_id of the contact.

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

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

Response is the full contact list doc, same as fetching a contact list by contact ID.

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

On this page