API documentation

The API lets your own systems — a reporting dashboard, a data warehouse, your CRM — read the feedback your customers leave. Everything is scoped to one account: the one the API key belongs to.

Instead of polling, webhooks can tell your server the moment a response arrives or matches an alert rule.

Not available today: creating or changing responses and questionnaires, and calls from a web page's JavaScript (browsers are blocked by CORS — call the API from a server).

Send your API key as a bearer token on every request:

Authorization: Bearer cfs_api_…

• Creating a key. Once API access is enabled, sign in as the account owner and open Settings → API Keys. Name the key after the system that will use it. The key is shown once; only a fingerprint of it is stored, so it cannot be shown again. An account can hold up to 10 keys.
• Available on request. On Growth and above plans the account owner requests access under Settings → API Keys (one request covers webhooks too), and we enable it after a short review. Starter and the free trial cannot request it. Access is checked on every request, so if the subscription lapses every key is refused with 403 — and works again as soon as it is renewed, without creating a new key.
• What a key can see. Everything in the account, at every location — including the names, email addresses and phone numbers of the customers responses came from. Keep keys on a server, never in a website, mobile app or shared spreadsheet.
• Revoking. Revoke a key on the same page and it stops working on the next request. Staff logins cannot create or revoke keys.
• Two kinds of key. cfs_api_… keys read through this API. cfs_crm_… connection keys only push customers in (below) and cannot read anything.

• 120 requests per minute per key. Every response carries RateLimit and RateLimit-Policy headers with the remaining budget and seconds until it resets.
• 50 failed key attempts per 15 minutes per IP address. After that, requests from that address get 429 until the window passes — check the key rather than retrying.
• Customer push: 60 requests per minute per connection.

On 429, wait for the number of seconds in the RateLimit header's reset value, then retry.

Errors use standard HTTP status codes and a JSON body with a stable, machine-readable code:

{
  "error": "limit must be an integer from 1 to 100",
  "code": "invalid_parameter",
  "param": "limit"
}

/responses is paginated with a cursor. Results come back oldest first, ordered by id. Each page includes has_more and next_cursor; pass next_cursor as starting_after to get the next page.

# First page
curl "https://customerfeedbacksimplified.com/api/v1/responses?limit=100" -H "Authorization: Bearer $CFS_API_KEY"

# ...returns "has_more": true, "next_cursor": 1141. Next page:
curl "https://customerfeedbacksimplified.com/api/v1/responses?limit=100&starting_after=1141" -H "Authorization: Bearer $CFS_API_KEY"

To sync continuously, store the last id you processed and call again later with starting_after set to it. Response ids only increase, so nothing is skipped or read twice. The other endpoints return every record in one call.

Each answer names its question and says what happened to it:

What value and numeric_value hold depends on the question type:

Both CES types changed direction on 25 September 2026, so that a higher numeric_value means easier, as it does for every other scored type. ces_5 used to return ces_very_easy as 1 and now returns it as 5. ces_7 used to return ces_strongly_agree as 1 and now follows standard CES 2.0, where 7 means strongly agree that it was easy. This applies to every response, including ones collected before the change. The value token did not change. If you stored numeric_value for either type before that date, reverse those rows: 6 − n for ces_5, 8 − n for ces_7.

Webhooks send an HTTPS POST to your server when something happens, so you do not have to poll. Add up to 5 endpoints under Settings → Webhooks — account owner, once access is enabled (on request, Growth and above). Each endpoint gets its own signing secret, shown once.

Payloads carry ids, not answers. Nothing about the customer or what they said is in the request. To read it, call GET /api/v1/responses/{id} with an API key.

POST /webhooks/feedback HTTP/1.1
Content-Type: application/json
User-Agent: CustomerFeedbackSimplified-Webhooks/1.0
X-CFS-Event-Id: 3f6c2a4e-8b1d-4c7e-9a52-6d0e1f2b3c4d
X-CFS-Event-Type: response.created
X-CFS-Delivery-Attempt: 1
X-CFS-Timestamp: 1789491725
X-CFS-Signature: v1=5d1c0a7e…

{
  "id": "3f6c2a4e-8b1d-4c7e-9a52-6d0e1f2b3c4d",
  "type": "response.created",
  "api_version": "v1",
  "created_at": "2026-09-14T18:22:05.000Z",
  "data": { "response_id": 1042, "questionnaire_id": 12, "location_id": 3 }
}

{
  "id": "9a0b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "type": "response.alert_matched",
  "api_version": "v1",
  "created_at": "2026-09-14T18:22:05.000Z",
  "data": {
    "response_id": 1042,
    "questionnaire_id": 12,
    "location_id": 3,
    "matched_question_ids": [301]
  }
}

Verifying the signature

X-CFS-Signature is v1= followed by the hex HMAC-SHA256 of <X-CFS-Timestamp>.<raw body>, keyed with the endpoint's secret. Compute it over the body exactly as received, compare in constant time, and refuse timestamps more than five minutes old.

const crypto = require('crypto');

// rawBody: the request body exactly as received, before any JSON parsing.
function isGenuine(headers, rawBody, secret) {
  const timestamp = headers['x-cfs-timestamp'];
  const signature = headers['x-cfs-signature'] || '';

  // Refuse anything older than five minutes, so a captured request cannot be replayed.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

import hashlib, hmac, time

# raw_body: the request body exactly as received, as bytes.
def is_genuine(headers, raw_body: bytes, secret: str) -> bool:
    timestamp = headers.get("X-CFS-Timestamp", "0")
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(headers.get("X-CFS-Signature", ""), expected)

Responding, retries and failures

• Answer with any 2xx within 10 seconds. Do the work afterwards. Anything else — another status, a timeout, a redirect — counts as a failure. Redirects are not followed.
• Retries. A failed delivery is tried up to 8 times: again after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours and 12 hours — about 22 hours in all. Every attempt carries the same X-CFS-Event-Id, so use it to ignore duplicates. Events can arrive out of order; use created_at if order matters.
• Switched off after 3 days of failures. An endpoint whose every delivery has failed for three days (and at least 10 attempts) is switched off and the account owner is emailed. Events in that time are not kept. Fix the endpoint, send a test, and switch it back on.
• Requirements. The URL must use HTTPS and resolve to a public internet address; private, loopback and link-local addresses are refused, both when the endpoint is saved and on every delivery.
• Delivery log. Each endpoint's deliveries — status, attempts and the last response code — are listed on the Webhooks page for 30 days, with a retry button for failed ones.
• Availability. Webhooks follow the same plan rules as the API. If they stop being available to the account, queued events are cancelled.

Your CRM or internal system can keep your customer list up to date, so feedback links can be sent to each person and every response arrives with a name on it. This endpoint uses a connection key rather than an API key: create a connection under CRM Customers → Connections to get its URL and key. Records land at the location the connection belongs to. Customer push follows your plan's CRM connection limit rather than the paid-plan rule above.

curl -X POST "https://customerfeedbacksimplified.com/api/crm/v1/<connection-path>/customers" \
  -H "X-CRM-Api-Key: $CFS_CRM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "uid": "C-1042",
        "full_name": "Asha Menon",
        "email": "asha@example.com",
        "mobile": "+14155551234",
        "external_data": { "tier": "gold" }
      }
    ]
  }'

{
  "created": 1,
  "updated": 0,
  "skipped": 1,
  "errors": [
    {
      "index": 1,
      "uid": "C-2087",
      "error": "Email already belongs to a different customer (uid C-1042). Two records cannot share it — merge or correct them in the source system."
    }
  ]
}

This is version 1. Within v1 we may add endpoints, optional parameters and new fields to responses — build your integration to ignore fields it does not recognise. We will not rename or remove a field, or change what one means, without releasing a new version.

Questions or something missing? Contact us.