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

# Delete Conversation Records with the Retention Period API

<Badge icon="arrow-left" color="gray">[Back to API List](/ai-for-service/apis/automation/api-list)</Badge>

Use this API to delete specific conversations by conversation IDs within the defined retention period or to delete all conversations associated with a specific channel user. It's a two-step process:

1. Initiate a deletion job.
2. Retrieve the deletion job status.

<Note> This API only initiates the deletion job. The actual deletion of conversation records is performed during off-peak hours.</Note>

## Initiate a Deletion Job for Specific Conversations

Use this API to delete specific conversation records by conversation IDs.

| Field | Value |
| - | - |
| **Method** | POST |
| **Endpoint** | `https://{{host}}/api/public/bot/{{botId}}/conversations/delete` |
| **Content Type** | `application/json` |
| **Authorization** | `auth: {{JWT}}` See [How to generate the JWT Token](/ai-for-service/apis/automation/api-introduction#generating-the-jwt-token). |
| **API Scope** | App Builder: Delete Conversations; Admin Console: Not Applicable |

### Path Parameters

| Parameter | Required | Description |
| - | - | - |
| `host` | Required | Environment URL, for example, `https://platform.kore.ai`. |
| `botId` | Required | App ID or Stream ID. You can access it by navigating to **App Settings** → **App Profile** in the app. |

### Sample Request

```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/conversations/delete' \
--header 'auth: {{jwt_token}}' \
--header 'Content-Type: application/json' \
--data '{
    "conversationIds": [
        "69eb0c87ec444445976xxxxx",                                                                                                                                                                                                                  
        "69eb0b5c7cd98618e06xxxxx"      
      ]          
    }' 
```

### Header Parameters

| Parameter | Required | Description |
| - | - | - |
| `auth` | Required | Environment URL, for example, `https://platform.kore.ai` |
| `botId` | Required | application/json;charset=UTF-8 |

### Request Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `conversationIds` | array of strings | required | List of conversation IDs to delete. Max 100 items per request. Takes precedence over date parameters. |

### Sample Response

```json theme={null}
{
    "status": "queued",
    "jobId": "cdj-e8c0d360-6b5b-50ab-bda1-ae54b18xxxxx",
    "message": "Deletion job queued successfully. The bot owner will be notified by email on completion.",
    "submittedAt": "2026-05-08T06:22:56.097Z"
}
```

### Response Parameters

| Parameter | Type | Description |
| - | - | - |
| `status` | string | Indicates the current status of the deletion job request. A value of `queued` indicates that the job was successfully accepted and scheduled for processing. |
| `jobId` | string | Unique job identifier to check the job status. Included in change logs and in the bot owner's completion email for correlation. |
| `message` | string | Response message indicating the result of the request. |
| `submittedAt` | string (date-time) | UTC timestamp at which the request was received and queued |

## Initiate a Deletion Job to Delete a Channel User's Conversation Records

Use this API to delete all conversation records associated with a specific channel user within the specified date range and retention period.

| Field | Value |
| - | - |
| **Method** | POST |
| **Endpoint** | `https://{{host}}/api/public/bot/{{botId}}/conversations/delete` |
| **Content Type** | `application/json` |
| **Authorization** | `auth: {{JWT}}` See [How to generate the JWT Token](/ai-for-service/apis/automation/api-introduction#generating-the-jwt-token). |
| **API Scope** | App Builder: Delete Conversations; Admin Console: Not Applicable |

### Path Parameters

| Parameter | Required | Description |
| - | - | - |
| `host` | Required | Environment URL, for example, `https://platform.kore.ai` |
| `botId` | Required | App ID or Stream ID. You can access it by navigating to **App Settings** → **App Profile** in the app. |

### Sample Request

```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/conversations/delete' \
--header 'auth: {{jwt_token}}' \
--header 'Content-Type: application/json' \
--data '{
    "cId":"u-e64325ed-82dc-5dd4-88dd-54ac52exxxxx",
    "startDate": "2026-05-04T00:00:00.000Z",              
      "endDate": "2026-05-04T23:59:59.999Z"
    }' 
```

### Header Parameters

| Header | Description | Required/Optional |
| - | - | - |
| `auth` | JWT token for authentication. | required |
| `Content-Type` | application/json;charset=UTF-8 | required |

### Request Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `cId` | string | Yes | A unique customer identifier whose conversation records must be deleted. |
| `startDate` | string (date) | No | Inclusive start of the deletion range. ISO 8601 format YYYY-MM-DD. Defaults to the user or bot creation date (whichever is later) when cId is used and this is omitted |
| `endDate` | string (date) | No | Inclusive end of the deletion range. ISO 8601 format YYYY-MM-DD. Must not be a future date. Defaults to the current date when omitted |

### Sample Response

```json theme={null}
{
    "status": "queued",
    "jobId": "cdj-1e905b0a-41be-5484-ac9b-3a31a41xxxxx",
    "message": "Deletion job queued successfully. The bot owner will be notified by email on completion.",
    "submittedAt": "2026-05-11T04:50:20.538Z"
}
```

### Response Parameters

| Parameter | Type | Description |
| - | - | - |
| `status` | string | Indicates the current status of the deletion job request. A value of `queued` indicates that the job was successfully accepted and scheduled for processing. |
| `jobId` | string | Unique job identifier to check the job status. Included in change logs and in the bot owner's completion email for correlation. |
| `message` | string | Response message indicating the result of the request. |
| `submittedAt` | string (date-time) | UTC timestamp at which the request was received and queued |

## Retrieve Deletion Job Status

Use this API to retrieve the status and execution summary of a deletion job.

| Field | Value |
| - | - |
| **Method** | GET |
| **Endpoint** | `https://{{host}}/api/public/bot/{{botId}}/conversations/delete/{{jobId}}` |
| **Content Type** | `application/json` |
| **Authorization** | `auth: {{JWT}}` See [How to generate the JWT Token](/ai-for-service/apis/automation/api-introduction#generating-the-jwt-token). |
| **API Scope** | App Builder: Delete Conversations; Admin Console: Not Applicable |

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `botId` | string | Yes | The Stream ID or App ID. You can access it from the bot's App Settings --> App Profile page. |
| `host` | string | Yes | The Environment URL. For example, `https://platform.kore.ai` |
| `jobId` | string | yes | The unique identifier of the job whose status needs to be retrieved. |

### Sample Request

```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/conversations/delete/{{jobId}}' \
--header 'auth: {{jwt_token}}' \
--data '' 
```

### Sample Response

The response includes the deleted records with the status as queued. After the job is run successfully and the records are deleted, the status changes to completed.

**When a job is queued**

```json expandable=true theme={null}
{
    "jobId": "cdj-2e5c62ad-df3a-542b-a59e-c72768xxxxx",
    "status": "queued",
    "requestType": "cId",
    "submittedAt": "2026-05-08T17:49:06.505Z",
    "scheduledAt": "2026-05-08T18:00:00.185Z",
    "startedAt": "2026-05-08T18:00:00.204Z",
    "completedAt": "2026-05-08T20:01:12.618Z",
    "result": {
        "totalConversations": 3,
        "processedCount": 3,
        "deletedCount": 89,
        "failedCount": 0,
        "skippedCount": 0,
        "retriesRemaining": 3
    }
} 
```

**When a job is completed**

```json expandable=true theme={null}
{
    "jobId": "cdj-2e5c62ad-df3a-542b-a59e-c72768bxxxxx",
    "status": "completed",
    "requestType": "cId",
    "submittedAt": "2026-05-08T17:49:06.505Z",
    "scheduledAt": "2026-05-08T18:00:00.185Z",
    "startedAt": "2026-05-08T18:00:00.204Z",
    "completedAt": "2026-05-08T20:01:12.618Z",
    "result": {
        "totalConversations": 3,
        "processedCount": 3,
        "deletedCount": 89,
        "failedCount": 0,
        "skippedCount": 0,
        "retriesRemaining": 3
    }
}
```

### Response Parameters

| Parameter | Description | Type | Example |
| - | - | - | - |
| `jobId` | Unique identifier generated for the deletion job. | string | `cdj-31e88d3d-b687-5bb6-9eb4-4ee67f6xxxxx` |
| `status` | Current status of the deletion job. | string | completed |
| `requestType` | Type of deletion request submitted. | string | `cId` |
| `submittedAt` | Timestamp indicating when the job request was submitted. | string (ISO 8601 timestamp) | `2026-05-04T19:43:14.534Z` |
| `scheduledAt` | Timestamp indicating when the job was scheduled for execution. | string (ISO 8601 timestamp) | `2026-05-07T18:00:00.073Z` |
| `startedAt` | Timestamp indicating when job execution started. | string (ISO 8601 timestamp) | `2026-05-07T18:00:00.091Z` |
| `completedAt` | Timestamp indicating when the job execution completed. | string (ISO 8601 timestamp) | `2026-05-07T18:00:01.008Z` |
| `result` | Object containing the deletion job execution summary. | object | |
| `result.totalConversations` | Total number of conversations identified for processing. | integer | 0 |
| `result.processedCount` | Total number of conversations processed by the job. | integer | 0 |
| `result.deletedCount` | Total number of conversations successfully deleted. | integer | 0 |
| `result.failedCount` | Total number of conversations that failed deletion. | integer | 0 |
| `result.skippedCount` | Total number of conversations skipped during processing. | integer | 0 |
| `result.retriesRemaining` | Number of retry attempts remaining for failed deletions. | integer | 3 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.