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.
/v1/contact/by_custom_field
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'
curl -X GET \
      'https://app.respond.io/api/v1/contact/by_custom_field?name=firstName&value=Muhammad%20Mahin' \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json'
Response - Success (HTTP status → 200)
{
      "data": [
        {
          "id": "1776025372480910",
          "custom_fields": {
            "firstName": "Mahin",
            "lastName": "Dar",
            "locale": "en_GB",
            "timezone": "5",
            "gender": "male",
            "phone": "123123",
            "email": "[email protected]",
            "customerid": "1",
            "isLead" : true
          },
          "tags": [
            "Blog Updates",
            "Platform Updates"
          ],
          "created_at": 1575618542
        }
      ],
      "links": {
        "first": "http://app.respond.io/api/v1/contact/by_custom_field?page=1",
        "last": "http://app.respond.io/api/v1/contact/by_custom_field?page=1",
        "prev": null,
        "next": null
      },
      "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://app.respond.io/api/v1/contact/by_custom_field",
        "per_page": 10,
        "to": 1,
        "total": 1
      }
    }
Get Contact by ID
This request returns a single Contact object.
/v1/contact/{contact_id}
Sample GET Request
curl -X GET \
      https://app.respond.io/api/v1/contact/1776025372480910 \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
Response - Success (HTTP status → 200)
{
        "data": {
            "id": "1776025372480910",
            "custom_fields": {
                "firstName": "Mahin",
                "lastName": "Dar",
                "locale": "en_GB",
                "timezone": "5",
                "gender": "male",
                "phone": "123123",
                "email": "[email protected]",
                "customerid": "1"
            },
            "tags": [
                "Blog Updates",
                "Platform Updates"
            ],
            "created_at": 1575618542
        }
    }
Update Contact by ID
This request updates a contact custom field value.
/v1/contact/{contact_id}
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
curl -X PUT \
      https://app.respond.io/api/v1/contact/1776025372480910 \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
        "custom_fields": [
            {
                "name": "firstName",
                "value": "Muhammad Mahin"
            },
            {
                "name": "lastName",
                "value": "Dar"
            },
            {
                "name": "profilePic",
                "value": "Muhammad Mahin"
            },
            {
                "name": "firstName",
                "value": "Muhammad Mahin"
            },
            {
                "name": "lastName",
                "value": "Dar"
            }
        ]
    }'
Response - Success (HTTP status → 200)
{
      "data": {
        "id": "cus_112233344555"
      }
    }
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.
/v1/contact/{contact_id}/tags
Sample POST Request
curl -X POST \
      https://app.respond.io/api/v1/contact/1776025372480910/tags \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
        "tags": [
            "Blog Updates",
            "Platform Updates"
        ]
    }'
Response - Success (HTTP status → 200)
{
        "status": "success",
        "message": "Contact Tags have been added successfully.",
        "data": []
    }
Limitations
Maximum 10 Tags added per Request.
Remove Tag by ID
This request deletes tags for a Contact.
/v1/contact/{contact_id}/tags
Sample DELETE Request
curl -X DELETE \
      https://app.respond.io/api/v1/contact/1776025372480910/tags \
      -H 'Authorization: Bearer {channel_token}' \
      -H 'Content-Type: application/json' \
      -d '{
        "tags": [
            "Blog Updates",
            "Platform Updates"
        ]
    }'
Response - Success (HTTP status → 200)
{
        "status": "success",
        "message": "Contact Tags deleted successfully.",
        "data": []
    }
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.
/v1/contact
Sample POST Request
curl -X POST \
      https://app.respond.io/api/v1/contact/ \
      -H 'Authorization: Bearer {channel_api_token}' \
      -H 'Content-Type: application/json' \
      -d '{
        "custom_fields": [
            {
                "name": "phone",
                "value": "03244077087"
            },
            {
                "name": "firstName",
                "value": "Muhammad Mahin"
            },
            {
                "name": "lastName",
                "value": "Dar"
            }
        ]
    }'
Response - Success (HTTP status → 200)
{
        "data": {
            "id": "cus_112233344555"
        }
    }
Error Codes
Unauthorized (HTTP Status → 401)
{
        "status": "error",
        "message": "API Token is invalid.",
        "data": []
    }
Too Many Requests (HTTP Status → 429)
  {
      "status": "error",
      "message": "Too many requests",
      "data": []
  }
Method Not Allowed (HTTP Status → 405)
  {
      "status": "error",
      "message": "405 Method Not Allowed.",
      "data": []
  }
General (HTTP Status → 403)
  {
      "status": "error",
      "message": "Message String",
      "data": []
  }
Limitations
Maximum 30 Fields created per Request.