Votes (v2)

Create a vote

Runs all three steps' rules, then opens the vote (the Share step) and answers its document with the share link; draft: true keeps it as an unshared draft instead (the Settings step's autosave). The vote is filed under the caller's trip as the Share step settles it: tripExternalId names one the caller may build on, else the place and dates typed match one, else a new trip is made. A free account at its trip limit with nothing matching gets the vote without a trip and needs_trip_choice with the candidates; POST /votes/{code}/trip files it afterwards.

post/api/v2/votes

Request

Base URL: https://www.endlesstravelplans.com
URL: https://www.endlesstravelplans.com/api/v2/votes
Auth: HTTP bearer

Request body

step'basic' | 'options' | 'settings' | 'all'

draftboolean

Keep an unshared draft instead of opening.

titlestring nullable required

The question.

typeIdinteger nullable required

The vote type id.

descriptionstring nullable

Must not be greater than 2000 characters.

tripExternalIdstring nullable

The trip to file the vote under.

tripDestinationstring nullable

Must not be greater than 255 characters.

departureDatestring nullable

Must be a valid date in the format <code>Y-m-d</code>.

returnDatestring nullable

Must be a valid date in the format <code>Y-m-d</code>.

activePresetinteger nullable

anonymousboolean

allowMultipleOptionsboolean

rankedChoiceVotingboolean

showLiveResultsboolean

weightedVotingEnabledboolean

Parents count double.

gamificationboolean

nameRequiredboolean

votingDeadlinestring nullable

The last day ballots are taken (Y-m-d).

consensusThresholdPercentinteger

Must be at least 0. Must not be greater than 100.

Example request

{
  "step": "settings",
  "title": "Where do we go for spring break?",
  "typeId": 1,
  "description": "Et animi quos velit et fugiat.",
  "tripExternalId": "01J9X",
  "tripDestination": "l",
  "departureDate": "2026-10-16",
  "returnDate": "2026-10-16",
  "options": [
    {
      "title": "Lisbon"
    },
    {
      "title": "Porto"
    }
  ],
  "activePreset": 16,
  "anonymous": true,
  "rankedChoiceVoting": true,
  "voterRoles": [
    {
      "name": "Sam",
      "role": "parent"
    }
  ],
  "nameRequired": true,
  "votingDeadline": "2026-11-30",
  "consensusThresholdPercent": 22
}

Response

codestring

statestring

titlestring

share_urlstring

Example response

{
  "code": "7Q2K-9M4N",
  "state": "open",
  "title": "Where do we go for spring break?",
  "options": [
    {
      "id": 1,
      "title": "Lisbon",
      "votes": 0
    }
  ],
  "share_url": "https://endlesstravelplans.com/vote/join/7Q2K9M4N",
  "events": [
    {
      "name": "vote.shared",
      "properties": {
        "tool": "vote_tool"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.