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

Key	Description	Type	Required
`description`	A friendly list description	`string(1..128)`	`false`
`name`	A friendly match list name	`string(1..128)`	`true`
`org`	Full legal name of the organization	`string()`	`false`
`owner_id`	UserId owner of the list	`string()`	`false`

Schema for a list of contacts

Key	Description	Type	Default	Required
`capture_group.key`	The number which is used to select this contact, length should be same as `capture_group_length`	`string()`		`false`
`capture_group.length`	Length of the numbers in the contacts for which it used to select desire Caller ID	`integer()`		`false`
`capture_group`	The capture group information	`object()`	`{}`	`false`
`contacts`	A list of contact information	`array([#/definitions/contacts](#contacts))`		`true`
`favorite`	Whether the contact is a favorite	`boolean()`	`false`	`false`
`first_name`	The first name of the contact	`string()`		`true`
`history`	The history of contact usage	`array([#/definitions/history](#history))`	`[]`	`false`
`last_name`	The last name of the contact	`string()`		`false`
`organization.name`	The name of the organization	`string()`		`false`
`organization`	The organization this entity belongs to	`object()`	`{}`	`false`
`pattern`	Match pattern	`string()`		`false`
`tags.[]`		`string()`		`false`
`tags`	Tags that contact belong to	`array(string())`		`false`

contacts

Schema for a contact.

Key	Description	Type	Required
`contact`	The phone number or email associated with the contact (Ex: +14158867903, user@2600hz.com)	`string()`	`true`
`device_type`	The type of the device	`string('work', 'home', 'mobile', 'personal', 'fax')`	`false`
`email_type`	The type of the email	`string('work', 'home')`	`false`
`ext`	The extension of the user (Ex: 356, 622)	`string()`	`false`
`primary`	If this is the primary contact for this contact type.	`boolean()`	`true`
`type`	The type of this contact	`string('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.

Key	Description	Type	Required
`contact`	The contact that was used	#/definitions/contacts	`true`
`notes`	Notes from the communication	`string()`	`false`
`timestamp`	The gregorian timestamp	`integer()`	`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

Lists

Examples

Schema

Schema for a list of contacts

contacts

history

Company Contact (No associated Owner ID)

Fetch

Fetch contact lists by Tag

Fetch a contact list

Create a new contact list

Replace contact list

Delete contact list

Update contact list

Personal Contact (With Owner ID)

Fetch contact lists by User Id

Fetch contact lists by Tag and User Id

Fetch a contact list by User Id

Create a new contact list with User Id

Replace contact list with User Id

Delete contact list with User Id

Update contact list with User Id

On this page