Pull Survey Responses With the API

API keys give external scripts, dashboards, and data pipelines access to your survey responses without requiring a browser login. Instead of exporting a file, your tool sends a request to Domandata and gets back structured JSON it can process immediately.

Common uses include pulling responses into a live research dashboard, syncing data to a statistical analysis environment, triggering downstream workflows when new responses arrive, and archiving data to a lab server on a schedule.

1. Step 1: Open Settings. From the top navigation, choose Settings.

   Step 1: Open Settings

   Top Navigation

   This is the same navigation component used in the app shell.

2. Step 2: Go to Advanced. Select the Advanced tab in Settings, then scroll to API Keys.

   Step 2: Go to Advanced

   Top Navigation

   This is the same navigation component used in the app shell.

3. Step 3: Start a new key. Click New API Key.

   Step 3: Start a new key

   Top Navigation

   This is the same navigation component used in the app shell.

4. Step 4: Name the key. Use the script or system name, such as R analysis pipeline or lab dashboard, so you can identify it later.

   Step 4: Name the key

   Top Navigation

   This is the same navigation component used in the app shell.

5. Step 5: Create and store it. Click Create, then copy the key immediately into your secrets manager or environment file.

   Step 5: Create and store it

   Top Navigation

   This is the same navigation component used in the app shell.

6. Step 6: Confirm ownership. Leave the Settings page only after you know which script owns the key and where the secret is stored.

   Step 6: Confirm ownership

   Top Navigation

   This is the same navigation component used in the app shell.

Each key has an internal prefix shown in the list so you can identify it later. Keys start with dmdt_.

Open the survey you want to pull from and copy the survey UUID from its URL. Pass the key as a Bearer token in the Authorization header. Replace YOUR_KEY with the key you copied and SURVEY_ID with the UUID.

GET /api/v1/responses?survey_id=SURVEY_ID
Authorization: Bearer YOUR_KEY

Example with curl:

curl -H "Authorization: Bearer dmdt_your_key_here" 

"https://app.domandata.com/api/v1/responses?survey_id=abc123"

The response is JSON:

Results are returned newest-first in pages of up to 50 by default (maximum 200). When there are more results, next_cursor contains a timestamp to pass as cursor on your next request.

Keep requesting with the returned cursor until next_cursor is null, which means you have reached the end of the data.

• Never commit keys to source control. Store keys in environment variables or a secrets manager, not in code files. If a key appears in a git commit, delete it immediately and create a new one.
• One key per system. Create a separate key for each script or integration. This makes it easy to revoke access for one system without disrupting others.
• Name keys descriptively. A name like Python export script or lab Shiny dashboard makes it clear what to revoke if a key is compromised.
• Use cursor-based pagination for large datasets. Fetching all responses in one large request is slower and more fragile. Page through results with cursor so a network failure only loses one page, not the full export.
• Handle errors gracefully. A 401 means the key is invalid or expired. A 403 means the key does not have access to that survey. A 429 means you are sending requests too fast - add a delay between pages. Log error codes rather than silently dropping data.
• Poll at a reasonable interval. If you are monitoring for new responses in real time, polling every 30-60 seconds is a reasonable cadence. Polling faster than once every few seconds provides little benefit and adds unnecessary load.
• Store the cursor between runs. If your script runs on a schedule, save the last next_cursor value to disk or a database between runs. On the next run, start from that cursor to fetch only new responses rather than re-downloading everything.
• Rotate keys periodically. For sensitive or long-running projects, create a new key, update your systems to use it, and delete the old key. Routine rotation limits exposure if a key was inadvertently logged or shared.

Go to Settings, open Advanced, scroll to API Keys, and click the delete icon next to the key. Confirm when prompted. Any script using that key will immediately receive 401 errors. Create and distribute a new key before deleting an old one if the system needs continued access.

• Export Research Survey Responses
• Survey Variable Names and Recodes
• Pre-Analysis Plans and Survey Codebooks
• Privacy and Anonymity in Research Surveys