Skip to main content

Acumatica

A generic wrapper over Acumatica's contract-based REST API: agents discover what entities and actions your instance exposes, then read, upsert, attach, and act on any of them — sales orders, customers, invoices, or your own customizations — without a per-entity tool.

Every tool on this page requires an Acumatica connector (see Connectors); pass its ID as connectorId.

Unlike most connectors, these tools aren't hard-coded to specific objects. Acumatica publishes its API as endpoints (named contract versions like Default 24.200.001) containing entities (SalesOrder, Customer, Bill, ...), and every tool takes the same addressing trio: endpointName (defaults to "Default"), endpointVersion, and entityName. The intended flow is discovery first: ACUMATICA_GET_ENTITIES to see what exists, ACUMATICA_GET_ENTITY_SCHEMA to learn an entity's exact field names and shapes, then the read/write/action tools. Record payloads use Acumatica's value-wrapper format — {"OrderType": {"value": "SO"}} — which the schema tool's output demonstrates.

Get entities TOOLACUMATICA_GET_ENTITIES​

Lists every entity exposed by an endpoint, parsed from the endpoint's swagger definition. This is the starting point when an agent doesn't yet know what the instance calls something — run it once, then drill into a specific entity with the schema tool.

Example​

Tool config
{
  "toolType": "ACUMATICA_GET_ENTITIES",
  "connectorId": "V1StGXR8Z5",
  "endpointVersion": "24.200.001"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    endpointVersion
    Type
    string
    Description
    Required: API version (e.g., "24.200.001")

Get entity schema TOOLACUMATICA_GET_ENTITY_SCHEMA​

Returns an LLM-friendly template of an entity's fields, built from Acumatica's ad-hoc schema plus (by default) a sample record for realistic example values. Deeply nested structures are truncated at maxDepth with a hint telling the agent to re-run with focusPath (e.g. "Details.Allocations") to go deeper. Always consult this before ACUMATICA_UPSERT_RECORD — field names are instance-specific and case-sensitive.

Example​

Tool config
{
  "toolType": "ACUMATICA_GET_ENTITY_SCHEMA",
  "connectorId": "V1StGXR8Z5",
  "entityName": "SalesOrder",
  "endpointVersion": "24.200.001",
  "maxDepth": 3
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    entityName
    Type
    string
    Description
    Required: Name of the entity (e.g., "SalesOrder", "Customer")
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    endpointVersion
    Type
    string
    Description
    Required: API version (e.g., "24.200.001")
  • Name
    includeSampleData
    Type
    boolean · optional
    Description
    Optional: Fetch sample record for examples (default: true)
  • Name
    maxDepth
    Type
    integer · optional
    Description
    Optional: Max nesting depth for schema output (default: 3)
  • Name
    focusPath
    Type
    string · optional
    Description
    Optional: Drill down into nested path (e.g., "Details.Allocations")

Get records TOOLACUMATICA_GET_RECORD​

Queries an entity with the standard OData toolkit: filter (e.g. "CustomerID eq 'CUST001' and Status eq 'Open'"), select to limit fields, expand to include nested detail entities, orderBy, and top/skip pagination (default 10 records). Errors come back with suggestions that steer the agent toward the schema tool when a field name is wrong.

Example​

Tool config
{
  "toolType": "ACUMATICA_GET_RECORD",
  "connectorId": "V1StGXR8Z5",
  "entityName": "SalesOrder",
  "endpointVersion": "24.200.001",
  "filter": "CustomerID eq '@@{CUSTOMER_ID}' and Status eq 'Open'",
  "select": "OrderNbr,CustomerID,OrderTotal,Status",
  "orderBy": "OrderNbr desc",
  "top": 10
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    entityName
    Type
    string
    Description
    Required: Name of the entity (e.g., "SalesOrder", "Customer")
  • Name
    endpointVersion
    Type
    string
    Description
    Required: API version (e.g., "24.200.001")
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    filter
    Type
    string · optional
    Description
    Optional: OData filter (e.g., "CustomerID eq 'CUST001' and Status eq 'Open'")
  • Name
    select
    Type
    string · optional
    Description
    Optional: Fields to return (e.g., "OrderNbr,CustomerID,OrderTotal")
  • Name
    expand
    Type
    string · optional
    Description
    Optional: Nested entities to expand (e.g., "Details,Payments")
  • Name
    orderBy
    Type
    string · optional
    Description
    Optional: Sort order (e.g., "OrderNbr desc" or "Date asc,CustomerID asc")
  • Name
    top
    Type
    integer · optional
    Description
    Optional: Max records to return (default: 10)
  • Name
    skip
    Type
    integer · optional
    Description
    Optional: Records to skip for pagination

Upsert a record TOOLACUMATICA_UPSERT_RECORD​

Creates or updates a record using Acumatica's PUT semantics: if the key fields in record match an existing record it's updated, otherwise a new one is created. record is a JSON string in Acumatica's value-wrapper format and supports @@{variable} replacement inside the string. Get the field names right with ACUMATICA_GET_ENTITY_SCHEMA first — validation errors return targeted suggestions so the agent can self-correct.

Example​

Tool config
{
  "toolType": "ACUMATICA_UPSERT_RECORD",
  "connectorId": "V1StGXR8Z5",
  "entityName": "Customer",
  "endpointVersion": "24.200.001",
  "record": "{\"CustomerID\": {\"value\": \"@@{CUSTOMER_ID}\"}, \"CustomerName\": {\"value\": \"@@{CUSTOMER_NAME}\"}, \"CustomerClass\": {\"value\": \"DEFAULT\"}}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    entityName
    Type
    string
    Description
    Required: Name of the entity (e.g., "SalesOrder", "Customer")
  • Name
    endpointVersion
    Type
    string
    Description
    Required: API version (e.g., "24.200.001")
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    record
    Type
    string
    Description
    Required: JSON string of record data (supports @@{var} replacement)

Get attachments TOOLACUMATICA_GET_ATTACHMENTS​

Lists the files attached to a specific record. keyId is the record's key values joined with / — "SO/000123" for a sales order (order type then number), "Normal/000029" for a bill. Returns filenames the agent can pass to ACUMATICA_DOWNLOAD_ATTACHMENT.

Example​

Tool config
{
  "toolType": "ACUMATICA_GET_ATTACHMENTS",
  "connectorId": "V1StGXR8Z5",
  "entityName": "SalesOrder",
  "endpointVersion": "24.200.001",
  "keyId": "SO/@@{ORDER_NUMBER}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    entityName
    Type
    string
    Description
    Required: Name of the entity (e.g., "SalesOrder", "PurchaseOrder")
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    endpointVersion
    Type
    string
    Description
    Required: API version (e.g., "24.200.001")
  • Name
    keyId
    Type
    string
    Description
    Required: Entity key values (e.g., "SO/000123" or "Normal/000029")

Download an attachment TOOLACUMATICA_DOWNLOAD_ATTACHMENT​

Downloads one attachment from a record and extracts its content so the agent can read it — a PDF invoice or a spec sheet becomes text the model can work with. filename must match the attachment exactly (case-sensitive), so list attachments first with ACUMATICA_GET_ATTACHMENTS.

Example​

Tool config
{
  "toolType": "ACUMATICA_DOWNLOAD_ATTACHMENT",
  "connectorId": "V1StGXR8Z5",
  "entityName": "SalesOrder",
  "endpointVersion": "24.200.001",
  "keyId": "SO/@@{ORDER_NUMBER}",
  "filename": "@@{ATTACHMENT_FILENAME}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    entityName
    Type
    string
    Description
    Required: Name of the entity (e.g., "SalesOrder", "PurchaseOrder")
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    endpointVersion
    Type
    string
    Description
    Required: API version (e.g., "24.200.001")
  • Name
    keyId
    Type
    string
    Description
    Required: Entity key values (e.g., "SO/000123" or "Normal/000029")
  • Name
    filename
    Type
    string
    Description
    Required: Exact filename to download (case-sensitive)

Get actions TOOLACUMATICA_GET_ACTIONS​

Discovers the business actions an endpoint exposes — release, confirm shipment, email invoice, and so on — parsed from the endpoint's swagger definition. Filter to one entity with entityName, or match action names with the case-insensitive filter. Run this before ACUMATICA_INVOKE_ACTION to get the exact action name and its parameters.

Example​

Tool config
{
  "toolType": "ACUMATICA_GET_ACTIONS",
  "connectorId": "V1StGXR8Z5",
  "entityName": "SalesOrder",
  "endpointVersion": "24.200.001"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    entityName
    Type
    string · optional
    Description
    Optional: Filter to actions for specific entity only
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    endpointVersion
    Type
    string
    Description
    Required: API version (e.g., "24.200.001")
  • Name
    filter
    Type
    string · optional
    Description
    Optional: Filter action names (case-insensitive contains match)

Invoke an action TOOLACUMATICA_INVOKE_ACTION​

Executes a business action against a record — the write-side of ERP workflows, like ReleaseSalesOrder. entity is a JSON string holding the record's key fields in value-wrapper format, and parameters carries any action parameters the same way. Long-running actions are polled automatically for up to 10 seconds; if the action is still in progress the response returns status: "PENDING" with an operationUrl for ACUMATICA_GET_ACTION_STATUS to poll later.

Example​

Tool config
{
  "toolType": "ACUMATICA_INVOKE_ACTION",
  "connectorId": "V1StGXR8Z5",
  "entityName": "SalesOrder",
  "actionName": "ReleaseSalesOrder",
  "endpointVersion": "24.200.001",
  "entity": "{\"OrderType\": {\"value\": \"SO\"}, \"OrderNbr\": {\"value\": \"@@{ORDER_NUMBER}\"}}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    entityName
    Type
    string
    Description
    Required: Name of the entity (e.g., "SalesOrder")
  • Name
    actionName
    Type
    string
    Description
    Required: Name of the action (e.g., "ReleaseSalesOrder")
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    endpointVersion
    Type
    string
    Description
    Required: API version (e.g., "24.200.001")
  • Name
    entity
    Type
    string
    Description
    Required: JSON object with entity key fields in Acumatica format
  • Name
    parameters
    Type
    string · optional
    Description
    Optional: JSON object with action parameters in Acumatica format

Get action status TOOLACUMATICA_GET_ACTION_STATUS​

Polls a long-running action that ACUMATICA_INVOKE_ACTION left in PENDING, using the operationUrl from that response. Reports whether the operation has completed, is still running, or failed.

Example​

Tool config
{
  "toolType": "ACUMATICA_GET_ACTION_STATUS",
  "connectorId": "V1StGXR8Z5",
  "operationUrl": "@@{OPERATION_URL}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    operationUrl
    Type
    string
    Description
    Required: The Location URL from AcumaticaInvokeAction 202 response

Raw API call TOOLACUMATICA_RAW_API_CALL​

The escape hatch: calls any Acumatica REST endpoint directly with the connector's authentication and returns the complete response — status, headers, and raw body. path can be a short form like "/entity/SalesOrder" (completed using endpointName/endpointVersion) or a full path. Supports GET, POST, PUT, and DELETE, so reserve it for cases the typed tools don't cover.

Example​

Tool config
{
  "toolType": "ACUMATICA_RAW_API_CALL",
  "connectorId": "V1StGXR8Z5",
  "method": "GET",
  "path": "/entity/SalesOrder",
  "endpointVersion": "24.200.001"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required: Reference to the Acumatica connector References a connector by ID.
  • Name
    method
    Type
    string
    Description
    Required: HTTP method (GET, POST, PUT, DELETE)
  • Name
    path
    Type
    string
    Description
    Required: API path (e.g., "/entity/SalesOrder" or full path like "/entity/Default/24.200.001/SalesOrder")
  • Name
    endpointVersion
    Type
    string · optional
    Description
    Optional: API version (e.g., "24.200.001") - used to build path if not fully specified
  • Name
    endpointName
    Type
    string · optional
    Description
    Optional: Endpoint name, defaults to "Default"
  • Name
    body
    Type
    string · optional
    Description
    Optional: JSON body for POST/PUT requests