rallly Documentation

• Guests (no account): 1 open poll
• Hobby (free): 3 open polls
• Pro: unlimited open polls

Finalize or close a poll to make room for another. There are also technical
limits in place to prevent misuse but these are very generous and should not
affect normal usage.

Apps Docs Introduction (`apps/docs/introduction.mdx`) Copy Section

icon: "house" title: "Introduction" Copy Chapter

What is Rallly? Copy Chapter

Rallly is a tool for creating scheduling polls. It's designed to help people find a common time to schedule a meeting or event.

Rallly is pronounced like "rally" but with an extra L.

I wanted to call the product "Rally" because that's what it's for - rallying people together to make things happen.
But, of course, the domain name was already taken. So, I did what any sane person would do - I added an extra L.

-- Luke Vella, Creator of Rallly

What is a Scheduling Poll? Copy Chapter

Scheduling polls help you find a time that works for everyone. The host
of the meeting will typically select a few date and time options for participants to vote
for and then select the most suitable option.

Individual vs Team Usage Copy Chapter

Rallly works great for both personal scheduling and team collaboration:

• Individual Use: Create personal polls and share them with participants
• Team Use: Create spaces for your organization with centralized billing and member management

How much does it cost? Copy Chapter

Most of Rallly's features are free and most users will never need to pay for anything.
However, there are some features that are only available to Pro users, and teams can benefit from centralized billing through spaces.

Apps Docs Package.Json (`apps/docs/package.json`) Copy Section

{
"name": "@rallly/docs",
"version": "0.0.0",
"private": true,
"scripts": {
"dev": "mint dev",
"validate": "mint validate"
},
"devDependencies": {
"@rallly/tsconfig": "workspace:*"
},
"dependencies": {
"mint": "^4.2.884"
}
}

Apps Docs Administrators Deleting A Meeting Poll (`apps/docs/administrators/deleting-a-meeting-poll.mdx`) Copy Section

title: "Delete a Poll" Copy Chapter

To delete a meeting poll, from the admin page:

1. Click Manage

2. Select Delete from the dropdown menu

3. Click Delete to confirm

Apps Docs Administrators Editing A Meeting Poll (`apps/docs/administrators/editing-a-meeting-poll.mdx`) Copy Section

title: "Edit a Poll" Copy Chapter

Everything about a poll is edited on one page: its details, its dates and
times, and its settings.

<Frame caption="Admin controls">
  
</Frame>

<Frame caption="Edit page">
  
</Frame>

**Event** - Change the title, location or description.

**Calendar** - Add or remove options using the calendar. Switch
between month and week view, change the duration, or make the poll all
day.

**Settings** - Require an email address from participants, hide
participant names, hide votes until a participant has voted, allow
comments, and choose the vote options.

If you remove an option that participants have voted for, Rallly asks you
to confirm first. Their votes for that option are deleted with it.

Vote options Copy Chapter

Vote options decides which answers participants can give. By default they
can answer Yes, If need be or No. Switch to Yes and No if
you want a straight answer with no maybes.

What can't be changed Copy Chapter

• Time zone - Once votes have been cast, the poll's time zone is locked.
  Changing it would move every option under participants who already answered.
• Scheduled polls - A poll that has been scheduled can no longer be edited,
  because the calendar invites your participants received would not pick up
  the change. The Edit item is hidden from the Manage menu for these
  polls.

Apps Docs Api Reference Authentication (`apps/docs/api-reference/authentication.mdx`) Copy Section

title: "Authentication" icon: "key" Copy Chapter

Every Polls endpoint requires a bearer token; only the OpenAPI document at /v1/openapi is public. Pass the API key in the Authorization header:

Authorization: Bearer sk_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx

curl https://api.rallly.co/v1/polls \
  -H "Authorization: Bearer $RALLLY_API_KEY"

Creating a key Copy Chapter

1. Open Settings → API keys in the space you want to access. Only the space owner sees this page.
2. Choose Create API key and give it a name that identifies the integration.
3. Copy the key. It is shown once and cannot be retrieved later; if you lose it, revoke it and create a new one.

Keys start with sk_. Store them as you would any secret: in an environment variable or a secrets manager, never in client-side code or a repository.

Scope Copy Chapter

A key belongs to one space and grants access to that space's polls only. It does not carry a user identity: polls created through the API are attributed to the organizer you name in the request, who must be a member of the space.

Revoking a key Copy Chapter

Revoke a key from the same settings page. Requests with a revoked, expired or unknown key fail with 401 and the UNAUTHORIZED error code.

Plan requirement Copy Chapter

The space behind the key must be on a Pro plan. A key for a space without an active subscription is accepted but every request fails with 403 and the SPACE_NOT_PRO error code until the space upgrades.

Apps Docs Api Reference Changelog (`apps/docs/api-reference/changelog.mdx`) Copy Section

title: "Changelog" icon: "clock-rotate-left" Copy Chapter

• GET /polls/{pollId}/participants/{participantId} returns one participant. A missing participant on an existing poll is 404 with PARTICIPANT_NOT_FOUND.
• Participants now carry availability: one { start, end, allDay, modifiers } span per option they can make, in start order, on both the list and the single-participant endpoint. A span matches an option of the poll by its time; end is exclusive; ifNeedBe is a modifier.

Webhooks, in beta. A space can register up to five HTTPS endpoints and receive signed, retried deliveries for nine poll and participant events. The event list and payloads may still change, and more events will be added. See Webhooks.

The poll and participant resources are unchanged.

Initial stable release under /v1.

• Create, list, get and delete polls
• Read a poll's results and participants
• Bearer authentication with space API keys
• Per space rate limits with RateLimit-* headers

Apps Docs Api Reference Errors (`apps/docs/api-reference/errors.mdx`) Copy Section

title: "Errors" icon: "triangle-exclamation" Copy Chapter

Every failure is application/json with the same shape:

{
  "error": {
    "code": "POLL_NOT_FOUND",
    "message": "Poll not found or does not belong to this space."
  }
}

code is stable and safe to branch on. message is for humans and may change without notice. VALIDATION_ERROR messages name each offending field, separated by semicolons.

Codes Copy Chapter

Handling errors Copy Chapter

• Treat 4xx responses other than 429 as bugs in the request. Retrying without changing it returns the same error.
• Retry 429 and 503 after the Retry-After header.
• Retry 500 with backoff. If it persists, contact support with the time of the request.

Apps Docs Api Reference Introduction (`apps/docs/api-reference/introduction.mdx`) Copy Section

title: "Introduction" icon: "house" Copy Chapter

The Rallly API lets you create polls, read their options, results and participants, and delete them from your own tools. Every request is scoped to one space: the API key identifies the space, and every poll you create or read belongs to it. Webhooks tell your systems when a poll or a response changes, so you never have to poll for results.

The API requires a Pro plan.

Getting a key Copy Chapter

Only the space owner can create API keys, from Settings → API keys. See Authentication for the header format and how keys are handled.

Base URL Copy Chapter

https://api.rallly.co/v1

v1 is stable. Additive changes such as new endpoints or new optional fields may land at any time; breaking changes only arrive under a new version prefix. The changelog records both.

Conventions Copy Chapter

• Requests and responses are JSON. Send Content-Type: application/json with a body.
• List endpoints return the items in data. GET /polls is paginated: it returns a nextCursor beside data; pass it as the cursor query parameter for the next page, and it is null on the last page. GET /polls/:pollId/participants returns every participant in one response, and GET /polls/:pollId/participants/:participantId returns one.
• Timestamps are ISO 8601 instants in UTC. A date poll's options carry a floating YYYY-MM-DD date with no timezone; a time poll's options carry a startTime instant and a duration in minutes.
• A participant's availability is a list of spans, { start, end, allDay, modifiers }. A span matches an option by its time: start is the option's startTime, or midnight UTC of its date with allDay: true. end is exclusive.
• Request bodies are validated strictly. A field that is not in the schema is rejected rather than ignored, so a misspelt setting never silently falls back to its default.

Machine readable spec Copy Chapter

The OpenAPI document that generates this reference is served at https://api.rallly.co/v1/openapi.

Apps Docs Api Reference Migrating From The Private Api (`apps/docs/api-reference/migrating-from-the-private-api.mdx`) Copy Section

title: "Migrating from the private API" icon: "arrow-right-arrow-left" Copy Chapter

/v1 replaces the unversioned private API at https://app.rallly.co/api/private. The private API is frozen: it still answers, but it receives no new fields or endpoints, and everything new lands on /v1 only.

Your API keys, poll IDs, invite links and rate limits carry over unchanged. What changes is the base URL, the request and response shapes, and how errors look.

Summary of changes Copy Chapter

Global changes Copy Chapter

Base URL Copy Section

Replace the host and prefix. The poll paths under it are the same, with two exceptions: PATCH /polls/{pollId} is removed, and /docs has no v1 equivalent. Both are covered below.

https://app.rallly.co/api/private/polls   →   https://api.rallly.co/v1/polls

Error envelope Copy Section

Every v1 failure is JSON with the same shape, including cases the private API answered in plain text or with the validator's raw output. Branch on error.code; error.message is for humans.

{
  "success": false,
  "error": [
    {
      "expected": "string",
      "code": "invalid_type",
      "path": ["title"],
      "message": "Invalid input: expected string, received undefined"
    }
  ],
  "data": { "dates": ["2027-03-01"] }
}

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

UNAUTHORIZED, INVALID_AUTHORIZATION_HEADER, SPACE_NOT_PRO, ORGANIZER_NOT_MEMBER, TOO_MANY_OPTIONS, INAPPROPRIATE_CONTENT, POLL_NOT_FOUND, RATE_LIMIT_EXCEEDED and SERVICE_UNAVAILABLE keep their status codes and meanings. See Errors for the full list.

Strict request bodies Copy Section

The private API silently dropped fields it did not know, including spaceId, which it accepted but never used. v1 rejects any field outside the documented schema with VALIDATION_ERROR. Remove spaceId and any other extra fields before switching.

The poll resource Copy Section

Every endpoint that returns a poll (POST /polls, GET /polls, GET /polls/{pollId}) returns the same v1 shape. Compared with the private API:

• timezone is renamed timeZone.
• user is replaced by organizer, which adds id and email.
• kind is added: date or time. It tells you which option shape to expect.
• updatedAt is added. Compare it between reads to notice changes.
• The five poll settings are returned as booleans.
• participantCount is on every poll, not only list items.
• Options in a date poll carry date instead of startTime and duration: 0. Options in a time poll are unchanged.

{
  "data": {
    "id": "Xk3pQ9vLm2Ab",
    "title": "Team offsite",
    "description": null,
    "location": null,
    "timezone": null,
    "status": "open",
    "createdAt": "2026-09-10T12:00:00.000Z",
    "user": { "name": "Jessie Smith", "image": null },
    "options": [
      {
        "id": "cm5h8x2k40000q9l4f7e2d3an",
        "startTime": "2027-03-01T00:00:00.000Z",
        "duration": 0
      }
    ],
    "adminUrl": "https://app.rallly.co/poll/Xk3pQ9vLm2Ab",
    "inviteUrl": "https://rallly.co/invite/Xk3pQ9vLm2Ab"
  }
}

{
  "data": {
    "id": "Xk3pQ9vLm2Ab",
    "title": "Team offsite",
    "description": null,
    "location": null,
    "timeZone": null,
    "status": "open",
    "kind": "date",
    "createdAt": "2026-09-10T12:00:00.000Z",
    "updatedAt": "2026-09-10T12:00:00.000Z",
    "organizer": {
      "id": "cm3f7d1qa0000t2k9c6b8h4jr",
      "name": "Jessie Smith",
      "email": "[email protected]",
      "image": null
    },
    "requireEmail": false,
    "hideParticipants": false,
    "hideScores": false,
    "disableComments": true,
    "allowTentativeVotes": true,
    "participantCount": 0,
    "options": [
      { "id": "cm5h8x2k40000q9l4f7e2d3an", "date": "2027-03-01" }
    ],
    "adminUrl": "https://app.rallly.co/poll/Xk3pQ9vLm2Ab",
    "inviteUrl": "https://rallly.co/invite/Xk3pQ9vLm2Ab"
  }
}

Endpoints Copy Chapter

Create a poll Copy Section

POST /api/private/polls → POST /v1/polls

Status code. v1 responds 201 Created instead of 200 OK. A client that checks for exactly 200 will treat every successful create as a failure.

Request. The private API chose the poll type from whether you sent dates or slots. v1 takes an explicit kind and puts every option under options. Each request option is the response option without its id: { date } for a date poll, { startTime, duration? } for a time poll. The body is strict, so the other response fields (id, status, createdAt, participantCount and so on) must not be sent.

Date polls:

{
  "title": "Team offsite",
  "dates": ["2027-03-01", "2027-03-02", "2027-03-03"]
}

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

Time polls: the slots wrapper is gone. duration and timeZone move to the top level, explicit times become options objects, and slot generators move to their own generators array.

{
  "title": "Project kickoff",
  "location": "Zoom",
  "slots": {
    "duration": 60,
    "timezone": "Europe/London",
    "times": [
      "2027-03-01T09:00:00",
      {
        "startDate": "2027-03-08",
        "endDate": "2027-03-12",
        "days": ["mon", "wed"],
        "startTime": "14:00",
        "endTime": "17:00",
        "interval": 90
      }
    ]
  }
}

{
  "title": "Project kickoff",
  "kind": "time",
  "location": "Zoom",
  "timeZone": "Europe/London",
  "duration": 60,
  "options": [{ "startTime": "2027-03-01T09:00:00" }],
  "generators": [
    {
      "startDate": "2027-03-08",
      "endDate": "2027-03-12",
      "days": ["mon", "wed"],
      "from": "14:00",
      "to": "17:00",
      "interval": 90
    }
  ]
}

Field by field:

Everything else (description, location, requireEmail, hideParticipants, hideScores, disableComments, allowTentativeVotes, organizer) is unchanged. The interpretation of a startTime without an offset is also unchanged: wall clock time in timeZone when set, floating otherwise.

Generator validation. The private API expanded a generator and only then failed with NO_OPTIONS_GENERATED if nothing came out. v1 rejects an impossible generator up front with VALIDATION_ERROR naming the field: to not later than from, a daily window shorter than duration, or a date range containing none of the listed days. Times in a generator are HH:mm; the private API also accepted seconds.

Response. The full poll, in the v1 shape.

List polls Copy Section

GET /api/private/polls → GET /v1/polls

Request. Unchanged. status, cursor and limit work the same way, and nextCursor is still returned beside data.

Response. Each item is the full v1 poll. The private API's list items already carried participantCount; the rest of the new fields are additions, and the renames (timezone, user, date options) apply here too.

Get a poll Copy Section

GET /api/private/polls/{pollId} → GET /v1/polls/{pollId}

Request. Unchanged.

Response. The v1 poll. Note that participantCount is now included, so a client that called both GET /polls/{pollId} and GET /polls/{pollId}/results just to count participants can drop the second call.

Update a poll Copy Section

PATCH /api/private/polls/{pollId} → removed

Polls close on their own once every option is in the past. To close a poll earlier, or to reopen one, use the app. If your integration polled results and stopped once the poll was closed, keep reading status from GET /polls/{pollId}/results; that part is unchanged.

Get poll results Copy Section

GET /api/private/polls/{pollId}/results → GET /v1/polls/{pollId}/results

Request. Unchanged.

Response. Three changes:

• kind is added at the top level.
• Options in a date poll carry date instead of startTime and duration: 0, matching the poll resource.
• votes is dense. The private API omitted any vote type with zero votes, so an option nobody voted on had votes: []. v1 lists every vote type the poll offers, in display order, with count: 0 where nobody chose it. A client that summed votes or looked a type up by type keeps working; a client that treated an empty array as "no votes" must check the counts instead.

{
  "data": {
    "pollId": "Xk3pQ9vLm2Ab",
    "status": "open",
    "participantCount": 2,
    "options": [
      {
        "id": "cm5h8x2k40000q9l4f7e2d3an",
        "startTime": "2027-03-01T00:00:00.000Z",
        "duration": 0,
        "votes": [{ "type": "yes", "count": 2 }],
        "score": 2002,
        "isTopChoice": true
      },
      {
        "id": "cm5h8x2k40001q9l4b8f3e4bo",
        "startTime": "2027-03-02T00:00:00.000Z",
        "duration": 0,
        "votes": [],
        "score": 0,
        "isTopChoice": false
      }
    ],
    "highScore": 2002
  }
}

{
  "data": {
    "pollId": "Xk3pQ9vLm2Ab",
    "kind": "date",
    "status": "open",
    "participantCount": 2,
    "options": [
      {
        "id": "cm5h8x2k40000q9l4f7e2d3an",
        "date": "2027-03-01",
        "votes": [
          { "type": "yes", "count": 2 },
          { "type": "ifNeedBe", "count": 0 },
          { "type": "no", "count": 0 }
        ],
        "score": 2002,
        "isTopChoice": true
      },
      {
        "id": "cm5h8x2k40001q9l4b8f3e4bo",
        "date": "2027-03-02",
        "votes": [
          { "type": "yes", "count": 0 },
          { "type": "ifNeedBe", "count": 0 },
          { "type": "no", "count": 0 }
        ],
        "score": 0,
        "isTopChoice": false
      }
    ],
    "highScore": 2002
  }
}

score, isTopChoice and highScore are computed the same way today, but v1 documents score as opaque: sort by it and use isTopChoice or highScore to find the leaders, but do not decode it into vote counts or compare it across polls. Vote types are an open set in v1, so tolerate a type you do not recognise.

Get poll participants Copy Section

GET /api/private/polls/{pollId}/participants → GET /v1/polls/{pollId}/participants

Request. Unchanged.

Response. data is the array itself. The private API wrapped it in an object with pollId; v1 drops the wrapper, since you already know the poll ID from the URL. The participant fields (id, name, email, createdAt) and the ordering (oldest response first) are unchanged.

{
  "data": {
    "pollId": "Xk3pQ9vLm2Ab",
    "participants": [
      {
        "id": "cm5j2r8wb0003q9l4a1x6p0zt",
        "name": "Jessie Smith",
        "email": "[email protected]",
        "createdAt": "2026-09-11T08:30:00.000Z"
      }
    ]
  }
}

{
  "data": [
    {
      "id": "cm5j2r8wb0003q9l4a1x6p0zt",
      "name": "Jessie Smith",
      "email": "[email protected]",
      "createdAt": "2026-09-11T08:30:00.000Z"
    }
  ]
}

Delete a poll Copy Section

DELETE /api/private/polls/{pollId} → DELETE /v1/polls/{pollId}

Unchanged. Responds 200 with { "data": { "id", "deleted": true } }, or 404 POLL_NOT_FOUND.

OpenAPI document and docs page Copy Section

GET /api/private/openapi → GET /v1/openapi

The spec moves with the API. The Scalar page at /api/private/docs has no v1 equivalent; this site is the reference. Both spec endpoints are public and need no key.

Checklist Copy Chapter

1. Change the base URL to https://api.rallly.co/v1.
2. Accept 201 from POST /polls.
3. Rewrite create requests: add kind, replace dates and slots with options and generators, rename timezone to timeZone and the generator's startTime and endTime to from and to, and remove spaceId and any other undocumented fields.
4. Read timeZone instead of timezone, and organizer instead of user, in every poll response.
5. Branch on kind when reading options: date for date polls, startTime and duration for time polls.
6. In results, stop treating an empty votes array as "no votes"; read the counts.
7. Read participants from data directly.
8. Parse every error as { "error": { "code", "message" } } and drop any handling of the private API's validator output, DUPLICATE_DATES, NO_OPTIONS_GENERATED and TRANSITION_NOT_AVAILABLE.
9. Remove any call to PATCH /polls/{pollId}.

Apps Docs Api Reference Openapi.Json (`apps/docs/api-reference/openapi.json`) Copy Section

{
"openapi": "3.1.0",
"info": {
"title": "Rallly API",
"description": "## Versioning\n\nv1 is stable. Additive changes (new endpoints, new optional fields) may land on this path at any time; breaking changes only arrive under a new version prefix.\n\n## Rate limits\n\nAll endpoints share two limits per space: 60 requests per minute and 5000 requests per day. Both are fixed windows that open with the first request and reset when they expire. Both limits are per space, not per API key, so creating additional keys does not increase throughput.\n\nEvery response from an authenticated request includes the standard RateLimit-* headers. Responses sent before the limiter runs (401, 403, and the maintenance 503) do not. RateLimit-Policy lists both limits; RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset describe whichever limit is closest to being exhausted. When either limit is exceeded the API responds with 429 Too Many Requests, a RATE_LIMIT_EXCEEDED error body, and a Retry-After header indicating how many seconds to wait before retrying.\n\nIf the rate limit store cannot be reached the API fails closed and responds with 503 Service Unavailable, a SERVICE_UNAVAILABLE error body, and a Retry-After header.\n\n## Dates and times\n\nEvery poll has a kind. A date poll offers calendar days: each option carries a date in YYYY-MM-DD format, which is a floating date with no time component and no timezone, so never convert it through a timezone. A time poll offers time slots: each option carries a startTime as an ISO 8601 instant in UTC and a duration in minutes; convert startTime into the poll's timeZone (or the viewer's) for display. Timestamps such as createdAt and updatedAt are always ISO 8601 instants in UTC.\n\n## Request bodies\n\nRequest bodies are validated strictly: a field that is not part of the documented schema is rejected with VALIDATION_ERROR rather than ignored, so a misspelt setting never silently falls back to its default.\n\n## Enums\n\nVote types are an open set. The built-in values are yes, ifNeedBe and no; new types may be added without a version change, so clients must tolerate values they do not recognise. status and kind are closed sets.\n\n## Lists\n\nList endpoints return the items in data. GET /polls is paginated: it returns a nextCursor beside data; pass it as the cursor query parameter to fetch the next page, and it is null on the last page. GET /polls/:pollId/participants returns every participant in one response.\n\n## Errors\n\nEvery failure is application/json with the shape { \"error\": { \"code\", \"message\" } }. code is stable and safe to branch on; message is human-readable and may change. VALIDATION_ERROR messages name each offending field.\n\n| Status | Code | When |\n| --- | --- | --- |\n| 400 | VALIDATION_ERROR | The body or query string did not match the schema, contained an unknown field, or the body was not valid JSON |\n| 400 | INVALID_AUTHORIZATION_HEADER | The Authorization header is not Bearer <key> |\n| 400 | ORGANIZER_NOT_MEMBER | The organizer email is not a member of the space |\n| 400 | TOO_MANY_OPTIONS | More than the maximum number of poll options |\n| 400 | CONFERENCING_UNAVAILABLE | The requested video call provider is not offered on this instance |\n| 400 | CONFERENCING_NOT_CONNECTED | The organizer has not connected an account for the requested video call provider |\n| 400 | INAPPROPRIATE_CONTENT | The title, description, location or video call was flagged by content moderation |\n| 401 | UNAUTHORIZED | The API key is missing, invalid, expired or revoked, or its owner is banned |\n| 403 | SPACE_NOT_PRO | The space behind the key has no Pro subscription |\n| 404 | NOT_FOUND | No route matches the method and path |\n| 404 | POLL_NOT_FOUND | The poll does not exist or belongs to another space |\n| 404 | PARTICIPANT_NOT_FOUND | The participant does not exist or belongs to another poll |\n| 429 | RATE_LIMIT_EXCEEDED | A rate limit window is exhausted |\n| 503 | SERVICE_UNAVAILABLE | Maintenance, or the rate limit store cannot be reached |\n| 500 | INTERNAL_ERROR | Unexpected failure; the request id is logged |",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.rallly.co"
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
},
"schemas": {
"Poll": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "Xk3pQ9vLm2Ab"
},
"title": {
"type": "string",
"example": "Team sync"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "Pick a time that works for everyone"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "Conference Room A"
},
"conferencing": {
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "meet"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "zoom"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "teams"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "webex"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "custom"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"uri": {
"type": "string",
"format": "uri"
}
},
"required": [
"provider",
"label"
]
}
]
},
{
"type": "null"
}
],
"description": "The video call for the event, or null. A meet, zoom, teams or webex entry has no link until the poll is finalized; a custom entry carries the organizer's label and, when given, the link.",
"example": {
"provider": "zoom"
}
},
"timeZone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "Europe/London"
},
"status": {
"$ref": "#/components/schemas/PollStatus"
},
"kind": {
"$ref": "#/components/schemas/PollKind"
},
"createdAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-10T12:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "When the poll was last modified. Changes when the poll's details, settings or status change.",
"example": "2025-01-12T08:30:00.000Z"
},
"organizer": {
"anyOf": [
{
"$ref": "#/components/schemas/PollOrganizer"
},
{
"type": "null"
}
],
"description": "The space member the poll belongs to. null when the organizer's account no longer exists."
},
"requireEmail": {
"type": "boolean",
"description": "Whether participants must provide their email address",
"example": false
},
"hideParticipants": {
"type": "boolean",
"description": "Whether participant names are hidden from other participants",
"example": false
},
"hideScores": {
"type": "boolean",
"description": "Whether vote counts are hidden from participants",
"example": false
},
"disableComments": {
"type": "boolean",
"description": "Whether the comments section is disabled",
"example": true
},
"allowTentativeVotes": {
"type": "boolean",
"description": "Whether participants may cast the tentative "if need be" vote",
"example": true
},
"participantCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of participants who have responded to the poll",
"example": 3
},
"options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PollOption"
}
},
"adminUrl": {
"type": "string",
"example": "https://app.rallly.co/poll/Xk3pQ9vLm2Ab"
},
"inviteUrl": {
"type": "string",
"example": "https://rallly.co/invite/Xk3pQ9vLm2Ab"
}
},
"required": [
"id",
"title",
"description",
"location",
"conferencing",
"timeZone",
"status",
"kind",
"createdAt",
"updatedAt",
"organizer",
"requireEmail",
"hideParticipants",
"hideScores",
"disableComments",
"allowTentativeVotes",
"participantCount",
"options",
"adminUrl",
"inviteUrl"
]
},
"PollStatus": {
"type": "string",
"enum": [
"open",
"closed",
"scheduled",
"canceled"
]
},
"PollKind": {
"type": "string",
"enum": [
"date",
"time"
],
"description": "Whether the poll offers calendar dates (date) or time slots (time). Determines which option shape the poll uses: every option in a date poll has a date, every option in a time poll has a startTime and duration.",
"example": "time"
},
"PollOrganizer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm3f7d1qa0000t2k9c6b8h4jr"
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"format": "email",
"example": "[email protected]"
},
"image": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "https://cdn.rallly.co/avatars/cm3f7d1qa0000t2k9c6b8h4jr.jpg"
}
},
"required": [
"id",
"name",
"email",
"image"
]
},
"PollOption": {
"anyOf": [
{
"$ref": "#/components/schemas/DateOption"
},
{
"$ref": "#/components/schemas/TimeOption"
}
],
"description": "A poll option. The shape follows the poll's kind: a DateOption for date polls, a TimeOption for time polls."
},
"DateOption": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5h8x2k40000q9l4f7e2d3an"
},
"date": {
"type": "string",
"format": "date",
"description": "Calendar date in YYYY-MM-DD format. All-day options are floating dates with no time component and no timezone.",
"example": "2025-01-15"
}
},
"required": [
"id",
"date"
],
"description": "An all-day option. Only present in polls with kind: date."
},
"TimeOption": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5h8x2k40000q9l4f7e2d3an"
},
"startTime": {
"type": "string",
"format": "date-time",
"description": "Start of the slot as an ISO 8601 instant in UTC.",
"example": "2025-01-15T09:00:00.000Z"
},
"duration": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Duration in minutes.",
"example": 30
}
},
"required": [
"id",
"startTime",
"duration"
],
"description": "A time slot. Only present in polls with kind: time."
},
"PollResponse": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Poll"
}
},
"required": [
"data"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code. The full list is in the API description.",
"example": "VALIDATION_ERROR"
},
"message": {
"type": "string",
"description": "Human-readable explanation. For VALIDATION_ERROR it names each offending field, e.g. title: Invalid input: expected string, received undefined; dates.0: Invalid ISO date.",
"example": "title: Invalid input: expected string, received undefined"
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
},
"CreateDatePollInput": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Team sync"
},
"kind": {
"type": "string",
"const": "date",
"description": "Participants vote on whole days."
},
"description": {
"example": "Pick a time that works for everyone",
"type": "string",
"maxLength": 1000
},
"location": {
"description": "Where the event takes place, as free text.",
"example": "Conference Room A",
"type": "string",
"maxLength": 255
},
"conferencing": {
"description": "The video call for the event. meet, zoom, teams and webex need the organizer to have connected that account in their Conferencing settings; the meeting link is created when the poll is finalized. custom names any call, with an optional link participants join with.",
"examples": [
{
"provider": "zoom"
},
{
"provider": "custom",
"label": "Microsoft Teams",
"uri": "https://teams.microsoft.com/l/meetup-join/abc"
}
],
"oneOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "meet"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "zoom"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "teams"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "webex"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "custom"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"uri": {
"type": "string",
"format": "uri"
}
},
"required": [
"provider",
"label"
]
}
]
},
"requireEmail": {
"description": "Require participants to provide their email address",
"example": true,
"type": "boolean"
},
"hideParticipants": {
"description": "Hide participant names from other participants",
"example": false,
"type": "boolean"
},
"hideScores": {
"description": "Hide vote counts from participants",
"example": false,
"type": "boolean"
},
"disableComments": {
"description": "Disable the comments section. Defaults to true: new polls have comments disabled unless this is set to false.",
"example": false,
"type": "boolean"
},
"allowTentativeVotes": {
"description": "Allow participants to answer "if need be" as well as yes and no. Defaults to true.",
"example": true,
"type": "boolean"
},
"organizer": {
"description": "Organizer of the poll. Defaults to the space owner if not provided. The organizer must be a member of the space.",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address of the organizer",
"example": "[email protected]"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"options": {
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/DateOptionInput"
},
"description": "Calendar days to offer. Dates are floating calendar days with no timezone, so never convert them through one. Duplicates are removed."
}
},
"required": [
"title",
"kind",
"options"
],
"additionalProperties": false,
"title": "Date poll"
},
"DateOptionInput": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Calendar day to offer, as a floating YYYY-MM-DD date.",
"example": "2027-03-01"
}
},
"required": [
"date"
],
"additionalProperties": false,
"title": "Date option",
"description": "One all-day option. The same shape DateOption returns."
},
"CreateTimePollInput": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Team sync"
},
"kind": {
"type": "string",
"const": "time",
"description": "Participants vote on time slots."
},
"description": {
"example": "Pick a time that works for everyone",
"type": "string",
"maxLength": 1000
},
"location": {
"description": "Where the event takes place, as free text.",
"example": "Conference Room A",
"type": "string",
"maxLength": 255
},
"conferencing": {
"description": "The video call for the event. meet, zoom, teams and webex need the organizer to have connected that account in their Conferencing settings; the meeting link is created when the poll is finalized. custom names any call, with an optional link participants join with.",
"examples": [
{
"provider": "zoom"
},
{
"provider": "custom",
"label": "Microsoft Teams",
"uri": "https://teams.microsoft.com/l/meetup-join/abc"
}
],
"oneOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "meet"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "zoom"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "teams"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "webex"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "custom"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"uri": {
"type": "string",
"format": "uri"
}
},
"required": [
"provider",
"label"
]
}
]
},
"requireEmail": {
"description": "Require participants to provide their email address",
"example": true,
"type": "boolean"
},
"hideParticipants": {
"description": "Hide participant names from other participants",
"example": false,
"type": "boolean"
},
"hideScores": {
"description": "Hide vote counts from participants",
"example": false,
"type": "boolean"
},
"disableComments": {
"description": "Disable the comments section. Defaults to true: new polls have comments disabled unless this is set to false.",
"example": false,
"type": "boolean"
},
"allowTentativeVotes": {
"description": "Allow participants to answer "if need be" as well as yes and no. Defaults to true.",
"example": true,
"type": "boolean"
},
"organizer": {
"description": "Organizer of the poll. Defaults to the space owner if not provided. The organizer must be a member of the space.",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address of the organizer",
"example": "[email protected]"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"timeZone": {
"description": "IANA time zone the times are written in. Datetime strings without an offset are interpreted in this zone. If omitted, offset-less datetimes are floating times (no conversion) and the poll has no time zone.",
"example": "Europe/London",
"type": "string"
},
"duration": {
"description": "Default slot length in minutes. Required when generators is set or an option omits its own duration.",
"example": 30,
"type": "integer",
"minimum": 15,
"maximum": 1440
},
"options": {
"description": "Explicit slots. Provide options, generators or both. Duplicates are removed.",
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/TimeOptionInput"
}
},
"generators": {
"description": "Slot generators. Each expands into recurring slots from a schedule and the result is appended to options.",
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/SlotGenerator"
}
}
},
"required": [
"title",
"kind"
],
"additionalProperties": false,
"title": "Time poll"
},
"TimeOptionInput": {
"type": "object",
"properties": {
"startTime": {
"type": "string",
"format": "date-time",
"description": "ISO datetime start time. A string without an offset is wall clock time in timeZone when that is set (2027-03-01T09:00:00 with timeZone: Europe/London means 09:00 in London) and a floating time with no conversion otherwise. A string with an offset or Z is an absolute instant.",
"example": "2027-03-01T09:00:00"
},
"duration": {
"description": "Length of this slot in minutes. Defaults to the poll's duration.",
"example": 30,
"type": "integer",
"minimum": 15,
"maximum": 1440
}
},
"required": [
"startTime"
],
"additionalProperties": false,
"title": "Time option",
"description": "One time slot. The same shape TimeOption returns."
},
"SlotGenerator": {
"type": "object",
"properties": {
"startDate": {
"type": "string",
"format": "date",
"description": "First day of the range to generate slots on, inclusive.",
"example": "2027-03-01"
},
"endDate": {
"type": "string",
"format": "date",
"description": "Last day of the range, inclusive. The range must span fewer than 366 days.",
"example": "2027-03-05"
},
"days": {
"default": [
"mon",
"tue",
"wed",
"thu",
"fri",
"sat",
"sun"
],
"description": "Days of the week to generate slots on. Days in the range that are not listed are skipped. Defaults to every day.",
"example": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"mon",
"tue",
"wed",
"thu",
"fri",
"sat",
"sun"
]
}
},
"from": {
"type": "string",
"pattern": "^(?:[01]\d|2[0-3]):[0-5]\d$",
"description": "Earliest slot start on each day, as a wall clock time in timeZone.",
"example": "09:00"
},
"to": {
"type": "string",
"pattern": "^(?:[01]\d|2[0-3]):[0-5]\d$",
"description": "End of the daily window, as a wall clock time in timeZone. A slot is only generated if it ends at or before this time.",
"example": "17:00"
},
"interval": {
"description": "Minutes between consecutive slot starts. Defaults to duration, which produces back to back slots.",
"example": 60,
"type": "integer",
"minimum": 15,
"maximum": 1440
}
},
"required": [
"startDate",
"endDate",
"from",
"to"
],
"additionalProperties": false,
"title": "Slot generator",
"description": "Expands into one slot of duration minutes every interval minutes between from and to, on each listed day of the week between startDate and endDate. Slots that would not end by to are not generated."
},
"CreatePollInput": {
"oneOf": [
{
"$ref": "#/components/schemas/CreateDatePollInput"
},
{
"$ref": "#/components/schemas/CreateTimePollInput"
}
],
"description": "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.",
"discriminator": {
"propertyName": "kind",
"mapping": {
"date": "#/components/schemas/CreateDatePollInput",
"time": "#/components/schemas/CreateTimePollInput"
}
}
},
"ListPollsResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Poll"
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Cursor to fetch the next page. null when there are no more results.",
"example": "Xk3pQ9vLm2Ab"
}
},
"required": [
"data",
"nextCursor"
]
},
"OptionResult": {
"anyOf": [
{
"$ref": "#/components/schemas/DateOptionResult"
},
{
"$ref": "#/components/schemas/TimeOptionResult"
}
],
"description": "Results for one option. The shape follows the poll's kind: a DateOptionResult for date polls, a TimeOptionResult for time polls."
},
"DateOptionResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5h8x2k40000q9l4f7e2d3an"
},
"date": {
"type": "string",
"format": "date",
"description": "Calendar date in YYYY-MM-DD format. All-day options are floating dates with no time component and no timezone.",
"example": "2025-01-15"
},
"votes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VoteCount"
},
"description": "One entry per vote type the poll offers, in display order, always present with count: 0 when nobody chose it."
},
"score": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Opaque ranking value: higher is better. Only comparable between options in the same response. The formula is not part of the contract and may change; do not decode it into vote counts, compare it across polls or threshold on it. Use votes for counts.",
"example": 5004
},
"isTopChoice": {
"type": "boolean",
"description": "Whether this option has the highest score in the poll. Several options share the flag when they tie. Always false when nobody has voted.",
"example": true
}
},
"required": [
"id",
"date",
"votes",
"score",
"isTopChoice"
],
"description": "Results for an all-day option. Only present in polls with kind: date."
},
"VoteCount": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/VoteType"
},
"count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of participants who gave this answer.",
"example": 3
}
},
"required": [
"type",
"count"
]
},
"VoteType": {
"type": "string",
"description": "A participant's answer for an option. The built-in types are yes (available), ifNeedBe (available if needed) and no (unavailable). New types may be added without a version change, so treat unknown values as a vote of an unfamiliar type rather than an error.",
"example": "yes"
},
"TimeOptionResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5h8x2k40000q9l4f7e2d3an"
},
"startTime": {
"type": "string",
"format": "date-time",
"description": "Start of the slot as an ISO 8601 instant in UTC.",
"example": "2025-01-15T09:00:00.000Z"
},
"duration": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Duration in minutes.",
"example": 30
},
"votes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VoteCount"
},
"description": "One entry per vote type the poll offers, in display order, always present with count: 0 when nobody chose it."
},
"score": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Opaque ranking value: higher is better. Only comparable between options in the same response. The formula is not part of the contract and may change; do not decode it into vote counts, compare it across polls or threshold on it. Use votes for counts.",
"example": 5004
},
"isTopChoice": {
"type": "boolean",
"description": "Whether this option has the highest score in the poll. Several options share the flag when they tie. Always false when nobody has voted.",
"example": true
}
},
"required": [
"id",
"startTime",
"duration",
"votes",
"score",
"isTopChoice"
],
"description": "Results for a time slot. Only present in polls with kind: time."
},
"GetPollResultsResponse": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"pollId": {
"type": "string",
"example": "Xk3pQ9vLm2Ab"
},
"kind": {
"$ref": "#/components/schemas/PollKind"
},
"status": {
"description": "Current poll status. Polls close automatically when all options are in the past.",
"example": "open",
"$ref": "#/components/schemas/PollStatus"
},
"participantCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Total number of participants",
"example": 8
},
"options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OptionResult"
}
},
"highScore": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The highest score among the options. Opaque like score: use it to identify the leading options, not as a measurement.",
"example": 5004
}
},
"required": [
"pollId",
"kind",
"status",
"participantCount",
"options",
"highScore"
]
}
},
"required": [
"data"
]
},
"Participant": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5j2r8wb0003q9l4a1x6p0zt"
},
"name": {
"type": "string",
"example": "Jane Smith"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "[email protected]"
},
"createdAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-10T12:00:00.000Z"
},
"availability": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AvailabilitySpan"
},
"description": "When the participant is available: one span per option they can make, in start order, not merged. Options they cannot make, or did not answer, are absent. Each span matches an option of the poll by its time."
}
},
"required": [
"id",
"name",
"email",
"createdAt",
"availability"
]
},
"AvailabilitySpan": {
"type": "object",
"properties": {
"start": {
"type": "string",
"format": "date-time",
"description": "Start of the span, inclusive, as a UTC instant.",
"example": "2025-01-15T09:00:00.000Z"
},
"end": {
"type": "string",
"format": "date-time",
"description": "End of the span, exclusive, as a UTC instant: a 30 minute slot starting at 09:00 ends at 09:30, and the instant 09:30 is not in it.",
"example": "2025-01-15T09:30:00.000Z"
},
"allDay": {
"type": "boolean",
"description": "True for a whole calendar day. The day is a floating date with no timezone, given as start at 00:00:00Z on that date and end at 00:00:00Z on the next; read the date from start and ignore the time of day.",
"example": false
},
"modifiers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Qualifiers on the availability. ifNeedBe means the participant can make it but would rather not. New modifiers may be added without a version change; one you do not recognise still leaves the span available.",
"example": [
"ifNeedBe"
]
}
},
"required": [
"start",
"end",
"allDay",
"modifiers"
]
},
"GetPollParticipantsResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Participant"
}
}
},
"required": [
"data"
]
},
"GetPollParticipantResponse": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Participant"
}
},
"required": [
"data"
]
},
"DeletePollResponse": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "Xk3pQ9vLm2Ab"
},
"deleted": {
"type": "boolean",
"const": true,
"example": true
}
},
"required": [
"id",
"deleted"
]
}
},
"required": [
"data"
]
}
}
},
"paths": {
"/v1/polls": {
"post": {
"operationId": "postV1Polls",
"tags": [
"Polls"
],
"summary": "Create a poll",
"description": "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.\n\n## Date poll\n\nPass 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.\n\njson\n{\n \"title\": \"Team offsite\",\n \"kind\": \"date\",\n \"options\": [{ \"date\": \"2027-03-01\" }, { \"date\": \"2027-03-02\" }, { \"date\": \"2027-03-03\" }]\n}\n\n\n## Time poll\n\nPass 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.\n\n### Explicit slots\n\nEach 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.\n\njson\n{\n \"title\": \"Kickoff\",\n \"kind\": \"time\",\n \"timeZone\": \"Europe/London\",\n \"duration\": 60,\n \"options\": [\n { \"startTime\": \"2027-03-01T09:00:00\" },\n { \"startTime\": \"2027-03-02T14:00:00\", \"duration\": 90 }\n ]\n}\n\n\n### Slot generators\n\nEach 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.\n\njson\n{\n \"title\": \"Interview availability\",\n \"kind\": \"time\",\n \"timeZone\": \"America/New_York\",\n \"duration\": 30,\n \"generators\": [\n {\n \"startDate\": \"2027-03-01\",\n \"endDate\": \"2027-03-05\",\n \"days\": [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\"],\n \"from\": \"09:00\",\n \"to\": \"12:00\",\n \"interval\": 60\n }\n ]\n}\n\n\nThis 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.\n\n| Field | Meaning |\n| --- | --- |\n| startDate, endDate | The date range, inclusive. Fewer than 366 days. |\n| days | Days of the week to include: mon to sun. Optional; defaults to every day. |\n| from | Earliest slot start on each day, HH:mm in timeZone. |\n| 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. |\n| interval | Minutes between slot starts. Optional; defaults to duration, which gives back to back slots. |\n\nA 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.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"201": {
"description": "Poll created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PollResponse"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a WWW-Authenticate header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a Retry-After header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a Retry-After header. Maintenance responses are sent before the rate limiter runs and carry no RateLimit-* headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePollInput"
},
"examples": {
"Date poll": {
"summary": "Date poll (all-day options)",
"description": "Let participants pick between calendar days. Each option is one all-day date.",
"value": {
"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"
}
]
}
},
"Time poll with explicit slots": {
"summary": "Time poll (explicit slots)",
"description": "Offer specific time slots. Datetimes without an offset are wall clock times in timeZone; this example offers 09:00 and 14:00 in London. Append Z or an offset for an absolute instant instead. A slot may override the poll's duration.",
"value": {
"title": "Project kickoff",
"kind": "time",
"location": "Zoom",
"timeZone": "Europe/London",
"duration": 60,
"options": [
{
"startTime": "2027-03-01T09:00:00"
},
{
"startTime": "2027-03-01T14:00:00",
"duration": 90
}
]
}
},
"Time poll with a slot generator": {
"summary": "Time poll (slot generator)",
"description": "Expand recurring slots across a date range. This example generates 30 minute slots at 09:00, 10:00 and 11:00 (New York time) every weekday from 1 to 5 March.",
"value": {
"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
}
]
}
},
"Time poll mixing slots and a generator": {
"summary": "Time poll (explicit slots + generator)",
"description": "options and generators combine. When interval is omitted it defaults to duration, so this generator produces back to back 90 minute slots at 14:00 and 15:30 on Monday and Wednesday.",
"value": {
"title": "Product workshop",
"kind": "time",
"timeZone": "Europe/Berlin",
"duration": 90,
"options": [
{
"startTime": "2027-03-06T10:00:00"
}
],
"generators": [
{
"startDate": "2027-03-08",
"endDate": "2027-03-10",
"days": [
"mon",
"wed"
],
"from": "14:00",
"to": "17:00"
}
]
}
}
}
}
}
}
},
"get": {
"operationId": "getV1Polls",
"tags": [
"Polls"
],
"summary": "List polls",
"description": "Lists the polls in the space associated with the API key, sorted by creation date (newest first).\n\nUse the status query parameter to only return polls in a given state — for example status=open to sweep polls that are still collecting responses. Results are paginated with a cursor: pass the nextCursor value from the previous response to fetch the next page.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListPollsResponse"
}
}
}
},
"400": {
"description": "Invalid query parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a WWW-Authenticate header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a Retry-After header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a Retry-After header. Maintenance responses are sent before the rate limiter runs and carry no RateLimit-* headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "status",
"schema": {
"example": "open",
"$ref": "#/components/schemas/PollStatus"
},
"description": "Filter polls by status. Omit to include all statuses."
},
{
"in": "query",
"name": "cursor",
"schema": {
"example": "Xk3pQ9vLm2Ab",
"type": "string"
},
"description": "Cursor for pagination. Pass the nextCursor value from the previous response to fetch the next page."
},
{
"in": "query",
"name": "limit",
"schema": {
"default": 20,
"example": 20,
"type": "integer",
"minimum": 1,
"maximum": 100
},
"description": "Number of polls to return per page (1-100)."
}
]
}
},
"/v1/polls/{pollId}": {
"get": {
"operationId": "getV1PollsByPollId",
"tags": [
"Polls"
],
"summary": "Get a poll",
"description": "Retrieves a poll by ID with its options, settings, organizer and participantCount. The poll must belong to the space associated with the API key. Compare updatedAt between reads to notice changes.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PollResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a WWW-Authenticate header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a Retry-After header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a Retry-After header. Maintenance responses are sent before the rate limiter runs and carry no RateLimit-* headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
}
]
},
"delete": {
"operationId": "deleteV1PollsByPollId",
"tags": [
"Polls"
],
"summary": "Delete a poll",
"description": "Deletes a poll by ID. The poll must belong to the space associated with the API key.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Poll deleted successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletePollResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a WWW-Authenticate header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a Retry-After header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a Retry-After header. Maintenance responses are sent before the rate limiter runs and carry no RateLimit-* headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
}
]
}
},
"/v1/polls/{pollId}/results": {
"get": {
"operationId": "getV1PollsByPollIdResults",
"tags": [
"Polls"
],
"summary": "Get poll results",
"description": "Retrieves aggregated voting results for a poll: vote counts per option without individual participant data. Use GET /polls/:pollId/participants to list who responded.\n\nvotes lists every vote type the poll offers with its count, zero included. score is an opaque ranking value: sort by it to order options from best to worst, and use isTopChoice or highScore to find the leading options. Its formula is not part of the contract, so do not decode it, compare it across polls or threshold on it.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPollResultsResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a WWW-Authenticate header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a Retry-After header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a Retry-After header. Maintenance responses are sent before the rate limiter runs and carry no RateLimit-* headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
}
]
}
},
"/v1/polls/{pollId}/participants": {
"get": {
"operationId": "getV1PollsByPollIdParticipants",
"tags": [
"Polls"
],
"summary": "List poll participants",
"description": "Lists every participant of a poll in one response, oldest response first, each with their availability. The poll must belong to the space associated with the API key.\n\nFor aggregate counts per option use the results endpoint.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPollParticipantsResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a WWW-Authenticate header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a Retry-After header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a Retry-After header. Maintenance responses are sent before the rate limiter runs and carry no RateLimit-* headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
}
]
}
},
"/v1/polls/{pollId}/participants/{participantId}": {
"get": {
"operationId": "getV1PollsByPollIdParticipantsByParticipantId",
"tags": [
"Polls"
],
"summary": "Get a poll participant",
"description": "Returns one participant of a poll with their availability. The poll must belong to the space associated with the API key. This is the endpoint to call from a poll.participant.* webhook.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPollParticipantResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a WWW-Authenticate header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found (POLL_NOT_FOUND) or participant not found (PARTICIPANT_NOT_FOUND)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a Retry-After header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a Retry-After header. Maintenance responses are sent before the rate limiter runs and carry no RateLimit-* headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "participantId",
"required": true
}
]
}
}
}
}

Apps Docs Api Reference Rate Limits (`apps/docs/api-reference/rate-limits.mdx`) Copy Section

title: "Rate limits" icon: "gauge-high" Copy Chapter

All endpoints share two limits per space:

Both are fixed windows that open with the first request and reset when they expire. Limits apply to the space, not the key, so creating more keys does not increase throughput.

Headers Copy Chapter

Every response to an authenticated request carries the standard RateLimit-* headers:

Responses sent before the limiter runs, such as 401, 403 and the maintenance 503, do not include them.

Exceeding a limit Copy Chapter

When either limit is exhausted the API responds with 429 Too Many Requests, a RATE_LIMIT_EXCEEDED error body and a Retry-After header with the number of seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 23

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after the time indicated in the Retry-After header."
  }
}

Wait for Retry-After before retrying. Do not retry on a fixed interval: a client that ignores the header spends its next window on requests that fail.

Store outages Copy Chapter

If the rate limit store cannot be reached the API fails closed and responds with 503 Service Unavailable, a SERVICE_UNAVAILABLE error body and a Retry-After header.

Apps Docs Api Reference Webhooks (`apps/docs/api-reference/webhooks.mdx`) Copy Section

title: "Overview" sidebarTitle: "Overview" icon: "webhook" Copy Chapter

Webhooks tell your own systems about poll and participant changes as they happen, so an integration never has to poll the API for results. Each endpoint you register receives a signed POST for every event it subscribes to.

Webhooks require a Pro plan.

Adding an endpoint Copy Chapter

1. As the space owner, open Settings → Webhooks and choose Add webhook.
2. Enter the URL. It must be https, on a public host, with no credentials in it.
3. Pick the events to receive. Every event is selected by default; you can change the selection later.
4. Copy the signing secret. It is shown once. If you lose it, delete the endpoint and add it again.

A space can have up to five endpoints. A new endpoint starts receiving events from the moment it is created; history is never replayed.

To check the endpoint before any poll changes, choose Send test event from its menu. Rallly sends a signed ping and shows the response it got back.

What an event carries Copy Chapter

An event says what happened and to which poll or participant. It references both by id and carries only the facts that belong to the event itself: the reason a poll closed, the time it was scheduled for. It does not carry the poll's title, options or settings, or the participant's details. Fetch the API when you need them; the fetch returns the current state, where a snapshot in the event would already be stale by the time a retry lands.

See Events for the envelope, the headers and every event with its payload.

Delivery Copy Chapter

Every delivery is a POST with a JSON body. Respond with any 2xx status within 10 seconds; the response body is ignored. Redirects are not followed and count as failures.

Delivery is at least once. A delivery that fails is retried with backoff after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours; after the sixth failure it is exhausted and not retried. Failed deliveries never block later ones, so a burst of events can arrive out of order: sort on createdAt if order matters, and deduplicate on id, which retries of one event share.

The settings page shows each endpoint's health. An endpoint is Failing once an attempt fails, and selecting that label shows the last error and response status. An endpoint that exhausts twenty deliveries in a row is turned off and shown as Turned off after failures. Fix the receiver, send a test event to confirm it, then turn the endpoint back on; events that happened while it was off are not delivered.

Every request is signed. Verify the signature before acting on a body; Security shows how.

Versioning Copy Chapter

The payload contract is dated. version in the body and the X-Rallly-Webhook-Version header carry the version a delivery was built against; today that is 2026-09-20. Additive changes, such as new fields, new events or new modifiers, keep the version, so ignore fields you do not recognise. A change that could break a receiver arrives under a new date, and existing endpoints keep the version they were created with until you upgrade them.

Apps Docs Contact Support (`apps/docs/contact/support.mdx`) Copy Section

title: Support Copy Chapter

If you have any questions, feedback or suggestions, please get in touch. We'd love to hear from you!

Apps Docs Contribute Documentation (`apps/docs/contribute/documentation.mdx`) Copy Section

title: Documentation icon: book Copy Chapter

If you have a Github account, you can make changes or report issues using the links that appear at the top of each page.

Submitting a Pull Request Copy Chapter

Submitting a pull request is a great way to fix minor issues like typos or broken links.
Click on the "pencil" icon and fork our repository to submit a pull request.

Creating an Issue Copy Chapter

For larger tasks, you can create a new issue by clicking on the "exclamation" icon.

Apps Docs Contribute Donations (`apps/docs/contribute/donations.mdx`) Copy Section

title: Donations icon: coins Copy Chapter

Why should I donate? Copy Chapter

Most users of Rallly use it for free, and that's great!
However, running Rallly costs money.
By donating, you can help keep Rallly running and ad-free.

How can I donate? Copy Chapter

You can donate using any of the following methods:

What will my donation be used for? Copy Chapter

Your donation will be used to cover the costs of running Rallly and to fund future development.

Apps Docs Contribute Introduction (`apps/docs/contribute/introduction.mdx`) Copy Section

title: Introduction icon: hand-holding-heart Copy Chapter

If you enjoy using Rallly and would like to contribute to its development, here are a few ways you can help out.

Apps Docs Contribute Translations (`apps/docs/contribute/translations.mdx`) Copy Section

title: Translations icon: globe Copy Chapter

Rallly is made available in different languages by volunteer translators.
Translations can be submitted through Crowdin.
Submitting translations is super easy and doesn't require any coding skills.

Sign Up to Crowdin Copy Chapter

The first thing you need to do is create a Crowdin account. Crowdin offers a user-friendly interface to submit translations.
You can then join the project using this link: https://crowdin.com/project/rallly

Once you've joined the project:

1. Pick the language you'd like to translate
2. Select a file (each file contains text for different parts of the site)
3. Start translating!

Tips for Translators Copy Chapter

Here are a few things to keep in mind when translating.

Punctuation Copy Section

Pay close attention to how phrases are punctuated.

Name:

If a sentence ends with a period (.) or a colon (:), you will want to include that in your translation.

❌ Nombre
✅ Nombre:

Variables Copy Section

Variables are placeholders for content that can change. They look like this:

Hi {name}, welcome back!

{name} is a variable that will be replaced with the user's name. Please make sure variables remain unchanged when translating.

❌ Salut {nom}, bienvenue!
✅ Salut {name}, bienvenue!

Tags Copy Section

Tags can be used to create a hyperlink or change the appearance of some text (ex. bold, italics etc…). They look like this:

Go to <a>page</a>

The tags should remain wrapped around the same content and should not be translated. The contents between the tags should be translated (unless they are a variable).

❌ Gehen Sie zur Seite
❌ <a>Gehen Sie zur Seite</a>
❌ Gehen Sie zur <a>page</a>
✅ Gehen Sie zur <a>Seite</a>

Plurals Copy Section

Plurals are like special rules that help make sure a message is written correctly when you're using different values.

For example, the following message will display 1 option if count is 1 or 2 options if count is anything else.

{count, plural, one {# option} other {# options}}

Note that # is a placeholder for the value of count.

If your language requires more than one plural form, you can add additional rules.

{count, plural, one {# опция} few {# опции} other {# опций}}

Register Copy Section

For languages that have different registers (informal vs. formal), the general advise is to use an informal register. However, there may be exceptions for certain languages so if you are not sure please reach out.

FAQ Copy Chapter

Contact Copy Chapter

If you have an questions you can reach out using one of the following methods:

Apps Docs Guide Content Moderation (`apps/docs/guide/content-moderation.mdx`) Copy Section

icon: shield-check title: Content Moderation Copy Chapter

Rallly uses automated content moderation to keep the platform safe for all users. When you create or update a poll, the content is checked against our content policy.

Content that is not related to scheduling or that violates our policies will be flagged and the poll will not be created or updated.

What happens if my content is flagged? Copy Chapter

If your content is flagged, you will see an error message. You can edit your content and try again.

Repeated violations may result in your account being suspended.

My content was flagged by mistake Copy Chapter

If you believe your content was incorrectly flagged, please contact support and we'll review your case.

Apps Docs Guide Participant Guide (`apps/docs/guide/participant-guide.mdx`) Copy Section

icon: user title: "Participant Guide" Copy Chapter

- **Yes** - you're available
- **If need be** - you can make it work if needed
- **No** - you're not available

Some polls only offer **Yes** and **No**.

<Note>If you leave an option unselected, it will be counted as a **No** vote.</Note>

<Frame>
  
</Frame>

When you're done, click **Continue**.

<Tip>To ensure you don't lose the ability to edit your response, enter your email address to receive a confirmation email with a magic link that identifies you .</Tip>

<Frame>
  
</Frame>

If you need to make changes, you can use the dropdown menu next to your name.

<Frame>
  
</Frame>

Frequently Asked Questions Copy Section

Apps Docs Integrations Google Meet (`apps/docs/integrations/google-meet.mdx`) Copy Section

icon: video title: Google Meet Copy Chapter

With the Google Meet integration, Rallly creates a Google Meet link on your Google account at the moment you finalize a poll. The link goes into the event, the calendar invite and the confirmation emails, so participants never wait for a link to follow.

How it works Copy Chapter

1. You connect your Google account once, from your settings.
2. When you create a poll, you choose Google Meet as the video call. The poll shows "Google Meet" to participants while voting is open; there is no link yet.
3. When you finalize the poll, Rallly creates a Google Meet meeting space on your Google account and attaches its link to the event.

The meeting space belongs to the Google account you connected, so it follows that account's Meet settings, such as who can join without asking. Rallly does not change those settings.

Requirements Copy Chapter

• A Google account. A personal Google account or a Google Workspace account both work. On Google Workspace, your administrator must allow Google Meet and let you connect third party apps.
• Google Meet works on every plan; the link is created when the poll is finalized.

Adding the app Copy Chapter

You can connect one Google account for Google Meet. To switch to a different Google account, disconnect the current one, then connect the new one.

If Google Calendar is already connected Copy Section

Google Calendar and Google Meet are separate connections in Rallly, but they use the same Google sign in. If you connect Google Meet with the Google account you already connected for Google Calendar, Google asks you to approve the Meet permission, and the calendar access you approved earlier is kept. Rallly keeps a single set of tokens for that Google account, covering both the calendar access you approved earlier and the new Meet permission. Your calendar connection is not affected.

You can also connect Google Meet with a different Google account from the one you use for Google Calendar. Each Google account then has its own connection and its own tokens.

Using the integration Copy Chapter

Choosing Google Meet for a poll Copy Section

When creating a poll, click Add video call and choose Google Meet.

The form shows "Google Meet" as the video call for this poll.

If your Google Meet account is not connected, the form tells you so and links to Conferencing settings.

Participants see "Google Meet" on the poll page while voting is open. No meeting link exists yet.

Finalizing the poll Copy Section

When you finalize the poll and pick the winning time, Rallly:

1. Creates a Google Meet meeting space on your Google account.
2. Attaches the meeting link to the event.
3. Includes the link in the calendar invite (.ics) and in the confirmation emails sent to you and to participants.

A meeting space is a reusable Meet room with its own link. It is not a Google Calendar event, so Rallly does not add anything to your Google Calendar through this integration, and the link is not tied to the scheduled time.

If the link cannot be created, for example because the Google connection has expired or was removed, the poll stays open and Rallly shows an error. Reconnect your account in Conferencing settings and finalize again.

Which account hosts the meeting Copy Section

The meeting space is created on the Google account of the poll's organizer. If a space member finalizes a poll organized by someone else, the meeting is still created on the organizer's Google account, and the organizer is the host.

Permissions Copy Chapter

When you connect, Rallly asks Google for these permissions:

The meetings.space.created permission only lets Rallly create meeting spaces and manage the spaces it created itself. Rallly does not read your other meetings, recordings, transcripts, participants, contacts or email, and does not join or record meetings.

Data Rallly stores Copy Chapter

For a connected Google account, Rallly stores:

• Your Google account id and email address, to identify the connection and show it in your settings.
• The access token and refresh token Google issues, encrypted at rest, so Rallly can create meeting spaces on your behalf without asking you to sign in each time. If the same Google account is also connected for Google Calendar, both connections share these tokens.

For each finalized poll, Rallly stores the link and meeting code of the meeting space it created, as part of the event.

Rallly does not store the content of any meeting.

Removing the app Copy Chapter

From Rallly Copy Section

1. Open Settings, then Conferencing.
2. Next to Google Meet, click the More options button and choose Disconnect.

The connection is removed immediately and Rallly stops creating Google Meet links for you. What happens to the tokens depends on whether the same Google account is connected for Google Calendar:

• If it is not, Rallly deletes the tokens it stored for that Google account.
• If it is, Rallly keeps the tokens, because your calendar connection still needs them.

Disconnecting in Rallly does not revoke the access you granted in your Google account, because the same Google access can also serve your calendar connection. To revoke it, remove Rallly from your Google account as described below.

Polls that already chose Google Meet keep that choice but can no longer be finalized with a Google Meet link until an account is connected again. Links Rallly already created keep working.

From your Google account Copy Section

To revoke Rallly's access on the Google side:

1. Open the third party apps and services page of your Google account.
2. Select Rallly.
3. Click Delete all connections you have with Rallly and confirm.

This revokes every permission Rallly holds on that Google account, including Google Calendar access if you connected it. Google does not tell Rallly, so the connections still appear in your settings until you disconnect them in Rallly as well; Rallly can no longer use them. If you sign in to Rallly with Google, you can still do so; Google asks you to approve Rallly again the next time.

Troubleshooting Copy Chapter

"Google Meet is not connected" when creating a poll. Your Rallly account has no Google Meet connection, or it was removed. Connect one in Conferencing settings and choose Google Meet again.

Finalizing fails with a video call error. The Google connection has expired, Rallly's access was removed from your Google account, or the Google Meet permission was not selected when you connected. Disconnect and reconnect Google Meet in Conferencing settings, then finalize again. The poll is unchanged until finalizing succeeds.

Google blocks the connection. On a Google Workspace account, your administrator may not allow third party apps or may have turned off Google Meet for your account. Ask your administrator to allow Rallly, or connect a different Google account.

Participants have to ask to join. Who can join without asking follows the Meet settings of the host's Google account or Workspace organization. The host can admit people from the meeting, or change the meeting access in Meet's host controls.

The meeting was created on the wrong account. The meeting is always created on the poll organizer's connected Google account. Check which account is connected in Conferencing settings.

Still stuck? Contact support.

Apps Docs Integrations Microsoft Teams (`apps/docs/integrations/microsoft-teams.mdx`) Copy Section

icon: video title: Microsoft Teams Copy Chapter

With the Microsoft Teams integration, Rallly creates a Teams meeting on your Microsoft account at the moment you finalize a poll. The join link goes into the event, the calendar invite and the confirmation emails, so participants never wait for a link to follow.

How it works Copy Chapter

1. You connect your Microsoft work or school account once, from your settings.
2. When you create a poll, you choose Microsoft Teams as the video call. The poll shows "Microsoft Teams" to participants while voting is open; there is no link yet.
3. When you finalize the poll, Rallly creates a Teams meeting for the chosen time on your Microsoft account and attaches the join link to the event.

The meeting is created on the Microsoft account you connected, so it follows your organization's Teams meeting policies, such as the lobby and who can present. Rallly does not change those settings.

Requirements Copy Chapter

• A Microsoft work or school account with a Microsoft Teams license. Personal Microsoft accounts (Outlook.com, Hotmail, Live) are not supported: Microsoft does not let apps create Teams meetings for them, so Rallly asks Microsoft for a work or school account when you connect.
• You must have used Teams at least once with that account. An account whose Microsoft 365 plan does not include Teams cannot create meetings.
• Your organization must let you approve Rallly, or an administrator must approve it for the organization. See Admin approval.

Adding the app Copy Chapter

When you connect, Rallly checks that the account can create Teams meetings by creating a test meeting and deleting it straight away. The test meeting does not appear in your calendar or in Teams. If Microsoft refuses it, Rallly does not connect the account and tells you why; see Troubleshooting.

You can connect one Microsoft account for Microsoft Teams. To switch to a different account, disconnect the current one, then connect the new one.

Connecting Microsoft Teams is separate from signing in to Rallly with Microsoft. You can sign in with any method and still connect Teams, and connecting Teams does not change how you sign in.

Admin approval Copy Section

Many organizations do not let their users approve apps themselves. If yours is one of them, Microsoft shows "Need admin approval" instead of the permissions, and Rallly shows an error when you return. Only an administrator of your organization can resolve this.

When the connection fails, Rallly offers a Copy link button. Send that link to your IT administrator. The administrator opens it, signs in with their administrator account and approves Rallly for the whole organization; they do not need a Rallly account. The link is:

https://app.rallly.co/api/integrations/admin-consent/microsoft-teams?redirect=/settings/conferencing

After the administrator approves, connect Microsoft Teams again. Microsoft no longer asks for approval. Administrators who prefer the Microsoft Entra admin center can grant the same approval under Enterprise apps, after searching for Rallly and opening Permissions.

Using the integration Copy Chapter

Choosing Microsoft Teams for a poll Copy Section

When creating a poll, click Add video call and choose Microsoft Teams. The form shows "Microsoft Teams" as the video call for this poll.

If your Microsoft Teams account is not connected, the form tells you so and links to Conferencing settings.

Participants see "Microsoft Teams" on the poll page while voting is open. No meeting link exists yet.

Finalizing the poll Copy Section

When you finalize the poll and pick the winning time, Rallly:

1. Creates a Teams meeting for that time on your Microsoft account.
2. Attaches the join link, meeting ID and passcode to the event.
3. Includes them in the calendar invite (.ics) and in the confirmation emails sent to you and to participants.

Rallly does not add the meeting to your Outlook calendar; the calendar invite Rallly sends covers it.

If the meeting cannot be created, for example because the Microsoft connection has expired or your account no longer has a Teams license, the poll stays open and Rallly shows an error that says which it is. See Troubleshooting.

Which account hosts the meeting Copy Section

The meeting is created on the Microsoft account of the poll's organizer. If a space member finalizes a poll organized by someone else, the meeting is still created on the organizer's Microsoft account, and the organizer is the host.

Permissions Copy Chapter

When you connect, Rallly asks Microsoft for these permissions:

Rallly uses OnlineMeetings.ReadWrite only to create a meeting when you finalize a poll and to create and immediately delete one test meeting when you connect. Rallly does not read your other meetings, chats, recordings, transcripts, files, contacts, calendar or email, and does not join or record meetings.

Data Rallly stores Copy Chapter

For a connected Microsoft account, Rallly stores:

• Your Microsoft account id and email address, to identify the connection and show it in your settings.
• The access token and refresh token Microsoft issues, encrypted at rest, so Rallly can create meetings on your behalf without asking you to sign in each time.

For each finalized poll, Rallly stores the join link, meeting ID and passcode of the meeting it created, as part of the event.

Rallly does not store the content of any meeting.

Removing the app Copy Chapter

From Rallly Copy Section

1. Open Settings, then Conferencing.
2. Next to Microsoft Teams, click the More options button and choose Disconnect.

The connection is removed immediately, Rallly deletes the tokens it stored for that Microsoft account and stops creating Teams meetings for you.

Microsoft does not let apps revoke their own access, so disconnecting in Rallly does not remove Rallly from your Microsoft account. Rallly no longer holds tokens to use it, but to remove the permission itself, follow the steps below.

Polls that already chose Microsoft Teams keep that choice but can no longer be finalized with a Teams link until an account is connected again. Meetings Rallly already created keep working.

From your Microsoft account Copy Section

1. Open My Apps and sign in with the account you connected.
2. Find Rallly, open its menu and choose Manage your application.
3. Choose Revoke permissions and confirm.

If you do not see the option, your organization manages app permissions centrally; ask your administrator to remove Rallly. Microsoft does not tell Rallly, so the connection still appears in your settings until you disconnect it in Rallly as well; Rallly can no longer use it.

Troubleshooting Copy Chapter

Microsoft says "Need admin approval". Your organization does not let users approve apps. Send your administrator the link described under Admin approval.

Microsoft does not accept your personal account. Microsoft Teams meetings can only be created for work or school accounts. Connect the account your organization gave you.

Rallly says the account can't create Teams meetings. Microsoft refused the test meeting Rallly creates when you connect. The account has no Teams license, Teams has never been opened with it, or your organization's policies do not let it create meetings. Open Teams with that account: if Teams does not open, ask your IT administrator for a license that includes Teams. Once Teams opens, connect the account in Rallly again.

"Microsoft Teams is not connected" when creating a poll. Your Rallly account has no Microsoft Teams connection, or it was removed. Connect one in Conferencing settings and choose Microsoft Teams again.

Finalizing fails because Microsoft Teams couldn't create the meeting. The account could create meetings when you connected it and no longer can, usually because its Teams license was removed. Check that you can open Teams with that account, then finalize again. The poll is unchanged until finalizing succeeds.

Finalizing fails because the account is not connected. The connection expired after 90 days without use, your password was changed, or your administrator removed Rallly. Disconnect and reconnect Microsoft Teams in Conferencing settings and finalize again.

Participants wait in the lobby. Who waits in the lobby follows your organization's Teams meeting policies. The host can admit people from the meeting, or change the meeting options in Teams.

The meeting was created on the wrong account. The meeting is always created on the poll organizer's connected Microsoft account. Check which account is connected in Conferencing settings.

Still stuck? Contact support.

Apps Docs Integrations Webex (`apps/docs/integrations/webex.mdx`) Copy Section

icon: video title: Webex Copy Chapter

With the Webex integration, Rallly creates a Webex meeting on your account at the moment you finalize a poll. The join link goes into the event, the calendar invite and the confirmation emails, so participants never wait for a link to follow.

How it works Copy Chapter

1. You connect your Webex account once, from your settings.
2. When you create a poll, you choose Webex as the video call. The poll shows "Webex" to participants while voting is open; there is no link yet.
3. When you finalize the poll, Rallly creates a Webex meeting for the chosen time on your Webex account and attaches the join link to the event.

The meeting is created on the Webex account you connected, so it follows that account's and your organization's Webex settings, such as the lobby and the meeting password. Rallly does not change those settings.

Requirements Copy Chapter

• A Webex account that can host meetings.
• Your organization must allow Webex integrations. Integrations are allowed by default; an administrator can block them in Control Hub. See Organization restrictions.

Adding the app Copy Chapter

You can connect one Webex account. To switch to a different account, disconnect the current one, then connect the new one.

Organization restrictions Copy Section

A Webex administrator can block integrations for everyone in the organization, or allow only some of them, under Management > Apps > Integrations in Control Hub. If yours does, Webex refuses the connection and Rallly shows an error when you return. Only an administrator of your organization can allow Rallly.

Using the integration Copy Chapter

Choosing Webex for a poll Copy Section

When creating a poll, click Add video call and choose Webex. The form shows "Webex" as the video call for this poll.

If your Webex account is not connected, the form tells you so and links to Conferencing settings.

Participants see "Webex" on the poll page while voting is open. No meeting link exists yet.

Finalizing the poll Copy Section

When you finalize the poll and pick the winning time, Rallly:

1. Creates a Webex meeting for that time on your Webex account.
2. Attaches the join link, meeting number and password to the event.
3. Includes them in the calendar invite (.ics) and in the confirmation emails sent to you and to participants.

Rallly asks Webex not to send its own invitation emails; the invite Rallly sends covers it.

Webex only schedules meetings between 10 minutes and 23 hours 59 minutes long that have not started yet. Rallly fits the Webex meeting to those limits: an all day event gets a meeting of 23 hours 59 minutes, an event shorter than 10 minutes gets a 10 minute meeting, and an event that has already started gets a meeting that starts at the next minute. The event itself keeps the time you picked.

If the meeting cannot be created, for example because the Webex connection has expired, the poll stays open and Rallly shows an error. See Troubleshooting.

Which account hosts the meeting Copy Section

The meeting is created on the Webex account of the poll's organizer. If a space member finalizes a poll organized by someone else, the meeting is still created on the organizer's Webex account, and the organizer is the host.

Permissions Copy Chapter

When you connect, Rallly asks Webex for these permissions:

Rallly uses meeting:schedules_write only to create a meeting when you finalize a poll, and spark:people_read only to read your own profile. Rallly does not read your existing meetings, messages, recordings, transcripts or contacts, and does not join or record meetings.

Data Rallly stores Copy Chapter

For a connected Webex account, Rallly stores:

• Your Webex account id and email address, to identify the connection and show it in your settings.
• The access token and refresh token Webex issues, encrypted at rest, so Rallly can create meetings on your behalf without asking you to sign in each time.

For each finalized poll, Rallly stores the join link, meeting number and password of the meeting it created, as part of the event.

Rallly does not store the content of any meeting.

Removing the app Copy Chapter

1. Open Settings, then Conferencing.
2. Next to Webex, click the More options button and choose Disconnect.

The connection is removed immediately, Rallly deletes the tokens it stored for that Webex account and stops creating Webex meetings for you. Polls that already chose Webex keep that choice but can no longer be finalized with a Webex link until an account is connected again. Meetings Rallly already created stay in your Webex account; delete them from Webex if you no longer need them.

Troubleshooting Copy Chapter

Webex refuses the connection. Your organization blocks Webex integrations. Ask your Webex administrator to allow Rallly; see Organization restrictions.

"Webex is not connected" when creating a poll. Your Rallly account has no Webex connection, or it was removed. Connect one in Conferencing settings and choose Webex again.

Finalizing fails because the account is not connected. The connection expired after a long period without use, or your administrator removed Rallly. Disconnect and reconnect Webex in Conferencing settings and finalize again.

Finalizing fails because the meeting link couldn't be created. The connected account may not be able to host meetings, for example a Webex account that only has messaging. Check that you can schedule a meeting in Webex with that account, then finalize again. The poll is unchanged until finalizing succeeds.

The meeting was created on the wrong account. The meeting is always created on the poll organizer's connected Webex account. Check which account is connected in Conferencing settings.

Still stuck? Contact support.

Apps Docs Integrations Zoom (`apps/docs/integrations/zoom.mdx`) Copy Section

icon: video title: Zoom Copy Chapter

With the Zoom integration, Rallly creates a Zoom meeting on your account at the moment you finalize a poll. The join link goes into the event, the calendar invite and the confirmation emails, so participants never wait for a link to follow.

How it works Copy Chapter

1. You connect your Zoom account once, from your settings.
2. When you create a poll, you choose Zoom as the video call. The poll shows "Zoom" to participants while voting is open; there is no link yet.
3. When you finalize the poll, Rallly creates a Zoom meeting for the chosen time on your Zoom account and attaches the join link to the event.

The meeting is created on the Zoom account you connected, so it follows that account's settings, such as waiting rooms, passcodes and recording defaults. Rallly does not change those settings.

Requirements Copy Chapter

• A Zoom account. A free Zoom plan is enough.

Adding the app Copy Chapter

You can connect one Zoom account per Rallly account. To switch to a different Zoom account, disconnect the current one, then connect the new one.

Using the integration Copy Chapter

Choosing Zoom for a poll Copy Section

When creating a poll, click Add video call and choose Zoom.

The form shows "Zoom" as the video call for this poll.

If your Zoom account is not connected, the form tells you so and links to Conferencing settings.

Participants see "Zoom" on the poll page while voting is open. No meeting exists yet.

Finalizing the poll Copy Section

When you finalize the poll and pick the winning time, Rallly:

1. Creates a scheduled Zoom meeting on your account for that date and time, using the poll title as the meeting topic.
2. Attaches the join link to the event.
3. Includes the link in the calendar invite (.ics) and in the confirmation emails sent to you and to participants.

The meeting also appears in your Zoom account under Meetings, where you can edit or delete it like any other meeting.

If the meeting cannot be created, for example because the Zoom connection has expired, the poll stays open and Rallly shows an error. Reconnect your account in Conferencing settings and finalize again.

Which account hosts the meeting Copy Section

The meeting is created on the Zoom account of the poll's organizer. If a space member finalizes a poll organized by someone else, the meeting is still created on the organizer's Zoom account.

Permissions Copy Chapter

When you connect, Rallly asks Zoom for these permissions:

Rallly does not read your existing meetings, recordings, contacts or chat, and does not join or record meetings.

Data Rallly stores Copy Chapter

For a connected Zoom account, Rallly stores:

• Your Zoom account id and email address, to identify the connection and show it in your settings.
• The access token and refresh token Zoom issues, encrypted at rest, so Rallly can create meetings on your behalf without asking you to sign in each time.

For each finalized poll, Rallly stores the meeting id, join link and passcode of the meeting it created, as part of the event.

Rallly does not store the content of any meeting.

Removing the app Copy Chapter

From Rallly Copy Section

1. Open Settings, then Conferencing.
2. Next to Zoom, click the More options button and choose Disconnect.

The connection is removed immediately: Rallly deletes the account details and tokens it stored, then asks Zoom to revoke its access. To confirm the access is gone, remove the app from Zoom as described below. Polls that already chose Zoom keep that choice but can no longer be finalized with a Zoom link until an account is connected again. Meetings Rallly already created stay in your Zoom account; delete them from Zoom if you no longer need them.

From Zoom Copy Section

You can also remove the app from the Zoom side:

1. Sign in to the Zoom App Marketplace.
2. Click Manage, then Added Apps.
3. Find Rallly and click Remove.

Removing the app from Zoom revokes Rallly's access. Zoom tells Rallly, which deletes the connection and the tokens it stored, so the account no longer appears in your settings. If the account still appears in your settings, disconnect it in Rallly as well.

Troubleshooting Copy Chapter

"Zoom is not connected" when creating a poll. Your Rallly account has no Zoom connection, or it was removed. Connect one in Conferencing settings and choose Zoom again.

Finalizing fails with a video call error. The Zoom connection has expired or was revoked on the Zoom side. Disconnect and reconnect the account, then finalize again. The poll is unchanged until finalizing succeeds.

The meeting was created on the wrong account. The meeting is always created on the poll organizer's connected Zoom account. Check which account is connected in Conferencing settings.

Still stuck? Contact support.

Apps Docs Self Hosting Conferencing (`apps/docs/self-hosting/conferencing.mdx`) Copy Section

icon: video title: Video Conferencing Copy Chapter

Available from v4.16.0 and later.

With conferencing enabled, organizers connect a Google Meet, Zoom, Microsoft Teams or Webex account in Settings > Conferencing. When they finalize a poll, Rallly creates the meeting on that account and puts the join link in the event, the calendar invite and the confirmation emails. See the integration guides for what organizers see.

Each provider needs an OAuth app that you register with the provider yourself. Rallly cannot ship one for you, because the redirect URI of an OAuth app is tied to your instance's domain. You turn on each provider separately; on a self-hosted instance every provider is available on every plan.

Enable conferencing Copy Chapter

A comma separated list of the providers organizers can use: google-meet, zoom, microsoft-teams, webex. A listed provider is offered once its OAuth app variables are set; Google and Microsoft credentials used for sign in never turn on Meet or Teams by themselves. An unknown value stops Rallly from starting. A listed provider without credentials is not offered, Rallly logs a warning at startup, and the Conferencing page says no provider is set up. Organizers can always paste their own video call link, whatever this lists.

Every redirect URI below starts with your instance's public address, written as https://<YOUR_DOMAIN>. It must match exactly, including the scheme and without a trailing slash.

Google Meet Copy Chapter

Google Meet uses the same Google OAuth app as Google sign in and Google Calendar. Setting the Google variables for sign in does not turn on Google Meet: finish the steps below, then add google-meet to CONFERENCING_PROVIDERS.

https://<YOUR_DOMAIN>/api/integrations/callback/google-meet

https://<YOUR_DOMAIN>/api/integrations/callback/zoom

https://<YOUR_DOMAIN>/api/integrations/zoom/deauthorize

https://<YOUR_DOMAIN>/api/integrations/callback/microsoft-teams

https://<YOUR_DOMAIN>/api/integrations/callback/webex

HTTPS_PROXY=http://proxy.internal.example.com:8080
HTTP_PROXY=http://proxy.internal.example.com:8080
NO_PROXY=garage,db

CA_CERT_FILE=/opt/rallly/certs/corporate-root-ca.pem

docker compose exec web openssl x509 -in /etc/ssl/certs/rallly-custom-ca.pem -noout -subject

openssl x509 -inform DER -in ca.crt -out ca.pem

openssl s_client -showcerts -connect licensing.rallly.co:443 </dev/null 2>/dev/null | openssl x509 -outform PEM > ca.pem

openssl x509 -in ca.pem -noout -subject

./rallly.sh logs web

./rallly.sh start          # Start all services
./rallly.sh stop           # Stop all services
./rallly.sh restart        # Restart all services
./rallly.sh status         # Show service status
./rallly.sh logs           # Stream logs for all services
./rallly.sh logs web       # Stream logs for a specific service
./rallly.sh update         # Pull latest images and recreate containers
./rallly.sh backup         # Back up the database to ./backups/

./rallly.sh restart

./rallly.sh update

./rallly.sh backup

# Stop the app (leave the db service running)
docker compose stop web

# Drop and recreate the database — connect to the "postgres" db so we can drop "rallly"
docker compose exec -T db psql -U postgres -d postgres -c "DROP DATABASE IF EXISTS rallly;"
docker compose exec -T db psql -U postgres -d postgres -c "CREATE DATABASE rallly;"

# Restore — ON_ERROR_STOP=1 fails fast on the first error instead of continuing silently
gunzip < backups/rallly_20260101_120000.sql.gz | docker compose exec -T db psql -v ON_ERROR_STOP=1 -U postgres rallly

# Bring the app back up
./rallly.sh start

./rallly.sh logs

./rallly.sh logs web
./rallly.sh logs traefik

./rallly.sh logs web
./rallly.sh logs db

docker compose exec -T rallly_db pg_dump -U postgres rallly | gzip > rallly-backup.sql.gz

docker compose down

# Examples, adjust to your setup
sudo systemctl stop nginx && sudo systemctl disable nginx
sudo systemctl stop caddy && sudo systemctl disable caddy

sudo ss -tlnp | grep -E ':(80|443)\b'

curl -fsSL https://get.rallly.co | bash

cd /opt/rallly
./rallly.sh start

./rallly.sh logs db

# Stop the app so it releases its connections to the rallly database
docker compose stop web

# Drop the freshly-migrated empty database and recreate it — connect to "postgres" to drop "rallly"
docker compose exec -T db psql -U postgres -d postgres -c "DROP DATABASE IF EXISTS rallly;"
docker compose exec -T db psql -U postgres -d postgres -c "CREATE DATABASE rallly;"

# Restore — ON_ERROR_STOP=1 fails fast on the first error instead of continuing silently
gunzip < /path/to/rallly-backup.sql.gz | docker compose exec -T db psql -v ON_ERROR_STOP=1 -U postgres rallly

./rallly.sh start

# Remove the old stack directory
rm -rf /path/to/old/rallly-selfhosted

# Remove orphaned Docker volumes from the old stack
docker volume ls
docker volume rm <old-volume-name>

https://<YOUR_DOMAIN>/api/auth/callback/google

https://<YOUR_DOMAIN>/api/auth/callback/microsoft-entra-id

{ "name": "email", "source": null, "essential": false, "additionalProperties": [] },
{ "name": "verified_primary_email", "source": null, "essential": false, "additionalProperties": [] },
{ "name": "verified_secondary_email", "source": null, "essential": false, "additionalProperties": [] },
{ "name": "xms_edov", "source": null, "essential": false, "additionalProperties": [] }

https://<YOUR_DOMAIN>/api/integrations/callback/microsoft-teams

https://<YOUR_DOMAIN>/api/auth/callback/oidc

# White labeling
APP_NAME="Acme Scheduler"
PRIMARY_COLOR="#0066cc"
PRIMARY_COLOR_DARK="#3399ff"
LOGO_URL="https://example.com/logo.svg"
LOGO_URL_DARK="https://example.com/logo-dark.svg"
LOGO_ICON_URL="https://example.com/icon.png"
HIDE_ATTRIBUTION="true"

<Frame>
  
</Frame>

<Frame>
  
</Frame>

<Note>
You can increase seats to any number you need. There's no upper limit on seat allocation.
</Note>

<Warning>
You cannot reduce seats below your current member count. Remove members first, then adjust seats.
</Warning>

<Frame>
  
</Frame>

<Note>
The person will receive an email invitation with instructions to join your space.
</Note>

<Frame>
  
</Frame>

</Frame>
  </Tab>
  <Tab title="Week view">
    <Frame caption="Use week view to draw time slots on a weekly calendar">
      
    </Frame>
  </Tab>
</Tabs>

**Duration** - Each option defaults to a 1 hour time slot. Use the duration picker above the calendar to change the length (30m, 1h, 1h 30m or 2h), or choose **All day** for participants to vote on whole days without specific times.

**Time zones** - Times are automatically shown to each participant in their own time zone. This is useful for remote meetings where participants are in different locations. If everyone should see the same times regardless of where they are, turn on **Lock time zone**.

**Vote options** - Participants can answer **Yes**, **If need be** or **No**.
Change this to **Yes** and **No** under **Settings** if you'd rather not
offer a maybe.

<Frame>
  
</Frame>

To share the **invite link**, click **Copy** and paste it anywhere: chat,
email or a calendar invite. Anyone with the link can vote on your poll.

To **invite by email**, enter an email address and click **Send invite**.
Rallly sends that person an email with a link to your poll.

<Frame caption="Each invitee shows whether the invite was sent, opened or responded to">
  
</Frame>

<Note>Inviting by email requires a [Pro subscription](https://rallly.co/pricing) on Rallly Cloud. Sharing the invite link is free.</Note>

<Note>Have a look at the [participant guide](/guide/participant-guide) for details on how participants can vote.</Note>

<Frame>
  
</Frame>

As responses come in, you can review the results on your poll page to see
which dates are preferred. If you invited people by email, the Share
dialog also shows who has opened their invite and who has responded.

<Frame>
  
</Frame>

<Frame>
  
</Frame>

This step is skipped when the poll has no participants yet.

<Frame>
  
</Frame>

This will:

1. Send a calendar invite to you by email.
2. Send a calendar invite to the participants you selected. Invites go out
   in batches, so on a large poll the last ones can take a few minutes.
3. Close the poll to new responses.

<Frame>
  
</Frame>

The final date is displayed on your poll for everyone to see and can be
added to a calendar with one click.

<Frame>
  
</Frame>

{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.closed",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": { "id": "Xk3pQ9vLm2Ab" },
    "reason": "manual"
  }
}

{ "poll": { "id": "Xk3pQ9vLm2Ab" } }

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.created",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    }
  }
}
```

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.updated",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    }
  }
}
```

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.closed",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    },
    "reason": "manual"
  }
}
```

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.reopened",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    }
  }
}
```

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.scheduled",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    },
    "event": {
      "start": "2025-01-15T09:00:00.000Z",
      "end": "2025-01-15T09:30:00.000Z",
      "allDay": false
    }
  }
}
```

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.deleted",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    }
  }
}
```

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.participant.created",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    },
    "participant": {
      "id": "cm5j2r8wb0003q9l4a1x6p0zt"
    }
  }
}
```

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.participant.updated",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    },
    "participant": {
      "id": "cm5j2r8wb0003q9l4a1x6p0zt"
    }
  }
}
```

```json
{
  "version": "2026-09-20",
  "id": "cm5h8x2k40000q9l4f7e2d3an",
  "type": "poll.participant.deleted",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {
    "poll": {
      "id": "Xk3pQ9vLm2Ab"
    },
    "participant": {
      "id": "cm5j2r8wb0003q9l4a1x6p0zt"
    }
  }
}
```

{
  "version": "2026-09-20",
  "id": "ping_V1StGXR8Z5jdHi6BmyT",
  "type": "ping",
  "createdAt": "2025-01-12T08:30:00.000Z",
  "data": {}
}

X-Rallly-Signature: t=1736670600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(header: string, rawBody: string, secret: string) {
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.split("=") as [string, string]),
  );
  const timestamp = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return false; // missing, or older than five minutes
  }
  if (!/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) {
    return false; // not a SHA-256 hex digest, so never worth comparing
  }
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest();
  return timingSafeEqual(expected, Buffer.from(parts.v1, "hex"));
}

curl -fsSL https://get.rallly.co | bash

PROXY_MODE=external
WEB_PORT=127.0.0.1:3000

DATABASE_URL=postgres://user:[email protected]:5432/rallly

S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
S3_BUCKET_NAME=my-rallly-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...

Under **Options**, switch on **Raw Body**. This is the step people miss. The signature covers the request body byte for byte; without this option the node parses the JSON and hands you an object, and re-serialising that object produces different bytes and a digest that never matches. With Raw Body on, the exact bytes are kept as binary data on the item, in the property named `data`.

Copy the node's **Production URL**.

In n8n, store the secret where the workflow can read it without it appearing in the workflow JSON. A workflow **variable** or an environment variable both work; the code below reads `$vars.RALLLY_WEBHOOK_SECRET`.

```js
const { createHmac, timingSafeEqual } = require("crypto");

const item = $input.first();
const header = item.json.headers["x-rallly-signature"] ?? "";
const rawBody = await this.helpers.getBinaryDataBuffer(0, "data");

const parts = Object.fromEntries(
  header.split(",").map((part) => part.split("=")),
);
const timestamp = Number(parts.t);
if (Math.abs(Date.now() / 1000 - timestamp) > 300) {
  throw new Error("Signature timestamp is missing or older than five minutes");
}
if (!/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) {
  throw new Error("Signature is not a SHA-256 digest");
}

const expected = createHmac("sha256", $vars.RALLLY_WEBHOOK_SECRET)
  .update(`${parts.t}.`)
  .update(rawBody)
  .digest();
if (!timingSafeEqual(expected, Buffer.from(parts.v1, "hex"))) {
  throw new Error("Signature does not match");
}

return [{ json: JSON.parse(rawBody.toString("utf8")) }];
```

A request that fails any check stops the workflow with an error, and the node outputs the verified event body as the item. Everything after this node can trust `$json.type` and `$json.data`.

If you run n8n on your own server, `require("crypto")` needs the built-in module allowed: set `NODE_FUNCTION_ALLOW_BUILTIN=crypto` in n8n's environment. n8n Cloud allows it already.

- **Method** `GET`
- **URL** `https://api.rallly.co/v1/polls/{{ $json.data.poll.id }}`
- **Authentication** `Generic Credential Type` → `Bearer Auth`, with a credential holding your Rallly API key from **Settings → API keys**

For a `poll.participant.*` event, fetch the participant the same way: `https://api.rallly.co/v1/polls/{{ $json.data.poll.id }}/participants/{{ $json.data.participant.id }}` returns their name, email and availability.

From here the poll and the participant are ordinary items: post to Slack, write a row to a sheet, or update your own system.