Sign in

v1

latestOpenAPI 3.0.02026-07-2447166133.5 KB
Contacts

Search contacts

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.

post/contacts/search

Query parameters

pageSizeinteger

How many contacts to return at one time

paginationTokenstring

Token given in a previous response to allow requesting the next page

Example:abcdefghijklmnop

Request body

freeTextstring

Example request

{
  "structured": {
    "ageFilter": [
      {
        "ages": [
          {
            "comparison": "equal"
          }
        ],
        "match": "all"
      }
    ],
    "categoryFilter": [
      {
        "categories": [
          "patient"
        ],
        "match": "all"
      }
    ],
    "createdTimeFilter": [
      {
        "createdTimes": [
          {
            "comparison": "equal",
            "time": "2021-01-30T08:30:00Z"
          }
        ],
        "match": "all"
      }
    ],
    "emailAddressFilter": [
      {
        "match": "all",
        "values": [
          "contact@example.com"
        ]
      }
    ],
    "faxNumberFilter": [
      {
        "match": "all"
      }
    ],
    "genderFilter": [
      {
        "genders": [
          "unknown"
        ],
        "match": "all"
      }
    ],
    "integrationIDFilter": [
      {
        "integrationIDs": [
          {
            "integrationLinkType": "elation"
          }
        ],
        "match": "all"
      }
    ],
    "inviteFilter": [
      {
        "inviteStates": [
          "has_account"
        ],
        "match": "all"
      }
    ],
    "nameFilter": [
      {
        "match": "all"
      }
    ],
    "organizationContactFieldFilter": [
      {
        "match": "all"
      }
    ],
    "phoneNumberFilter": [
      {
        "match": "all"
      }
    ],
    "tagFilter": [
      {
        "match": "all"
      }
    ]
  }
}

Response

A paged array of contacts

hasMoreboolean required
paginationTokenstring

Token given in a previous response to allow requesting the next page

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

Example response

{
  "contacts": [
    {
      "apiURL": "https://api.sprucehealth.com/contact/entity_0E5QDGJC03000",
      "appURL": "https://app.sprucehealth.com/org/entity_0D4QABCC06000/contact/entity_0E5QDGJC03000",
      "canDelete": true,
      "canEdit": true,
      "category": "patient",
      "companyName": "Walgreens",
      "created": "2021-01-30T08:30:00Z",
      "customContactFields": [
        {
          "id": "entityCustomField_0E5QDGJC03000",
          "name": "Preferred Pharmacy",
          "value": "CVS"
        }
      ],
      "dateOfBirth": "2000-01-30",
      "displayName": "Joe William Smith",
      "emailAddresses": [
        {
          "id": "entityContact_26RRC7PQ6JG00",
          "label": "Work",
          "value": "contact@example.com"
        }
      ],
      "familyName": "Smith",
      "faxNumbers": [
        {
          "displayValue": "(222) 555-0000",
          "id": "entityContact_26RRC7PQ6JG00",
          "label": "Work"
        }
      ],
      "gender": "unknown",
      "genderDetail": "Non-binary",
      "givenName": "Joe",
      "hasAccount": true,
      "hasPendingInvite": true,
      "id": "entity_0E5QDGJC03000",
      "integrationLinks": [
        {
          "contactId": "entity_0E5QDGJC03000",
          "externalId": "elation_140797386655555",
          "type": "elation"
        }
      ],
      "middleName": "William",
      "organizationContactFields": [
        {
          "id": "managedCustomField_0E5QDGJC03000",
          "name": "Preferred Pharmacy",
          "value": "CVS"
        }
      ],
      "phoneNumbers": [
        {
          "displayValue": "(222) 555-0000",
          "id": "entityContact_26RRC7PQ6JG00",
          "label": "Work"
        }
      ],
      "pronouns": "he/him",
      "tags": [
        {
          "id": "tag_0E5QDGJC03000",
          "value": "Smith"
        }
      ]
    }
  ],
  "paginationToken": "abcdefghijklmnop",
  "totalCount": 750,
  "totalCountRelation": "equal"
}