Contacts API

Allows you to add, edit and retrieve contact information via API.

Contacts and Messages API 1.0 will be deprecated in 2023. We highly recommend that you start migrating to the new API soon.
Start building with respond.io's next-generation API. Please see our specific API Documentation here for more information.
​
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.

Integrations - Previous

Webhooks

Next - 👨‍💻 DEVELOPER API

Messages API

Last modified 3mo ago