REST API: User-defined fields (UDFs)
A user-defined field (UDF) is a custom field created in Autotask by customers to collect and store data that is not included in the default Autotask entity fields. Autotask administrators create UDFs in the Administration Settings of the Autotask system.
The REST API permits you to retrieve values for all entity UDFs via the query method. You may also update UDFs for entity types that allow update and create.
NOTE Not all entities use UDFs. To determine an entity's scope of UDF support, locate it in the and click to open the entity's topic. Alternately, use the GET call against the entity path listed for the entity in its topic.
IMPORTANT Requests to this entity require special handling. Refer to the Entity URLs and relationships section of this article for details.
Entity URLs and relationships
- If this entity has a Parent relationship, you must perform all Create, Update, and Delete actions on the parent entity.
- If this entity is a child of a parent, you can leverage our Swagger instance to find the URLs you should use in your API calls. For more information, refer to Finding resource and child access URLs of REST API entities.
- To learn how to access Swagger, refer to Using Swagger UI to explore REST API requests.
| Parent | None |
| Children | UserDefinedFieldListItems |
| URLs | Refer to UserDefinedFieldDefinitions and UserDefinedFieldListItems |
Considerations
| Permissions | Client must be logged in with a user account that has access to the appropriate Autotask module for the entity type and with sufficient rights to perform the specified API call. |
| Other | When querying any endpoint with UDFs where the set of entities returned does not have any UDF values, the response will not include the userDefinedFields collection. |
Conditions and requirements
- API calls to multi-select and reference UDFs are not supported.
- UDF fields required in the UI are not required for the API, with the exception of Site Configuration UDFs (associated with the CompanySiteConfiguration entity).
If no value is provided for a required UDF on create, and a default exists in Autotask, the default will populate the field.
If no value is provided for a required UDF on create, and there is no Autotask default, the field remains unpopulated.
If no value is provided on update and the field is not currently populated, the field remains unpopulated.
If no value is provided on update and the field is currently populated, the current value remains in place.
On update, if a required field is currently populated, the current value cannot be removed without providing a new value.
Creating user-defined fields (UDFs)
The following example demonstrates how to create a UDF called "Company Ranking" with POST.
Syntax example
POST URL:
https://webservices[n].autotask.net/atservicesrest/v1.0/UserDefinedFieldDefinitions
{
"id": 0,
"dataType": 1,
"Name": "Company Ranking",
"udfType": 1
}
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.
Entities that support UDFs
Each entity has a maximum number of active user-defined fields that you can define. For more information, refer to Managing user-defined fields.
IMPORTANT You can only query by one user-defined field at a time.
To learn how to make PUT, PATCH, and POST requests to entities that support UDFs, refer to Creating resources via POST request in the REST API, Updating data via PUT request with the REST API and Updating data via PATCH request with the REST API.
