Developer Docs
Platform guideSign in

Contact lists

Who to call, and what the platform knows about them.

A contact list carries its own schema. You declare the fields once, and every contact imported into the list is checked against them, so a campaign reading memberId can rely on it being there.

A field is { fieldName, displayName, dataType, isRequired }. dataType is one of string, number, boolean, date, object or array. Every list also has two system fields, phoneNumber and fullName: always present, always required, and not yours to remove or demote. Only their displayName can change.

Contacts go in through /api/v1/contact-lists/{id}/contacts (see Contacts). Imports run in the background and are tracked as an import job.

List contact lists#

Every contact list in the key's organization that the key can read. Not paginated.

GET/api/v1/contact-lists

Responses

The contact lists.

curl -X GET "https://voice.evryhealth.com/api/v1/contact-lists" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response200
{
  "contactLists": [
    {
      "id": "6d1f3c2a-8b4e-4f7a-9c1d-2e5b7a9f0c13",
      "name": "Healthcare Providers",
      "description": "Q1 outreach",
      "totalContacts": 500,
      "status": "active",
      "schema": {
        "fields": [
          {
            "fieldName": "phoneNumber",
            "displayName": "Phone Number",
            "dataType": "string",
            "isRequired": true,
            "isSystem": true
          },
          {
            "fieldName": "fullName",
            "displayName": "Full Name",
            "dataType": "string",
            "isRequired": true,
            "isSystem": true
          },
          {
            "fieldName": "memberId",
            "displayName": "Member ID",
            "dataType": "string",
            "isRequired": true,
            "isSystem": false
          },
          {
            "fieldName": "renewalDate",
            "displayName": "Renewal date",
            "dataType": "date",
            "isRequired": false,
            "isSystem": false
          }
        ]
      },
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-20T08:00:00.000Z"
    }
  ]
}

Create a contact list#

Creates a list with the fields you declare. `phoneNumber` and `fullName` are added as required system fields; declaring them yourself has no effect.

POST/api/v1/contact-lists

Body

application/json
name
string
required
description
string
schema
{ fields: { fieldName, displayName, dataType, isRequired? }[] }
required

Responses

The created list.

curl -X POST "https://voice.evryhealth.com/api/v1/contact-lists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Healthcare Providers",
    "description": "Q1 outreach",
    "schema": {
      "fields": [
        {
          "fieldName": "memberId",
          "displayName": "Member ID",
          "dataType": "string",
          "isRequired": true
        },
        {
          "fieldName": "renewalDate",
          "displayName": "Renewal date",
          "dataType": "date"
        }
      ]
    }
  }'
Response201
{
  "id": "6d1f3c2a-8b4e-4f7a-9c1d-2e5b7a9f0c13",
  "name": "Healthcare Providers",
  "description": "Q1 outreach",
  "totalContacts": 0,
  "status": "active",
  "schema": {
    "fields": [
      {
        "fieldName": "phoneNumber",
        "displayName": "Phone Number",
        "dataType": "string",
        "isRequired": true,
        "isSystem": true
      },
      {
        "fieldName": "fullName",
        "displayName": "Full Name",
        "dataType": "string",
        "isRequired": true,
        "isSystem": true
      },
      {
        "fieldName": "memberId",
        "displayName": "Member ID",
        "dataType": "string",
        "isRequired": true,
        "isSystem": false
      },
      {
        "fieldName": "renewalDate",
        "displayName": "Renewal date",
        "dataType": "date",
        "isRequired": false,
        "isSystem": false
      }
    ]
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-20T08:00:00.000Z"
}

Get a contact list#

One list, with its schema and how many contacts it holds.

GET/api/v1/contact-lists/{id}

Path parameters

idstringrequired
Contact list id.

Responses

The contact list.

curl -X GET "https://voice.evryhealth.com/api/v1/contact-lists/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response200
{
  "id": "6d1f3c2a-8b4e-4f7a-9c1d-2e5b7a9f0c13",
  "name": "Healthcare Providers",
  "description": "Q1 outreach",
  "totalContacts": 500,
  "status": "active",
  "schema": {
    "fields": [
      {
        "fieldName": "phoneNumber",
        "displayName": "Phone Number",
        "dataType": "string",
        "isRequired": true,
        "isSystem": true
      },
      {
        "fieldName": "fullName",
        "displayName": "Full Name",
        "dataType": "string",
        "isRequired": true,
        "isSystem": true
      },
      {
        "fieldName": "memberId",
        "displayName": "Member ID",
        "dataType": "string",
        "isRequired": true,
        "isSystem": false
      },
      {
        "fieldName": "renewalDate",
        "displayName": "Renewal date",
        "dataType": "date",
        "isRequired": false,
        "isSystem": false
      }
    ]
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-20T08:00:00.000Z"
}

Update the schema#

Replaces the list's fields with the ones you send, so send the whole schema: the simplest way is to edit the fields `get` returned and send them back. `phoneNumber` and `fullName` stay system fields whether or not you include them, and `isSystem` in the request is ignored. Once a list has contacts, removing a required field is rejected. Existing contacts are not rewritten to match. Refused with 409 while an import is running into the list.

PATCH/api/v1/contact-lists/{id}/schema

Path parameters

idstringrequired
Contact list id.

Body

application/json
fields
{ fieldName, displayName, dataType, isRequired? }[]
required

Responses

The list with its new schema.

curl -X PATCH "https://voice.evryhealth.com/api/v1/contact-lists/{id}/schema" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "fieldName": "phoneNumber",
        "displayName": "Mobile",
        "dataType": "string"
      },
      {
        "fieldName": "memberId",
        "displayName": "Member ID",
        "dataType": "string",
        "isRequired": true
      },
      {
        "fieldName": "renewalDate",
        "displayName": "Renewal date",
        "dataType": "date"
      },
      {
        "fieldName": "planTier",
        "displayName": "Plan tier",
        "dataType": "string"
      }
    ]
  }'
Response200
{
  "id": "6d1f3c2a-8b4e-4f7a-9c1d-2e5b7a9f0c13",
  "name": "Healthcare Providers",
  "description": "Q1 outreach",
  "totalContacts": 500,
  "status": "active",
  "schema": {
    "fields": [
      {
        "fieldName": "phoneNumber",
        "displayName": "Mobile",
        "dataType": "string",
        "isRequired": true,
        "isSystem": true
      },
      {
        "fieldName": "fullName",
        "displayName": "Full Name",
        "dataType": "string",
        "isRequired": true,
        "isSystem": true
      },
      {
        "fieldName": "memberId",
        "displayName": "Member ID",
        "dataType": "string",
        "isRequired": true,
        "isSystem": false
      },
      {
        "fieldName": "renewalDate",
        "displayName": "Renewal date",
        "dataType": "date",
        "isRequired": false,
        "isSystem": false
      },
      {
        "fieldName": "planTier",
        "displayName": "Plan tier",
        "dataType": "string",
        "isRequired": false,
        "isSystem": false
      }
    ]
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-20T08:00:00.000Z"
}