> For the complete documentation index, see [llms.txt](https://heyx.gitbook.io/heyx-integration/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://heyx.gitbook.io/heyx-integration/welcome/contacts-api.md).

# 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](broken://pages/-LAINBFnEdnw43Th-iaZ). There is a 200 API calls per minute rate limit.

## Requests

The Contacts API is composed of several requests:

* [Get Contact by Custom Field](broken://pages/-LwIA27nuOFEqh7lopG0#get-contact-by-custom-field)
* [Get Contact by ID](broken://pages/-LwIA27nuOFEqh7lopG0#get-contact-by-id)
* [Update Contact by ID](broken://pages/-LwIA27nuOFEqh7lopG0#update-contact-by-id)
* [Add Tag by ID](broken://pages/-LwIA27nuOFEqh7lopG0#add-tag-by-id)
* [Remove Tag by ID](broken://pages/-LwIA27nuOFEqh7lopG0#remove-tag-by-id)
* [Create Contact](broken://pages/-LwIA27nuOFEqh7lopG0#limitations-3)

### Get Contact by Custom Field

This request returns a list of Contact objects with pagination.

```
/v1/contact/by_custom_field
```

#### Sample GET Request

{% hint style="info" %}
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'`
{% endhint %}

```
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'
```

#### Response - **Success (HTTP status → 200)**

```
{
      "data": [
        {
          "id": "1776025372480910",
          "custom_fields": {
            "firstName": "Mahin",
            "lastName": "Dar",
            "locale": "en_GB",
            "timezone": "5",
            "gender": "male",
            "phone": "123123",
            "email": "muhammad@heyx.io",
            "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
      }
    }
```

### Get Contact by ID

This request returns a single Contact object.

```
/v1/contact/{contact_id}
```

#### Sample GET Request

```
curl -X GET \
      https://app.heyx.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": "muhammad@heyx.io",
                "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.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"
            }
        ]
    }'
```

#### Response - **Success (HTTP status → 200)**

```
{
      "data": {
        "id": "cus_112233344555"
      }
    }
```

#### Limitations

Maximum 30 Fields updated per Request.

{% hint style="info" %}
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.
{% endhint %}

### Add Tag by ID

This request adds tags for a Contact.

```
/v1/contact/{contact_id}/tags
```

#### Sample POST Request

```
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"
        ]
    }'
```

#### 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.heyx.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.

{% hint style="info" %}
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.
{% endhint %}

### Create Contact

This request creates a Contact and sets values for its Custom Fields.

```
/v1/contact
```

#### Sample POST Request

```
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"
            }
        ]
    }'
```

#### 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.