SOAP API: user-defined fields (UDFs)
IMPORTANT The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will be deactivated.
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.
NOTE Not all entities use UDFs. To determine if an entity can use UDFs, locate it in the and click to open the entity's topic. Alternately, use the API calls The getEntityInfo() SOAP API call and getUDFInfo().
The Web Services 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().
- The getEntityInfo() SOAP API call will show any UDFs being used.
- getUDFInfo() returns a list of all UDFs for a specified entity and descriptive information about the fields.
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.
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 AccountLocation 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.
UDF create() and update() XML
Include the UDF collection of tags on create or update SOAP XML within the Entity tags.
<UserDefinedFields>
<UserDefinedField>
<Name>My Ticket Priority</Name>
<Value>3</Value>
</UserDefinedField>
<UserDefinedField>
<Name>Bob's Numeric UDF</Name>
<Value>1.5000</Value>
</UserDefinedField>
</UserDefinedFields>