# Track.co

### Overview

With the Track.co connector, Birdie can import survey responses (NPS and CSAT) directly from [Track.co](https://track.co/), enabling seamless integration between the Birdie platform and your customer survey interactions.

Track.co offers two APIs that Birdie supports:

* **CXM API** — imports survey interactions (recommended for most use cases)
* **NPS API** — imports NPS campaign answers (legacy)

#### Requirements

To connect Track.co to Birdie, you need:

* An active Track.co account with access to the **Apps** area.
* Permission to install the **API v2** app and create or access an API token.
* For the CXM API: your Organization ID and (optionally) survey public hashes.
* For the NPS API: (optionally) campaign codes.

For details on how to obtain the API token and Organization ID, check the [Track.co API docs](https://documenter.getpostman.com/view/14932352/Tz5v1upm#2fd4ac07-f9d0-4ad4-8987-14041be124ba), under the **"AUTHENTICATION TOKEN AND ORGANIZATION IDENTIFIER FOR INTEGRATION WITH THE TRACK CXM API"** section.

#### Setup in Track.co

{% stepper %}
{% step %}
**Access Apps**

Once you're logged in, access your User menu and choose the option Apps.

![User menu → Apps](https://tawk.link/685001d2e1d1cb19110409b6/kb/attachments/UkIC8x3wMO.png)
{% endstep %}

{% step %}
**Install API v2**

In the Apps page, click on "Instalar API v2".

![Install API v2](https://tawk.link/685001d2e1d1cb19110409b6/kb/attachments/r42rLW_IWf.png)
{% endstep %}

{% step %}
**Create or Select a Token**

Select an existing token or create a new one. Birdie will use this token value as the Access token when setting up your Track connector.

![Select or create token](https://tawk.link/685001d2e1d1cb19110409b6/kb/attachments/Nu2OMBiSRc.png)
{% endstep %}
{% endstepper %}

#### Integration

Through this integration, you can import both NPS and CSAT data. To ensure the integration works correctly, a survey must include exactly one question of either the NPS or CSAT type. Besides that, you can include any number of questions of other types.

When setting up a survey:

* For importing NPS, the survey must have one question with type `nps` or `nps_relational`.
* For importing CSAT, the survey must have one question with type `csat`.

You can also import CSAT/NPS responses as transactional responses, which are associated with a Ticket (e.g., from Zendesk) by specifying a Ticket ID metadata field name.

For each answer related to CSAT or NPS, Birdie extracts the main fields for that interaction — such as rating, author name, posted date, answers to all questions, and if present, the associated ticket — then imports the feedback into Birdie.

#### Share Connection Details with Birdie

To configure the integration, securely provide Birdie with the following information.

**For CXM API (recommended):**

```json
{
  "connection_details": {
    "token": "your-track-api-token",
    "track_api": "cxm"
  },
  "data_source": {
    "organization_id": "your-organization-uuid",
    "surveys": ["survey-public-hash-1", "survey-public-hash-2"],
    "time_zone": "America/Sao_Paulo"
  },
  "metadata": {
    "transaction_id_field": "ticket_id",
    "transaction_platform": "Zendesk"
  }
}
```

**For NPS API:**

```json
{
  "connection_details": {
    "token": "your-track-api-token",
    "track_api": "nps"
  },
  "data_source": {
    "campaigns": [123, 456]
  }
}
```

| Section              | Field                  | Required | Description                                                                                |
| -------------------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `connection_details` | `token`                | Yes      | Track.co API authentication token.                                                         |
| `connection_details` | `track_api`            | No       | Which Track API to use: `cxm` (default) or `nps`.                                          |
| `data_source`        | `organization_id`      | CXM      | The unique identifier of the organization to import data from.                             |
| `data_source`        | `surveys`              | No       | List of survey public hashes to import. If empty, imports from all available surveys.      |
| `data_source`        | `time_zone`            | No       | Time zone for parsing dates. Defaults to `UTC`. Use IANA format, e.g. `America/Sao_Paulo`. |
| `data_source`        | `campaigns`            | No       | List of NPS campaign codes. If empty, imports from all available campaigns.                |
| `metadata`           | `transaction_id_field` | No       | Name of the metadata field in CXM that contains the external ticket ID.                    |
| `metadata`           | `transaction_platform` | No       | Name of the external ticketing platform (e.g. `Zendesk`) associated with the ticket ID.    |

[Share credentials securely](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration) with the Birdie team. Never send credentials via email or unencrypted channels.

#### Example Feedback

Consider a survey with 3 questions:

* "How satisfied are you with Birdie?" (`csat` type)
* "What other features would you like to see?" (`open` type)
* "How would you rate Birdie's usefulness?" (`ces2` type)

Example of imported feedback:

```json
{
  "kind": "csat",
  "rating": "5",
  "title": "[CSAT] Birdie",
  "posted_at": "2024-07-01T10:30:00Z",
  "additional_fields": {
    "How satisfied are you with Birdie?": 5,
    "What other features would you like to see?": "Better reporting dashboards",
    "How would you rate Birdie's usefulness?": 4
  }
}
```

If the survey is configured as a follow-up to a ticket (tNPS or tCSAT), this information will be included in the ticket, reflecting the client's final thoughts on their experience.

#### Custom Fields

All additional data provided by Track's API that doesn't fit into the main schema can be imported by Birdie as "additional fields". Additional fields can be configured as custom fields in the Birdie App, enabling text search and filtering.

#### References

* [Track.co](https://track.co/)
* [Track.co API Documentation](https://documenter.getpostman.com/view/14932352/Tz5v1upm)
* [Securely Sharing Credentials](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration)


---

# 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://ask.birdie.ai/integrations-and-data-ingestion/how-to-integrate-with/track.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.