Updating data via PATCH request with the REST API

This article provides the steps to update resource data in Autotask by making a PATCH request to the REST API.

To help you learn how to construct requests to the Autotask REST API, Datto provides a customizable REST API request collection for use with Postman. For more information, refer to Sample requests.

Overview

PATCH requests are useful for updating entities in Autotask. The request will update only the properties of the target that you designate. If the JSON input does not include a property for a field, the API will not update that field.

IMPORTANT  PATCH behavior differs from the way that PUT works, which updates all fields regardless of whether or not they contain values.

NOTE  You can refer to the Online Help to find root and child access URLs of the entity you wish to query. Refer to Finding resource and child access URLs of REST API entities for more information.

Syntax examples: Updating a resource with PATCH

In the non-UDF example, the PATCH request will update the ContactGroups item with an ID of 4 if it exists and if the user has sufficient permission. If the query finds a match, it sets the item's isActive value to false. Click each example's name to view the syntax.

In the UDF example, the PATCH will update the companyName and CustomerRanking fields to new values. Only the fields changing need to be passed.

PATCH URL: 

https://webservices[n].autotask.net/atservicesrest/v1.0/ContactGroups

Body: 

{
    "itemId": 4
}

IMPORTANT  You can only query by one user-defined field at a time.

PATCH URL: 

https://webservices[n].autotask.net/atservicesrest/v1.0/Companies

Body: 

                    {
  "id" : 198,
  "companyName" : "ABC Company",
   "userDefinedFields": [
        {
            "name": "CustomerRanking",
            "value": "Golden"
        },
   ]

}

Verifying success or failure

When making operational calls, you will not receive a JSON-formatted response. Creating data will return a JSON-formatted response, which will either be the item ID of the created resource or an error string array. You can verify the success or failure of operational calls by checking their return HTTP status code.

Successful operations will return an HttpStatusCode of 200 with a response that looks similar to this example:

EXAMPLE  "itemId": 4

Unsuccessful operations will return an HttpStatusCode of 500 with a response that looks similar to this example:

EXAMPLE  {"errors":["A ContactGroup already exists with Name [Test 1 Create of Contact Group x]. ContactGroup names must be unique."]}

An unsuccessful operation might also return a 400-series response, depending on the cause of the error. In general, it's a best practice to treat any response other than 200 as an error state.