Surveys

Read-only access to survey templates and the answers collected across their spawns. Mirrors the data available in the CMS Excel export.

A template defines the survey (questions, schedule, anonymity); each time it runs it produces a spawn (one occurrence, with its own answers). Pass the template id to /surveys/{template_id}/answers to retrieve answers from every spawn of that template in one feed — each row carries its spawn's id and starts_at so you can group client-side.

Required scope: read:surveys

Endpoints

List templates

Returns survey templates only (not spawn instances), ordered by updated_at, newest first.

curl "https://customer.monotree.com/api/open/v1/surveys?category=satisfaction" \
  -H "Authorization: Bearer mono_your_token_here"

Template response

{
  "data": {
    "id": 42,
    "title": "Monthly pulse",
    "category": "satisfaction",
    "is_template": true,
    "respondent_identity": "anonymous",
    "is_anonymous": true,
    "is_published": false,
    "has_public_results": false,
    "rrule": "RRULE:FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=1",
    "starts_at": null,
    "created_at": "2026-01-10T09:00:00+01:00",
    "updated_at": "2026-03-28T14:20:00+01:00"
  }
}

category is one of the four values the category filter takes. is_template is always true on these endpoints. respondent_identity is required, optional, or anonymous — this is the field the privacy note above refers to; satisfaction surveys are always anonymous and development surveys always required. is_anonymous is true only when identity is anonymous; with optional, each answer's own is_anonymous says whether that answer was given anonymously. is_published is currently always false, even on published templates; use the status filter to tell published templates from drafts. has_public_results is true when employees in the survey's groups can see its results, not only admins and managers. rrule is the recurrence rule the template spawns by, as an RFC 5545 string (the example runs monthly on the 1st); null for a one-off survey. starts_at may be null — satisfaction templates have no start date of their own. GET /surveys/{id} returns the same object for any template, published or not; the id of a spawn returns 404.

List answers for a template

Returns all answers across every spawn of the template, ordered by created_at descending. Each answer embeds its spawn (id + starts_at), question, and choice so the row is self-describing — no separate question lookup required.

curl "https://customer.monotree.com/api/open/v1/surveys/42/answers?since=2026-04-01&per_page=100" \
  -H "Authorization: Bearer mono_your_token_here"

since and until sent with Z or another offset are compared as that moment; without an offset they are read as Copenhagen time. A date that cannot be read in since, until or spawn_starts_at returns 422. GET /surveys/{template_id}/answers/{id} returns 404 when the answer belongs to another template or to a spawn hidden by the respondent threshold.

Answer response

{
  "data": {
    "id": 9001,
    "template_id": 42,
    "spawn": { "id": 1378, "starts_at": "2026-04-01" },
    "question": {
      "id": 17,
      "title": "Engagement",
      "body": "How was your week?",
      "type": "rating",
      "position": 1
    },
    "choice": { "id": 88, "body": "Great", "value": 100 },
    "body": null,
    "reason": "lots of customers this week",
    "is_skipped": false,
    "is_anonymous": false,
    "respondent": {
      "id": 501,
      "name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "title": "Line Cook",
      "email": "jane@example.com",
      "type": "default",
      "avatar_url": "https://images.monotree.com/avatars/jane-doe.jpg",
      "is_manager": false,
      "groups": [
        { "id": 12, "name": "Kitchen", "type": "department", "is_manager": false, "created_at": "2025-09-01T10:00:00+02:00" }
      ],
      "hired_at": "2025-09-01",
      "date_of_birth": "1996-02-03",
      "is_away": false,
      "last_active_on": "2026-04-28T08:41:07.000000Z",
      "registered_at": "2025-11-01T09:00:00+01:00",
      "created_at": "2025-11-01T09:00:00+01:00"
    },
    "department": { "id": 12, "name": "Kitchen", "type": "department", "created_at": "2025-09-01T10:00:00+02:00" },
    "created_at": "2026-04-01T11:14:33+02:00",
    "updated_at": "2026-04-01T11:14:33+02:00"
  }
}

respondent uses the same Open API user object served by /users, and is null when the answer is anonymous. department uses the group object, and is null when the answer has no department or, on anonymous surveys, when the department had too few respondents in the spawn (see the privacy note above). body is the free-text answer, null when skipped or empty; reason is the optional reason the respondent wrote with the answer, null when none.