---
title: "Search contacts"
method: POST
path: "/contacts/search"
tags: ["Contacts"]
---

# Search contacts

`POST /contacts/search`

## Request

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

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.

## Query parameters

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

## Request body

- ContactSearch
  - `freeText` string
  - `structured` ContactSearchStructuredFilter
    - `ageFilter` ContactSearchAgeFilter[]
      - `ages` object[], required
        - `age` integer, required
        - `comparison` 'equal' | 'less_than' | 'less_than_or_equal_to' | 'greater_than' | 'greater_than_or_equal_to', required
      - `match` 'all' | 'any' | 'none', required
    - `categoryFilter` ContactSearchCategoryFilter[]
      - `categories` ContactCategory[], required
      - `match` 'all' | 'any' | 'none', required
    - `createdTimeFilter` ContactSearchCreatedTimeFilter[]
      - `createdTimes` object[], required
        - `comparison` 'equal' | 'less_than' | 'less_than_or_equal_to' | 'greater_than' | 'greater_than_or_equal_to', required
        - `time` string, date-time, required: The date this contact was added to Spruce
      - `match` 'all' | 'any' | 'none', required
    - `emailAddressFilter` ContactSearchEmailAddressFilter[]
      - `match` 'all' | 'any' | 'none', required
      - `values` EmailAddressValue[], required
    - `faxNumberFilter` ContactSearchFaxNumberFilter[]
      - `match` 'all' | 'any' | 'none', required
      - `values` PhoneNumberValue[], required
    - `genderFilter` ContactSearchGenderFilter[]
      - `genders` ContactGender[], required
      - `match` 'all' | 'any' | 'none', required
    - `integrationIDFilter` ContactSearchIntegrationIDFilter[]
      - `integrationIDs` object[], required
        - `id` string, required
        - `integrationLinkType` 'elation' | 'hint' | 'athena' | 'custom', required
      - `match` 'all' | 'any' | 'none', required
    - `inviteFilter` ContactSearchInviteFilter[]
      - `inviteStates` ContactSearchInviteStateFilter[], required
      - `match` 'all' | 'any' | 'none', required
    - `nameFilter` ContactSearchNameFilter[]
      - `match` 'all' | 'any' | 'none', required
      - `names` object[], required
        - `familyName` string
        - `givenName` string
    - `organizationContactFieldFilter` ContactSearchOrganizationContactFieldFilter[]
      - `match` 'all' | 'any' | 'none', required
      - `organizationContactFields` object[], required
        - `name` string, required
        - `value` string, required
    - `phoneNumberFilter` ContactSearchPhoneNumberFilter[]
      - `match` 'all' | 'any' | 'none', required
      - `values` PhoneNumberValue[], required
    - `tagFilter` ContactSearchTagFilter[]
      - `match` 'all' | 'any' | 'none', required
      - `tags` string[], required

## 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
  - `totalCountRelation` 'eq' | 'gte', required: The relation to use when comparing the total number of available search to the value specified in the results count field. A value of `gte` means that the count is a lower bound of the total results that match the query and a value of `eq` indicates that the count is accurate.

## 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)
