API Reference

All API requests require a bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Generate your API key from Account Settings in the ImpactCheck dashboard. Keep it secret — treat it like a password.

Each survey is one of three modes. The mode is set when the creator builds the survey and locks once the first response is collected, with one exception: an owner or admin can change an Anonymous survey to Confidential (responses collected while it was Anonymous stay untracked).

The endpoint reference below indicates which mode each endpoint applies to.

Each API key carries a scope that determines what it can read. Create keys from Settings → API Keys in your dashboard. Default for new keys is aggregate.

Reads that return individual respondent identity on an admin-scope key are recorded in an internal audit trail.

Each API key gets a per-minute request budget. Default is 120 requests / minute; high-volume integrations can request a higher limit per key in the dashboard.

On overflow, we return 429 Too Many Requests with a Retry-After header (seconds).

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 60

Conditional requests still count toward your rate-limit budget, but ETag caching avoids transferring and recomputing the payload.

Requests with a missing, malformed, or revoked key are separately rate-limited per IP and receive 429 when that limit is exceeded.

The Results endpoint (GET /surveys/:id/results) returns a weak ETag derived from the survey's responses and its current question/metadata state, so renaming a survey or question also invalidates it. Send If-None-Match on subsequent requests; we'll return 304 Not Modified if nothing has changed.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H 'If-None-Match: W/"v1:80:1715000000:abc123"' \
     https://impactcheck.net/api/v1/surveys/15/results

# HTTP/1.1 304 Not Modified  (no body; still counts toward rate limit budget)

Also sets Cache-Control: private, max-age=30 so an HTTP cache or CDN can serve the same response for 30 seconds. The ETag changes whenever a new response lands.

The API uses standard HTTP status codes. Error responses include a JSON body with an error field.

Example error response:

{
  "error": "email is required"
}

GET /api/v1/surveys

Returns all active surveys for the authenticated user. Use the id field from the response as the survey_id parameter in other endpoints. Each results_url is the absolute URL of the creator results page, including the account slug; opening it requires a signed-in user with access to that account.

Sample surveys are excluded from all API endpoints. A sample survey ID returns the same 404 response as an unknown ID.

{
  "surveys": [
    {
      "id": 15,
      "name": "Leadership Accelerator 2025",
      "programme_name": "Leadership Accelerator",
      "survey_type": "programme_evaluation",
      "template_name": "Post-Programme",
      "retrospective": false,
      "slug": "k7m2p9x4q1",
      "response_count": 25,
      "published_at": "2026-02-14T10:30:00Z",
      "survey_url": "https://impactcheck.net/k7m2p9x4q1",
      "results_url": "https://impactcheck.net/apex-leadership/surveys/15/results"
    }
  ]
}

curl https://impactcheck.net/api/v1/surveys \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /api/v1/surveys/:survey_id/facilitators/lookup

Look up a facilitator by email. Creates the facilitator and/or assigns them to the survey if they don't exist yet. Returns the facilitator's unique survey link token. This endpoint is idempotent — calling it multiple times with the same email returns the same result.

{
  "facilitator": {
    "id": 42,
    "first_name": "Jane",
    "last_name":  "Smith",
    "email": "[email protected]"
  },
  "survey_facilitator": {
    "token": "a8f3x2m9"
  },
  "survey_url": "https://impactcheck.net/k7m2p9x4q1?f=a8f3x2m9",
  "created": false,
  "assigned": true
}

curl -X POST https://impactcheck.net/api/v1/surveys/15/facilitators/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email":      "[email protected]",
    "first_name": "Jane",
    "last_name":  "Smith"
  }'

POST /api/v1/surveys/:survey_id/respondents/lookup

Look up a respondent by email. Creates the respondent record (organization-scoped, reusable across surveys) and assigns them to the survey if they aren't already. Returns the survey_respondent.token — the per-invite hash that identifies this person on this survey. Idempotent — same (survey, email) returns the same token. Use this when you want to manage URL composition yourself; otherwise prefer the Invitation endpoint below.

{
  "anonymity":         "named",
  "respondent":        { "id": 12, "first_name": "Alice", "last_name": "Smith", "email": "[email protected]" },
  "survey_respondent": { "token": "kx9p2m...", "completed_at": null },
  "created":  true,
  "assigned": true,
  "warnings": []
}

curl -X POST https://impactcheck.net/api/v1/surveys/15/respondents/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "first_name": "Alice", "last_name": "Smith" }'

POST /api/v1/surveys/:survey_id/invitations

Convenience endpoint that does find-or-create for both respondent and facilitator and returns a fully composed survey URL. Each input is independent — send only what you have. Use this when you want a single API call to produce a ready-to-send link.

{
  "survey_url": "https://impactcheck.net/abc1234567?r=kx9p2m...&f=sf123456&g=Cohort+A&s=Session+3",
  "anonymity":  "named",
  "respondent":  { "id": 12, "first_name": "Alice", "last_name": "Smith", "email": "[email protected]", "token": "kx9p2m..." },
  "facilitator": { "id": 7,  "first_name": "Sam",   "last_name": "Coach", "email": "[email protected]",  "token": "sf123456" },
  "warnings": []
}

curl -X POST https://impactcheck.net/api/v1/surveys/15/invitations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "respondent":         { "email": "[email protected]", "first_name": "Alice", "last_name": "Smith" },
    "facilitator":        { "email": "[email protected]", "first_name": "Sam",   "last_name": "Coach" },
    "group_identifier":   "Cohort A",
    "session_identifier": "Session 3"
  }'

GET /api/v1/surveys/:survey_id/filter_dimensions

Returns the set of filter values consumers can use when fetching results — facilitators, groups, sessions, plus respondents on admin-scope keys (Named surveys only; never on Confidential). Designed so you can render a complete filter UI in a single API call.

{
  "facilitators": [
    { "token": "abc12345", "first_name": "Sam", "last_name": "Coach", "response_count": 18 }
  ],
  "groups":   [{ "value": "Cohort A", "response_count": 14 }],
  "sessions": [{ "value": "Session 1", "response_count": 30 }],
  "total_responses": 30,
  "has_unattributed": true,
  "respondents": [    // admin scope + Named survey only
    {
      "id": 12, "first_name": "Alice", "last_name": "Smith", "email": "[email protected]",
      "invitations": [
        { "token": "kx9p2m..", "completed_at": "2026-05-04T10:00:00Z" },
        { "token": "qz4n7r..", "completed_at": null }
      ]
    }
  ]
}

GET /api/v1/surveys/:survey_id/results

Per-question rollup — same data the IC dashboard uses. Returns a distribution per scale question, mean, retrospective deltas where applicable, response counts, and a date-bucketed trend if the survey has been live more than 7 days.

HTTP/1.1 200 OK
ETag: W/"v4:30:1715000000:abc123def456:123456abcdef"
Cache-Control: private, max-age=30

{
  "survey":          { "id": 15, "name": "...", "anonymity": "named", "response_count": 30, ... },
  "total_responses": 30,
  "suppressed": false,
  "min_display_responses": 3,
  "question_results": [
    { "question": { "id": 23, "question_type": "scale", "retrospective": true, ... },
      "response_count": 30, "distribution": {"1": 0, "2": 1, ...}, "mean": 4.2,
      "distribution_before": {"1": 4, "2": 9, ...}, "mean_before": 2.1, "mean_shift": 2.1 }
  ],
  "responses_over_time": [{ "date": "2026-04-30", "count": 6 }, ...],
  "filters": { "facilitator": "abc12345", "group": ["Cohort A", "Cohort B"] }
}

GET /api/v1/surveys/:survey_id/responses
GET /api/v1/surveys/:survey_id/responses.csv

Paginated individual response rows with respondent identity. Default 50 per page, max 200. Append .csv (or send Accept: text/csv) for the same data formatted as CSV — column-for-column matching the dashboard's CSV export. Returns 403 on Anonymous and Confidential surveys.

{
  "data": [
    {
      "id": 1234,
      "submitted_at": "2026-05-04T10:00:00Z",
      "respondent":  { "first_name": "Alice", "last_name": "Smith", "email": "[email protected]" },
      "facilitator": { "first_name": "Sam",   "last_name": "Coach", "email": "[email protected]" },
      "group_identifier": "Cohort A",
      "session_identifier": "Session 1",
      "answers": [
        { "question_id": 23, "question_type": "scale", "value": "4", "value_before": "2" }
      ]
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 30, "next_page": null }
}

GET /api/v1/surveys/:survey_id/respondents

Completion-status list — one row per person, with each invitation they've received nested under invitations. A respondent can be invited multiple times (e.g. after session 1 and again after session 5), so each invitation has its own token and completed_at.

{
  "data": [
    {
      "id": 12, "first_name": "Alice", "last_name": "Smith", "email": "[email protected]",
      "invitations": [
        { "token": "kx9p2m..", "completed_at": "2026-05-04T10:00:00Z" },
        { "token": "qz4n7r..", "completed_at": null }
      ]
    },
    {
      "id": 13, "first_name": "Bob", "last_name": "Jones", "email": "[email protected]",
      "invitations": [
        { "token": "by7n3z..", "completed_at": null }
      ]
    }
  ]
}

On a Confidential survey, completed_at is a date ("2026-05-04"), never a timestamp.

GET /api/v1/surveys/:survey_id/respondents/status?tokens[]=t1&tokens[]=t2

Bulk completion-check for tokens you already hold. Designed for the "did this batch of invitees finish?" use case without requiring the admin scope (no PII in the response). Up to 200 tokens per request.

{
  "data": [
    { "token": "kx9p2m..", "found": true,  "completed": true,  "completed_at": "2026-05-04T10:00:00Z" },
    { "token": "by7n3z..", "found": true,  "completed": false, "completed_at": null },
    { "token": "missing.", "found": false, "completed": false, "completed_at": null }
  ]
}

On a Confidential survey, completed_at is a date ("2026-05-04"), never a timestamp.

Each token in the request is echoed in the response in the same order, so you can map results 1:1 to your input list. Duplicate tokens are each echoed; blank tokens are returned with found: false. Only a completely empty tokens[] is rejected (422). Unknown tokens return found: false rather than 404.

POST /api/v1/respondents/erase

GDPR right-to-erasure. Anonymises the respondent matching email across your whole organisation: name and email are removed permanently, but their submitted responses remain so aggregate results stay intact. Org-level (not survey-scoped). Erasing the same email a second time returns 404 (the person is no longer identifiable in your organisation).

{ "email": "[email protected]" }

{
  "erased": true,
  "already_erased": false,
  "respondent_id": 42,
  "invitation_count": 3
}

Returns 404 when no respondent in your organisation matches the email, 422 when email is missing. This endpoint works even when your plan has lapsed — erasure is a legal obligation, so it's never gated.

GET /api/v1/surveys/aggregate?ids[]=1&ids[]=2&strategy=union

Cross-survey roll-up for "compare cohort 1 vs cohort 2" reporting. Two strategies:

• union (default) — pool all responses across the listed surveys into one combined result. Surveys must share question structure — position, type, resolved scale points, choice options, and each question's retrospective setting must all match; otherwise the request is rejected (422). Option text must match across pooled surveys, so an option reworded on one survey must be reworded identically on the others.
• compare — return parallel result objects, one per survey, for side-by-side rendering.

{
  "strategy": "compare",
  "min_display_responses": 3,
  "surveys": [
    { "survey": { "id": 9,  "name": "Cohort A", "response_count": 30 }, "suppressed": false, "question_results": [...], "total_responses": 30 },
    { "survey": { "id": 10, "name": "Cohort B", "response_count": 2  }, "suppressed": true,  "question_results": [],    "total_responses": 2  }
  ]
}

Returns 422 if surveys diverge structurally and you ask for union, or if you pass more than 100 survey IDs in one request. 404 if any of the listed survey IDs belongs to another organisation.

Set webhook_url on a Named or Confidential survey (in the creator UI), and ImpactCheck will POST a signed event to that URL: response.created each time a response lands on a Named survey, or respondent.completed each time an invited respondent completes a Confidential survey. The signature scheme is Stripe-compatible — existing webhook libraries (Ruby, Node, Python, Go, etc.) decode it without modification.

Content-Type: application/json
X-ImpactCheck-Signature: t=<unix_timestamp>,v1=<HMAC-SHA256 hex>
Idempotency-Key: evt_<response_id>   (Named)  |  evt_rc_<id>   (Confidential)
User-Agent: ImpactCheck-Webhook/1.0

{
  "id": "evt_1234",
  "event": "response.created",
  "survey":      { "id": 9, "slug": "abc1234567", "name": "Programme Eval" },
  "respondent":  { "token": "kx9p2m...", "email_address": "[email protected]", "first_name": "Alice", "last_name": "Smith" },
  "response":    {
    "id": 1234,
    "submitted_at": "2026-05-07T14:30:00Z",
    "group_identifier":   "Cohort A",
    "session_identifier": "Session 3"
  },
  "facilitator": { "token": "sf123456", "first_name": "Sam", "last_name": "Coach", "email_address": "[email protected]" }
}

{
  "id": "evt_rc_5678",
  "event": "respondent.completed",
  "survey":       { "id": 9, "slug": "abc1234567", "name": "Programme Eval" },
  "respondent":   { "token": "kx9p2m...", "email_address": "[email protected]", "first_name": "Alice", "last_name": "Smith" },
  "completed_on": "2026-05-07",
  "facilitator":  { "token": "sf123456", "first_name": "Sam", "last_name": "Coach", "email_address": "[email protected]" },
  "group_identifier":   "Cohort A",
  "session_identifier": "Session 3"
}