- The XML request
- The XML response
- Current version
- Use a Sage Intacct SDK
- Concurrent connections and timeouts
- Manipulating owned objects
- Web Services versus Platform Services
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.
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.
You must have an active Sage Intacct Web Services developer license before you can use Web Services. Contact your account manager if you don’t already have such a license. This license entitles you to a Web Services sender ID and password. Once you have these, the next step is to make sure that the Web Services subscription is enabled in the company (Company > Subscriptions). If you don’t need access to the UI, consider using a Web Services-only user account as described in Company credentials below.
To summarize, the following are required for Web Services access to an Sage Intacct company:
- Web Services sender ID and password
- Web Services subscription enabled in the Sage Intacct company
- User account for the Sage Intacct company (can be Web Services-only)
You use HTTP POST requests to communicate via a unique endpoint. The endpoint is always
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.
All schemas are available for download in the intacct_dtd repository on GitHub.
As XML requests are passed through the Sage Intacct Web Services gateway, they are parsed and validated against either a DTD or XSD:
2.1is validated against the DTD files inside the v2.1 folder.
3.0is validated against the XSD file inside the v3.0 folder.
Your XML requests must be constructed carefully in order to avoid an error response from the gateway.
Learning to read the Sage Intacct DTD and XSD files will help you write valid XML more consistently.
The XML request
At a high level, the XML document establishes various credentials and provides the API function calls, as shown.
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.
For more information, see the XML responses topic.
All requests sent to the XML gateway should use
3.0 as the value in the
The legacy version
2.1 is still supported, however it will likely not receive new product enhancements.
A Web Services request requires two levels of authentication:
- Web Services credentials
- Company credentials
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 tied to a particular Sage Intacct company/user, which means Marketplace Partners can use one sender ID across many Sage Intacct companies (their customers).
Company credentials consist of either:
- A company ID, user ID, and password - this is called login authentication.
- A temporary session ID - this is called session authentication.
Both of these approaches are tied to a set of company credentials. It is strongly recommended that you set up a Web Services only user account in the Sage Intacct system for this purpose (Company > User > User Information).
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.
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:
- Smart events
- UI events
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.
Warning: 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.
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
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.
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 slots, but this can vary based on the level of service and contractual terms. If an API request arrives before a slot is available, it is held for 30 seconds. If a slot 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:
- Limit querying to fewer than 1000 records and paginate the results, even when using
- When manipulating records, limit the number of affected records to fewer than 100.
- Consider logging the time that it takes to get responses back from the gateway. If the elapsed time is over 5 minutes, throw an alert that suggests you reduce the request size.
- Consider setting the request’s
trueto enforce idempotence for the functions in that request—see the information about mid-process failures in error handling for instructions.
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.
- Try a tutorial that gets you started with your first Web Service requests.
- Get started using one of the Sage Intacct SDKs.