---
title: "Send a broadcast"
method: POST
path: "/api/v1/broadcasts/"
tags: ["messages"]
---

# Send a broadcast

`POST /api/v1/broadcasts/`

## Request

- Base URL: `https://api.prolific.com`
- URL: `https://api.prolific.com/api/v1/broadcasts/`
- Auth: API key in header `Authorization`

Sends one message to many participants on a study. Each of them gets a new conversation carrying the broadcast's subject, topic and study, with the message as its first message. Replies stay in that conversation, between the participant and the sender.

The broadcast is saved as it was sent and never changes. The conversations are created in the background, so they can take a short while to appear.

Pass your own `id` to make sending safe to repeat. Sending again with an id you've already used returns that broadcast rather than sending it twice.

Send it to `recipient_ids` or to a `participant_group_id`, exactly one of the two. With `audience_source: submissions`, each recipient must have a submission for the study in any status. With `audience_source: TYPED_IDS` (IDs typed in) or `MESSAGES` (participants picked from your conversations), each must be a participant who has taken part in one of your studies or already has a conversation with you. A group's members get it as the group is at the moment of sending, whether or not they're on the study, which only labels the broadcast. Each member must have taken part in one of your studies or already have a conversation with you. A group that isn't in the study's workspace or its organisation, or that you can't view, returns 404, and one with no members returns 400. If your access to the group can't be checked right now, it returns 503. A broadcast has the same recipient limit as a bulk message. Going over it returns a 400 that gives the limit. The study must belong to a workspace you are in. A study you can't broadcast about returns 404, as does the endpoint while broadcasts aren't enabled for the study's workspace.

## Request body

- CreateBroadcast: Send it to recipient_ids or to a participant_group_id, exactly one of the two.
  - `id` string: An id you choose for the broadcast. Sending again with the same id returns the broadcast already sent. One is made for you if it's left out.
  - `study_id` string, required: The study the broadcast is about.
  - `subject` string, required: Shown as the title of each recipient's conversation.
  - `topic` 'payment-timing' | 'payment-issues' | 'technical-issues' | 'feedback' | 'rejections' | 'other': Which of the fixed categories it falls under, if any.
  - `body` string, required: The message, sent as the first message of each conversation.
  - `recipient_ids` string[]: Participants to send it to. Repeats are ignored. Needs audience_source, which sets who's allowed.
  - `participant_group_id` string: Send to every member of this participant group, as it is at the moment of sending. The group must belong to the study's workspace or its organisation. The study labels the broadcast and doesn't narrow who gets it, so members don't need a submission for it. A group with no members returns 400.
  - `audience_source` 'submissions' | 'TYPED_IDS' | 'MESSAGES': Where recipient_ids were picked. `submissions` for participants picked from the study's submissions, `TYPED_IDS` for IDs typed in, `MESSAGES` for participants picked from your conversations. Left out for a participant group, which sets it to PARTICIPANT_GROUP.
  - `workspace_id` string: Send it as this workspace rather than as yourself. Must be the study's workspace, and requires workspace messaging.

## Response `201`

The broadcast

- Broadcast
  - `id` string, required
  - `study_id` string, required
  - `subject` string, required
  - `topic` string, nullable, required
  - `body` string, required
  - `audience_source` 'submissions' | 'PARTICIPANT_GROUP' | 'TYPED_IDS' | 'MESSAGES', required
  - `participant_group` BroadcastParticipantGroup, required: The participant group it was sent to, or null.
    - `id` string, required
    - `name` string, required: The group's name when it was sent.
  - `recipient_count` integer, required
  - `datetime_created` string, date-time, required

## Other responses

- `400`: Error

## Changes

- **2026-10-27** `0eeae21e89fe`: 1 warning, 1 info
  - added the new `MESSAGES` enum value to the `audience_source` response property for the response status `201`
  - added the new `MESSAGES` enum value to the request property `audience_source`
- **2026-10-26** `498c9e20b1ce`: 1 warning, 1 info
  - added the new `TYPED_IDS` enum value to the `audience_source` response property for the response status `201`
  - added the new `TYPED_IDS` enum value to the request property `audience_source`
- **2026-10-23** `0a2c3f2c92ef`: 2 warning, 4 info
  - added the new `PARTICIPANT_GROUP` enum value to the `audience_source` response property for the response status `201`
  - added the new `submissions` enum value to the `audience_source` response property for the response status `201`
  - added the new optional request property `participant_group_id`
  - the request property `audience_source` became optional
  - …2 more
- **2026-10-19** `d8ab5baad529`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/prolific/apis/api-reference/changes/api/v1/broadcasts/post.md)

---

[API](https://skmtc.dev/prolific/apis/api-reference.md) - [All operations](https://skmtc.dev/prolific/apis/api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/prolific/apis/api-reference/revisions/36e3bb40c638?raw)