> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/integrations-and-data-ingestion/how-to-integrate-with/asknicely.md).

# AskNicely

### Integration

This integration imports AskNicely survey responses into Birdie so they can be analyzed alongside other feedback sources. The connector currently supports **NPS** and **CSAT** responses and maps them into Birdie Feedback.

### Requirements

To connect AskNicely to Birdie, you need:

* **AskNicely base URL**: the URL you use to access AskNicely in your browser (must include `https://`).
* **AskNicely API key**: AskNicely authenticates API requests via a per-user API key.

Recommendation: create a dedicated AskNicely user for Birdie and use that user’s API key.

### Setup in AskNicely

#### 1) Find your AskNicely base URL

1. Log in to AskNicely.
2. Copy the full URL from your browser address bar.
3. Use that as the **base URL** in Birdie (including `https://`).

#### 2) Generate an API key

AskNicely API requests are authenticated using the `X-apikey` header.

1. Log in to AskNicely.
2. Go to **Settings**.
3. Open **Users**.
4. Select the user that will be used for the Birdie integration (or create a dedicated user).
5. Copy the API key for that user.

References:

* <https://demo.asknice.ly/help/apidocs/>

### Connect to Birdie

Provide the following to Birdie (share credentials via a secure, one-time channel):

* `domain`: AskNicely base URL (must include scheme, e.g. `https://…`)
* `api_key`: AskNicely API key

Birdie manages the import window internally (start/end timestamps) as part of the scheduled sync.

### Data in scope

#### Entities imported

* **Survey responses** (NPS and CSAT)

#### Endpoint and authentication

Birdie fetches responses from AskNicely using:

* **Method**: `GET`
* **Path**: `/api/v1/responses/desc/100/{page}/0/json`
* **Query**: `realdates=yes`
* **Auth header**: `X-apikey: <api_key>`
* **Accept**: `application/json`

#### Pagination

* Page-based pagination (`{page}` starts at 1).
* Fixed page size of **100** responses per page.
* Pagination stops when a page returns fewer than 100 items.

#### Incremental/time window behavior

* Birdie filters responses by the AskNicely `responded` timestamp to match the scheduled start/end time window.
* Birdie applies an **overlap window** by subtracting `overlap_seconds` from the requested start time to avoid missing late-arriving responses. Responses are deduplicated using `response_id`.

#### Primary keys and idempotency

* Birdie uses AskNicely `response_id` as the stable identifier for each feedback.
* Birdie’s `feedback_id` is derived from `response_id` to keep updates consistent across reprocessing.

#### Mapping

AskNicely fields are mapped as follows:

* `question_type` → feedback kind (`nps` / `csat`)
* `answer` → rating
* `comment` → text
* `survey_template` → title
* `responded` → posted\_at

### References

* AskNicely API docs: <https://demo.asknice.ly/help/apidocs/>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/asknicely.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.