API Overview

The ClickNPS API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

https://api.clicknps.com/v1

Authentication

The ClickNPS API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

curl https://api.clicknps.com/v1/surveys \
  -H "Authorization: Bearer YOUR_API_KEY"

🔑 API Key Format: All API keys start with sk_live_ for production or sk_test_ for test mode.

Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds."
  }
}

Endpoints

Surveys

Responses

Webhooks

Request Format

All POST and PATCH requests must include a Content-Type: application/json header:

curl -X POST https://api.clicknps.com/v1/surveys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Survey",
    "question": "How likely are you to recommend us?"
  }'

Response Format

All responses are returned in JSON format:

{
  "id": "survey_abc123",
  "name": "My Survey",
  "question": "How likely are you to recommend us?",
  "created_at": "2025-01-15T10:30:00Z",
  "status": "active"
}

Error Handling

The API uses conventional HTTP response codes:

Error Response

{
  "error": {
    "type": "validation_error",
    "message": "Invalid survey name",
    "field": "name"
  }
}

Pagination

List endpoints support pagination using limit and offset parameters:

curl "https://api.clicknps.com/v1/surveys?limit=10&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 20,
    "has_more": true
  }
}

Idempotency

POST requests support idempotency keys to safely retry requests:

curl -X POST https://api.clicknps.com/v1/surveys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Versioning

The API version is included in the URL path (/v1/). We maintain backwards compatibility and will notify you of any breaking changes at least 6 months in advance.

SDKs

Official SDKs are available for:

• JavaScript/TypeScript - npm install @clicknps/sdk
• Python - pip install clicknps
• Ruby - gem install clicknps
• Go - go get github.com/clicknps/go-sdk

Need Help?

• Installation Guide
• API Reference (detailed)
• Support