Contacts API

API calls are made per channel. Tokens can be generated by using the key icon, next to the desired channel in Settings. There is a 200 API calls per minute rate limit.
Requests
The Contacts API is composed of several requests:
​Get Contact by Custom Field​
​Get Contact by ID​
​Update Contact by ID​
​Add Tag by ID​
​Remove Tag by ID​
​Create Contact​
Get Contact by Custom Field
This request returns a list of Contact objects with pagination.
1
/v1/contact/by_custom_field
Copied!
Sample GET Request
If you wish to retrieve a list of contacts by custom field of type boolean, please be sure to use true or false as a value. 
If you wish to retrieve a list of contacts by phone number, please be sure to replace the '+' with '%2B'
1
curl -X GET \
2
      'https://app.respond.io/api/v1/contact/by_custom_field?name=firstName&value=Muhammad%20Mahin' \
3
      -H 'Authorization: Bearer {channel_token}' \
4
      -H 'Content-Type: application/json'
Copied!
Response - Success (HTTP status → 200)
1
{
2
      "data": [
3
        {
4
          "id": "1776025372480910",
5
          "custom_fields": {
6
            "firstName": "Mahin",
7
            "lastName": "Dar",
8
            "locale": "en_GB",
9
            "timezone": "5",
10
            "gender": "male",
11
            "phone": "123123",
12
            "email": "[email protected]",
13
            "customerid": "1",
14
            "isLead" : true
15
          },
16
          "tags": [
17
            "Blog Updates",
18
            "Platform Updates"
19
          ],
20
          "created_at": 1575618542
21
        }
22
      ],
23
      "links": {
24
        "first": "http://app.respond.io/api/v1/contact/by_custom_field?page=1",
25
        "last": "http://app.respond.io/api/v1/contact/by_custom_field?page=1",
26
        "prev": null,
27
        "next": null
28
      },
29
      "meta": {
30
        "current_page": 1,
31
        "from": 1,
32
        "last_page": 1,
33
        "path": "http://app.respond.io/api/v1/contact/by_custom_field",
34
        "per_page": 10,
35
        "to": 1,
36
        "total": 1
37
      }
38
    }
Copied!
Get Contact by ID
This request returns a single Contact object.
1
/v1/contact/{contact_id}
Copied!
Sample GET Request
1
curl -X GET \
2
      https://app.respond.io/api/v1/contact/1776025372480910 \
3
      -H 'Authorization: Bearer {channel_token}' \
4
      -H 'Content-Type: application/json' \
Copied!
Response - Success (HTTP status → 200)
1
{
2
        "data": {
3
            "id": "1776025372480910",
4
            "custom_fields": {
5
                "firstName": "Mahin",
6
                "lastName": "Dar",
7
                "locale": "en_GB",
8
                "timezone": "5",
9
                "gender": "male",
10
                "phone": "123123",
11
                "email": "[email protected]",
12
                "customerid": "1"
13
            },
14
            "tags": [
15
                "Blog Updates",
16
                "Platform Updates"
17
            ],
18
            "created_at": 1575618542
19
        }
20
    }
Copied!
Update Contact by ID
This request updates a contact custom field value.
1
/v1/contact/{contact_id}
Copied!
Contact field (IDs) that are allowed to be updated
firstName
lastName
profilePic
language
phone
email
custom_field IDs (Refer Contact Field module to get the ID of each custom field)
Custom field is allowed to be updated 
Sample PUT Request
1
curl -X PUT \
2
      https://app.respond.io/api/v1/contact/1776025372480910 \
3
      -H 'Authorization: Bearer {channel_token}' \
4
      -H 'Content-Type: application/json' \
5
      -d '{
6
        "custom_fields": [
7
            {
8
                "name": "firstName",
9
                "value": "Muhammad Mahin"
10
            },
11
            {
12
                "name": "lastName",
13
                "value": "Dar"
14
            },
15
            {
16
                "name": "profilePic",
17
                "value": "Muhammad Mahin"
18
            },
19
            {
20
                "name": "firstName",
21
                "value": "Muhammad Mahin"
22
            },
23
            {
24
                "name": "lastName",
25
                "value": "Dar"
26
            }
27
        ]
28
    }'
Copied!
Response - Success (HTTP status → 200)
1
{
2
      "data": {
3
        "id": "cus_112233344555"
4
      }
5
    }
Copied!
Limitations
Maximum 30 Fields updated per Request.
Please note that in case of Viber Channel - due to a certain limitation - the Contact ID needs to be provided in a Base64 encoded format.
Add Tag by ID
This request adds tags for a Contact.
1
/v1/contact/{contact_id}/tags
Copied!
Sample POST Request
1
curl -X POST \
2
      https://app.respond.io/api/v1/contact/1776025372480910/tags \
3
      -H 'Authorization: Bearer {channel_token}' \
4
      -H 'Content-Type: application/json' \
5
      -d '{
6
        "tags": [
7
            "Blog Updates",
8
            "Platform Updates"
9
        ]
10
    }'
Copied!
Response - Success (HTTP status → 200)
1
{
2
        "status": "success",
3
        "message": "Contact Tags have been added successfully.",
4
        "data": []
5
    }
Copied!
Limitations
Maximum 10 Tags added per Request.
Remove Tag by ID
This request deletes tags for a Contact.
1
/v1/contact/{contact_id}/tags
Copied!
Sample DELETE Request
1
curl -X DELETE \
2
      https://app.respond.io/api/v1/contact/1776025372480910/tags \
3
      -H 'Authorization: Bearer {channel_token}' \
4
      -H 'Content-Type: application/json' \
5
      -d '{
6
        "tags": [
7
            "Blog Updates",
8
            "Platform Updates"
9
        ]
10
    }'
Copied!
Response - Success (HTTP status → 200)
1
{
2
        "status": "success",
3
        "message": "Contact Tags deleted successfully.",
4
        "data": []
5
    }
Copied!
Limitations
Maximum 10 Tags deleted per Request.
Please note that in case of Viber Channel - due to a certain limitation - the Contact ID needs to be provided in a Base64 encoded format.
Create Contact
This request creates a Contact and sets values for its Custom Fields.
1
/v1/contact
Copied!
Sample POST Request
1
curl -X POST \
2
      https://app.respond.io/api/v1/contact/ \
3
      -H 'Authorization: Bearer {channel_api_token}' \
4
      -H 'Content-Type: application/json' \
5
      -d '{
6
        "custom_fields": [
7
            {
8
                "name": "phone",
9
                "value": "03244077087"
10
            },
11
            {
12
                "name": "firstName",
13
                "value": "Muhammad Mahin"
14
            },
15
            {
16
                "name": "lastName",
17
                "value": "Dar"
18
            }
19
        ]
20
    }'
Copied!
Response - Success (HTTP status → 200)
1
{
2
        "data": {
3
            "id": "cus_112233344555"
4
        }
5
    }
Copied!
Error Codes
Unauthorized (HTTP Status → 401)
1
{
2
        "status": "error",
3
        "message": "API Token is invalid.",
4
        "data": []
5
    }
Copied!
Too Many Requests (HTTP Status → 429)
1
  {
2
      "status": "error",
3
      "message": "Too many requests",
4
      "data": []
5
  }
Copied!
Method Not Allowed (HTTP Status → 405)
1
  {
2
      "status": "error",
3
      "message": "405 Method Not Allowed.",
4
      "data": []
5
  }
Copied!
General (HTTP Status → 403)
1
  {
2
      "status": "error",
3
      "message": "Message String",
4
      "data": []
5
  }
Copied!
Limitations
Maximum 30 Fields created per Request.