What we do
Tools
Industries
Department
How we workLet's talk →
Home/Acumatica/Acumatica API Calls That Survive an Upgrade
Acumatica

Acumatica API Work Starts With Picking an Endpoint Version

You've got an Acumatica URL, a user and a list of records another system needs. Before the first request, there are two choices: which endpoint version you build against, and whether you sign in with a session cookie or OAuth. Get those right and the API behaves the same way your staff's screens do, validations and all.

The shape of a first call

URL: https://<your-instance>/entity/Default/<version>/<Entity>, for example .../entity/Default/24.200.001/SalesOrder. The version names the endpoint release, not your Acumatica build.

Sign in with a session: POST your username, password and tenant (company) to /entity/auth/login, reuse the cookie, and POST to /entity/auth/logout when the job ends.

Or OAuth 2.0: register a client on the Connected Applications screen and request tokens from /identity/connect/token. Better for anything running unattended.

Limits come from your license: it caps how many API requests run at once and how many arrive per minute. The License Monitoring Console shows where you stand.

Reading and writing a sales order, end to end

  1. 1

    Pick the endpoint and version

    Each release ships a new version of the Default endpoint, listed on the Web Service Endpoints screen. Pin your code to one version so an upgrade doesn't change the fields under you, and move to a newer one on purpose.

    Watch for: fields your business added. If they aren't on the Default endpoint, extend it into your own endpoint here rather than reaching around it.

  2. 2

    Sign in

    For a quick test, the cookie login is fine. For a service, use an OAuth client so there's no password sitting in a config file.

  3. 3

    Read with filters, not full pulls

    GET the entity with $filter, $select and $expand (for detail lines). Pulling every record every time is the fastest way to hit the per-minute limit.

  4. 4

    Write through the same entity

    PUT a JSON body to create or update a record. Acumatica runs the same business logic a person would trigger on the screen, so a missing required field fails exactly as it would in the UI.

    Watch for: actions such as releasing a document. Those are separate calls on the entity, not a field you set.

  5. 5

    Log out

    If you used a session, end it. Sessions left open count against your license and are the usual cause of the "API Login Limit" error.

Four ways into Acumatica, and the job each one suits

Interface Use it for Watch for
Contract-based REST API New integrations that read and write orders, customers, inventory and financial records. Pin the endpoint version, and extend the endpoint for custom fields.
Generic inquiries over OData Reporting and BI tools that need data shaped by an inquiry you've already built. Read-only. Writes still go through the REST API.
Push notifications Telling another system the moment records change, by sending the changes to a webhook URL. Built on an inquiry or query you define, so the definition decides what fires.
SOAP (contract-based or screen-based) Existing integrations written before REST became the default. The screen-based API is tied to screen layouts, which is why older syncs break on upgrades.

What makes an Acumatica integration fall over after an upgrade

Code written against "whatever the current endpoint is"

How you'll know: A field goes missing or renamed the week after an upgrade.

Fix: Pin a version in the URL and test the next one before switching. Acumatica ships two major releases a year, so plan for this twice a year.

Sessions nobody closes

How you'll know: Jobs fail with "API Login Limit" while the system is quiet.

Fix: Log out at the end of every run, reuse one session for a batch, or move to OAuth.

Polling to find out what changed

How you'll know: A sync queries every order every few minutes and the per-minute limit starts biting during the day.

Fix: Define a push notification on the records you care about and let Acumatica send the change.

A screen-based SOAP sync nobody wants to touch

How you'll know: It times out at month-end volume and breaks when a screen changes.

Fix: Rebuild it on the contract-based REST API, against a pinned endpoint version.

Let's talk

An Acumatica integration that survives the next release

n-frames builds Acumatica integrations on the contract-based REST API: a pinned endpoint extended for your custom fields, OAuth or sessions that close properly, and push notifications where polling used to be. Older SOAP syncs get rebuilt the same way.

Pin the endpoint, then build →

Questions people ask

Does Acumatica have an API?

Several ways in, in fact. The main one is the contract-based REST API, organized into versioned endpoints. There's also a SOAP version of the contract-based API, the older screen-based SOAP API, OData for generic inquiries, and push notifications for sending changes out.

Do I need a developer to use Acumatica's API?

For anything past a one-off data pull, yes. Choosing and extending endpoints, handling sign-in and limits, and making sure each call triggers the right business logic is development work. That's the work n-frames takes on for Acumatica customers.

Is Acumatica's API included, or does it cost extra?

API access comes with the platform rather than as a separate product. What varies is capacity: your license sets how many requests can run at once and per minute, so a heavy integration can need a bigger allocation.

What's the difference between Acumatica's REST and SOAP APIs?

The contract-based API comes in REST and SOAP forms with the same versioned endpoints, and REST is where new work goes. The older screen-based API is SOAP only and mirrors screen layouts, which makes it fragile across upgrades.

Why does my Acumatica integration get an "API Login Limit" error?

Too many open API sessions for your license, usually because a job signs in and never signs out. Log out after each run or switch the integration to OAuth.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.