Does each location need a separate Sage user?

Yes, if you want independent refresh tokens. Using the same user for multiple locations causes token overwrites that break other connections.

Why do we need array-order mapping on create?

Because Sage does not include your external IDs in the response. It returns results in the order you sent them, so your middleware must track position to map results correctly.

Why use both /query and /objects endpoints?

Because /query does not return all fields. The /objects/... endpoint is sometimes required for full data retrieval, especially for fields not exposed in the query response.

Can I change the client scope after creating an application?

No. The client scope (Production or Non-production) cannot be changed after the application is created. Choose carefully during setup.

How long does the access token last?

The Sage Intacct access token expires after 43,200 seconds (12 hours). Use the refresh token to obtain a new access token before it expires.

Sage Intacct REST API Integration Guide (Step-by-Step)

April 13, 2026 8 min read

Sage Intacct cloud ERP with REST API integration connecting CRM, banking, inventory, and eCommerce for unified data flow

Sage Intacct REST API Integration Guide

This article documents the following aspects of Sage Intacct’s REST API integration:

End-to-end integration method
Exact OAuth steps
App creation
Entity-level access
Querying
Posting data
Real-life challenges to consider when building a middleware

Prerequisites for Sage Intacct API Integration

Before starting, ensure you have:

Sage Intacct login with Company Administrator privileges
Access to the Sage Developer Console

How to Integrate with Sage Intacct REST API

To integrate with the Sage Intacct REST API, you need to create an OAuth application, configure redirect URLs, generate client credentials, complete the OAuth authorization flow, and then use the access token to query or post data through Sage Intacct REST endpoints.

At a high level, the integration process includes:

Creating a Sage Developer Console account
Creating a Sage Intacct OAuth application
Configuring redirect URIs and origin domains
Selecting the correct client scope: Production or Non-production
Getting approval from Sage Intacct
Generating the client ID and client secret
Completing the authorization code flow
Storing access and refresh tokens securely
Querying Sage Intacct objects using the /query endpoint
Posting data and mapping API responses back to your source records

This process is important because Sage Intacct REST API integrations often involve company-level access, entity-level access, OAuth token handling, and middleware-side data mapping.

Planning these items early helps avoid issues during production rollout.

Creating an OAuth Application in the Sage Intacct Developer Console

Sage Intacct developer console creating OAuth application with client credentials, redirect URI, and API integration setup

1. Account Setup

Open Developer Console: Go to https://developer.sage.com/intacct. Log in with your developer account (create one if you don’t have one). Select “View Console” and enter your Sage account credentials.
Create a new organization: A Sage Intacct developer organisation allows you to manage client applications, generate API keys, and monitor usage across teams and environments. You can invite other developers and monitor API usage by customer and application.
Create a new Application: From the navigation menu, select Applications > New Application. For “Select an API,” choose Sage Intacct and select Continue.

2. Complete the Application Form

2.1: Provide an Application name. Optionally add a Terms and Conditions URL. Select Continue.

2.2: Configure your API integration settings:

Provide Redirect URIs: full URLs to redirect users after OAuth 2.0 authorization.
Add Origin Domains: full https:// URLs where your application makes browser-based API requests.
The Intacct Web Services License Key (Sender ID) is prepopulated.
Add your Intacct Web Services License Password (Related Sender Password)
From the Client Scope dropdown, choose the environment type:
- Production: For live production companies (up to five production API keys per web services ID)
- Non-production: For sandbox or test environments

Important: You cannot change the client scope after it is created. Choose carefully between Production and Non-production.

Select Create Application.

2.3: Expect confirmation from Sage Intacct. After completing the steps, Sage validates the details and sends a notification email. Once approved, you can access your client ID and client secret.

Security: Store your client_id and client_secret securely in a database or .env file. Never expose them in client-side code. (Best practices for privacy and security, 2026)

Understanding Sage Intacct OAuth Flow

The user signs into your application and clicks a link to authorize access to their Sage Intacct data. Your app constructs an authorization URL.

Authorization Code Request (GET)

Endpoint: https://api.intacct.com/ia/api/v1/oauth2/authorize

Parameter	Value
response_type	`code`
client_id	Your client ID
redirect_uri	Your registered redirect URI
state	Random encrypted value for CSRF protection
scope	`offline_access` (if you need a refresh token)

The user is prompted to grant your application access and log in with their Sage account.

Authorization Redirect Response

The authentication server redirects the user to your callback URI with an authorization code in the query string:

https://your-domain.com/callback?code=<AUTH_CODE>&state=xyz

Validate the state parameter, then exchange the code for tokens.

Access Token Request (POST)

Endpoint: https://api.intacct.com/ia/api/v1/oauth2/token

Parameter	Value
grant_type	`authorization_code`
code	The authorization code received
redirect_uri	Your registered redirect URI
client_id	Your client ID
client_secret	Your client secret

Sample token response:

{
  "token_type": "Bearer",
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "expires_in": 43200
}

Refresh Token Request (POST)

Use when the access_token is expired or nearing expiry. Optionally pass entity_id to obtain a token scoped to a specific entity.

Location (Entity) Access

This is one of the most important parts of the system integration.

Default Behavior

If you do not specify a location (entity), the token belongs to the top-level company. (API Sessions | Sage Intacct Developer, 2023)

When You Request a Token with location_id

Endpoint: https://api.intacct.com/ia/api/v1/oauth2/token

Parameter	Value
grant_type	`refresh_token`
refresh_token	Your refresh token
entity_id	The entity/location ID
client_id	Your client ID
client_secret	Your client secret

You will only get data for that specific entity. The token behaves differently from a top-level token.

Critical OAuth Limitation: If you try to connect the same Sage user account to multiple locations using OAuth, authorizing the second location immediately invalidates the previous refresh token. The first connection stops working.

Solution: Use Different Sage Users Per Location

Create one Sage Intacct user per location, each assigned to its respective entity. Each user maintains its own OAuth session, access token, refresh token, and entity access.

Sage User	Assigned Location
Controller (USA)	E110
Controller (CAN)	E120

With this structure, authorizing one user does NOT invalidate another user’s token. Each location works independently and refresh tokens no longer conflict.

Setting Up Entity-Level Access

You must assign entity access to each user – this is a crucial step often missed:

Sage Intacct: Go to Company → Admin → Users → [User Name] → User entities

Querying Data Using Sage Intacct REST API

List vs query API comparison showing basic fetch, advanced filtering, sorting, pagination, and database query optimization

One of the first surprises when integrating with Sage Intacct is that fetching data is not as straightforward as typical REST APIs.

Default “List” Approach

The default list endpoint returns only minimal fields: id, key, and href.

The Query Approach

Sage provides a flexible /query endpoint using POST.

What You Can Do

Select fields: Request only the fields needed for your sync, including nested fields (e.g., audit.modifiedDateTime)
Filters: $eq, $gt, $lt, $ge, $in — including filtering with audit.modifiedDateTime
Order: Sort by fields like id or audit.modifiedDateTime
Pagination: Using start, pageSize, next, previous parameters
Multi-condition filters: Add multiple filters with filter expressions

Important: Not all fields are queryable and filterable. Use the object model definition to verify which fields support filtering before building your queries.

Posting Data to Sage Intacct API

Sage Intacct does NOT return results mapped by your IDs. It returns results in the same array order you send them. Because Sage does not support custom externalId fields in entities, your middleware must maintain positional mapping.

Sage Bulk Insert Rules

Maximum 500 items per request
If one item fails, others still process
Mixed success/failure responses in one response

Key takeaway: When you send [timesheet1, timesheet2], the response is [result_for_timesheet1, result_for_timesheet2]. Always use an array index to map results back to your source records.

Common Sage Intacct REST API Integration Challenges

While the Sage Intacct REST API is useful for building modern ERP integrations, developers should plan for a few real-world implementation challenges before starting development.

OAuth Token Expiry and Refresh Handling

Sage Intacct access tokens expire after a fixed duration, so your application should not depend on manual reauthorization. Store refresh tokens securely and build logic to refresh the access token before it expires.

This helps prevent sync failures during scheduled jobs or background data transfers.

Entity-Level Access Issues

In multi-entity Sage Intacct environments, token behavior can change depending on whether the token is generated for the top-level company or for a specific entity.

If your integration needs data from multiple locations, define the user and entity-access strategy before development starts.

Queryable and Non-Queryable Fields

Not every Sage Intacct field is available through the /query endpoint. Some fields may require object-specific endpoints or additional API calls.

Before finalizing the sync logic, validate which fields are queryable, filterable, and available in the response.

Partial Success in Bulk Posting

When posting multiple records in one request, some records may succeed while others fail.

Your middleware should track each record position, store the related source record ID, and handle partial success responses properly. This is especially important for invoices, bills, journal entries, timesheets, and other transactional records.

Sandbox and Production Scope Limitations

The client scope selected during application setup cannot be changed later. If you select the wrong scope, you may need to create a new application.

Always confirm whether the application is meant for sandbox testing or production use before creating the Sage Intacct app.

Sage Intacct REST API vs XML API: What Developers Should Know

Sage Intacct supports both REST API and XML API approaches.

The REST API is commonly preferred for modern integrations because it follows familiar HTTP methods, supports OAuth-based authorization, and works well with middleware applications, SaaS platforms, and cloud-based systems.

However, developers should know that the XML API is still widely used in many existing Sage Intacct integrations. In some cases, specific objects, fields, or legacy workflows may still require XML API support.

Because of this, the right approach depends on the integration use case, data objects, authentication requirements, and long-term maintenance plan.

For new integrations, the REST API is usually a better starting point when the required objects and operations are available.

For older implementations or complex accounting workflows, teams may need to evaluate both REST and XML API coverage before finalizing the architecture.

A practical approach is to:

List the Sage Intacct objects required for the integration
Check whether each object and field is available in REST API
Confirm whether the required fields are queryable or filterable
Review posting requirements for transactions
Decide whether REST API alone is enough or whether XML API support is also needed

Conclusion

This article goes over everything you need to know to successfully integrate the Sage Intacct REST API, such as OAuth redirects, app creation, entity-level access, query limits, posting batches, and how to deal with Sage’s real-world quirks.

When connecting Sage Intacct to another system, use this guide as your only source of information.

Sage Intacct API FAQs

How do you integrate with the Sage Intacct REST API?: To integrate with the Sage Intacct REST API, create an OAuth application in the Sage Developer Console, configure redirect URIs and origin domains, select the correct client scope, generate client credentials, complete the OAuth authorization code flow, and store the access and refresh tokens securely. After authentication, use Sage Intacct REST endpoints such as /query to retrieve data and object-specific endpoints to post records.
Does each location need a separate Sage user?: Yes, if you want independent refresh tokens. Using the same user for multiple locations causes token overwrites that break other connections.
Why do we need array-order mapping on create?: Because Sage does not include your external IDs in the response. It returns results in the order you sent them, so your middleware must track position to map results correctly.
Why use both /query and /objects endpoints?: Because query does not return all fields. The /objects/… endpoint is sometimes required for full data retrieval, especially for fields not exposed in the query result.
Can I change the client scope after creating an application?: No. The client scope (Production or Non-production) cannot be changed after the application is created. Choose carefully during setup.
How long does the access token last?: The Sage Intacct access token expires after 43,200 seconds (12 hours). Use the refresh token to obtain a new access token before it expires.