Consent

Record consent evidence (Tier 2: can make a number callable)

POST /v1/consents

Scope

consent:write

Tier

Tier 2 (reaches or unlocks real people)

Data

Personal data

Idempotency

Idempotency-Key: required

TIER 2. Structured evidence only: who consented, to which channel, when, captured where, and your own reference to the proof. A bare consent: true is never accepted. Needs the consent:write scope and the account switch tier2_consent_write_enabled.

Parameters

Request body

The consent evidence.

JSON: ConsentCreateRequest

Response

201: The consent record.

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/consents" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H 'Idempotency-Key: 5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a' \
  -H "Content-Type: application/json" \
  --data '{
  "phone": "+12125550123",
  "channel": "voice",
  "captured_at": "2026-09-20T10:00:00Z",
  "expires_at": "2027-09-20T10:00:00Z",
  "source": "customer_crm",
  "external_reference": "CRM-CONSENT-1001",
  "proof_url": "https://crm.example.com/consents/1001.pdf"
}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.consents.create(
    phone="+12125550123",
    channel="voice",
    captured_at="2026-09-20T10:00:00Z",
    expires_at="2027-09-20T10:00:00Z",
    source="customer_crm",
    external_reference="CRM-CONSENT-1001",
    proof_url="https://crm.example.com/consents/1001.pdf",
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

201

{
  "id": "cns_0f8fad5b-d9cb-469f-a165-70867728950e",
  "phone": "+12125550123",
  "channel": "example",
  "status": "active",
  "captured_at": "2026-09-20T10:00:00Z",
  "expires_at": "2027-09-20T10:00:00Z",
  "source": "api",
  "external_reference": "CRM-CONSENT-1001",
  "created_at": "2026-09-29T09:15:00Z"
}

Error examples

403 tier_not_enabled

{
  "type": "https://docs.dialerbee.com/errors/tier-not-enabled",
  "title": "Capability not enabled",
  "status": 403,
  "detail": "This operation can reach or unlock real people.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "tier_not_enabled",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

409 outcome_unknown

{
  "type": "https://docs.dialerbee.com/errors/outcome-unknown",
  "title": "Outcome unknown",
  "status": 409,
  "detail": "An earlier request with this Idempotency-Key may or may not have taken effect: the platform did not confirm it.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "outcome_unknown",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

400 validation_failed

{
  "type": "https://docs.dialerbee.com/errors/validation-failed",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request is not valid.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "validation_failed",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "errors": [
    {
      "pointer": "/leads/1/phone",
      "code": "missing"
    }
  ]
}

Errors

Objects

ConsentCreateRequest

Date rules the schema cannot express answer 422 validation_failed, with one errors[] entry per field: captured_at in_future (up to 5 minutes of clock skew is allowed); expires_at in_past, before_captured_at or too_long (more than 730 days after captured_at). Control characters are refused in external_reference and proof_url. Timestamps must be strings with a UTC offset.

Consent