---
title: Patch
description: To patch a resource, send an HTTP PATCH request with an array of operation objects in the payload. Each operation object uses some combination of these fields:
component: pingoneaic
page_id: pingoneaic:developer-docs:crest/patch
canonical_url: https://docs.pingidentity.com/pingoneaic/developer-docs/crest/patch.html
section_ids:
  crest-patch-add: Add operation
  crest-patch-copy: Copy operation
  crest-patch-increment: Increment operation
  crest-patch-move: Move operation
  crest-patch-remove: Remove operation
  crest-patch-replace: Replace operation
  crest-patch-transform: Transform operation
  crest-patch-limitations: Limitations
  parameters: Parameters
---

# Patch

To patch a resource, send an HTTP PATCH request with an array of operation objects in the payload. Each operation object uses some combination of these fields:

* `operation`

  The type of operation.

* `field`

  The target field.

* `value`

  The value to apply.

* `from`

  The source field.

The service applies the PATCH operations in order.

```http
PATCH /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-Match: _rev
{ JSON array of patch operations }
```

PATCH operations work differently depending on the field types:

* Single-value

  An object, string, boolean, or number.

* List semantics array

  The elements are ordered, and duplicates are allowed.

* Set semantics array

  The elements are not ordered, and duplicates are not allowed.

Whether an endpoint supports a specific `operation` depends on the implementation.

## Add operation

The `add` operation ensures the target field contains the value provided, creating parent fields as necessary.

If the target field is single-valued, the value replaces the value of the target.

If the value is an array, the outcome depends on the type:

* List semantics arrays

  If you `add` an array of values, the operation appends the array to the existing list of values.

  If you `add` a single value, specify an ordinal element in the target array, or use the `{-}` special index to add the value to the end of the list.

* Set semantics arrays

  The operation merges the value(s) in the patch with the existing set of values. Any duplicates in the array are removed.

As an example, start with the following list semantic array resource:

```json
{
  "fruits": ["orange", "apple"]
}
```

The following `add` operation appends `pineapple` at the end of the array:

```json
{
  "operation": "add",
  "field": "/fruits/-",
  "value": "pineapple"
}
```

The resulting resource is:

```json
{
  "fruits": ["orange", "apple", "pineapple"]
}
```

## Copy operation

The `copy` operation replaces the value(s) of the target field with the value(s) from the source field.

The following example replaces the value of `another_mail` with the value of `mail`:

```json
[{
  "operation": "copy",
  "from": "mail",
  "field": "another_mail"
}]
```

If the source field value and the target field value are arrays, the result depends on whether the array has list semantics or set semantics. Learn more in [Add operation](#crest-patch-add).

## Increment operation

The `increment` operation changes the value or values of the target field by the amount you specify. The value must be a positive or negative number. The target must be a single-valued number.

The following example adds `1000` to `/user/payment`:

```json
[{
  "operation": "increment",
  "field": "/user/payment",
  "value": "1000"
}]
```

## Move operation

The `move` operation removes existing values from the source and adds them to the target field. The operation creates the target field if it does not exist.

The following example moves `surname` values to `lastName`:

```json
[{
  "operation": "move",
  "from": "surname",
  "field": "lastName"
}]
```

To apply a `move` to an array, the source and target must have compatible semantics. Learn more in [Add operation](#crest-patch-add).

## Remove operation

The `remove` operation deletes values in the target field.

When no value is specified, the operation removes the field:

```json
[{
  "operation": "remove",
  "field": "phoneNumber"
}]
```

For arrays, the result depends on the semantics:

* List semantic arrays

  Delete the specified element in the array.

  The following example removes the first phone number (zero-based array index):

  ```json
  [{
    "operation": "remove",
    "field": "/phoneNumber/0"
  }]
  ```

* Set semantic arrays

  Delete the specified values from the array.

  The following example removes the specified phone number:

  ```json
  [{
    "operation": "remove",
    "field": "/phoneNumber",
    "value": "+1 408 555 9999"
  }]
  ```

## Replace operation

The `replace` operation removes existing values in the target, replacing them with the provided value(s).

The following example replaces existing `telephoneNumber` values with `+1 408 555 9999`:

```json
[{
  "operation": "replace",
  "field": "/telephoneNumber",
  "value": "+1 408 555 9999"
}]
```

For list semantic arrays, you can target items by their indexes. As an example, start with the following resource:

```json
{
  "fruits": ["apple", "orange", "kiwi", "lime"]
}
```

Apply the following operation:

```json
[{
  "operation": "replace",
  "field": "/fruits/1",
  "value": "pineapple"
}]
```

The result is:

```json
{
  "fruits": ["apple", "pineapple", "kiwi", "lime"]
}
```

## Transform operation

The `transform` operation changes the field value based on a script or a data transformation command.

The following example applies the `something.js` script to the `/objects` value:

```json
[{
  "operation": "transform",
  "field": "/objects",
  "value": {
    "script": {
      "type": "text/javascript",
      "file": "something.js"
    }
  }
}]
```

## Limitations

Some HTTP client libraries do not support the HTTP PATCH operation.

Make sure the library you use supports HTTP PATCH before using this REST operation. For example, the Java method `HttpURLConnection.setRequestMethod("PATCH")` throws `ProtocolException`.

## Parameters

You can use the following query string parameters:

| Parameter                  | Description                                                                                                                                                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_fields=field[,field...]` | Return only the specified fields in the body of the response.The `field` values are JSON pointers. For example, if the resource is `{"parent":{"child":"value"}}`, `parent/child` refers to the `"child":"value"`.If the `field` is left blank, the endpoint returns all default values. |
| `_prettyPrint=true`        | Format the body of the response.                                                                                                                                                                                                                                                         |