Skip to navigation
API ReferenceMessages

Start a conversation

View as MarkdownOpen in Claude

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.

Authentication

AuthorizationToken

The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.

Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.

If your token is leaked, delete it and create a new one directly in the app.

In your requests add Authorization header with the value Token <your token>.

Request

This endpoint expects an object.
recipient_idstringRequired
The participant or researcher to start the conversation with.
subjectstringRequired<=500 characters
What the conversation is about, shown as its title.
topicenumRequired
Which of the fixed categories the conversation falls under.
study_idstringOptional
The study it relates to.
workspace_idstringOptional
Start it as this workspace rather than as yourself. Requires workspace messaging.
bodystringOptional<=10000 characters
A first message, sent into the conversation as part of creating it.

Response

The new conversation
idstring

The conversation id. The same value appears as channel_id on its messages.

memberslist of objects
Who is in the conversation. A member is a user or, for workspace messaging, a workspace.
subjectstring or null
What the conversation is about. Null on conversations that predate subjects.
topicenum or null
One of the message categories, or null.
Allowed values:
study_idstring or null
The study the conversation is about, or null.
unread_countinteger
Unread messages for the caller.
datetime_createddatetime
datetime_updateddatetime
When the most recent message was sent.
last_message_bodystring or nullOptional
Body of the most recent message.

Errors

4XX
Client Request Error
503
Service Unavailable Error
504
Gateway Timeout Error