Skip to content
Vocapable Developers

Record a revocation: suppress a number across every channel

POST
/v1/dnc-entries
curl --request POST \
  --url https://api.vocapable.com/v1/dnc-entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "phone_e164": "example", "scope": "internal", "source": "opt_out_call" }'

Suppress a number on this tenant’s internal DNC - and everything that implies.

A tenant writing this row is recording a revocation, so it takes the same path a mid-call opt-out takes: the suppression, optout.recorded, and the withdrawal of the consent standing behind the number, in one transaction. Writing the row alone would leave the consent ledger saying this person still consents - the suppression blocks the dial either way (internal DNC is an unwaivable floor, CANON fact 71), but the ledger is what an evidence request is answered from, so it may not contradict the opt-out beside it.

Which is why a revocation may not be time-limited here, and expires_at is refused by name rather than accepted and quietly ignored - the same reason scope is expressible at all (docs/07-compliance.md: internal DNC is a suppression record that persists, and is carved out of erasure for exactly that reason).

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
DncEntryCreateRequest

What a tenant may send to POST /v1/dnc-entries, which records a revocation.

expires_at is parsed but not published. Recording this entry withdraws the consent behind the number and sets the contact’s do-not-call flag, and neither is restorable when a suppression lapses, so an expiry is refused with dnc_expiry_not_supported (docs/04-api.md §9). SkipJsonSchema keeps the field out of the generated OpenAPI - a published optional field whose only legal value is null is a setter every SDK offers and every call to it 422s - while leaving the refusal reachable, so a client sending one is told why instead of having it silently dropped. Same reason scope is expressible.

object
phone_e164
required
Phone E164
string
/^\+[1-9]\d{1,14}$/
scope
DncScope
string
default: internal
Allowed values: internal federal state
source
Source
string
default: api
Allowed values: opt_out_call sms_stop manual import api

Responses

Section titled “Responses”

201

Section titled “201”

Successful Response

Media typeapplication/json
DncEntrySummary
object
id
required
Id
string
phone_e164
required
Phone E164
string
scope
required
DncScope
string
Allowed values: internal federal state
state_code
Any of:
string
source
required
Source
string
Allowed values: opt_out_call sms_stop manual import api
origin_call_id
Any of:
string
added_at
required
Added At
string format: date-time
expires_at
Any of:
string format: date-time
Example
{
  "scope": "internal",
  "source": "opt_out_call"
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}