> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unleashx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Audience Contacts

> Soft-delete one or more contacts by contact ID, scoped to the caller's company/workspace. No audience_id is required; every affected audience's contact count is resynced.

Use this endpoint to **soft-delete one or more contacts** by contact ID.

## Endpoint

**POST** `/audience/delete-contacts`

**Content-Type:** `application/json`
**Authentication:** Required (workspace auth)

## Request Body

```json theme={null}
{
  "contact_id": [101, 102, 103]
}
```

| Field         | Type            | Required | Description                                                                                                                                       |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contact_id`  | number \| array | Yes\*    | Contact ID(s) to delete. Accepts a single ID, an array, a JSON-string array (e.g. `"[101,102]"`), or a comma-separated string (e.g. `"101,102"`). |
| `contact_ids` | number \| array | Yes\*    | Alias for `contact_id`. Either field is accepted.                                                                                                 |

## Response

```json theme={null}
{
  "message": "Contacts deleted successfully",
  "data": { "deleted": 3 }
}
```

## Behavior

* **Soft delete** — sets the contact's status to deleted; records are not removed from the database.
* Scoped to the caller's company and workspace only — no `audience_id` is needed, and contact IDs outside the caller's scope, or already deleted, are silently skipped.
* Every audience whose contacts were affected has its denormalized contact count resynced.
* Any pending dial rows for the deleted contacts are halted immediately (they will not be called even if already queued).

## Error Cases

| Error                    | Cause                                                                    |
| ------------------------ | ------------------------------------------------------------------------ |
| `contact_id is required` | Neither `contact_id` nor `contact_ids` resolved to at least one valid ID |

## Example cURL

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/audience/delete-contacts \
  -H "Content-Type: application/json" \
  -H "token: <api_key>" \
  -d '{
    "contact_id": [101, 102, 103]
  }'
```


## OpenAPI

````yaml api-reference/openapi.json POST /audience/delete-contacts
openapi: 3.1.0
info:
  title: >-
    UnleashX - Build human like conversations | Voice Agents | Automations | AI
    Workforce
  version: 1.0.0
  description: UnleashX - Your home for human like conversations
servers:
  - url: https://www.tryunleashx.com/api/v1/global/
security:
  - bearerAuth: []
paths:
  /audience/delete-contacts:
    post:
      tags:
        - Audience
      summary: Delete audience contacts
      description: >-
        Soft-delete one or more contacts by contact ID, scoped to the caller's
        company/workspace. No audience_id is required; every affected audience's
        contact count is resynced.
      parameters:
        - name: token
          in: header
          required: true
          description: API token for authentication
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contact_id:
                  description: >-
                    Contact ID(s) to delete. Accepts a single ID, an array, a
                    JSON-string array, or a comma-separated string.
                  oneOf:
                    - type: integer
                    - type: string
                    - type: array
                      items:
                        type: integer
                contact_ids:
                  description: Alias for contact_id. Either field is accepted.
                  oneOf:
                    - type: integer
                    - type: string
                    - type: array
                      items:
                        type: integer
      responses:
        '200':
          description: Contacts deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      deleted:
                        type: integer
        '400':
          description: contact_id is required
        '401':
          description: Unauthorized
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````