Survey Responses

The Survey Responses API allows you to retrieve responses submitted to your organisation's surveys and forms. This includes all types of form submissions including surveys, assessments, and progress reports.

List Survey Responses

Retrieve a paginated list of survey responses with optional filtering.

Endpoint

GET /api/v1/survey-responses

Query Parameters

Pagination:

• limit (number, default: 100, max: 250) - Maximum number of responses to return
• offset (number, default: 0) - Number of responses to skip for pagination

Filtering:

• SurveyId (string) - Filter by form/survey ID
• funderSurveyId (string) - Filter by funder survey ID

Response

{
  "surveyResponses": [
    {
      "responseId": "response_abc123",
      "surveyId": "form_xyz789",
      "funderSurveyId": null,
      "managedBy": "org123",
      "submittedTo": "org123",
      "creator": "user_456",
      "date": "2025-01-20T14:30:00.000Z",
      "created": "2025-01-20T14:30:00.000Z",
      "updated": "2025-01-20T14:35:00.000Z",
      "responses": [
        {
          "questionId": "q_001",
          "question": "How would you rate your experience?",
          "outcome": "satisfaction",
          "type": "select",
          "response": "Very satisfied"
        },
        {
          "questionId": "q_002",
          "question": "What could we improve?",
          "outcome": "feedback",
          "type": "textarea",
          "response": "The session was excellent. More evening slots would be helpful."
        },
        {
          "questionId": "q_003",
          "question": "Would you recommend us to others?",
          "outcome": "nps",
          "type": "number",
          "response": 9
        }
      ],
      "linkedEntities": {
        "memberIds": ["member_123"],
        "partnerIds": [],
        "volunteerIds": []
      },
      "tags": ["feedback", "q1-2025"],
      "isPrivate": false,
      "surveyScore": 85
    }
  ],
  "offset": 0,
  "limit": 100,
  "total": 342
}

Example Requests

List all survey responses:

curl -X GET "https://app.plinth.org.uk/api/v1/survey-responses" \
  -H "x-api-key: sk_your_api_key"

Filter by survey/form ID:

curl -X GET "https://app.plinth.org.uk/api/v1/survey-responses?SurveyId=form_xyz789" \
  -H "x-api-key: sk_your_api_key"

Filter by funder survey:

curl -X GET "https://app.plinth.org.uk/api/v1/survey-responses?funderSurveyId=funder_survey_123" \
  -H "x-api-key: sk_your_api_key"

Paginate through results:

curl -X GET "https://app.plinth.org.uk/api/v1/survey-responses?limit=50&offset=100" \
  -H "x-api-key: sk_your_api_key"

Response Fields

Survey Response Object

Response Item Object

Each item in the responses array contains:

Linked Entities Object

Use Cases

Exporting Survey Data

To export all responses for a specific survey:

# Get all responses for a survey, paginating through results
curl -X GET "https://app.plinth.org.uk/api/v1/survey-responses?SurveyId=form_xyz789&limit=250" \
  -H "x-api-key: sk_your_api_key"

Linking Responses to Members

Each response includes a linkedEntities object that tells you which members, partners, or volunteers the response is associated with. You can use these IDs to fetch additional information from the respective endpoints.

Error Responses