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