API specification

This is v1.0 of the data API and this documentation is subject to change.

For a full list of endpoints you can add /api/1/docs to the end of your Citizen Space URL eg:

https://demo.citizenspace.com/api/1/docs

For a list of endpoints and example outputs read on below.

Show API key

GET /api/1/whoami

Return the name of the API key that matches your authentication method.

Headers

Name	Value
Authorization	Basic <base64 key:secret>

Response

200

{
  "Test Key"
}

400

List activities

GET /api/1/activities

Return a list of activities including uid, state, start date, end date, and path.

Headers

Name	Value
Authorization	Basic <base64 key:secret>

Response

200

{
        "uid": "67f18beb302944c9944e06521cfxxxxx",
        "title": "Smallville resident forum",
        "state": "open",
        "start_date": "2023-03-29T00:00:00",
        "end_date": "2027-03-26T00:00:00",
        "path": "demo/smallville-resident-forum"
},

400

Inspect survey information

GET /api/1/activities/{activity_uid}/survey

Requires the activity_uid and returns basic information about the activity.

Headers

Name	Value
Authorization	Basic <base64 key:secret>

Response

200

{
    "link_text": "Online Survey",
    "question_numbering": "continuous",
    "linear": true,
    "body": "",
    "factbank_heading": "Related information",
    "factbank": "",
    "thankyou_message": "Thank you for your response.",
    "email_thankyou_message": "Thank you for your response.",
    "has_skip_logic": false
}

400

Inspect survey pages

GET /api/1/activities/{activity_uid}/pages

Requires the activity_uid and returns basic information about the pages of an activity.

Headers

Name	Value
Authorization	Basic <base64 key:secret>

Response

200

{
        "id": "intro",
        "title": "Introduction",
        "body": "",
        "factbank": "",
        "factbank_heading": "Related information",
        "skip_logic_rules": [],
        "type": "SubPage"
}

400

Inspect survey questions

GET /api/1/activities/{activity_uid}/questions

Requires the activity_uid and returns basic information about the pages of an activity.

Headers

Name	Value
Authorization	Basic <base64 key:secret>

Response

200

{
        "page_id": "intro",
        "id": "opsuite.respondentmanagement.name",
        "title": "What is your name?",
        "number": "1",
        "analyst_only": false
    },
    {
        "page_id": "intro",
        "id": "quickconsult.email",
        "title": "What is your email address?",
        "number": "2",
        "analyst_only": false
    },

400

Inspect survey components

GET /api/1/activities/{activity_uid}/components

Returns a list of survey components and associated information.

Headers

Name	Value
Authorization	Basic <base 64 key:secret>

Response

200

{
        "id": "opsuite.respondentmanagement.name_subquestion",
        "type": "textsubquestion",
        "visibility": [
            "analyst",
            "public"
        ],
        "required": false,
        "label": "Name",
        "heading": "Name",
        "validation_options": [],
        "page_id": "intro",
        "question_id": "opsuite.respondentmanagement.name"
    },
    {
        "id": "opsuite.respondentmanagement.name-quickconsult.analysis.what_to_analyse_subquestion",
        "type": "whattoanalysesubquestion",
        "visibility": [
            "analyst"
        ],
        "required": false,
        "label": null,
        "heading": "Analyst notes",
        "character_limit": 0,
        "page_id": "intro",
        "question_id": "opsuite.respondentmanagement.name"
    },
    

400

List responses

GET /api/1/activities/{activity_uid}/responses

Requires an activity_uid and returns a list of responses and associated id.

Headers

Name	Value
Authorization	Basic <base64 key:secret>

Response

200

{
        "id": "ANON-XXXX-YYYY-C",
        "completed": true,
        "deleted": false,
        "answers": {
            "Name (opsuite.respondentmanagement.name_subquestion)": "Test",
            "Email (quickconsult.email_subquestion)": "[e-mail]",
            "Organisation (opsuite.respondentmanagement.organisation_subquestion)": "Test Organisation",
            "Visited Pages (__userinfo_pages_visited)": [
                "intro"
            ],
            "IP Address (__userinfo_ip)": "...",
            "Browser Identification (__userinfo_useragent)": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
            "Survey State (__userinfo_state)": "open",
            "Citizen Space Version (__userinfo_cs_version)": [
                "v7.27.0"
            ]
        }
    },

400

List responses (batched)

GET /api/1/activities/{activity_uid}/responses_batched

Requires an activity_uid and returns a list of responses and associated id.

Query Parameters (optional):

• batch_size - Controls how many responses are returned per batch

• batch_start - Sets the starting point for pagination

Basic query (no parameters): GET /api/1/activities/{activity_uid}/responses_batched

Basic query with batch parameters: GET /api/1/activities/{activity_uid}/responses_batched?batch_size=10&batch_start=0

For subsequent queries: GET /api/1/activities/{activity_uid}/responses_batched?batch_size=10&batch_start=20

Headers

Name	Value
Authorization	Basic <base64 key:secret>

Response

200

{
    "batching": {
        "total": 24,
        "batch_size": 10,
        "batch_start": 20,
        "next_batch_url": null
    },
    "responses": [
        {
        "id": "ANON-XXXX-YYYY-C",
        "completed": true,
        "deleted": false,
        "answers": {
            "Name (opsuite.respondentmanagement.name_subquestion)": "Test",
            "Email (quickconsult.email_subquestion)": "[e-mail]",
            "Organisation (opsuite.respondentmanagement.organisation_subquestion)": "Test Organisation",
            "Visited Pages (__userinfo_pages_visited)": [
                "intro"
            ],
            "IP Address (__userinfo_ip)": "...",
            "Browser Identification (__userinfo_useragent)": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
            "Survey State (__userinfo_state)": "open",
            "Citizen Space Version (__userinfo_cs_version)": [
                "v7.27.0"
            ]
        }
    }
]
}

Inspect a response

GET /api/1/activities/{activity_uid}/responses/{response_id}

Return information of a single response. Requires activity_uid and id as parameters.

Headers

Name	Value
Authorization	Basic <base64 key:secret>

Response

200

{
        "id": "ANON-XXXX-YYYY-C",
        "completed": true,
        "deleted": false,
        "answers": {
            "Name (opsuite.respondentmanagement.name_subquestion)": "Test",
            "Email (quickconsult.email_subquestion)": "[e-mail]",
            "Organisation (opsuite.respondentmanagement.organisation_subquestion)": "Test Organisation",
            "Visited Pages (__userinfo_pages_visited)": [
                "intro"
            ],
            "IP Address (__userinfo_ip)": "...",
            "Browser Identification (__userinfo_useragent)": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
            "Survey State (__userinfo_state)": "open",
            "Citizen Space Version (__userinfo_cs_version)": [
                "v7.27.0"
            ]
        }
    }

400