Consents

Records of a person agreeing to be called or texted at a number.

A consent records that a person agreed to be contacted at one number: on which channel, for what purpose, where the agreement was captured and the evidence for it, and when it ends. Numbers are stored in E.164.

A campaign created or updated with requireConsent: true calls only numbers that hold an active voice consent: granted, not revoked, and not past expiresAt. The check runs when a call is triggered and again just before it is dialled.

Reading consents needs contact_list:read. Recording and revoking them needs contact_list:manage_consent ("Manage contact consent"): owners and admins have it, and custom roles can be granted it; a key also needs that scope if it is scoped.

Consents are never deleted. Revoking keeps the record with when and why. When a person asks not to be called during a call, their voice consents in your organization are revoked automatically, with revocationReason dnc_request.

List consents#

Newest first. Filter by number, channel or status.

GET/api/v1/consents

Query parameters

phoneNumberstring: Only this number.
channelstring: voice or sms.
statusstring: active (granted and unexpired), granted, or revoked.
limitnumber: Up to 200.; Default50
cursorstring: From meta.pagination.nextCursor.

Responses

A page of consents.

Request

curl -X GET "https://voice.evryhealth.com/api/v1/consents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200

{
  "data": {
    "consents": [
      {
        "id": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b",
        "phoneNumber": "+14155551234",
        "channel": "voice",
        "status": "granted",
        "active": true,
        "purpose": "Appointment reminders",
        "source": "web_form",
        "evidence": "Checked the consent box on the intake form, IP 203.0.113.7",
        "externalContactId": "crm-48213",
        "grantedAt": "2026-01-15T10:30:00.000Z",
        "expiresAt": "2027-01-15T10:30:00.000Z",
        "revokedAt": null,
        "revocationReason": null,
        "createdByUserId": "0b7e4c1a-2d3f-4e5a-9b8c-7d6e5f4a3b2c",
        "createdAt": "2026-01-15T10:30:02.000Z",
        "updatedAt": "2026-01-15T10:30:02.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_…",
    "pagination": {
      "nextCursor": null,
      "limit": 50
    }
  }
}

Record a consent#

`channel` defaults to `voice`. `grantedAt` defaults to now and cannot be in the future; `expiresAt` must be after it. Recording a second consent for the same number keeps both.

POST/api/v1/consents

Body

application/json

phoneNumber: string (E.164); required
channel: voice | sms (default voice)
source: string, e.g. web_form, verbal, written; required
purpose: string
evidence: string
externalContactId: string
grantedAt: string (ISO 8601)
expiresAt: string (ISO 8601)

Responses

The recorded consent.

Request

curl -X POST "https://voice.evryhealth.com/api/v1/consents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155551234",
    "source": "web_form",
    "purpose": "Appointment reminders",
    "evidence": "Checked the consent box on the intake form, IP 203.0.113.7",
    "externalContactId": "crm-48213",
    "expiresAt": "2027-01-15T10:30:00.000Z"
  }'

Response201

{
  "data": {
    "id": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b",
    "phoneNumber": "+14155551234",
    "channel": "voice",
    "status": "granted",
    "active": true,
    "purpose": "Appointment reminders",
    "source": "web_form",
    "evidence": "Checked the consent box on the intake form, IP 203.0.113.7",
    "externalContactId": "crm-48213",
    "grantedAt": "2026-01-15T10:30:00.000Z",
    "expiresAt": "2027-01-15T10:30:00.000Z",
    "revokedAt": null,
    "revocationReason": null,
    "createdByUserId": "0b7e4c1a-2d3f-4e5a-9b8c-7d6e5f4a3b2c",
    "createdAt": "2026-01-15T10:30:02.000Z",
    "updatedAt": "2026-01-15T10:30:02.000Z"
  },
  "meta": {
    "requestId": "req_…"
  }
}

Get a consent#

One consent in this organization.

GET/api/v1/consents/{consentId}

Path parameters

consentIdstringrequired: Consent id.

Responses

The consent.

Request

curl -X GET "https://voice.evryhealth.com/api/v1/consents/{consentId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response200

{
  "data": {
    "id": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b",
    "phoneNumber": "+14155551234",
    "channel": "voice",
    "status": "granted",
    "active": true,
    "purpose": "Appointment reminders",
    "source": "web_form",
    "evidence": "Checked the consent box on the intake form, IP 203.0.113.7",
    "externalContactId": "crm-48213",
    "grantedAt": "2026-01-15T10:30:00.000Z",
    "expiresAt": "2027-01-15T10:30:00.000Z",
    "revokedAt": null,
    "revocationReason": null,
    "createdByUserId": "0b7e4c1a-2d3f-4e5a-9b8c-7d6e5f4a3b2c",
    "createdAt": "2026-01-15T10:30:02.000Z",
    "updatedAt": "2026-01-15T10:30:02.000Z"
  },
  "meta": {
    "requestId": "req_…"
  }
}

Revoke a consent#

Withdraws the consent from now on. The body is optional. Revoking a consent already revoked changes nothing and returns it as it is.

POST/api/v1/consents/{consentId}/revoke

Path parameters

consentIdstringrequired: Consent id.

Body

application/json

reason: string

Responses

The revoked consent.

Request

curl -X POST "https://voice.evryhealth.com/api/v1/consents/{consentId}/revoke" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Asked by email to stop calls"
  }'

Response200

{
  "data": {
    "id": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b",
    "phoneNumber": "+14155551234",
    "channel": "voice",
    "status": "revoked",
    "active": false,
    "purpose": "Appointment reminders",
    "source": "web_form",
    "evidence": "Checked the consent box on the intake form, IP 203.0.113.7",
    "externalContactId": "crm-48213",
    "grantedAt": "2026-01-15T10:30:00.000Z",
    "expiresAt": "2027-01-15T10:30:00.000Z",
    "revokedAt": "2026-02-01T09:00:00.000Z",
    "revocationReason": "Asked by email to stop calls",
    "createdByUserId": "0b7e4c1a-2d3f-4e5a-9b8c-7d6e5f4a3b2c",
    "createdAt": "2026-01-15T10:30:02.000Z",
    "updatedAt": "2026-01-15T10:30:02.000Z"
  },
  "meta": {
    "requestId": "req_…"
  }
}