Creates a conversation on a device in the case from the given participant and source details.
POST
/case/conversations/{caseId}/add
curl \
--request POST 'http://api.example.com/case/conversations/{caseId}/add' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--header "organization: string" \
--data '{
"name": "string",
"chatName": "string",
"source": "string",
"deviceId": "string",
"deviceType": "string",
"caseId": "string",
"service": "string",
"isGroup": true,
"externalId": "string",
"externalData": {},
"contacts": [
"string"
]
}'
Request examples
# Headers
organization: string
# Payload
{
"name": "string",
"chatName": "string",
"source": "string",
"deviceId": "string",
"deviceType": "string",
"caseId": "string",
"service": "string",
"isGroup": true,
"externalId": "string",
"externalData": {},
"contacts": [
"string"
]
}
Response examples (200)
{
"data": {
"createdAt": "2026-01-15T14:30:00.000Z",
"updatedAt": "2026-01-15T14:30:00.000Z",
"id": "507f1f77bcf86cd799439011",
"messageSharing": {
"sharedMessageCount": 320,
"totalMessageCount": 1200,
"totalReportedAt": "2026-01-15T14:30:00.000Z"
},
"selectionCoverage": {
"app": "message",
"conversationId": 42,
"mode": "selected_messages",
"selectedMessageCount": 320,
"eligibleMessageCount": 1200,
"includedMessageCount": 320,
"omittedEligibleMessageCount": 880,
"selectedNotIncludedCount": 0,
"totalMessageCount": 1200,
"deviceConversation": "507f1f77bcf86cd799439011",
"ingestionStatus": "completed",
"ingestedMessageCount": 320,
"verifiedAt": "2026-01-15T14:30:00.000Z",
"completedAt": "2026-01-15T14:30:00.000Z",
"failedAt": null,
"isPartial": true,
"coverage": "selected_messages",
"eligibleScope": "after_date_and_incremental_filters",
"uploadAttemptId": "a3e6a3ab-2c6e-469c-a3ae-ab1e926c93c2",
"deviceBackupId": "65a1b2c3d4e5f6a7b8c9d0e2",
"reportOrder": "2026-01-15T14:30:00.000Z:65a1b2c3d4e5f6a7b8c9d0e2"
},
"name": "Jane Doe",
"displayName": "Conversation with Jane Doe",
"chatName": "+15555550100",
"originalDisplayName": "Jane Doe",
"source": "message",
"linkedContacts": [
{}
],
"device": {
"createdAt": "2026-01-15T14:30:00.000Z",
"updatedAt": "2026-01-15T14:30:00.000Z",
"id": "507f1f77bcf86cd799439011",
"deviceId": "3F2504E0-4F89-11D3-9A0C-0305E82C3301",
"serialNumber": "F2LXK0QJHG7F",
"name": "Jane's iPhone",
"type": "ios",
"nonDeviceType": "string",
"model": "iPhone 15",
"timeZone": "America/New_York",
"osVersion": "18.0",
"owner": {},
"devicePhoneNumber": "+15555550100",
"organizations": [
"507f1f77bcf86cd799439011"
],
"extractionCodes": [
"507f1f77bcf86cd799439013"
],
"availableData": {
"messages": true,
"calls": false
}
},
"avatar": {
"createdAt": "2026-01-15T14:30:00.000Z",
"updatedAt": "2026-01-15T14:30:00.000Z",
"id": "507f1f77bcf86cd799439011",
"name": "photo.heic",
"providerId": "uploads/507f1f77bcf86cd799439011/photo.heic",
"convertedName": "photo.jpg",
"convertedProviderId": "uploads/507f1f77bcf86cd799439011/photo.jpg",
"provider": "s3",
"size": 204800,
"transferState": 42.0
},
"service": "iMessage",
"lastMessageText": "See you at 6",
"firstMessageDate": "2025-03-01T09:00:00.000Z",
"lastMessageDate": "2026-01-15T14:30:00.000Z",
"displayNameEditedAt": "2026-05-04T09:42:00Z",
"lastMessageExternalId": "58231",
"isGroup": false,
"owner": {},
"isReadonly": false,
"lastExportedAt": "2026-05-04T09:42:00Z",
"messagesCount": 320,
"archivedBy": {},
"archivedAt": "2026-05-04T09:42:00Z",
"starredAt": "2026-05-04T09:42:00Z",
"tags": [
{
"createdAt": "2026-01-15T14:30:00.000Z",
"updatedAt": "2026-01-15T14:30:00.000Z",
"id": "507f1f77bcf86cd799439011",
"name": "Important",
"nameLowercase": "important",
"backgroundColor": "#FDE68A",
"textColor": "#92400E",
"type": "system",
"severity": "info",
"origin": "manual",
"creatorAccessType": "org",
"isActive": true
}
],
"attachedTags": [
{
"tagId": "507f1f77bcf86cd799439011",
"tag": "Important",
"addedBy": "user",
"addedById": "507f1f77bcf86cd799439012",
"removedAt": "2026-05-04T09:42:00Z",
"removedBy": "user",
"removedById": "string"
}
],
"isPlaceholder": false,
"isArchived": false,
"isStarred": false,
"hasAllAttachmentProcessed": true,
"processedAttachmentCount": 12,
"conversationName": "Conversation with Jane Doe",
"isNameEdited": false,
"participantCount": 2
},
"statusCode": 200,
"timestamp": "2026-01-15T10:15:00.000Z"
}