The new Apideck developer docs are live. See what’s new →

Sage Intacct API: XML vs REST, Auth, Limits and Access

Sage Intacct API guide: XML Web Services vs the REST API, sender IDs and OAuth, locationid for entities, query paging, rate limits, sandboxes and fees.

Saurabh RaiSaurabh Rai

Saurabh Rai · Developer Relations Engineer, Apideck

14 min readView as .md
Sage Intacct API: XML vs REST, Auth, Limits and Access

Sage Intacct has two APIs, and Sage now labels the older one legacy. The XML Web Services API takes XML over HTTP POST at a single gateway URL, and Sage's tools page says that since 2025 Release 1 (February 2025) the REST API is generally available and the XML SDKs no longer get enhancements. Any Sage Intacct API project starts with that choice, then runs into the same per-company setup on both sides: a developer license, an admin who authorizes your app in each customer's company, and a Web Services user whose role decides what you can read and write (updated October 2026).

XML Web Services or the REST API

Sage's help center is direct about the recommendation: "Intacct strongly recommends using the REST API for your client applications. We continue to support the Sage Intacct XML API (Legacy), but new objects and features are released using REST," according to its developer resources page. The REST API release note lists the Web Services subscription and a Web Services user as requirements, the same as for XML.

The XML API is not going away. A banner across developer.intacct.com says its documentation moves to developer.sage.com with the FY27 R1 release, and that "the XML API itself is not changing, and existing integrations will continue to work." Sage's FAQ says legacy functions "will not be enhanced" and that there are "no plans to deprecate" them.

Comparison of the Sage Intacct XML Web Services API and REST API on status, format, credentials, what the customer's admin does, which user calls run as, how an entity is selected and how paging works, from Sage Intacct documentation read on 21 October 2026

The two APIs also differ in coverage. In Apideck's work on both APIs, customer refunds exist only on REST, while the financial reports (balance sheet, profit and loss, aged receivables) are only usable as data through XML; the Sage Intacct REST connector docs note that REST's report endpoints generate files asynchronously. A new integration that only needs transactions and master data belongs on REST. One that needs a trial balance or account balances as data still needs the XML function get_trialbalance, per Apideck's connector coverage; our financial statement API guide covers statements across ledgers.

Getting access: the developer license and the Marketplace

Every Web Services call starts with a developer license. Sage's Web Services overview says you need "an active Sage Intacct Web Services developer license, which includes a Web Services sender ID and password," and that one sender ID can be authorized for more than one company. When asked how to get that license, Sage's FAQ points to the Marketplace: "We use the term 'Marketplace Partners' for companies that develop add-ons and applications that integrate with Sage Intacct," with a link to Sage's partner page. The same overview says anyone who needs a developer license can contact their Sage account manager.

The partner page lists no fees. Sage confirmed to Apideck in October 2026 that the Marketplace partner program costs USD 2,500 a year, as recorded in our accounting API pricing guide, which includes about 66,666 API calls a month (a USD 1,000 monthly credit at USD 0.015 a call), with higher volumes agreed with Sage. Approval runs in stages that Apideck's connector docs list as a security questionnaire, a discovery meeting, the partner contract, development, an API review, technical documentation and a live demo. Ask your Sage partner contact for the timeline before you plan a launch date around it.

Each customer then does their part in their own company. The company admin enables the Web Services subscription under Company > Admin > Subscriptions, authorizes your sender ID, and creates a Web Services user, which is a user without UI access. For REST, the admin adds your application's client ID to the list of Authorized client applications; "Applications not listed cannot send REST API calls."

Five steps before the first Sage Intacct API call: get a Web Services developer license, register an OAuth application for REST, then in each customer's company turn on the Web Services subscription, authorize the sender ID or client ID, and create a Web Services user with the right role

For a click-by-click walkthrough of the credentials, see our guide on how to get your Sage Intacct API keys.

Authentication on the XML API

An XML request authenticates twice. The control block carries your sender ID and password, and the operation block carries the company credentials: either a company ID, user ID and password ("login authentication") or a session ID. Sage's requests reference also requires a controlid and a dtdversion (use 3.0). Sage advises against logging in on every call: "You should use getAPISession to request a session ID and unique endpoint, then make all subsequent requests with this context."

The session call goes in a request of its own, per the API sessions reference:

<getAPISession>
  <locationid>California</locationid>
</getAPISession>

The response returns a sessionid and an endpoint such as https://na12.intacct.com/ia/xml/xmlgw.phtml, and later calls go to that endpoint. The session expires after the user's or company's session duration, and each call resets the clock. If you receive session IDs from elsewhere, such as a Smart event, Sage says to call getAPISession to validate them and to check the endpoint is on an intacct.com domain.

When a customer's admin forgot to authorize your sender ID, every call fails with error XL03000006, "Invalid Web Services Authorization", and the description names the sender ID and company. The fix is on their side, in the Web Services authorizations list.

Authentication on the REST API

The REST API uses OAuth 2.0. You register an application in the Sage developer console and receive a client ID and secret. Apideck's connector docs and spec record what that involves in practice: registration asks for your Web Services license password, each application gets a Production or Non-production client scope that can't be changed later, and the authorization code flow runs against https://api.intacct.com/ia/api/v1/oauth2/authorize and /oauth2/token. The connection acts as the user who signed in, with that user's role permissions.

One REST behavior catches teams in production. Apideck's connector docs say that signing in to the Sage Intacct web UI as the authorizing user invalidates the token (error REST-2102), so authorize with a dedicated integration user that nobody uses interactively.

Sage's REST reference on developer.sage.com could not be checked for this update (it blocked automated access on 21 October 2026). The REST details above come from Sage's help center and Apideck's connector documentation, so confirm field names in Sage's developer portal before you code against them.

Multi-entity companies and locationid

A multi-entity company has a top level and entities below it. Sage's entity reference defines an entity as "a type of location (a dimension) that is available in multi-entity shared companies only," representing a business unit, legal entity or office. On the XML API you pick the entity with locationid, either in the login element or in getAPISession, and an empty locationid returns a top-level session. Sage's FAQ gives the same answer for writing a record at entity level: "Add a location ID to your login."

Read the entity list once per connection with a query on LOCATIONENTITY, store which entity each of your customer's records belongs to, and send every call with the matching session. A top-level session and an entity-level session see different data, and a record created at the top level is not the same as one created privately in an entity.

Dimensions

Dimensions are how Sage Intacct customers slice their books. The dimensions reference describes standard dimensions such as location and department plus user-defined dimensions (UDDs), which are custom objects enabled as GL dimensions. The getDimensions function lists both kinds for a company, with flags for userDefinedDimension and enabledInGL.

Sage's own invoice example shows how many dimensions a single line can carry: locationid, departmentid, projectid, customerid, vendorid, employeeid, itemid, classid and warehouseid. Call getDimensions when a customer connects and map their UDDs before you write transactions, because a UDD in one company won't exist in the next.

Reading data with the Sage Intacct API

The XML API has two query functions. The queries guide calls readByQuery "a legacy function that accepts a simple string" and recommends query, which supports more operators, related-object fields, sorting and aggregates. This example from that guide lists AP bills for one vendor:

<query>
    <object>APBILL</object>
    <filter>
        <equalto>
            <field>VENDORNAME</field>
            <value>Regal Services</value>
        </equalto>
    </filter>
    <select>
        <field>RECORDNO</field>
        <field>VENDORNAME</field>
    </select>
</query>

A query returns 100 records per page by default and 2,000 at most, and you move through larger sets with offset. Each offset call is a new query, so records added between calls can shift the result set. The Web Services overview gives a stricter rule for request size: "Limit queries to fewer than 1000 records and paginate the results," because large requests can time out after 15 minutes.

Two details save debugging time. readByQuery can't return owned collections such as bill lines, so fetch the key first and then read the record, as the FAQ explains. And dates on generic functions use mm/dd/yyyy; Sage's FAQ says ISO 8601 isn't supported, and both the FAQ and the parameter formats page say dates carry no timezone.

The key objects have stable names on the XML side: GLACCOUNT for GL accounts, GLBATCH for journal entries, ARINVOICE for AR invoices, APBILL for bills, ARPYMT for AR payments, and CUSTOMER and VENDOR for the contacts. On REST, Apideck's connector spec maps them to paths under https://api.intacct.com/ia/api/v1/objects/, for example accounts-receivable/invoice and general-ledger/journal-entry, with lists served by a query service.

Writing data

Writes on the XML API use generic functions such as create, except where Sage only offers a legacy function. AR invoices are one of those: the invoices reference lists "Create Invoice (Legacy)" only, using create_invoice with dates split into year, month and day elements and lines that need a GL account (or account label) and an amount. Journal entries do have a generic create. This is Sage's own example from the journal entries reference:

<create>
    <GLBATCH>
        <JOURNAL>PYRJ</JOURNAL>
        <BATCH_DATE>03/31/2016</BATCH_DATE>
        <REVERSEDATE>04/01/2016</REVERSEDATE>
        <BATCH_TITLE>Payroll accrual 03/31/2016</BATCH_TITLE>
        <ENTRIES>
            <GLENTRY>
                <ACCOUNTNO>2080</ACCOUNTNO>
                <DEPARTMENT>ADMIN</DEPARTMENT>
                <LOCATION>100</LOCATION>
                <CURRENCY>USD</CURRENCY>
                <TR_TYPE>-1</TR_TYPE>
                <AMOUNT>1450.80</AMOUNT>
                <EXCH_RATE_TYPE_ID>Intacct Daily Rate</EXCH_RATE_TYPE_ID>
                <DESCRIPTION>Accrued salaries</DESCRIPTION>
            </GLENTRY>
            <GLENTRY>
                <ACCOUNTNO>6500</ACCOUNTNO>
                <DEPARTMENT>ADMIN</DEPARTMENT>
                <LOCATION>100</LOCATION>
                <CURRENCY>USD</CURRENCY>
                <TR_TYPE>1</TR_TYPE>
                <AMOUNT>1450.80</AMOUNT>
                <EXCH_RATE_TYPE_ID>Intacct Daily Rate</EXCH_RATE_TYPE_ID>
                <DESCRIPTION>Salary expense</DESCRIPTION>
            </GLENTRY>
        </ENTRIES>
    </GLBATCH>
</create>

Set uniqueid to true in the control block for anything that creates or updates; Sage's requests reference says 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," and the function's controlid is then checked so a retried request doesn't post twice. Wrap dependent functions in <operation transaction="true"> so they roll back together, and keep each write under 100 records, as the Web Services overview recommends.

Lines are owned objects. You can't update an invoice or bill line directly; you update the header and pass the lines inside it. Regional data differs too: tax entries on journal entries apply only in Australia, the UK and South Africa in Sage's examples.

Webhooks and change tracking

Sage Intacct offers no webhook subscriptions in its XML API or help center. The closest feature is Smart events, which, per Sage's Smart events help, send an email or "a post to a web application" when a record is added, set or deleted and a condition is met. They need the Customization Services or Platform Services subscription, and the customer's admin has to configure them in their company. Sage's Smart event examples show an HTTP post that passes a session ID and the API endpoint so your server can call back. Sage's help suggests that current Smart events users consider platform triggers instead.

For most integrations that means polling: query on a modified-date field per object on a schedule, and keep the interval in line with your API budget.

Rate limits, concurrency and API transactions

The limits depend on which API you call. On REST, Sage's performance tiers page sets three entitlements per company: API transactions a month, concurrent API requests, and concurrent offline processes. The standard Tier 1 allows 100,000 transactions a month, 6 concurrent requests per application and 8 per company, and one offline process. Sage doesn't block transactions over the monthly entitlement; it bills them as overage, and transactions from authorized Marketplace partners don't count against the customer's entitlement.

On XML Web Services, the limit is per company. The Web Services overview says the gateway limits "the number of concurrent connections to the gateway by tenant (company ID)," with the example that out of 100 simultaneous requests 5 might be processed while the rest wait about 5 seconds. For offline and asynchronous jobs, such as asynchronous Web Services requests, triggers, Smart events and imports, Sage's FAQ describes the standard level of service as one API transaction job and one offline report job per company at a time; "If a company receives more than two requests at a time, the third one is held for 30 seconds" before failing with "There are too many operations running for this company." More throughput means a higher level-of-service package for that customer.

Sage also defines what counts as an API transaction. Its API usage help page says each record created, updated or deleted counts as one, an invoice or bill with all its lines in one call counts as one, and each read call counts as one "regardless of the number of records returned," including every readMore. Large pages are cheaper than many small ones. Customers can see REST and XML usage per sender ID on the API usage tab, which lags by up to two days.

Sandboxes and testing

Sandboxes exist, with conditions. Sage's sandbox help page describes a sandbox as "a copy of your production environment that you can use for testing or training," refreshable up to four times a year and valid for the billing cycle. Several modules aren't available in a sandbox, including Fixed Assets and Advanced Audit Trail. Self-service sandbox automation is limited to new direct customers with a small tenant, and isn't offered to customers on a console or who bought through a partner.

On REST, a Non-production client scope is a separate registration from your Production one. Test with a Web Services user whose role matches what your customers will grant, because a role may allow listing invoices but not creating them.

Gotchas

Sage's own reference and FAQ flag these:

  • AR invoices created from Order Entry are deleted and recreated when the order is updated, so the RECORDNO changes; Sage suggests filtering on MODULEKEY instead.
  • The attachment field in XML calls is SUPDOCID, not "attachments."
  • Updating a statistical journal entry replaces all of its entries, per Sage's FAQ, so send every line you want to keep.
  • Use the XML return format with readByQuery; other formats drop the resultId you need for readMore.
  • Custom fields aren't indexed, so filtering large objects on them slows queries.

Sage Intacct through Apideck

Apideck has two live connectors, one per API, and they aren't interchangeable: switching means a new connection and new record IDs. The XML connector takes your sender ID once and each customer's company ID, user ID, password and default entity in Apideck Vault, and it is the one that serves balance sheet, profit and loss, trial balance and aged debtors. The REST connector runs the OAuth flow, adds customer refunds, and has Apideck sandbox credentials for evaluation before your own app is registered. Both emit Apideck's virtual webhooks for created, updated and deleted records, because Sage offers no webhook subscriptions, and the Proxy API reaches any Sage endpoint the unified model doesn't cover.

Listing GL accounts is the same call on either connector, with the service ID set to sage-intacct or sage-intacct-rest:

curl "https://unify.apideck.com/accounting/ledger-accounts" \
  -H "Authorization: Bearer $APIDECK_API_KEY" \
  -H "x-apideck-app-id: $APIDECK_APP_ID" \
  -H "x-apideck-consumer-id: customer-123" \
  -H "x-apideck-service-id: sage-intacct"

Start new work on REST unless your product needs financial statements as data, and plan the Marketplace application first, because it sets your launch date more than the code does. If Sage Intacct is one of several ledgers your customers use, build the Sage Intacct API integration on Apideck's Accounting API and add the next ledger with the same calls.

Frequently asked questions

Trusted by fast-moving product & engineering teams

Bonsai by Zoom
JobNimbus
Blue Zinc
Exact
Drata