---
title: "List contacts"
method: GET
path: "/contacts"
tags: ["Contacts"]
---

# List contacts

`GET /contacts`

## Request

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

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.

## Query parameters

- `pageSize` integer
- `paginationToken` string: Token given in a previous response to allow requesting the next page

## Response `200`

A paged array of contacts

- object
  - `contacts` 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
  - `hasMore` boolean, required
  - `paginationToken` string: Token given in a previous response to allow requesting the next page
  - `totalCount` integer, required

## Other responses

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