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

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.

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.

SOAP REST
Account Companies
AccountLocation CompanySiteConfigurations
Contact Contacts
Contract Contracts
InstalledProduct ConfigurationItems
Opportunity Opportunities
Product Products
Project Projects
SalesOrder SalesOrders
 

ServiceBundles

 

Services

Subscription Subscriptions
Task Tasks
Ticket Tickets

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.

Additional resources