Skip to main content
POST
/
do-not-call
Add a phone number to the DNC list
curl --request POST \
  --url https://api.goyappr.com/do-not-call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "+972501234567",
  "reason": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "agent_ids": [
    "7e8a91c1-0000-4c11-9a00-000000000001"
  ]
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "company_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "phone_number": "+972501234567",
  "reason": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "agents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "type": "prompt",
      "flow_config": {
        "nodes": [
          {
            "id": "<string>",
            "name": "<string>",
            "position": {
              "x": 123,
              "y": 123
            },
            "agent_speaks_first": true,
            "greeting": "<string>",
            "is_literal": false,
            "next_step_id": "<string>",
            "auto_advance": true
          }
        ],
        "flow_config_version": "1",
        "metadata": {
          "custom_metadata_keys": [
            "<string>"
          ]
        }
      },
      "system_prompt": "<string>",
      "description": "<string>",
      "background_sound_volume": 0.3,
      "temperature": 1,
      "greeting_message": "<string>",
      "agent_speaks_first": true,
      "vad_stop_secs": 0.5,
      "vad_start_secs": 0.2,
      "vad_confidence": 0.7,
      "silence_timeout_secs": 60,
      "max_continuous_speech_secs": 120,
      "max_call_duration_secs": 600,
      "lead_memory_enabled": true,
      "is_active": true,
      "webhook_url": "<string>",
      "webhook_events": [],
      "extraction_parameters": [
        {
          "name": "customerName",
          "description": "The caller's full name as mentioned during the conversation"
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.goyappr.com/llms.txt

Use this file to discover all available pages before exploring further.

Add a phone number to your company’s Do-Not-Call list. Once added, outbound call placement (both POST /calls and the queue dispatcher) skips this destination: a call_logs row is written with status: "dnc_blocked" for analytics, but no carrier leg is established and no minutes are charged. The number is normalized to E.164 before storage, so any common input format works (+972501234567, 972501234567, 0501234567). Re-adding a number that is already on the list is idempotent — the existing row is returned with HTTP 200 instead of an error. To replace metadata on an existing entry, use PATCH /do-not-call/{id}. By default an entry is global (every outbound agent is blocked). Pass agent_ids to scope the block to specific agents — agents not in the list can still call the number. Required scope: do_not_call:manage.

​
Example request

# Global block (every agent in the company)
curl -X POST "https://api.goyappr.com/do-not-call" \
  -H "Authorization: Bearer $YAPPR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+972501234567",
    "reason": "Customer requested removal"
  }'

# Scoped block (only specific agents)
curl -X POST "https://api.goyappr.com/do-not-call" \
  -H "Authorization: Bearer $YAPPR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+972501234567",
    "reason": "Only block the sales agent — renewals still allowed",
    "agent_ids": ["7e8a91c1-0000-4c11-9a00-000000000001"]
  }'

​
Example response

{
  "id": "8c0e0f8a-1c11-4d3a-9a02-2b1e9d2f0001",
  "company_id": "fe493f11-0000-0000-0000-000000000001",
  "phone_number": "+972501234567",
  "reason": "Customer requested removal",
  "source": "api",
  "expires_at": null,
  "agents": [],
  "created_at": "2026-05-10T08:14:22.123Z"
}
HTTP 201 is returned for a new entry; HTTP 200 with the same shape is returned for an idempotent re-add.

​
Errors

HTTPCodeWhen
400—phone_number missing or not parseable.
400—expires_at is in the past.
400—agent_ids contains a UUID that does not reference an agent in this company.
401INSUFFICIENT_SCOPEAPI key lacks do_not_call:manage.

Authorizations

​
Authorization
string
header
required

Your Yappr API key (e.g. ypr_live_...). Generate one in the dashboard under Settings → API Keys.

Body

application/json
​
phone_number
string
required

Phone number in any common format. Normalized to E.164 before storage.

Example:

"+972501234567"

​
reason
string | null

Optional free-form note ("Customer requested removal", "Regulator complaint", etc.).

​
expires_at
string<date-time> | null

When the block lapses. Omit or set to null for a permanent block.

​
agent_ids
string<uuid>[]

Optional. Omit or pass [] for a global block (every agent in your company is blocked from calling this number). Pass an array of agent UUIDs to scope the block to those agents — agents NOT in the list can still place outbound calls to this number. All UUIDs must reference active agents in the same company; otherwise the request is rejected with HTTP 400.

Example:
["7e8a91c1-0000-4c11-9a00-000000000001"]

Response

Existing entry returned (idempotent re-add)

A phone number on the company's Do-Not-Call list. Outbound call placement skips numbers on this list — the request returns status: "dnc_blocked" and a call_logs row is recorded for analytics, but no carrier leg is established and no minutes are charged.

DNC entries can be global (block every agent) or agent-scoped (block only specific agents — others can still call the number). Scope is controlled via the agent_ids field.

​
id
string<uuid>
​
company_id
string<uuid>
​
phone_number
string

E.164 form, e.g. +972501234567. Whatever input format you submit gets normalized before storage.

Example:

"+972501234567"

​
reason
string | null

Optional free-form note. Surfaced in the dashboard, not in outbound API responses.

​
source
enum<string>

Where this entry came from. manual = added via dashboard, api = added via this API, auto = reserved for future automated additions (e.g. opt-out keyword detection during a call).

Available options:
manual,
api,
auto
​
expires_at
string<date-time> | null

When the block lapses. null = permanent. Past timestamps are filtered out at outbound-check time.

​
agents
object[]

Empty array [] (or omitted on insert) = global: every agent in the company is blocked from calling this number.

Non-empty = scoped: only the listed agents are blocked. Agents NOT in the array can still place outbound calls to this number.

On GET responses each item is the full agent object (resolved from the underlying agent_ids column so you don't have to make a second /agents/{id} call). On POST/PATCH inputs the field is named agent_ids and takes a string[] of UUIDs — see those endpoints for the input shape.

​
created_by
string<uuid> | null

Best-effort attribution to a user; null when added via API.

​
created_at
string<date-time>