Acumatica API Integration: A Practical Guide

The contract-based REST API

The contract-based REST API is the endpoint most integrations target. Each request hits a URL shaped like /entity/Default/{version}/{Entity}, where Default is the endpoint name, {version} pins the contract version, and {Entity} is a top-level record type such as Customer, SalesOrder, or StockItem. Standard HTTP verbs map to operations: GET reads, PUT creates or updates, POST runs actions, and DELETE removes records.

Because the API is contract-based, the fields you get back match the entity definition in the endpoint rather than the raw database columns. That keeps an integration stable when Acumatica changes its schema underneath, but it also means the shape of every response is defined by the endpoint version you call, so pinning that version matters.

Extending the default endpoint

The stock Default endpoint covers common entities, but real projects usually need fields or screens it does not expose. You extend it by creating a custom web service endpoint in the Acumatica UI, mapping the screen fields you need to a named entity. That gives you a versioned contract you control, but every new field, linked entity, or detail line becomes manual mapping work you own and maintain as the business changes.

PUT /entity/Default/24.200.001/Customer HTTP/1.1
Host: your-instance.acumatica.com
Cookie: .ASPXAUTH=...
Content-Type: application/json

{
  "CustomerID":   { "value": "C000042" },
  "CustomerName": { "value": "Acme Robotics" },
  "Email":        { "value": "ap@acme.example" }
}

OData feeds and import scenarios

Not every integration needs write access. For reporting and read-heavy pulls, Acumatica exposes OData feeds built from Generic Inquiries. You point a BI tool or a script at the OData URL, filter with standard query options, and pull tabular results. OData is read-only and shaped by the inquiry, so it is a clean fit for dashboards but not for pushing records back into Acumatica.

Import and export scenarios

Import scenarios and export scenarios live inside Acumatica itself. You define a data provider (a CSV file, an Excel sheet, or another table), map its columns to a target screen, and run the scenario to load records through the same business logic the UI uses. They are useful for one-off migrations and scheduled batch loads, but they run on a schedule or a manual trigger, not continuously, and they are not a substitute for a live API integration keeping two systems in agreement.

Where EDI fits

Acumatica EDI integration is usually a layer on top of these same surfaces. A trading-partner platform or middleware translates X12 or EDIFACT documents (850 purchase orders, 810 invoices, 856 advance ship notices) into REST calls or import scenarios that create sales orders, shipments, and invoices in Acumatica. The API does the writing; the EDI layer handles the document format and partner routing. If your requirement is document exchange with retailers or logistics partners, plan for that translation step rather than expecting the REST API to speak EDI directly.

Authenticating with the Acumatica API

Acumatica supports two auth paths. The modern route is OAuth 2.0: you register a connected application in the instance, receive a client ID and secret, and run the authorization-code or resource-owner flow to get an access token and a refresh token. The older route is cookie-based login: you POST credentials to /entity/auth/login, receive a session cookie, reuse it on every call, and POST to /entity/auth/logout when you finish so you do not exhaust the license's session pool.

Whichever path you pick, token and session lifecycle is your problem. OAuth access tokens expire and need refresh logic; cookie sessions count against concurrent-session limits and have to be released. Getting this wrong shows up as intermittent 401s under load, which is one of the first pieces of plumbing every hand-built Acumatica integration has to solve before it can be trusted in production.

Rate limits, pagination, and push notifications

Acumatica meters API usage through license-based limits on concurrent API users and requests, so a naive integration that opens a connection per record will hit a wall. Reads that return large sets need pagination: use $top, $skip, and $filter on the query, and page in stable order so you do not miss or double-count rows. Writes need idempotency and retry-with-backoff, because a timed-out PUT may still have committed on the server.

Push notifications for event-driven reads

To avoid polling, Acumatica offers push notifications driven by business events. You define a condition on a screen (an order reaching a status, a customer being created), and Acumatica posts a payload to a webhook endpoint you host. That gets you event-driven updates, but you still own the receiver: verifying the payload, de-duplicating, ordering, and writing the change into the other system, plus handling the case where your endpoint is down when the event fires and the notification has to be replayed.

Build on the Acumatica API yourself vs managed two-way sync

Every capability above is reachable, and for a single one-way feed it is reasonable to write it yourself. The cost shows up when you need two systems to agree continuously. Now you are maintaining auth refresh, pagination, retries, field mapping in both directions, conflict handling when the same record changes on both sides, and a way to replay events you missed during an outage. That is a standing engineering commitment, not a one-time script, and it competes with your team's roadmap every quarter.

The subtle failures are the expensive ones. A record updated in both Acumatica and the other system within the same window needs a deterministic rule for which write wins, or the two copies quietly drift apart. A webhook that arrives out of order can overwrite a newer value with an older one. A schema change on either side breaks a mapping that no test covered. None of these are exotic; they are the day-two reality of any bidirectional integration, and they are why sync is usually cheaper to buy than to keep.

Conclusion

Acumatica gives you a capable contract-based REST API, OData for reporting, import scenarios for batch loads, and business-event push notifications for events. All of it is usable directly, and for a single feed that is the right call. For keeping Acumatica and another system continuously in agreement, the maintenance cost of doing it by hand is the real number to weigh.

If you would rather skip the plumbing, book a demo or explore the Acumatica connector to see managed real-time two-way sync running on the Acumatica API.