Using the PATCH method in CORE Public APIs

CORE Public APIs allow you to use the HTTP PATCH method to update resources using a partial object. If you are using the PUT method to update resources, you need to send the complete object in the request body, which can be cumbersome at times and also uses unnecessary bandwidth. This is where PATCH can be helpful as it allows you to update the resources by only sending the properties that you want to change. Please note that, as of now, we do not support PATCH to update any nested objects (sub-models), e.g., address, assignedGroups, etc. For now, customFields is the only nested object that you can update using PATCH.

Updating non-nested properties using PATCH

Updating custom fields using PATCH

Updating non-nested properties using PATCH

To update the non-nested properties, you need to send a patchDocument parameter in the request body as explained in the API documentation. To know more about how to structure the patchDocument, check out the relevant RFC.

Suppose you want to update the billRate property in an Employee object using PATCH. For that, you need to send the request to:

base_url/employee/{id}

In the request body, you need to send the patchDocument, which may look something like:

{
  "Document": [
  {
    "op": "replace",
    "path": "/billRate",
    "value": 30
  }
  ],
    "version": "AAAAAAAaWBI="
}

Note that we are using the replace operation here. Also, the value for the version property must match the latest value from the object. So, it may be a good idea to first retrieve the Employee object to find the value for the version property. When the PATCH request is successful, you receive the complete Employee object in the response body with the updated billRate.

Updating custom fields using PATCH

If you are using custom fields, our APIs support updating them in a module using PATCH. Let us assume that the module you are trying to update already has custom fields assigned (whether through the web app or using the Custom Fields API). Assigned custom fields that do not yet have a value in the object are not added as sub-models in the customFields array until you set the value. Accordingly, two cases arise:

1. The custom field that you are trying to update already has a value in the object, and you simply want to change that value. In this case, you need to use the replace operation and send the new value in the patchDocument. Additionally, you need to send the objectState property to indicate that you are modifying an existing value ("objectState"=2). For example, if you want to modify a custom field value in an Employee object, you need to send the PATCH request to the base_url/employee/{id} endpoint as before, and the patchDocument in the request body may look something like:

{
  "Document": [
  {
    "op": "replace",
    "path": "/customFields/1/value",
    "value": "New Value"
  },
  { "op": "replace",
    "path": "/customFields/1/objectState",
    "value": 2
  }
  ],
    "version": "AAAAAAAaWUU="
}

Note that the version property must have the latest value from the Employee object and the customFields array is zero-indexed. You need to determine which index value to use in the patchDocument. Again, it might be a good idea to first retrieve the Employee object to determine the latest version and the index value to use. In the example above, the index value /1/ indicates we are trying to update the second index in the customFields array as seen on the retrieved employee model. When the PATCH request is successful, you receive the complete Employee object in the response body with the updated custom field value.

2. The custom field you are trying to update is assigned to the module but does not yet have a value for the object. In this case, you need to add the customFields sub-model to the object using the add operation. For example, if you want to add the value for a custom field in the Employee object, you need to send the PATCH request to the base_url/employee/{id} endpoint as before, and the patchDocument in the request body may look something like:

{
    "Document": [
        {
            "op": "add",
            "path": "/customFields",
            "value": [
                {
                    "value": "New Value",
                    "objectState": 0,
                    "definitionId": "2f13e520-0c0f-4a3e-b9fa-54e722eca545"
                }
            ]
        }
    ],
    "version": "AAAAAAAaWZk="
}

Again, the version here must be the latest one from the Employee object, and "objectState": 0 indicates we are adding a new value. Additionally, to specify the custom field that you are adding the value for, you need to get its defniitionId using the Custom Fields List endpoint and use it in the patchDocument.
Was this article helpful?
1 out of 1 found this helpful