PATCHes and arrays

You can include arrays in a PATCH request payload. For most arrays in Cloud API, PATCHing an array does not add the PATCH members to the members already existing in the array. Instead, the PATCH replaces the existing members with the PATCH members.

For example, in the Admin API, the User resource has a roles array. This is an array of roles the user has (such as underwriter and billing admin). The following PATCH payload sets the roles array of a user to a single role (billing_clerical). If there were other roles in this array before the patch, they are removed and replaced with role billing_clerical.

{
    "data": {
        "attributes": {
            "roles": [
                {
                    "id": "billing_clerical"
                }
            ]
        }
    }
}

If you want a PATCH to be additive to an array, you must first determine the existing members of the array, and then specify an array in the PATCH with the existing members as well as the ones you wish to add.