---
title: "Block a caller"
method: POST
path: "/blocked-callers"
tags: ["Blocked callers"]
---

# Block a caller

`POST /blocked-callers`

## Request

- Base URL: `https://vocenya.com/api/public/v1`
- URL: `https://vocenya.com/api/public/v1/blocked-callers`
- Auth: HTTP bearer

Block a number, or every number starting with a prefix (`512555*`). Adding a pattern already on the list
returns the existing entry with status 200.

## Request body

- StoreBlockedCallerRequest
  - `pattern` string, required: A US phone number in any common format, or a prefix of at least four digits ending in `*` to block every number starting with it.
  - `note` string, nullable

## Response `200`

The pattern was already on the list: the existing entry.

- object
  - `data` BlockedCallerResource, required
    - `id` integer, required
    - `livemode` boolean, required: `true` for live data, `false` for test data (created with a `vk_test_` key).
    - `pattern` string, required: An E.164 number, or a prefix ending in `*` that blocks every number starting with it.
    - `source` 'manual' | 'ai' | 'call', required: How a number ended up on a client's blocked callers list. | | |---| | `manual` <br/> Typed in on the blocked callers page or sent through the API. | | `ai` <br/> The AI receptionist judged a call spam and blocked the number. | | `call` <br/> Blocked from a call's page. |
    - `note` string, nullable, required
    - `calls_blocked` integer, required: How many calls this entry has turned away.
    - `last_blocked_at` string, nullable, required
    - `created_at` string, nullable, required

## Other responses

- `201`: The entry.
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `dnc:write` scope.
- `422`: Validation failed, or the pattern is neither a US number nor a prefix (`invalid_pattern`).
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

---

[API](https://skmtc.dev/vocenya/apis/vocenya-api.md) · [All operations](https://skmtc.dev/vocenya/apis/vocenya-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vocenya/apis/vocenya-api/revisions/946913941565?raw)