IMPORTANT The SOAP API entered a limited enhancement phase in Q4 2020. Access deactivation for version 1.5 began in Q1 2022 and will enter its concluding phases in October 2022. Access to version 1.6 will be deactivated in Q4 2024. Visit our SOAP API lifecycle FAQ article to learn more.
Version 1.6 of the Autotask SOAP API is a major revision from previous versions of the platform. To ensure the best service and performance, version 1.6.0 includes new requirements, and sound development processes are more important than ever.
This version of the API introduces the following significant changes.
The API User (API-only) security level is required to access API v1.6. It provides full system administrator access to Autotask modules, features, and data via the Autotask Web Services API, with no access to the Autotask UI.
IMPORTANT Users with licenses that provide access to the UI and security levels that allow access to the API can access only Web services v 1.5.
There is no per-seat charge for this security level and no limit to the number of resources that can be assigned an API-only user security level. You no longer have to provide full Autotask user credentials to your integration partners, and partners can each have their own credentials. This makes it easier for you to keep track of what each integration is doing. Coupled with the API tracking identifiers, it provides more precision for Autotask when diagnosing and addressing any issues that might come up.
NOTE If a resource's API User (API-only) security level is changed to another Autotask security level, applicable per seat charges will be billed.
You can configure API Only security levels to allow the impersonation of other resources on supported endpoints. The API will set the impersonated user’s name and ImpersonatorCreatorResourceID value as the content creator during create operations. This data will not change during update operations.
You'll need to ensure that you configure the security level of the impersonated resource to allow impersonation. The impersonated resource must have permission to act as configured in the other sections on the Edit Security Level page.
- Both the integration user and the API-only user must have security level permission to add or edit the entity.
- The integration user's security level must allow the resource to be impersonated.
- The API-only user's security level must allow impersonation on the entity type.
For configuration details, refer to Allow impersonation of resources with this security level.
You can configure the following entities to allow querying, adding, editing, and deleting (bold items only):
Impersonation SOAP XML Example
Integration users need to provide the <ImpersonateAsResourceID> tag in the AutotaskIntegrations SOAP header. This examples creates a ticket note on behalf of another user account.
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Header> <AutotaskIntegrations xmlns="http://autotask.net/ATWS/v1_6/"> <IntegrationCode>[substitute Tracking Identifier here]</IntegrationCode> <ImpersonateAsResourceID>[substitute ID of RESOURCE TO IMPERSONATE here]</ImpersonateAsResourceID> </AutotaskIntegrations> </soap:Header> <soap:Body> <create xmlns="http://autotask.net/ATWS/v1_6/"> <Entities> <Entity xsi:type="TicketNote" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Description>Note Description</Description> <NoteType>3</NoteType> <Publish>1</Publish> <TicketID>14072</TicketID> <Title>Note Title</Title> </Entity> </Entities> </create> </soap:Body> </soap:Envelope>
Tracking identifiers are required for API-only users accessing v1.6. Identifiers are critical for Autotask in providing optimal service to all API users. They are also a valuable tool for integrators working with multiple API-only users and building multiple integrations.
Tracking identifiers are assigned or self-generated on the Security tab of the API-only user's Resource Management page when adding a new API-only user, or editing an API-only user that does not yet have an identifier assigned.
There are two types of identifiers, Vendor and Custom.
- Vendor identifiers are assigned to an Autotask integrations partner. They can be selected from a menu.
- Custom (Internal Integration) identifiers are for customers who develop and use integrations for their internal use. They are automatically generated on the Security tab and are then displayed on that tab. The Custom (Internal Integration) tracking ID allows access to only the user's database.
A tracking identifier is not required to access v1.5, unless the user accessing v1.5 already has an identifier assigned. In that case, the user is required to provide their identifier.
NOTE Tracking identifiers appear on the Manage Resource page, Security tab. API-only users do not have access to the UI, so you will have to ask a user with HR Security level to provide the tracking ID to you.
IMPORTANT Example of a tracking identifier SOAP XML with a query on the Account entity. From experience with vendors already implementing tracking identifiers, it is important to note the <AutotaskIntegrations xmlns="http://autotask.net/ATWS/v1_6/"> must be included like as shown. The <AutotaskIntegrations> tag without the xmlns="http://autotask.net/ATWS/v1_6/" doesn't work properly.
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Header> <AutotaskIntegrations xmlns="http://autotask.net/ATWS/v1_6/"> <IntegrationCode>[substitute tracking identifier here]</IntegrationCode> </AutotaskIntegrations> </soap:Header> <soap:Body> <query xmlns="http://autotask.net/ATWS/v1_6/"> <sXML><![CDATA[<queryxml><entity>Account</entity><query><condition><field>id<expression op="greaterthan">0</expression></field></condition></query></queryxml>]]></sXML> </query> </soap:Body> </soap:Envelope>
For details on assigning API tracking identifiers, refer to API tracking identifier.
To remain aligned with industry standard best practices, Datto now requires TLS 1.2 protocol for inbound connections to Autotask.net, as well as inbound calls to the API. This applies to partner integrations and Autotask customers who develop their own integrations.
NOTE The Web Services API does not support single sign on (SSO). If you are using SSO with Autotask, the API will recognize your Autotask credentials used prior to SSO. The password will not expire.