An XML request document establishes various credentials and includes the API function calls to execute via the gateway.
The following example highlights the basic structure of a request. The main element,
request, organizes the functionality into child elements. The first child is a
control element that includes your Web Services credentials and applies to the entire request. This is followed by an
operation element that authenticates access to a Sage Intacct company and provides the API calls as the content.
Supplies the Web Services credentials and provides information about the request as a whole. It includes the following child elements:
senderid and password elements (required)
Permanent Web Services sender ID and corresponding password, for example:
Important: Your Web Services sender ID must be authorized for use in a given company.
controlid element (required)
Identifier used by the client application to match a request to its response. Clients can use a GUID or other identification system, for example:
The value of this element is not checked for uniqueness, which means that a request may be submitted twice without an error. Using a timestamp for this value is a good way to differentiate similar requests. If you want to provide a check for uniqueness, use
The use of
controlidis particularly important when using asynchronous requests.
Do not confuse the
controlidelement here with the
controlidattribute of a function—see below for more information.
uniqueid element (optional)
Specifies whether a request can be submitted more than once without an error.
When set to
true, which is the default, a request cannot be repeated. The
controlidattribute of the
<function>element will be checked to determine if the operation was previously executed and completed.
When set to
false, the system allows the operation to execute any number of times.
Many read operations have no meaningful side effects on the state of the system. On the other hand, many financial transactions do cause a meaningful change in the state of the system. It is common to set
false for operations that contain exclusively read operations and
true for operations that contain create or update functions. While working in test mode, you can set
false for expediency.
dtdversion element (required)
Identifies the version of the API in use. The value of
3.0 (the current version) is strongly recommended as it provides access to both the generic functions and the object-specific functions.
includewhitespace element (optional)
Specifies whether responses should be formatted with whitespace and carriage returns for readability or if these marks should be omitted to improve performance and reduce the response size. The formatting is not needed if the response will be loaded into an XML parser anyway.
When set to
true, which is the default, responses are formatted for readability.
When set to
false, responses do not include formatting.
policyid element (optional)
Chooses asynchronous communication with the gateway by designating an existing transport policy (agreed upon by the client and Sage Intacct). With asynchronous communication, the response is returned via a new HTTP connection using the parameters indicated in the transport policy settings.
If you do not include a
policyid, synchronous communication is used. With synchronous communication, the response is returned in the same HTTP connection as the request.
Note: If you need to create a transport policy, open a support case.
Supplies the user authentication for a particular shared or distributed company and provides the content for the request. The content includes one or more API function calls.
operation element has an optional attribute for setting transaction integrity.
transaction attribute (optional)
Specifies whether all the functions in the operation block represent a single transaction.
When set to
true, all of the functions are treated as a single transaction. 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.
When set to
false, which is the default, functions execute independently. If one function fails, others still proceed.
Provides credentials for access to the target company. You can provide company login credentials or a valid session ID.
login element (optional)
Chooses to authenticate the request using login credentials. How you provide login credentials varies depending on your company setup. Some examples are below.
For a standalone company
Provide a user ID, company ID, and password to log in to a standalone company. This is the same information you use when you log into the Sage Intacct UI.
For a multi-entity shared company
Add a location ID to log into a multi-entity shared company. Entities are typically different locations of a single company.
For console slide in
You need a client ID to log into a distributed child company. The user ID and password in this scenario are for access to the console, not the target/client company itself.
Here’s an alternative way of providing the same credentials:
sessionid element (optional)
Chooses to authenticate the request using a session ID, which is the preferred way to make repeated API requests. A session ID is always tied to a set of user credentials and a unique endpoint.
You can get a session ID and unique endpoint using getAPISession.
For testing purposes, you can use the Generate API Session request that is included with the downloadable Sage Intacct API collection:
Supplies one or more
function elements to be executed.
Supplies one or more API calls.
Note: The XML API includes two categories of functions, generic and object-specific. For more information, see About API Functions.
Identifier for the function that can be used to correlate the results from the gateway with your calls. To assure transaction idempotence, use unique values such as GUIDs or sequenced numbers.
The function name defines the operation to execute, and the sub-elements of the function provide the necessary input data.
The following example uses a generic
create function to create two standard and one custom (
Control ID for a request versus control ID attribute of a function
Keep in mind that there are two places in a request where control IDs are used, and they serve different purposes.
<controlid> element in the
<control> block is simply used by a client to match a request with a response. The
controlid attribute of a
<function> element is required for uniquely identifying functions for recovery purposes.