---
title: "Suppress phone numbers"
method: POST
path: "/v2/phone-suppressions/suppress"
tags: ["Phone Suppressions"]
---

# Suppress phone numbers

`POST /v2/phone-suppressions/suppress`

## Request

- Base URL: `https://api.carecycle.ai`
- URL: `https://api.carecycle.ai/v2/phone-suppressions/suppress`
- Auth: API key in header `x-api-key`

Block phone numbers so careCycle never contacts them and they can't call in. The block applies to your whole organization.

Send a body containing only `records`. The server generates the operation identity and returns a `jobId`. No client-generated key is required. An optional `Idempotency-Key` header (1 to 200 characters) lets you reuse the same operation when retrying with the same records, including after a lost response. Reusing a supplied key with different records returns 409. Without the header, each submission creates a new operation. Poll `GET /v2/phone-suppressions/suppress/{jobId}` with the same caller credentials to obtain progress and the final outcome; it requires `phone_suppression.manage` with the standard View prerequisite.

Submit one or more phone numbers in the `records` array, up to 1,000 per request. Each record contains `phoneNumber` and an optional `reason`. Formatting is normalized automatically; blank or unrecognized reasons become `other`. Duplicate numbers use the first record. Requires `phone_suppression.manage`. The response acknowledges records accepted for processing.

Single record:
```json
{
  "records": [
    {
      "phoneNumber": "2125550123",
      "reason": "customer_request"
    }
  ]
}
```

Multiple records:
```json
{
  "records": [
    {
      "phoneNumber": "2125550123",
      "reason": "customer_request"
    },
    {
      "phoneNumber": "+1 (212) 555-0124",
      "reason": "other"
    }
  ]
}
```

## Headers

- `Idempotency-Key` string

## Request body

- PostV2PhoneSuppressionsSuppressRequestBody
  - `records` object[], required: One or more phone numbers to suppress, up to 1,000 records.
    - `phoneNumber` string, required: Phone number to suppress. Formatting is normalized automatically.
    - `reason` 'abusive_behavior' | 'customer_request' | 'deceased' | 'duplicate_recently_handled' | 'failed_verification' | 'not_interested' | 'other' | 'out_of_network' | 'repeated_shopping' | 'suspected_fraud_spam' | 'wrong_person_invalid_number': Optional reason code. Blank or unrecognized reasons use other.

## Response `200`

POST /v2/phone-suppressions/suppress Positive response

- PostV2PhoneSuppressionsSuppressPositiveResponse
  - `jobId` string, required
  - `status` 'accepted', required
  - `acceptedCount` integer, required

## Other responses

- `400`: POST /v2/phone-suppressions/suppress Negative response 400
- `401`: POST /v2/phone-suppressions/suppress Negative response 401
- `403`: POST /v2/phone-suppressions/suppress Negative response 403
- `404`: POST /v2/phone-suppressions/suppress Negative response 404
- `409`: Idempotency-Key was already used with different records
- `422`: POST /v2/phone-suppressions/suppress Negative response 422
- `429`: POST /v2/phone-suppressions/suppress Negative response 429
- `500`: POST /v2/phone-suppressions/suppress Negative response 500
- `502`: POST /v2/phone-suppressions/suppress Negative response 502
- `503`: POST /v2/phone-suppressions/suppress Negative response 503

---

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