Connect to the Surveyr API

1. 1

   Get an API key from Surveyr

   • Ask your Surveyr contact for a key. Surveyr makes it in Super admin → API keys and shows it only once, so store it safely straight away. It starts with svk_.
   • Your key is a read-only key for one organisation. It reads that organisation's surveys and responses through this API, and nothing else: it can't change or delete anything, anywhere.
   • Keep it server-side. Never put it in a browser, an app or a shared sheet.

   If a key leaks, tell Surveyr. We revoke it at once and make you a new one.

2. 2

   Note the base URL

   • Every call starts with https://www.surveyr.africa/api/external/v1.
   • All times are ISO 8601 in UTC, such as 2026-11-04T07:06:12.000Z. All ids are strings.

   Surveyr may give you a test address for trying things out first. Use it in place of https://www.surveyr.africa; the rest of each call stays the same.

3. 3

   Pick a tool

   • Use HTTPie, curl or Postman. Every example here has an HTTPie tab, a curl tab and a Copy button.
   • In Postman, add a header called x-api-key, with your key as its value, on the Headers tab.

   Tip: Postman can import a curl command: choose Import → Raw text and paste it. Then swap $SURVEYR_API_KEY and $SURVEY_ID for real values.

4. 4

   Put your key in a variable

   • The examples read your key from SURVEYR_API_KEY, so it never lands in a command you copy or share. In a macOS or Linux terminal (or WSL on Windows), run read -rs SURVEYR_API_KEY; export SURVEYR_API_KEY, paste the key and press Enter. Nothing shows as you paste, and the key stays out of your shell history.
   • In Part 3 you set SURVEY_ID the same way.

http https://www.surveyr.africa/api/external/v1/me \
  x-api-key:$SURVEYR_API_KEY

The key goes in the x-api-key header on every request. A good answer looks like this:

{
  "organization": {
    "id": "Ab12Cd",
    "name": "Example Observer Mission"
  },
  "authType": "apiKey",
  "rateLimit": {
    "perMinute": 120,
    "maxPageSize": 500
  },
  "version": "v1",
  "serverTime": "2026-11-04T07:12:00.000Z"
}

• organization is the organisation your key reads from.
• rateLimit.perMinute is how many requests a minute you may make. rateLimit.maxPageSize is the most records one page can hold.
• serverTime is Surveyr's clock.

http https://www.surveyr.africa/api/external/v1/surveys \
  x-api-key:$SURVEYR_API_KEY

You get data, a list of surveys without their questions, plus count and generatedAt. A survey's id is the surveyId in every call that follows. Put yours in a variable: export SURVEY_ID=6900aa000000000000000001. Then open the survey:

http https://www.surveyr.africa/api/external/v1/surveys/$SURVEY_ID \
  x-api-key:$SURVEYR_API_KEY

{
  "data": {
    "id": "6900aa000000000000000001",
    "name": "opening_report_2026",
    "status": "active",
    "type": "survey",
    "organizationId": "Ab12Cd",
    "start": "2026-11-04T05:00:00.000Z",
    "end": "2026-11-04T23:00:00.000Z",
    "isLiveEvent": false,
    "languages": [
      "eng_Latn",
      "zul_Latn"
    ],
    "questionCount": 5,
    "createdAt": "2026-10-20T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z",
    "questions": [
      {
        "id": "1",
        "number": 1,
        "text": "Did the voting station open by 07:00?",
        "type": "optionList",
        "options": [
          {
            "id": "a",
            "value": "Yes",
            "description": null
          },
          {
            "id": "b",
            "value": "No",
            "description": "Opened late"
          }
        ]
      },
      {
        "id": "k3Fq9mZa",
        "number": 2,
        "text": "Describe the queue when you arrived.",
        "type": "openEnded",
        "options": []
      },
      {
        "id": "g5Hs1dYu",
        "number": 5,
        "text": "Share your live location at the station.",
        "type": "location",
        "options": [],
        "location": {
          "verifyLocation": true,
          "radiusMeters": 300,
          "enforcement": "soft_flag",
          "target": {
            "latitude": -26.2041,
            "longitude": 28.0473
          }
        }
      }
    ]
  },
  "generatedAt": "2026-11-04T07:12:00.000Z"
}

Every question has a stable id. It doesn't change when questions are reordered, renamed or translated, and every response keys its answers by it. In 2024 answers came through in the order they were given, so a report filled in out of sequence couldn't be matched to its questions; keying each answer by its question's id means that can't happen.

http https://www.surveyr.africa/api/external/v1/surveys/$SURVEY_ID/responses/sample \
  count==3 \
  x-api-key:$SURVEYR_API_KEY

It takes your real survey, gives each question a made-up answer of its kind, and runs the reports through the same formatter as live data. You get choices, multi-select picks, text, a voice note with a media URL on surveys that take voice notes, and a location inside the geofence. If the survey asks for a location and you ask for two or more reports, the last one has a forwarded pin, so you can test your review filter. Nothing is stored.

• count is how many reports to make up: 1 to 50 (3 when you leave it out).
• The body carries "sample": true, and the observers are called Sample observer 1, Sample observer 2 and so on.
• format=csv works here too.
• The answers and ids are the same every time for a given survey, so you can keep them as a test fixture; the times follow the clock.
• The record and observer ids are sample-… strings, not the 24-character ids of real records, so a made-up report can't be mistaken for a real one.
• After the reports come three more records, so you can test versions: the first report's earlier version (latest: false; the first report is its version 2), an unfinished form (status: "incomplete") and a deletion notice.

http https://www.surveyr.africa/api/external/v1/surveys/$SURVEY_ID/responses \
  since==30m \
  x-api-key:$SURVEYR_API_KEY

since=30m means "from 30 minutes before the server's clock". You can also use 2h or 1d (up to 90d), or a full date such as 2026-11-04T07:00:00Z. A full date needs the Z (or an offset such as +02:00, with the + sent as %2B in a query string); without one it's refused with 400.

{
  "survey": {
    "id": "6900aa000000000000000001",
    "name": "opening_report_2026",
    "questionCount": 5
  },
  "data": [
    {
      "id": "6909c2a1b7e4f10012ab34cd",
      "surveyId": "6900aa000000000000000001",
      "respondentId": "66f1a2b3c4d5e6f7a8b9c0d1",
      "respondent": {
        "id": "66f1a2b3c4d5e6f7a8b9c0d1",
        "name": "Thandi M.",
        "cellNumber": "27820000001",
        "properties": {
          "stationNumber": "32850682",
          "province": "Gauteng"
        }
      },
      "submittedAt": "2026-11-04T07:06:12.000Z",
      "updatedAt": "2026-11-04T07:06:12.000Z",
      "status": "complete",
      "version": 1,
      "reportId": "6909c2a1b7e4f10012ab34cd",
      "replacesId": null,
      "supersededBy": null,
      "latest": true,
      "deleted": false,
      "deletedAt": null,
      "language": "eng_Latn",
      "source": "chatbot",
      "location": {
        "latitude": -26.2035,
        "longitude": 28.0481
      },
      "locationFlags": {
        "forwarded": false,
        "outsideGeofence": false,
        "distanceMeters": 102,
        "enforcement": "soft_flag",
        "flaggedAt": null,
        "needsReview": false
      },
      "answeredCount": 5,
      "questionCount": 5,
      "answers": {
        "1": {
          "questionId": "1",
          "number": 1,
          "type": "optionList",
          "answered": true,
          "value": "No",
          "label": "Opened late",
          "media": null,
          "location": null,
          "transcript": null,
          "skipped": false
        },
        "v2Tn7cRb": {
          "questionId": "v2Tn7cRb",
          "number": 4,
          "type": "audio",
          "answered": true,
          "value": "The station opened at ten past seven.",
          "label": null,
          "media": {
            "url": "https://api.cloudinary.com/v1_1/surveyr/video/download?public_id=surveyr%2Fprivate%2FUwtbDE%2Fchatbot%2Fabc%2F123&format=ogg&type=private&expires_at=1793779920&…",
            "type": "audio",
            "expiresAt": "2026-11-04T08:12:00.000Z"
          },
          "location": null,
          "transcript": "The station opened at ten past seven.",
          "skipped": false
        }
      }
    }
  ],
  "pagination": {
    "limit": 100,
    "count": 1,
    "hasMore": false,
    "nextCursor": null
  },
  "window": {
    "since": "2026-11-04T06:42:00.000Z",
    "until": null,
    "generatedAt": "2026-11-04T07:12:00.000Z"
  }
}

There is one record per version of a report (Part 6 explains versions):

Each entry in answers has these fields:

An unanswered question looks like this, so your parser never has to guess:

{
  "questionId": "k3Fq9mZa",
  "number": 2,
  "type": "openEnded",
  "answered": false,
  "value": null,
  "label": null,
  "media": null,
  "location": null,
  "transcript": null,
  "skipped": false
}

Repeated questions. A question with loop: { sourceQuestionId, shuffle } in the survey is asked once for each option the respondent picked in the multi-select question sourceQuestionId (its text names that option with {{loop.currentAnswer}}). Its answer has type: "loop", value a readable summary ("Soul Fries: KFC; SoulFire: Steers") and iterations: one entry per repeat, in the order asked, each with sourceOptionId, sourceValue, sourceLabel, position, answered, value, label, explanation and media. Join on sourceOptionId (the source option's id), not on position: the order can be shuffled per respondent. Options marked exclusive ("None of them") are never repeated for.

{
  "questionId": "q_brand",
  "number": 17,
  "type": "loop",
  "answered": true,
  "value": "Soul Fries: KFC; SoulFire: Steers",
  "label": null,
  "media": null,
  "location": null,
  "transcript": null,
  "skipped": false,
  "iterations": [
    {
      "sourceOptionId": "e2",
      "sourceValue": "Soul Fries",
      "sourceLabel": "Soul Fries",
      "position": 1,
      "answered": true,
      "value": "KFC",
      "label": "KFC",
      "explanation": null,
      "media": null
    },
    {
      "sourceOptionId": "e1",
      "sourceValue": "SoulFire",
      "sourceLabel": "SoulFire",
      "position": 2,
      "answered": true,
      "value": "Steers",
      "label": "Steers",
      "explanation": null,
      "media": null
    }
  ]
}

Media. WhatsApp shrinks photos and videos on the observer's phone before sending them, so Surveyr receives the reduced copy, not the original; voice notes are not affected in any way that matters. For organisations whose media is private (SAFE VOTE's is), the files can't be opened without a link Surveyr issues: media.url is such a link, made fresh on every pull, and it stops working at media.expiresAt, an hour after the pull. Download the files you need into your own storage during the pull. For other organisations the link is permanent and expiresAt is null.

Order and paging. Records come oldest first, or newest first with order=newest; ties on updatedAt are broken by id. When pagination.hasMore is true, call again with cursor set to pagination.nextCursor. The cursor is only a bookmark for the next page: a 12-minute poll normally fits in one page, so you rarely need it, but keep the loop for busy moments and full rebuilds. The cursor carries the first page's window and order, so since=30m means the same moment on every page of a pull; a since, until or order sent with a cursor is ignored, so sending the same query again is fine. The cursor is a position, not an offset, so reports that arrive in the meantime never shift a page. The same cursor is in the X-Next-Cursor header, and X-Has-More says whether there is one.

http https://www.surveyr.africa/api/external/v1/surveys/$SURVEY_ID/responses \
  since==2026-11-04T07:00:00Z \
  limit==500 \
  cursor==$NEXT_CURSOR \
  x-api-key:$SURVEYR_API_KEY

CSV. Add format=csv to get the same page as CSV (RFC 4180, UTF-8, CRLF). The fixed columns come first, then one column per question named q_<questionId>, plus q_<questionId>_media after each open-ended and word-cloud question for the media URL, then the version columns status, version, report_id, replaces_id, superseded_by, latest, deleted_at, and last, for each repeated question, one column per option of its source question named q_<questionId>__<sourceOptionId> with the answer given for that option. Multi-select values are joined with ; , and a location cell is latitude,longitude. Paging works the same way: read the X-Next-Cursor header.

http https://www.surveyr.africa/api/external/v1/surveys/$SURVEY_ID/responses \
  since==1d \
  format==csv \
  x-api-key:$SURVEYR_API_KEY

Every survey at once. GET /responses gives the reports of every survey of your organisation in one feed, with the same parameters and paging. It is JSON only, because the CSV columns would differ per survey.

http https://www.surveyr.africa/api/external/v1/responses \
  since==30m \
  x-api-key:$SURVEYR_API_KEY

1. 1

   Work out where to start

   • Take window.generatedAt from the first page of your previous successful pull.
   • Subtract 5 minutes and use that as since. The overlap covers clock skew and late writes.
   • On your first pull there is no previous one: use the survey's start instead.

   Use window.generatedAt, Surveyr's clock, not your own. A full date from it can't skip a record if a poll runs late; since=30m can.

2. 2

   Pull every page

   • Call GET /surveys/:surveyId/responses with that since and limit=500.
   • While pagination.hasMore is true, call again with cursor set to pagination.nextCursor. The cursor keeps the first page's since, so sending the same since again is harmless.
   • Stop when hasMore is false.
3. 3

   Upsert each record by id

   • Insert each record, or replace the one you already hold with the same id.
   • The overlap brings some records twice. An upsert makes that harmless.

   Corrections, unfinished forms and deletions arrive through this same loop, each as its own record (below). Nothing is removed without a record saying so.

4. 4

   Save where you got to

   • Once every page is stored, save window.generatedAt of the first page as the time of your last successful pull.
   • If a pull fails part-way, don't save it. The next pull starts from the same place, and the upserts take care of the repeats.

One call of the loop, when the previous pull's window.generatedAt was 2026-11-04T07:12:00.000Z:

http https://www.surveyr.africa/api/external/v1/surveys/$SURVEY_ID/responses \
  since==2026-11-04T07:07:00Z \
  limit==500 \
  x-api-key:$SURVEYR_API_KEY

Versions, unfinished forms and deletions. Surveyr keeps every version of a report and sends each as its own record with its own id. An observer can send the same form many times (an hourly report, several incidents); each submission is a separate report with its own reportId.

{
  "forwarded": false,
  "outsideGeofence": false,
  "distanceMeters": 102,
  "enforcement": "soft_flag",
  "flaggedAt": null,
  "needsReview": false
}

locationFlags is null when the survey asked for no location, or when it doesn't check the pin (its location question has verifyLocation: false).

Read only. Only GET (and HEAD) is accepted. Your key is a read-only key: any other method answers 403 with the error read_only_key. With a valid key that isn't read only, any other method answers 405 with Allow: GET, HEAD and the error method_not_allowed. Nothing you send can change or delete data.

Rate limit. Each key may make 120 requests a minute (rateLimit.perMinute in GET /me). Every answer after the key is accepted carries three headers (a 401, or a 403 from the key check itself, has none):

Over the limit, you get 429 and a Retry-After header. Wait that many seconds, then carry on.

{
  "error": "rate_limited",
  "message": "Too many requests: at most 120 per minute. Retry after 37s.",
  "retryAfterSeconds": 37
}

Errors. Every error has a message that says what went wrong, and most have an error code too: