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.

example of an XML request


control element

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:

<senderid>jsmith_user</senderid>  
<password>agfh!@34</password>

Note that both the sender ID and password are case sensitive.

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:

<controlid>7a4ce54d-63d4-4433-bf09-92fcb00bab8d</controlid>

Important Notes

uniqueid element (optional)

Specifies whether a request can be submitted more than once without an error.

<uniqueid>false</uniqueid> 

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 uniqueid to 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 uniqueid to 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.

<dtdversion>3.0</dtdversion>

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.

<includewhitespace>false</includewhitespace> 

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.

<policyid>myAsyncPolicy</policyid>

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.

showadditionalerrorinfo element (optional)

When set to true, error responses will include an <additionalinfo> section containing a unique error ID and other information:

<target> can be set at both error and message levels, and thus will be returned at both error level and message levels in error response

All optional elements will be returned with empty values if there is no information available.

Default Error Response Error Response with showadditionalerrorinfo set to true
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <control>
    <status>success</status>
    <senderid>partner1</senderid>
    <controlid>ControlIdHere</controlid>
    <uniqueid>false</uniqueid>
    <dtdversion>3.0</dtdversion>
  </control>
  <operation>
    <authentication>
      <status>success</status>
      <userid>jjones</userid>
      <companyid>Zzyzz Delivery</companyid>
      <locationid></locationid>
      <sessiontimestamp>2023-04-25T00:50:25+00:00</sessiontimestamp>
      <sessiontimeout>2023-04-25T03:00:25+00:00</sessiontimeout>
    </authentication>
    <result>
      <status>failure</status>
      <function>create</function>
      <controlid>testFunctionId</controlid>
      <data listtype="objects" count="0"/>
      <errormessage>
        <error>
          <errorno>BL01001973</errorno>
          <description>Duplicate account number</description>
          <description2>The account number &#039;5000.11&#039; already exists [Support ID: EsppO%7EZEcj0DEGV_L5hm95Ec91twAAABA]</description2>
          <correction>Enter unique account number</correction>
        </error>
        <error>
          <errorno>BL01001973</errorno>
          <description></description>
          <description2>Could not create GL Account record.</description2>
          <correction></correction>
        </error>
      </errormessage>
    </result>
  </operation>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <control>
    <status>success</status>
    <senderid>partner1</senderid>
    <controlid>ControlIdHere</controlid>
    <uniqueid>false</uniqueid>
    <dtdversion>3.0</dtdversion>
  </control>
  <operation>
    <authentication>
      <status>success</status>
      <userid>jjones</userid>
      <companyid>Zzyzz Delivery</companyid>
      <locationid></locationid>
      <sessiontimestamp>2023-04-25T00:52:34+00:00</sessiontimestamp>
      <sessiontimeout>2023-04-25T03:02:34+00:00</sessiontimeout>
    </authentication>
    <result>
      <status>failure</status>
      <function>create</function>
      <controlid>testFunctionId</controlid>
      <data listtype="objects" count="0"/>
      <errormessage>
        <error>
          <errorno>BL01001973</errorno>
          <description>Duplicate account number</description>
          <description2>The account number &#039;5000.11&#039; already exists [Support ID: d3DJI%7EZEckUDEkV9t5KUU5mpPrrQAAAAk]</description2>
          <correction>Enter unique account number</correction>
          <additionalinfo>
            <errorid>GL-0493</errorid>
            <category>Duplication Prevention</category>
            <target domain="" requestinfo="d3DJI%7EZEckUDEkV9t5KUU5mpPrrQAAAAk" object="" field="" businessinfo=""/>
            <description>
              <messageid>IA.DUPLICATE_ACCOUNT_NUMBER</messageid>
              <target domain="" requestinfo="" object="" field="" businessInfo=""/>
              <placeholders></placeholders>
            </description>
            <cdescription>
                <messageid>IA.THE_ACCOUNT_NUMBER_ALREADY_EXISTS</messageid>
                <target domain="" requestinfo="[Support ID: d3DJI%7EZEckUDEkV9t5KUU5mpPrrQAAAAk]" object="" field="" businessInfo=""/>
                <placeholders>
                  <placeholder name="ACCOUNTNO" value="5000.11"/>
                </placeholders>
            </cdescription>
            <correction>
              <messageid>IA.ENTER_UNIQUE_ACCOUNT_NUMBER</messageid>
              <target domain="" requestinfo="" object="" field="" businessInfo=""/>
              <placeholders></placeholders>
            </correction>
          </additionalinfo>
        </error>
        <error>
          <errorno>BL01001973</errorno>
          <description></description>
          <description2>Could not create GL Account record.</description2>
          <correction></correction>
          <additionalinfo>
            <errorid>GL-0504</errorid>
            <category>Unable to create record.</category>
            <target domain="" requestinfo="d3DJI%7EZEckUDEkV9t5KUU5mpPrrQAAAAk" object="" field="" businessinfo=""/>
            <description>
              <messageid></messageid>
              <category></category>
              <target domain="" object="" field="" businessInfo=""/>
              <placeholders></placeholders>
            </description>
            <cdescription>
              <messageid>IA.COULD_NOT_CREATE_GL_ACCOUNT_RECORD</messageid>
              <target domain="" requestinfo="" object="" field="" businessInfo=""/>
              <placeholders></placeholders>
            </cdescription>
            <correction>
              <messageid></messageid>
              <category></category>
              <target domain="" object="" field="" businessInfo=""/>
              <placeholders></placeholders>
            </correction>
          </additionalinfo>
        </error>
      </errormessage>
    </result>
  </operation>
</response>

operation element

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.

The 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.

<operation transaction="true">

authentication element

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.

<login>
  <userid>myUserId</userid>
  <companyid>myCompanyId</companyid>
  <password>myPassword</password>
</login>

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.

<login>
  <userid>myUserId</userid>
  <companyid>myParentCompanyId</companyid>
  <password>myPassword</password>
  <locationid>entityId</locationid>
</login>

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.

<login>
  <userid>myExtUserId</userid>
  <companyid>myConsoleId</companyid>
  <password>myPassword</password>
  <clientid>clientCompanyId</clientid>
  <locationid>entityId</locationid>
</login>

Here’s an alternative way of providing the same credentials:

<login>
  <userid>myExtUserId</userid>
  <companyid>myConsoleId|clientCompanyId|entityId</companyid>
  <password>myPassword</password>
</login>

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.

<sessionid>validSessionId</sessionid>

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:

Download


content element

Supplies one or more function elements to be executed.

function element

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.

controlid attribute

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.

<function controlid="x99876">

function name

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 (COUNTER) object.

<function controlid="3G2DFC86-9899-4283-360X-C789142D2801">
  <create>
    <LOCATION>
      <LOCATIONID>23</LOCATIONID>
      <NAME>Bags and More</NAME>
    </LOCATION>
    <VENDOR>
      <VENDORID>Vend-201</VENDORID>
      <NAME>Style Messenger Bags</NAME>
      <DISPLAYCONTACT>
        <MAILADDRESS>
          <COUNTRYCODE>US</COUNTRYCODE>
        </MAILADDRESS>
      </DISPLAYCONTACT>
    </VENDOR>
    <COUNTER>
      <ID>2389</ID>
      <DESCRIPTION>Item count</DESCRIPTION>
    </COUNTER>
  </create>
</function>

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.

The <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.

control ID for the request versus control IDs for functions


What’s next?

Provide feedback