VocalDocscontracts 1.65.0

Import a suppression list

POST /v1/consent-records/imports

PropertyValue
Operationcreate_suppression_import
GroupConsent
Scopeconsent:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited contacts.suppression_import.create (mutation)
Released in1.61.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Queues a suppression import of at most 10,000 addresses (a target), each an Organization-scope opt-out recorded with the source import and no Contact needed, and answers 202 with the import (1.61.0; rule 8), so a customer's do-not-call list is enforced from its first Call; app_push entries fail as channel_not_available.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the consent:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/consent-records/imports" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "channel": "voice",
        "address": "<address>"
      }
    ]
  }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: SuppressionImportRequest.

FieldTypeRequiredDescription
entriesarray of SuppressionEntryInputyes
occurred_atRequestTimestampnoWhen the people opted out, if the list says; the import instant otherwise.

Responses

StatusContent typeShapeError codes
202application/jsonContactImport
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 202 answer

The shape is ContactImport.

FieldTypeRequiredDescription
countsContactImportCountsyes
created_atTimestampyes
created_byActorRefyes
environmentEnvironmentyes
error_codestring or nullyesWhy a failed import read nothing; null otherwise.
errorsarray of ContactImportRowErroryesThe first 100 failed rows (a target), in row order.
finished_atTimestamp or nullyes
idContactImportIdyes
kindContactImportKindyes
object"contact_import"yes
started_atTimestamp or nullyes
statusContactImportStatusyes