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