Skip to content
VocenyaDocs

Blocked callers

Numbers and prefixes whose inbound calls are turned away before your receptionist answers (spam, robocallers). Reading needs dnc:read, changes need dnc:write.

Endpoints

List blocked callers

GET/blocked-callers

Needs the dnc:read scope

Your blocked callers, newest first. Pass pattern to look up one number or prefix.

Query parameters

  • patternstringOptional

    Look up one number (any common US format) or prefix (digits ending in *).

    Up to 32 characters

  • sourcestringOptional

    manual (you added it), ai (the receptionist blocked a spam caller) or call (blocked from a call's page). | | |---| | 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. |

    One ofmanualaicall
  • per_pageintegerOptional

    How many items per page, 1 to 100.

    Minimum 1 · Maximum 100

  • cursorstring | nullOptional

    The meta.next_cursor (or meta.prev_cursor) of the previous page.

    Up to 1024 characters

Returns

Paginated set of BlockedCallerResource

  • dataarray of objectsRequired
  • linksobjectRequired
  • metaobjectRequired

Responses

  • 200Paginated set of BlockedCallerResource
  • 401The API key is missing, invalid, expired or revoked.
  • 403The key does not have the dnc:read scope.
  • 422Validation error
  • 429Too many requests for this key. Wait for the Retry-After seconds.
curl https://vocenya.com/api/public/v1/blocked-callers \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
Response 200
{
  "data": [
    {
      "id": 1,
      "livemode": true,
      "pattern": "+15125550123",
      "source": "manual",
      "note": "string",
      "calls_blocked": 1,
      "last_blocked_at": "2026-10-02T14:03:11+00:00",
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "path": "string",
    "per_page": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}

Block a caller

POST/blocked-callers

Needs the dnc:write scope

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

  • patternstringRequired

    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.

    Up to 32 characters

  • notestring | nullOptional

    Up to 255 characters

Returns

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

  • dataobjectRequired

Responses

  • 200The pattern was already on the list: the existing entry.
  • 201The entry.
  • 401The API key is missing, invalid, expired or revoked.
  • 403The key does not have the dnc:write scope.
  • 422Validation failed, or the pattern is neither a US number nor a prefix (invalid_pattern).
  • 429Too many requests for this key. Wait for the Retry-After seconds.
curl -X POST https://vocenya.com/api/public/v1/blocked-callers \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pattern": "string",
  "note": "Robocaller"
}'
Response 200
{
  "data": {
    "id": 1,
    "livemode": true,
    "pattern": "+15125550123",
    "source": "manual",
    "note": "string",
    "calls_blocked": 1,
    "last_blocked_at": "2026-10-02T14:03:11+00:00",
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}

Unblock a caller

DELETE/blocked-callers/{entry}

Needs the dnc:write scope

Path parameters

  • entryintegerRequired

    The entry id.

Responses

  • 204Removed.
  • 401The API key is missing, invalid, expired or revoked.
  • 403The key does not have the dnc:write scope.
  • 404No record with that id belongs to your account.
  • 429Too many requests for this key. Wait for the Retry-After seconds.
curl -X DELETE https://vocenya.com/api/public/v1/blocked-callers/31 \
  -H "Authorization: Bearer $VOCENYA_API_KEY"