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 6 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

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.

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

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.