# Kustomer

### Overview

This integration imports conversations from your **Kustomer** account into Birdie\
so that you can analyze support and messaging interactions alongside other feedback sources.

Below are key details about what we need to set up the integration and how\
conversations and data are imported.

### Requirements

For Birdie to authenticate with the **Kustomer API** and import data, you'll need to generate an API Key (an auto-generated token), used to authenticate API requests. Provide the Birdie team with the following:

* Subdomain of your Kustomer account (e.g.: subdomain.kustomerapp.com)
* API Key (with read permissions)

If identification of agents and customers is necessary, Birdie can request additional permissions, see all permissions below.

#### API Key Permissions

<table><thead><tr><th width="314">Role</th><th width="116" align="center">Status</th><th>Description</th></tr></thead><tbody><tr><td>org.permission.conversation.read</td><td align="center"><strong>Required</strong></td><td>View conversations</td></tr><tr><td>org.permission.message.read</td><td align="center"><strong>Required</strong></td><td>View messages</td></tr><tr><td>org.permission.tag.read</td><td align="center"><strong>Required</strong></td><td>View tags</td></tr><tr><td>org.permission.metadata.read</td><td align="center"><strong>Required</strong></td><td>View records metadata<br>(custom fields / KObjects)</td></tr><tr><td>org.permission.search.create<br>org.permission.search.update<br>org.permission.search_global.create<br>org.permission.search_preview.create</td><td align="center"><strong>Required</strong></td><td>Search records</td></tr><tr><td>org.permission.customer.read</td><td align="center">Optional</td><td>View customers</td></tr><tr><td>org.permission.team.read<br>org.permission.user.read</td><td align="center">Optional</td><td>View user (agents) and teams</td></tr><tr><td>org.permission.note.read</td><td align="center">Optional</td><td>View conversation internal notes</td></tr><tr><td>org.permission.satisfaction.read</td><td align="center">Optional</td><td>View conversation satisfaction</td></tr><tr><td>org.permission.brand.read</td><td align="center">Optional</td><td>View brands from organization</td></tr></tbody></table>

### Setup in the third‑party tool

{% stepper %}
{% step %}

#### Accessing your Kustomer account

* Log in to your Kustomer account and go to **Settings**.
* Select **Security**.
* Click **API Keys**.

![](https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2FH3kDafqp0fG9bD2yRamR%2Fsettings.png?alt=media\&token=186a3bd8-bd94-4cb2-90d6-3226037168f1)
{% endstep %}

{% step %}

#### Generate an API Key

* Enter a descriptive **Name** for your API key (e.g.: Birdie Integration).
* Set **Expires (in days)** to "No Expiration".
* Set **Roles** permissions, this field specifies what access will the generated key have.
* Leave **CIDR IP Restriction** empty or for additional security, we recommend setting the restriction to allow only Birdie's infrastructure to use this key. \
  **Contact the Birdie team to obtain the IP ranges to whitelist.**
* Click **Create**.
* Copy and save the generated API Key. **It will only be shown once**.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2FB9Z2e73GRvj4luRCQSVx%2Fmanage-api-keys.gif?alt=media&#x26;token=484fb205-194d-4410-bc29-afa67c9cfaa2" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Permissions cannot be changed once the key is created.
{% endhint %}
{% endstep %}
{% endstepper %}

### Delete an API Key

If you suspect a token has been compromised, delete it immediately. Deleting a token will deactivate it permanently.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2FwcHwQ5Wz7ASAzHPfBoaO%2Fdelete-apikey.png?alt=media&#x26;token=04cb2ca5-30e1-45be-96ea-a8c319f70665" alt=""><figcaption></figcaption></figure>

When using API keys, keep the following in mind:

* API keys cannot be edited, only deleted.
* A deleted token cannot be used to make requests to and from **Kustomer**.
* When selecting roles, be mindful of what permissions are necessary for this token. For example, if a service only requires READ access, you can create a token with just **org.permission.\<service>.read**.
* Provide a helpful naming to your API Key since your team may use dozens of tokens along the way.

### Connect to Birdie

Once you have generated an API Key, [share securely](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration) with the Birdie team:

* Kustomer subdomain
* API Key

The Birdie team will configure the connector and confirm once the integration is active.

### Data in scope

#### Additional records for enhanced segmentation

Birdie supports importing additional records associated with conversations to improve segmentation, such as: customers, teams, users (agents), internal notes, and satisfaction ratings.

* The **team** and **user** permissions can provide more context for conversations, including which team was responsible.
* The **satisfaction** permission allows the ingestion of **CSAT (Customer Satisfaction)** data, enabling its use for customer experience analysis, and performance reporting across teams and agents.
* The **note** permission allows the ingestion of internal notes added by agents to conversations, providing additional internal context that can help enrich conversation analysis by capturing observations, troubleshooting details, or internal communication.

{% hint style="info" %}
Before setting up the integration, some [permissions](#api-key-permissions) need to be enabled depending on your integration requirements.
{% endhint %}

#### Custom fields

If your Kustomer setup includes custom fields (KObjects), these fields can be mapped directly into Birdie, preserving your unique data structure. Kustomer custom fields support a variety of data types and allow you to store additional data within conversations beyond standard fields (see Kustomer's KObjects documentation: [Data model overview](https://help.kustomer.com/en_us/data-model-overview-SyIS1S3zM)).

Once imported, Kustomer custom fields appear as Birdie custom fields, maintaining consistency across all platforms and enabling enhanced segmentation, filtering, and custom workflows in Birdie.

### References

* [API keys](https://help.kustomer.com/api-keys-SJs5YTIWX)
  * [Common API roles](https://help.kustomer.com/api-keys-SJs5YTIWX#common)
* [Data model overview](https://help.kustomer.com/en_us/data-model-overview-SyIS1S3zM)
* [Authentication and API keys](https://developer.kustomer.com/kustomer-api-docs/reference/authentication)