Ballot limitations

Branch builds a ballot from the districts matched to a voter's address and the election content researched for those districts. In some cases, Branch can return useful ballot content but cannot guarantee that it is the voter's complete, official ballot.

Applications should use the fields below to explain that uncertainty and direct voters to their local election authority for confirmation.

Incomplete ballot content

The limitedSupport field is the main indicator that Branch cannot guarantee the ballot is complete.

• false: Branch matched the relevant districts, supports those districts for the election, and has completed the applicable race and measure research.
• true: At least one of those conditions was not met. The response can still contain races and measures, but it should not be presented as a guaranteed complete ballot.

When limitedSupport is true, limitedSupportReason explains the limitation. When it is false, limitedSupportReason is normally null or omitted.

Case 1: districts

Branch could not confidently match every district type relevant to the election.

• fullDistrictMatch is false when one or more relevant district types could not be resolved.
• missingDistricts is not normally populated for this reason because the unmatched district is unknown. Branch tracks the missing district types internally instead.

Case 2: outside-supported-area

Branch matched the voter's districts, but at least one matched district is outside Branch's guaranteed coverage area for the election.

• inSupportedDistricts is false.
• missingDistricts identifies the matched districts that do not have active Branch coverage. Depending on response population, each entry can be a district ID or a District object.

Case 3: races-and-measures, races, and measures

Branch supports the matched districts, but local ballot content is still being identified for the election.

• contentScouted is false.
• missingDistricts identifies districts with incomplete race or measure research.

In summary, Branch considers a ballot fully supported only when fullDistrictMatch, inSupportedDistricts, and contentScouted are all true.

---

Incomplete district matching

Some local districts do not have boundaries that Branch can use to determine exactly which district contains a voter's address. For example, Branch may know the voter's city but not which city council district applies.

When this happens, Branch includes all potentially applicable local districts in the match and returns the races associated with them. This avoids silently omitting a race, but it also means the response can contain local races that are not on the voter's official ballot. Applications should clearly label these races and ask the voter to confirm them with their local election authority.

• hasUnknownBoundaries is true only when at least one ambiguous district has a race or measure in the returned ballot. It can be false while ambiguousDistricts is nonempty if those districts have no relevant content in the election.
• ambiguousDistricts contains the district IDs or populated District objects that might apply to the voter but could not be selected precisely.
• A returned race tied directly to one of these districts has ambiguousRace: true, which applications can use to label or group the race.

hasUnknownBoundaries describes ambiguity in the content returned for the ballot. It is separate from limitedSupport, which describes whether Branch can guarantee that the ballot is complete.