VoterGuideOS
API Specificationsquestionnaires

Find questionnaires

Returns paginated questionnaires. Anonymous callers may find questionnaires for a specific `race` and `organization`. Other external callers must authenticate; organization-scoped queries require voter guide permissions for that organization unless the caller has Branch admin/editor permissions.

GET
/questionnaires

Query Parameters

$limit?integer

Maximum number of records to return.

Range0 <= value
$skip?integer

Number of records to skip.

Range0 <= value
$sort?

Sort object, for example $sort[createdAt]=-1.

_id?|array<>

Questionnaire id or ids.

$search?string

Fuzzy search query against questionnaire name.

election?string

Election key.

organization?string

Organization id. Required with race for anonymous public find access.

Match^[a-fA-F0-9]{24}$
race?string

Race id. When paired with organization, the service maps this to the stored races array and allows anonymous reads for race-assigned questionnaires.

Match^[a-fA-F0-9]{24}$
visibility?string

Visibility filter. Service-token public reads must use public.

Value in"public" | "org-specific"
contentType?string

Questionnaire content type.

Value in"questionnaire" | "third-party"

Header Parameters

X-Organization-Id*string

The ID of the organization making the request.

Response Body

application/json

Paginated questionnaire results.

TypeScript Definitions

Use the response body type in TypeScript.

application/json

Invalid public/service-token questionnaire query.

TypeScript Definitions

Use the response body type in TypeScript.

application/json

Authentication is required for protected questionnaire queries.

TypeScript Definitions

Use the response body type in TypeScript.

application/json

Caller does not have permission to read the requested organization scope.

TypeScript Definitions

Use the response body type in TypeScript.

curl -X GET "https://example.com/questionnaires" \  -H "X-Organization-Id: org_123"
{
  "total": 0,
  "limit": 0,
  "skip": 0,
  "data": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "name": "string",
      "description": "string",
      "organization": "65d4f20f8f5a4d7e9a123456",
      "election": "string",
      "visibility": "public",
      "contentType": "questionnaire",
      "includeDefaultQuestions": true,
      "questions": [
        {
          "_id": "65d4f20f8f5a4d7e9a123456",
          "title": "string",
          "description": "string",
          "type": "text-long",
          "options": [
            "string"
          ],
          "required": true,
          "wordCountMax": 0,
          "visibility": "public",
          "archived": false,
          "default": false,
          "internalFieldId": "email",
          "mapsToField": "phone"
        }
      ],
      "createdByUser": "65d4f20f8f5a4d7e9a123456",
      "recentActivity": [
        {
          "user": "65d4f20f8f5a4d7e9a123456",
          "createdAt": "2019-08-24T14:15:22Z"
        }
      ],
      "races": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "statusByCandidate": [
        {
          "candidate": "65d4f20f8f5a4d7e9a123456",
          "race": "65d4f20f8f5a4d7e9a123456",
          "status": "not-started"
        }
      ],
      "analytics": {
        "numberCandidates": 0,
        "numberRaces": 0,
        "numberCandidatesNotStarted": 0,
        "numberCandidatesInProgress": 0,
        "numberCandidatesCompleted": 0,
        "numberCandidatesPublished": 0,
        "numberCandidatesSubmitted": 0
      },
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}

Get questionnaire-response by ID

Returns a single questionnaire response by id. Authentication is optional for this read; when `$includeQuestionnaire=true`, the response embeds the questionnaire object after applying the caller's visibility.

Get questionnaire by ID

Returns a single questionnaire by id. Authentication is optional for this read; if provided, the token is validated and may affect fields visible to the caller.