# Contacts API

Contacts allow you to tie individual Calls from many Contact Numbers back to one person. You can also tag Contacts, and calls from their Contact Numbers will automatically inherit the tags.

## Get all Contacts

```shell
curl "https://api.retreaver.com/contacts.json?api_key=[api_key]&company_id=1"
```

> The above command returns JSON structured like this:

```json
[
  {
    "contact": {
      "id": 2,
      "contact_numbers": [
        {
          "number": "+18668987878",
          "description": "Landline",
          "id": 2
        }
      ],
      "tag_values": [
        {
          "key": "name",
          "value": "Retreaver Support",
          "operator": "==",
          "id": 154060720
        }
      ]
    }
  }
]
```

Provides a complete list of Contacts. Results are paginated.

### HTTP Request

`GET https://api.retreaver.com/contacts.json?api_key=[api_key]&company_id=1`

### Query Parameters

| Parameter | Type    | Default | Required | Description                                     |
| --------- | ------- | ------- | -------- | ----------------------------------------------- |
| page      | integer | 1       |          | The page of results to return.                  |
| per_page  | integer | 25      |          | The number of results per page. Maximum is 100. |

## Get a Specific Contact by ID

```shell
curl "https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1"
```

> The above command returns JSON structured like this:

```json
{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18668987878",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Retreaver Support",
        "operator": "==",
        "id": 154060720
      }
    ]
  }
}
```

Finds a Contact by its Retreaver ID.

### HTTP Request

`GET https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1`

## Create a Contact

```shell
curl -s \
    -X POST \
    https://api.retreaver.com/contacts.json \
    -H "Content-Type: application/json" \
    -d '{"contact":{"tag_list":"<<<name:Retreaver Support>>>","contact_numbers_attributes":[{"number":"8668987878", "description":"Landline"}]}}'
```

> The above command returns JSON structured like this:

```json
{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18668987878",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Retreaver Support",
        "operator": "==",
        "id": 154060720
      }
    ]
  }
}
```

Creates a Contact and associated Contact Number(s).

### HTTP Request

`POST https://api.retreaver.com/contacts.json?api_key=[api_key]&company_id=1`

`Content-Type: application/json`

`{"contact":{"tag_list":"<<<name:Retreaver Support>>>","contact_numbers_attributes":[{"number":"8668987878", "description":"Landline"}]}}`

### Parameters

| Parameter                  | Type   | Default | Required | Description                |
| -------------------------- | ------ | ------- | -------- | -------------------------- |
| tag_list                   | string |         |          | See notes below.           |
| contact_numbers_attributes | array  |         | required | An array of Contact Numbers. |

**Nested Attribute: Contact Number**

These are the phone numbers that are associated with your Contact.

| Parameter   | Type   | Default | Required | Description                                                                                                                        |
| ----------- | ------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| number      | string |         | required | Either a phone number or `sip:user@domain.com` formatted SIP endpoint. PSTN numbers should be [E.164 formatted](https://en.wikipedia.org/wiki/E.164). |
| description | string |         |          | A description of the phone number, like 'Home', 'Mobile', 'Work', 'iPhone', etc.                                                   |

### tag_list notes

To set tags on a Contact, pass in a comma delineated, triple-angle-bracket enclosed string of tags as the `tag_list` value.

The system will create/find whatever tags you have set given this input without you having to track tag IDs. You must include the full list of tags you want set any time a tag_list parameter is passed in. To clear the tags, just pass in a blank string.

There is a limit of 100 tags added in this manner, but the system will automatically concatenate US zip `geo` tags.

## Update a Contact

```shell
curl -s \
    -X PUT \
    https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"contact":{"contact_numbers_attributes":[{"id":2,"number":"+18001234567"}]}}'
```

> The above command returns JSON structured like this:

```json
{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18001234567",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Retreaver Support",
        "operator": "==",
        "id": 154060720
      }
    ]
  }
}
```

Changes any attributes you have passed in on the Contact. To change a Contact Number, you must pass in the ID of the existing Contact Number, or see [below](#update-a-contact-number-by-phone-number) for an easier method.

### HTTP Request

`PUT https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1`

`Content-Type: application/json`

`{"contact":{"contact_numbers_attributes":[{"id":2,"number":"+18001234567"}]}}`

## Remove a Contact

```shell
curl -X DELETE https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1
```

Deletes the given Contact and all Contact Numbers associated with it.

### HTTP Request

`DELETE https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1`

## Get a specific Contact by phone number

```shell
curl "https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1"
```

> The above command returns JSON structured like this:

```json
{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18001234567",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Retreaver Support",
        "operator": "==",
        "id": 154060720
      }
    ]
  }
}
```

Finds a Contact by phone number.

### HTTP Request

`GET https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1`

## Update a Contact by phone number

```shell
curl -s \
    -X PUT \
    https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"contact":{"tag_list":"<<<name:Invalid Number>>>"}}'
```

> The above command returns JSON structured like this:

```json
{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18001234567",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Invalid Number",
        "operator": "==",
        "id": 154060721
      }
    ]
  }
}
```

Updates a Contact by phone number. This endpoint acts as an upsert: if no Contact Number exists for the given phone number, a new Contact Number and Contact are created automatically.

### HTTP Request

`PUT https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1`

`Content-Type: application/json`

`{"contact":{"tag_list":"<<<name:Invalid Number>>>"}}`

## Delete a Contact by phone number

```shell
curl -X DELETE https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1
```

Deletes the contact associated with the phone number and all other contact numbers associated with the contact.

### HTTP Request

`DELETE https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1`