# AskNicely > AskNicely is a customer-experience platform for service businesses, built around Net Promoter Score, CSAT and 5-Star surveys delivered by email, SMS, web badge and in-app. Its public REST API imports contacts, triggers surveys, and returns responses and statistics. AskNicely publishes no llms.txt of its own — this file was generated by API Evangelist from AskNicely's public documentation and the artifacts in this repository. Base URL: `https://{domain}.asknice.ly/api/v1` — every account gets its own subdomain; substitute yours. Authentication: a single account API key in the `X-apikey` request header. Found in-platform under Settings > API. Versioning: `v1` in the URI path. One version only; no version pinning and no version header. Idempotency: not supported. Contact writes upsert on email, but repeating a survey trigger can send a second survey. Errors: proprietary `{"success": false, "msg": "..."}` envelope. Not RFC 9457. No machine-readable error code. Rate limits: 200 requests / 10s and 1000 / 60s per account; 100 / 10s and 500 / 60s on `/contact/trigger`. HTTP 429 with `Retry-After`. Redirects: `/responses` and `/contacts/deactivateall` depend on HTTP redirects. Your client must follow them. Custom fields: any unrecognised parameter becomes a custom data field on the contact; suffix names with `_c`. ## APIs - [AskNicely API](https://demo.asknice.ly/help/apidocs): Contacts, survey triggering, responses, statistics, unsubscribes and GDPR erasure. 12 operations. - [AskNicely In-App Survey API](https://demo.asknice.ly/help/apidocs/inapp): Exchange an HMAC-SHA256-signed contact identity for a one-time survey slug so a survey renders inside your own web or mobile surface. - [AskNicely MCP Server (Ask NiceAI)](https://asknicely.zendesk.com/hc/en-us/articles/51310930486292-Adding-AskNicely-as-a-Custom-Connector-in-Claude): Remote MCP server at `https://{domain}.asknice.ly/mcp`, OAuth 2.1 with dynamic client registration and PKCE S256, single scope `tools`. Requires the Ask NiceAI add-on. ## Operations - `POST /contact/trigger` — `triggerSurvey`: add or update one contact and send them a survey. Check `result[].survey_sent`, not the HTTP status. - `POST /contacts/add` — `bulkAddContacts`: asynchronous bulk import; `"obeyrules": true` also triggers surveys. 6MB payload cap. Returns 201 immediately. - `POST /curlupload/{importerId}` — `uploadContactsCsv`: upload a CSV to a preconfigured CSV Importer. - `GET /contact/get/{search}/{key}` — `getContact`: look up a contact by email (default) or any other property. - `GET /contact/remove/{search}/{key}` — `removeContact`: deactivate a contact. Not a deletion. - `POST /privacy/remove` — `privacyRemoveContacts`: GDPR erasure. IRREVERSIBLE; the contact is blocklisted. - `POST /contacts/deactivateall` — `deactivateAllContacts`: deactivate every contact in the account. Returns 307 until done. - `GET /contacts/unsubscribed` — `getUnsubscribedContacts`: list contacts who unsubscribed. `pagenumber` / `pagesize`. - `GET /responses/{sortDirection}/{pagesize}/{pagenumber}/{sinceTime}/{format}` — `getResponses`: survey responses, JSON or CSV, max 50,000 per call. - `GET /getnps/{days}` — `getNps`: the account's NPS over a rolling window. - `GET /sentstats/{days}` — `getSentStats`: sent/delivered/opened/responded counts and response rate. - `GET /stats` — `getHistoricalStats`: day-by-day historical statistics. - `POST /service/inapp.php?id={uuid}` — `requestSurveySlug`: in-app survey slug negotiation (not under /api/v1). ## Specs - [OpenAPI — AskNicely API](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/openapi/asknicely-openapi.yml) - [OpenAPI — In-App Survey API](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/openapi/asknicely-inapp-openapi.yml) - [Webhook catalog](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/asyncapi/asknicely-webhooks.yml) - [MCP manifest](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/mcp/asknicely-mcp.yml) - [OAuth scopes](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/scopes/asknicely-scopes.yml) - [Authentication profile](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/authentication/asknicely-authentication.yml) - [API conventions](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/conventions/asknicely-conventions.yml) - [Error catalog](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/errors/asknicely-problem-types.yml) - [Rate limits](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/rate-limits/asknicely-rate-limits.yml) - [Data model](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/data-model/asknicely-data-model.yml) - [Lifecycle](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/lifecycle/asknicely-lifecycle.yml) - [Changelog](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/changelog/asknicely-changelog.yml) - [Conformance](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/conformance/asknicely-conformance.yml) - [Examples](https://raw.githubusercontent.com/api-evangelist/asknicely/refs/heads/main/examples/asknicely-examples.yml) ## Docs - [API reference](https://demo.asknice.ly/help/apidocs) - [Authentication and quick start](https://demo.asknice.ly/help/apidocs/auth) - [API changelog](https://demo.asknice.ly/help/apidocs/changelog) - [Webhooks](https://asknicely.zendesk.com/hc/en-us/articles/47782734299540-Triggering-Webhooks-in-AskNicely) - [Ask NiceAI](https://asknicely.zendesk.com/hc/en-us/articles/46840078787988-Ask-NiceAI) - [Help centre](https://asknicely.zendesk.com/hc/en-us) - [Security and compliance](https://www.asknicely.com/security) - [Status page](https://status.asknicely.com/) - [Integrations](https://www.asknicely.com/integrations) - [Pricing](https://www.asknicely.com/pricing) ## Notes for agents - There is no sandbox or test host. Every call runs against the live account and can email real customers. `triggeremail=true` overrides ALL contact rules — never send it in production. - `POST /privacy/remove` is irreversible and blocklists the contact. Require explicit human approval. - `POST /contacts/deactivateall` is account-wide. Require explicit human approval. - `filters[]` and `values[]` are paired by position; a mismatch returns an empty result set with no error. - There is no SDK in any language. Call the API directly over HTTP.