---
title: "Create a contact"
method: POST
path: "/contacts"
tags: ["Contacts"]
---

# Create a contact

`POST /contacts`

## Request

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

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`).

## Headers

- `s-idempotency-key` string

## Request body

- CreateContact
  - `category` 'patient' | 'professional'
  - `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.
  - `dateOfBirth` string, date: The contact's date of birth in the format YYYY-MM-DD.
  - `emailAddresses` EmailAddressInput[]
    - `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` FaxNumberInput[]
    - `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'
  - `genderDetail` string: Optional free-text details for gender
  - `givenName` string: The contact's given name (typically first name in US)
  - `internalMemberIds` string[]: 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
  - `organizationContactFields` ContactOrganizationContactFieldInput[]: Fields on a contact that are custom to your organization
    - `id` string, required: Spruce's contact organization contact custom field ID
    - `value` string, required: The value of the field
  - `phoneNumbers` PhoneNumberInput[]
    - `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
  - `tagIds` ContactTagId[]: An array of Spruce contact tag ids

## Response `201`

created

- Contact
  - `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

## Other responses

- `400`: bad request
- `422`: duplicate request
- `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)
