API Reference

Integrate ImpactCheck with your platform to programmatically manage facilitators, generate survey links, and retrieve results.

The API is currently in v1. All endpoints are stable and backwards-compatible within this version.

Authentication

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.

Regenerating your API key invalidates the previous one immediately.

Base URL

https://impactcheck.net/api/v1

All endpoints return JSON. Send request bodies as JSON with Content-Type: application/json.

Error Handling

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

Status Meaning
200Success — resource already exists
201Created — new resource was created
401Unauthorized — missing or invalid API key
404Not found — survey or facilitator doesn't exist
422Validation error — missing required fields

Example error response:

{
  "error": "email is required"
}
GET

List Surveys

Endpoint

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.

Response

{
  "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"
    }
  ]
}

Example Request

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

Facilitator Lookup

Endpoint

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.

URL Parameters

Parameter Type Description
survey_id integer The ID of the survey to assign the facilitator to. Must belong to the authenticated user.

Request Body

Field Type Required Default Description
email string required — Facilitator's email address. Used as the unique lookup key within your account.
name string required* — Facilitator's display name. Required when creating a new facilitator. Updates the name if it has changed.
create_facilitator boolean optional true If the facilitator doesn't exist, create them. Set to false to return 404 instead.
assign_to_survey boolean optional true If the facilitator isn't assigned to this survey, assign them. Set to false to return 404 instead.

Response

Returns 201 if anything was newly created or assigned, 200 if everything already existed.

{
  "facilitator": {
    "id": 42,
    "name": "Jane Smith",
    "email": "jane@coaching.com"
  },
  "survey_facilitator": {
    "token": "a8f3x2m9"
  },
  "survey_url": "https://impactcheck.net/k7m2p9x4q1?f=a8f3x2m9",
  "created": false,
  "assigned": true
}
Field Description
facilitator The facilitator object (id, name, email)
survey_facilitator.token The opaque token for this facilitator's survey link
survey_url The full URL to send to participants — includes the ?f= token. Append &g=Cohort+3 to tag a group and &s=Day+1 to tag a session.
created true if the facilitator was newly created
assigned true if the facilitator was newly assigned to this survey

Example Request

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": "jane@coaching.com",
    "name": "Jane Smith"
  }'

Quickstart

1

Generate your API key

Go to Account Settings in the ImpactCheck dashboard and click "Generate API Key".

2

Create a survey

Create and publish a survey in the dashboard. Note its ID from the URL (e.g., /surveys/15).

3

Look up a facilitator

Call the Facilitator Lookup endpoint with the coach's email. You'll get back a unique survey URL.

4

Send the link to participants

Use the survey_url from the response. Responses submitted via this link are automatically attributed to the facilitator.