# Acumatica REST API URL Builder

> Source: https://netray.co/tools/acumatica-rest-api-url-builder
> Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems.
> Section: Free Tools

## Short answer

Generate contract-based REST URLs and the login call for any Acumatica entity, with $filter, $select, $expand, $top and $skip filled in for you.

## Category

developer

## Erp

Acumatica

## Audience

- ERP developer
- Integration engineer
- Acumatica consultant

## Tool

**Kind:** template

**Output:** code

**Language:** http

**Fields:**

#### Instance base URL

**Key:** base

**Type:** text

**Default:** https://mycompany.acumatica.com

**Help:** No trailing slash. Include the virtual directory for on-premise installs.

#### Endpoint name

**Key:** endpoint

**Type:** text

**Default:** Default

#### Endpoint version

**Key:** version

**Type:** text

**Default:** 24.200.001

**Help:** Check the Web Service Endpoints screen (SM207060) for versions on your tenant.

#### Entity

**Key:** entity

**Type:** text

**Default:** StockItem

#### $filter expression

**Key:** filter

**Type:** text

**Default:** ItemStatus eq 'Active'

#### $select fields

**Key:** select

**Type:** text

**Default:** InventoryID,Description,ItemClass,DefaultPrice

#### $expand detail

**Key:** expand

**Type:** text

**Placeholder:** WarehouseDetails

#### $top (page size)

**Key:** top

**Type:** number

**Default:** 100

#### $skip (offset)

**Key:** skip

**Type:** number

**Default:** 0

#### Tenant name

**Key:** tenant

**Type:** text

**Default:** Company

#### API user name

**Key:** user

**Type:** text

**Default:** apiuser

**Blocks:**

#### 1. Login (store the session cookie)

**Body:** POST {{base}}/entity/auth/login
Content-Type: application/json

{
  "name": "{{user}}",
  "password": "<password>",
  "tenant": "{{tenant}}"
}

#### 2. Read records

**Body:** GET {{base}}/entity/{{endpoint}}/{{version}}/{{entity}}?$filter={{filter}}&$select={{select}}&$expand={{expand}}&$top={{top}}&$skip={{skip}}
Accept: application/json

#### 3. Read one record by key

**Body:** GET {{base}}/entity/{{endpoint}}/{{version}}/{{entity}}/<key value>?$select={{select}}
Accept: application/json

#### 4. Create or update (PUT)

**Body:** PUT {{base}}/entity/{{endpoint}}/{{version}}/{{entity}}
Content-Type: application/json

{
  "InventoryID": { "value": "WIDGET-100" },
  "Description": { "value": "Widget, anodized" }
}

#### 5. Logout (release the API login slot)

**Body:** POST {{base}}/entity/auth/logout

**Notes:** Remove the $expand parameter if you leave it blank. Field names and values in the PUT body are Acumatica contract names and must match your endpoint version. Acumatica limits concurrent API logins per license, so always log out. Verify against your version of the Web Service Endpoints.

## Content

**Intro:** Acumatica exposes ERP data through a contract-based REST API where every call is a URL made of the instance, an endpoint, a version and an entity. This builder assembles that URL, the OData-style query options and the login and logout calls so you can paste them straight into Postman or code.

**Sections:**

#### How to use the builder

**Body:** Enter your instance base URL, the endpoint name and version, and the entity you want such as StockItem, SalesOrder or Customer. Add a filter, the fields you need and a page size. The output shows login, read, single-record read, create or update, and logout. Copy the blocks into your REST client, replace the password placeholder and run the login first. Acumatica returns a session cookie that every later call must send.

**Bullets:**

- Always login, call, then logout in one script
- Use $select to cut payload size on wide entities
- Page with $top and $skip instead of one huge pull
- Use the Default endpoint for standard entities, a custom endpoint for your own

#### How the URL is structured

**Body:** The path pattern is /entity/{endpoint}/{version}/{entity}. The Default endpoint ships with Acumatica and covers customers, vendors, stock items, sales orders and many more. The version string follows the release, for example 24.200.001 for a 2024 R2 style build. Query options follow OData conventions: $filter uses operators such as eq, ne, gt and lt, strings use single quotes, and $expand pulls detail collections like warehouse details or order lines in the same call.

#### Reading the result and paging

**Body:** A GET returns a JSON array where every field is an object with a value property, for example the InventoryID is returned as an object holding the actual string. Plan your parsing for that. For large tables, loop with $top set to a few hundred and increase $skip by the same amount until a page comes back short. Acumatica can also time out very large reads, so prefer narrow filters such as a last modified date.

#### Common mistakes

**Body:** Most failures come from small details: forgetting to log out so the license slot stays occupied, using double quotes inside a filter, sending the wrong tenant name, or calling an entity that is not in the chosen endpoint version. A 500 response on a PUT usually means a required field or a key mismatch rather than a bad URL. Test reads first, then writes in a sandbox tenant.

**Cta:** If you are wiring Acumatica to MES, quality or reporting systems, we can build and test those integrations with your team, including read-only AI queries over the data.

**Faq:**

#### What is the Acumatica contract-based REST API?

**Answer:** It is a versioned web service where each endpoint defines a set of entities such as customers or sales orders with stable field names. Because the contract is versioned, your integration does not break when the underlying screens change between releases.

#### How do I authenticate to Acumatica REST?

**Answer:** You can post name, password and tenant to the auth login URL and reuse the session cookie, or use OAuth 2.0 with a connected application. The cookie method is simplest for scripts. Always call logout when finished to free the login.

#### Why does my $filter return nothing?

**Answer:** Check that field names match the contract exactly, string values use single quotes, and dates follow the datetimeoffset format. Also confirm the user has rights to the data. A silent empty result often means a misspelled field or a restrictive role.

#### Can I use this for custom fields?

**Answer:** Yes, but custom fields appear in the REST contract only after you add them to a custom endpoint or through the custom field mapping on the Default endpoint. Use the Web Service Endpoints screen to expose them, then reference them by the name you mapped.

## Search terms

acumatica rest api url, acumatica contract based api, acumatica odata filter example, acumatica rest api login, acumatica stockitem api, acumatica api expand, acumatica api paging top skip, acumatica integration url builder

---
Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json