# Spruce Health Documentation > Documentation for Spruce Health ## Guides - [Spruce API Overview](https://developer.sprucehealth.com/docs/overview.md): Getting started with the Spruce API - [Spruce Integration Guide](https://developer.sprucehealth.com/docs/integration-guide.md): Interacting with the Spruce Public API for integration with external systems - [Retrieving a Call Recording from a ConversationItem](https://developer.sprucehealth.com/docs/retrieving-a-call-recording-from-a-conversationitem.md) - [Spruce CSV Data Export](https://developer.sprucehealth.com/docs/data-exports.md): Interacting with the Spruce Data Export that can be delivered to an SFTP endpoint - [Spruce Webhooks Overview](https://developer.sprucehealth.com/docs/webhooks-overview.md): Getting started with Spruce Webhooks ## API Reference - [List contacts](https://developer.sprucehealth.com/reference/listcontacts.md): This operation lists all contacts available to a given organization. The `hasMore` field can be used to determine if there are remaining results to list. The `paginationToken` field can be provided on subsequents calls to retrieve the next page of results. - [Create a contact](https://developer.sprucehealth.com/reference/createcontact.md): This operation creates a contact within an organization. Creating a new contact requires at least of the following fields to be populated (`givenName`, `familyName`, `phoneNumbers`, `faxNumbers`, `emailAddresses`). - [Delete a contact](https://developer.sprucehealth.com/reference/deletecontact.md): This operation deletes a specific contact by id. See the `canDelete` field on a given contact to determine if deletion is allowed. - [Get a contact by Spruce Contact ID](https://developer.sprucehealth.com/reference/contact.md): This operation retrieves a specific contact by id. - [Update a contact](https://developer.sprucehealth.com/reference/updatecontact.md): This operation updates a specific contact by id. Fields provided in the input object will be updated, omitted fields *(null)* will be unchanged. - [List the conversations associated with a contact](https://developer.sprucehealth.com/reference/contactconversations.md): This operation retrieves the conversations associated with a contact - [Delete an integration link](https://developer.sprucehealth.com/reference/deletecontactintegrationlink.md): This operation deletes a specific integration link associated with a contact. - [List the integration links associated with a contact](https://developer.sprucehealth.com/reference/contactintegrationlinks.md): This operation retrieves the integration links associated with a contact - [Create an integration link](https://developer.sprucehealth.com/reference/createcontactintegrationlink.md): This operation creates a link between a contact and an external system with which the Spruce account is integrated. - [Invite patient to Spruce](https://developer.sprucehealth.com/reference/sendinvite.md): This operation sends an invite to a patient contact: - If the contact is invited for the first time, a new secure conversation will be created, - If the contact is already invited, the invite will be re-sent to the same secure conversation, - If the contact is already on Spruce, an error will be returned. - [Search contacts](https://developer.sprucehealth.com/reference/searchcontacts.md): This operation searches all contacts available to a given organization and returns a resulting set of results. The `hasMore` field can be used to determine if there are remaining results to list. The `paginationToken` field can be provided on subsequents calls to retrieve the next page of results. ## Sort Order Results are sorted by **entity ID in ascending order** when doing a structured search and by **relevance** for free text search. Why is this a `POST`? `GET` requests with a body are not supported by all HTTP libraries. To support complex nested search filters and other tooling, the `POST` body is leveraged. - [List all organization contact fields available to the organization](https://developer.sprucehealth.com/reference/contactfields.md): This operation lists all organization contact fields. These fields appear on all contacts in the interface. - [Create an organization contact field](https://developer.sprucehealth.com/reference/createcontactfield.md): This operation creates an organization contact field for the given organization. This field will appear on all contacts in the interface. Requesting creation of an already existing field will result in a `201` response and the response will contain the existing field. - [List all contact tags available to the organization](https://developer.sprucehealth.com/reference/contacttags.md): This operation lists all contact tags available to a given organization. The `hasMore` field can be used to determine if there are remaining results to list. The `paginationToken` field can be provided on subsequents calls to retrieve the next page of results. - [Create a contact tag](https://developer.sprucehealth.com/reference/createcontacttag.md): This operation creates a contact tag for the given organization. This tag can then be applied to contacts in subsequent operations. Requesting creation of an already existing tag will result in a `201` response and the response will contain the existing tag. - [Delete a conversation item](https://developer.sprucehealth.com/reference/deleteconversationitem.md): 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. - [Get a conversation item for a given id](https://developer.sprucehealth.com/reference/conversationitem.md): This operation fetches a specific conversation item for the provided id. - [List and filter all conversations available to the organization](https://developer.sprucehealth.com/reference/listconversations.md): This operation lists all conversations available to the organization. This is an eventually consistent view and may take a short time before new conversations appear in results. To iterate through all conversations in the organization, list the first page of conversations (without specifying `paginationToken` or `startFrom`). If `hasMore=true`, the provide the `paginationToken` to the API to list subsequent pages of conversations until `hasMore=false`. ## Detecting conversations with new messages Note that the conversations are ordered by created date by default. You can also order them by the time of last activity in the conversation by specifying `orderBy=last_message`. This is particularly helpful when trying to determine conversations with new activity in them. In this particular case, you can query the list of conversations with `orderBy=last_message` and capture the `lastMessageAt` time for the last conversation in the list. On the next query, you can then `startFrom=` and `orderBy=last_message` to return any conversations with new activity since your last query. While you can determine the conversations with new activity, it is also important to know if the latest messages in each conversation were from your teammates or from an external contact (like a patient). To determine this, you can use the [listing of conversation items API](/reference/conversationitems) to query for the latest items since a particular time with the `startFrom` field. If any message in the list returned has `direction=inbound` then it indicates a message received since the last query for message items. - [Create a new conversation](https://developer.sprucehealth.com/reference/createconversation.md): 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. - [Get a conversation for a given id](https://developer.sprucehealth.com/reference/conversation.md): This operation fetches a specific conversation for the provided id. - [Update a conversation](https://developer.sprucehealth.com/reference/updateconversation.md): This operation updates a specific conversation by id. Fields provided in the input object will be updated, omitted fields *(null)* will be unchanged. - [List and filter all conversation items in a conversation](https://developer.sprucehealth.com/reference/conversationitems.md): This operation lists all conversations items available in a conversation. This is an eventually consistent view and may take a short time before new conversation items appear in results. - [Post a message to a specific conversation](https://developer.sprucehealth.com/reference/postconversationmessage.md): This operation posts a message in a conversation as specified by the conversationId. You can retrieve the conversationId by [listing the conversations for a contact](/reference/contactconversations) or by [listing all conversations in the organization](/reference/conversations). You can also [send messages to a phone number, an email address, fax number, or securely message a contact](/reference/postmessagefromendpoint) using a [specific internal endpoint](/reference/internalendpoints). The `requestID` returned by this API may be used to match against the `requestID` field of the `conversationItem.created` webhook event to identify when the message is posted. ## Posting an internal message containing a page for an organization member To post a message with a page for an organization member, you'll first need to know the member's id. You can find the id of the organization member by [listing all organization members](/reference/organizationmembers). Once the member id is known, you can post a message to the conversation with `internal=true` and an element of `type=page` and `value=` in the list of `body` elements being posted. The `body` parameter is a list of message elements. Each element can be of type `text` or `page`. The request can contain combinations of `text` and `page` elements to create internal messages with useful content while also notifying a set of members. ## Posting to a Team or Note conversation You can also use this API to post messages into a Team or Note conversations. For Note conversations, you will have to specify `internal=true` since only internal messages can be posted in Note conversations. - [List any messages scheduled in a conversation](https://developer.sprucehealth.com/reference/listconversationscheduledmessages.md): This operation lists the messages that are scheduled in a conversation. - [Schedule a message to be sent in a conversation](https://developer.sprucehealth.com/reference/scheduleconversationmessage.md): This operation creates a scheduled message to be sent in a conversation at the designated time. If no author is specified, the message will be sent as the organization. - [List any messages scheduled for the organization](https://developer.sprucehealth.com/reference/listscheduledmessages.md): This operation lists the messages that are scheduled to be sent from the organization. - [Delete a scheduled message](https://developer.sprucehealth.com/reference/deletescheduledmessage.md): This operation deletes a scheduled message specified by id. - [List all conversation tags available to the organization](https://developer.sprucehealth.com/reference/conversationtags.md): This operation lists all conversation tags available to a given organization. The `hasMore` field can be used to determine if there are remaining results to list. The `paginationToken` field can be provided on subsequents calls to retrieve the next page of results. - [Create a conversation tag](https://developer.sprucehealth.com/reference/createconversationtag.md): This operation creates a conversation tag for the given organization. This tag can then be applied to conversations in subsequent operations. Requesting creation of an already existing tag will result in a `201` response and the response will contain the existing tag. - [List all internal endpoints](https://developer.sprucehealth.com/reference/internalendpoints.md): This operation lists all internal endpoints which organizations can use to communicate with. This includes all Spruce phone numbers, fax numbers, email addresses and Spruce Links. You can then [use an internal endpoint to send a message](/reference/postmessagefromendpoint). - [Send a message from an internal endpoint](https://developer.sprucehealth.com/reference/postmessagefromendpoint.md): This operation sends a message to an external endpoint (phone number or email address) or a contact (secure messaging). Only one of secureEndpoint or smsOrEmailEndpoint should be specified. You will need to also specify the appropriate internal endpoint from the [list of available internal endpoints for an organization](/reference/internalendpoints). The RequestID returned by this API may be used to match against the `RequestID` field of the `conversationItem.created` webhook event to identify when the message is posted. ## Send a secure message * Get the appropriate Spruce phone number from the [list of internal endpoints for an organization](/reference/internalendpoints) (of channel type `secure`) * Specify the internal endpoint's `endpoint.Id` in the `internalEndpointId` path parameter * Get the Id of the appropriate contact to send the secure message to. You can [list all contacts in the organization](/reference/listcontacts) or [search for the appropriate contact](/reference/searchcontacts) to determine the contact Id if you do not have it already. * Populate the `destination.secureEndpoint` object with the `contactId`, the appropriate `deliveryMethod` and `subject` for the conversation. The `deliveryMethod` can be one of the following: * (Default) `any_available_secure_conversation`: The system will first try to deliver messages using conversations from the specified internal endpoint. Then it will try to deliver to any existing secure conversation with the recipient. Then, if no conversation exists, a new secure conversation will be created. * `only_conversations_matching_internal_endpoint`: The system will deliver messages in conversations from the specified internal endpoint. If such a conversation doesn't yet exist, a new one will be created. * `new_conversation`: This option will create a new conversation, separate from any existing conversation. ## Send an SMS * Get the appropriate Spruce phone number from the [list of internal endpoints for an organization](/reference/internalendpoints) (of channel type `phone`) * Specify the internal endpoint's `endpoint.Id` in the `internalEndpointId` path parameter * Specify the phone number to send the the message to in the `destination.smsOrEmailEndpoint` body parameter ## Send an email * Get the appropriate Spruce phone number from the [list of internal endpoints for an organization](/reference/internalendpoints) (of channel type `email`) * Specify the internal endpoint's `endpoint.Id` in the `internalEndpointId` path parameter * Specify the email address to send the the message to in the `destination.smsOrEmailEndpoint` body parameter ## Send a fax * Get the appropriate Spruce fax number from the [list of internal endpoints for an organization](/reference/internalendpoints) (of channel type `fax`) * Specify the internal endpoint's `endpoint.Id` in the `internalEndpointId` path parameter * Specify the fax number to send the the message to in the `destination.faxEndpoint` body parameter * Note: Each outbound fax message sent from an internal endpoint will result in a new fax conversation being created - [Create an outbound proxy call](https://developer.sprucehealth.com/reference/postcreateproxycall.md): This operation creates an outbound proxy call from an internal endpoint to an external phone number and returns the proxy number for use. To learn more about proxy calling on Spruce, [visit this link](https://help.sprucehealth.com/hc/en-us/articles/40126738273435-Web-Desktop-Phone-Calls#h_01K322JXWY7T60ESF4DFTBKZP0). - [Upload media](https://developer.sprucehealth.com/reference/uploadmedia.md): This operation uploads media such a images, videos, and files to Spruce for use in messaging. Uploading a file will return a media ID that can be used to reference the file in other operations. Callers of this API should record the resulting media ID for future use. A media ID can be used in the `attachmentID` field of the [conversation message post attachment](/reference/postmessagefromendpoint). Media IDs can be used multiple times. The `Content-Type` and `Content-Disposition` headers on the multipart `media` field can use used to provide additional metadata about the media. This metadata can impact how the media is displayed and downloaded from the application. **Example Headers** * `Content-Disposition: form-data; name="media"; filename="image.png"` * `Content-Type: image/png` - [List information about the organization](https://developer.sprucehealth.com/reference/organization-1.md): This returns your organization's information. Most importantly, it returns your organization's `id` which will often be used as the owner or a member of other objects. - [List all members of the organization](https://developer.sprucehealth.com/reference/organizationmembers.md): This returns a list of all members of the organization. This includes all teammates and all teams, as well as a reference to the organization itself. - [Get a member of the organization by id](https://developer.sprucehealth.com/reference/organizationmember.md): This operation retrieves a specific organization member (organization, team, or teammate), by id. - [List all phone lines of the organization](https://developer.sprucehealth.com/reference/phonelines.md): This returns a list of all phone lines of the organization. - [Get a phone line of the organization by id](https://developer.sprucehealth.com/reference/phoneline.md): This operation retrieves a specific phone line by id. - [List saved messages](https://developer.sprucehealth.com/reference/listsavedmessages.md): Lists all saved messages accessible to the organization. Returns both private and organization-wide saved messages with pagination support. - [List the members of a team](https://developer.sprucehealth.com/reference/teammembers.md): This operation lists the members of a team identified by id. - [Get a transcription by id](https://developer.sprucehealth.com/reference/transcription.md): This operation fetches the full transcription text and its summarization (if available) for the provided transcription id. The transcription id is available on the `transcriptionId` field of relevant objects. **Limitation:** Voicemail transcriptions created before November 2025 were stored in a legacy format that cannot be retrieved by this endpoint. Their ids may still appear on conversation items, but requests for them respond with a `404` and an explanatory message. - [List webhook destination endpoints](https://developer.sprucehealth.com/reference/listwebhookendpoints.md): This operation lists the endpoints that an organization has registered for webhooks. - [Create a webhook destination endpoint](https://developer.sprucehealth.com/reference/createwebhookendpoint.md): This operation creates a destination endpoint for webhooks events. - [Delete a webhook destination endpoint by id](https://developer.sprucehealth.com/reference/deletewebhookendpoint.md): This operation deleted a destination endpoint for webhook events by id. - [Get a webhook destination endpoint by id](https://developer.sprucehealth.com/reference/webhookendpoint.md): This operation retrieves a specific destination endpoint for webhooks events by id. - [List events for an endpoint](https://developer.sprucehealth.com/reference/listwebhookendpointevents.md): This operation retrieves information about events that have been attempted to be published to a webhook destination endpoint. Events are queryable for a period of 30 days after creation and are returned in sets of 20 at a time. Use the pagination token to retrieve more events. - [Pause or resume a webhook destination endpoint](https://developer.sprucehealth.com/reference/modifywebhookendpointpaused.md): This operation sets the 'paused' state of a webhook destination endpoint.