# Contacts API

API calls are made per channel. Tokens can be generated by using the key icon, next to the desired channel in [Settings](https://heyx.gitbook.io/heyx-integration/welcome/broken-reference). There is a 200 API calls per minute rate limit.

## Requests

The Contacts API is composed of several requests:

* [Get Contact by Custom Field](https://heyx.gitbook.io/heyx-integration/welcome/broken-reference)
* [Get Contact by ID](https://heyx.gitbook.io/heyx-integration/welcome/broken-reference)
* [Update Contact by ID](https://heyx.gitbook.io/heyx-integration/welcome/broken-reference)
* [Add Tag by ID](https://heyx.gitbook.io/heyx-integration/welcome/broken-reference)
* [Remove Tag by ID](https://heyx.gitbook.io/heyx-integration/welcome/broken-reference)
* [Create Contact](https://heyx.gitbook.io/heyx-integration/welcome/broken-reference)

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