List, create, retrieve, and update conversations (message threads) in an organization, and manage conversation tags. Listing supports cursor pagination and ordering by creation time or last message.
openapi: 3.0.3
info:
title: Spruce Public API
description: >-
The Spruce Public API connects a Spruce Health organization to internal
tools, electronic health records (EHRs), practice management systems, and
other external systems so practices can automate workflows, sync data, and
receive real-time events. It is a RESTful API over HTTPS with a base URL of
https://api.sprucehealth.com/v1 and Bearer token authentication
(Authorization: Bearer <your-token>); tokens are generated by administrators
from the "API Access" section of Settings after Spruce Support enables API
access for the organization (API access is part of the Communicator plan).
Grounding note: the base URL and Bearer auth are confirmed from the Spruce
developer documentation, and the following paths are confirmed directly from
the API reference: GET /contacts, GET /conversations,
POST /conversations/{conversationId}/messages, GET /webhooks/endpoints,
POST /webhooks/endpoints, and GET /internalendpoints. The remaining paths and
all request/response schemas are honestly MODELED from the published
operation catalog (developer.sprucehealth.com/llms.txt) and documented
behavior; exact request/response bodies should be reconciled against the
live reference and the machine-readable OpenAPI Spruce publishes.
version: '1.0'
contact:
name: Spruce Health
url: https://developer.sprucehealth.com
x-endpointsModeled: true
servers:
- url: https://api.sprucehealth.com/v1
description: Spruce Public API
security:
- bearerAuth: []
tags:
- name: Contacts
description: Contacts (patients and other parties) in a Spruce organization.
- name: Conversations
description: Conversations (message threads) in a Spruce organization.
- name: Messages
description: Conversation items, messages, media, endpoints, and scheduled messages.
- name: Webhooks
description: Webhook endpoints for real-time contact / conversation events.
paths:
/contacts:
get:
operationId: listContacts
tags:
- Contacts
summary: List contacts
description: Lists all contacts available to a given organization. Confirmed path.
parameters:
- name: pageSize
in: query
schema:
type: integer
format: int32
minimum: 1
maximum: 200
- name: paginationToken
in: query
schema:
type: string
responses:
'200':
description: A list of contacts.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
'403':
$ref: '#/components/responses/Forbidden'
post:
operationId: createContact
tags:
- Contacts
summary: Create a contact
description: Creates a new contact in the organization. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
responses:
'200':
description: The created contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'403':
$ref: '#/components/responses/Forbidden'
/contacts/search:
get:
operationId: searchContacts
tags:
- Contacts
summary: Search contacts
description: Search contacts by name, phone, email, or other fields. Modeled.
parameters:
- name: query
in: query
schema:
type: string
responses:
'200':
description: Matching contacts.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
/contacts/{contactId}:
parameters:
- name: contactId
in: path
required: true
schema:
type: string
get:
operationId: contact
tags:
- Contacts
summary: Get a contact
description: Retrieves a single contact by ID. Modeled.
responses:
'200':
description: The requested contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'403':
$ref: '#/components/responses/Forbidden'
patch:
operationId: updateContact
tags:
- Contacts
summary: Update a contact
description: Updates fields on an existing contact. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
responses:
'200':
description: The updated contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
delete:
operationId: deleteContact
tags:
- Contacts
summary: Delete a contact
description: Deletes a contact from the organization. Modeled.
responses:
'204':
description: Contact deleted.
/contacts/{contactId}/conversations:
parameters:
- name: contactId
in: path
required: true
schema:
type: string
get:
operationId: contactConversations
tags:
- Contacts
summary: List a contact's conversations
description: Lists the conversations associated with a contact. Modeled.
responses:
'200':
description: Conversations for the contact.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Conversation'
/contacts/{contactId}/integration-links:
parameters:
- name: contactId
in: path
required: true
schema:
type: string
get:
operationId: contactIntegrationLinks
tags:
- Contacts
summary: List a contact's integration links
description: Lists links between a contact and external systems (EHR/PM). Modeled.
responses:
'200':
description: Integration links for the contact.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/IntegrationLink'
post:
operationId: createContactIntegrationLink
tags:
- Contacts
summary: Create a contact integration link
description: Links a contact to a record in an external system. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationLink'
responses:
'200':
description: The created integration link.
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationLink'
/contacts/fields:
get:
operationId: contactFields
tags:
- Contacts
summary: List contact custom fields
description: Lists the custom fields defined for contacts. Modeled.
responses:
'200':
description: Contact fields.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
post:
operationId: createContactField
tags:
- Contacts
summary: Create a contact custom field
description: Creates a new custom field for contacts. Modeled.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The created contact field.
/contacts/tags:
get:
operationId: contactTags
tags:
- Contacts
summary: List contact tags
description: Lists the tags that can be applied to contacts. Modeled.
responses:
'200':
description: Contact tags.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Tag'
post:
operationId: createContactTag
tags:
- Contacts
summary: Create a contact tag
description: Creates a new contact tag. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
responses:
'200':
description: The created contact tag.
/conversations:
get:
operationId: listConversations
tags:
- Conversations
summary: List conversations
description: Lists conversations in the organization. Confirmed path and parameters.
parameters:
- name: pageSize
in: query
schema:
type: integer
format: int32
minimum: 1
maximum: 200
description: How many conversations to return at one time (max 200).
- name: paginationToken
in: query
schema:
type: string
description: Token to fetch subsequent pages; cannot be combined with startFrom.
- name: orderBy
in: query
required: true
schema:
type: string
enum:
- created
- last_message
description: Order results by creation time or last message.
- name: startFrom
in: query
schema:
type: string
format: date-time
description: Only return conversations whose ordering field value is at or after this RFC 3339 timestamp.
responses:
'200':
description: A list of conversations.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Conversation'
'403':
$ref: '#/components/responses/Forbidden'
post:
operationId: createConversation
tags:
- Conversations
summary: Create a conversation
description: Creates a new conversation. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
responses:
'200':
description: The created conversation.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
/conversations/{conversationId}:
parameters:
- name: conversationId
in: path
required: true
schema:
type: string
get:
operationId: conversation
tags:
- Conversations
summary: Get a conversation
description: Retrieves a single conversation by ID. Modeled.
responses:
'200':
description: The requested conversation.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
patch:
operationId: updateConversation
tags:
- Conversations
summary: Update a conversation
description: Updates an existing conversation. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
responses:
'200':
description: The updated conversation.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
/conversations/tags:
get:
operationId: conversationTags
tags:
- Conversations
summary: List conversation tags
description: Lists the tags that can be applied to conversations. Modeled.
responses:
'200':
description: Conversation tags.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Tag'
post:
operationId: createConversationTag
tags:
- Conversations
summary: Create a conversation tag
description: Creates a new conversation tag. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
responses:
'200':
description: The created conversation tag.
/conversations/{conversationId}/messages:
parameters:
- name: conversationId
in: path
required: true
schema:
type: string
post:
operationId: postConversationMessage
tags:
- Messages
summary: Post a message to a conversation
description: Posts a new message into a conversation. Confirmed path.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCreate'
responses:
'200':
description: The created conversation item (message).
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationItem'
'403':
$ref: '#/components/responses/Forbidden'
/conversations/{conversationId}/items:
parameters:
- name: conversationId
in: path
required: true
schema:
type: string
get:
operationId: conversationItems
tags:
- Messages
summary: List conversation items
description: Lists the items (messages, calls, faxes, events) in a conversation. Modeled.
responses:
'200':
description: Conversation items.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ConversationItem'
/conversations/{conversationId}/items/{itemId}:
parameters:
- name: conversationId
in: path
required: true
schema:
type: string
- name: itemId
in: path
required: true
schema:
type: string
get:
operationId: conversationItem
tags:
- Messages
summary: Get a conversation item
description: Gets a conversation item for a given id. Modeled path (operation confirmed).
responses:
'200':
description: The conversation item.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationItem'
delete:
operationId: deleteConversationItem
tags:
- Messages
summary: Delete a conversation item
description: Deletes a conversation item. Modeled.
responses:
'204':
description: Item deleted.
/internalendpoints:
get:
operationId: internalEndpoints
tags:
- Messages
summary: List internal endpoints
description: Lists all internal endpoints (phone lines / addresses) an organization can communicate with. Confirmed path.
responses:
'200':
description: Internal endpoints.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Endpoint'
/internalendpoints/{endpointId}/messages:
parameters:
- name: endpointId
in: path
required: true
schema:
type: string
post:
operationId: postMessageFromEndpoint
tags:
- Messages
summary: Send a message from an internal endpoint
description: Sends a message (e.g. SMS/secure) from a given internal endpoint. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCreate'
responses:
'200':
description: The created conversation item.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationItem'
/proxy-calls:
post:
operationId: postCreateProxyCall
tags:
- Messages
summary: Create a proxy call
description: Creates a proxy (bridge) call between a member and a contact. Modeled.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The created proxy call.
/media:
post:
operationId: uploadMedia
tags:
- Messages
summary: Upload media
description: Uploads media for use as a message attachment. Modeled.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
responses:
'200':
description: The uploaded media reference.
/scheduled-messages:
get:
operationId: listScheduledMessages
tags:
- Messages
summary: List scheduled messages
description: Lists scheduled messages for the organization. Modeled.
responses:
'200':
description: Scheduled messages.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
/conversations/{conversationId}/scheduled-messages:
parameters:
- name: conversationId
in: path
required: true
schema:
type: string
get:
operationId: listConversationScheduledMessages
tags:
- Messages
summary: List a conversation's scheduled messages
description: Lists scheduled messages for a conversation. Modeled.
responses:
'200':
description: Scheduled messages for the conversation.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
post:
operationId: scheduleConversationMessage
tags:
- Messages
summary: Schedule a message in a conversation
description: Schedules a message to be sent in a conversation at a future time. Modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCreate'
responses:
'200':
description: The scheduled message.
/scheduled-messages/{scheduledMessageId}:
parameters:
- name: scheduledMessageId
in: path
required: true
schema:
type: string
delete:
operationId: deleteScheduledMessage
tags:
- Messages
summary: Delete a scheduled message
description: Deletes a scheduled message before it is sent. Modeled.
responses:
'204':
description: Scheduled message deleted.
/saved-messages:
get:
operationId: listSavedMessages
tags:
- Messages
summary: List saved messages
description: Lists saved (canned/template) messages for the organization. Modeled.
responses:
'200':
description: Saved messages.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
/webhooks/endpoints:
get:
operationId: listWebhookEndpoints
tags:
- Webhooks
summary: List webhook endpoints
description: Lists the endpoints an organization has registered for webhooks (secret keys are not returned). Confirmed path.
responses:
'200':
description: Webhook endpoints.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WebhookEndpoint'
post:
operationId: createWebhookEndpoint
tags:
- Webhooks
summary: Create a webhook endpoint
description: >-
Registers a new HTTPS webhook endpoint with a name and destination URL.
The response includes a signing secret used to verify event signatures;
the endpoint must respond 2XX within 5 seconds. Confirmed path.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointCreate'
responses:
'200':
description: The created webhook endpoint, including its signing secret.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
'403':
$ref: '#/components/responses/Forbidden'
/webhooks/endpoints/{endpointId}:
parameters:
- name: endpointId
in: path
required: true
schema:
type: string
get:
operationId: webhookEndpoint
tags:
- Webhooks
summary: Get a webhook endpoint
description: Retrieves a webhook endpoint by ID. Modeled.
responses:
'200':
description: The webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
delete:
operationId: deleteWebhookEndpoint
tags:
- Webhooks
summary: Delete a webhook endpoint
description: Deletes a webhook endpoint. Modeled.
responses:
'204':
description: Webhook endpoint deleted.
/webhooks/endpoints/{endpointId}/events:
parameters:
- name: endpointId
in: path
required: true
schema:
type: string
get:
operationId: listWebhookEndpointEvents
tags:
- Webhooks
summary: List a webhook endpoint's events
description: Lists the events delivered (or attempted) for a webhook endpoint. Modeled.
responses:
'200':
description: Webhook endpoint events.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WebhookEvent'
/webhooks/endpoints/{endpointId}/paused:
parameters:
- name: endpointId
in: path
required: true
schema:
type: string
put:
operationId: modifyWebhookEndpointPaused
tags:
- Webhooks
summary: Pause or resume a webhook endpoint
description: Pauses or resumes dispatch of events to a webhook endpoint. Modeled.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
paused:
type: boolean
responses:
'200':
description: The updated webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Organization API token generated in Settings after Spruce Support enables API access.
responses:
Forbidden:
description: Missing, incorrect, or disabled API token.
content:
application/json:
schema:
type: object
properties:
error:
type: string
schemas:
Contact:
type: object
properties:
id:
type: string
displayName:
type: string
firstName:
type: string
lastName:
type: string
phones:
type: array
items:
type: object
properties:
value:
type: string
label:
type: string
emails:
type: array
items:
type: object
properties:
value:
type: string
label:
type: string
tags:
type: array
items:
type: string
IntegrationLink:
type: object
properties:
id:
type: string
externalId:
type: string
system:
type: string
Tag:
type: object
properties:
id:
type: string
name:
type: string
color:
type: string
Conversation:
type: object
properties:
id:
type: string
title:
type: string
createdAt:
type: string
format: date-time
lastMessageAt:
type: string
format: date-time
tags:
type: array
items:
type: string
ConversationItem:
type: object
properties:
id:
type: string
conversationId:
type: string
type:
type: string
description: Item type, e.g. message, call, fax, or secure conversation event.
body:
type: string
createdAt:
type: string
format: date-time
MessageCreate:
type: object
properties:
body:
type: string
mediaIds:
type: array
items:
type: string
Endpoint:
type: object
properties:
id:
type: string
displayName:
type: string
type:
type: string
value:
type: string
WebhookEndpointCreate:
type: object
required:
- name
- url
properties:
name:
type: string
url:
type: string
format: uri
events:
type: array
items:
type: string
WebhookEndpoint:
type: object
properties:
id:
type: string
name:
type: string
url:
type: string
format: uri
secret:
type: string
description: Signing secret, returned only on creation.
paused:
type: boolean
events:
type: array
items:
type: string
WebhookEvent:
type: object
properties:
id:
type: string
type:
type: string
description: e.g. contact.created, conversation.updated, conversationItem.created.
createdAt:
type: string
format: date-time
deliveryStatus:
type: string