Results

Results are public (no auth) and available both while a process runs (a live tally) and after it ends (final). Because each question is its own election, results come back per question. The one exception is the free-text memos on an open-value question, which are returned to a manager/admin only.

Reading results¶

Fetch results for the whole process by processId. Each entry is one published question, keyed by its questionId and upstreamId, with a results matrix (one row per question field, one column per value). Per-question status and dates are not returned here - read those from the process or question read.

curl -s "$B/processes/$PROCESS/results"

{
  "id": "6a1f...",
  "questions": [{
    "questionId": "b2c3...", "upstreamId": "a1b2...64hex...",
    "voteCount": 42, "maxVoters": 500, "finalResults": true,
    "results": [ ["25", "17"] ]
  }]
}

• finalResults: false - the question is still open; the tally is provisional.
• finalResults: true - voting has ended; results are final.

var r = await Get($"/processes/{process}/results");
int votes = r.GetProperty("questions")[0].GetProperty("voteCount").GetInt32();

r = get(f"/processes/{process}/results").json()
votes = r["questions"][0]["voteCount"]

Voter memos¶

A question can mark one choice openValue - an "Other" option whose voters may attach a short free-text memo. Those memos come back as a memos array folded into the question's tally. There is no separate memos endpoint; they ride the reads you already make:

Mind that difference: on /results the field is a sibling of results, on the other two it is inside it. The GET /processes list does not resolve memos at all.

Memos are the one part of a tally that is not public. Only a manager/admin of the owning organization - or a voting:write API key acting as one - receives them. Everyone else gets the very same 200 with memos simply absent, never a 401, so an anonymous client cannot tell an open-value question from an ordinary one by its results. This is the optional authentication pattern.

# same URL, two answers: no key -> no memos; manager key -> memos
curl -s "$B/processes/$PROCESS/results"
curl -s -H "Authorization: Bearer $TOKEN" "$B/processes/$PROCESS/results"

{
  "id": "6a1f...",
  "questions": [{
    "questionId": "b2c3...", "upstreamId": "a1b2...64hex...",
    "voteCount": 42, "maxVoters": 500, "finalResults": true,
    "results": [ ["25", "12", "5"] ],
    "memos": [ "Grace Hopper", "Grace Hopper", "write-ins should be allowed" ]
  }]
}

How to read the array¶

• One entry per vote, not per distinct text. A memo three voters sent appears three times, which is what lets you count it - "Grace Hopper" twice above means two votes, not a duplicate to deduplicate away.
• Only memos that selected the open choice. A voter who typed something but voted for a different choice is not represented; the memo is dropped rather than reported against the wrong option. Concretely: singlechoice matches when the ballot's single value is the open choice's value, multichoice when the open choice's field is 1, cumulative when it is greater than 0.
• No voter, no order. The array carries text only - no nullifier, no address, no timestamp, and no guaranteed ordering. You cannot join a memo back to a ballot, and neither can anyone else.
• Absence is the only signal, and it is ambiguous. The field is present only when at least one memo resolved; there is no empty-array case (memos is omitempty). A missing memos can mean any of: you are not a manager, the question has no open-value choice, none have been cast yet, the question is still encrypted, or the chain read failed. Never infer authorization or "nobody wrote anything" from its absence.

The results matrix¶

Each question's results is a matrix of strings (tallies can be large or weighted): results[field][value] = the number of voters who put value in that field. For a single yes/no question with choices Yes (value 0) and No (value 1):

results[0] = ["25", "17"]
              └Yes  └No        -> 25 voted Yes, 17 voted No  (voteCount = 42)

Interpretation¶

The matrix is a raw histogram; clients turn it into per-option numbers in a few ways, picked by the question's voting type:

• Discrete (count per choice) - the common case for single choice. Each inner array is read directly as the per-choice counts.
• Index-weighted - for each field, multiply each count by its column index and sum. Used by ranked ballots, where the value (the rank) carries meaning.
• Aggregated - each field already holds a summed amount in column 0, so read results[i][0] directly. Used by cumulative ballots: their maxValue: 0 tells the protocol the field values are credits to add up, so the matrix is single-column and index-weighting it would return 0 for every option.

Multichoice reads differently again. There the matrix has one field per option, each a [#voted-0, #voted-1] histogram, so an option's count is the second number, results[i][1] - not results[0]:

results = [ ["0","3"], ["1","2"] ]    # options Yes / No, 3 ballots
            └Yes        └No
Yes approved by results[0][1] = 3 ;  No approved by results[1][1] = 2

Reading results[0] here (["0","3"]) as "Yes 0, No 3" is the classic mistake - each voter can approve several options, so iterate the fields, not one field's values. See Voting types for which reading each ballot uses.

Turnout¶

voteCount is how many ballots a question received; maxVoters is its eligible-voter count, already restricted to the question's eligibility subset - so turnout is voteCount / maxVoters, straight from the response. A bar that fills votesForOption / maxVoters reads as turnout share; one that fills against the leading option always shows the winner at 100%, which hides participation.