Spruce Health Contacts API

openapi: 3.0.0
info:
  title: Spruce Health API — Contacts
  version: 1.0.0
  description: The Contacts 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: Contacts
paths:
  /contacts:
    get:
      description: '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.

        '
      operationId: ListContacts
      parameters:
      - description: How many contacts to return at one time
        in: query
        name: pageSize
        required: false
        schema:
          format: int32
          maximum: 500
          minimum: 1
          type: integer
      - in: query
        name: paginationToken
        required: false
        schema:
          $ref: '#/components/schemas/paginationToken'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  contacts:
                    items:
                      $ref: '#/components/schemas/contact'
                    type: array
                  hasMore:
                    $ref: '#/components/schemas/hasMore'
                  paginationToken:
                    $ref: '#/components/schemas/paginationToken'
                  totalCount:
                    $ref: '#/components/schemas/totalCount'
                required:
                - totalCount
                - contacts
                - hasMore
                type: object
          description: A paged array of contacts
          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
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: unexpected error
      summary: List contacts
      tags:
      - Contacts
    post:
      description: '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`).

        '
      operationId: CreateContact
      parameters:
      - $ref: '#/components/parameters/s-idempotency-key'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createContact'
              description: Contact json object. At least one name or piece of contact information is required
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact'
          description: created
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: duplicate request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: unexpected error
      summary: Create a contact
      tags:
      - Contacts
  /contacts/{contactId}:
    delete:
      description: 'This operation deletes a specific contact by id.


        See the `canDelete` field on a given contact to determine if deletion is allowed.

        '
      operationId: DeleteContact
      parameters:
      - description: The id of the contact to delete
        in: path
        name: contactId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok response
          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: Delete a contact
      tags:
      - Contacts
    get:
      description: This operation retrieves a specific contact by id.
      operationId: Contact
      parameters:
      - description: The id of the contact to retrieve
        in: path
        name: contactId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact'
          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 contact by Spruce Contact ID
      tags:
      - Contacts
    patch:
      description: 'This operation updates a specific contact by id.


        Fields provided in the input object will be updated, omitted fields *(null)* will be unchanged.

        '
      operationId: UpdateContact
      parameters:
      - $ref: '#/components/parameters/s-idempotency-key'
      - description: The id of the contact to update
        in: path
        name: contactId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateContact'
              description: Contact json object. Omitted fields are not updated.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact'
          description: ok response
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: duplicate request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: unexpected error
      summary: Update a contact
      tags:
      - Contacts
  /contacts/{contactId}/conversations:
    get:
      description: This operation retrieves the conversations associated with a contact
      operationId: ContactConversations
      parameters:
      - description: The id of the contact to fetch conversations for
        in: path
        name: contactId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  conversations:
                    items:
                      $ref: '#/components/schemas/conversation'
                    type: array
                required:
                - conversations
                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: List the conversations associated with a contact
      tags:
      - Contacts
  /contacts/{contactId}/integrationlinks:
    delete:
      description: This operation deletes a specific integration link associated with a contact.
      operationId: DeleteContactIntegrationLink
      parameters:
      - description: The id of the contact to delete the integration link for.
        in: path
        name: contactId
        required: true
        schema:
          type: string
      - description: The identifier of the integration type the existing integration link is for.
        in: query
        name: type
        required: false
        schema:
          $ref: '#/components/schemas/contact_integrationLinkType'
      - description: The id of the contact in the external integrated system.
        in: query
        name: externalId
        required: false
        schema:
          $ref: '#/components/schemas/contact_externalId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contact_deleteContactIntegrationLink'
        required: false
      responses:
        '200':
          description: ok response
          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: Delete an integration link
      tags:
      - Contacts
    get:
      description: This operation retrieves the integration links associated with a contact
      operationId: ContactIntegrationLinks
      parameters:
      - description: The unique identifier of the contact
        in: path
        name: contactId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  integrationLinks:
                    $ref: '#/components/schemas/contact_integrationLinks'
                required:
                - integrationLinks
                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: List the integration links associated with a contact
      tags:
      - Contacts
    post:
      description: This operation creates a link between a contact and an external system with which the
        Spruce account is integrated.
      operationId: CreateContactIntegrationLink
      parameters:
      - $ref: '#/components/parameters/s-idempotency-key'
      - description: The id of the contact for which the integration link should be created.
        in: path
        name: contactId
        required: true
        schema:
          type: string
      - description: The integration type of the existing integration link.
        in: query
        name: type
        required: false
        schema:
          $ref: '#/components/schemas/contact_integrationLinkType'
      - description: The id of the contact in the external integrated system.
        in: query
        name: externalId
        required: false
        schema:
          $ref: '#/components/schemas/contact_externalId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contact_createContactIntegrationLink'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  integrationLinks:
                    $ref: '#/components/schemas/contact_integrationLinks'
                required:
                - integrationLinks
                type: object
          description: created
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: duplicate request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: unexpected error
      summary: Create an integration link
      tags:
      - Contacts
  /contacts/{contactId}/invite:
    post:
      description: '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.

        '
      operationId: SendInvite
      parameters:
      - description: The id of the contact to invite.
        in: path
        name: contactId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sendInvite'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  contact:
                    $ref: '#/components/schemas/contact'
                  conversation:
                    $ref: '#/components/schemas/conversation'
                required:
                - contact
                - conversation
                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: Invite patient to Spruce
      tags:
      - Contacts
  /contacts/search:
    post:
      description: '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.

        '
      operationId: SearchContacts
      parameters:
      - description: How many contacts to return at one time
        in: query
        name: pageSize
        required: false
        schema:
          format: int32
          maximum: 500
          minimum: 1
          type: integer
      - in: query
        name: paginationToken
        required: false
        schema:
          $ref: '#/components/schemas/paginationToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contactSearch'
              description: Contact Search json object.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  contacts:
                    items:
                      $ref: '#/components/schemas/contact'
                    type: array
                  hasMore:
                    $ref: '#/components/schemas/hasMore'
                  paginationToken:
                    $ref: '#/components/schemas/paginationToken'
                  totalCount:
                    $ref: '#/components/schemas/totalCount'
                  totalCountRelation:
                    $ref: '#/components/schemas/searchTotalCountRelation'
                required:
                - totalCount
                - totalCountRelation
                - contacts
                - hasMore
                type: object
          description: A paged array of contacts
          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
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: unexpected error
      summary: Search contacts
      tags:
      - Contacts
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
  parameters:
    s-idempotency-key:
      description: A unique value generated by the client used to recognize subsequent retries of the
        same request. Idempotency keys can be up to 255 characters long.
      example: S7uiKYMMRzAcuG8S
      in: header
      name: s-idempotency-key
      required: false
      schema:
        type: string
  schemas:
    contact:
      properties:
        apiURL:
          description: An absolute URL for fetching this contact from the API
          example: https://api.sprucehealth.com/contact/entity_0E5QDGJC03000
          format: url
          type: string
        appURL:
          description: An absolute URL to view the contact in the Spruce app
          example: https://app.sprucehealth.com/org/entity_0D4QABCC06000/contact/entity_0E5QDGJC03000
          format: url
          type: string
        canDelete:
          description: Whether the contact may be deleted.
          example: true
          type: boolean
        canEdit:
          description: Whether the contact may be edited.
          example: true
          type: boolean
        category:
          $ref: '#/components/schemas/contact_category'
        companyName:
          $ref: '#/components/schemas/contact_companyName'
        created:
          description: The date this contact was added to Spruce
          example: '2021-01-30T08:30:00Z'
          format: date-time
          type: string
        customContactFields:
          $ref: '#/components/schemas/contact_customContactFields'
        dateOfBirth:
          $ref: '#/components/schemas/contact_dateOfBirth'
        displayName:
          $ref: '#/components/schemas/contact_displayName'
        emailAddresses:
          $ref: '#/components/schemas/contact_emailAddresses'
        familyName:
          $ref: '#/components/schemas/contact_familyName'
        faxNumbers:
          $ref: '#/components/schemas/contact_faxNumbers'
        gender:
          $ref: '#/components/schemas/contact_gender'
        genderDetail:
          $ref: '#/components/schemas/contact_genderDetail'
        givenName:
          $ref: '#/components/schemas/contact_givenName'
        hasAccount:
          description: Whether the contact has created a Spruce account for secure messaging, video calling,
            etc.
          example: true
          type: boolean
        hasPendingInvite:
          description: Whether the contact has a pending Spruce account invitation
          example: true
          type: boolean
        id:
          $ref: '#/components/schemas/contact_id'
        integrationLinks:
          $ref: '#/components/schemas/contact_integrationLinks'
        internalMemberIds:
          $ref: '#/components/schemas/contact_internalMemberIds'
        middleName:
          $ref: '#/components/schemas/contact_middleName'
        object:
          $ref: '#/components/schemas/objectType'
        organizationContactFields:
          $ref: '#/components/schemas/contact_organizationContactFields'
        phoneNumbers:
          $ref: '#/components/schemas/contact_phoneNumbers'
        pronouns:
          $ref: '#/components/schemas/contact_pronouns'
        tags:
          $ref: '#/components/schemas/contact_tags'
      required:
      - id
      - displayName
      - tags
      - gender
      - category
      - created
      - phoneNumbers
      - emailAddresses
      - customFields
      - appURL
      - apiURL
      - hasAccount
      - hasPendingInvite
      - customContactFields
      - organizationContactFields
      - canDelete
      - canEdit
      - integrationLinks
      - object
      - internalMemberIds
      type: object
    contactSearch:
      properties:
        freeText:
          type: string
        structured:
          $ref: '#/components/schemas/contact_searchStructuredFilter'
      type: object
    contact_category:
      enum:
      - patient
      - professional
      - clinic
      - unknown
      example: patient
      type: string
    contact_categoryInput:
      enum:
      - patient
      - professional
      example: patient
      type: string
    contact_companyName:
      description: The contact's company. This field can also be used to specify the name of a non-patient
        contact, such as another healthcare facility.
      example: Walgreens
      type: string
    contact_createContactIntegrationLink:
      properties:
        externalId:
          $ref: '#/components/schemas/contact_externalId'
          description: The id of the contact in the external integrated system.
        type:
          $ref: '#/components/schemas/contact_integrationLinkType'
          description: The integration type of the integration link.
        url:
          description: The URL to the contact in the external system (only for custom integration links).
          example: https://example.com/contacts/123
          type: string
      type: object
    contact_customContactField:
      properties:
        id:
          $ref: '#/components/schemas/contact_customContactFieldId'
        name:
          $ref: '#/components/schemas/contact_customFieldName'
        value:
          $ref: '#/components/schemas/contact_customFieldValue'
      required:
      - id
      - name
      - value
      type: object
    contact_customContactFieldId:
      description: Spruce's contact contact custom field ID
      example: entityCustomField_0E5QDGJC03000
      type: string
    contact_customContactFields:
      description: Fields on a contact that are custom
      items:
        $ref: '#/components/schemas/contact_customContactField'
      type: array
    contact_customFieldName:
      description: A name for the field
      example: Preferred Pharmacy
      type: string
    contact_customFieldValue:
      description: The value of the field
      example: CVS
      type: string
    contact_dateOfBirth:
      description: The contact's date of birth in the format YYYY-MM-DD.
      example: '2000-01-30'
      format: date
      type: string
    contact_deleteContactIntegrationLink:
      properties:
        externalId:
          $ref: '#/components/schemas/contact_externalId'
          description: The id of the contact in the external integrated system.
        type:
          $ref: '#/components/schemas/contact_integrationLinkType'
          description: The identifier of the integration type the existing integration link is for.
      type: object
    contact_displayName:
      description: The contact's full name for easy display to a user. This is determined by combining
        the givenName, middleName, and familyName, or if those are all empty, falling back to companyName,
        phone number or email address.
      example: Joe William Smith
      type: string
    contact_emailAddressInputs:
      items:
        $ref: '#/components/schemas/emailAddressInput'
      type: array
    contact_emailAddresses:
      items:
        $ref: '#/components/schemas/emailAddress'
      type: array
    contact_externalId:
      description: The id of a contact in an external system.
      example: elation_140797386655555
      type: string
    contact_familyName:
      description: The contact's family name (typically last name in US)
      example: Smith
      type: string
    contact_faxNumberInputs:
      items:
        $ref: '#/components/schemas/faxNumberInput'
      type: array
    contact_faxNumbers:
      items:
        $ref: '#/components/schemas/faxNumber'
      type: array
    contact_gender:
      enum:
      - unknown
      - male
      - female
      - other
      example: unknown
      type: string
    contact_genderDetail:
      description: Optional free-text details for gender
      example: Non-binary
      type: string
    contact_givenName:
      description: The contact's given name (typically first name in US)
      example: Joe
      type: string
    contact_id:
      description: Spruce's contact ID
      example: entity_0E5QDGJC03000
      type: string
    contact_integrationLink:
      properties:
        contactId:
          $ref: '#/components/schemas/contact_id'
        externalId:
          $ref: '#/components/schemas/contact_externalId'
        type:
          $ref: '#/components/schemas/contact_integrationLinkType'
        url:
          description: The url of a contact in an integrated external system.
          type: string
      required:
      - type
      - externalId
      - contactId
      type: object
    contact_integrationLinkType:
      enum:
      - elation
      - hint
      - athena
      - custom
      example: elation
      type: string
    contact_integrationLinks:
      description: Links between a contact and an integrated external system.
      items:
        $ref: '#/components/schemas/contact_integrationLink'
      type: array
    contact_internalMemberIds:
      description: The ids of the teammates, teams and/or your organization that are members of the contact.
        Contact Membership must be enabled for the organization for this field to be interacted with.
      items:
        type: string
      type: array
    contact_middleName:
      description: The contact's middle name
      example: William
      type: string
    contact_organizationContactField:
      properties:
        id:
          $ref: '#/components/schemas/contact_organizationContactFieldId'
        name:
          $ref: '#/components/schemas/contact_customFieldName'
        value:
          $ref: '#/components/schemas/contact_customFieldValue'
      required:
      - id
      - name
      - value
      type: object
    contact_organizationContactFieldId:
      description: Spruce's contact organization contact custom field ID
      example: managedCustomField_0E5QDGJC03000
      type: string
    contact_organizationContactFieldInput:
      properties:
        id:
          $ref: '#/components/schemas/contact_organizationContactFieldId'
        value:
          $ref: '#/components/schemas/contact_customFieldValue'
      required:
      - id
      - value
      type: object
    contact_organizationContactFieldInputs:
      description: Fields on a contact that are custom to your organization
      items:
        $ref: '#/components/schemas/contact_organizationContactFieldInput'
      type: array
    contact_organizationContactFields:
      description: Fields on a contact

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spruce-health/refs/heads/main/openapi/spruce-health-contacts-openapi.yml