Contacts API
Allows you to add, edit and retrieve contact information via 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.
The Contacts API is composed of several requests:
This request returns a list of Contact objects with pagination.
/v1/contact/by_custom_field
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.heyx.io/api/v1/contact/by_custom_field?name=firstName&value=Muhammad%20Mahin' \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json'
{
"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.heyx.io/api/v1/contact/by_custom_field?page=1",
"last": "http://app.heyx.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.heyx.io/api/v1/contact/by_custom_field",
"per_page": 10,
"to": 1,
"total": 1
}
}
This request returns a single Contact object.
/v1/contact/{contact_id}
curl -X GET \
https://app.heyx.io/api/v1/contact/1776025372480910 \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
{
"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
}
}
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
curl -X PUT \
https://app.heyx.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"
}
]
}'
{
"data": {
"id": "cus_112233344555"
}
}
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.
This request adds tags for a Contact.
/v1/contact/{contact_id}/tags
curl -X POST \
https://app.heyx.io/api/v1/contact/1776025372480910/tags \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
-d '{
"tags": [
"Blog Updates",
"Platform Updates"
]
}'
{
"status": "success",
"message": "Contact Tags have been added successfully.",
"data": []
}
Maximum 10 Tags added per Request.
This request deletes tags for a Contact.
/v1/contact/{contact_id}/tags
curl -X DELETE \
https://app.heyx.io/api/v1/contact/1776025372480910/tags \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
-d '{
"tags": [
"Blog Updates",
"Platform Updates"
]
}'
{
"status": "success",
"message": "Contact Tags deleted successfully.",
"data": []
}
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.
This request creates a Contact and sets values for its Custom Fields.
/v1/contact
curl -X POST \
https://app.heyx.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"
}
]
}'
{
"data": {
"id": "cus_112233344555"
}
}
{
"status": "error",
"message": "API Token is invalid.",
"data": []
}
{
"status": "error",
"message": "Too many requests",
"data": []
}
{
"status": "error",
"message": "405 Method Not Allowed.",
"data": []
}
{
"status": "error",
"message": "Message String",
"data": []
}
Maximum 30 Fields created per Request.
Last modified 1yr ago