Delete Conversation Records with the Retention Period API

Back to API List 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:

Initiate a deletion job.
Retrieve the deletion job status.

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

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.
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

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

{
    "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.
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

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

{
    "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.
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

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

{
    "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

{
    "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

​Initiate a Deletion Job for Specific Conversations

​Path Parameters

​Sample Request

​Header Parameters

​Request Parameters

​Sample Response

​Response Parameters

​Initiate a Deletion Job to Delete a Channel User’s Conversation Records

​Path Parameters

​Sample Request

​Header Parameters

​Request Parameters

​Sample Response

​Response Parameters

​Retrieve Deletion Job Status

​Path Parameters

​Sample Request

​Sample Response

​Response Parameters

Initiate a Deletion Job for Specific Conversations

Path Parameters

Sample Request

Header Parameters

Request Parameters

Sample Response

Response Parameters

Initiate a Deletion Job to Delete a Channel User’s Conversation Records

Path Parameters

Sample Request

Header Parameters

Request Parameters

Sample Response

Response Parameters

Retrieve Deletion Job Status

Path Parameters

Sample Request

Sample Response

Response Parameters