---
title: "Invite patient to Spruce"
method: POST
path: "/contacts/{contactId}/invite"
tags: ["Contacts"]
---

# Invite patient to Spruce

`POST /contacts/{contactId}/invite`

## Request

- Base URL: `https://api.sprucehealth.com/v1`
- URL: `https://api.sprucehealth.com/v1/contacts/{contactId}/invite`
- Auth: HTTP bearer

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.

## Path parameters

- `contactId` string, required

## Request body

- SendInvite
  - `customMessage` string: The message to send to the invitee.
  - `destinationId` string, required: The id of the phone number or email to send the invite to.
  - `internalEndpointId` string, required: Organization's internal secure endpoint that will be used to send the invite.

## Response `200`

Expected response to a valid request

- object
  - `contact` Contact, required
    - `apiURL` string, url, required: An absolute URL for fetching this contact from the API
    - `appURL` string, url, required: An absolute URL to view the contact in the Spruce app
    - `canDelete` boolean, required: Whether the contact may be deleted.
    - `canEdit` boolean, required: Whether the contact may be edited.
    - `category` 'patient' | 'professional' | 'clinic' | 'unknown', required
    - `companyName` string: The contact's company. This field can also be used to specify the name of a non-patient contact, such as another healthcare facility.
    - `created` string, date-time, required: The date this contact was added to Spruce
    - `customContactFields` ContactCustomContactField[], required: Fields on a contact that are custom
      - `id` string, required: Spruce's contact contact custom field ID
      - `name` string, required: A name for the field
      - `value` string, required: The value of the field
    - `dateOfBirth` string, date: The contact's date of birth in the format YYYY-MM-DD.
    - `displayName` string, required: 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.
    - `emailAddresses` EmailAddress[], required
      - `id` string, string, required: Spruce's phone number ID
      - `label` string: A label for the email address such as 'Work', 'Home', etc.
      - `value` string, email, required
    - `familyName` string: The contact's family name (typically last name in US)
    - `faxNumbers` FaxNumber[]
      - `displayValue` string, required: The contact phone number in an easily readable format.
      - `id` string, string, required: Spruce's phone number ID
      - `label` string: A label for the phone number such as 'Work', 'Home', 'Cell', etc.
      - `value` string, string, required: The contact phone number. An acceptable phone number is in the format 2065551234, +12065551234, (206) 555-1234, or 206-555-1234.
    - `gender` 'unknown' | 'male' | 'female' | 'other', required
    - `genderDetail` string: Optional free-text details for gender
    - `givenName` string: The contact's given name (typically first name in US)
    - `hasAccount` boolean, required: Whether the contact has created a Spruce account for secure messaging, video calling, etc.
    - `hasPendingInvite` boolean, required: Whether the contact has a pending Spruce account invitation
    - `id` string, required: Spruce's contact ID
    - `integrationLinks` ContactIntegrationLink[], required: Links between a contact and an integrated external system.
      - `contactId` string, required: Spruce's contact ID
      - `externalId` string, required: The id of a contact in an external system.
      - `type` 'elation' | 'hint' | 'athena' | 'custom', required
      - `url` string: The url of a contact in an integrated external system.
    - `internalMemberIds` string[], required: 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.
    - `middleName` string: The contact's middle name
    - `object` string, required: String representing the object's type
    - `organizationContactFields` ContactOrganizationContactField[], required: Fields on a contact that are custom
      - `id` string, required: Spruce's contact organization contact custom field ID
      - `name` string, required: A name for the field
      - `value` string, required: The value of the field
    - `phoneNumbers` PhoneNumber[], required
      - `displayValue` string, required: The contact phone number in an easily readable format.
      - `id` string, string, required: Spruce's phone number ID
      - `label` string: A label for the phone number such as 'Work', 'Home', 'Cell', etc.
      - `value` string, string, required: The contact phone number. An acceptable phone number is in the format 2065551234, +12065551234, (206) 555-1234, or 206-555-1234.
    - `pronouns` string: The contact's pronouns
    - `tags` ContactTag[], required
      - `id` string, required: Spruce's contact tag ID
      - `object` string, required: String representing the object's type
      - `value` string, required: The text value of a contact tag
  - `conversation` Conversation, required
    - `apiURL` string, url, required: An absolute URL for fetching this conversation from the API
    - `appURL` string, url, required: An absolute URL to view the conversation in the Spruce app
    - `archived` boolean, required: Whether or not the conversation is archived
    - `assignedToMemberId` string: The id of the teammate the conversation is assigned to
    - `associatedContactIds` string[]: 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.
    - `createdAt` string, date-time, required: The date the conversation was created
    - `externalParticipants` object[]: The external participants in the conversation.
      - `contact` string: The id of the contact associated with the participant. This will be omitted if the participant is not a saved contact.
      - `displayName` string, required: The display name of the participant
      - `endpoint` Endpoint
        - `channel` 'email' | 'phone' | 'fax' | 'secure', required: 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.
        - `displayValue` string, required: 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.
        - `id` string, required: 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.
        - `isInternal` boolean, required: Internal endpoints are endpoints that are owned by your organization, such as your organization's Spruce Phone Numbers or Spruce Links.
        - `label` string: The optional label of the endpoint
        - `object` string, required: String representing the object's type
        - `rawValue` string, required: 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.
    - `id` string, required: Spruce's conversation ID
    - `internalEndpoint` Endpoint
      - `channel` 'email' | 'phone' | 'fax' | 'secure', required: 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.
      - `displayValue` string, required: 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.
      - `id` string, required: 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.
      - `isInternal` boolean, required: Internal endpoints are endpoints that are owned by your organization, such as your organization's Spruce Phone Numbers or Spruce Links.
      - `label` string: The optional label of the endpoint
      - `object` string, required: String representing the object's type
      - `rawValue` string, required: 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.
    - `internalMemberIds` string[]: The ids of the teammates, teams and/or your organization that are members of the conversation.
    - `isReadOnly` boolean, required: If the conversation is read-only, messages cannot be sent to it.
    - `lastMessageAt` string, date-time: The time of the conversations latest message
    - `object` string, required: String representing the object's type
    - `subtitle` string: The subtitle of the conversation
    - `tags` ConversationTag[], required
      - `id` string, required: Spruce's conversation tag ID
      - `object` string, required: String representing the object's type
      - `value` string, required: The text value of a conversation tag
    - `title` string, required: The title of the conversation
    - `type` 'email' | 'phone' | 'secure' | 'fax' | 'team' | 'note' | 'other', required: 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.

## Other responses

- `400`: bad request
- `404`: not found
- `500`: unexpected error

---

[API](https://skmtc.dev/sprucehealth/apis/spruce-health-api.md) - [All operations](https://skmtc.dev/sprucehealth/apis/spruce-health-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sprucehealth/apis/spruce-health-api/revisions/06e7a37de1ce?raw)
