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

# List contacts

`GET /contacts`

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.net/sprucehealth/apis/spruce-health-api.md) · [All operations](https://skmtc.net/sprucehealth/apis/spruce-health-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sprucehealth/spruce-health-api/revisions/988e298cd9fd/schema)