SOAP API: user-defined fields (UDFs)

IMPORTANT  The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will eventually be deactivated. At this time, there is no end-of-lifecycle date.

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().

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.

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>