Web Services Overview

With Web Services, you can leverage the cloud storage and advanced business logic of the Sage Intacct SaaS framework while providing your own customer-facing web application.

For example, you might integrate a web store front or other business with automated billing into the Sage Intacct ecosystem.

Once integrated, your application can create, update, read, or delete standard or custom objects in a Sage Intacct company (or tenant). Your application interacts with the system through the Web Services gateway using one of the Sage Intacct SDKs or using the underlying XML API framework directly.

integrated application communicating with the system

The rest of this topic highlights basic concepts of Web Services. Some of the material about working with XML APIs directly is not as relevant when working with the SDKs, but it’s still important to understand the underlying concepts.

Note: For information about creating extensions that are inside the Sage Intacct UI, see the Platform Services documentation.

Requirements

You must have an active Sage Intacct Web Services developer license, which includes a Web Services sender ID and password. A sender ID can be authorized for more than one company and can be tracked through an audit history report.

Note: If you need a developer license, contact your account manager.

In addition, the administrator for the target company must:

Endpoint

You use HTTP POST requests to communicate via a unique endpoint. The endpoint is always https://api.intacct.com/ia/xml/xmlgw.phtml initially.

Note: HTTP GET requests are not supported and will be blocked as of January 15, 2023. Use POST requests only.

Content-Type

All data should be sent encoded as XML with a Content-Type of application/xml. Sage Intacct currently does not support receiving JSON through Web Services.

The XML request

At a high level, the XML document establishes various credentials and provides the API function calls, as shown.

XML request with callouts

For an in-depth look at each of the elements in the XML request body, see the XML requests topic.

The XML response

By default, the response from the gateway returns to the client in the same HTTP connection as the request, which is known as a synchronous response. You can alternatively configure asynchronous responses according to your application requirements.

A successful request has a response with any number of results, while a failed response contains an error message. Both types of responses are keyed to the request’s control ID.

The response provides a control element and an operation element, just like the request. The control element shows the status of the Web Services authentication at the gateway. The operation element shows the status of the user’s company access and goes on to provide the results for each function call.

XML response with with session lifespan

For more information, see the XML responses topic.

Current version

All requests sent to the XML gateway should use 3.0 as the value in the control block’s dtdversion element.

The legacy version 2.1 is still supported, however it will likely not receive new product enhancements.

Authentication

A Web Services request requires two levels of authentication:

Important: Your Web Services sender ID must be authorized for use in a given company.

Web Services credentials

Web Services credentials consist of a sender ID and password. These are provisioned by Sage Intacct for customers/partners with an active Web Services developer license.

These credentials are not necessarily tied to a particular Sage Intacct company/user. A Marketplace Partner can use a sender ID for any Sage Intacct company that has authorized that sender ID for Web Services.

Company credentials

Company credentials consist of either:

Both of these approaches are tied to a set of company credentials. It is strongly recommended that you set up a Web Services user account in the Sage Intacct UI for this purpose (Company > Web Services user).

Login authentication

Although you can send all requests using login authentication, this is not recommended. You should use getAPISession to request a session ID and unique endpoint, then make all subsequent requests with this context.

Session authentication

A session ID is always tied to a set of company credentials and is the preferred way to make repeated Web Services requests. Session IDs can be generated and sent in a variety of ways:

The response for every API call includes the projected session timeout in the authentication element—for more information about session lifespan and timeouts, see API Sessions.

Warning: Regardless of how you receive a session ID, you should call back with a getAPISession function to validate the session and retrieve an appropriate endpoint. Do not blindly trust session IDs that your server receives over the internet. You should also validate that endpoints are *.intacct.com domains.

Use a Sage Intacct SDK

Instead of writing XML on your own, consider using one of the many libraries and tools available from Sage Intacct and third-parties. Much of what is discussed in this guide is built into these, saving time and reducing complexity.

Transactions

A transaction is a group of function calls that succeed or fail as a single unit—if one function fails, all previously executed functions within the operation are rolled back. This is useful for groups of functions that rely on each other to change information in the database.

To specify that the functions in a request be treated as a transaction, set the transaction attribute to true in the operation element:

<operation transaction="true">

When a transaction fails, you get an error in the response:

The entire transaction in this operation has been rolled back due to an error.

You can find and fix the errors, then resubmit the request. If your application is not set up to resubmit failed requests, see the information about mid-process failures in error handling for instructions.

When the transaction attribute is set to false, which is the default, functions execute independently. If one function fails, others still proceed.

Concurrent connections and timeouts

Sage Intacct limits the number of concurrent connections to the gateway by tenant (company ID). A typical tenant defaults to two connections, but this can vary based on the level of service and contractual terms. If an API request arrives when all available connections are in use, it is held for 30 seconds. If a connection does not become available in that time, an error is returned explaining that too many operations are running.

Sending a large request can cause the sender process to time out (after 15 minutes) even though the request is still being processed by the gateway. Sage Intacct recommends that you avoid timeouts with the following recommendations:

Manipulating owned objects

Certain sub-components of Sage Intacct standard objects are referred to as owned objects. An owned object belongs to another object and typically cannot be manipulated directly. Instead, you work with owned objects by making API calls on the owner.

For example, in almost all cases, the line items of a transaction are objects owned by the header. Accordingly, you cannot perform an update operation directly on a transaction’s line item record. Instead you perform an update operation on the transaction header and pass in the line item information as sub-elements of the update operation.

Web Services versus Platform Services

With Sage Intacct Web Services, you can create an external application that leverages the functionality and business logic of Sage Intacct through the API and the gateway. With Platform Services, you extend the capabilities of Sage Intacct from within the framework, such as by creating custom objects, menus, pages, and even platform applications.

Platform Services provides an additional tie in with external applications through triggers, which perform actions based on given operations. In particular, HTTP triggers can be used to make HTTP GET and POST requests to an external application (outside of the gateway). Also note that triggers can be used to make API requests within the Sage Intacct framework.

integrated application with Platform Services triggers

What’s next?

Provide feedback