SOAP API lifecycle FAQ

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.

This article explains the upcoming end-of-lifecycle milestones for versions 1.5 and 1.6 of the Autotask SOAP API. It provides details about the lifecycle initiative, explains key dates and service changes, and provides guidance for migrating your integrations to SOAP 1.6 and REST.

Index

What is the lifecycle initiative?

Version 1.0 of the Autotask SOAP API was originally developed in 2007, and it has enjoyed a long and venerable service life since then, receiving its most recent major updates in version 1.5 and version 1.6. For several years, Datto has kept both of these major versions of the SOAP API available in parallel for customer use.

As part of our ongoing commitment to continual service improvement, we continuously reevaluate our platform offerings to ensure that we're delivering maximum value to our customers. With the advent of more performant, secure, and industry-preferred API technologies such as REST, the Autotask SOAP API has entered its end-of-lifecycle phase.

To ensure continuity of your integration service, we recommend migrating your SOAP API applications to the REST platform.

What are the key dates, and how will my service change?

Version 1.5 of the SOAP API received its final update with the release of SOAP 1.6 in 2018. The API entered a limited-supportability phase on July 1, 2021. Vendor integration access removal began in April 2022 and will conclude by June 2022. Access removal for general integrations is currently underway and will conclude in December 2022.

Enhancements to version 1.6 of the SOAP API will end on December 31, 2020. The service will enter a limited-supportability phase on July 1, 2024 before access deactivates on December 31, 2024.

The following timeline provides a detailed look at key milestones in the SOAP 1.5 and SOAP 1.6 end-of-lifecycle initiatives. It also explains the service changes scheduled to take place on those dates.

IMPORTANT  All listed dates are subject to change based on emergent security, customer, and business needs.

Date SOAP API version Service change
February 1, 2021 Version 1.5 API users required for application access
July 1, 2021 Version 1.5 End of support; API access will remain available until Q4 2021
Q1 2022 Version 1.5 Version 1.5 deactivation begins
December 31, 2022 Version 1.5 End of service; SOAP API version 1.5 fully deactivated and no longer available
December 31, 2020 Version 1.6 No new enhancements added
July 1, 2024 Version 1.6 End of support; API access will remain available until Q4 2024
December 31, 2024 Version 1.6 End of service; SOAP API version 1.6 will be deactivated and no longer available

How do I convert my integrations from SOAP 1.5 to SOAP 1.6?

Converting your version 1.5 integrations to version 1.6 is a simple process. To do so, perform the following steps.

  1. Update the Web Services URL and WSDL versions from 1.5 to 1.6. Refer to Autotask API zones and WSDL versions for a zone-by-zone list of SOAP API 1.6 URLs and WSDL files. When changing WSDL URLs, you will also need to make the same changes to any ASMX URL calls.

EXAMPLE  https://webservices2.autotask.net/atservices/1.5/atws.wsdl changes to https://webservices2.autotask.net/atservices/1.6/atws.wsdl

EXAMPLE  https://webservices2.autotask.net/atservices/1.5/atws.asmx becomes https://webservices2.autotask.net/atservices/1.6/atws.asmx

  1. Make sure that any API calls referencing /atservices/1.5/ change to /atservices/1.6/.

  2. Follow the steps in Defining an API User to update the authentication method of your integrations to an API User security level.
  3. Each SOAP call must have a tracking number added to the SOAP header. Review Requirements for version 1.6+ > A tracking identifier is required and Requirements for version 1.6+ > Tracking Identifier SOAP XML Example for more information.
  4. In a very small number of cases, code changes may be necessary to move from version 1.5 to version 1.6. For example, you may have an integration that creates objects, such as ticket notes, with a specific author attributed. You may find that, in version 1.6, that process is now attributing "API User" as the author. You can resolve this issue by using impersonation to have the integration create the ticket note on behalf of the desired resource. To learn more about setting up impersonation, refer to Requirements for version 1.6+ > Permission to impersonate and be impersonated.

How do I convert my integrations from SOAP to REST?

While there is no direct conversion path from SOAP to REST, as programming and scripting environments and implementations vary greatly, there are a number of different methods you can use to port your applications. We recommend migrating all of your integrations to REST via the method best suited to your specific needs.

Version 1.0 of the REST API was designed to be very similar to SOAP. It provides endpoints that correspond to SOAP entities so that the structure of an existing application can remain the same when translated to the REST architecture.

To learn more about the REST API, refer to Introduction to the Autotask REST API.

BillingItem type and sub-type SOAP to REST mapping

The type and sub-type picklist values for the BillingItem(s) endpoint differ between the Autotask SOAP and REST APIs. The following tables detail these changes.

Billing type mapping

SOAP ID & billing type name REST ID & billing type name

1. Labor

1. Labor

1. Labor

2. Labor Adjustment

2. Project Cost

3. Cost (ticket, project, contract)

3. Ticket Cost

3. Cost (ticket, project, contract)

4. Expense

4. Expense

5. Subscription

5. Subscription

6. Setup Fee

7. Recurring Contract Setup Fee

7. Recurring Services

6. Recurring Service/Bundle

8. Recurring Services Adjustment

6. Recurring Service/Bundle

9. Recurring Service Bundle

6. Recurring Service/Bundle

10. Recurring Service Bundle Adjustment

6. Recurring Service/Bundle

11. Milestone

8. Milestone

12. Contract Block

3. Cost (ticket, project, contract)

13. Contract Retainer

3. Cost (ticket, project, contract)

14. Contract Cost

3. Cost (ticket, project, contract)

15. Contract Incident

3. Cost (ticket, project, contract)

Billing sub-type mapping

SOAP ID & billing sub-type name REST ID & billing sub-type name

1. Labor

1. Ticket Labor

1. Labor

2. Task Labor

2. Milestone Labor

3. Fixed Price Ticket Labor

2. Milestone Labor

4. Fixed Price Task Labor

1. Labor

5. Ticket Labor Adjustment

1. Labor

6. Task Labor Adjustment

5. Ticket Cost Deductions

7. Service Desk Ticket Cost

6. Ticket Cost

7. Service Desk Ticket Cost

3. Project Cost Deductions

8. Project Cost

4. Project Cost

8. Project Cost

5. Ticket Cost Deductions

9. Contract Cost

7. Expense

10. Expense

8. Expense Deductions

10. Expense

9. Subscription

11. Subscription

10. Subscription Cost

11. Subscription

12. Recurring Services

12. Recurring Services

13. Recurring Services Adjustment

13. Recurring Services Adjustment

14. Recurring Service Bundle

14. Recurring Service Bundle

15. Recurring Service Bundle Adjustment

15. Recurring Service Bundle Adjustment

11. Setup Fee

16. Setup Fee

16. Milestones

17. Milestone

17. Block Purchase

18. Block Purchase

18. Retainer Purchase

19. Retainer Purchase

19. Ticket Purchase

20. Ticket Purchase

No SOAP Mapping

21. Per Contact Cost

No SOAP Mapping

22. Per Installed Product Cost