Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors Examples See Also

StartMergeCases

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.

Request Syntax


POST /domains/domainId/cases/caseId/merge HTTP/1.1
Content-type: application/json

{
   "fieldsConfiguration": [ 
      { 
         "fieldIds": [ 
            { 
               "id": "string"
            }
         ],
         "sourceCaseId": "string"
      }
   ],
   "performedBy": { ... },
   "relatedItemsConfiguration": { 
      "comment": boolean,
      "connectCase": boolean,
      "contact": boolean,
      "custom": boolean
   },
   "secondaryCaseIds": [ "string" ]
}

URI Request Parameters

The request uses the following URI parameters.

caseId

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.

Length Constraints: Minimum length of 1. Maximum length of 500.

Pattern: [A-Za-z0-9\-._/:#=+-]*

Required: Yes

domainId

The unique identifier of the Cases domain.

Length Constraints: Minimum length of 1. Maximum length of 500.

Required: Yes

Request Body

The request accepts the following data in JSON format.

fieldsConfiguration

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.

Type: Array of FieldsConfiguration objects

Required: No

performedBy

The user who performed the merge. If you provide userArn, you must also have DescribeUser permission on the ARN of that user.

Type: UserUnion object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No

relatedItemsConfiguration

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.

Type: RelatedItemsConfiguration object

Required: No

secondaryCaseIds

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.

Type: Array of strings

Array Members: Fixed number of 1 item.

Length Constraints: Minimum length of 1. Maximum length of 500.

Pattern: [A-Za-z0-9\-._/:#=+-]*

Required: Yes

Response Syntax


HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 403

ConflictException

The requested operation would cause a conflict with the current state of a service resource associated with the request. Resolve the conflict before retrying this request. See the accompanying error message for details.

HTTP Status Code: 409

InternalServerException

We couldn't process your request because of an issue with the server. Try again later.

retryAfterSeconds: Advice to clients on when the call can be safely retried.

HTTP Status Code: 500

ResourceNotFoundException

We couldn't find the requested resource. Check that your resources exists and were created in the same AWS Region as your request, and try your request again.

resourceId: Unique identifier of the resource affected.
resourceType: Type of the resource affected.

HTTP Status Code: 404

ServiceQuotaExceededException

The service quota has been exceeded. For a list of service quotas, see Connect Customer Service Quotas in the Connect Customer Administrator Guide.

HTTP Status Code: 402

ThrottlingException

The rate has been exceeded for this API. Please try again after a few minutes.

HTTP Status Code: 429

ValidationException

The request isn't valid. Check the syntax and try again.

HTTP Status Code: 400

Examples

Request and Response example

This example illustrates one usage of StartMergeCases.


{
  "secondaryCaseIds": [
    "[secondary_case_id]"
  ],
  "fieldsConfiguration": [
    {
      "sourceCaseId": "[secondary_case_id]",
      "fieldIds": [
        { "id": "[field_id]" }
      ]
    }
  ],
  "relatedItemsConfiguration": {
    "comment": true,
    "connectCase": true,
    "contact": true,
    "custom": true
  },
  "performedBy": {
    "userArn": "arn:aws:connect:us-west-2:[account_id]:instance/[instance_id]/agent/[agent_id]"
  }
}

{ }