curl --request POST \
  --url https://api.rallly.co/v1/polls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Team offsite",
  "kind": "date",
  "description": "Which days work for a two day offsite?",
  "options": [
    {
      "date": "2027-03-01"
    },
    {
      "date": "2027-03-02"
    },
    {
      "date": "2027-03-03"
    }
  ]
}
'

{
  "data": {
    "id": "Xk3pQ9vLm2Ab",
    "title": "Team sync",
    "description": "Pick a time that works for everyone",
    "location": "Zoom",
    "timeZone": "Europe/London",
    "status": "open",
    "kind": "time",
    "createdAt": "2025-01-10T12:00:00.000Z",
    "updatedAt": "2025-01-12T08:30:00.000Z",
    "organizer": {
      "id": "cm3f7d1qa0000t2k9c6b8h4jr",
      "name": "John Doe",
      "email": "organizer@example.com",
      "image": "https://cdn.rallly.co/avatars/cm3f7d1qa0000t2k9c6b8h4jr.jpg"
    },
    "requireEmail": false,
    "hideParticipants": false,
    "hideScores": false,
    "disableComments": true,
    "allowTentativeVotes": true,
    "participantCount": 3,
    "options": [
      {
        "id": "cm5h8x2k40000q9l4f7e2d3an",
        "date": "2025-01-15"
      }
    ],
    "adminUrl": "https://app.rallly.co/poll/Xk3pQ9vLm2Ab",
    "inviteUrl": "https://rallly.co/invite/Xk3pQ9vLm2Ab"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

Polls

Create a poll

Creates a poll and responds with 201 Created and the full poll, exactly as GET /polls/:pollId returns it. Share inviteUrl with participants. The request mirrors the response: kind chooses what participants vote on, and options takes the same shape the poll returns, so a poll can be recreated from the body of a GET. A poll has at most 100 options.

Date poll

Pass kind: "date" and options, one { "date": "YYYY-MM-DD" } per day. Each becomes one all-day option. Dates are floating calendar days with no timezone, so never convert them through one. Duplicate dates are removed.

{
  "title": "Team offsite",
  "kind": "date",
  "options": [{ "date": "2027-03-01" }, { "date": "2027-03-02" }, { "date": "2027-03-03" }]
}

Time poll

Pass kind: "time", optionally a timeZone (an IANA zone the times are written in) and a default duration in minutes, and the slots as options, generators or both.

Explicit slots

Each entry in options is one slot: a startTime and an optional duration that overrides the poll default. A startTime with no offset, like 2027-03-01T09:00:00, is wall clock time in timeZone when that is set and a floating time with no conversion otherwise; one with an offset or Z is an absolute instant.

{
  "title": "Kickoff",
  "kind": "time",
  "timeZone": "Europe/London",
  "duration": 60,
  "options": [
    { "startTime": "2027-03-01T09:00:00" },
    { "startTime": "2027-03-02T14:00:00", "duration": 90 }
  ]
}

Slot generators

Each object in generators expands into recurring slots of duration minutes from a schedule, so availability across days or weeks does not have to be listed slot by slot. duration is required when generators is set.

{
  "title": "Interview availability",
  "kind": "time",
  "timeZone": "America/New_York",
  "duration": 30,
  "generators": [
    {
      "startDate": "2027-03-01",
      "endDate": "2027-03-05",
      "days": ["mon", "tue", "wed", "thu", "fri"],
      "from": "09:00",
      "to": "12:00",
      "interval": 60
    }
  ]
}

This produces 30 minute slots at 09:00, 10:00 and 11:00 New York time on each weekday from 1 to 5 March, fifteen options in all. Drop interval and the window fills with back to back slots at 09:00, 09:30, 10:00, 10:30, 11:00 and 11:30.

Field	Meaning
`startDate`, `endDate`	The date range, inclusive. Fewer than 366 days.
`days`	Days of the week to include: `mon` to `sun`. Optional; defaults to every day.
`from`	Earliest slot start on each day, `HH:mm` in `timeZone`.
`to`	End of the daily window, `HH:mm` in `timeZone`. A slot is only generated if it ends by this time. Must be later than `from`.
`interval`	Minutes between slot starts. Optional; defaults to `duration`, which gives back to back slots.

A generator that cannot produce a slot is rejected with VALIDATION_ERROR naming the field: to not later than from, a window shorter than duration, or a range that contains none of the listed days. Generators are expanded when the poll is created, the result is appended to options, and duplicate slots are removed. A request that would exceed 100 options fails with TOO_MANY_OPTIONS.

POST

polls

curl --request POST \
  --url https://api.rallly.co/v1/polls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Team offsite",
  "kind": "date",
  "description": "Which days work for a two day offsite?",
  "options": [
    {
      "date": "2027-03-01"
    },
    {
      "date": "2027-03-02"
    },
    {
      "date": "2027-03-03"
    }
  ]
}
'

{
  "data": {
    "id": "Xk3pQ9vLm2Ab",
    "title": "Team sync",
    "description": "Pick a time that works for everyone",
    "location": "Zoom",
    "timeZone": "Europe/London",
    "status": "open",
    "kind": "time",
    "createdAt": "2025-01-10T12:00:00.000Z",
    "updatedAt": "2025-01-12T08:30:00.000Z",
    "organizer": {
      "id": "cm3f7d1qa0000t2k9c6b8h4jr",
      "name": "John Doe",
      "email": "organizer@example.com",
      "image": "https://cdn.rallly.co/avatars/cm3f7d1qa0000t2k9c6b8h4jr.jpg"
    },
    "requireEmail": false,
    "hideParticipants": false,
    "hideScores": false,
    "disableComments": true,
    "allowTentativeVotes": true,
    "participantCount": 3,
    "options": [
      {
        "id": "cm5h8x2k40000q9l4f7e2d3an",
        "date": "2025-01-15"
      }
    ],
    "adminUrl": "https://app.rallly.co/poll/Xk3pQ9vLm2Ab",
    "inviteUrl": "https://rallly.co/invite/Xk3pQ9vLm2Ab"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Invalid input: expected string, received undefined"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Date poll
Time poll

kind chooses what participants vote on: whole days (date) or time slots (time). The request mirrors the poll the API returns: the same settings, and options in the same shape as the response.

title

string

required

Required string length: 1 - 255

Example:

"Team sync"

kind

string

required

Participants vote on whole days.

Allowed value: "date"

options

Date option · object[]

required

Calendar days to offer. Dates are floating calendar days with no timezone, so never convert them through one. Duplicates are removed.

Minimum array length: 1

Show child attributes

description

string

Maximum string length: 1000

Example:

"Pick a time that works for everyone"

location

string

Maximum string length: 255

Example:

"Zoom"

requireEmail

boolean

Require participants to provide their email address

Example:

true

hideParticipants

boolean

Hide participant names from other participants

Example:

false

hideScores

boolean

Hide vote counts from participants

Example:

false

disableComments

boolean

Disable the comments section. Defaults to true: new polls have comments disabled unless this is set to false.

Example:

false

allowTentativeVotes

boolean

Allow participants to answer "if need be" as well as yes and no. Defaults to true.

Example:

true

organizer

object

Organizer of the poll. Defaults to the space owner if not provided. The organizer must be a member of the space.

Show child attributes

Response

Poll created

data

object

required

Show child attributes