HAPI FAQ: Overview of Ballots API and Participation Data

HAPI FAQ – Ballots API

Where is the Ballots API documented?

• XSD:

  • https://bitbucket.org/sdo-hapi/data-models/src/master/schema/xsd/ballots/harmonized-ballots.xsd

  • https://bitbucket.org/sdo-hapi/data-models/src/master/schema/xsd/ballots/harmonized-ballot-configuration.xsd

• OpenAPI YAML:

  • https://bitbucket.org/sdo-hapi/api-specifications/src/master/openapi-v3/iec-ballots-openapi3.yaml

  • https://bitbucket.org/sdo-hapi/api-specifications/src/master/openapi-v3/clc-ballots-openapi3.yaml

• OpenAPI: IEC API Portal – https://api-portal.iec.ch/ (developer account required)

What does the Ballots API provide?

Metadata of on-going and closed ballots on IEC and CENELEC committee documents. It uses two schemas: harmonized-ballots.xsd and harmonized-ballot-configuration.xsd.

What can my application see?

• Ballot information (opening date, closing date, outcome): visible to all NCs.

• Participation (who voted/commented, what was submitted): only for your own NC.

What participation data is provided for my NC?

• Latest vote (in favour / against / abstain)

• URL of the attached comment file, if any

• Name and email of the expert(s) nominated by the NC

• Name and URN of the person who submitted the vote

Where do I find the Compilation of Comments (CC)?

Once the closing date (closingVote effectiveDate) is reached, the draft CC URL appears under outcome. Download requires the FULLDOC permission in the Working Documents API.

What is the ballot configuration?

A separate schema describing features common to many ballots (e.g. the same questions for all CDVs), so they are not repeated in each ballot payload.

How are parallel IEC/CENELEC ballots linked?

Under Frankfurt Agreement, ballotRelations contains the URN of the counterpart ballot (IEC ↔ CENELEC).

Can European NCs get IEC and CENELEC ballots together?

Yes. Omit originator to get both, or set originator=iec / originator=cenelec. Non-European members get IEC ballots only.

Example queries