API Specificationsballots
Create ballot
Creates a ballot from a voter street address. Use `uuidLock` on subsequent ballot reads to reveal anonymous choices tied to that lock.
Header Parameters
X-Organization-Id*string
The ID of the organization making the request.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
Created or existing ballot response.
TypeScript Definitions
Use the response body type in TypeScript.
application/json
Request validation failed. For partisan elections, this can include a partyMissing error when the request does not include party.
TypeScript Definitions
Use the response body type in TypeScript.
application/json
Ballot, election, district match, or supported area was not found.
TypeScript Definitions
Use the response body type in TypeScript.
curl -X POST "https://example.com/ballots" \ -H "X-Organization-Id: org_123" \ -H "Content-Type: application/json" \ -d '{ "street": "string" }'{
"user": null,
"organization": "69b1833f486f6eaa92fc1b5b",
"overlayOrganization": "69b1833f486f6eaa92fc1b5b",
"testBallot": false,
"manuallySpecifiedElection": false,
"lastRefreshed": "2026-05-29T16:14:30.000Z",
"address": "890 Memorial Dr SE, Atlanta, GA 30316",
"addressComponents": {
"prettyStreet": "890 Memorial Dr SE, Atlanta, GA 30316",
"state": "GA",
"county": "Fulton County",
"city": "Atlanta",
"zip": 30316,
"number": 890,
"street": "Memorial DR",
"postDirection": "SE",
"lat": 33.7474205,
"long": -84.3586514,
"source": "google"
},
"street": "890 Memorial dr SE",
"zip": 30316,
"party": "D",
"election": {
"_id": "6a109422784dc82893dfc45b",
"name": "2026 Georgia Primary Runoff",
"key": "2026-georgia-primary-runoff",
"status": "live",
"active": true,
"state": "5eac8e9f21ddc806d4f9aacf",
"stateCode": "GA",
"date": "2026-06-16T04:00:00.000Z",
"year": 2026,
"electionType": "primary-runoff",
"primaryMode": "PRIMARY_MODE_BY_PARTY",
"runoffMode": "RUNOFF_MODE_50_PERCENT_REQUIRED",
"nonpartisanPrimaryMode": "NONPARTISAN_PRIMARY_MODE_DECIDED_IN_PRIMARY",
"partisan": true,
"uncontestedPrimariesAppearOnBallot": true,
"runoffPrecedent": "2026-georgia-primary-election",
"partiesPresent": [
"D",
"N",
"R"
],
"ballotOverview": [],
"createdAt": "2026-05-22T17:36:34.844Z",
"updatedAt": "2026-05-27T14:53:58.209Z",
"parties": [
{
"_id": "69ab528ea7e6cdab132a6f71",
"key": "D",
"name": "Democrat",
"createdAt": "2026-03-06T22:17:50.164Z",
"updatedAt": "2026-03-06T22:17:50.164Z"
}
]
},
"upcomingElections": [],
"districts": [
{
"_id": "5eac8e9f21ddc806d4f9aacf",
"type": "state",
"matchName": "ga",
"displayName": "Georgia",
"name": "Georgia",
"parent": "United States of America",
"parentId": "63bb84b0e93e6e8743b455d7",
"votingType": "voting-district",
"population": 10711908,
"parentsFlat": [],
"populationType": "definitive",
"intersectingCities": [],
"intersectingCounties": [],
"state": "5eac8e9f21ddc806d4f9aacf",
"translationAvailable": true,
"longName": "State of Georgia",
"shortName": "Georgia"
}
],
"races": [
{
"_id": "6a16f8593b0c6fc25939f0d1",
"election": "2026-georgia-primary-runoff",
"office": "ga-state-lt-governor",
"positionData": {
"special": false
},
"raceKey": "2026-georgia-primary-runoff-ga-state-lt-governor-ga-d",
"district": {
"_id": "5eac8e9f21ddc806d4f9aacf",
"type": "state",
"matchName": "ga",
"longName": "State of Georgia",
"shortName": "Georgia",
"name": "Georgia",
"parent": "United States of America",
"translationAvailable": true
},
"parentDistrict": "63bb84b0e93e6e8743b455d7",
"districtType": "state",
"cities": [],
"counties": [],
"excludedDistricts": [],
"additionalDistricts": [],
"party": "D",
"runoffPrecedent": "69b14a7a5f811ffbe325bc34",
"primaryPrecedent": [],
"ballotOrder": 3000,
"maxChoices": 1,
"retention": false,
"uncontested": false,
"uncontestedDetailed": "contested",
"longName": "Georgia Lieutenant Governor Runoff, Democratic Primary",
"officeName": "Lieutenant Governor",
"descriptionShort": "The second highest elected official in the state and President of the State Senate",
"candidates": [
{
"_id": "6a16f85b3b0c6fc25939f585",
"photo": "https://branch-production-bucket.s3.amazonaws.com/images/candidates/1774465350435_blob",
"photoPathFace": "https://branch-production-bucket.s3.amazonaws.com/images/candidates/1774465350435_blob",
"name": "Josh McLaurin",
"party": "D",
"official": "josh-mclaurin"
}
]
}
],
"measures": [],
"limitedSupport": true,
"limitedSupportReason": "races-and-measures",
"fullDistrictMatch": true,
"inSupportedDistricts": true,
"contentScouted": false,
"missingDistricts": [
"5eac8e9f21ddc806d4f9aacf"
],
"hasUnknownBoundaries": false,
"ambiguousDistricts": [],
"progress": {
"racesTotal": 4,
"measuresTotal": 0,
"racesComplete": 0,
"measuresComplete": 0,
"percentageComplete": 0
},
"keyActions": {
"created": true,
"shared": false,
"opened": false,
"firstChoice": false,
"completed": false
},
"analytics": {
"views": 0,
"referredBallots": 0
},
"experiments": [],
"_id": "6a19bb71282f1fcddeaef23c",
"recentElections": [],
"raceChoices": [],
"measureChoices": [],
"likes": [],
"decisionFactors": [],
"createdAt": "2026-05-29T16:14:41.678Z",
"updatedAt": "2026-05-29T16:14:41.678Z"
}