Overview

With Web Services, you can leverage the cloud storage and advanced business logic of the 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 Intacct ecosystem.

Once integrated, your application can create, update, read, or delete standard or custom objects in an Intacct company (or tenant). Your application interacts with the system through the Web Services gateway using one of the 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 Intacct UI, see the Platform Services documentation.


Requirements

You must have an active 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 Intacct company (Company > Subscriptions). If you don’t need access to the Intacct 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 Intacct company:


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.


Content-Type

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


Schemas

All schemas are available for download in the intacct_dtd repository on GitHub.

As XML requests are passed through the Intacct Web Services gateway, they are parsed and validated against either a DTD or XSD:

Your XML requests must be constructed carefully in order to avoid an error response from the gateway.

Learning to read the 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.


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:

Web Services credentials

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

These credentials are not tied to a particular Intacct company/user, which means Marketplace Partners can use one sender ID across many Intacct companies (their customers).

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 only user account in the Intacct System for this purpose (Company > User > User Information).

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:

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 an Intacct SDK

Instead of writing XML on your own, consider using one of the many libraries and tools available from 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

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. Intacct recommends that you avoid timeouts with the following recommendations:


Manipulating owned objects

Certain sub-components of Intacct 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 Intacct Web Services, you can create an external application that leverages the functionality and business logic of Intacct through the API and the gateway. With Platform Services, you extend the capabilities of Intacct from within the Intacct 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 Intacct framework.


What’s next?

Provide feedback