2026/11/11 - Amazon Connect Cases - 2 new1 updated api methods
Changes This release adds APIs that allow customers to merge cases to consolidate case history, and get the status of an ongoing case merge operation.
Merges a secondary case into a primary case. The primary case, which you specify in the request URI, remains active. Both cases must belong to the same domain.
The merge runs asynchronously. To track its progress, call GetMergeCasesStatus. When the merge finishes, the selected field values and related items from the secondary case are on the primary case, the two cases are linked, and the secondary case is closed. Both cases record the merge in their audit history. For more information, see GetCaseAuditEvents.
Important things to know
Both cases must have the same customer, or at least one of them must have no customer.
While the merge runs, you can't modify the secondary case or its related items, and you can't delete the primary case. These requests return a ConflictException.
After the merge, the secondary case can be reopened, updated, and deleted, but it can't be merged again.
The request fails with a ValidationException, and no merge starts, if:
The primary case and the secondary case are the same case.
Either case is closed.
Both cases have a customer, and the customers are different.
fieldsConfiguration selects a field that can't be merged, or a field that the secondary case doesn't have.
After the merge, the primary case would have more than 500 field values, or would exceed the maximum case size.
The request fails with a ServiceQuotaExceededException if, after the merge, either case would exceed the quota for related items per case. For the primary case, the count is its existing related items, plus the related items moved from the secondary case, plus the new case link. See Connect Customer Cases quotas.
The request fails with a ConflictException if either case is already part of a merge that is running, or was previously merged into another case as the secondary case.
Endpoints: See Connect Customer endpoints and quotas.
See also: AWS API Documentation
Request Syntax
client.start_merge_cases(
domainId='string',
caseId='string',
secondaryCaseIds=[
'string',
],
fieldsConfiguration=[
{
'fieldIds': [
{
'id': 'string'
},
],
'sourceCaseId': 'string'
},
],
relatedItemsConfiguration={
'comment': True|False,
'connectCase': True|False,
'contact': True|False,
'custom': True|False
},
performedBy={
'userArn': 'string',
'customEntity': 'string'
}
)
string
[REQUIRED]
The unique identifier of the Cases domain.
string
[REQUIRED]
The unique identifier of the primary case. The primary case remains active and receives the merged field values and related items. The cases can use different templates, and the primary case keeps its template.
list
[REQUIRED]
The unique identifier of the secondary case to merge into the primary case. The secondary case is closed when the merge finishes. Specify exactly one case ID.
(string) --
list
The fields whose values to take from the secondary case. You can only merge custom fields and the following system fields: assigned_queue, assigned_user, summary, and case_reason. If you select any other system field, the request fails with a ValidationException.
For each field that can be merged, the merge works as follows:
If you select the field, the primary case gets the secondary case's value. If the secondary case's value is empty, the primary case's value is cleared.
If you don't select the field and the primary case has a value for it, the primary case keeps its value.
If you don't select the field and the primary case doesn't have the field, or its value is empty, the primary case gets the secondary case's value. This applies even when the field isn't on the primary case's template.
Field values are read from both cases when the merge runs, so changes that you make to the primary case after you start the merge are taken into account.
Specify at most one entry, and set its sourceCaseId to the secondary case ID.
(dict) --
Specifies the fields whose values to take from the secondary case when you merge cases.
fieldIds (list) -- [REQUIRED]
The fields whose values to take from the source case. Each field must exist on the source case and must be a field that can be merged. Don't list the same field more than once.
(dict) --
Object for unique identifier of a field.
id (string) -- [REQUIRED]
Unique identifier of a field.
sourceCaseId (string) -- [REQUIRED]
The unique identifier of the case to take the field values from. This must be the secondary case.
dict
The types of related items to move from the secondary case to the primary case. Related items of a type that you don't select, or set to false, stay on the closed secondary case. If you omit this parameter, no related items are moved.
File, SLA, and work plan related items are never moved. They stay on the secondary case.
comment (boolean) --
Whether to move Comment related items to the primary case.
connectCase (boolean) --
Whether to move Case related items to the primary case. If the primary case already links to the same case, the secondary case's link is removed instead of moved.
contact (boolean) --
Whether to move Contact related items to the primary case. If the same contact is related to both cases, the primary case keeps its related item and gets any tag keys that only the secondary case's related item has.
custom (boolean) --
Whether to move Custom related items to the primary case.
dict
The user who performed the merge. If you provide userArn, you must also have DescribeUser permission on the ARN of that user.
userArn (string) --
Represents the Connect Customer ARN of the user.
customEntity (string) --
Any provided entity.
dict
Response Syntax
{}
Response Structure
(dict) --
Returns the merge status of a case. Use this operation to track a merge that you started with StartMergeCases, or to check whether a case is part of a merge before you modify it.
The operation returns the following, depending on the case:
For the primary case or the secondary case of a merge that is running, it returns IN_PROGRESS.
For a case that was merged into another case as the secondary case, it returns COMPLETED.
For any other case, it returns a ResourceNotFoundException. This includes the primary case after its merge finishes.
Endpoints: See Connect Customer endpoints and quotas.
See also: AWS API Documentation
Request Syntax
client.get_merge_cases_status(
domainId='string',
caseId='string'
)
string
[REQUIRED]
The unique identifier of the Cases domain.
string
[REQUIRED]
The unique identifier of the case. This can be the primary case or the secondary case of a merge.
dict
Response Syntax
{
'status': 'IN_PROGRESS'|'COMPLETED',
'primaryCaseId': 'string',
'secondaryCaseIds': [
'string',
]
}
Response Structure
(dict) --
status (string) --
The merge status of the case.
primaryCaseId (string) --
The unique identifier of the primary case of the merge.
secondaryCaseIds (list) --
The unique identifiers of the secondary cases of the merge.
(string) --
{'auditEvents': {'mergeMetadata': {'mergeEventId': 'string',
'primaryCaseId': 'string',
'secondaryCaseId': 'string'},
'type': {'Case.Merged'}}}
Returns the audit history about a specific case if it exists.
See also: AWS API Documentation
Request Syntax
client.get_case_audit_events(
caseId='string',
domainId='string',
maxResults=123,
nextToken='string'
)
string
[REQUIRED]
A unique identifier of the case.
string
[REQUIRED]
The unique identifier of the Cases domain.
integer
The maximum number of audit events to return. When no value is provided, 25 is the default.
string
The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.
dict
Response Syntax
{
'nextToken': 'string',
'auditEvents': [
{
'eventId': 'string',
'type': 'Case.Created'|'Case.Updated'|'RelatedItem.Created'|'RelatedItem.Deleted'|'RelatedItem.Updated'|'Case.Merged',
'relatedItemType': 'Contact'|'Comment'|'File'|'Sla'|'ConnectCase'|'Custom',
'performedTime': datetime(2015, 1, 1),
'fields': [
{
'eventFieldId': 'string',
'oldValue': {
'stringValue': 'string',
'doubleValue': 123.0,
'booleanValue': True|False,
'emptyValue': {},
'userArnValue': 'string'
},
'newValue': {
'stringValue': 'string',
'doubleValue': 123.0,
'booleanValue': True|False,
'emptyValue': {},
'userArnValue': 'string'
}
},
],
'performedBy': {
'user': {
'userArn': 'string',
'customEntity': 'string'
},
'iamPrincipalArn': 'string'
},
'mergeMetadata': {
'mergeEventId': 'string',
'primaryCaseId': 'string',
'secondaryCaseId': 'string'
}
},
]
}
Response Structure
(dict) --
nextToken (string) --
The token for the next set of results. This is null if there are no more results to return.
auditEvents (list) --
A list of case audits where each represents a particular edit of the case.
(dict) --
Represents the content of a particular audit event.
eventId (string) --
Unique identifier of a case audit history event.
type (string) --
The type of audit history event.
Valid Values: Case.Created | Case.Updated | RelatedItem.Created | RelatedItem.Updated | RelatedItem.Deleted | Case.Merged
Case.Merged summarizes a merge on each of the two cases that took part in it.
relatedItemType (string) --
The Type of the related item.
performedTime (datetime) --
Time at which an Audit History event took place.
fields (list) --
A list of Case Audit History event fields.
(dict) --
Fields for audit event.
eventFieldId (string) --
Unique identifier of field in an Audit History entry.
oldValue (dict) --
Union of potential field value types.
stringValue (string) --
Can be either null, or have a String value type. Only one value can be provided.
doubleValue (float) --
Can be either null, or have a Double value type. Only one value can be provided.
booleanValue (boolean) --
Can be either null, or have a Boolean value type. Only one value can be provided.
emptyValue (dict) --
An empty value. You cannot set EmptyFieldValue on a field that is required on a case template.
This structure will never have any data members. It signifies an empty value on a case field.
userArnValue (string) --
Can be either null, or have a String value type formatted as an ARN. Only one value can be provided.
newValue (dict) --
Union of potential field value types.
stringValue (string) --
Can be either null, or have a String value type. Only one value can be provided.
doubleValue (float) --
Can be either null, or have a Double value type. Only one value can be provided.
booleanValue (boolean) --
Can be either null, or have a Boolean value type. Only one value can be provided.
emptyValue (dict) --
An empty value. You cannot set EmptyFieldValue on a field that is required on a case template.
This structure will never have any data members. It signifies an empty value on a case field.
userArnValue (string) --
Can be either null, or have a String value type formatted as an ARN. Only one value can be provided.
performedBy (dict) --
Information of the user which performed the audit.
user (dict) --
Represents the entity that performed the action.
userArn (string) --
Represents the Connect Customer ARN of the user.
customEntity (string) --
Any provided entity.
iamPrincipalArn (string) --
Unique identifier of an IAM role.
mergeMetadata (dict) --
Information about the merge that produced this audit event. Present only on audit events produced by a merge. For more information, see StartMergeCases.
mergeEventId (string) --
The unique identifier of the merge. All audit events produced by the same merge, on both cases, have the same value. Use it to group the changes that a merge made.
primaryCaseId (string) --
The unique identifier of the primary case of the merge.
secondaryCaseId (string) --
The unique identifier of the secondary case of the merge.