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

# Manage contacts

## Introduction

Contact data is owned and managed by the contact-service. It's important to understand that contacts can be created at multiple levels:

* global
* group
* site/device

## list global contacts

<mark style="color:blue;">`GET`</mark> `https://talos-app.io/api/contact-service/contacts/search/findGlobalContacts{companyId}`

Use this endpoint to list global contacts for a particular company.

#### Query Parameters

| Name      | Type   | Description                                                            |
| --------- | ------ | ---------------------------------------------------------------------- |
| companyId | string | The Company ID, as it is displayed on the evalink talos Web Interface. |

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

{% tabs %}
{% tab title="200 " %}

```
{
    "_embedded": {
        "contacts": [
            {
                "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
                "deviceId": null,
                "deviceGroupId": null,
                "id": "8a81ac997541955b0175924f82860576",
                "name": "Jane Doe",
                "description": null,
                "email": "kaiser.lukas@gmail.com",
                "codeword": null,
                "available": true,
                "availableScheduleId": null,
                "availableScheduleState": null,
                "overrideId": null,
                "overrideStart": null,
                "overrideEnd": null,
                "overrideRemark": null,
                "updatedAt": 1604477485700,
                "updatedBy": "John Doe",
                "phones": [
                    {
                        "id": "8a81ac997541955b0175924f82860577",
                        "number": "+41315110101",
                        "phoneType": "MAIN",
                        "customType": null
                    }
                ],
                "entityStatus": "VALIDATED",
                "rolesPreview": [],
                "currentlyOverriden": false,
                "contactListsPreview": [
                    {
                        "id": "8a81f4af754194a90175924fc97b0650",
                        "name": "My Global Contact List"
                    }
                ],
                "phone": "+41315110101",
                "_links": {
                    "self": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81ac997541955b0175924f82860576"
                    },
                    "contact": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81ac997541955b0175924f82860576"
                    },
                    "contactLists": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81ac997541955b0175924f82860576/contactLists"
                    },
                    "roles": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81ac997541955b0175924f82860576/roles"
                    }
                }
            },
            {
                "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
                "deviceId": null,
                "deviceGroupId": null,
                "id": "8a81f4af754194a9017592396840064b",
                "name": "John Doe",
                "description": null,
                "email": "lukas.kaiser@sitasys.com",
                "codeword": null,
                "available": true,
                "availableScheduleId": null,
                "availableScheduleState": null,
                "overrideId": null,
                "overrideStart": null,
                "overrideEnd": null,
                "overrideRemark": null,
                "updatedAt": 1604502197123,
                "updatedBy": "John Doe",
                "phones": [
                    {
                        "id": "8a81f4af754194a9017592396840064c",
                        "number": "+41315110101",
                        "phoneType": "MAIN",
                        "customType": null
                    }
                ],
                "entityStatus": "VALIDATED",
                "rolesPreview": [],
                "currentlyOverriden": false,
                "contactListsPreview": [
                    {
                        "id": "8a81f4af754194a90175924fc97b0650",
                        "name": "My Global Contact List"
                    }
                ],
                "phone": "+41315110101",
                "_links": {
                    "self": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81f4af754194a9017592396840064b"
                    },
                    "contact": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81f4af754194a9017592396840064b"
                    },
                    "contactLists": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81f4af754194a9017592396840064b/contactLists"
                    },
                    "roles": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81f4af754194a9017592396840064b/roles"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://talos-app.io/api/contact-service/contacts/search/findGlobalContacts?companyId=064646f3-18a2-4298-a28e-6e2883f27407"
        }
    }
}
```

{% endtab %}

{% tab title="403 " %}

```
{
    "error": "access_denied",
    "error_description": "Access is denied"
}
```

{% endtab %}
{% endtabs %}

## list contacts for one or many device groups

<mark style="color:blue;">`GET`</mark> `https://talos-app.io/api/contact-service/contacts/search/findByDeviceGroupIdIn{deviceGroupIds}`

Use this endpoint to list the contacts of one or multiple site (device) groups.

#### Path Parameters

| Name           | Type   | Description                   |
| -------------- | ------ | ----------------------------- |
| deviceGroupIds | string | The list of device group IDs. |

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

{% tabs %}
{% tab title="200 " %}

```
{
    "_embedded": {
        "contacts": [
            {
                "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
                "deviceId": null,
                "deviceGroupId": "8a81c66d76041f280176244360141c22",
                "id": "8a81a1ee76240e8f017624447da80000",
                "name": "My Group Contact",
                "description": "this is a contact on group level",
                "email": "john.doe.group@evalink.io",
                "codeword": "secret",
                "available": true,
                "availableScheduleId": null,
                "availableScheduleState": null,
                "overrideId": null,
                "overrideStart": null,
                "overrideEnd": null,
                "overrideRemark": null,
                "updatedAt": 1606926237080,
                "updatedBy": "John Doe",
                "phones": [
                    {
                        "id": "8a81a1ee76240e8f017624447db00001",
                        "number": "+41315110101",
                        "phoneType": "MAIN",
                        "customType": null
                    }
                ],
                "entityStatus": "VALIDATION_PENDING",
                "currentlyOverriden": false,
                "rolesPreview": [],
                "contactListsPreview": [],
                "phone": "+41315110101",
                "_links": {
                    "self": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f017624447da80000"
                    },
                    "contact": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f017624447da80000"
                    },
                    "roles": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f017624447da80000/roles"
                    },
                    "contactLists": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f017624447da80000/contactLists"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://talos-app.io/api/contact-service/contacts/search/findByDeviceGroupIdIn?deviceGroupIds=8a81c66d76041f280176244360141c22"
        }
    }
}
```

{% endtab %}

{% tab title="403 " %}

```
{
    "error": "access_denied",
    "error_description": "Access is denied"
}
```

{% endtab %}
{% endtabs %}

## list contacts of one or many devices&#x20;

<mark style="color:blue;">`GET`</mark> `https://talos-app.io/api/contact-service/contacts/search/findByDeviceIdIn{deviceIds}`

Use this endpoint to list all the contacts for one or a list of devices

#### Query Parameters

| Name      | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| deviceIds | string | The collection of device IDs. |

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

{% tabs %}
{% tab title="200 " %}

```
{
    "_embedded": {
        "contacts": [
            {
                "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
                "deviceId": "8a81c66d76041f28017623e5db421ba9",
                "deviceGroupId": null,
                "id": "8a81a1ee76240e8f017624484dcb0002",
                "name": "My Local Contact",
                "description": "This is a contact on site/device level",
                "email": "jane.doe.local@evlink.io",
                "codeword": "some secret",
                "available": true,
                "availableScheduleId": null,
                "availableScheduleState": null,
                "overrideId": null,
                "overrideStart": null,
                "overrideEnd": null,
                "overrideRemark": null,
                "updatedAt": 1606926486981,
                "updatedBy": "John Doe",
                "phones": [
                    {
                        "id": "8a81a1ee76240e8f017624484dcb0003",
                        "number": "+41315110101",
                        "phoneType": "MAIN",
                        "customType": null
                    }
                ],
                "entityStatus": "VALIDATED",
                "currentlyOverriden": false,
                "rolesPreview": [],
                "contactListsPreview": [],
                "phone": "+41315110101",
                "_links": {
                    "self": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f017624484dcb0002"
                    },
                    "contact": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f017624484dcb0002"
                    },
                    "roles": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f017624484dcb0002/roles"
                    },
                    "contactLists": {
                        "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f017624484dcb0002/contactLists"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://talos-app.io/api/contact-service/contacts/search/findByDeviceIdIn?deviceIds=8a81c66d76041f28017623e5db421ba9"
        }
    }
}
```

{% endtab %}
{% endtabs %}

## create a global contact

<mark style="color:green;">`POST`</mark> `https://talos-app.io/api/contact-service/contacts`

Use this endpoint to create a global contact in your company on evalink talos.

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

#### Request Body

| Name      | Type    | Description                                                            |
| --------- | ------- | ---------------------------------------------------------------------- |
| phone     | string  | The phone number for the contact.                                      |
| phones    | array   | A list of phone numbers for the contact.                               |
| available | boolean | The availability of the contact.                                       |
| email     | string  | The e-mail of the contact.                                             |
| name      | string  | The name of the contact.                                               |
| companyId | string  | The Company ID, as it is displayed on the evalink talos Web Interface. |

{% tabs %}
{% tab title="200 " %}

```
{
    "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
    "deviceId": null,
    "deviceGroupId": null,
    "id": "8a81e949761929c101762455866300e3",
    "name": "New Global Contact",
    "description": null,
    "email": "kaiser.lukas@gmail.com",
    "codeword": "some secret",
    "available": true,
    "availableScheduleId": null,
    "availableScheduleState": null,
    "overrideId": null,
    "overrideStart": null,
    "overrideEnd": null,
    "overrideRemark": null,
    "updatedAt": 1606927353440,
    "updatedBy": "API - API-DOC",
    "phones": [],
    "entityStatus": "VALIDATION_PENDING",
    "rolesPreview": [],
    "currentlyOverriden": false,
    "contactListsPreview": [],
    "phone": null,
    "_links": {
        "self": {
            "href": "http://talos-app.io/api/contact-service/contacts/8a81e949761929c101762455866300e3"
        },
        "contact": {
            "href": "http://talos-app.io/api/contact-service/contacts/8a81e949761929c101762455866300e3"
        },
        "contactLists": {
            "href": "http://talos-app.io/api/contact-service/contacts/8a81e949761929c101762455866300e3/contactLists"
        },
        "roles": {
            "href": "http://talos-app.io/api/contact-service/contacts/8a81e949761929c101762455866300e3/roles"
        }
    }
}
```

{% endtab %}
{% endtabs %}

## create a contact on group level

<mark style="color:green;">`POST`</mark> `https://talos-app.io/api/contact-service/contacts`

Use this endpoint to create a contact on your company in evalink talos.

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

#### Request Body

| Name          | Type    | Description                       |
| ------------- | ------- | --------------------------------- |
| phone         | string  | The phone number for the contact. |
| available     | boolean | The availability of the contact.  |
| email         | string  | The e-mail of the contact.        |
| description   | string  | The description of the contact.   |
| deviceGroupId | string  | The relevant device group ID.     |
| name          | string  | The name of the contact.          |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## create a contact on device level

<mark style="color:green;">`POST`</mark> `https://talos-app.io/api/contact-service/contacts`

Use this endpoint to create a contact on device level.

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

#### Request Body

| Name        | Type    | Description                      |
| ----------- | ------- | -------------------------------- |
| phone       | string  | The phone number of the contact. |
| available   | boolean | The availability of the contact. |
| email       | string  | The e-mail of the contact.       |
| description | string  | The description of the contact.  |
| deviceId    | string  | The relevant device ID.          |
| name        | string  | The name of the contact.         |

{% tabs %}
{% tab title="200 " %}

```
{
    "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
    "deviceId": "8a81c66d76041f28017623e5db421ba9",
    "deviceGroupId": null,
    "id": "8a81a1ee76240e8f0176245ff71e0005",
    "name": "New Local Contact",
    "description": null,
    "email": "kaiser.lukas@gmail.com",
    "codeword": "some secret",
    "available": true,
    "availableScheduleId": null,
    "availableScheduleState": null,
    "overrideId": null,
    "overrideStart": null,
    "overrideEnd": null,
    "overrideRemark": null,
    "updatedAt": 1606928037660,
    "updatedBy": "API - API-DOC",
    "phones": [],
    "entityStatus": "VALIDATION_PENDING",
    "currentlyOverriden": false,
    "rolesPreview": [],
    "contactListsPreview": [],
    "phone": null,
    "_links": {
        "self": {
            "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f0176245ff71e0005"
        },
        "contact": {
            "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f0176245ff71e0005"
        },
        "roles": {
            "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f0176245ff71e0005/roles"
        },
        "contactLists": {
            "href": "http://talos-app.io/api/contact-service/contacts/8a81a1ee76240e8f0176245ff71e0005/contactLists"
        }
    }
}
```

{% endtab %}
{% endtabs %}

## delete a contact&#x20;

<mark style="color:red;">`DELETE`</mark> `https://talos-app.io/api/contact-service/contacts/{id}`

Use this endpoint to delete a contact from your contact list.

#### Path Parameters

| Name | Type   | Description              |
| ---- | ------ | ------------------------ |
| id   | string | The relevant contact ID. |

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## update a contact

<mark style="color:purple;">`PATCH`</mark> `https://talos-app.io/api/contact-service/contacts/{id}`

Use this endpoint to create a new contact.

#### Path Parameters

| Name | Type   | Description              |
| ---- | ------ | ------------------------ |
| id   | string | The relevant contact ID. |

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}