Browse Business Software Categories

Close  

API Management

ERP

IT Management

Acumatica API: Contract-Based REST Endpoints and Integration Setup

Acumatica API: Contract-Based REST Endpoints and Integration Setup

Last updated: November 4, 2026 · Independent guide · We do not sell rankings or coverage.

The Acumatica API is a set of web services that external applications use to read and write ERP data, and for almost every new integration the right choice is the contract-based REST API with OAuth 2.0 authentication. You register the application on the Connected Applications form, call a versioned endpoint such as Default/25.200.001, and stay within your license’s per-minute request limits. The steps below follow the order an administrator and developer would work in.

Contract-based vs screen-based APIs: which one to use

The contract-based API works with business objects such as SalesOrder or Customer that do not depend on a particular form. Acumatica’s Integration Development Guide says each contract “is fixed and does not change based on system customization,” and that you can keep using the same system endpoint in future versions (Acumatica Integration Development Guide, 2020 R2 edition, no date shown). Contract versions 2 and 3 support SOAP and REST, while contract version 4 is REST only.

The screen-based API is a SOAP interface that mirrors a user’s commands on a form. Because element names follow form field names, “any changes made to the UI after the application is created require the application to be updated and recompiled,” according to the documentation for the screen-based API wrapper (Screen-Based API Wrapper, no date shown). A wrapper library, PX.Soap.dll, reduces that breakage.

A third interface, OData, serves reporting reads over generic inquiries and data access classes (Acumatica blog, August 20, 2025).

Interface Protocol Tied to Best use
Contract-based API REST (SOAP on older contract versions) A versioned endpoint contract New integrations, create and update records, run actions
Screen-based API SOAP Individual forms and their UI elements Legacy integrations or form logic the contract does not expose
OData OData over HTTP Generic inquiries and data access classes Reporting and BI extracts

Before you start

Step 1: Check your API limits

Open License Monitoring Console (SM604000) and review the License and Constraints tab. It shows three values that govern every integration: Maximum Number of Web Services API Users, Maximum Number of Concurrent Web Services API Requests, and Maximum Number of Web Services API Requests per Minute, which includes sign-in and sign-out calls (License Monitoring Console, no date shown).

Step 2: Create a dedicated integration user

Create a separate account for each integration on Users (SM201010), and assign only the roles it needs on the Roles tab. Its Max. Number of Concurrent Logins setting defaults to three (Users (SM201010), no date shown).

On User Types (EP202500), the Allowed Login Type setting offers UI, API or Unrestricted. API allows sign-in only through the web services Login method, while Unrestricted, the default, also covers OAuth 2.0 (User Types, no date shown). Test the login type with OAuth in a sandbox before restricting a production user.

Step 3: Register the connected application

  1. Open Connected Applications (SM303010).
  2. In the Summary area, enter a Client Name and select a Flow. The form offers Authorization Code, Implicit, Resource Owner Password Credentials and Hybrid (Connected Applications, no date shown).
  3. On the Secrets tab, click Add Shared Secret, enter a description and copy the value. The value is displayed only once.
  4. For Authorization Code, Implicit or Hybrid flows, add an absolute redirect URI on the Redirect URIs tab.
  5. Set the Refresh Tokens mode. Absolute Expiration defaults to 30 days; Sliding Expiration defaults to 90 days absolute and 15 days sliding, with an Infinite option.
  6. Click Save. The generated Client ID ends in @ and the tenant name.

Use Authorization Code when a person approves access, such as a SaaS product connecting to a customer instance, and Resource Owner Password Credentials for a server job running as the Step 2 user.

Step 4: Pick the endpoint and version

Every contract-based URL follows the pattern https://<instance>/entity/<EndpointName>/<Version>/<Entity>. The version decides which entities, actions and fields you can use (Endpoints and Contracts, no date shown). Use the system endpoint, Default, when its contract is enough; obsolete system endpoints may be removed in later versions.

Open Web Service Endpoints (SM207060) to browse each version, or click OpenAPI 3.0 to open its swagger.json schema (Web Service Endpoints, no date shown). Store the version as configuration, because new versions deprecate fields: Default/24.200.001, for example, recommends StockItem.LastModifiedDateTime in place of StockItem.LastModified, which will be removed in a future endpoint version (Web Services: New System Endpoint, no date shown).

Step 5: Extend the endpoint if a field is missing

You cannot edit the Default contract. To add a custom field or entity, extend it:

  1. On Web Service Endpoints (SM207060), select the base endpoint in Endpoint Name and Endpoint Version.
  2. Click Extend Endpoint. In the Extend Current Endpoint dialog, enter a new endpoint name and version, then click OK.
  3. Select the inherited entity in the left pane, click Extend Entity on the Fields tab, and use Populate or Add Row to add fields.
  4. Click Save, then click Validate Endpoint to check element names and mappings (Web Service Endpoints, no date shown).

Source: To Extend an Existing Endpoint, no date shown. An extension keeps the base contract version, and you cannot rename or retype inherited elements. A custom endpoint built from scratch uses the latest contract version and holds the elements you add to it (Custom Endpoints and Endpoint Extensions, no date shown). Package it in a customization project so it moves with your other changes. Our guide to ERP customization vs configuration explains why that matters at upgrade time.

Step 6: Get a token and send your first request

For a server job, POST to https://<instance>/identity/connect/token as application/x-www-form-urlencoded with grant_type=password, client_id, client_secret, username, password and scope=api offline_access (Resource Owner Password Credentials Flow: Obtaining of an Access Token, no date shown). The api scope covers REST, screen-based SOAP and OData, and offline_access returns a refresh token. The documented response returns a Bearer token with expires_in of 3600 seconds.

This illustrative request creates a customer with PUT, following the vendor’s Create a Record example (Create a Record, no date shown).

PUT https://yourcompany.acumatica.com/entity/Default/25.200.001/Customer
Authorization: Bearer <access_token>
Accept: application/json
Content-Type: application/json

{
  "CustomerID": { "value": "JOHNGOOD" },
  "CustomerName": { "value": "John Good" },
  "CustomerClass": { "value": "DEFAULT" },
  "MainContact": {
    "Email": { "value": "[email protected]" }
  }
}

Status 200 returns the record, 401 means not signed in, 403 means missing rights to the matching form, 422 carries validation errors, and 429 means the license request limit was exceeded.

Step 7: Sign out and monitor

When a job finishes, send POST https://<instance>/entity/auth/logout with your Authorization header; a 204 confirms the session closed (Sign Out from the Service, no date shown). If sign-out fails and you reach the concurrent session limit, you cannot force the API user’s sessions closed; they expire after a 10-minute timeout. After go-live, click Refresh Statistics on the Statistics tab of License Monitoring Console (SM604000) to see delayed and declined requests.

Licensing limits on API calls

The April 2026 licensing guide sets these base web API limits per product tier:

Product Requests per minute Max queue (concurrency) Simultaneous requests (parallelism)
Essentials 50 5 1
Select 100 10 2
Prime 150 20 3
Enterprise 300 40 8

Source: Acumatica Licensing Guide, April 2026. SaaS Reserved Resources raise these limits; Enterprise Premium allows 600 requests per minute. API connections are counted separately from named users, and applications that fail to log out keep holding a connection.

Once requests in the past minute reach 50% of the per-minute limit, new requests are delayed, and requests are declined only when more than 20 are queued or one has waited over 10 minutes (License Restrictions for API Users, no date shown). As an illustration, a Select tenant slows after about 50 calls in a minute, shared by every connected app. Daily import volume and commercial transaction tiers are separate limits; see our NetSuite vs Acumatica comparison for how that resource-based model differs from per-user licensing.

Common mistakes and how to fix them

  • Losing the client secret. The value cannot be retrieved later. Add a new shared secret on the Secrets tab and update your application.
  • Sign-in errors after a few runs. Sessions were not closed. Call logout in a finally block and wait out the 10-minute timeout.
  • Requests that suddenly slow down. You crossed the 50% threshold. Filter reads on LastModifiedDateTime and spread jobs out.
  • 403 on a record you can see in the UI. Add the role for that form on Users (SM201010).
  • Fields disappear after an upgrade. You target a deprecated field. Compare versions on Web Service Endpoints and switch.
  • Custom field missing from the response. Extend the endpoint (Step 5).

Limitations of the native API

The native API gives raw access; you build retries, mapping, error queues and logging yourself. Per-minute limits are shared across every connected app on the tenant, so a busy eCommerce connector can slow your custom job. Each customer instance may run a different endpoint version, so software vendors must track schema per customer. Change detection needs filtered reads of data changed since the last sync, or push notifications configured on the Push Notifications (SM302000) form (Acumatica blog, August 20, 2025).

When companies add a third-party tool

Teams add a third-party tool when they connect several systems, want monitoring built in, or sell software to many Acumatica customers. Apideck, which sells a unified accounting API, documents an Authorization Code connection through Connected Applications (Apideck connector docs, no date shown). CData, which sells drivers and cloud connectors, publishes OAuth app setup for its Acumatica drivers (CData Creating a Custom OAuth App, no date shown). Both still consume your tenant’s API limits. For broader design choices, see our guide to ERP data integration.

How we researched this

We read the top-ranking pages for “acumatica api” in November 2026, including articles from Apideck, Paystand and Acumatica’s own blog. We checked each step against vendor documentation: Acumatica’s April 2026 licensing guide, its 2020 R2 Integration Development Guide, and the current Integration Development Guide and form reference published by MYOB for MYOB Acumatica. MYOB Acumatica runs on the Acumatica platform, but release timing can differ, and we did not test against a live tenant, so confirm form IDs and endpoint versions in your own instance.

Related guides

Frequently asked questions

Should I use the contract-based or screen-based Acumatica API?

Use the contract-based API for new work. Its contracts do not change when the system is customized, while the screen-based SOAP API depends on form layouts and breaks when they change.

How do I get an Acumatica API client ID and secret?

Register your application on the Connected Applications (SM303010) form, add a shared secret on the Secrets tab and save. The client ID is generated on save and ends with the tenant name. Copy the secret immediately, because it is displayed only once.

How many API calls can Acumatica handle per minute?

The April 2026 licensing guide sets 50 requests per minute for Essentials, 100 for Select, 150 for Prime and 300 for Enterprise. Requests are delayed once you reach half that limit.

How long does an Acumatica access token last?

The documented token response shows expires_in of 3600 seconds, or one hour. Request offline_access for a refresh token, whose chain expires after 30 days by default.

Sources

  • Acumatica, Licensing Guide, April 2026. acumatica.com
  • Acumatica, Integration Development Guide, 2020 R2 edition, no date shown. acumatica.com
  • Acumatica blog, Unlocking Acumatica Web Services: REST API, OData, and Integration Best Practices, August 20, 2025. acumatica.com
  • MYOB Acumatica Integration Development Guide, Endpoints and Contracts, no date shown. help.myob.com.au
  • MYOB Acumatica Integration Development Guide, Custom Endpoints and Endpoint Extensions, no date shown. help.myob.com.au
  • MYOB Acumatica Integration Development Guide, To Extend an Existing Endpoint, no date shown. help.myob.com.au
  • MYOB Acumatica Integration Development Guide, Screen-Based API Wrapper, no date shown. help.myob.com.au
  • MYOB Acumatica Integration Development Guide, Registration of an OAuth 2.0 or OIDC Application, no date shown. help.myob.com.au
  • MYOB Acumatica Integration Development Guide, Resource Owner Password Credentials Flow: Obtaining of an Access Token, no date shown. help.myob.com.au
  • MYOB Acumatica Integration Development Guide, Create a Record, no date shown. help.myob.com.au
  • MYOB Acumatica Integration Development Guide, Sign Out from the Service, no date shown. help.myob.com.au
  • MYOB Acumatica Integration Development Guide, License Restrictions for API Users, no date shown. help.myob.com.au
  • MYOB Acumatica Release Notes, Web Services: New System Endpoint, no date shown. help.myob.com.au
  • MYOB Acumatica User Guide, Connected Applications (SM303010), no date shown. help.myob.com.au
  • MYOB Acumatica User Guide, Web Service Endpoints (SM207060), no date shown. help.myob.com.au
  • MYOB Acumatica User Guide, License Monitoring Console (SM604000), no date shown. help.myob.com.au
  • MYOB Acumatica User Guide, Users (SM201010), no date shown. help.myob.com.au
  • MYOB Acumatica User Guide, User Types (EP202500), no date shown. help.myob.com.au
  • Apideck (sells a unified accounting API), Acumatica connector OAuth credentials, no date shown. developers.apideck.com
  • Apideck (sells a unified accounting API), How to integrate with the Acumatica API, October 18, 2026. apideck.com
  • CData (sells data connectivity drivers), Creating a Custom OAuth App, no date shown. cdn.cdata.com

Sherman Hsieh

CEO & Editor-in-Chief, Business-Software.com
Independent analysis of enterprise software — ERP, CRM and more
Sherman Hsieh is the founder, CEO, and editor-in-chief of Business-Software.com. He leads the site's independent, buyer-focused coverage of ERP, CRM, and other business systems, including vendor-neutral comparisons, pricing analysis, and implementation guidance. Before founding Business-Software.com, Sherman was an executive at Siebel ...