# Integration Information

## Authenticating

To begin, you will need to authenticate to the Polarity Server to obtain a reusable bearer token that will be used with subsequent authenticated requests.

See [Authentication](/polarity-admin-guide-version-5/NgjzS0G79DnLnaNepozV/guides/authentication.md) for information on how to authenticate to the Polarity Platform and acquire an authentication token.  The authentication token will be used in all the requests outlined below and is referenced in examples as `<AUTH_TOKEN>`.

## Get Integrations

You can retrieve information about integrations by using the `GET /api/integrations` endpoint.  This endpoint will return information about integrations installed on your server to include running status, integration option values, and references to any integration errors.

{% hint style="info" %}
Be sure to include the `Content-Type` header with a value of `application/vnd.api+json`
{% endhint %}

### Examples

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

```bash
curl -v -X GET \
https://<POLARITY_HOSTNAME>/api/integrations \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'
```

{% endtab %}

{% tab title="python" %}

```python
import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'

    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations('my-auth-token', 'https://my-server')    
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Replace `<POLARITY_HOSTNAME>` with the hostname of your Polarity server and `<AUTH_TOKEN>` with the value of your bearer token.
{% endhint %}

### Paging

The default page size for the endpoint is 100 which means if you have more than 100 installed integrations you will need to increase the page size or page through the results using the `page[size]` and `page[number]` query parameters.  The parameter `page[size]` tells the endpoint the maximum number of results to return and the parameter `page[number]` tells the endpoint which page of results to return.

{% tabs %}
{% tab title="curl" %}
{% code title="Paging" %}

```
curl -v -X GET -G \
'https://<POLARITY_HOSTNAME>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d page[size]=200 \
-d page[number]=1
```

{% endcode %}
{% endtab %}

{% tab title="python" %}
{% code title="Paging" %}

```python
import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'

    params = {
        'page[size]': 200,
        'page[number]': 1
    }
    
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations('my-auth-token', 'https://my-server')    
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Filtering

#### Integration Status

You can return only integrations that are running by using the query parameter  `filter[integration.status]=running`&#x20;

{% tabs %}
{% tab title="curl" %}
{% code title="Filtering Status" %}

```
curl -v -X GET -G \
'https://<POLARITY_HOSTNAME>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d filter[integration.status]=running
```

{% endcode %}
{% endtab %}

{% tab title="python" %}
{% code title="Filtering Status" %}

```python
import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'

    params = {
        'filter[integration.status]': 'running'
    }
    
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations('my-auth-token', 'https://my-server')  
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### Integration Errors

You can return only integrations with errors using the `filter[integration.integration-errors]=true` query parameter.

{% tabs %}
{% tab title="curl" %}
{% code title="Filtering Errors" %}

```bash
curl -v -X GET -G \
'https://<POLARITY_HOSTNAME>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d filter[integration.integration-errors]=true
```

{% endcode %}
{% endtab %}

{% tab title="python" %}
{% code title="Filtering Errors" %}

```python
import requests
import json

def get_integrations_with_errors(token, host):
    url = f'{host}/api/integrations'

    params = {
        'filter[integration.integration-errors]': true
    }
    
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations_with_errors('my-auth-token', 'https://my-server')  
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Return Payload Format

The endpoint will return a JSON payload with a list of integration models as part of a top level `data` key.  In addition, there will be a top level `meta` key which contains paging information including the `page.total` attribute which indicates the total number of integrations that could be returned by the endpoint given the applied filtering. &#x20;

{% code title="Return Data Example" %}

```json
{
  "data": [
     // one or more integration models
   ],
   "meta": {
     "page": {
       "number": 1, // current page number
       "size": 100, // number of integrations returned per page
       "total": 135 // total number of integrations matching the filter criteria
     }
   }
}  
```

{% endcode %}

Each integration model contained within `data`  will have the following structure:

{% code title="Integration Model" %}

```json
{
  "attributes": {
    // integration model attributes
  },
  "id": "<INTEGRATION_ID>",
  "links": {
    "self": "/api/integrations/<INTEGRATION_ID>"
  },
  "relationships": {
    "integration-errors": {
      "data": [
        // list of integration errors (empty if there are no errors
       ]
      "links": {
        "self": "/api/integration-errors?filter[integration.id]=<INTEGRATION_ID>"
      }
    },
    "integration-options": {
      "data": [
        // list of integration options
      ],
      "links": {
        "self": "/api/integration-options?filter[integration.id]=<INTEGRATION_ID>
      }
  },
  "type": "integrations"
}
```

{% endcode %}

## Integration Attributes

To view a full list of integration attributes returned by the fetch integration endpoints see the Integration Attributes page.

{% content-ref url="/pages/19cMFJbCsLGQr3p6fceY" %}
[Integration Attributes](/polarity-admin-guide-version-5/NgjzS0G79DnLnaNepozV/rest-api/integration-information/integration-attributes.md)
{% endcontent-ref %}

## Get Integration Errors

You can fetch all integration errors using the `GET /api/integrations/errors` endpoint.  Only integration managers and Polarity admins are able to view errors for integrations.

### Examples

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

```bash
curl -v -X GET \
https://<POLARITY_HOSTNAME>/api/integrations/errors \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'
```

{% endtab %}

{% tab title="python" %}

```python
import requests
import json

def get_integration_errors(token, host):
    url = f'{host}/api/integrations/errors'

    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers)
    response.raise_for_status()

    return response.json()
    
integration_errors = get_integration_errors('my-auth-token', 'https://my-server')    
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
This endpoint does not support paging and will return all available errors.&#x20;
{% endhint %}

### Return Payload Format

The errors endpoint will return an array of error models within a top level `data` attribute.

```json
{
  "data": [
    // Zero or more error models
  ],
  "jsonapi": {
    "version": "1.0"
  }
}  
```

The error model has the following format:

{% code title="Error Model" %}

```json
{
  "attributes": {
    // error attributes
  },
  "id": "<ERROR_ID>",
  "links": {
    "self": "/api/integration/<INTEGRATION_ID>/errors/<ERROR_ID>"
  },
  "relationships": {
    "integration": {
      "data": {
        "id": "<INTEGRATION_ID>"
        "type": "integrations"
      }
    }
  },
  "type": "integration-errors"
}
```

{% endcode %}

### Error Attributes

Each error model has fixed attributes common to all errors and then also includes a `meta` attribute which contains integration specific error information.&#x20;

<table><thead><tr><th width="164">attribute</th><th width="96">type</th><th>description</th></tr></thead><tbody><tr><td>code</td><td>string</td><td>A short error description</td></tr><tr><td>title</td><td>string</td><td>A title for the error</td></tr><tr><td>detail</td><td>string</td><td>A more detailed description of the error</td></tr><tr><td>error-count</td><td>number</td><td>The number of times the specific error has occurred. </td></tr><tr><td>integration-id</td><td>string</td><td>The id of the integration that returned the error</td></tr><tr><td>meta</td><td>object</td><td>An object containing integration specific error details.  This <code>meta</code> property typically contains detailed information to include stack traces and integration specific REST API error information including HTTP status codes returned by the REST API the integration is accessing.</td></tr><tr><td>meta.affected_users</td><td>object</td><td>The <code>meta.affected_users</code> attribute contains one or more user objects.  The user objects include a user <code>id</code> and <code>username</code> attribute for Polarity users that triggered/caused the specific error.  This attribute, when available, can be used to determine which users are affected by a specific error. </td></tr><tr><td>occurred-on</td><td>string</td><td>An ISO 8601 formatted date-time string detailing the the last time the error occurred (e.g., <code>2024-04-08 14:20:07.834943Z</code>)</td></tr><tr><td>status</td><td>number</td><td>An HTTP status code associated with the error</td></tr></tbody></table>


---

# 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://docs.polarity.io/polarity-admin-guide-version-5/NgjzS0G79DnLnaNepozV/rest-api/integration-information.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.