Start a conversation | Prolific API

curl -X POST https://api.prolific.com/api/v1/conversations/ \
     -H "Authorization: Token <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "recipient_id": "619e049f7648a4e1f8f3645b",
  "subject": "Bonus for the second session",
  "topic": "payment-issues",
  "study_id": "719e049f7648a4e1f8f3645a",
  "body": "Hi, your bonus for the second session is on its way."
}'

{
  "id": "d45c8a5e812ff990fc6546beaf888c9820f4c184f7200a45d900cf0f321f7f38",
  "members": [
    {
      "id": "619e049f7648a4e1f8f3645b",
      "type": "user"
    }
  ],
  "subject": "Bonus for the second session",
  "topic": "payment-issues",
  "study_id": "620ca2735fcbba4fa2b3211a",
  "unread_count": 1,
  "datetime_created": "2024-01-15T09:30:00Z",
  "datetime_updated": "2024-01-15T09:30:00Z",
  "last_message_body": "string"
}

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.

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>.

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