Get ballot by ID

Returns a single ballot by id. Supplying `uuidLock` reveals anonymous ballot choices tied to that lock.

Path Parameters

id*string

Ballot id.

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

Query Parameters

uuidLock?string

Reveals anonymous ballot choices associated with this lock.

Header Parameters

X-Organization-Id*string

The ID of the organization making the request.

Response Body

`application/json`

Ballot response.

TypeScript Definitions

Use the response body type in TypeScript.

_id?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

user?|

Authenticated user id when the ballot belongs to a logged-in user; otherwise null.

organization?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

overlayOrganization?schemas-ObjectId

MongoDB ObjectId serialized as a string.

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

testBallot?boolean

Defaultfalse

manuallySpecifiedElection?boolean

Defaultfalse

lastRefreshed?string

Formatdate-time

address?string

Full resolved address. For referred ballot reads, address details are omitted unless the ballot belongs to a canvass session.

city?string

City derived from the address when address details are protected.

addressComponents?

street?string

zip?integer

party?BallotParty

Party key. Common values include D, R, and N, but any party key may be used.

election?|

Election key in storage; populated election object in normal public responses.

recentElections?array<>

upcomingElections?array<>

createdAt?string

Formatdate-time

updatedAt?string

Formatdate-time

keyActions?

analytics?

experiments?array<|>

name?string

firstName?string

lastName?string

email?string

Formatemail

phone?string

races?array<>

measures?array<>

progress?

districts?array<>

limitedSupport?boolean

Defaultfalse

limitedSupportReason?BallotLimitedSupportReason

Value in"districts" | "outside-supported-area" | "races-and-measures" | "races" | "measures"

fullDistrictMatch?boolean

Defaultfalse

inSupportedDistricts?boolean

Defaultfalse

contentScouted?boolean

Defaultfalse

missingDistricts?array<|>

hasUnknownBoundaries?boolean

Defaultfalse

ambiguousDistricts?array<|>

raceChoices?array<>

Filtered to choices matching the supplied uuidLock.

measureChoices?array<>

Filtered to choices matching the supplied uuidLock.

likes?array<>

Filtered to likes matching the supplied uuidLock.

decisionFactors?array<>

Filtered to decision factors matching the supplied uuidLock.

`application/json`

Ballot, election, district match, or supported area was not found.

TypeScript Definitions

Use the response body type in TypeScript.

name?string

message?string

code?integer

className?string

data?

errors?

curl -X GET "https://example.com/ballots/65d4f20f8f5a4d7e9a123456" \  -H "X-Organization-Id: org_123"

{
  "_id": "65d4f20f8f5a4d7e9a123456",
  "user": "65d4f20f8f5a4d7e9a123456",
  "organization": "65d4f20f8f5a4d7e9a123456",
  "overlayOrganization": "65d4f20f8f5a4d7e9a123456",
  "testBallot": false,
  "manuallySpecifiedElection": false,
  "lastRefreshed": "2019-08-24T14:15:22Z",
  "address": "string",
  "city": "string",
  "addressComponents": {
    "prettyStreet": "string",
    "state": "string",
    "county": "string",
    "city": "string",
    "zip": 0,
    "number": 0,
    "street": "string",
    "postDirection": "string",
    "lat": 0,
    "long": 0,
    "source": "string"
  },
  "street": "string",
  "zip": 0,
  "party": "D",
  "election": "string",
  "recentElections": [
    {
      "key": "string",
      "date": "2019-08-24T14:15:22Z",
      "electionType": "primary"
    }
  ],
  "upcomingElections": [
    {
      "key": "string",
      "date": "2019-08-24T14:15:22Z",
      "electionType": "primary"
    }
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "keyActions": {
    "created": true,
    "shared": true,
    "opened": true,
    "firstChoice": true,
    "completed": true
  },
  "analytics": {
    "views": 0,
    "referredBallots": 0
  },
  "experiments": [
    "65d4f20f8f5a4d7e9a123456"
  ],
  "name": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "user@example.com",
  "phone": "string",
  "races": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "election": "string",
      "office": "string",
      "officeName": "string",
      "positionData": {
        "special": true,
        "seatIdentifier": "string",
        "seatIdentifierType": "post"
      },
      "raceKey": "string",
      "district": {
        "_id": "65d4f20f8f5a4d7e9a123456",
        "type": "county",
        "matchName": "ga-fulton",
        "displayName": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z",
        "name": "string",
        "fipsCode": "string",
        "number": 0,
        "letter": "string",
        "parentId": "65d4f20f8f5a4d7e9a123456",
        "parent": "string",
        "parentsFlat": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "population": 0,
        "populationType": "definitive",
        "votingType": "voting-district",
        "intersectingCities": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "intersectingCounties": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "state": "65d4f20f8f5a4d7e9a123456",
        "translationAvailable": true,
        "longName": "State House District 77",
        "shortName": "District 77"
      },
      "parentDistrict": "65d4f20f8f5a4d7e9a123456",
      "originalDistrict": "65d4f20f8f5a4d7e9a123456",
      "cities": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "counties": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "excludedDistricts": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "additionalDistricts": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "districtType": "county",
      "party": "string",
      "runoffPrecedent": "65d4f20f8f5a4d7e9a123456",
      "primaryPrecedent": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "ballotOrder": 0,
      "maxChoices": 0,
      "rankedChoice": {
        "enabled": true,
        "maxChoices": 0
      },
      "retention": true,
      "uncontested": true,
      "uncontestedDetailed": "under-contested",
      "longName": "string",
      "descriptionShort": "string",
      "detailShort": "string",
      "detailLong": "string",
      "readMoreLink": "string",
      "coveragePlan": "string",
      "coverageStatus": "no-coverage",
      "impactIssues": [
        {
          "key": "string",
          "how": "string",
          "name": "string"
        }
      ],
      "candidateSummary": {
        "numCandidates": 0,
        "numCandidatesNotQualified": 0,
        "names": [
          "string"
        ],
        "keys": [
          "string"
        ],
        "ids": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "photos": [
          "string"
        ],
        "parties": [
          "string"
        ]
      },
      "candidates": [
        {
          "_id": "65d4f20f8f5a4d7e9a123456",
          "photo": "string",
          "photoPathFace": "string",
          "name": "string",
          "party": "string",
          "official": "string"
        }
      ],
      "result": {},
      "ambiguousRace": true,
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "measures": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "election": "string",
      "key": "string",
      "title": "string",
      "descriptionShort": "string",
      "ballotText": "string",
      "actNumbers": "string",
      "whatItMeans": "string",
      "whatItMeansHtml": "string",
      "commentaryAvailable": true,
      "supportersSay": "string",
      "opponentsSay": "string",
      "sources": [
        {
          "url": "http://example.com",
          "type": "string",
          "sourceType": "website",
          "directQuote": "string",
          "title": "string"
        }
      ],
      "district": {
        "_id": "65d4f20f8f5a4d7e9a123456",
        "type": "county",
        "matchName": "ga-fulton",
        "displayName": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z",
        "name": "string",
        "fipsCode": "string",
        "number": 0,
        "letter": "string",
        "parentId": "65d4f20f8f5a4d7e9a123456",
        "parent": "string",
        "parentsFlat": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "population": 0,
        "populationType": "definitive",
        "votingType": "voting-district",
        "intersectingCities": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "intersectingCounties": [
          "65d4f20f8f5a4d7e9a123456"
        ],
        "state": "65d4f20f8f5a4d7e9a123456",
        "translationAvailable": true,
        "longName": "State House District 77",
        "shortName": "District 77"
      },
      "originalDistrict": "65d4f20f8f5a4d7e9a123456",
      "additionalDistricts": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "districtType": "county",
      "coveragePlan": "auto-coverage",
      "coverageStatus": "published",
      "status": "incomplete",
      "result": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "progress": {
    "racesTotal": 0,
    "measuresTotal": 0,
    "racesComplete": 0,
    "measuresComplete": 0,
    "percentageComplete": 0
  },
  "districts": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "type": "county",
      "matchName": "ga-fulton",
      "displayName": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z",
      "name": "string",
      "fipsCode": "string",
      "number": 0,
      "letter": "string",
      "parentId": "65d4f20f8f5a4d7e9a123456",
      "parent": "string",
      "parentsFlat": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "population": 0,
      "populationType": "definitive",
      "votingType": "voting-district",
      "intersectingCities": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "intersectingCounties": [
        "65d4f20f8f5a4d7e9a123456"
      ],
      "state": "65d4f20f8f5a4d7e9a123456",
      "translationAvailable": true,
      "longName": "State House District 77",
      "shortName": "District 77"
    }
  ],
  "limitedSupport": false,
  "limitedSupportReason": "districts",
  "fullDistrictMatch": false,
  "inSupportedDistricts": false,
  "contentScouted": false,
  "missingDistricts": [
    "65d4f20f8f5a4d7e9a123456"
  ],
  "hasUnknownBoundaries": false,
  "ambiguousDistricts": [
    "65d4f20f8f5a4d7e9a123456"
  ],
  "raceChoices": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "race": "65d4f20f8f5a4d7e9a123456",
      "candidate": "65d4f20f8f5a4d7e9a123456",
      "choice": "yes",
      "uuidLock": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "measureChoices": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "measure": "65d4f20f8f5a4d7e9a123456",
      "choice": "yes",
      "uuidLock": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "likes": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "candidate": "65d4f20f8f5a4d7e9a123456",
      "byStances": [
        {
          "stance": "65d4f20f8f5a4d7e9a123456",
          "issue": "string",
          "action": "like"
        }
      ],
      "uuidLock": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "decisionFactors": [
    {
      "_id": "65d4f20f8f5a4d7e9a123456",
      "type": "like",
      "issue": "string",
      "candidate": "65d4f20f8f5a4d7e9a123456",
      "race": "65d4f20f8f5a4d7e9a123456",
      "uuidLock": "string"
    }
  ]
}

Path Parameters

Query Parameters

Header Parameters

Response Body

200application/json

404application/json

`application/json`

`application/json`