---
title: "Start a conversation"
method: POST
path: "/api/v1/conversations/"
tags: ["messages"]
---

# Start a conversation

`POST /api/v1/conversations/`

## Request

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

Starts a new conversation with a participant or researcher, separate from the default one between you. Give it a subject and a topic, and optionally the study it is about and a first message.

Send further messages into it with `POST /api/v1/messages` and its `conversation_id`. Other conversations with the same person are untouched.

For participant senders, `study_id` must be a study the participant has a submission for, and the recipient must be that study's researcher, publisher or workspace. Otherwise the request is rejected with a 400.

## Request body

- CreateConversation
  - `recipient_id` string, required: The participant or researcher to start the conversation with.
  - `subject` string, required: What the conversation is about, shown as its title.
  - `topic` 'payment-timing' | 'payment-issues' | 'technical-issues' | 'feedback' | 'rejections' | 'other', required: Which of the fixed categories the conversation falls under.
  - `study_id` string: The study it relates to.
  - `workspace_id` string: Start it as this workspace rather than as yourself. Requires workspace messaging.
  - `body` string: A first message, sent into the conversation as part of creating it.

## Response `201`

The new conversation

- Conversation
  - `id` string, required: The conversation id. The same value appears as `channel_id` on its messages.
  - `members` ConversationMember[], required: Who is in the conversation. A member is a user or, for workspace messaging, a workspace.
    - `id` string, required
    - `type` 'user' | 'space', required
  - `subject` string, nullable, required: What the conversation is about. Null on conversations that predate subjects.
  - `topic` 'payment-timing' | 'payment-issues' | 'technical-issues' | 'feedback' | 'rejections' | 'other', required: One of the message categories, or null.
  - `study_id` string, nullable, required: The study the conversation is about, or null.
  - `broadcast` ConversationBroadcast: The broadcast that started the conversation, or null if it didn't come from one.
    - `id` string, required
    - `recipient_count` integer, required: How many people the broadcast went to.
    - `sent_at` string, date-time, required
  - `unread_count` integer, required: Unread messages for the caller.
  - `last_message_body` string, nullable: Body of the most recent message.
  - `datetime_created` string, date-time, required
  - `datetime_updated` string, date-time, required: When the most recent message was sent.
  - `replied` boolean: Only when listing a broadcast's conversations. Whether the recipient has replied. Your own follow-ups don't count.

## Other responses

- `400`: Error
- `503`: Message service temporarily unavailable
- `504`: Message query timed out

## Changes

- **2026-10-22** `8ad56496a97c`: 1 info
  - added the optional property `replied` to the response with the `201` status
- **2026-10-19** `d8ab5baad529`: 1 warning, 1 info
  - added the new `payment-timing` enum value to the `topic/oneOf[subschema #1: ConversationTopic]/` response property for the response status `201`
  - added the optional property `broadcast` to the response with the `201` status
- **2026-09-24** `9449de4ad274`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/prolific/apis/api-reference/changes/api/v1/conversations/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)