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.

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",
      "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://res.cloudinary.com/surveyr/video/upload/v1762240000/surveyr/chatbot/abc/123.ogg",
            "type": "audio"
          },
          "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 submitted report:

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
}

Paging. When pagination.hasMore is true, call again with cursor set to pagination.nextCursor. The cursor carries the first page's window, so since=30m means the same moment on every page of a pull; a since or until 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. 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.

   A report the observer corrects through the bot arrives as a new record, with a new id and a later updatedAt, and the earlier record is removed on Surveyr's side. Match a correction to the report it replaces by respondentId and surveyId, and keep the newest.

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

{
  "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: