openapi: 3.0.0
info:
title: Spruce Health API — Conversation Item
version: 1.0.0
description: The Conversation Item operations of the Spruce Health API, split by tag from the OpenAPI
Spruce Health publishes for developer.sprucehealth.com (ReadMe registry @spruce/v1.0#13needamst2v4m6).
Base https://api.sprucehealth.com/v1, Bearer organization token.
contact:
name: Spruce Health
url: https://developer.sprucehealth.com
servers:
- url: https://api.sprucehealth.com/v1
variables:
domain:
default: api.sprucehealth.com
security:
- spruceAPIToken: []
tags:
- name: Conversation Item
paths:
/conversationItems/{conversationItemId}:
delete:
description: 'Deletes a specific conversation item by ID. This operation follows the same business
rules as the in-app delete mechanism, including permission checks and content restrictions.
**Soft Delete Behavior**: The API performs a soft delete, creating a placeholder that can be restored
by users with appropriate access. The conversation item will be marked as deleted but not permanently
removed from the system.
**Permission Requirements**: You can only delete conversation items in conversations owned by
your organization. The deletion must comply with the same restrictions as the Spruce app (e.g.,
certain system messages cannot be deleted).
**Asynchronous Processing**: The deletion is processed asynchronously. The API immediately returns
a `requestId` that can be used to correlate this deletion request with webhook events when the
deletion is actually completed.
'
operationId: DeleteConversationItem
parameters:
- description: The id of the conversation item to delete
in: path
name: conversationItemId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
requestId:
$ref: '#/components/schemas/asyncRequest_id'
required:
- requestId
type: object
description: Expected response to a valid request
headers:
s-ratelimit-limit:
$ref: '#/components/headers/s-ratelimit-limit'
s-ratelimit-remaining:
$ref: '#/components/headers/s-ratelimit-remaining'
s-request-id:
$ref: '#/components/headers/s-request-id'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: bad request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: forbidden - user does not have permission to delete this conversation item
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: not found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: unexpected error
summary: Delete a conversation item
tags:
- Conversation Item
get:
description: This operation fetches a specific conversation item for the provided id.
operationId: ConversationItem
parameters:
- description: The id of the conversation item to retrieve
in: path
name: conversationItemId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
conversationItem:
$ref: '#/components/schemas/conversationItem'
required:
- conversationItem
type: object
description: Expected response to a valid request
headers:
s-ratelimit-limit:
$ref: '#/components/headers/s-ratelimit-limit'
s-ratelimit-remaining:
$ref: '#/components/headers/s-ratelimit-remaining'
s-request-id:
$ref: '#/components/headers/s-request-id'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: bad request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: not found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: unexpected error
summary: Get a conversation item for a given id
tags:
- Conversation Item
components:
headers:
s-ratelimit-limit:
description: Request limit per minute
example: 100
schema:
type: integer
s-ratelimit-remaining:
description: Requests remaining this minute
example: 94
schema:
type: integer
s-request-id:
description: The ID of the request
example: 0E5QDGJC030000E5QDGJC03000
schema:
type: string
schemas:
answeredBy:
properties:
externalNumber:
description: the telephone number external to Spruce this call was answered by
type: string
lineId:
description: the ID of the phone line on the Spruce system this call was answered by
type: string
teammateID:
$ref: '#/components/schemas/teammate_id'
type: object
asyncRequest_id:
description: The id of an asynchronous request
example: asyncRequest_0D4QABCC06000
type: string
conversation:
properties:
apiURL:
description: An absolute URL for fetching this conversation from the API
example: https://api.sprucehealth.com/conversations/t_0E5QDJJC03000
format: url
type: string
appURL:
description: An absolute URL to view the conversation in the Spruce app
example: https://app.sprucehealth.com/org/entity_0D4QABCC06000/thread/t_0E5QDJJC03000
format: url
type: string
archived:
description: Whether or not the conversation is archived
example: false
type: boolean
assignedToMemberId:
description: The id of the teammate the conversation is assigned to
example: entity_0D4QABCC06000
type: string
associatedContactIds:
description: 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.
example:
- entity_0D4QABCC06000
items:
type: string
type: array
createdAt:
description: The date the conversation was created
example: '2020-04-01T00:00:00Z'
format: date-time
type: string
externalParticipants:
description: The external participants in the conversation.
items:
properties:
contact:
description: The id of the contact associated with the participant. This will be omitted
if the participant is not a saved contact.
example: entity_0D4QABCC06000
type: string
displayName:
description: The display name of the participant
example:
- 555-555-5555
- John Doe
- patient@example.com
type: string
endpoint:
$ref: '#/components/schemas/endpoint'
description: The endpoint of the participant, such as their phone number or email address.
For secure conversations, there will not be an endpoint.
required:
- displayName
type: object
type: array
id:
$ref: '#/components/schemas/conversation_id'
internalEndpoint:
$ref: '#/components/schemas/endpoint'
description: 'The internal endpoint of the conversation. For secure conversations, this will
be a Spruce Link.
Note: for secure endpoints, the `id` returned here is a derived value that will not equal
the `endpoint.id` returned for the same Spruce Link by the list internal endpoints API. Use
`rawValue` to match a conversation''s secure internal endpoint to the corresponding Spruce
Link. Endpoint ids for phone, fax, and email channels use the same format across responses
and can be compared directly.
'
internalMemberIds:
description: The ids of the teammates, teams and/or your organization that are members of the
conversation.
example:
- entity_0D4QABCC06000
items:
type: string
type: array
isReadOnly:
description: If the conversation is read-only, messages cannot be sent to it.
example: false
type: boolean
lastMessageAt:
description: The time of the conversations latest message
example: '2020-04-01T00:00:00Z'
format: date-time
type: string
object:
$ref: '#/components/schemas/objectType'
subtitle:
description: The subtitle of the conversation
example: Billing
type: string
tags:
$ref: '#/components/schemas/conversation_tags'
title:
description: The title of the conversation
example: John Doe
type: string
type:
description: 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.
enum:
- email
- phone
- secure
- fax
- team
- note
- other
type: string
required:
- appURL
- apiURL
- archived
- createdAt
- id
- isReadOnly
- tags
- type
- title
- object
type: object
conversationItem:
properties:
apiURL:
description: An absolute URL for fetching this conversation item from the API
example: https://api.sprucehealth.com/conversationItems/ti_0E5QDJJC03000
format: url
type: string
appURL:
description: An absolute URL to view the conversation item in the Spruce app.
example: https://app.sprucehealth.com/org/entity_0D4QABCC06000/thread/t_0E5QDJJC03000/message/ti_23170B3D36G00
format: url
type: string
attachments:
description: Attachments for the conversation item.
items:
$ref: '#/components/schemas/conversationItem_Attachment'
type: array
author:
$ref: '#/components/schemas/conversationItem_Author'
description: The author of the conversation item.
buttons:
description: The buttons associated with the conversation item.
items:
$ref: '#/components/schemas/conversationItem_Button'
type: array
canDelete:
description: If the conversation item can be deleted.
example: true
type: boolean
conversation:
$ref: '#/components/schemas/conversation'
description: The parent conversation object. This field is only present in webhook event payloads
(e.g. conversationItem.created) and is omitted from REST API responses.
conversationId:
$ref: '#/components/schemas/conversation_id'
createdAt:
description: The date time the conversation item was created.
example: '2020-04-01T00:00:00Z'
format: date-time
type: string
direction:
description: The direction of the item relative to this organization. Possible values are `inbound`,
`outbound` and `none`. `inbound` indicates a message received by the organization, `outbound`
indicates a message sent to an external contact by a teammate in the organization. `none`
indicates a message that is likely internal to the organization or one for which the direction
cannot be determined.
enum:
- inbound
- outbound
- none
type: string
event:
$ref: '#/components/schemas/conversationItem_Event'
description: Any event data associate with the conversation item.
id:
$ref: '#/components/schemas/conversationItem_id'
isInternalNote:
description: If the conversation item is an internal note - which is visible only to the posting
side of the conversation.
example: false
type: boolean
modifiedAt:
description: The date time the conversation item was last modified.
example: '2020-04-01T00:00:00Z'
format: date-time
type: string
object:
$ref: '#/components/schemas/objectType'
pages:
description: The pages associated with the conversation item.
items:
$ref: '#/components/schemas/conversationItem_Page'
type: array
requestId:
$ref: '#/components/schemas/asyncRequest_id'
text:
description: The text of the conversation item. If the conversation item contains pages, they
will be listed in the pages property.
example: Can you look at this @Dr. Smith?
type: string
required:
- id
- conversationId
- attachments
- author
- direction
- isInternalNote
- appURL
- apiURL
- text
- pages
- buttons
- modifiedAt
- createdAt
- object
- requestId
- canDelete
type: object
conversationItem_Attachment:
properties:
data:
anyOf:
- $ref: '#/components/schemas/conversationItem_AudioAttachment'
- $ref: '#/components/schemas/conversationItem_DocumentAttachment'
- $ref: '#/components/schemas/conversationItem_EntityProfileAttachment'
- $ref: '#/components/schemas/conversationItem_ImageAttachment'
- $ref: '#/components/schemas/conversationItem_VideoAttachment'
title:
description: The title of the attachment.
example: example.pdf
type: string
type:
description: The type of the attachment.
enum:
- audio
- carePlan
- document
- entityProfile
- genericUrl
- image
- paymentRequest
- video
- visit
type: string
required:
- title
- type
type: object
conversationItem_AudioAttachment:
properties:
mimetype:
description: The mimetype of the audio attachment.
example: audio/mpeg
type: string
signedUrl:
$ref: '#/components/schemas/signedUrl'
description: The URL used to fetch the audio attachment.
transcription:
$ref: '#/components/schemas/conversationItem_Transcription'
description: The transcription for this audio attachment, if available. Use the [Transcription
endpoint](/reference/transcription) to fetch the full transcription text.
required:
- mimetype
- signedUrl
type: object
conversationItem_Author:
properties:
deviceInformation:
$ref: '#/components/schemas/deviceInformation'
displayName:
type: string
id:
description: 'The id of the entity that authored the conversation item, populated only when
it identifies a stable Spruce entity. It will be set for items authored by a teammate, team,
or your organization, and for items received from a saved contact through Spruce secure messaging
(where the id matches the contact id). It will be omitted for items received from a contact
over a standard channel (SMS, voice, email, or fax) because the sender''s identity is derived
from an endpoint (such as a phone number or email address) that can be reassigned to a different
contact over time. It may also be omitted for system-generated items or when the author entity
could not be resolved.
'
example: entity_0D4QABCC06000
type: string
required:
- displayName
type: object
conversationItem_Button:
properties:
id:
description: The id of the button.
type: string
state:
description: The state of the button.
enum:
- disabled
- normal
- selected
type: string
text:
description: The text of the button.
type: string
required:
- id
- text
- state
type: object
conversationItem_DocumentAttachment:
properties:
mimetype:
description: The mimetype of the document attachment.
example: application/pdf
type: string
name:
description: The name associated with the attached document.
type: string
signedUrl:
$ref: '#/components/schemas/signedUrl'
description: The URL used to fetch the document attachment.
required:
- name
- mimetype
- signedUrl
type: object
conversationItem_EntityProfileAttachment:
properties:
title:
description: The title associated with the attached entity profile.
example: John Smith
type: string
url:
description: The URL of the entity profile.
type: string
required:
- title
- url
type: object
conversationItem_Event:
properties:
data:
anyOf:
- $ref: '#/components/schemas/conversationItem_PhoneCallEvent'
- $ref: '#/components/schemas/conversationItem_VideoCallEvent'
type:
description: The type of the event. Additional events will be added in the future, so any parsing
of this field should gracefully handle unexpected values.
enum:
- inboundCall
- inboundVideoCall
- outboundCall
- outboundVideoCall
type: string
required:
- type
type: object
conversationItem_ImageAttachment:
properties:
mimetype:
description: The mimetype of the image attachment.
example: image/png
type: string
signedUrl:
$ref: '#/components/schemas/signedUrl'
description: The URL used to fetch the image attachment.
required:
- mimetype
- signedUrl
type: object
conversationItem_Page:
properties:
id:
description: The id of the page.
type: string
memberId:
description: The id of the teammate being paged.
example: entity_0D4QABCC06000
type: string
resolved:
description: If the page has been resolved.
type: boolean
resolvedAt:
description: The date time the page was resolved at.
example: '2020-04-01T00:00:00Z'
format: date-time
type: string
resolvedByMemberId:
description: The id of the teammate that resolved the page.
example: entity_0D4QABCC06000
type: string
required:
- id
- memberId
- resolved
type: object
conversationItem_PhoneCallEvent:
properties:
answered:
description: If the call was answered.
type: boolean
answeredBy:
$ref: '#/components/schemas/answeredBy'
description: If an inbound call was answered, which desk phone or external phone number answered
it.
callFlowMenuOption:
description: For inbound calls that went through a Call Flow menu, the description of the specific
menu option the caller selected (e.g., "Option 1 - Billing Questions"). This represents the
final node reached in the call flow.
example: Option 2 - Hours and Locations
type: string
callFlowTopLevelMenuOption:
description: For inbound calls that went through a Call Flow menu with nested options, the description
of the first-level (top-level) menu option the caller selected. This helps identify the main
category chosen before any sub-menu navigation.
example: Main Menu - Press 1 for Appointments
type: string
duration:
description: The duration of the call in seconds.
type: integer
failed:
description: If the call failed.
type: boolean
initiatedBy:
$ref: '#/components/schemas/initiatedBy'
description: For outbound calls, which desk phone or teammate initiated it.
recordings:
description: The recordings of the call if any exist.
items:
$ref: '#/components/schemas/conversationItem_AudioAttachment'
type: array
spam:
description: If the call was marked as spam.
type: boolean
voicemail:
$ref: '#/components/schemas/conversationItem_AudioAttachment'
required:
- answered
- duration
- failed
- inbound
- spam
type: object
conversationItem_Transcription:
properties:
id:
description: The id of the transcription job. Pass this to the [Transcription endpoint](/reference/transcription)
to fetch the full transcription text.
type: string
status:
description: The current status of the transcription. When `pending`, the transcription is still
being processed.
enum:
- completed
- pending
- failed
- noSpeech
type: string
summarizationStatus:
description: The current status of the summarization, if the transcription is being summarized.
Null when no summarization was requested.
enum:
- completed
- pending
- failed
type: string
required:
- id
- status
type: object
conversationItem_VideoAttachment:
properties:
mimetype:
description: The mimetype of the video attachment.
example: video/mp4
type: string
signedUrl:
$ref: '#/components/schemas/signedUrl'
description: The URL used to fetch the video attachment.
required:
- mimetype
- signedUrl
type: object
conversationItem_VideoCallEvent:
properties:
answered:
description: If the call was answered.
type: boolean
duration:
description: The duration of the call in seconds.
type: integer
initiatedBy:
$ref: '#/components/schemas/teammate_id'
description: The Spruce is of the teammate that initiated it..
required:
- answered
- duration
- initiatedBy
type: object
conversationItem_id:
description: The id of a conversation item.
example: ti_0D4QABCC06000
type: string
conversation_id:
description: Spruce's conversation ID
example: t_0E5QDGJC03000
type: string
conversation_tag:
properties:
id:
$ref: '#/components/schemas/conversation_tagId'
object:
$ref: '#/components/schemas/objectType'
value:
$ref: '#/components/schemas/conversation_tagValue'
required:
- id
- value
- object
type: object
conversation_tagId:
description: Spruce's conversation tag ID
example: tag_0E5QDGJC03000
type: string
conversation_tagValue:
description: The text value of a conversation tag
example: Smith
type: string
conversation_tags:
items:
$ref: '#/components/schemas/conversation_tag'
type: array
deviceInformation:
properties:
accessID:
description: The access ID of API credentials used to make the request.
type: string
appVersion:
description: The version of the app.
type: string
device:
description: The type of the device.
type: string
deviceId:
description: The id of the device.
type: string
deviceModel:
description: The model of the device.
type: string
platform:
description: The platform of the device.
type: string
type: object
endpoint:
properties:
channel:
description: 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.
enum:
- email
- phone
- fax
- secure
type: string
displayValue:
description: 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.
example:
email:
value: patient@example.com
phone:
value: (555) 555-5555
secure:
value: spruce.care/123456
type: string
id:
$ref: '#/components/schemas/endpoint_id'
isInternal:
description: Internal endpoints are endpoints that are owned by your organization, such as your
organization's Spruce Phone Numbers or Spruce Links.
example: false
type: boolean
label:
description: The optional label of the endpoint
example:
- Home
- Work
type: string
object:
$ref: '#/components/schemas/objectType'
rawValue:
description: 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.
example:
email:
value: patient@example.com
phone:
value: 15555555555
secure:
value: https://spruce.care/123456
type: string
required:
- id
- channel
- displayValue
- rawValue
- isInternal
- object
type: object
endpoint_id:
description: '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.
'
example: 15555555555
type: string
error:
properties:
message:
example: Invalid Contact ID
type: string
statusCode:
example: 400
type: integer
type:
example: BAD_PARAMETER
type: string
required:
- message
- statusCode
- type
type: object
initiatedBy:
properties:
lineId:
description: the ID of the phone line on the Spruce system this call was initiated by
type: string
teammateID:
$ref: '#/components/schemas/teammate_id'
type: object
objectType:
description: String representing the object's type
type: string
signedUrl:
properties:
expiresAt:
description: The date the signed URL expires.
format: date-time
type: string
url:
description: The signed URL.
format: url
type: string
required:
- url
- expiresAt
type: object
teammate_id:
description: The id of the teammate
example: entity_0E5QDGJC03000
type: string
securitySchemes:
spruceAPIToken:
description: API token provided by Spruce should be passed in an "Authorization" header with the
value "Bearer <token>"
scheme: bearer
type: http