REST API

SoSci Survey offers options for automation via API for various functions.

As of version 3.6.12, these functions are made available via a uniform REST API.

An OpenAPI Specification (OAS) for development with Swagger is available at https://www.soscisurvey.de/templates/sosci-survey-api.yaml. Enable the option Access for web applications in the API access and enter the API key as “Bearer” in Swagger.

Creating an API Key

An API key is required to access the REST API. It is created in My Account under API Access.

Note: An API key is valid for the user account on the server on which it was created. If you have created an API key on www.soscisurvey.de, it is not valid for projects on s2survey.net. To create an API key on the Pro server, click Special Features → API Access in the survey project.

The API key is bound to a user account and, as a matter of principle, only has the permissions that the user account has. In addition, when creating the API key, you can specify which functions it can be used for.

Important: Currently, an IP filter for using the API key cannot be configured yet. Protect the API key very well, because third parties can use it to gain access to your user account and your survey projects.

When you click the API key under API Access, an API URL and an HTTP header are displayed. The header contains the API key. This Authorization header must be sent with the request in order to gain access.

Functions

The following resources (endpoints) are currently available below the API URL, all resources return the data as JSON. The HTTP status code indicates whether the request was successful.

/projects
- Returns a list of all survey projects in the user account incl. database IDs via GET.
- /<projectID>
  - Returns information about the project with the given ID via GET.
  - /contents
    - Returns a list of the sections in the list of questions and of the text elements via GET.
    - /sections
      - Returns a list of the sections in the list of questions via GET.
      - /<section ID>
        
        Returns a list of the questions, components, and texts in the section via GET
        
        /<element ID> (number between 1 and 99)
        
        Returns meta data about the question, the component, or the text
        
        /<item ID> (number between 1 and 99)
        
        Returns the texts and settings of the item via GET.
        
        Modifies the item via PATCH.
        
        Creates a new item with the given item ID via POST.
        
        Deletes the item via DELETE.
    - /files
      - Lists all images and media files that were uploaded to the survey project via GET.
  - /dataset
    - Returns the data via GET, according to the Filter Criteria for Valid Cases as set in the survey project.
    - To retrieve selected cases, the GET parameters according to API for Data Retrieval can be used.
  - /dataset.csv
    - Like dataset, but returns the dataset in CSV format for R.
  - /uploads
    - Returns a list of the files uploaded by respondents via GET.
    - /<file name>
      - Returns the file via GET
  - /databank
    - Returns the content of the Content Database via GET
    - Allows adding and updating entries via POST

Retrieving the Project List

https://www.soscisurvey.de/admin/api.php?v1/projects

[
	{
		"id": 104,
		"folder": "alpha",
		"title": "Project Alpha",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	},
	{
		"id": 17,
		"folder": "beta",
		"title": "Project Beta",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	},
	{
		"id": 103,
		"folder": "gamma",
		"title": "Project Gamma",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	}
]

The id is the database ID that is required to access the survey project.
The entry active indicates whether the survey project is still active or has already been archived.
The entry accessible indicates whether the survey project can be reached via this API URL or whether it is located on another survey server and may have to be addressed via the API URL of that survey server.

Retrieving Data

The following call would retrieve all cases from the project with the ID 130 whose data was changed after February 20, 2025, 4:32 p.m.

https://www.soscisurvey.de/admin/api.php?v1/projects/130/dataset?changedMin=2025-02-20T16:32:00

For the output of the dataset as JSON, see API for Data Retrieval

Downloading Files

By means of the API and R, you can also download all files uploaded by the respondents from a survey project. Optionally, use the following R Markdown for this.

In your user account, create a new API token under API Access that has read access to `/projects` and `/projects/uploads` (you can omit `/projects` if you already know the project ID)
Copy the “API URL” and enter it in the setup block of the R script.
Copy the “API key” and enter it in the setup block as well.
Depending on whether you enter the (numeric) project ID or not, the list of projects is retrieved and displayed, or the files are downloaded directly.

uploads.rmd

---
title: "Download Uploads"
author: "SoSci Survey"
date: "`r Sys.Date()`"
output: html_document
---
 
## Preparation
 
  * Go to the user account, select **API Access** and create
    a new token that is allowed to read `/projects` and `/projects/uploads`
    (you can skip `/projects` if you already know the project's ID)
  * Copy the "API URL" and paste here the setup script below
  * Copy the "API key" and paste into the script
 
 
```{r setup, include=FALSE}
# R setup block
knitr::opts_chunk$set(echo = TRUE)
 
# Insert the API URL below
api_url <- "INSERT HERE"
 
# Insert the API key below
api_key <- "INSERT HERE"
 
# Insert the project's ID below,
# eventually to be added after running the "projects" block
project_id <- 0
 
if (!require("pacman")) {
    install.packages("pacman")
    library("pacman")
}
p_load("httr2")
```
 
 
## Projects
 
Now, find the project's ID in this list (skip this code block if you already know the project's ID).
 
```{r projects, results='asis'}
if (project_id < 1) {
    req <- request(paste(api_url, "/projects", sep="")) |> req_auth_bearer_token(api_key)
    resp <- req |> req_perform()
    api_projects <- resp |> resp_body_json()
 
    for (api_project in api_projects) {
        cat(paste("  * ID ", api_project$id, ": ", api_project$title, "\r\n", sep=""))
    }
 
    rm(api_projects, api_project, resp, req)
} else {
    cat("Already set a project ID, skipping project listing retrieval.\r\n")
}
```
 
**Note:** Write the project's ID to `project_id` in the setup block (if not already done).
 
**Note:** Should you see an 401 error, make sure to grant the API key reading access to `/projects`.
 
 
## Download Uploads
 
Download the uploads to ''/uploads''.
 
```{r download, results='asis'}
if (project_id < 1) {
    cat("No project ID set, yet. Stopping processing.\r\n")
} else {
    req <- request(paste(api_url, "/projects/", project_id, "/uploads", sep="")) |> req_auth_bearer_token(api_key)
    resp <- req |> req_perform()
    api_uploads <- resp |> resp_body_json()
 
    dir.create("uploads", showWarnings = FALSE)
 
    for (upload_filename in api_uploads$files) {
        # Skip download if the file already exists
        if (file.exists(paste("uploads", upload_filename, sep="/"))) {
            cat(paste("  * ", upload_filename, " (skipped, already present)\r\n", sep=""))
        } else {
            cat(paste("  * ", upload_filename, "\r\n", sep=""))
            # Download the file and store to /uploads
            req_file <- request(
                    paste(api_url, "/projects/", project_id, "/uploads/", upload_filename, sep="")
                ) |> req_auth_bearer_token(api_key)
            req_file |>
                req_perform(path = paste("uploads", upload_filename, sep="/"))
        }
    }
    rm(upload_filename, api_uploads, resp, req, req_file)
}
 
rm(api_key, api_url, project_id)
```
 
**Note:** Should you see an 401 error, make sure to grant the API key reading access to `/projects/uploads`.

Table of Contents