---
title: "Send a poll"
method: POST
path: "/polls"
tags: ["Messages"]
---

# Send a poll

`POST /polls`

## Request

- Base URL: `https://osis.co/api/v1/comms`
- URL: `https://osis.co/api/v1/comms/polls`
- Auth: HTTP bearer

Send a poll over iMessage. Needs an iMessage conversation and a line that supports polls. Scope: comms_send.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `to` string, required: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string: A conversation to send in. Required unless you set to or contact_id.
    - `question` string, required: The question.
    - `options` string[], required: 2 to 12 choices. Extra spaces are trimmed, and duplicates are removed (ignoring case).
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `channel` 'imessage' | 'whatsapp': imessage (default) or whatsapp.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.
  - object
    - `to` string: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string, required: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string: A conversation to send in. Required unless you set to or contact_id.
    - `question` string, required: The question.
    - `options` string[], required: 2 to 12 choices. Extra spaces are trimmed, and duplicates are removed (ignoring case).
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `channel` 'imessage' | 'whatsapp': imessage (default) or whatsapp.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.
  - object
    - `to` string: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string, required: A conversation to send in. Required unless you set to or contact_id.
    - `question` string, required: The question.
    - `options` string[], required: 2 to 12 choices. Extra spaces are trimmed, and duplicates are removed (ignoring case).
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `channel` 'imessage' | 'whatsapp': imessage (default) or whatsapp.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.

## Response `200`

Already sent with this idempotency key. Returns the first result.

- SendPollResponse
  - `message` Message
    - `id` string
    - `body` string
    - `direction` 'outbound' | 'inbound'
    - `conversation_id` string
    - `reply_to_message_id` string: The ID of the message this replies to, if it's in this conversation.
    - `thread_root_message_id` string: The first message in this thread.
    - `channel` 'sms' | 'imessage' | 'rcs' | 'whatsapp'
    - `status` string
    - `contact_id` string
    - `line_id` string: Line ID when available.
    - `line_e164` string: Your number in this conversation: the number that received the message, or the number you sent from.
    - `to` string
    - `read_at` string, date-time: The native read time when a read receipt is available. For one-to-one iMessage and RCS, the recipient must have read receipts on. Never available for SMS; absence does not mean unread.
    - `created_at` string, date-time
    - `audience` 'direct' | 'shared': Whether the message is in a group conversation or a one-on-one conversation.
    - `author` object: Who sent the message. Display names aren't verified.
      - `contact_id` string, required
      - `external_id` string, required
      - `display_name` string
    - `reply_to_provider_message_id` string: Another ID for the message this replies to, when available.
    - `thread_originator_guid` string: Another ID for the first message in the thread, when available.
    - `attachments` InboundAttachment[]: Files someone sent you. If a message is only files, body is empty.
      - `id` string
      - `filename` string, required
      - `content_type` string, required
      - `mediaType` string, required
      - `size_bytes` integer
      - `transcription` string
      - `url` string, uri: Where to download the file. Needs an API key with comms_read from the same workspace and line.
    - `unsent_at` string, date-time: When the unsend was confirmed. The original text and delivery history are kept.
  - `duplicate` boolean
  - `poll` object
    - `question` string
    - `options` string[]

## Other responses

- `201`: Poll accepted
- `400`: Bad request
- `401`: API key is missing or wrong
- `402`: You've used your plan's messages
- `403`: Your key doesn't have the scope this needs
- `404`: Not found
- `409`: The conversation isn't available, or the request conflicts with an earlier one
- `429`: Too many requests. Slow down and retry.

---

[API](https://skmtc.dev/osis/apis/comms-api.md) · [All operations](https://skmtc.dev/osis/apis/comms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/osis/apis/comms-api/revisions/59a4c0ba8936?raw)