### API Quick Start and Authentication

Source: https://asknicely.asknice.ly/help/apidocs/auth

Information on how to get started with the AskNicely API, including obtaining API keys and authenticating requests.

```APIDOC
## API Quick Start

Upon signing up you will be provided with everything you need to get started using the AskNicely API, including an AskNicely subdomain (e.g. demo.asknice.ly) and API key.
The AskNicely API is a _RESTful_ API, returning JSON responses.

### API Keys

* AskNicely only requires a single API key `N/A` to authenticate your request.
* Every AskNicely user is assigned their own API key, if you want to isolate API requests, create a new user.

### Authenticating

* Include your API key as a header `X-apikey: N/A` to authenticate your request.

### Contact Rules (Found on the Send page)

* The API will only obey the first contact rule found on the send page
  * i.e. _"Wait at least X days before contacting a customer again"_
* The API **ignores** the second rule
  * i.e. _"For newly added contacts, wait X days…"_

### Adding your own Custom Data

You can add your own custom data fields to every contact, by simply sending along your desired field name, in _snake_case_ suffixed with an _`_c`_.
For example, if you would like your contacts to show a custom data field for their "Branch Location", please send along a parameter of `branch_location_c: Portland`
```

--------------------------------

### Get Last 5 Responses with Filters (cURL)

Source: https://asknicely.asknice.ly/help/apidocs/responses

Retrieves the last 5 response results from AskNicely in JSON format. This example demonstrates the use of `filters` and `values` parameters to narrow down the results. Ensure you replace 'DEMO.asknice.ly' with your actual tenant URL and provide a valid API key. The `--location` flag is used to follow redirects.

```curl
curl -X GET \
    "https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json?filters[]=city_c&filters[]=country_c&values[]=Abbotsford&values[]=Canada" \
    --header "X-apikey: " \
    --location
```

--------------------------------

### Get Last 5 Published Testimonials in JSON

Source: https://asknicely.asknice.ly/help/apidocs/responses

Fetches the last 5 published testimonials from AskNicely in JSON format. This allows access to approved feedback. Authentication with an API key is necessary.

```shell
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json/published \
    --header "X-apikey: " \
    --location
```

--------------------------------

### API Authentication Example

Source: https://asknicely.asknice.ly/help/apidocs/auth

To authenticate your API requests, include your unique AskNicely API key in the 'X-apikey' header. This ensures your requests are properly identified and authorized.

```http
GET /contacts HTTP/1.1
Host: demo.asknice.ly
X-apikey: YOUR_API_KEY

```

--------------------------------

### Get a Contact

Source: https://asknicely.asknice.ly/help/apidocs/getcontact

Retrieves the details of a specific contact by searching via email or other customer properties.

```APIDOC
## GET /api/v1/contact/get/{search}/{key}

### Description
Get the details of a particular contact.

### Method
GET

### Endpoint
https://DEMO.asknice.ly/api/v1/contact/get/`search`/`key`

### Parameters
#### Path Parameters
- **search** (string) - Required - URL-encoded value to search, eg email address of a contact
- **key** (string) - Required - By default this is email, but you could search by any value eg a customer property set via the API

### Request Example
Search by email
```bash
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/contact/get/schrodinger%40example.com/email
```

Search by id
```bash
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/contact/get/your_id/id
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the contact details if successful.
  - **id** (string) - The unique identifier for the contact.
  - **lastemailed** (string) - Timestamp of the last email sent.
  - **active** (string) - Indicates if the contact is active ('1') or not ('0').
  - **created** (string) - Timestamp when the contact was created.
  - **scheduled** (string) - Indicates if the contact is scheduled.
  - **name** (string) - The name of the contact.
  - **email** (string) - The email address of the contact.
  - **segment** (string) - The segment the contact belongs to.
  - **importedattime** (string) - Timestamp when the contact was imported.
  - **source** (string) - The source of the contact data.
  - **intercomid** (string) - The Intercom ID if applicable.
  - **unsubscribetime** (string|null) - Timestamp when the contact unsubscribed, or null.

#### Response Example
```json
{
   "success":true,
   "data":{
      "id":"15816",
      "lastemailed":"1452219376",
      "active":"1",
      "created":"1418350105",
      "scheduled":"0",
      "name":"John Ballinger",
      "email":"john@asknice.ly",
      "segment":"VIP Customer",
      "importedattime":"1450653162",
      "source":"intercom",
      "intercomid":"548a4e19bcdac3592e0019b7",
      "unsubscribetime":null
   }
}
```
```

--------------------------------

### Generating An Email Hash

Source: https://asknicely.asknice.ly/help/apidocs/inapp

This section provides examples for generating a secure email hash using a provided secret key. This hash is crucial for authenticating users and ensuring the security of the in-app survey process.

```APIDOC
## Generating An Email Hash

This endpoint demonstrates how to generate a secure email hash using a secret key. This hash is used in the in-app survey flow to authenticate users.

### Description

Generate a secure `email_hash` for a given user's email address using the provided `secret_key`.

### Method

(Not applicable for hash generation examples, as these are client-side implementations)

### Endpoint

(Not applicable for hash generation examples)

### Parameters

(Not applicable for hash generation examples)

### Request Example

**PHP Example:**
```php
<?php echo hash_hmac('sha256', $user->email, 'secret_key'); ?>
```

**Ruby Example:**
```ruby
<%= OpenSSL::HMAC.hexdigest('sha256', 'secret_key', current_user.email) %>
```

**Python Example:**
```python
{{ hmac.new('secret_key', request.user.email, digestmod=hashlib.sha256).hexdigest() }}
```

**Java Example:**
```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class ApiSecurityExample {
    private final static char[] hexArray = "0123456789abcdef".toCharArray();

    private static String bytesToHex(byte[] bytes) {
        char[] hexChars = new char[bytes.length * 2];
        for ( int j = 0; j < bytes.length; j++ ) {
            int v = bytes[j] & 0xFF;
            hexChars[j * 2] = hexArray[v >>> 4];
            hexChars[j * 2 + 1] = hexArray[v & 0x0F];
        }
        return new String(hexChars);
    }

    public static void main(String[] args) {
        try {
            String key = "secret_key";
            String message = "user@example.com";

            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);

            String hash = bytesToHex(sha256_HMAC.doFinal(message.getBytes()));
            System.out.println(hash);
        } catch (Exception e) {
            System.out.println("Error");
        }
    }
}
```

**C# Example:**
```csharp
using System.Security.Cryptography;

public class ApiSecurityExample
{
    private static string CreateHash(string message, string secret)
    {
        secret = secret ?? "";
        var encoding = new System.Text.ASCIIEncoding();
        byte[] keyByte = encoding.GetBytes(secret);
        byte[] messageBytes = encoding.GetBytes(message);
        using (var hmacsha256 = new HMACSHA256(keyByte))
        {
            byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
            return System.BitConverter.ToString(hashmessage).Replace("-", string.Empty).ToLower();
        }
    }

    public static void Main(string[] args)
    {
        string key = "secret_key";
        string message = "user@example.com";
        System.Console.WriteLine(ApiSecurityExample.CreateHash(message, key));
    }
}
```

### Response

(Not applicable for hash generation examples)
```

--------------------------------

### Get NPS Results API Request (cURL)

Source: https://asknicely.asknice.ly/help/apidocs/getnps

This snippet demonstrates how to retrieve Net Promoter Score (NPS) results using a GET request to the AskNicely API. It shows the basic endpoint structure and how to specify the number of days for the calculation. An API key is required for authentication.

```bash
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/getnps/30
```

--------------------------------

### Get Responses API

Source: https://asknicely.asknice.ly/help/apidocs/responses

Retrieve detailed responses for your surveys. Supports pagination, filtering, and sorting. Handles large datasets by potentially redirecting to S3.

```APIDOC
## GET /api/v1/responses/{sort_direction}/{pagesize}/{pagenumber}/{since_time}/{format}/{filter}/{sort_by}/{end_time}

### Description
Use the Get Responses API to retrieve the detailed response each of your contacts has provided for your survey. You can request up to 50,000 responses per call and perform multiple requests to retrieve all responses to update your contact database. If you are using a combination of metrics in the leading question of your surveys, the question_type will indicate if the response was to a NPS, CSAT or 5STAR survey.
API calls may be redirected to a temporary file stored on S3 depending on the number of responses you request. Your application will need to be able to follow redirects.

### Method
GET

### Endpoint
`https://DEMO.asknice.ly/api/v1/responses/{sort_direction}/{pagesize}/{pagenumber}/{since_time}/{format}/{filter}/{sort_by}/{end_time}`

### Query Parameters
- **sort_direction** (string) - Optional - Default is `asc` (ascending). Example: `desc`
- **pagesize** (integer) - Required - Default is 50,000 per request; maximum is 50,000 per request. Example: `50`
- **pagenumber** (integer) - Required - Current page starting at 1, being the first page. Example: `1`
- **since_time** (unix timestamp) - Required - Pass in a unix timestamp to set the 'after date' from which you want to get all responses for. Example: `0`
- **format** (string) - Optional - Leave blank or set to `json` to get data in json format. Use `csv` to get data in csv format. Example: `json`
- **filter** (string) - Optional - Leave blank or `answered` for all survey responses. `raw` for all surveys sent, this includes surveys sent and have not been responded to. `published` for only customer testimonials. Example: `answered`
- **sort_by** (string) - Optional - Leave blank or `sent` to sort by survey sent date. `responded` to sort by survey response date. Example: `responded`
- **end_time** (unix timestamp) - Optional - Leave blank to default the date to now or pass in a unix timestamp to set the 'before date' up to which you want to get all responses for. Example: `1642981569`
- **includestatustime** (boolean) - Optional - Include this optional query parameter to also retrieve the unix timestamp based `case_closed_time` for your responses. Example: `yes`
- **filters[]** (string) - Optional - Use to filter on custom fields. Example: `custom_field_c`
- **values[]** (string) - Optional - The value to filter the corresponding custom field by. Example: `Custom%20Value`

**Note**: The number of `filters[]` and `values[]` parameters must be the same, and they need to match in order. Incorrect matches will result in no data being returned.

### Request Example
```bash
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json \
    --header "X-apikey: " \
    --location
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **total** (string) - The total number of responses available.
- **totalpages** (string) - The total number of pages for the current query.
- **pagenumber** (string) - The current page number.
- **pagesize** (string) - The number of responses per page.
- **since_time** (string) - The timestamp used for filtering responses (start date).
- **end_time** (string) - The timestamp indicating the end date for filtering responses.
- **data** (array) - An array of response objects.
  - **response_id** (string) - Unique identifier for the response.
  - **person_id** (string) - Identifier for the person who gave the response.
  - **contact_id** (string) - Identifier for the contact associated with the response.
  - **name** (string) - Name of the contact.
  - **email** (string) - Email address of the contact.
  - **answer** (string) - The response given by the contact.
  - **answerlabel** (string) - The label corresponding to the answer.
  - **data** (any) - Additional data related to the response (can be null).
  - **comment** (string) - Any comments provided with the response.
  - **note** (any) - Internal notes (can be null).
  - **status** (string) - Status of the response.
  - **dontcontact** (any) - Flag indicating if the contact should not be contacted (can be null).
  - **sent** (string) - Unix timestamp when the survey was sent.
  - **opened** (string) - Unix timestamp when the survey was opened.
  - **responded** (string) - Unix timestamp when the survey was responded to.
  - **lastemailed** (string) - Unix timestamp when the last email was sent.
  - **created** (string) - Unix timestamp when the response record was created.
  - **segment** (any) - Segment information (can be null).
  - **question_type** (string) - Type of question asked (e.g., 'nps', 'csat', '5star').
  - **published** (string) - Indicates if the response is published.
  - **publishedname** (string) - Name associated with published responses.

#### Response Example
```json
{
    "success": true,
    "total": "10395",
    "totalpages": "2079",
    "pagenumber": "1",
    "pagesize": "5",
    "since_time": "0",
    "end_time": "1642981569",
    "data": [
        {
            "response_id": "54120",
            "person_id": "54121",
            "contact_id": "54121",
            "name": "Aiman Shakeel",
            "email": "3d2c555c.39829842@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "",
            "dontcontact": null,
            "sent": "1614192119",
            "opened": "1614192119",
            "responded": "1614192119",
            "lastemailed": "1614192119",
            "created": "1614192119",
            "segment": null,
            "question_type": "nps",
            "published": "",
            "publishedname": "",
            ...
        },
        ...
    ]
}
```

### Limits
The maximum results per request is 50,000.
```

--------------------------------

### Get NPS Results with cURL

Source: https://asknicely.asknice.ly/help/apidocs/index

This snippet demonstrates how to retrieve NPS results for a specified number of days using a cURL request. It shows the basic structure of the GET request and the expected JSON response.

```bash
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/getnps/30
```

```json
{"NPS":"64.5"}
```

--------------------------------

### Get Last 5 Responses in JSON Format

Source: https://asknicely.asknice.ly/help/apidocs/responses

Fetches the last 5 response results from AskNicely in JSON format. This includes status and case closed time. Requires an API key for authentication.

```shell
curl -X GET \
    "https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json?includestatustime=yes" \
    --header "X-apikey: " \
    --location
```

--------------------------------

### Get Last 5 Published Testimonials

Source: https://asknicely.asknice.ly/help/apidocs/responses

Retrieves the last 5 published testimonials from AskNicely in JSON format.

```APIDOC
## GET /api/v1/responses/desc/5/1/0/json/published

### Description
Retrieves the last 5 published testimonials in JSON format.

### Method
GET

### Endpoint
`https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json/published`

### Parameters
None

### Request Example
```bash
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json/published \
    --header "X-apikey: " \
    --location
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **total** (string) - Total number of testimonials.
- **totalpages** (string) - Total number of pages.
- **pagenumber** (string) - Current page number.
- **pagesize** (string) - Number of testimonials per page.
- **since_time** (string) - Timestamp for filtering results.
- **end_time** (string) - Timestamp for filtering results.
- **data** (array) - Array of testimonial objects, each containing details like `response_id`, `name`, `email`, `comment`, `published`, and `publishedname`.

#### Response Example
```json
{
    "success": true,
    "total": "2",
    "totalpages": "1",
    "pagenumber": "1",
    "pagesize": "5",
    "since_time": "0",
    "end_time": "1625783435",
    "data": [
        {
            "response_id": "455",
            "person_id": "3",
            "contact_id": "3",
            "name": "John Doe",
            "email": "johndoe@example.com",
            "answer": "10",
            "answerlabel": "10",
            "comment": "I love this gym!",
            "sent": "1619849044",
            "created": "1619849044",
            "question_type": "nps",
            "published": "approved",
            "publishedname": "John Doe"
        }
    ]
}
```
```

--------------------------------

### Get Survey Responses (JSON) - cURL

Source: https://asknicely.asknice.ly/help/apidocs/responses

This example demonstrates how to retrieve the last 5 survey response results from AskNicely in JSON format using a cURL request. It specifies the API endpoint, desired page size, page number, and a time filter. The response includes pagination details and an array of response objects.

```curl
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json \
    --header "X-apikey: " \
    --location
```

--------------------------------

### Bulk Add Contacts with Custom Values (cURL)

Source: https://asknicely.asknice.ly/help/apidocs/bulkasync

This cURL example shows how to add contacts with custom data fields. It illustrates sending additional key-value pairs within each contact object to store specific information.

```cURL
curl -X POST \
    https://DEMO.asknice.ly/api/v1/contacts/add \
    --header "X-apikey: " \
    --data-binary @- << JSON
{
    "contacts": [
        {
            "name": "Erwin Schrodinger",
            "email": "schrodinger@example.com",
            "custom_field_c": "Custom Value"
        },
        {
            "name": "John Smith",
            "email": "john@example.com",
            "another_custom_field_c": "Another Custom Value"
        }
    ]
}
JSON
```

--------------------------------

### Bulk Add Contacts (cURL)

Source: https://asknicely.asknice.ly/help/apidocs/bulkasync

This example demonstrates how to use cURL to send a POST request to the AskNicely API to add multiple contacts. The request includes a JSON payload with a list of contact objects, each requiring an email address.

```cURL
curl -X \
    POST https://DEMO.asknice.ly/api/v1/contacts/add \
    --header "X-apikey: " \
    --data-binary @- << JSON
{
    "contacts": [
        {
            "name": "Erwin Schrodinger",
            "email": "schrodinger@example.com"
        },
        {
            "name": "John Smith",
            "email": "john@example.com"
        }
    ]
}
JSON
```

--------------------------------

### Get Last 3 Responses (CSV)

Source: https://asknicely.asknice.ly/help/apidocs/responses

Retrieves the last 3 response results from AskNicely in CSV format.

```APIDOC
## GET /api/v1/responses/desc/3/1/0/csv

### Description
Retrieves the last 3 response results in CSV format.

### Method
GET

### Endpoint
`https://DEMO.asknice.ly/api/v1/responses/desc/3/1/0/csv`

### Parameters
None

### Request Example
```bash
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/3/1/0/csv \
    --header "X-apikey: " \
    --location
```

### Response
#### Success Response (200)
- A CSV formatted string containing response data, with headers such as `response_id`, `person_id`, `contact_id`, `name`, `email`, `answer`, `sent`, `opened`, `responded`, `created`, `segment`, `question_type`, `survey_template`.

#### Response Example
```csv
response_id, person_id, contact_id, name, email, answer, sent, opened, responded, created, segment, question_type, survey_template
3, 123, 456, John Doe, johndoe@asknice.ly, 10, 1562641317, 1562641317, 1562641317, 1552610049, new, nps, Default
2, 433, 643, Jane Smith, janesmith@asknice.ly, 9, 1562641316, 1562641316, 1562641320, 1552610049, 1524789143, new, nps, Default
1, 674, 542, Steve Rogers, srogers@asknice.ly, 10, 1562641251, 1562641252, 1562641257, 1523828237, 1523828195, new, nps, Default
```
```

--------------------------------

### Bulk Add Contacts and Trigger Survey (cURL)

Source: https://asknicely.asknice.ly/help/apidocs/bulkasync

This cURL example shows how to add contacts and simultaneously trigger a survey for them by setting the 'obeyrules' field to true for each contact. This respects global contact rules but not exceptions for newly added contacts.

```cURL
curl -X POST \
    https://DEMO.asknice.ly/api/v1/contacts/add \
    --header "X-apikey: " \
    --data-binary @- << JSON
{
    "contacts": [
        {
            "name": "Erwin Schrodinger",
            "email": "schrodinger@example.com",
            "obeyrules": true
        },
        {
            "name": "John Smith",
            "email": "john@example.com",
            "obeyrules": true
        }
    ]
}
JSON
```

--------------------------------

### Successful Response (JSON)

Source: https://asknicely.asknice.ly/help/apidocs/bulkasync

This is an example of a successful response from the AskNicely API when contacts are added or updated. It indicates that the operation was successful.

```JSON
{
  "success": true
}
```

--------------------------------

### Trigger Survey with Segment and Custom Data via CURL

Source: https://asknicely.asknice.ly/help/apidocs/survey

This example shows a CURL request to trigger a survey while also including segment information and custom data for a contact. It uses 'segment' for categorization and 'city_c' as an example of custom data, demonstrating how to pass additional attributes.

```curl
curl -X POST \
  --data-urlencode "email=schrodinger@example.com" \
  --data-urlencode "name=Erwin Schrodinger" \
  --data-urlencode "triggeremail=true" \
  --data-urlencode "segment=green" \
  --data-urlencode "city_c=portland" \
  --header "X-apikey: " \
  https://DEMO.asknice.ly/api/v1/contact/trigger
```

--------------------------------

### Get Last 3 Responses in CSV Format

Source: https://asknicely.asknice.ly/help/apidocs/responses

Retrieves the last 3 response results from AskNicely in CSV format. This endpoint is useful for exporting data in a tabular structure. An API key is required.

```shell
curl -X GET \
    https://DEMO.asknice.ly/api/v1/responses/desc/3/1/0/csv \
    --header "X-apikey: " \
    --location
```

--------------------------------

### Error Response - Server Error (JSON)

Source: https://asknicely.asknice.ly/help/apidocs/bulkasync

This JSON example represents a generic server error during the API request. It indicates a '500 Internal Server Error' status.

```JSON
{
  "success": false,
  "msg": "Internal Server Error"
}
```

--------------------------------

### GET /email/conversation/{slug}

Source: https://asknicely.asknice.ly/help/apidocs/inapp

Retrieves and displays a survey using its slug. This endpoint is intended to be loaded via an iframe, new window, or WebView.

```APIDOC
## GET /email/conversation/{slug}

### Description
Retrieves and displays a survey using its slug. This endpoint is intended to be loaded via an iframe, new window, or WebView.

### Method
GET

### Endpoint
https://[YOUR_DOMAIN].asknice.ly/email/conversation/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The previously obtained slug that is to be loaded and used to display your survey.

#### Query Parameters
- **template_name** (string) - Required - The template name of the survey you want to use.
- **inapp** (string) - Required - Whether this survey is considered 'in app' or not. Affects some display rules and is typically not used by custom/mobile implementations, but is used by the AskNicely Javascript implementation.

### Response
This endpoint returns the HTML/content for the survey to be displayed.

### Displaying Your Survey
Once you have a survey slug, you can display the survey using an iframe, by opening another browser window, or (for mobile applications) loading the URL in a WebView.

For mobile implementations, the page returned implements a message handler under the name `askNicelyInterface`.
These events return a standard object that consists of a 'event' and 'msg' (message).

#### askNicelyInterface Events
- **askNicelyDone** - Triggered By: The survey being completed by the person being surveyed. - Description: A 'msg' of 'Success' indicates that the survey was completed successfully, and is usually used to automatically close the survey display when outside of a web browser window.
```

--------------------------------

### GET /api/v1/responses/desc/{response_type}/{limit}/{offset}/json

Source: https://asknicely.asknice.ly/help/apidocs/responses

Retrieves the latest response results from AskNicely. This endpoint supports filtering responses by specified criteria using `filters` and `values` parameters and allows controlling the number of results returned and the offset.

```APIDOC
## GET /api/v1/responses/desc/{response_type}/{limit}/{offset}/json

### Description
Retrieves the latest response results from AskNicely. This endpoint supports filtering responses by specified criteria using `filters` and `values` parameters and allows controlling the number of results returned and the offset.

### Method
GET

### Endpoint
`https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json`

### Parameters
#### Query Parameters
- **filters[]** (string) - Required - An array of filter keys to apply to the search. Example: `filters[]=city_c`
- **values[]** (string) - Required - An array of values corresponding to the `filters`. Example: `values[]=Abbotsford`

### Request Example
```bash
curl -X GET \
    "https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json?filters[]=city_c&filters[]=country_c&values[]=Abbotsford&values[]=Canada" \
    --header "X-apikey: YOUR_API_KEY" \
    --location
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **total** (string) - The total number of responses available.
- **totalpages** (string) - The total number of pages for the results.
- **pagenumber** (string) - The current page number.
- **pagesize** (string) - The number of responses per page.
- **since_time** (string) - Timestamp indicating the start of the data retrieval window.
- **end_time** (string) - Timestamp indicating the end of the data retrieval window.
- **data** (array) - An array of response objects, each containing details like `response_id`, `person_id`, `name`, `email`, `answer`, `city_c`, `country_c`, etc.

#### Response Example
```json
{
    "success": true,
    "total": "323",
    "totalpages": "65",
    "pagenumber": "1",
    "pagesize": "5",
    "since_time": "0",
    "end_time": "1642981569",
    "data": [
        {
            "response_id": "54120",
            "person_id": "54121",
            "contact_id": "54121",
            "name": "Aiman Shakeel",
            "email": "3d2c555c.39829842@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "",
            "dontcontact": null,
            "sent": "1614192119",
            "opened": "1614192119",
            "responded": "1614192119",
            "lastemailed": "1614192119",
            "created": "1614192119",
            "segment": null,
            "question_type": "nps",
            "published": "",
            "publishedname": "",
            "city_c": "Abbotsford",
            "country_c": "Canada"
        }
    ]
}
```

## Errors
### 401 (Unauthorized)
Invalid API key. Please check if the API key you are using is correct or valid.
```json
{
    "success": false,
    "msg": "Could not find user with API key \"invalid_api_key\""
}
```

### 400 (Bad Request)
An error `400` with a message is returned when the request exceeds the limit.
```json
{
    "success": false,
    "msg": "The request exceeds the results per request limit."
}
```

## Redirects
### 302 (Found)
Not setting your requests to follow redirection will return this response.
```
Redirecting to https://asknicely-tenant-files.amazonaws.com/download/.../responses_1625713191.json
```
For curl requests, set the `--location` or `-L` option to avoid this redirection message.
```

--------------------------------

### Get NPS Results with Filters API Request (cURL)

Source: https://asknicely.asknice.ly/help/apidocs/getnps

This snippet illustrates how to fetch NPS results while applying filters for specific criteria like country and city. It demonstrates how to pass multiple filter fields and their corresponding values in the request parameters. Ensure the number and order of filters and values match for accurate results.

```bash
curl --header "X-apikey: " \
"https://DEMO.asknice.ly/api/v1/getnps/30?filters[]=country_c&filters[]=city_c&values[]=Canada&values[]=Abbotsford"
```

--------------------------------

### Error Response - Malformed JSON (JSON)

Source: https://asknicely.asknice.ly/help/apidocs/bulkasync

This JSON example shows an error response when the provided JSON data for contacts is malformed. It indicates a '400 Bad Request' status and may include specific error details.

```JSON
{
  "success": false,
  "msg": "Errors found in json - {error}"
}
```

--------------------------------

### Get NPS Results

Source: https://asknicely.asknice.ly/help/apidocs/getnps

Retrieves the current Net Promoter Score (NPS) for a specified period. Supports filtering by custom fields.

```APIDOC
## GET /api/v1/getnps/{days}

### Description
Retrieves your current NPS score for a specified number of past days. You can optionally filter the results based on custom fields.

### Method
GET

### Endpoint
`https://DEMO.asknice.ly/api/v1/getnps/`{days}

### Parameters
#### Path Parameters
- **days** (integer) - Optional - Number of days since today to calculate NPS score on, default is 30

#### Query Parameters
- **filters[]** (string) - Optional - Custom field to filter on (e.g., `country_c`)
- **values[]** (string) - Optional - Value to match for the corresponding filter (e.g., `Canada`)

**Note:** The number of `filters` and `values` must be the same, and they must correspond in order. Incorrect matches will result in no data being returned.

### Request Example
#### Standard Request (Last 30 days)
```curl
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/getnps/30
```

#### Request with Filters (Last 30 days, filtering by Country and City)
```curl
curl --header "X-apikey: " \
"https://DEMO.asknice.ly/api/v1/getnps/30?filters[]=country_c&filters[]=city_c&values[]=Canada&values[]=Abbotsford"
```

### Response
#### Success Response (200)
- **NPS** (string) - The calculated NPS score.

#### Response Example
```json
{
  "NPS": "64.5"
}
```

#### Response Example with Filters
```json
{
  "NPS": "51.1"
}
```
```

--------------------------------

### AskNicely API Survey Display URL

Source: https://asknicely.asknice.ly/help/apidocs/inapp

Provides the GET request URL format for displaying a survey using its slug and template name. This is used for embedding surveys in web pages, new windows, or mobile WebViews.

```http
GET https://{your_domain}.asknice.ly/email/conversation/{slug}?template_name={template_name}&inapp={inapp}
```

--------------------------------

### Get Contact Details using cURL

Source: https://asknicely.asknice.ly/help/apidocs/getcontact

This snippet demonstrates how to retrieve the details of a specific contact using the AskNicely API via a cURL request. It requires the search term (e.g., email or ID) and the key to search by (e.g., 'email' or 'id'). The API returns a JSON object containing contact information upon success.

```curl
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/contact/get/schrodinger%40example.com/email
```

```curl
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/contact/get/your_id/id
```

--------------------------------

### AskNicely API Survey Display Query Arguments

Source: https://asknicely.asknice.ly/help/apidocs/inapp

Details the query arguments required for the survey display URL. This includes the survey slug, template name, and an 'inapp' flag to indicate if the survey is considered in-app.

```text
Query Arguments:
`slug`: Required, the previously obtained survey slug.
`template_name`: Required, the survey template name.
`inapp`: Required, indicates if the survey is 'in app'.
```

--------------------------------

### POST /email/conversation

Source: https://asknicely.asknice.ly/help/apidocs/inapp

Creates and prepares a survey for a specific user. It requires user details and a domain key, and returns a survey ID, slug, and display information.

```APIDOC
## POST /email/conversation

### Description
Creates and prepares a survey for a specific user. It requires user details and a domain key, and returns a survey ID, slug, and display information.

### Method
POST

### Endpoint
/email/conversation

### Parameters
#### Query Parameters
- **uuid** (string) - Required - We require a one-use dash-free 16 length uuid to prevent duplicate spam.

#### Request Body
- **domain_key** (string) - Required - The domain you signed up to AskNicely with.
- **template_name** (string) - Required - The template name of the survey you want to use.
- **name** (string) - Required - The name of the person being surveyed.
- **email** (string) - Required - The email address of the person being surveyed.
- **email_hash** (string) - Required - The email address of the person being surveyed after having been hashed through your secret key.
- **created** (string) - Required - A unix timestamp (seconds since 01/01/1970) of when this customer joined your service.
- **force** (boolean) - Optional - Whether to 'force' the survey/ignore set contact rules. **This is intended for testing during development, and will prevent the survey from triggering workflows. Please do not use this in production!**
- **a_custom_property** (string) - Optional - Any number of custom properties beyond the above are supported. They will be stored against the person and question for your later use.

### Request Example
```json
{
  "domain_key": "DEMO",
  "template_name": "default",
  "name": "Erwin Schrodinger",
  "email": "schrodinger@example.com",
  "email_hash": "ABCDEF0123456789",
  "created": "1418350105",
  "force": true,
  "a_custom_property": "Sample String"
}
```

### Response
#### Success Response (200)
- **id** (integer) - The id of the prepared survey.
- **slug** (string) - The slug to use when displaying the generated and prepared survey.
- **wait** (integer) - In the case of failure, this will show how long to wait before attempting to make another survey.
- **show** (boolean) - Whether to immediately show the survey. When used with the web in-app experience this is tied to the automatic javascript, but can be ignored outside that context.
- **info** (string) - Any extra error/status message that may come with the survey. Usually only populated if there was an error preparing the slug.

#### Response Example
```json
{
  "wait": 86400,
  "slug": "abcdefghijkl",
  "show": true,
  "id": 123456,
  "info": ""
}
```
```

--------------------------------

### AskNicely API Survey Creation Arguments

Source: https://asknicely.asknice.ly/help/apidocs/inapp

Defines the query and body arguments required for creating a survey via the AskNicely API. This includes unique identifiers, domain information, template selection, recipient details, and optional parameters like custom properties.

```text
Query Arguments:
`uuid`: Required, 16 length unique identifier to prevent duplicates.

Body Arguments:
`domain_key`: Required, your AskNicely domain.
`template_name`: Required, the survey template to use.
`name`: Required, the name of the person surveyed.
`email`: Required, the email of the person surveyed.
`email_hash`: Required, hashed email for security.
`created`: Required, Unix timestamp of customer join date.
`force`: Optional, forces survey ignoring contact rules (for testing).
`a_custom_property`: Optional, any custom properties.
```

--------------------------------

### Get Sent Statistics

Source: https://asknicely.asknice.ly/help/apidocs/sentstats

Retrieves statistics for surveys sent within a specified number of days. Supports filtering by custom fields and question types.

```APIDOC
## GET /api/v1/sentstats/{days}/{field?}/{value?}

### Description
Get statistics of your sent surveys.

### Method
GET

### Endpoint
`https://DEMO.asknice.ly/api/v1/sentstats/`

### Parameters
#### Path Parameters
- **days** (integer) - Optional - Number of days since today for emails sent, default is 30
- **field** (string) - Optional - The name of a custom property field you want to filter on.
- **value** (string) - Optional - The value of your custom property you want to filter on.

#### Query Parameters
- **filters[]** (string) - Optional - An array of custom field names to filter on.
- **values[]** (string) - Optional - An array of values corresponding to the `filters` to filter on.

### Request Example
Example to get your statistics of your sent surveys in the last 30 days
```bash
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/sentstats/30
```

Example filtered by one property
```bash
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/sentstats/30/custom_field_c/Custom%20Value
```

Example filtered by multiple properties
```bash
curl --header "X-apikey: " \
"https://DEMO.asknice.ly/api/v1/sentstats/30?filters[]=custom_field_c&filters[]=another_custom_field_c&values[]=Custom%20Value&values[]=Another%20Custom%20Value"
```

Example filtered by question type. Possible values: NPS, CSAT, FIVESTAR
```bash
curl --header "X-apikey: " \
"https://DEMO.asknice.ly/api/v1/sentstats/30/question_type/csat"
```

### Response
#### Success Response (200)
- **sent** (integer) - The total number of surveys sent.
- **delivered** (integer) - The number of surveys successfully delivered.
- **opened** (integer) - The number of surveys opened.
- **responded** (integer) - The number of surveys responded to.
- **promoters** (integer) - The number of promoter responses (for NPS).
- **passives** (integer) - The number of passive responses (for NPS).
- **detractors** (integer) - The number of detractor responses (for NPS).
- **responserate** (string) - The response rate as a percentage.

#### Response Example
```json
{
  "sent": 6,
  "delivered": 6,
  "opened": 3,
  "responded": 2,
  "promoters": 0,
  "passives": 0,
  "detractors": 2,
  "responserate": "33.3%"
}
```
```

--------------------------------

### Get Unsubscribed Contacts List (API)

Source: https://asknicely.asknice.ly/help/apidocs/getunsubscribed

Retrieves a list of contacts who have unsubscribed from AskNicely surveys. Supports optional pagination with pagenumber and pagesize arguments. The API endpoint is a HTTPS GET request.

```curl
curl --header "X-apikey: " \
https://DEMO.asknice.ly/api/v1/contacts/unsubscribed
```

```curl
curl --header "X-apikey: " \
"https://DEMO.asknice.ly/api/v1/contacts/unsubscribed?pagenumber=1&pagesize=1000"
```

--------------------------------

### Get Last 5 Responses (JSON)

Source: https://asknicely.asknice.ly/help/apidocs/responses

Retrieves the last 5 response results from AskNicely in JSON format. The `includestatustime` query parameter can be used to include status time information.

```APIDOC
## GET /api/v1/responses/desc/5/1/0/json

### Description
Retrieves the last 5 response results in JSON format. Use `?includestatustime=yes` to include status time details.

### Method
GET

### Endpoint
`https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json`

### Query Parameters
- **includestatustime** (boolean) - Optional - Include status time information.

### Request Example
```bash
curl -X GET \
    "https://DEMO.asknice.ly/api/v1/responses/desc/5/1/0/json?includestatustime=yes" \
    --header "X-apikey: " \
    --location
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **total** (string) - Total number of responses.
- **totalpages** (string) - Total number of pages.
- **pagenumber** (string) - Current page number.
- **pagesize** (string) - Number of responses per page.
- **since_time** (string) - Timestamp for filtering results.
- **end_time** (string) - Timestamp for filtering results.
- **data** (array) - Array of response objects, each containing details like `response_id`, `person_id`, `email`, `answer`, `status`, and `case_closed_time`.

#### Response Example
```json
{
    "success": true,
    "total": "10395",
    "totalpages": "2079",
    "pagenumber": "1",
    "pagesize": "5",
    "since_time": "0",
    "end_time": "1642981569",
    "data": [
        {
            "response_id": "54120",
            "person_id": "54121",
            "contact_id": "54121",
            "name": "Aiman Shakeel",
            "email": "3d2c555c.39829842@example.com",
            "answer": "8",
            "answerlabel": "8",
            "data": null,
            "comment": "",
            "note": null,
            "status": "Closed",
            "case_closed_time" : "1677805059"
        }
    ]
}
```
```