Updating data via PUT request with the REST API

This article provides the steps to update resource data in Autotask by making a PUT 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

PUT requests are useful for updating entities in Autotask. The request will update all properties of the target. If the JSON you send does not include a property for a field, the target field value will default to null.

IMPORTANT  PUT behavior differs from the way that PATCH works, which only updates those values explicitly designated in the JSON input.

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 PUT

In the non-UDF example, the request will update the ContactGroups item with an ID of 4 if it exists and if the user has sufficient permission. Note that the API will set any other writable fields not included in this query to null.

In the UDF example, the PUT request will pass all desired fields where the changes are to the companyName and CustomerRanking user-defined fields. All fields with existing data must be passed in the body.

PUT URL: 

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

Body: 

                    {
    "id": "4",
    "Name": "Test 3 Update of Contact Group x",
    "IsActive": "True"
}

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

PUT URL: 

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

Body: 

                    {
    "id": 283,
    "companyName":"AB Company",
    "companyType":1,
    "ownerResourceID":4,
    "phone":"5555555555",
    "userDefinedFields": [
        {
            "name": "CustomerRanking",
            "value": "almost 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.