# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sitasys-ag.gitbook.io/evalink-talos/management-api/manage-contacts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.