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

# Search contacts

`POST /contacts/search`

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