Your first anonymous survey, in about ten minutes.

Register your application

Open /new-caller and give a name and an administrator email. The name is the employer label your employees will see at the top of the questionnaire, so use the company name rather than the name of your integration.

A one-time link arrives by email. It opens a confirmation page; pressing the button mints the access token and shows it once.

The extra click is deliberate. Corporate mail gateways follow links in incoming mail, and a scanner would otherwise burn the one-time code before you ever clicked it.

/new-caller           # register, then check your email
/new-caller/rotate    # lost the token — needs client_app_id

Keep both strings

You are given a client_app_id and an access_token. Every API call needs both: the token in the Authorization header, the id in the body.

Save the client_app_id as carefully as the token. It isn't secret — it goes out on every request — but it is the only way to rotate a lost token. Lose both and your surveys are unreachable forever: there is deliberately no lookup by name or by email, because either would let anyone enumerate the employers using this service.

Names are not unique and identify nothing. Identity is the id plus the token.

{
  "client_app_id": "01J7ZQ8N4KDV6PMB3XW9YC2RTF",
  "app_name":      "Northwind Trading",
  "access_token":  "kP2vR…"
}

Create a survey

Create-only: there is no edit, close-early or delete endpoint.

timezone is an IANA name. An offset like -04:00 is rejected. Datetimes are stored as UTC and returned in the survey's own zone. datetime_end must be in the future; a start in the past just opens the survey immediately.

Put the returned code into the panel above.

curl -sX POST "https://enps-survey.org/api/v1/surveys" \
  -H "Authorization: Bearer " \
  -H 'Content-Type: application/json' \
  -d '{
    "client_app_id": "",
    "survey_title": "Employee sentiment H2",
    "timezone": "America/Toronto",
    "datetime_start": "2027-07-01T09:00:00",
    "datetime_end": "2027-07-15T18:00:00"
  }'

{
  "survey_code": "eQ5H3e7BS62pCojPVM32",
  "survey_title": "Employee sentiment H2",
  "datetime_start": "2027-07-01T09:00:00-04:00",
  "datetime_end": "2027-07-15T18:00:00-04:00",
  "timezone": "America/Toronto"
}

Register participants, one row per employee

Send only the labels you want to slice by later. No name, no email, no employee number — the service has nowhere to put them, and the fields would be rejected. Each participant comes back with an invitation link.

Batches cap at 500 and are all-or-nothing inside a transaction: one bad row rolls the whole request back and names the index, so a roster can never be half-loaded.

Any demographic may be omitted and becomes unspecified, which then groups like any other value. An unrecognised bracket is rejected rather than quietly defaulted. Decide your slicing before you load the roster — a label you did not send cannot be added afterwards.

curl -sX POST "https://enps-survey.org/api/v1/participants" \
  -H "Authorization: Bearer " \
  -H 'Content-Type: application/json' \
  -d '{
    "client_app_id": "",
    "survey_code": "",
    "participants": [
      {"location":"toronto", "org_unit":"engineering", "tenure_bracket":"2-3"},
      {"location":"boston",  "org_unit":"sales",       "tenure_bracket":"4-5"}
    ]
  }'

{
  "survey_code": "eQ5H3e7BS62pCojPVM32",
  "registered": 2,
  "participants": [
    { "participant_survey_code": "…", "submit_url": "…" },
    { "participant_survey_code": "…", "submit_url": "…" }
  ]
}

Email the links yourself

This service never contacts your employees. You hold the roster, so you do the matching — and because you do, we never learn which code belongs to whom. That is what the anonymity rests on.

The participants come back in the order you sent them, so pair each submit_url with the person on your side, send it, and do not keep the pairing any longer than the send takes. A stored map of code to employee recreates exactly what this design removes.

Participants can be added at any point up to datetime_end, including before the survey opens — so a new joiner mid-survey is one more call. Afterwards: 422.

to: alice@northwind.example
link: https://enps-survey.org/submit/{participant_survey_code}

Answer one yourself, before your staff do

Register a couple of extra participants for yourself and open one of their links. Pick a score; the follow-up question appears, asking what could improve at 0–8 and what makes the place good at 9–10. The comment is optional; the score is the only required field.

Each link works exactly once. Answering turns it into an "already submitted" page, so keep a spare or two if you want to look again.

The page picks its language from the employee's browser, and they can change it themselves. Append ?lang= to see any locale: en es fr de pt-BR it nl ja ko zh-Hans. Switching language part-way through keeps whatever has been answered so far.

It works with JavaScript disabled, which is worth knowing before somebody reports it broken from a locked-down desktop: the follow-up reveal is CSS, not script.

Watch participation while it runs

Counts only — how many invited, how many replied. Never who. Poll this to decide whether to send a reminder.

Group by location, org_unit or cost_center — either position, any pair. Omit grouping1 for the survey as a whole.

Groups with fewer than 2 invited merge into an other row. Branch on the other boolean, not on the label — a real cost centre may legitimately be called other.

curl -sX POST "https://enps-survey.org/api/v1/surveys/status" \
  -H "Authorization: Bearer " \
  -H 'Content-Type: application/json' \
  -d '{"client_app_id":"","survey_code":"","grouping1":"cost_center"}'

{
  "grouping": ["cost_center"],
  "rows": [
    { "group1": "cc-1001", "group2": null, "other": false, "invited": 17, "replied": 14 },
    { "group1": "other",   "group2": null, "other": true,  "invited": 1,  "replied": 0 }
  ],
  "totals": { "invited": 60, "replied": 40 }
}

Ask for one dimension at a time

grouping1 alone may be any of the six demographics. This is the query you will use most, because it is the only shape that returns comments.

Check suppressed before reading anything else. A suppressed row carries invited and replies and nothing at all besides — the scores, enps and comments keys are absent, not null. totals is subject to the same rule.

Omit grouping1 entirely for one figure covering the whole organisation.

curl -sX POST "https://enps-survey.org/api/v1/surveys/results" \
  -H "Authorization: Bearer " \
  -H 'Content-Type: application/json' \
  -d '{"client_app_id":"","survey_code":"","grouping1":"org_unit"}'

{
  "rows": [
    {
      "group1": "engineering", "other": false,
      "invited": 24, "replies": 17, "suppressed": false,
      "scores": {"0":0,"3":1,"…":0,"9":5,"10":3},
      "enps": 35,
      "comments": ["Good team, clear priorities…", "…"]
    },
    {
      "group1": "other", "other": true,
      "invited": 9, "replies": 4, "suppressed": true
    }
  ],
  "totals": { "invited": 60, "replies": 40, "suppressed": false, "enps": 25 }
}

Read the histogram, not just the score

eNPS is % promoters − % detractors, as a whole number. 9–10 are promoters, 0–6 are detractors, and 7–8 are passives, who count in the denominator but score nothing.

Which means one number hides a lot. A team split between enthusiasts and the thoroughly fed up scores the same as a team of shrugs. Those are not the same problem and they do not have the same fix, so read scores — the full 0–10 histogram is in every unsuppressed row.

Compare groups against each other and against your own last survey rather than against a published benchmark. The number is most useful as a difference.

Cross two dimensions to find where a problem lives

A poor score for a site is a question, not an answer. Crossing it with tenure or with occupational range often turns it into something actionable — "new joiners at this site" is a thing you can act on.

Crossed, grouping1 is location or org_unit and grouping2 is one of the three brackets; anything else is 422 invalid_grouping. You also get a subtotals array, one row per grouping1 value.

A crossed query never returns comments. Not a limitation — a cross-tabulation of free text is a re-identification kit, because each extra dimension narrows the pool of people a comment could have come from. Suppression still applies to every cell, so expect more suppressed rows here than on a single dimension.

curl -sX POST "https://enps-survey.org/api/v1/surveys/results" \
  -H "Authorization: Bearer " \
  -H 'Content-Type: application/json' \
  -d '{
    "client_app_id": "",
    "survey_code": "",
    "grouping1": "location",
    "grouping2": "tenure_bracket"
  }'

Read the comments — carefully

The comments are where the improvement actually is. The score tells you there is a problem; only the text tells you what it is.

They come back in random order, unlinked to any score and unlinked to each other, so you cannot tell which comment came from the 2 and which from the 9. That is intentional: pairing a harsh comment with the lowest score in a small team names its author to anyone willing to guess.

Escape them before rendering. They are employee-written text, returned verbatim, and will contain quotes, angle brackets and newlines.

And one caution worth reading properly: running all six single-dimension queries and intersecting the comment lists labels every comment with its author's full demographic profile. Suppression does not prevent this. ARCHITECTURE.md sets out the exposure — if you build a reporting UI, don't hand its users a way to do that by accident.