Create ballot
Creates a ballot from a voter street address or a pre-geocoded `location`. A pre-geocoded location bypasses geocoding and does not count toward billable API ballot lookup usage, but it is included in normal ballot lookup analytics. Anonymous callers must provide `uuidLock` to store contact fields and must reuse it on subsequent reads to reveal protected contact fields and choices.
Query Parameters
Stores or reveals anonymous choices and protected contact fields associated with this lock.
Header Parameters
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": "730 Peachtree St NE, Atlanta, GA 30308", "election": "ga-2026-general-election" }'{
"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": "yes",
"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"
}Get ballot by ID
Returns a single ballot by id. Supplying `uuidLock` reveals anonymous ballot choices tied to that lock. Ballots that have not been refreshed in the last 48 hours are refreshed before the response is returned.
Update ballot
Updates a ballot's party, street address, or protected contact fields. Anonymous contact updates are ignored unless `uuidLock` is supplied.