Create a conversation. | PlannrCRM API documentation

Create a conversation. Run in API Explorer

POST /api/v1/conversation

Personal access token & O auth2

Headers

X-PLANNR-ACCOUNT-UUID string

application/json

Body

name string Required

Conversation title
case string(uuid)

Case UUID to assign this conversation to
participants array[string(uuid)]

Account UUIDs belonging to the firm
message string

Contents of first message to be created alongside the conversation.

Responses

200 application/json
Hide response attributes Show response attributes object
- uuid string
  
  The UUID of the resource.
- created_at string
  
  The timestamp of when the resource was created.
- updated_at string
  
  The timestamp of when the resource was updated.
- name string
  
  Conversation title
- slug string
  
  Conversation title as a slug
- belongs_to_case boolean
  
  Whether or not the conversation belongs to a case.
- case object
  
  Case the conversation belongs to (if included)
  
  Hide case attributes Show case attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  name string
  
  slug string
  
  status string
  
  type string
  
  review_at string
  
  assigned_to_uuids array[string]
  
  group_uuids array[string]
  
  completed_at string
  
  value object
  
  Hide value attributes Show value attributes object
  
  amount object
  
  Hide amount attributes Show amount attributes object
  
  example string
  
  description string
  
  formatted object
  
  Hide formatted attributes Show formatted attributes object
  
  example string
  
  description string
  
  currency object
  
  Hide currency attributes Show currency attributes object
  
  example string
  
  description string
  
  status_position integer
  
  participants_count integer
  
  participants string
  
  task_board_uuid string
  
  plans string
  
  custom_fields string
- participants_count integer
  
  Number of participants in conversation (if included)
- participants array[object]
  
  Participants in this conversation (if included)
  
  Hide participants attributes Show participants attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  type string
  
  role string
  
  first_name string
  
  last_name string
  
  name string
  
  email string
  
  photo_url string
  
  firm string
  
  primary_phone_number string
  
  primary_email string
  
  current_time_entry string
  
  assigned_adviser string
  
  assigned_administrator string
  
  assigned_paraplanner string
  
  introduced_by string
  
  business_unit string
  
  groups string
  
  tags string
  
  owners string
  
  first_contact_date string
  
  next_review_date string
  
  previous_review_date string
  
  anniversary_review_date string
  
  terms_of_business_at string
  
  client_agreement_at string
  
  with_login boolean
  
  has_joint_account boolean
  
  can_be_deleted string
  
  joint_account_circle string
  
  circles string
  
  ownership_percentage integer
  
  inactive_at string
  
  last_interaction_at string
  
  referral_code string
  
  permissions object
  
  Hide permissions attributes Show permissions attributes object
  
  firm:read array[string]
  
  network:read array[string]
  
  custom_fields string
  
  external_references string
- latest_message object
  
  The latest message of the conversation (if included)
  
  Hide latest_message attributes Show latest_message attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  deleted_at string
  
  contents string
  
  edited boolean
  
  files string
  
  author string
  
  user string
  
  reactions string
- messages_count integer
  
  Number of messages in the conversation (if included)
- files_count integer
  
  Number of files in the conversation (if included)
- tags array[object]
  
  Conversation tags (if included)
  
  Hide tags attributes Show tags attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  name string
  
  slug string
  
  colour string
- pinned boolean
  
  Whether the conversation has been pinned to the top (if participants included)
- is_admin boolean
  
  If the authenticated account is an admin of the conversation (if participants included)

POST /api/v1/conversation

curl \
 --request POST 'https://api.plannrcrm.com/api/v1/conversation' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"name":"Annual Review","case":"15ef72e3-cbc5-4fae-bfd0-bc1b7855e932","participants":["37c49cfe-2624-4adb-88f0-26c2e3d90dd1","a7a0a8bc-15dc-4f13-be32-585bd508a08c","2a27c19f-8ad8-4c4d-a5ac-601e5a24f666"],"message":"Hello world!"}'

Request examples

# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "name": "Annual Review",
  "case": "15ef72e3-cbc5-4fae-bfd0-bc1b7855e932",
  "participants": [
    "37c49cfe-2624-4adb-88f0-26c2e3d90dd1",
    "a7a0a8bc-15dc-4f13-be32-585bd508a08c",
    "2a27c19f-8ad8-4c4d-a5ac-601e5a24f666"
  ],
  "message": "Hello world!"
}

Response examples (200)

{
  "uuid": "813c3c02-fd66-4b12-9572-740154f17c59",
  "created_at": "2026-05-21T13:23:45+01:00",
  "updated_at": "2026-05-21T13:23:45+01:00",
  "name": "Welcome to Plannr",
  "slug": "welcome-to-plannr",
  "belongs_to_case": true,
  "case": {
    "uuid": "694c4ae2-a2d8-4fd3-9959-1d5db8b9f2c1",
    "created_at": "2026-05-21T13:23:45+01:00",
    "updated_at": "2026-05-21T13:23:45+01:00",
    "name": "finance",
    "slug": "finance",
    "status": "App\\Http\\Resources\\CasesStatusResource",
    "type": "App\\Http\\Resources\\CasesTypeResource",
    "review_at": "2026-05-21T13:23:45+01:00",
    "assigned_to_uuids": [
      "790ceb50-a026-40d0-bd38-f84548d90c2d"
    ],
    "group_uuids": [
      "309ae35f-bd56-4de4-85ce-5722be8f776c"
    ],
    "completed_at": "2026-05-21T13:23:45+01:00",
    "value": {
      "amount": {
        "example": "4000",
        "description": "Money amount at their lowest denominator (for example: pennies)"
      },
      "formatted": {
        "example": "£40.00",
        "description": "Money amount formatted with currency"
      },
      "currency": {
        "example": "GBP",
        "description": "Currency of the money"
      }
    },
    "status_position": 4,
    "participants_count": 4,
    "participants": "App\\Http\\Resources\\AccountResource",
    "task_board_uuid": "d914dca1-f66d-45fa-a6d4-9344880848a8",
    "plans": "App\\Http\\Resources\\Plans\\PlanResource",
    "custom_fields": "App\\Http\\Resources\\CustomFieldValueResource"
  },
  "participants_count": 3,
  "participants": [
    {
      "uuid": "8b26832d-3494-4714-bab0-555172d045e3",
      "created_at": "2026-05-21T13:23:45+01:00",
      "updated_at": "2026-05-21T13:23:45+01:00",
      "type": "client",
      "role": "client",
      "first_name": "Gareth",
      "last_name": "Thompson",
      "name": "Gareth Thompson",
      "email": "gareth@codepotato.co.uk",
      "photo_url": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
      "firm": "App\\Http\\Resources\\FirmResource",
      "primary_phone_number": "App\\Http\\Resources\\ContactDetailResource",
      "primary_email": "App\\Http\\Resources\\ContactDetailResource",
      "current_time_entry": "App\\Http\\Resources\\TimeEntryResource",
      "assigned_adviser": "App\\Http\\Resources\\AccountResource",
      "assigned_administrator": "App\\Http\\Resources\\AccountResource",
      "assigned_paraplanner": "App\\Http\\Resources\\AccountResource",
      "introduced_by": "App\\Http\\Resources\\AccountResource",
      "business_unit": "App\\Http\\Resources\\BusinessUnitResource",
      "groups": "App\\Http\\Resources\\GroupResource",
      "tags": "App\\Http\\Resources\\TagResource",
      "owners": "App\\Http\\Resources\\AccountResource",
      "first_contact_date": "2026-05-21T13:23:45+01:00",
      "next_review_date": "2026-05-21T13:23:45+01:00",
      "previous_review_date": "2026-05-21T13:23:45+01:00",
      "anniversary_review_date": "2026-05-21T13:23:45+01:00",
      "terms_of_business_at": "2026-05-21T13:23:45+01:00",
      "client_agreement_at": "2026-05-21T13:23:45+01:00",
      "with_login": true,
      "has_joint_account": true,
      "can_be_deleted": "false",
      "joint_account_circle": "App\\Http\\Resources\\CircleResource",
      "circles": "App\\Http\\Resources\\CircleResource",
      "ownership_percentage": 100,
      "inactive_at": "2026-05-21",
      "last_interaction_at": "2026-05-21 13:23:45",
      "referral_code": "ABC12345",
      "permissions": {
        "firm:read": [
          "firm"
        ],
        "network:read": [
          "network:uuid"
        ]
      },
      "custom_fields": "App\\Http\\Resources\\CustomFieldValueResource",
      "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
    }
  ],
  "latest_message": {
    "uuid": "a76812d3-940f-4326-b23b-b6f9a7f1cf85",
    "created_at": "2026-05-21T13:23:45+01:00",
    "updated_at": "2026-05-21T13:23:45+01:00",
    "deleted_at": "2026-05-21T13:23:45+01:00",
    "contents": "Welcome to Plannr!",
    "edited": true,
    "files": "App\\Http\\Resources\\FileResource",
    "author": "App\\Http\\Resources\\AccountResource",
    "user": "App\\Http\\Resources\\UserResource",
    "reactions": "App\\Http\\Resources\\ReactionResource"
  },
  "messages_count": 30,
  "files_count": 2,
  "tags": [
    {
      "uuid": "4e6f44f8-60ea-4249-b3d8-62301f363f42",
      "created_at": "2026-05-21T13:23:45+01:00",
      "updated_at": "2026-05-21T13:23:45+01:00",
      "name": "Mortgage",
      "slug": "mortgage",
      "colour": "#ef4582"
    }
  ],
  "pinned": true,
  "is_admin": false
}