Candidate

Use Candidate to describe information about a candidate in a contest. A Candidate can be referenced by the CandidateSelection entity.

Select one of the following feed types to learn more about how to use Candidate with that type of feed.

Some elections are composed of multiple smaller contests or involve a series of subsequent contests. In these kinds of related contests, a Person must be referenced by only one Candidate. Consider the following example:

  • In Round 1 of an election in Poland, Person 1 is referenced by Candidate 1.
  • In Round 2, though, Person 1 is referenced by Candidate 2.

In this case, Candidate 1 and Candidate 2 are duplicates. Both contests need to reference the same Candidate. Generally, don't include a candidate in multiple unrelated contests.

Attributes

The following table shows the attributes for Candidate:

Attribute Required? Type Description
objectId Required ID Unique internal identifier that's used by other elements to reference this element.

Elements

The following table shows the elements for Candidate:

Element Multiplicity Type Description
BallotName 1 InternationalizedText Provides the candidate's name as it's listed on the ballot.
CampaignSlogan 0 or 1 InternationalizedText

The slogan that you get when you ask a candidate or their campaign what their campaign slogan is. See these examples from the 2020 US presidential election:

  • Joe Biden’s slogan: “Our Best Days Still Lie Ahead.”
  • Donald Trump’s slogan: “Make America Great Again.“
ContactInformation 0 or more ContactInformation Associate campaign headquarter address, phone numbers, etc. with the candidate information.
ExternalIdentifiers 1 ExternalIdentifiers Associates an ID with the candidate. A stable identifier is required.
FileDate 0 or 1 PartialDate The date when the candidate officially filed for the contest.
IsIncumbent 0 or 1 boolean A value of true indicates that the candidate is the current holder of the office associated with the contest. If this element isn't present, the default is false.
IsTopTicket 0 or 1 boolean Indicates whether the candidate is the top of a ticket that includes multiple candidates. Only include this element when there's more than one Candidate in a CandidateSelection object. If this element isn't present, the default is false.
PartyId 1 or more IDREF Unique identifier for a Party element. Used to associate a candidate with their political party.
PersonId 1 IDREF Unique identifier for a Person element. Used to associate more detailed information about the candidate.
PostElectionStatus 0 or 1 CandidatePostElectionStatus Final status of the candidate such as winner or withdrawn.
PreElectionStatus 0 or 1 CandidatePreElectionStatus Registration status of the candidate such as filed or qualified.

Additional types for ExternalIdentifiers

In the ExternalIdentifiers element of Candidate, provide additional data with a Type of other, along with values for OtherType and Value. The following table shows possible values for these elements:

OtherType Example values Description
electoral-commission H2NY22097

Optional

Electoral commission ID.

Examples

XML

    <Candidate objectId="can-1001-kenyatta">
      <BallotName>
        <Text language="en">Uhuru Kenyatta</Text>
        <Text language="sw">Uhuru Kenyatta</Text>
      </BallotName>
      <ExternalIdentifiers>
         <ExternalIdentifier>
            <Type>other</Type>
            <OtherType>stable</OtherType>
            <Value>can-per-100</Value>
          </ExternalIdentifier>
          <ExternalIdentifier>
            <Type>other</Type>
            <OtherType>electoral-commission</OtherType>
            <Value>H2NY22097</Value>
          </ExternalIdentifier>
        </ExternalIdentifiers>
      <IsIncumbent>1</IsIncumbent>
      <IsTopTicket>1</IsTopTicket>
      <PartyId>par-jubilee</PartyId>
      <PartyId>par-0002</PartyId>
      <PersonId>per-001-kenyatta</PersonId>
      <PostElectionStatus>projected-winner</PostElectionStatus>
      <PreElectionStatus>qualified</PreElectionStatus>
    </Candidate>

JSON

      "Candidate": [
          {
            "objectId": "can-1001-kenyatta",
            "BallotName": {
              "Text": [
                {
                  "value": "Uhuru Kenyatta",
                  "language": "en"
                },
                {
                  "value": "Uhuru Kenyatta",
                  "language": "sw"
                }
              ]
            },
            "ExternalIdentifiers": {
              "ExternalIdentifier" : [
                {
                  "Type": "other",
                  "OtherType": "stable",
                  "Value": "can-per-100"
                },
                {
                  "Type": "other",
                  "OtherType": "electoral-commission",
                  "Value": "H2NY22097"
                },
              ]
            }
            "IsIncumbent": 1,
            "IsTopTicket": 1,
            "PartyId": ["par-jubilee","par-0002"]
            "PersonId": "per-001-kenyatta",
            "PostElectionStatus": "projected-winner",
            "PreElectionStatus": "qualified"
          }
      ]