Contacts

Here you find all available endpoints related to Swell CX contacts. These endpoints are protected and you'll need an API Key.

In order to use the GET and POST requests, add to the header the following:

Key Value
Content-Type application/json
Accept application/json

GET /api/v1/contacts

Parameters

Param Required Description
token Required The API token generated throught UI interface on swell platform.
team_id Optional Filter contacts to show only those from this team_id
contact_id Optional Filter contacts to show for this contact_id
location_id Optional Filter contacts to show only those from this location_id. Format: (Integer or Array).
created_before Optional Filter contacts by created date. Format: yyyy-mm-dd HH:MI.
created_after Optional Filter contacts by created date. Format: yyyy-mm-dd HH:MI.
updated_before Optional Filter contacts by updated date. Format: yyyy-mm-dd HH:MI.
updated_after Optional Filter contacts by updated date. Format: yyyy-mm-dd HH:MI.
page Optional Specify the page you would like returned in a request. Minimum value: 1
per_page Optional Specify the number of records to return in one request, specified as an integer from 1 to 100. Default 15.

Examples


Request Example

/api/v1/contacts?token=3lxeh7XMElKc97lbPNwWKNEBOw9Nzuur7ntfoKwBzh4UboVos0qU5qhFh4nT


Response

{
    "data": [
        {
            "id": 307178,
            "name": "John Doe",
            "phone": "8017874321",
            "email": "john.doe@mail.com",
            "source": "swell",
            "tags": [],
            "locations": [
                {
                    "id": 374,
                    "name": "John Doe Company"
                }
            ],
            "country_code": {
                 "short_name": "US", 
                 "code": "+1"
            },
            "created_at": "2021-09-01T16:05:14-06:00"
        },
        {
            "id": 307181,
            "name": "Jane Doe",
            "phone": "8014838306",
            "email": "jane.doe@mail.com",
            "source": "swell",
            "tags": [],
            "locations": [
                {
                    "id": 374,
                    "name": "John Doe Company"
                }
            ],
            "country_code": null,
            "created_at": "2021-09-01T16:05:14-06:00"
        }
    ],
    "links": {
        "first": "http://swell.test/api/v1/contacts?page=1",
        "last": "http://swell.test/api/v1/contacts?page=297",
        "prev": null,
        "next": "http://swell.test/api/v1/contacts?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 297,
        "path": "http://swell.test/api/v1/contacts",
        "per_page": 2,
        "to": 2,
        "total": 593
    }
}

Filters

Filter Required Description
name Optional Filter by contact name
phone Optional Filter by contact phone
email Optional Filter by contact email

Examples


Request Example

/api/v1/contacts?name=John&token=3lxeh7XMElKc97lbPNwWKNEBOw9Nzuur7ntfoKwBzh4UboVos0qU5qhFh4nT


Response

{
    "data": [
        {
            "id": 307178,
            "name": "John Doe",
            "phone": "8017874321",
            "email": "john.doe@mail.com",
            "source": "swell",
            "tags": [],
            "locations": [
                {
                    "id": 374,
                    "name": "John Doe Company"
                }
            ],
            "country_code": {
                 "short_name": "US", 
                 "code": "+1"
            },
            "created_at": "2021-09-01T16:05:14-06:00"
        }
    ],
    "links": {
        "first": "http://swell.test/api/v1/contacts?page=1",
        "last": "http://swell.test/api/v1/contacts?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://swell.test/api/v1/contacts",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

GET /api/v1/contacts/{id}

Parameters

Param Required Description
token Required The API token generated throught UI interface on swell platform.
id Required The id of the contact

Examples


Request Example

/api/v1/contacts/307178?token=3lxeh7XMElKc97lbPNwWKNEBOw9Nzuur7ntfoKwBzh4UboVos0qU5qhFh4nT


Response

{
    "data": [
        {
            "id": 307178,
            "name": "John Doe",
            "phone": "8017874321",
            "email": "john.doe@mail.com",
            "source": "swell",
            "tags": [],
            "locations": [
                {
                    "id": 374,
                    "name": "John Doe Company"
                }
            ],
            "country_code": {
                 "short_name": "US", 
                 "code": "+1"
            },
            "created_at": "2021-09-01T16:05:14-06:00"
        },
    ]
}

POST /api/v1/contacts

Parameters

Param Required Description
token Required The API token generated throught UI interface on Swell CX platform.
name Optional Name contact.
email Required If phone is included, then this is optional.
phone Required If email is included, then this is optional.
tags Optional Tags names array.
locations Required Locations id or ids array.
country_code Optional Optional with phone, if included do not include country code on phone. String containing one of the following US, CA, NZL, UK, AUS, defaults to OTHER.

Examples


Request Example

{
    "token": "3lxeh7XMElKc97lbPNwWKNEBOw9Nzuur7ntfoKwBzh4UboVos0qU5qhFh4nT",
    "name": "user_name",
    "email": "user@swell.com",
    "phone": "0123456789",
    "tags": ["tag_name1", "tag_name2"],
    "locations": [1, 2],
    "country_code": "US"
}


Response

{
    "id": 601321,
    "name": "user_name",
    "phone": "0123456789",
    "email": "user@swell.com",
    "source": "swell",
    "tags": [
        {
            "id": 1,
            "name": "tag_name1"
        },
        {
            "id": 2,
            "name": "tag_name2"
        }
    ],
    "locations": [
        {
            "id": 1,
            "name": "location_name1"
        },
        {
            "id": 2,
            "name": "location_name2"
        }
    ],
    "country_code": {
        "short_name": "US", 
        "code": "+1"
    },
    "created_at": "2021-09-01T16:05:14-06:00"
}

PATCH /api/v1/contacts/{id}

Parameters

Param Required Description
token Required The API token generated throught UI interface on Swell CX platform.
id Required The id of the contact to patch.
name Optional Name contact.
email Required If phone is included, then this is optional. It is recommended to include both the phone and email parameters.
phone Required If email is included, then this is optional. It is recommended to include both the phone and email parameters.
tags Optional Tags names array.
locations Optional Locations id or ids array.
country_code Optional Optional with phone, if included do not include country code on phone. String containing one of the following US, CA, NZL, UK, AUS, defaults to OTHER.

Examples


PATCH Example

/api/v1/contacts/601321
{
    "token": "3lxeh7XMElKc97lbPNwWKNEBOw9Nzuur7ntfoKwBzh4UboVos0qU5qhFh4nT",
    "name": "New Name",
    "email": "user@swell.com",
    "phone": "0123456789"
}


Response

{
    "id": 601321,
    "name": "New name",
    "phone": "0123456789",
    "email": "user@swell.com",
    "source": "swell",
    "tags": [
        {
            "id": 1,
            "name": "tag_name1"
        },
        {
            "id": 2,
            "name": "tag_name2"
        }
    ],
    "locations": [
        {
            "id": 1,
            "name": "location_name1"
        },
        {
            "id": 2,
            "name": "location_name2"
        }
    ],
    "country_code": {
        "short_name": "US", 
        "code": "+1"
    },
    "created_at": "2021-09-01T16:05:14-06:00"
}