POST /v1/precall

The precall endpoint is the most critical call in the eConsent Voice lifecycle. It runs before every dial and returns a binary decision: allowed: true (proceed with the call) or allowed: false (do not dial).

This endpoint bills 1 precall check unit per request.

Request

POST https://voice.econsent.org/v1/precall
Authorization: Bearer ec_voice_YOUR_KEY
Content-Type: application/json

Body

{
  "phone": "+15551234567",
  "calling_entity": "Acme Insurance LLC",
  "calling_number": "+18005550100",
  "purpose": "telemarketing",
  "call_type": "ai_voice",
  "metadata": {
    "campaign_id": "spring-2026",
    "agent_id": "agent_abc"
  }
}

Field	Type	Required	Description
phone	string	Yes	Consumer phone number in E.164 format
calling_entity	string	Yes	Legal entity name making the call
calling_number	string	No	Phone number that will appear on caller ID
purpose	string	Yes	telemarketing, transactional, informational, survey, debt_collection, appointment_reminder
call_type	string	Yes	ai_voice, human_voice, automated_voice
metadata	object	No	Free-form metadata, returned in the audit log

Response: Allowed

{
  "allowed": true,
  "decision_id": "dec_lx8k9m2a1b2c3d4e",
  "consent": {
    "consent_id": "cst_lx8k7n3f4g5h6j7k",
    "type": "prior_express_written",
    "ai_specific_consent": true,
    "captured_at": "2026-03-15T14:23:11Z",
    "scope": ["ai_voice", "telemarketing"],
    "evidence_url": "https://verify.econsent.org/c/cst_lx8k7n3f4g5h6j7k"
  },
  "honor_by_date": null,
  "disclosure": {
    "required": true,
    "script": "Hi, this is an AI assistant calling on behalf of Acme Insurance. Our callback number is 800-555-0100. If you'd like to opt out at any time, just say 'stop' or press 9.",
    "version": "fcc-2026-v3",
    "delivery_window_seconds": 2
  },
  "compliance_notes": []
}

Tip

When allowed: true, the disclosure.script field contains the exact FCC-required disclosure your agent should read at the start of the call. For AI voice calls, this disclosure must be delivered within delivery_window_seconds (2 seconds) of the call connecting.

Response: Blocked

{
  "allowed": false,
  "decision_id": "dec_lx8k9m2a1b2c3d4e",
  "reason": "consumer_revoked",
  "revoked_at": "2026-03-22T09:14:00Z",
  "honor_by_date": "2026-04-05T09:14:00Z",
  "compliance_notes": [
    "Consumer issued a revocation. FCC 10-business-day honor window in effect."
  ]
}

Possible reason values

Reason	Meaning
no_consent_on_file	No prior express written consent found for this calling entity
consent_expired	Consent is too old to rely on
consumer_revoked	Consumer revoked consent at this entity or via the network
scope_mismatch	Consent exists but for a different entity
ai_consent_missing	General consent exists but AI-specific consent was not captured
honor_window_active	Within the FCC 10-business-day honor window after revocation
adversary_nation	Calling agent originating from an adversary-nation jurisdiction (FCC March 2026 NPRM)

Caution

When reason is ai_consent_missing, the consumer has general telemarketing consent but has not specifically authorized AI-generated calls. You can capture AI-specific consent during the call using POST /v1/capture-verbal with consent_scope: ["ai_voice"].

Code Examples

Node.js

const { allowed, disclosure, reason } = await voice.precall({
  phone: '+15551234567',
  callingEntity: 'Acme Insurance LLC',
  callingNumber: '+18005550100',
  purpose: 'telemarketing',
  callType: 'ai_voice',
});

if (!allowed) {
  console.log(`Call blocked: ${reason}`);
  return;
}

// Read the disclosure at call start
agent.dial(phone, { disclosure: disclosure.script });

Python

decision = voice.precall(
    phone="+15551234567",
    calling_entity="Acme Insurance LLC",
    calling_number="+18005550100",
    purpose="telemarketing",
    call_type="ai_voice",
)

if not decision.allowed:
    print(f"Call blocked: {decision.reason}")
    return

agent.dial(phone, disclosure=decision.disclosure.script)

cURL

curl -X POST https://voice.econsent.org/v1/precall \
  -H "Authorization: Bearer ec_voice_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "calling_entity": "Acme Insurance LLC",
    "calling_number": "+18005550100",
    "purpose": "telemarketing",
    "call_type": "ai_voice"
  }'