---
title: "Create a new conversation"
method: POST
path: "/conversations"
tags: ["Conversations"]
---

# Create a new conversation

`POST /conversations`

This operation creates a new conversation within an organization. The following conversation types are supported:

### Secure Conversations (`type: "secure"`)

A secure conversation can be started with a single contact or a group of contacts. All contacts must be patients and either have a Spruce account or a pending secure invite.

### Note Conversations (`type: "note"`)

A note conversation is an internal-only conversation for documenting information. Notes can optionally include organization members/groups and can be associated with contacts for organizational purposes (via `associatedContactIds`). Associated contacts will not have access to the note.

### Asynchronous Message Processing

If a message is included in the conversation creation request, the message will be posted asynchronously after the conversation is created. The API will immediately return the conversation details along with a `postMessageRequestId` that can be used to track when the message is actually sent.

The `postMessageRequestId` returned in the response can be matched against the `requestID` field of the `conversationItem.created` webhook event to identify when the message has been successfully posted to the conversation.

## Headers

- `s-idempotency-key` string

## Request body

- CreateConversation
  - `note` CreateConversationNote
    - `associatedContactIds` string[] — The ids of contacts that this note is regarding. These contacts will not have access to the note but will be associated with it for organizational purposes.
    - `memberIds` string[] — The ids of organization members or groups to include in the note conversation. If not provided, the note will be private to the creator.
    - `message` ConversationMessagePost
      - `attachments` ConversationMessagePostAttachment[]
        - `attachmentId` string, required — The id of the attachment. In most cases, this will be a media id returned from posting a file to the [media endpoint](/reference/uploadmedia).
        - `title` string, required — The title of the attachment
      - `author` string — The ID of the organization member (teammate, team, or organization) to send the message as. If not provided, defaults to the organization.
      - `body` ConversationMessageBodyElement[], required
        - `type` 'text' | 'page', required
        - `value` string, required — The value of the message body element
      - `internal` boolean — Whether the message is internal or not
      - `stayArchived` boolean — Whether the conversation should stay archived (if it is already archived) after the message is sent
    - `title` string — The title of the note conversation. If not provided, a default title will be generated.
  - `secure` CreateConversationSecure
    - `destinationContactIds` string[], required — The ids of the destination contacts.
    - `internalEndpointId` string, required — Organization's internal endpoint ID that will be used as the internal endpoint for the conversation.
    - `message` ConversationMessagePost
      - `attachments` ConversationMessagePostAttachment[]
        - `attachmentId` string, required — The id of the attachment. In most cases, this will be a media id returned from posting a file to the [media endpoint](/reference/uploadmedia).
        - `title` string, required — The title of the attachment
      - `author` string — The ID of the organization member (teammate, team, or organization) to send the message as. If not provided, defaults to the organization.
      - `body` ConversationMessageBodyElement[], required
        - `type` 'text' | 'page', required
        - `value` string, required — The value of the message body element
      - `internal` boolean — Whether the message is internal or not
      - `stayArchived` boolean — Whether the conversation should stay archived (if it is already archived) after the message is sent
    - `subject` string — The conversation's subject.
  - `type` 'secure' | 'note', required — The type of conversation to create.

## Response `201`

created

- object
  - `conversation` Conversation, required
    - `apiURL` string, url, required — An absolute URL for fetching this conversation from the API
    - `appURL` string, url, required — An absolute URL to view the conversation in the Spruce app
    - `archived` boolean, required — Whether or not the conversation is archived
    - `assignedToMemberId` string — The id of the teammate the conversation is assigned to
    - `associatedContactIds` string[] — The ids of the contacts associated with the conversation. This may include contacts that are not a part of the conversation. For example, the conversation may be with parents, but associated with a contact representing their child.
    - `createdAt` string, date-time, required — The date the conversation was created
    - `externalParticipants` object[] — The external participants in the conversation.
      - `contact` string — The id of the contact associated with the participant. This will be omitted if the participant is not a saved contact.
      - `displayName` string, required — The display name of the participant
      - `endpoint` Endpoint
        - `channel` 'email' | 'phone' | 'fax' | 'secure', required — The channel of the endpoint (e.g. 'email', 'phone', 'fax', etc.). More endpoint channels may be added in the future, so ensure while parsing this that you gracefully handle any new/unexpected values.
        - `displayValue` string, required — The display value of the endpoint. This is the value that should be displayed to the user when showing the endpoint, along with the label if it's populated.
        - `id` string, required — The id of the endpoint. For secure (Spruce Link) endpoints, the id format depends on where the endpoint is returned: the list internal endpoints API returns the underlying organization invite id, while a secure endpoint that appears on a conversation is returned with a different, derived value. To determine whether a conversation belongs to a particular Spruce Link, compare `endpoint.rawValue` rather than `endpoint.id`. Endpoint ids for phone, fax, and email channels use the same format across responses.
        - `isInternal` boolean, required — Internal endpoints are endpoints that are owned by your organization, such as your organization's Spruce Phone Numbers or Spruce Links.
        - `label` string — The optional label of the endpoint
        - `object` string, required — String representing the object's type
        - `rawValue` string, required — The raw value of the endpoint. This can be used for programmatically comparing contact values, and is the stable identifier to use when matching a secure endpoint on a conversation back to the corresponding Spruce Link returned by the list internal endpoints API. The raw value for a phone/fax number will be in E164 format.
    - `id` string, required — Spruce's conversation ID
    - `internalEndpoint` Endpoint
      - `channel` 'email' | 'phone' | 'fax' | 'secure', required — The channel of the endpoint (e.g. 'email', 'phone', 'fax', etc.). More endpoint channels may be added in the future, so ensure while parsing this that you gracefully handle any new/unexpected values.
      - `displayValue` string, required — The display value of the endpoint. This is the value that should be displayed to the user when showing the endpoint, along with the label if it's populated.
      - `id` string, required — The id of the endpoint. For secure (Spruce Link) endpoints, the id format depends on where the endpoint is returned: the list internal endpoints API returns the underlying organization invite id, while a secure endpoint that appears on a conversation is returned with a different, derived value. To determine whether a conversation belongs to a particular Spruce Link, compare `endpoint.rawValue` rather than `endpoint.id`. Endpoint ids for phone, fax, and email channels use the same format across responses.
      - `isInternal` boolean, required — Internal endpoints are endpoints that are owned by your organization, such as your organization's Spruce Phone Numbers or Spruce Links.
      - `label` string — The optional label of the endpoint
      - `object` string, required — String representing the object's type
      - `rawValue` string, required — The raw value of the endpoint. This can be used for programmatically comparing contact values, and is the stable identifier to use when matching a secure endpoint on a conversation back to the corresponding Spruce Link returned by the list internal endpoints API. The raw value for a phone/fax number will be in E164 format.
    - `internalMemberIds` string[] — The ids of the teammates, teams and/or your organization that are members of the conversation.
    - `isReadOnly` boolean, required — If the conversation is read-only, messages cannot be sent to it.
    - `lastMessageAt` string, date-time — The time of the conversations latest message
    - `object` string, required — String representing the object's type
    - `subtitle` string — The subtitle of the conversation
    - `tags` ConversationTag[], required
      - `id` string, required — Spruce's conversation tag ID
      - `object` string, required — String representing the object's type
      - `value` string, required — The text value of a conversation tag
    - `title` string, required — The title of the conversation
    - `type` 'email' | 'phone' | 'secure' | 'fax' | 'team' | 'note' | 'other', required — The type of the conversation (e.g. 'email', 'phone', 'secure', etc.). Note that SMS will be in a 'phone' conversation, and video calls will be in a 'secure' conversation. More conversation types may be added in the future, so ensure while parsing this that you gracefully handle any new/unexpected values.
  - `postMessageRequestId` string — The id of an asynchronous request

## Other responses

- `400` — bad request
- `500` — unexpected error

---

[API](https://skmtc.net/sprucehealth/apis/spruce-health-api.md) · [All operations](https://skmtc.net/sprucehealth/apis/spruce-health-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sprucehealth/spruce-health-api/revisions/988e298cd9fd/schema)