Developer Guide

Integration Development Guide

2022 R2
 Contents | 2

Contents
Copyright............................................................................................................................................. 10
Integration Development Guide............................................................................................................. 11
Configuring the REST API...................................................................................................................... 12
Contract-Based Web Service API.................................................................................................................... 12
Endpoints and Contracts.................................................................................................................................12
API Entities, Fields, and Actions......................................................................................................................14
Custom Fields...................................................................................................................................................16
Custom Endpoints and Endpoint Extensions.................................................................................................18
Naming Rules for Endpoints........................................................................................................................... 18
Comparison of Contract Versions................................................................................................................... 19
Comparison of System Endpoints.................................................................................................................. 20
Changes to the Entities, Fields, and Actions of the Default/18.200.001 Endpoint as Compared to the
Default/17.200.001 Endpoint................................................................................................................. 21
Changes to the Entities, Fields, and Actions of the Default/20.200.001 Endpoint as Compared to the
Default/18.200.001 Endpoint................................................................................................................. 28
Changes to the Entities, Fields, and Actions of the Default/22.200.001 Endpoint as Compared to the
Default/20.200.001 Endpoint................................................................................................................. 38
Contract-Based REST API of a Web Service Endpoint................................................................................... 46
Contract-Based REST API of an Instance........................................................................................................47
Representation of a Record in JSON Format................................................................................................. 47
To Create a Custom Endpoint......................................................................................................................... 50
To Extend an Existing Endpoint...................................................................................................................... 53
To Validate an Endpoint.................................................................................................................................. 54
To Import a REST Schema to a Visual Studio Solution..................................................................................55
REST API Examples............................................................................................................................... 58
Basic Requests................................................................................................................................................. 58
Sign In to the Service............................................................................................................................. 58
Sign Out from the Service......................................................................................................................60
Create a Record...................................................................................................................................... 62
Update a Record..................................................................................................................................... 65
Retrieve a Record by Key Fields.............................................................................................................67
Retrieve a Record by ID.......................................................................................................................... 69
Retrieve Records by Conditions.............................................................................................................71
Retrieve Data from an Inquiry Form......................................................................................................73
Retrieve Records with Attributes........................................................................................................... 75
 Contents | 3

Remove a Record by Key Fields.............................................................................................................78

Remove a Record by ID.......................................................................................................................... 80
Execute an Action That Is Present in an Endpoint................................................................................81
Execute a Custom Action........................................................................................................................83
Retrieve a File Attached to a Record..................................................................................................... 86
Attach a File to a Record........................................................................................................................ 89
Retrieve the Schema of Custom Fields................................................................................................. 91
Retrieve a Record with Custom Fields...................................................................................................92
Create a Record with Custom Fields..................................................................................................... 94
Change the Business Date or Current Branch.......................................................................................95
Retrieve the Acumatica ERP Version and the List of Endpoints...........................................................97
Retrieve the List of Records in Batches.................................................................................................99
Specify Localized Values of a Multi-Language Field........................................................................... 101
Retrieve Localized Values of a Multi-Language Field......................................................................... 103
Parameters for Retrieving Records............................................................................................................... 105
$filter Parameter................................................................................................................................... 106
$top Parameter..................................................................................................................................... 107
$skip Parameter....................................................................................................................................107
$expand Parameter.............................................................................................................................. 107
$select Parameter................................................................................................................................. 108
$custom Parameter.............................................................................................................................. 108
Account...........................................................................................................................................................109
Add an Account to an Account Group................................................................................................. 109
Retrieve the List of Accounts in a Group............................................................................................. 110
Remove an Account from a Group...................................................................................................... 111
AccountDetailsForPeriodInquiry................................................................................................................... 111
Get General Ledger Transactions for Some Period.............................................................................112
AccountGroup................................................................................................................................................ 112
Create an Account Group..................................................................................................................... 112
Specify the Default Account of an Account Group..............................................................................113
Activity............................................................................................................................................................ 114
Create an Activity that Is Linked to a Case..........................................................................................114
Create an Activity that Is Linked to a Customer................................................................................. 115
Create an Activity that Is Linked to a Lead......................................................................................... 116
Bill................................................................................................................................................................... 117
Create a Bill for Particular Lines of a Purchase Order........................................................................ 117
 Contents | 4

Create a Bill for Particular Lines of a Purchase Receipt..................................................................... 118

Create a Bill with Tax Parameters Overridden.................................................................................... 120
BillOfMaterial..................................................................................................................................................122
Create a Bill of Material........................................................................................................................122
Retrieve the Bills of Material................................................................................................................124
BusinessAccount............................................................................................................................................ 124
Retrieve the List of Business Accounts................................................................................................124
Case................................................................................................................................................................ 125
Create a Case........................................................................................................................................ 125
Link a Case to Another Case................................................................................................................ 126
CompaniesStructure...................................................................................................................................... 127
Retrieve the Companies' Structure..................................................................................................... 127
Contact........................................................................................................................................................... 128
Create a Contact with Attributes......................................................................................................... 128
Activate a Contact.................................................................................................................................129
Retrieve the List of Contacts................................................................................................................130
Link Multiple Contacts to a Customer................................................................................................. 131
Customer........................................................................................................................................................ 131
Create a Customer................................................................................................................................ 132
Retrieve the List of Customers with Contacts.....................................................................................132
Update a Customer...............................................................................................................................133
Retrieve the Shipping Contact of a Customer.................................................................................... 134
Employee........................................................................................................................................................134
Create an Employee............................................................................................................................. 134
Retrieve Information about an Employee...........................................................................................136
InventorySummaryInquiry............................................................................................................................ 136
Get a Summary of an Inventory Item..................................................................................................136
Invoice............................................................................................................................................................ 137
Create an Invoice with Tax Parameters Overridden........................................................................... 137
Retrieve the List of Invoices................................................................................................................. 140
Release an AR Invoice...........................................................................................................................141
Specify the Tax Zone for an Invoice.....................................................................................................142
ItemWarehouse.............................................................................................................................................. 142
Override Values in the Item–Warehouse Details.................................................................................143
JournalTransaction........................................................................................................................................144
Create a GL Transaction with a Project Code That Does Not Produce a Project Transaction........... 144
 Contents | 5

Lead................................................................................................................................................................ 145
Create a Lead........................................................................................................................................ 145
Ledger............................................................................................................................................................. 146
Retrieve the List of Ledgers................................................................................................................. 146
Opportunity....................................................................................................................................................146
Create a Sales Order from an Opportunity......................................................................................... 146
Create a Business Account from an Opportunity............................................................................... 147
Payment..........................................................................................................................................................148
Create an AR Payment..........................................................................................................................148
Retrieve Payments One by One........................................................................................................... 149
ProFormaInvoice............................................................................................................................................150
Send a Pro Forma Invoice by Email.....................................................................................................150
Project.............................................................................................................................................................152
Create a Project from a Project Template...........................................................................................152
Make a Project Active........................................................................................................................... 153
Specify the Next Billing Date for a Project.......................................................................................... 153
Invoke Project Billing........................................................................................................................... 154
Retrieve the List of Pro Forma Invoices of a Project...........................................................................156
ProjectBudget................................................................................................................................................ 156
Specify the Progress of a Project Task................................................................................................ 156
ProjectTask..................................................................................................................................................... 157
Retrieve a Project Task.........................................................................................................................157
Activate a Project Task......................................................................................................................... 158
PurchaseOrder............................................................................................................................................... 159
Create a Purchase Order...................................................................................................................... 159
Create a Purchase Order with Tax Parameters Overridden................................................................160
PurchaseReceipt............................................................................................................................................ 161
Create a Purchase Receipt................................................................................................................... 161
Insert Lines with Allocations (with Location) in a PO Receipt........................................................... 162
Insert Lines with Allocations (with Expiration Dates) in a PO Receipt............................................... 164
Create a Purchase Return from a Purchase Receipt Record.............................................................. 165
Create a Purchase Return from a Purchase Receipt...........................................................................166
Create a Purchase Return for Particular Items................................................................................... 167
Create a Purchase Receipt in a Non-Base Currency........................................................................... 168
Create a Transfer Receipt with Allocations for a Transfer Order........................................................ 169
Release a Purchase Receipt................................................................................................................. 171
 Contents | 6

SalesInvoice....................................................................................................................................................171
Create a Credit Memo...........................................................................................................................172
SalesOrder...................................................................................................................................................... 173
Create a Sales Order with the Unit of Measure Specified.................................................................. 173
Create a Sales Order with a Credit Card Payment..............................................................................174
Create a Sales Order with a Captured Credit Card Payment..............................................................175
Create a Sales Order with an Authorized Credit Card Payment.........................................................177
Create a Sales Order with an External Credit Card Payment............................................................. 178
Apply Discounts to a Sales Order........................................................................................................ 180
Create a Return for Credit Without Validation of the Card Refund Against the Original Transaction. 183
Create a Shipment from a Sales Order................................................................................................185
Create a Return Order for Invoices...................................................................................................... 186
ServiceOrder...................................................................................................................................................187
Retrieve a Service Order.......................................................................................................................187
Shipment........................................................................................................................................................ 188
Create a Shipment for Two Sales Orders with Allocations and Package Specifications...................188
Read the Tracking Number from a Shipment..................................................................................... 190
Write the Tracking Number to a Shipment......................................................................................... 191
Update the Freight Cost or Price......................................................................................................... 192
Create Separate Shipments for Each Sales Order.............................................................................. 193
StockItem....................................................................................................................................................... 195
Retrieve the List of Modified Stock Items........................................................................................... 195
Retrieve Stock Items with Attributes...................................................................................................195
Retrieve Unit Conversion Rules from a Stock Item.............................................................................196
Retrieve Stock Items with Prices and Quantities by Warehouse....................................................... 197
TaxCategory....................................................................................................................................................197
Update a Tax Category......................................................................................................................... 197
TimeEntry....................................................................................................................................................... 198
Read Employee Time Activities........................................................................................................... 198
Write Employee Time Activities........................................................................................................... 199
Search for Time Entries by Date.......................................................................................................... 200
Vendor............................................................................................................................................................ 201
Retrieve the List of Vendors................................................................................................................. 201
Create a Vendor.................................................................................................................................... 201
Scenarios........................................................................................................................................................ 203
Inventory and Order Management...................................................................................................... 203
 Contents | 7

Project Accounting............................................................................................................................... 209

Authorizing Client Applications to Work with Acumatica ERP................................................................. 216
Authorization Code Flow...............................................................................................................................216
Implicit Flow...................................................................................................................................................223
Resource Owner Password Credentials Flow...............................................................................................227
Hybrid Flow.................................................................................................................................................... 233
Comparison of the Flows.............................................................................................................................. 238
To Register a Client Application....................................................................................................................239
To Revoke the Access of a Connected Application...................................................................................... 241
Limiting Connections of Integrated Applications................................................................................... 243
License Restrictions for API Users.................................................................................................................243
Limitation of API Connections for Integrated Applications.........................................................................246
To Limit the Number of API Connections of Integrated Applications......................................................... 247
To Limit API Connections of a Particular Application..................................................................................248
Configuring Push Notifications............................................................................................................ 249
Push Notifications..........................................................................................................................................249
Recommendations for the Data Queries...................................................................................................... 250
Push Notification Destinations..................................................................................................................... 250
Push Notification Format.............................................................................................................................. 252
To Configure Push Notifications................................................................................................................... 253
To Process Failed Notifications..................................................................................................................... 257
To Create a Built-In Definition.......................................................................................................................258
To Connect to the SignalR Hub.....................................................................................................................260
To Add Additional Information to Push Notifications................................................................................. 262
To Create a Custom Destination Type.......................................................................................................... 263
Configuring Webhooks........................................................................................................................ 266
To Create an Implementation Class............................................................................................................. 266
To Register an Implementation Class...........................................................................................................267
To Configure the External Application..........................................................................................................267
To Manage Request Log................................................................................................................................ 267
Webhook Configuration Example................................................................................................................. 268
Working with the SOAP APIs................................................................................................................ 272
Working with the Contract-Based SOAP API................................................................................................ 272
Multi-Language Fields.......................................................................................................................... 272
To Configure the Client Application.................................................................................................... 274
Contract-Based SOAP API Reference............................................................................................................ 276
 Contents | 8

Login() Method......................................................................................................................................277
Logout() Method................................................................................................................................... 278
SetBusinessDate() Method................................................................................................................... 279
Get() Method......................................................................................................................................... 279
GetList() Method (Contract Version 3)................................................................................................. 280
GetList() Method (Contract Version 2)................................................................................................. 281
Put() Method......................................................................................................................................... 282
Delete() Method.................................................................................................................................... 286
Invoke() Method....................................................................................................................................286
GetProcessStatus() Method..................................................................................................................287
GetFiles() Method................................................................................................................................. 288
PutFiles() Method................................................................................................................................. 289
GetCustomFieldSchema() Method.......................................................................................................290
Attributes Property............................................................................................................................... 290
CustomFields Property.........................................................................................................................291
ReturnBehavior Property (Contract Version 3)................................................................................... 293
ReturnBehavior Property (Contract Version 2)................................................................................... 295
Working with the Screen-Based SOAP API................................................................................................... 297
Screen-Based Web Services API.......................................................................................................... 297
API Objects Related to Acumatica ERP Forms.................................................................................... 298
Screen-Based API Wrapper.................................................................................................................. 300
To Generate the WSDL File of the Web Services................................................................................. 302
To Import the WSDL File Into the Development Environment...........................................................304
To Use the Screen-Based API Wrapper................................................................................................305
Working with Commands of the Screen-Based SOAP API...........................................................................306
Commands for Retrieving the Values of Elements............................................................................. 306
Selection of a Group of Records for Export.........................................................................................308
Commands for Setting the Values of Elements.................................................................................. 309
Commands for Clicking Buttons on a Form........................................................................................310
Commands for Adding Detail Lines..................................................................................................... 310
Commands for Pop-Up Dialog Boxes and Pop-Up Forms.................................................................. 311
Commands for Pop-Up Panels.............................................................................................................313
Commands for Record Searching: Filter Service Command..............................................................315
Commands for Record Searching: Key Command............................................................................. 317
Commands for Record Searching: Custom Field................................................................................ 318
Commands That Require a Commit....................................................................................................319
 Contents | 9

Commands for Working with Attachments.........................................................................................320

Commands for Working with Multi-Language Fields......................................................................... 321
Screen-Based SOAP API Reference............................................................................................................... 322
Login() Method......................................................................................................................................323
Logout() Method................................................................................................................................... 324
SetLocaleName() Method.....................................................................................................................325
SetBusinessDate() Method................................................................................................................... 325
GetScenario() Method...........................................................................................................................326
GetSchema() Method............................................................................................................................326
SetSchema() Method............................................................................................................................ 327
Export() Method.................................................................................................................................... 327
Submit() Method...................................................................................................................................328
Import() Method................................................................................................................................... 330
Clear() Method...................................................................................................................................... 330
GetProcessStatus() Method..................................................................................................................331
 Copyright | 10

Copyright

© 2022 Acumatica, Inc.

ALL RIGHTS RESERVED.

No part of this document may be reproduced, copied, or transmitted without the express prior consent of
Acumatica, Inc.
3933 Lake Washington Blvd NE, # 350, Kirkland, WA 98033

Restricted Rights
The product is provided with restricted rights. Use, duplication, or disclosure by the United States Government is
subject to restrictions as set forth in the applicable License and Services Agreement and in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Soware clause at DFARS 252.227-7013 or subparagraphs (c)(1) and
(c)(2) of the Commercial Computer Soware-Restricted Rights at 48 CFR 52.227-19, as applicable.

Disclaimer
Acumatica, Inc. makes no representations or warranties with respect to the contents or use of this document, and
specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose.
Further, Acumatica, Inc. reserves the right to revise this document and make changes in its content at any time,
without obligation to notify any person or entity of such revisions or changes.

Trademarks
Acumatica is a registered trademark of Acumatica, Inc. HubSpot is a registered trademark of HubSpot, Inc.
Microso Exchange and Microso Exchange Server are registered trademarks of Microso Corporation. All other
product names and services herein are trademarks or service marks of their respective companies.

Soware Version: 2022 R2

Last Updated: 01/30/2023
 Integration Development Guide | 11

Integration Development Guide

In this guide, you can find information about how to develop client applications that work with Acumatica ERP
through the web services.

In This Guide
• Configuring the REST API
• REST API Examples
• Authorizing Client Applications to Work with Acumatica ERP
• Limiting Connections of Integrated Applications
• Configuring Push Notifications
• Configuring Webhooks
• Working with the SOAP APIs
 Configuring the REST API | 12

Configuring the REST API

Acumatica ERP provides web services for integration with external systems. Through the web services of Acumatica
ERP, external systems can get data records from Acumatica ERP, process these records, and save new or updated
records to Acumatica ERP.
To access these web services, you can use the contract-based representational state transfer (REST) API, the
contract-based SOAP application programming interface (API), and the screen-based SOAP API. In this chapter, you
will find the main concepts that are related to the contract-based SOAP API and the contract-based REST API.

Contract-Based Web Service API

The contract-based web service APIs operate with business logic objects that do not depend on Acumatica ERP
forms or their properties and methods. (In this context, contract-based means based on the object model that the
web service API provides.) Each web service contract is fixed and does not change based on system customization,
localization, or any other changes made to Acumatica ERP.
For example, suppose that the contract of the web service contains the definition of the CustomerID field, which
accesses the Customer ID element on the Customers (AR303000) form. If you have changed the name of the
Customer ID element to Customer Identifier in a customization project, the contract of the web service remains
fully functional and does not require update; also, your application requires no further modifications. You can
access the Customer Identifier element on the form through the same CustomerID field.

REST and SOAP Interfaces of the Contract-Based Web Services

You can work with the contract-based web services through the REST interface.
To use the contract-based REST or SOAP API in your application, first of all, you should decide which endpoint to
use. You can find more information on the endpoints and their contracts in Endpoints and Contracts.
Aer that, you can use the REST API in your application. For details on the REST API, see Basic Requests.
Aer you have selected the endpoint, to use the contract-based SOAP API in your application, you should obtain
the WSDL description of the contract of this endpoint, import the WSDL file into your development environment (as
described in To Configure the Client Application), and start developing your application. You can find the description
of the SOAP API methods in Contract-Based SOAP API Reference.
You can find examples of how to use the contract-based REST API in the I310 Web Services: Basic | Data Retrieval
with REST API, I320 Web Services: Advanced | Data Retrieval with REST API, and I330 Web Services: Data Manipulation
with REST API training course.
Related Links
• Endpoints and Contracts
• API Entities, Fields, and Actions

Endpoints and Contracts

You access the contract-based REST and SOAP API through endpoints that you configure on the Web Service
Endpoints (SM207060) form.
 Configuring the REST API | 13

Endpoints and Contracts

An endpoint is an entry point to the Acumatica ERP web services. For each endpoint that a web service API
provides, a contract of the endpoint defines the entities, with their actions and fields, that are available through the
endpoint and the methods that you can use to work with these entities.
The endpoint is identified by the URL that you use to access the web services API. You can see the name and
version of an endpoint in its URL. For example, the endpoint http://localhost/AcumaticaDB/entity/
Default/18.200.001?wsdl has the version 18.200.001 and the name Default. The version of an endpoint
defines the list of entities, with their actions and fields you can work with through this endpoint.
The contract of an endpoint is identified by contract version. The version of a contract defines the list of methods
for working with entities that you can use when working with Acumatica ERP through the endpoint with this
version of the contract. For the difference between the contract versions, see Comparison of Contract Versions.

Contract Version 1 is not supported starting from Acumatica ERP 2018 R2.

System and Custom Endpoints

You can use two types of endpoints to access the web services:
• System endpoint: The system endpoints are precofigured in the system and have the Default name. Each of
these endpoints has a predefined contract, which includes the API that is preconfigured in the system. You
cannot change the contract of a system endpoint.
If the API that is available in the contract of a system endpoint is sufficient for the requirements of your
application, you should use the system endpoint for accessing Acumatica ERP web services. You can use
the same system endpoint in future versions of Acumatica ERP. For example, if you use the system endpoint
with Version 17.200.001 and Contract Version 3 to access Acumatica ERP 2017 R2, you can use the same
endpoint to access future versions of Acumatica ERP.

Acumatica ERP can include endpoints preconfigured in the system that have names other than
Default. The system uses these endpoints internally. We recommend that you not use these
endpoints.

• Custom endpoint: By default, there are no custom endpoints in the system. If the API provided by the
system endpoint is not sufficient for the requirements of your application, you can create a custom
endpoint. You can configure the contract of a custom endpoint by adding the needed elements of the API to
the contract.
If you need to use the same custom endpoint in future versions of Acumatica ERP, you should maintain it in
future versions.

Obsolete system endpoints may be removed in some version of Acumatica ERP. For example, the
Default/6.00.001 endpoint has been removed in Acumatica ERP 2020 R2, and extensions of this
endpoint cannot be used starting from Acumatica ERP 2020 R2.

The following diagram provides an example of multiple endpoints configured in the system. The diagram shows
two system endpoints with Contract Versions 3 and 4 and two custom endpoints with the names EastEndpoint and
WestEndpoint.
 Configuring the REST API | 14

Figure: Contract-based web services

API Entities, Fields, and Actions

The contract of an endpoint defines the following elements of the contract-based web services API: entities, fields,
and actions.

Entities
An entity corresponds to a business logic object that you are going to work with. For example, the contract of a
system endpoint includes the Warehouse entity, which represents a warehouse and holds the data related to the
warehouse. This entity is associated with the Warehouses (IN204000) form.
For a custom endpoint, if you are going to use an entity to transfer data to or from Acumatica ERP, you should
associate this entity with a particular Acumatica ERP form. For example, you can create a Vendor entity, which
represents a vendor. This entity is associated with the Vendors (AP303000) form.

Fields
The fields of an entity correspond to the parameters of a business logic object. For example, the Warehouse entity
that is available through the system endpoint has the Description and WarehouseID fields, among others. In the
contract, these fields are mapped to the Description and the Warehouse ID elements of the Summary area of the
Warehouses form.

For a custom endpoint, if you need to connect the field with a particular element on an Acumatica ERP form,
you should map the field to this element. For example, if you have created the Vendor entity, which designates
a vendor, you can add the field VendorID to the entity and connect this field with the Vendor ID element of the
Summary area of the Vendors form.
 Configuring the REST API | 15

Actions
The actions of an entity correspond to the actions that can be applied to a business logic object. For example, the
TransferOrder entity, which is available through the system endpoint, has the ReleaseTransferOrder action. This
action corresponds to the Release button on the form toolbar of the Transfers (IN304000) form.
For a custom endpoint, if you need to use an Acumatica ERP action, you should add this action to the contract of
the custom endpoint with the needed parameters. For example, suppose you want to add an action that changes
the customer ID of an existing customer, you can add the action ChangeID and map it to the Change ID action,
which is available on the Customers form. The new action should have one parameter, which specifies the new ID of
a customer as the Change ID action has.

Types of Entities
When you add a new entity to a contract, you should specify the type of the entity, which can be one of the
following:
• Top-Level: Entities of this type are the main entities of the contract. A top-level entity usually corresponds to
an Acumatica ERP form. For example, the Warehouse entity of the contract of the system endpoint is a top-
level entity that corresponds to the Warehouses form.
• Detail: Detail entities correspond to the detail lines of a master-detail form. A detail entity exists only as a
part of a top-level entity. For example, the top-level entity SalesOrder of the contract of the system endpoint
contains the detail entity SalesOrderDetail, which corresponds to a detail line on the Document Details tab
of the Sales Orders (SO301000) form, as shown in the following screenshot.

Figure: Detail entity

• Linked: Linked entities are supplementary entities of a contract. A linked entity usually corresponds to a
part of an Acumatica ERP form and is related to one top-level entity of the contract or multiple such entities.
For example, the top-level entity Contact of the contract of the system endpoint contains the linked entity
 Configuring the REST API | 16

Address, which corresponds to the Address group of fields on the Details tab of the Contacts (CR302000)
form, as shown in the following screenshot.

Figure: Linked entity

Custom Fields

You can work with the values of the custom fields that are not included in the entity definition.

Custom fields can correspond to the following elements:

• The predefined elements on an Acumatica ERP form that are not included in the entity
definition
• The elements that were added to the Acumatica ERP form in a customization project
• The user-defined fields

To work with the needed custom field, you need to know the name of the data view that contains the
corresponding custom element and the name of the field, which are described in detail below.
 Configuring the REST API | 17

Field Name and View Name

A field name is the internal name of a particular element of an Acumatica ERP form. A view name is the name of the
data view to which a particular element belongs. For example, the Posting Class element on the General tab of the
Stock Items (IN202500) form has the PostClassID field name and belong to the ItemSettings data view.

To find out the field name and view name, on the title bar of the form, you click Customization > Inspect Element
and click the needed element on the form. In the Element Properties dialog box, which opens, you find the
field name in the Data Field element and the view name in the View Name element, as shown in the following
screenshot.

Figure: Field name and view name

In the contract-based REST API, you can also find out the field name and the view name through the special URL.
For details on the URL and the HTTP method, see Retrieve the Schema of Custom Fields.
In the contract-based SOAP API, you can find out the field name and the view name in code by using the
GetCustomFieldSchema() method. For details on the method, see GetCustomFieldSchema() Method.

Field Name and View Name of a User-Defined Field

For any user-defined field, the field name is Attribute<AttributeID>, where you replace <AttributeID>
with the ID of the attribute that corresponds to the user-defined field. For details on how you can find out the view
name, see Retrieve the Schema of Custom Fields.
For example, suppose that on the Sales Orders (SO301000) form, you have added a user-defined field for
the OPERATSYST attribute. You work with this user-defined field by using the Document view name and the
AttributeOPERATSYST field name.

Use of Custom Fields

For details on retrieving the values of custom fields by using the contract-based REST API, see the description of the
$custom parameter in Parameters for Retrieving Records. For details on specifying the values of custom fields, see
Representation of a Record in JSON Format.
 Configuring the REST API | 18

For details on working with custom elements through the contract-based SOAP API, see CustomFields Property.

Custom Endpoints and Endpoint Extensions

If the API provided by the system endpoint of Acumatica ERP is not sufficient for the requirements of your
application, you can create a custom endpoint from scratch or by extending an existing endpoint.

An Extension of an Existing Endpoint

If you are creating an endpoint as an extension of an existing endpoint, for the API elements that were inherited
from the base endpoint, you cannot edit the names and types of the entities and fields, and the names, types,
and parameters of the actions. In the contract of the new endpoint, you can add new top-level entities, new fields
or entities to any entity, and new actions. Then you can use both the API that you added to the contract of the
endpoint and the API of the base endpoint in your application. For information on how to extend an existing
endpoint, see To Extend an Existing Endpoint.
The new endpoint that was created as an extension of an existing endpoint has the version of the contract of the
base endpoint; that is, the API methods for working with entities are the same for the base endpoint and the new
endpoint. See REST API Examples and Contract-Based SOAP API Reference for the description of the API methods
of the needed contract version.

An Endpoint Created from Scratch

If you are creating an endpoint from scratch, you should add the needed elements of the API to the contract. Then
you can use these API elements in your application. For information on how to create an endpoint from scratch, see
To Create a Custom Endpoint.

The new endpoint that is created from scratch always has the latest version of the contract. For the description
of the API methods for working with entities that are available in the latest version of the contract, see REST API
Examples.

Related Links
• Comparison of Contract Versions

Naming Rules for Endpoints

When you create a custom endpoint on the Web Service Endpoints (SM207060) form (either from scratch or by
extending a system endpoint), for the names of the entities, fields, actions, and action parameters of the endpoint,
and the endpoint name and version, you should make sure to adhere to the following rules:
• The name of the endpoint can contain only English letters, digits, underscores, and periods, and cannot
start with a digit.
• The version of the endpoint can contain only English letters, digits, underscores, and periods.
• The name of the entity, field, action, or action parameter can contain only English letters, digits, and
underscores, and cannot start with a digit.
• The name of the field cannot match any of the following reserved names:
• ID
• RowNumber
• Note
• Delete
• CustomFields
 Configuring the REST API | 19

• ReturnBehavior
• Entity
• Action
• The name of the field must be unique among the names of the fields of the entity.
• The name of the parameter must be unique among the names of the parameters of the action.
• The name of the entity or action must be unique among the names of the entities and actions of the
endpoint.
The system checks whether the names used in the endpoint satisfy these rules each time you enter the name of
a new entity, field, action, or action parameter. You can also validate the endpoint manually, as described in To
Validate an Endpoint.

Related Links
• To Validate an Endpoint

Comparison of Contract Versions

Acumatica ERP 2022 R2 supports three versions of system contracts. You can use endpoints with any of these
contract versions. In this topic, you can learn the main differences between the contract versions.

Contract Version 1 is not supported starting from Acumatica ERP 2018 R2.

Table: Comparison of Contract Versions

Characteristic Contract Ver- Contract Ver- Contract Ver-

sion 2 sion 3 sion 4

The REST API is supported for the endpoints with this Yes Yes Yes
contract version.

The SOAP API is supported for the endpoints with this Yes Yes No
contract version.

You can specify particular fields of the entity to be re- Yes Yes Yes
turned from the system.

By default, the system returns all fields of the entity For the SOAP No No
(including fields of the linked and detail entities de- API: Yes
fined within the entity).
For the REST
API: No

Through the endpoint, you can work with the ele- Yes Yes Yes
ments that were added to the Acumatica ERP form in a
customization project.

Through the endpoint, you can work with the prede- Yes Yes Yes
fined elements on an Acumatica ERP form that are not
included in the entity definition.
 Configuring the REST API | 20

Characteristic Contract Ver- Contract Ver- Contract Ver-

sion 2 sion 3 sion 4

When optimization for speed of the retrieval of the list The system re- The system re- The system re-
of records fails, the system behaves as follows. trieves data in turns an error. turns an error.
an unoptimized
way (slow).

Custom endpoints created from scratch have this con- No No Yes

tract version.

The system endpoint that has this contract version is No Yes (Endpoint Yes (Endpoint
included in Acumatica ERP 2022 R2. Versions De- Versions De-
fault/18.200.001 fault/20.200.001
and De- and De-
fault/17.200.001) fault/22.200.001)

Related Links
• Endpoints and Contracts

Comparison of System Endpoints

Acumatica ERP 2022 R2 supports three system endpoints. In this topic, you can learn about the differences between
these endpoints.

Contract Versions of the Endpoints

The following table specifies the contract versions of the endpoints. For details about the differences between the
contract versions, see Comparison of Contract Versions.

Endpoint Contract Version

Default/22.200.001 4

Default/20.200.001 4

Default/18.200.001 3

Default/17.200.001 3

The following topics describe the changes made to the Default endpoint as compared to its previous version:
• Changes to the Entities, Fields, and Actions of the Default/18.200.001 Endpoint as Compared to the
Default/17.200.001 Endpoint
• Changes to the Entities, Fields, and Actions of the Default/20.200.001 Endpoint as Compared to the
Default/18.200.001 Endpoint
• Changes to the Entities, Fields, and Actions of the Default/22.200.001 Endpoint as Compared to the
Default/20.200.001 Endpoint
 Configuring the REST API | 21

Changes to the Entities, Fields, and Actions of the Default/18.200.001 Endpoint as

Compared to the Default/17.200.001 Endpoint

The following tables contain the new, modified, or removed elements of the Default/18.200.001 endpoint as
compared to the Default/17.200.001 endpoint.

Table: New Entities

The entities listed in the following table (except ProFormaInvoice) can be created, retrieved, updated, and
deleted through the standard API methods. ProFormaInvoice can be created only by the invocation of the
RunProjectBilling action of Project.

Entity Related Form Name and ID

AccountGroup Account Groups (PM201000)

Activity Activity (CR306010)

AllocationRule Allocation Rules (PM207500)

ChangeOrder Change Orders (PM308000)

ChangeOrderClass Change Order Classes (PM203000)

CommonTask Common Tasks (PM208030)

CompanyFinancialPeriod Company Financial Calendar (GL201100)

CostCode Cost Codes (PM209500)

ExpenseClaim Expense Claim (EP301000)

ExpenseReceipt Expense Receipt (EP301020)

ExternalCommitment External Commitments (PM209000)

LaborCostRate Labor Rates (PM209900)

ManageFinancialPeriods Manage Financial Periods (GL503000)

ProFormaInvoice Pro Forma Invoices (PM307000)

Project Projects (PM301000)

ProjectBilling Run Project Billing (PM503000)

ProjectBillingRules Billing Rules (PM207000)

ProjectBudget Project Budget (PM309000)

ProjectTask Project Tasks (PM302000)

ProjectTemplate Project Templates (PM208000)

 Configuring the REST API | 22

Entity Related Form Name and ID

ProjectTemplateTask Project Template Tasks (PM208010)

TimeEntry Time Entry (PM209100)

UnionLocal Union Locals (PM209700)

WorkClassCompensationCode Workers' Compensation Codes (PM209800)

Table: Changed Entities

Entity Related Form Name and ID Change

Email.TimeActivity Email Activity (CR306015) The object name has been changed
from EmailTimeActivity to
TimeActivity.

Employee Employees (EP203000) The mapping of the entity has been

completely changed.

Table: New Fields and Actions

Field or Action Name Related Form Name and ID

AccountLocation.Address.Validated Account Locations (CR303010)

Bill.Details.CalculateDiscountsOnImport Bills and Adjustments (AP301000)

Bill.Details.CostCode Bills and Adjustments (AP301000)

Bill.Details.InventoryID Bills and Adjustments (AP301000)

Bill.Details.POLine Bills and Adjustments (AP301000)

Bill.Details.POReceiptLine Bills and Adjustments (AP301000)

Bill.Details.POReceiptNbr Bills and Adjustments (AP301000)

Bill.Project Bills and Adjustments (AP301000)

BusinessAccount.Activities.NoteID Business Accounts (CR303000)

BusinessAccount.LastModifiedDateTime Business Accounts (CR303000)

BusinessAccount.MainAddress.Validated Business Accounts (CR303000)

BusinessAccount.ShippingAddress.Validated Business Accounts (CR303000)

Case.Activities.CostCode Cases (CR306000)

Case.Activities.NoteID Cases (CR306000)

CashSale.Details.CostCode Cash Sales (AR304000)

 Configuring the REST API | 23

Field or Action Name Related Form Name and ID

CashSale.Details.ProjectTask Cash Sales (AR304000)

CashSale.Project Cash Sales (AR304000)

Contact.Activities.NoteID Contacts (CR302000)

Contact.Address.Validated Contacts (CR302000)

Contact.LastModifiedDateTime Contacts (CR302000)

Email.TimeActivity.CostCode Email Activity (CR306015)

FinancialPeriod.Details.Status Master Financial Calendar

(GL201000)

JournalTransaction.Details.CostCode Journal Transactions (GL301000)

JournalTransaction.Details.IsNonPM Journal Transactions (GL301000)

JournalTransaction.Details.ProjectTransactionID Journal Transactions (GL301000)

InventoryReceipt.Details.CostCode Receipts (IN301000)

InventoryReceipt.Details.Project Receipts (IN301000)

InventoryReceipt.Details.ProjectTask Receipts (IN301000)

Invoice.Details.CalculateDiscountsOnImport Invoices and Memos (AR301000)

Invoice.Details.CostCode Invoices and Memos (AR301000)

Invoice.DiscountDetails Invoices and Memos (AR301000)

Lead.Activities.NoteID Leads (CR301000)

Lead.Address.Validated Leads (CR301000)

Opportunity.Activities.NoteID Opportunities (CR304000)

Opportunity.Address.Validated Opportunities (CR304000)

Payment.PaymentLoadDocuments Payments and Applications

(AR302000)

Payment.PaymentLoadOrders Payments and Applications

(AR302000)

PhysicalInventoryReview.CreatedDateTime Payments and Applications

(AR302000)

ProjectTransaction.Details.Billed Project Transactions (PM304000)

ProjectTransaction.Details.CostCode Project Transactions (PM304000)

 Configuring the REST API | 24

Field or Action Name Related Form Name and ID

ProjectTransaction.Details.ExternalRefNbr Project Transactions (PM304000)

ProjectTransaction.ReleaseTransactions Project Transactions (PM304000)

PurchaseOrder.Branch Purchase Orders (PO301000)

PurchaseOrder.Details.CalculateDiscountsOnImport Purchase Orders (PO301000)

PurchaseOrder.Details.CostCode Purchase Orders (PO301000)

PurchaseOrder.Details.Project Purchase Orders (PO301000)

PurchaseOrder.Details.ProjectTask Purchase Orders (PO301000)

PurchaseOrder.EnterAPBill Purchase Orders (PO301000)

PurchaseOrder.EnterPOReceipt Purchase Orders (PO301000)

PurchaseOrder.LastModifiedDateTime Purchase Orders (PO301000)

PurchaseOrder.Project Purchase Orders (PO301000)

PurchaseOrder.ShippingInstructions.ShipToAd- Purchase Orders (PO301000)

dress.Validated

PurchaseOrder.TaxDetails Purchase Orders (PO301000)

PurchaseOrder.Terms Purchase Orders (PO301000)

PurchaseOrder.VendorTaxZone Purchase Orders (PO301000)

PurchaseReceipt.BillDate Purchase Receipts (PO302000)

PurchaseReceipt.Branch Purchase Receipts (PO302000)

PurchaseReceipt.CreateAPBill Purchase Receipts (PO302000)

PurchaseReceipt.Description Purchase Receipts (PO302000)

PurchaseReceipt.TransferOrderNbr Purchase Receipts (PO302000)

PurchaseReceipt.TransferOrderType Purchase Receipts (PO302000)

PurchaseReceipt.TransferShipmentNbr Purchase Receipts (PO302000)

PurchaseReceipt.UnbilledQuantity Purchase Receipts (PO302000)

PurchaseReceipt.Warehouse Purchase Receipts (PO302000)

SalesInvoice.ApplicationsCreditMemo Invoices (SO303000)

SalesInvoice.ApplicationsInvoice Invoices (SO303000)

 Configuring the REST API | 25

Field or Action Name Related Form Name and ID

SalesInvoice.BillToSettings.BillToAddress.Validated Invoices (SO303000)

SalesInvoice.BillToSettings.CustomerLocation Invoices (SO303000)

SalesInvoice.CashDiscount Invoices (SO303000)

SalesInvoice.Commissions Invoices (SO303000)

SalesInvoice.CreditHold Invoices (SO303000)

SalesInvoice.Currency Invoices (SO303000)

SalesInvoice.Details.CostCode Invoices (SO303000)

SalesInvoice.Details.ProjectTask Invoices (SO303000)

SalesInvoice.Details.CalculateDiscountsOnImport Invoices (SO303000)

SalesInvoice.Details.DiscountAmount Invoices (SO303000)

SalesInvoice.Details.DiscountPercent Invoices (SO303000)

SalesInvoice.Details.ExpirationDate Invoices (SO303000)

SalesInvoice.Details.InventoryDocType Invoices (SO303000)

SalesInvoice.Details.InventoryRefNbr Invoices (SO303000)

SalesInvoice.Details.Location Invoices (SO303000)

SalesInvoice.Details.LotSerialNbr Invoices (SO303000)

SalesInvoice.Details.ManualDiscount Invoices (SO303000)

SalesInvoice.Details.OrderLineNbr Invoices (SO303000)

SalesInvoice.Details.OrigInvLineNbr Invoices (SO303000)

SalesInvoice.Details.OrigInvNbr Invoices (SO303000)

SalesInvoice.Details.OrigInvType Invoices (SO303000)

SalesInvoice.Details.Subitem Invoices (SO303000)

SalesInvoice.Details.TaxCategory Invoices (SO303000)

SalesInvoice.Details.TransactionDescr Invoices (SO303000)

SalesInvoice.Details.WarehouseID Invoices (SO303000)

SalesInvoice.DiscountDetails Invoices (SO303000)

SalesInvoice.FinancialDetails Invoices (SO303000)

 Configuring the REST API | 26

Field or Action Name Related Form Name and ID

SalesInvoice.Project Invoices (SO303000)

SalesInvoice.SalesInvoiceAddOrder Invoices (SO303000)

SalesInvoice.SalesInvoiceAutoApply Invoices (SO303000)

SalesInvoice.TaxDetails Invoices (SO303000)

SalesInvoice.Totals Invoices (SO303000)

SalesInvoice.VATExemptTotal Invoices (SO303000)

SalesInvoice.VATTaxableTotal Invoices (SO303000)

SalesOrder.AutoRecalculateDiscounts Sales Orders (SO301000)

SalesOrder.BillToAddress.Validated Sales Orders (SO301000)

SalesOrder.Details.CalculateDiscountsOnImport Sales Orders (SO301000)

SalesOrder.Details.CostCode Sales Orders (SO301000)

SalesOrder.DisableAutomaticDiscountUpdate Sales Orders (SO301000)

SalesOrder.DiscountDetails.Description Sales Orders (SO301000)

SalesOrder.DiscountDetails.ExternalDiscountCode Sales Orders (SO301000)

SalesOrder.OpenSalesOrder Sales Orders (SO301000)

SalesOrder.PaymentProfileID Sales Orders (SO301000)

SalesOrder.ReleaseFromCreditHoldSalesOrder Sales Orders (SO301000)

SalesOrder.SalesOrderAddInvoice Sales Orders (SO301000)

SalesOrder.SalesOrderAddStockItem Sales Orders (SO301000)

SalesOrder.SalesOrderCreatePurchaseOrder Sales Orders (SO301000)

SalesOrder.SalesOrderCreateReceipt Sales Orders (SO301000)

SalesOrder.SalesOrderCreateShipment Sales Orders (SO301000)

SalesOrder.ShipToAddress.Validated Sales Orders (SO301000)

Shipment.PrepareInvoice Shipments (SO302000)

Shipment.ShipToSettings.ShipToAddress.Validated Shipments (SO302000)

Task.RelatedActivities.NoteID Task (CR306020)

 Configuring the REST API | 27

Field or Action Name Related Form Name and ID

Task.TimeActivity.CostCode Task (CR306020)

Table: Renamed Actions

Action Name in Default/18.200.001 (Action Name in Default/17.200.001) Related Form Name and ID

Email.CreateContactFromEmail (Email.CreateCon- Email Activity (CR306015)

tactEmail)

Email.CreateEventFromEmail (Email.CreateEventEmail) Email Activity (CR306015)

Email.CreateLeadFromEmail (Email.CreateLeadEmail) Email Activity (CR306015)

Email.CreateOpportunityFromEmail (Email.CreateOppor- Email Activity (CR306015)

tunityEmail)

Email.CreateExpenseReceiptFromEmail (Email.CreateEx- Email Activity (CR306015)

penseReceiptEmail)

Email.CreateCaseFromEmail (Email.CreateCaseEmail) Email Activity (CR306015)

Email.CreateTaskFromEmail (Email.CreateTaskEmail) Email Activity (CR306015)

Email.LinkEntityToEmail (Email.SelectRelatedEntityE- Email Activity (CR306015)

mail)

Event.LinkEntityToEvent (Event.SelectRelatedEnti- Event (CR306030)

tyEvent)

Task.LinkEntityToTask (Task.SelectRelatedEntityTask) Task (CR306020)

Table: Removed Fields and Actions

Field or Action Name Related Form Name and ID

Email.SelectSourceEmail Email Activity (CR306015)

FinancialPeriod.Details.Active Master Financial Calendar (GL201000)

FinancialPeriod.Details.ClosedInGL Master Financial Calendar (GL201000)

FinancialPeriod.Details.ClosedInPR Master Financial Calendar (GL201000)

PurchaseReceipt.Details.Project Purchase Receipts (PO302000)

PurchaseReceipt.Details.ProjectTask Purchase Receipts (PO302000)

 Configuring the REST API | 28

Changes to the Entities, Fields, and Actions of the Default/20.200.001 Endpoint as

Compared to the Default/18.200.001 Endpoint

The following tables contain the new, modified, or removed elements of the Default/20.200.001 endpoint as
compared to the Default/18.200.001 endpoint.

Table: New Entities

Entity Related Form Name and ID

AccountDetailsForPeriodInquiry Account Details for Period (GL404001)

Budget Budgets (GL302010)

CompaniesStructure Company Branch (CS401000)

Ledger Ledgers (GL201500)

Payment.SalesOrderPayment Payments and Applications (AR302000)

SalesOrder.SalesOrderCreditCardTrans- Sales Orders (SO301000)

actionDetail

Shipment.ShipmentPackageDetail Shipments (SO302000)

StorageDetailsInquiry Storage Details (IN408050)

StorageDetailsByLocationInquiry Storage Details by Item Warehouse Location

(IN408055)

Task.TaskRelatedActivity Task (CR306020)

ServiceOrder Service Orders (FS300100)

Appointment Appointments (FS300200)

Table: Changed Entities

Entity Related Form Name and ID Change

InventoryAdjustment Adjustments (IN303000) • The Adjustment entity has

been renamed to Invento-
ryAdjustment.
• The AdjustmentDetail de-
tail entity has been renamed to
InventoryAdjustmentDe-
tail.
 Configuring the REST API | 29

Entity Related Form Name and ID Change

AttributeDefinition Attributes (CS205000) The AttributeDetail detail

entity has been removed. The fol-
lowing fields have been added to
the AttributeValue detail enti-
ty:
• AttributeDescription
• RefNoteID
• ValueDescription

These changes affect

many entities.

BusinessAccount Business Accounts (CR303000) • The BusinessAccountAc-

tivityDetail detail entity
has been removed; Activity-
Detail is used instead.
• The BusinessAccountMar-
ketingListDetail detail
entity has been removed; the
MarketingListDetail de-
tail entity is used instead.
• The mapping has been changed.

AccountSummaryInquiry Account Summary (GL401000) In the AccountSummaryRow de-

tail entity, the following changes
have been made:
• The BeginingBalance field
has been renamed to Begin-
ningBalance.
• The CurrencyBegining-
Balance field has been re-
named to CurrencyBegin-
ningBalance.

Case Cases (CR306000) • The CaseActivityDetail

detail entity has been removed,
and the ActivityDetail de-
tail entity is used instead.
• The mapping has been changed.
• The type of Case.CaseRe-
latedCase.ParentCaseID
has been changed.

ChangeOrder Change Orders (PM308000) The mapping has been changed.

Contact Contacts (CR302000) The mapping has been changed.

 Configuring the REST API | 30

Entity Related Form Name and ID Change

Event Event (CR306030) • The mapping has been changed.

• The EventRelatedActiv-
ity detail entity has been re-
moved; ActivityDetail is
used instead.

ExpenseReceipt Expense Receipt (EP301020) The type and mapping of the Re-
ceiptID field have been changed.

Lead Leads (CR301000) The mapping has been changed.

NonStockItem Non-Stock Items (IN202000) • The type of the Attributes

field has been changed.
• The mapping has been changed.

Opportunity Opportunities (CR304000) The mapping has been changed.

Payment Payments and Applications The mapping has been changed.

(AR302000)

Project Projects (PM301000) The mapping has been changed.

TaxReportingSettings Reporting Settings (TX205100) The ReportingSettings enti-

ty has been renamed to TaxRe-
portingSettings.

SalesInvoice Invoices (SO303000) The mapping has been changed.

SalesOrder Sales Orders (SO301000) • The type of the Payments field

has been changed.
• The mapping has been changed.

Shipment Shipments (SO302000) The mapping has been changed.

Task Task (CR306020) • The type of the RelatedAc-

tivities field has been
changed.
• The mapping has been changed.

Table: New Fields and Actions

Field or Action Name Related Form Name and ID

Activity.CreatedByID Activity (CR306010)

Activity.CreatedDateTime Activity (CR306010)

Activity.LastModifiedDateTime Activity (CR306010)

Activity.RelatedEntityType Activity (CR306010)

Activity.RelatedEntityNoteID Activity (CR306010)

 Configuring the REST API | 31

Field or Action Name Related Form Name and ID

Activity.RelatedEntityDescription Activity (CR306010)

Activity.ActivityDetail.Billable Activity (CR306010)

Activity.ActivityDetail.Overtime Activity (CR306010)

Activity.ActivityDetail.BillableOvertime Activity (CR306010)

Activity.ActivityDetail.BillableTime Activity (CR306010)

Activity.ActivityDetail.Category Activity (CR306010)

Activity.ActivityDetail.CostCode Activity (CR306010)

Activity.ActivityDetail.CreatedDateTime Activity (CR306010)

Activity.ActivityDetail.LastModifiedDateTime Activity (CR306010)

Activity.ActivityDetail.CreatedByID Activity (CR306010)

Bill.LastModifiedDateTime Bills and Adjustments (AP301000)

BusinessAccount.NoteID Business Accounts (CR303000)

Carrier.CarrierUnits Carriers (CS207700)

Carrier.Centimeter Carriers (CS207700)

Carrier.Inch Carriers (CS207700)

Carrier.Kilogram Carriers (CS207700)

Carrier.Pound Carriers (CS207700)

Carrier.WarehouseID Carriers (CS207700)

Case.LastModifiedDateTime Cases (CR306000)

Case.NoteID Cases (CR306000)

Check.LastModifiedDateTime Checks and Payments (AP302000)

Check.VoidCheck Checks and Payments (AP302000)

Contact.NoteID Contacts (CR302000)

Email.StartDate Email Activity (CR306015)

Email.CreatedByID Email Activity (CR306015)

Email.CreatedDateTime Email Activity (CR306015)

Email.LastModifiedDateTime Email Activity (CR306015)

 Configuring the REST API | 32

Field or Action Name Related Form Name and ID

Email.NoteID Email Activity (CR306015)

Email.RelatedEntityType Email Activity (CR306015)

Email.RelatedEntityNoteID Email Activity (CR306015)

Email.RelatedEntityDescription Email Activity (CR306015)

Event.CreatedByID Event (CR306030)

Event.CreatedDateTime Event (CR306030)

Event.LastModifiedDateTime Event (CR306030)

Event.RelatedEntityType Event (CR306030)

Event.RelatedEntityNoteID Event (CR306030)

Event.RelatedEntityDescription Event (CR306030)

InventoryReceipt.LastModifiedDateTime Receipts (IN301000)

InventoryReceipt.InventoryReceiptDetail.PORe- Receipts (IN301000)

ceiptNbr

Invoice.BillToContact Invoices and Memos (AR301000)

Invoice.BillToContactOverride Invoices and Memos (AR301000)

Invoice.ShipToContact Invoices and Memos (AR301000)

Invoice.ShipToContactOverride Invoices and Memos (AR301000)

ItemWarehouse.OverrideProductManager Item Warehouse Details (IN204500)

KitAssembly.LastModifiedDateTime Kit Assembly (IN307000)

Lead.LastModifiedDateTime Leads (CR301000)

Lead.NoteID Leads (CR301000)

Lead.Active Leads (CR301000)

Lead.Description Leads (CR301000)

Lead.RefContactID Leads (CR301000)

Lead.ConvertedBy Leads (CR301000)

Lead.QualificationDate Leads (CR301000)

Opportunity.LastModifiedDateTime Opportunities (CR304000)

 Configuring the REST API | 33

Field or Action Name Related Form Name and ID

Opportunity.NoteID Opportunities (CR304000)

Payment.Branch Payments and Applications

(AR302000)

Payment.LastModifiedDateTime Payments and Applications

(AR302000)

Payment.ProcessingCenterID Payments and Applications

(AR302000)

Payment.SaveCard Payments and Applications

(AR302000)

Payment.CreditCardTransactionInfo Payments and Applications

(AR302000)

Payment.PaymentDetail.CashDiscountTaken Payments and Applications

(AR302000)

PurchaseOrder.BaseCurrencyID Purchase Orders (PO301000)

PurchaseOrder.CurrencyEffectiveDate Purchase Orders (PO301000)

PurchaseOrder.CurrencyRate Purchase Orders (PO301000)

PurchaseOrder.CurrencyRateTypeID Purchase Orders (PO301000)

PurchaseOrder.CurrencyReciprocalRate Purchase Orders (PO301000)

PurchaseReceipt.BaseCurrencyID Purchase Receipts (PO302000)

PurchaseReceipt.CurrencyEffectiveDate Purchase Receipts (PO302000)

PurchaseReceipt.CurrencyRate Purchase Receipts (PO302000)

PurchaseReceipt.CurrencyRateTypeID Purchase Receipts (PO302000)

PurchaseReceipt.CurrencyReciprocalRate Purchase Receipts (PO302000)

PurchaseReceipt.Location Purchase Receipts (PO302000)

PurchaseReceipt.ProcessReturnWithOriginalCost Purchase Receipts (PO302000)

PurchaseReceipt.TotalCost Purchase Receipts (PO302000)

PurchaseReceipt.PurchaseReceiptDetail.EditableUnit- Purchase Receipts (PO302000)

Cost

PurchaseReceipt.PurchaseReceiptDetail.Estimat- Purchase Receipts (PO302000)

edINExtendedCost

PurchaseReceipt.PurchaseReceiptDetail.ExtendedCost Purchase Receipts (PO302000)

 Configuring the REST API | 34

Field or Action Name Related Form Name and ID

PurchaseReceipt.PurchaseReceiptDetail.FinalINEx- Purchase Receipts (PO302000)

tendedCost

PurchaseReceipt.PurchaseReceiptDetail.POReceiptLi- Purchase Receipts (PO302000)

neNbr

PurchaseReceipt.PurchaseReceiptDetail.POReceiptNbr Purchase Receipts (PO302000)

PurchaseReceipt.PurchaseReceiptDetail.Transfer- Purchase Receipts (PO302000)

OrderLineNbr

SalesInvoice.DetailTotal Invoices (SO303000)

SalesInvoice.DiscountTotal Invoices (SO303000)

SalesInvoice.FreightPrice Invoices (SO303000)

SalesInvoice.PaymentTotal Invoices (SO303000)

SalesInvoice.TaxTotal Invoices (SO303000)

SalesOrder.SalesOrderDetail.Amount Sales Orders (SO301000)

Shipment.CreateNewShipmentForEveryOrder Shipments (SO302000)

Shipment.Description Shipments (SO302000)

Shipment.OverrideFreightPrice Shipments (SO302000)

Shipment.FreightCurrencyID Shipments (SO302000)

Shipment.Picked Shipments (SO302000)

Shipment.ShipmentPackage.PackageContents Shipments (SO302000)

Shipment.ShippingSettings.Freight Shipments (SO302000)

Shipment.ShippingSettings.FreightCost Shipments (SO302000)

Shipment.ShippingSettings.FreightCostIsuptodate Shipments (SO302000)

Shipment.ShippingSettings.FreightTaxCategory Shipments (SO302000)

Shipment.ShippingSettings.OrderVolume Shipments (SO302000)

Shipment.ShippingSettings.OrderWeight Shipments (SO302000)

Shipment.ShippingSettings.PackageWeight Shipments (SO302000)

Shipment.ShippingSettings.PremiumFreight Shipments (SO302000)

Task.CreatedByID Task (CR306020)

 Configuring the REST API | 35

Field or Action Name Related Form Name and ID

Task.CreatedDateTime Task (CR306020)

Task.LastModifiedDateTime Task (CR306020)

Task.RelatedEntityType Task (CR306020)

Task.RelatedEntityNoteID Task (CR306020)

Task.RelatedEntityDescription Task (CR306020)

TransferOrder.LastModifiedDateTime Transfers (IN304000)

Table: Removed Entities

Entity Related Form Name and ID

AccountByPeriodInquiry Account by Period (GL402000)

AccountBySubaccountInquiry Account by Subaccount (GL403000)

AccountDetailsInquiry Account Details (GL404000)

AccountLocation Account Locations (CR303010)

InterBranchAccountMapping Inter-Branch Account Mapping (GL101010)

JournalVoucher Journal Vouchers (GL304000)

ManageFinancialPeriods Manage Financial Periods (GL503000)

Payment.Payments Payments and Applications (AR302000)

SalesInvoice.SalesInvoiceTotals Invoices (SO303000)

VoucherEntryCode Voucher Entry Codes (GL106000)

Table: Removed Fields and Actions

Field or Action Name Related Form Name and ID

Activity.RelatedEntityDescription Activity (CR306010)

Activity.LinkEntityToActivity Activity (CR306010)

Activity.ActivityDetail.ClassIcon Activity (CR306010)

Activity.ActivityDetail.CreatedAt Activity (CR306010)

Activity.ActivityDetail.CreatorID Activity (CR306010)

Activity.ActivityDetail.CreatorUser- Activity (CR306010)

name
 Configuring the REST API | 36

Field or Action Name Related Form Name and ID

Activity.ActivityDetail.IsCompleteIcon Activity (CR306010)

Activity.ActivityDetail.PriorityIcon Activity (CR306010)

Activity.ActivityDetail.ReminderIcon Activity (CR306010)

BusinessAccount.ConvertBusinessAc- Business Accounts (CR303000)

countToVendor

Carrier.CarrierUnitOfWeight Carriers (CS207700)

Carrier.UOM Carriers (CS207700)

Contact.ConvertContactToBusinessAc- Contacts (CR302000)

count

Contact.CloseContactAsDuplicate Contacts (CR302000)

Email.Date Email Activity (CR306015)

Email.RelatedEntityDescription Email Activity (CR306015)

Email.StartTime Email Activity (CR306015)

Email.DownloadEmlFileEmail Email Activity (CR306015)

Email.LinkEntityToEmail Email Activity (CR306015)

Event.RelatedEntityDescription Event (CR306030)

Event.StartTime Event (CR306030)

Event.CompleteAndFollowUpEvent Event (CR306030)

Event.LinkEntityToEvent Event (CR306030)

FinancialPeriod.GeneratePeriods Master Financial Calendar (GL201000)

Invoice.ReverseInvoice Invoices and Memos (AR301000)

Lead.CloseLeadAsDuplicate Leads (CR301000)

Payment.PaymentLoadDocuments Payments and Applications (AR302000)

Payment.PaymentLoadOrders Payments and Applications (AR302000)

PurchaseOrder.EnterPOReceipt Purchase Orders (PO301000)

PurchaseOrder.EnterAPBill Purchase Orders (PO301000)

PurchaseReceipt.ControlAmount Purchase Receipts (PO302000)

PurchaseReceipt.TotalAmount Purchase Receipts (PO302000)

 Configuring the REST API | 37

Field or Action Name Related Form Name and ID

PurchaseReceipt.PurchaseReceiptDe- Purchase Receipts (PO302000)

tail.ExtendedCost

SalesInvoice.Totals Invoices (SO303000)

SalesInvoice.SalesInvoiceAddOrder Invoices (SO303000)

SalesInvoice.SalesInvoiceAutoApply Invoices (SO303000)

SalesOrder.SalesOrderAddStockItem Sales Orders (SO301000)

SalesOrder.SalesOrderCreatePurchase- Sales Orders (SO301000)

Order

Shipment.CurrencyID Shipments (SO302000)

Shipment.FreightCurrency Shipments (SO302000)

Task.RelatedEntityDescription Task (CR306020)

Task.CompleteAndFollowUpTask Task (CR306020)

Task.LinkEntityToTask Task (CR306020)

TimeEntry.Totals.Freight Time Entry (PM209100)

TimeEntry.Totals.FreightCost Time Entry (PM209100)

TimeEntry.Totals.FreightCostIsuptodate Time Entry (PM209100)

TimeEntry.Totals.FreightTaxCategory Time Entry (PM209100)

TimeEntry.Totals.OrderVolume Time Entry (PM209100)

TimeEntry.Totals.OrderWeight Time Entry (PM209100)

TimeEntry.Totals.PackageWeight Time Entry (PM209100)

TimeEntry.Totals.PremiumFreight Time Entry (PM209100)

TrialBalance.TrialBalanceProcess Trial Balance (GL303010)

TrialBalance.TrialBalanceProcessAll Trial Balance (GL303010)

TrialBalance.ReleaseTrialBalance Trial Balance (GL303010)

 Configuring the REST API | 38

Changes to the Entities, Fields, and Actions of the Default/22.200.001 Endpoint as

Compared to the Default/20.200.001 Endpoint

The following tables contain the new, modified, or removed elements of the Default/22.200.001 endpoint as
compared to the Default/20.200.001 endpoint.

Table: New Entities

Entity Related Form Name and ID

BigCommerceStores BigCommerce Stores (BC201000)

DeductionBenefitCode Deduction and Benefit Codes (PR101060)

EarningTypeCode Earning Type Codes (PR102000)

EmployeePayrollClass Employee Payroll Class (PR202000)

EmployeePayrollSettings Employee Payroll Settings (PR203000)

InventoryIssue Issues (IN302000)

InventoryQuantityAvailable Available Quantity by Inventory Item (GI640590)

PayGroup Pay Groups (PR205000)

PayPeriod Pay Periods (PR201000)

PayrollBatch Payroll Batches (PR301000)

PayrollUnionLocal Union Locals (PR209700)

PayrollWCCCode Workers' Compensation Codes (PR209800)

PTOBank PTO Banks (PR204000)

ShopifyStore Shopify Stores (BC201010)

TemplateItems Template Items (IN203000)

WorkCalendar Work Calendar (CS209000)

WorkLocation Work Locations (PR101040)

Table: Changed Entities

Entity Related Form Name and ID Change

LaborCostRate Labor Rates (PM209900) The set of fields has been changed.

ProjectTask Project Tasks (PM302000) The Attribute field has been re-
named to Attributes.
 Configuring the REST API | 39

Table: New Fields and Actions

Field or Action Name Related Form Name and ID

ChangeOrder.HoldChangeOrder Change Orders (PM308000)

ChangeOrder.RemoveChangeOrderFromHold Change Orders (PM308000)

Payment.VoidCardPayment Payments and Applications

(AR302000)

Payment.CardOperation Payments and Applications

(AR302000)

ProFormaInvoice.HoldProFormaInvoice Pro Forma Invoices (PM307000)

ProFormaInvoice.RemoveProFormaInvoiceFromHold Pro Forma Invoices (PM307000)

Project.ActivateProject Projects (PM301000)

Project.HoldProject Projects (PM301000)

Project.CompleteProject Projects (PM301000)

Project.SuspendProject Projects (PM301000)

Project.CancelProject Projects (PM301000)

ProjectTask.ActivateProjectTask Project Tasks (PM302000)

ProjectTask.CompleteProjectTask Project Tasks (PM302000)

ProjectTask.CancelProjectTask Project Tasks (PM302000)

ProjectTask.HoldProjectTask Project Tasks (PM302000)

ProjectTemplate.ActivateProjectTemplate Project Templates (PM208000)

ProjectTemplate.HoldProjectTemplate Project Templates (PM208000)

ChangeOrder.ChangeOrderCommitment.POType Change Orders (PM308000)

Contact.FullName Contacts (CR302000)

Payment.CreditCardTransactionInfo.OrigTranNbr Payments and Applications

(AR302000)

Payment.CreditCardTransactionInfo.ExpirationDate Payments and Applications

(AR302000)

Payment.CreditCardTransactionInfo.CardType Payments and Applications

(AR302000)

Customer.RestrictVisibilityTo Customers (AR303000)

 Configuring the REST API | 40

Field or Action Name Related Form Name and ID

Customer.CreditLimit Customers (AR303000)

Customer.NoteID Customers (AR303000)

Customer.EntityUsageType Customers (AR303000)

Customer.TaxExemptionNumber Customers (AR303000)

CustomerLocation.NoteID Customer Locations (AR303020)

CustomerPaymentMethod.CardType Customer Payment Methods

(AR303010)

CustomerPriceClass.NoteID Customer Price Classes (AR208000)

InventoryAdjustment.Details.CostCode Adjustments (IN303000)

InventoryAdjustment.Details.CostLayerType Adjustments (IN303000)

InventoryAdjustment.Details.Project Adjustments (IN303000)

InventoryAdjustment.Details.ProjectTask Adjustments (IN303000)

InventoryAdjustment.Details.SpecialOrderNbr Adjustments (IN303000)

NonStockItem.CrossReferences.UOM Non-Stock Items (IN202000)

InventoryReceipt.Details.CostLayerType Receipts (IN301000)

InventoryReceipt.Details.SpecialOrderNbr Receipts (IN301000)

ItemClass.CountryOfOrigin Item Classes (IN201000)

ItemClass.TariffCode Item Classes (IN201000)

ItemSalesCategory.SortOrder Item Sales Categories (IN204060)

ItemSalesCategory.NoteID Item Sales Categories (IN204060)

ItemWarehouse.MaxQty Item Warehouse Details (IN204500)

ItemWarehouse.OverrideServiceLevel Item Warehouse Details (IN204500)

ItemWarehouse.OverrideMaxQty Item Warehouse Details (IN204500)

ItemWarehouse.OverrideReorderPoint Item Warehouse Details (IN204500)

ItemWarehouse.OverrideSafetyStock Item Warehouse Details (IN204500)

ItemWarehouse.ReorderPoint Item Warehouse Details (IN204500)

ItemWarehouse.SafetyStock Item Warehouse Details (IN204500)

 Configuring the REST API | 41

Field or Action Name Related Form Name and ID

NonStockItem.CurySpecificMSRP Non-Stock Items (IN202000)

NonStockItem.CurySpecificPrice Non-Stock Items (IN202000)

NonStockItem.Availability Non-Stock Items (IN202000)

NonStockItem.ExportToExternal Non-Stock Items (IN202000)

NonStockItem.Categories Non-Stock Items (IN202000)

NonStockItem.Content Non-Stock Items (IN202000)

NonStockItem.CurrentStdCost Non-Stock Items (IN202000)

NonStockItem.CustomURL Non-Stock Items (IN202000)

NonStockItem.DimensionWeight Non-Stock Items (IN202000)

NonStockItem.FileUrls Non-Stock Items (IN202000)

NonStockItem.MetaDescription Non-Stock Items (IN202000)

NonStockItem.MetaKeywords Non-Stock Items (IN202000)

NonStockItem.MSRP Non-Stock Items (IN202000)

NonStockItem.NoteID Non-Stock Items (IN202000)

NonStockItem.PageTitle Non-Stock Items (IN202000)

NonStockItem.SearchKeywords Non-Stock Items (IN202000)

NonStockItem.TemplateItemID Non-Stock Items (IN202000)

NonStockItem.Visibility Non-Stock Items (IN202000)

NonStockItem.VendorDetails.Default Non-Stock Items (IN202000)

Payment.ExternalRef Payments and Applications

(AR302000)

Payment.OrigTransaction Payments and Applications

(AR302000)

Payment.BranchID Payments and Applications

(AR302000)

Payment.CustomerLocationID Payments and Applications

(AR302000)

Payment.IsNewCard Payments and Applications

(AR302000)
 Configuring the REST API | 42

Field or Action Name Related Form Name and ID

Payment.NoteID Payments and Applications

(AR302000)

Payment.AvailableBalance Payments and Applications

(AR302000)

Payment.AppliedToOrders Payments and Applications

(AR302000)

PaymentMethod.UseInPR Payment Methods (CA204000)

PaymentMethod.SetPaymentDatetoBankTransactionDate Payment Methods (CA204000)

PaymentMethod.SettingsForPR Payment Methods (CA204000)

PaymentMethod.AllowedCashAccounts.LastModifiedDate- Payment Methods (CA204000)

Time

PaymentMethod.AllowedCashAccounts.UseInPR Payment Methods (CA204000)

Project.GLAccounts.DefaultCostAccount Projects (PM301000)

Project.GLAccounts.DefaultCostSubaccount Projects (PM301000)

ProjectTask.DefaultValues.DefaultCostAccount Project Tasks (PM302000)

ProjectTask.DefaultValues.DefaultCostSubaccount Project Tasks (PM302000)

PurchaseOrder.IsTaxValid Purchase Orders (PO301000)

PurchaseReceipt.InventoryRefNbr Purchase Receipts (PO302000)

SalesInvoice.IsTaxValid Invoices (SO303000)

SalesOrder.ExternalOrderOriginal Sales Orders (SO303000)

SalesOrder.ExternalRefundRef Sales Orders (SO303000)

SalesOrder.WillCall Sales Orders (SO303000)

SalesOrder.PaymentRef Sales Orders (SO303000)

SalesOrder.NoteID Sales Orders (SO303000)

SalesOrder.UsrExternalOrderOriginal Sales Orders (SO303000)

SalesOrder.ExternalOrderOrigin Sales Orders (SO303000)

SalesOrder.ExternalOrderSource Sales Orders (SO303000)

SalesOrder.TaxCalcMode Sales Orders (SO303000)

SalesOrder.CreatedDate Sales Orders (SO303000)

 Configuring the REST API | 43

Field or Action Name Related Form Name and ID

SalesOrder.Payments.CreditCardTransactionInfo.Card- Sales Orders (SO303000)

Type

SalesOrder.Details.CustomerOrderNbr Sales Orders (SO303000)

SalesOrder.Details.SchedOrderDate Sales Orders (SO303000)

SalesOrder.Details.ShipToLocation Sales Orders (SO303000)

SalesOrder.Details.TaxZone Sales Orders (SO303000)

SalesOrder.Details.AssociatedOrderLineNbr Sales Orders (SO303000)

SalesOrder.Details.GiftMessage Sales Orders (SO303000)

SalesOrder.Details.ManualPrice Sales Orders (SO303000)

SalesOrder.Details.LotSerialNbr Sales Orders (SO303000)

SalesOrder.Details.NoteID Sales Orders (SO303000)

SalesOrder.Details.ExternalRef Sales Orders (SO303000)

SalesOrder.Details.InvoiceLineNbr Sales Orders (SO303000)

SalesOrder.Details.InvoiceNbr Sales Orders (SO303000)

SalesOrder.Details.InvoiceType Sales Orders (SO303000)

SalesOrder.Details.PurchaseWarehouse Sales Orders (SO303000)

SalesOrder.Details.PurchasingDetails Sales Orders (SO303000)

SalesOrder.Details.VendorID Sales Orders (SO303000)

SalesOrder.Details.Allocations.CustomerOrderNbr Sales Orders (SO303000)

SalesOrder.Details.Allocations.SchedOrderDate Sales Orders (SO303000)

SalesOrder.Payments.ExternalRef Sales Orders (SO303000)

SalesOrder.Payments.NoteID Sales Orders (SO303000)

SalesOrder.Shipments.InventoryNoteID Sales Orders (SO303000)

SalesOrder.Shipments.LastModifiedDateTime Sales Orders (SO303000)

SalesOrder.Shipments.OrderNoteID Sales Orders (SO303000)

SalesOrder.Shipments.ShippingNoteID Sales Orders (SO303000)

SalesPricesInquiry.SalesPriceDetails.NoteID Sales Prices (AR202000)

 Configuring the REST API | 44

Field or Action Name Related Form Name and ID

SalesPricesInquiry.SalesPriceDetails.Warehouse Sales Prices (AR202000)

SalesPricesInquiry.SalesPriceDetails.TaxCalcula- Sales Prices (AR202000)

tionMode

SalesPricesInquiry.TaxCalculationMode Sales Prices (AR202000)

Shipment.NoteID Shipments (SO302000)

Shipment.Orders.OrderNoteID Shipments (SO302000)

Shipment.Packages.LineNbr Shipments (SO302000)

Shipment.Packages.NoteID Shipments (SO302000)

Shipment.Packages.PackageContents.OrigOrderNbr Shipments (SO302000)

Shipment.Packages.PackageContents.OrigOrderType Shipments (SO302000)

ShippingBox.LinearUOM Boxes (CS207600)

SalesOrder.ShippingSettings.OverrideFreightPrice Sales Orders (SO303000)

StockItem.CurySpecificMSRP Stock Items (IN202500)

StockItem.CurySpecificPrice Stock Items (IN202500)

StockItem.Availability Stock Items (IN202500)

StockItem.CustomURL Stock Items (IN202500)

StockItem.ExportToExternal Stock Items (IN202500)

StockItem.FileURLs Stock Items (IN202500)

StockItem.MetaDescription Stock Items (IN202500)

StockItem.MetaKeywords Stock Items (IN202500)

StockItem.NoteID Stock Items (IN202500)

StockItem.PageTitle Stock Items (IN202500)

StockItem.SearchKeywords Stock Items (IN202500)

StockItem.TemplateItemID Stock Items (IN202500)

StockItem.Visibility Stock Items (IN202500)

StockItem.NotAvailable Stock Items (IN202500)

StockItem.CountryOfOrigin Stock Items (IN202500)

 Configuring the REST API | 45

Field or Action Name Related Form Name and ID

StockItem.TariffCode Stock Items (IN202500)

SalesOrder.TaxDetails.CustomerTaxZone Sales Orders (SO303000)

SalesOrder.Totals.Freight Sales Orders (SO303000)

SalesOrder.Totals.FreightCost Sales Orders (SO303000)

SalesOrder.Totals.FreightCostIsuptodate Sales Orders (SO303000)

SalesOrder.Totals.FreightTaxCategory Sales Orders (SO303000)

SalesOrder.Totals.OrderVolume Sales Orders (SO303000)

SalesOrder.Totals.OrderWeight Sales Orders (SO303000)

SalesOrder.Totals.PackageWeight Sales Orders (SO303000)

SalesOrder.Totals.PremiumFreight Sales Orders (SO303000)

SalesOrder.Totals.OverrideFreightAmount Sales Orders (SO303000)

TransferOrder.Details.CostCode Transfers (IN304000)

TransferOrder.Details.Project Transfers (IN304000)

TransferOrder.Details.ProjectTask Transfers (IN304000)

TransferOrder.Details.SpecialOrderNbr Transfers (IN304000)

TransferOrder.Details.ToCostCode Transfers (IN304000)

TransferOrder.Details.ToCostLayerType Transfers (IN304000)

TransferOrder.Details.ToProject Transfers (IN304000)

TransferOrder.Details.ToProjectTask Transfers (IN304000)

TransferOrder.Details.ToSpecialOrderNbr Transfers (IN304000)

Table: Renamed Fields and Actions

Old Field or Action New Field or Action Name Related Form Name and ID

Shipment.FreightAmount FreightPrice Shipments (SO302000)

SalesOrder.ShippingSet- FreightPrice Sales Orders (SO301000)

tings.Freight
 Configuring the REST API | 46

Table: Removed Entities

Field or Action Name Related Form Name and ID

AllocationRule Allocation Rules (PM207500)

CommonTask Common Tasks (PM208030)

ProjectBilling Run Project Billing (PM503000)

ProjectBillingRules Billing Rules (PM207000)

Table: Removed Fields and Actions

Field or Action Name Related Form Name and ID

SalesOrder.SalesOrderAddInvoice Sales Orders (SO301000)

ChangeOrder.Commitments.OpenAmount Change Orders (PM308000)

ChangeOrder.RevenueBudget.ActualAmount Change Orders (PM308000)

ChangeOrder.RevenueBudget.ActualQty Change Orders (PM308000)

ChangeOrder.RevenueBudget.Completed Change Orders (PM308000)

ChangeOrder.RevenueBudget.DraftInvoic- Change Orders (PM308000)

esAmount

ChangeOrder.RevenueBudget.OriginalBud- Change Orders (PM308000)

getedAmount

ChangeOrder.RevenueBudget.OriginalBud- Change Orders (PM308000)

getedQty

ItemWarehouse.OverrideServiceLevel- Item Warehouse Details (IN204500)

Override

SalesOrder.Details.PurchasingSettings Sales Orders (SO303000)

Contract-Based REST API of a Web Service Endpoint

Acumatica ERP provides you with the contract-based REST APIs of web service endpoints and with the contract-
based REST API of an Acumatica ERP instance. The methods of a REST API are provided in a swagger.json
file, which is an OpenAPI 2.0 (formerly known as Swagger 2.0) file. For more information about the OpenAPI
specification, see https://www.openapis.org. You can use the swagger.json files to review the APIs of the instance
and endpoints and build the client applications for Acumatica ERP based on these files.
You can retrieve the swagger.json file of a web service endpoint by clicking View Endpoint Service > OpenAPI
2.0 on the Web Service Endpoints (SM207060) form or by using the following URL.

http://<Base endpoint URL>/swagger.json

 Configuring the REST API | 47

In this URL, <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to
work with Acumatica ERP. This URL has the following format.

http://<Acumatica ERP instance URL>/entity/<Endpoint name>/<Endpoint version>/

You can specify the company URL parameter to obtain information on the API of the endpoint available in a
particular company. For example, suppose that you want to retrieve the API reference of the custom endpoint with
the name MyEndpoint and Version 18.200.001 available in the MyCompany company from a local Acumatica ERP
instance with the name AcumaticaDB. You would use the following URL to obtain the swagger.json file: http://
localhost/AcumaticaDB/entity/MyEndpoint/18.200.001/swagger.json?company=MyCompany.
If no company is specified, the API of the endpoint available in the company to which the user is currently logged in
is returned.

Contract-Based REST API of an Instance

You can retrieve the swagger.json file of an Acumatica ERP instance by using the following URL.

http://<Acumatica ERP instance URL>/entity/swagger.json

For example, if you use a local instance with the name AcumaticaU100, you would retrieve the swagger.json file
related to this instance by using the following URL: http://AcumaticaU100/entity/swagger.json.
The contract-based REST API of an instance contains the methods that do the following:
• Signing in to Acumatica ERP
• Signing out from Acumatica ERP
• Getting the Acumatica ERP version

Representation of a Record in JSON Format

By using the contract-based REST API, you obtain existing records from Acumatica ERP, create new records, update,
and delete them. You work with the records in Acumatica ERP by using the entities that are defined in the contract
of the endpoint that you use to access the service. You pass records to and receive them from the contract-based
REST API in JavaScript object notation (JSON) format. JSON is a text format for transmitting data objects that
consist of key-value pairs.
To represent a record in JSON format, you use the rules that are described in the following sections. You do not
need to specify the values of all fields of an entity; you can specify the values of only the needed fields.

System Fields
You specify the value of a system field (such as id or rowNumber) of an entity in the following format.

<Field name> : <Value>

For example, if you need to specify the row number 1 for an entity, you use the following string.

"rowNumber" : 1

To specify the value of the note field, you use this format only for Contract Version 3 or earlier. For Contract
Version 4, you specify the note field in the same way as you would any general field (see the next section).
 Configuring the REST API | 48

General Fields
You specify the value of a general field (that is, a field that is not a system field) of an entity in the following format.

<Field name> : {"value" : <Value>}

For example, if you need to specify JOHNGOOD as the customer ID of a customer record, you use the following
string.

"CustomerID" : {"value" : "JOHNGOOD"}

For Contract Version 4, a response can have any number of error fields that contain the validation errors, as in the
following example.

"CustomerID": {
"value": "ABARTENDE1",
"error": "'Customer' cannot be found in the system."
}

Linked Entities
You specify the values of the fields of a linked entity in the following format.

<Field name> :
{
<List of fields of the linked entity with values>
}

For example, if you need to specify the values of an email address and the address of a customer main contact, you
use the following string.

"MainContact" :
{
"Email" : {"value" : "[email protected]" },
"Address" :
{
"AddressLine1" : {"value" : "4030 Lake Washington Blvd NE" },
"AddressLine2" : {"value" : "Suite 100" },
"City" : {"value" : "Kirkland" },
"State" : {"value" : "WA" },
"PostalCode" : {"value" : "98033" }
}
}

Detail Entities
You specify the values of the fields of a detail entity in the following format.

<Field name> :
[
{
<List of fields of the detail entity with the values>
},
{
 Configuring the REST API | 49

<List of fields of the detail entity with the values>

},
…
]

For example, if you need to specify the values of two detail lines of a sales order, you use the following string.

"Details" : [
{
"InventoryID" : {"value": "AALEGO500"},
"Quantity" : {"value": 10},
"UOM" : {"value": "PIECE"}
},
{
"InventoryID" : {"value": "CONGRILL"},
"Quantity" : {"value": 1},
"UOM" : {"value": "PIECE"}
}
]

Custom Fields
You specify the values of the custom fields (that is, the fields that are not included in the contract of the endpoint)
in the following format.

Custom fields can correspond to the following elements:

• The predefined elements on an Acumatica ERP form that are not included in the entity
definition
• The elements that were added to the Acumatica ERP form in a customization project
• The user-defined fields

"custom" :
{
<View name> :
{
<Field name> :
{
"type" : <value>,
"value" : <value>
}
}
}

You use this block in the JSON representation of the entity (top-level, detail, or linked) that contains this custom
field.

For details on how to find out the field name and the name of the data view, see Custom Fields.

For example, suppose that you added the Personal ID element to the Main Contact area of the Customers
(AR303000) form in a customization project. The Contact entity, which is available through the MainContact
property of the Customer entity, contains the Personal ID custom element. This element has the
UsrPersonalID field name and belongs to the DefContact data view. The type of the element depends on
the contract version (in Contract Version 2, String; in Contract Version 3, CustomStringField). Therefore, to
 Configuring the REST API | 50

specify the value AB123456 of the Personal ID custom element for the customer with ID JOHNGOOD through the
REST API, you use one of the following strings depending on the contract version of the endpoint:
• For Contract Version 3
{
"CustomerID" : {value : "JOHNGOOD" } ,
"MainContact" :
{
"custom" :
{
"DefContact" :
{
"UsrPersonalID" :
{
"type" : "CustomStringField",
"value" : "AB123456"
}
}
}
}
}

• For Contract Version 2

{
"CustomerID" : {value : "JOHNGOOD" } ,
"MainContact" :
{
"custom" :
{
"DefContact" :
{
"UsrPersonalID" :
{
"type" : "String",
"value" : "AB123456"
}
}
}
}
}

To Create a Custom Endpoint

You use the Web Service Endpoints (SM207060) form to create a custom endpoint.
If you need to use a custom endpoint, you can either create an endpoint from scratch or extend an existing
endpoint with the needed API. This procedure describes how to create a custom endpoint from scratch. To learn
how to extend an existing endpoint, see To Extend an Existing Endpoint.
 Configuring the REST API | 51

To Create an Endpoint from Scratch

You can create an endpoint that has the latest version of the contract only.

1. Open the Web Service Endpoints (SM207060) form.

2. In the Endpoint Name box, type the name of the new endpoint.

For details on the characters that can be used in the endpoint name and version, see Naming
Rules for Endpoints.

3. In the Endpoint Version box, type the version of the new endpoint.
4. Add the needed entities, fields, and actions to the contract of the created endpoint, as described in the
sections below.
5. Click Save on the form toolbar.

To Add a Top-Level Entity to the Contract of the Endpoint

1. In the Endpoint Name box, select the name of the endpoint to which you want to add an entity.
2. In the Endpoint Version box, select the version of the endpoint to which you want to add an entity.
3. In the le pane, select the Endpoint node.
4. On the toolbar of the le pane, click Insert, and in the Create Entity dialog box, specify the values as
follows, and click OK:
a. In the Object Name box, type the name of the entity. This is the name of the API object that you will use
in the code of your application to work with the entity.

For details on the characters that can be used in the entity names, see Naming Rules for
Endpoints.

b. In the Screen Name lookup box, select the form to which the entity should correspond.
5. Add the needed fields, actions, or nested entities to the entity, as described in the sections below.

To Add a Linked or Detail Entity to Another Entity

1. In the Endpoint Name box, select the name of the endpoint to which you want to add an entity.
2. In the Endpoint Version box, select the version of the endpoint to which you want to add an entity.
3. In the le pane, select the entity node to which you want to add a linked or detail entity.
4. On the toolbar of the le pane, click Insert.
5. In the Field Name box of the Create Entity dialog box, which opens, type the name of the field that should
be used to access the nested entity, and specify the values of other elements in one of the following ways:
• If you want to insert an entity that already exists in the contract, select the Use Existing Entity check
box, and select the needed entity in the Entity Type box.
• If you want to insert a new entity, in the Object Name box, type the name of the entity, and in the
Object Type box, select the type of the entity: Top-Level, Linked, or Detail. If you have selected the top-
level entity to be inserted, in the Screen Name lookup box, specify the form to which the entity should
correspond.
 Configuring the REST API | 52

For details on the characters that can be used in the entity names, see Naming Rules for
Endpoints.

6. Click OK. The new entity appears in the contract.

7. Add fields to the created entity, as described in the following section.

To Add Fields to an Entity

1. In the Endpoint Name box, select the name of the endpoint to which you want to add an entity.
2. In the Endpoint Version box, select the version of the endpoint to which you want to add an entity.
3. In the le pane, select the entity node to which you want to add fields.
4. On the Fields tab of the right pane, do one of the following:
• Click Populate on the tab toolbar. In the Populate Fields dialog box, select the Acumatica ERP object
whose fields you want to include in the entity and the fields that you want to include, and click OK. The
selected fields are added to the contract.
• Click Add Row on the tab toolbar; then type the name of the new field in the Field Name column of the
added row, select the Acumatica ERP object whose field you want to include in the entity in the Mapped
Object column, and select the field that you want to include in the Mapped Field column.

• For some fields to be included in the entity, the corresponding Acumatica ERP feature or
features must be enabled on the Enable/Disable Features (CS100000) form. For information
on Acumatica ERP basic functionality and add-on features, see Preparing an Instance:
Acumatica ERP Features.
• For details on the characters that can be used in the field names, see Naming Rules for
Endpoints.

5. Click Save on the form toolbar.

To Add an Action to an Entity

You can add actions that are performed on multiple records (such as the removal of all records or
those the user selects) to processing forms only. Actions that can be performed on multiple records
are not supported for data entry and maintenance forms.

1. In the Endpoint Name box, select the name of the endpoint to which you want to add an entity.
2. In the Endpoint Version box, select the version of the endpoint to which you want to add an entity.
3. In the le pane, select the Actions node in the needed entity.
4. On the toolbar of the le pane, click Insert.
5. In the Create Action dialog box, which opens, select the needed Acumatica ERP action, type the name that
should be used to invoke this action through the API, and click OK. The dialog box is closed, and the new
action is added to the contract.

For details on the characters that can be used in the action names, see Naming Rules for
Endpoints.

6. If the action has parameters, add the parameters to the action as follows:
a. In the le pane, click the action you have created.
b. On the Parameters tab of the right pane, do one of the following:
 Configuring the REST API | 53

• Click Populate on the tab toolbar. In the Populate Fields dialog box, which opens, select the
Acumatica ERP object whose fields you want to use as parameters of the action and the fields that
you want to use as parameters, and click OK. The selected fields are added to the contract.
• Click Add Row on the tab toolbar; then type the name of the new parameter in the Parameter Name
column of the added row, select the Acumatica ERP object whose field you want to use a parameter of
the action in the Mapped Object column, and select the field that you want to use as a parameter in
the Mapped Field column.

• For details on the characters that can be used in the parameter names, see Naming
Rules for Endpoints.
• If you need to add parameters of a workflow action, select the Transition Parameters
object as the object whose fields you want to use as parameters. For details about
workflow actions, see Action Configuration: General Information in the Workflow Guide.

7. On the form toolbar, click Save.

To Extend an Existing Endpoint

You use the Web Service Endpoints (SM207060) form to create an endpoint as an extension of an existing endpoint.
You may need to create an extension of an endpoint if you want to use the entities that are defined in the contract
of the existing endpoint but you also need some additional entities, fields, and actions in the contract. For example,
the contract of the system endpoint with the name Default and Version 20.200.001 contains the Address entity,
which includes the following fields: AddressLine1, AddressLine2, City, Country, PostalCode, State,
and Validated. Suppose that you want to add the new GPSCoordinates field to the Address entity of the
contract and use it with other API of the contract. You cannot edit the contract of the system endpoint; instead, you
should create an endpoint that is based on this system endpoint, and add the new GPSCoordinates field to the
Address entity of the contract of the new endpoint.
This procedure describes how to create an endpoint that is based on an existing endpoint.

To Extend an Existing Endpoint

1. Open the Web Service Endpoints (SM207060) form.
2. Select the endpoint that you want the new endpoint to be based on as follows:
a. Select the name of the base endpoint in the Endpoint Name box.
b. Select the version of the base endpoint in the Endpoint Version box.
3. Click Extend Endpoint on the form toolbar.
4. In the Extend Current Endpoint dialog box, which opens, make sure the correct name and version of the
base endpoint are specified in the Base Endpoint Name and Base Endpoint Version boxes. Specify the
name of the new endpoint in the Endpoint Name box and the version of the new endpoint in the Endpoint
Version box and click OK.

For details on the characters that can be used in the endpoint name and version, see Naming
Rules for Endpoints.

The new endpoint with the name and version you specify appears on the form. On the le pane of the form,
you can see the list of entities that were inherited from the base endpoint.
5. Add the needed entities, fields, and actions to the contract of the created endpoint, as described in To
Create a Custom Endpoint, or extend the entities inherited from the base endpoint, as described in To Extend
an Existing Entity.
 Configuring the REST API | 54

6. Click Save on the form toolbar.

To Extend an Existing Entity

1. Select the extended endpoint in which you want to extend an entity inherited from the base endpoint as
follows:
a. In the Endpoint Name box, select the name of the extended endpoint.
b. In the Endpoint Version box, select the version of the extended endpoint.
2. In the le pane, select the entity inherited from the base endpoint to which you want to add new fields,
linked or detail entities, or actions.
3. If you want to add fields to the entity, do the following:
a. On the toolbar of the Fields tab in the right pane, click Extend Entity.
b. Use the Add Row, Delete Row, and Populate buttons, which have become available on the tab toolbar,
to add and delete fields of the entity. For more details, see To Add Fields to an Entity.
4. If you want to add actions or linked or detail entities, follow the instructions in To Create a Custom Endpoint.
5. Click Save on the form toolbar.

To Validate an Endpoint

You use the Web Service Endpoints (SM207060) form to validate an endpoint, an entity, or an action. During this
validation, the system makes sure the following criteria are met for the elements of the endpoint, entity, or action:
• The names of the elements satisfy the naming rules. For details on these rules, see Naming Rules for
Endpoints.
• The elements are mapped to objects, fields, and actions that exist in the system.
The validation of the name of a new entity, field, action, or action parameter is performed automatically once you
have entered the name on the form. You can validate an endpoint, entity, or action manually, as described in this
topic.

To Validate an Endpoint
1. Open the Web Service Endpoints (SM207060) form.
2. Select the endpoint that you want to validate as follows:
a. In the Endpoint Name box, select the name of the endpoint.
b. In the Endpoint Version box, select the version of the endpoint.
3. On the form toolbar, click Validate Endpoint. The long-running validation operation starts.
Once the validation is finished, the system displays a message with the results of the validation. If the
validation has failed, the error message contains the names of all fields that caused the error.
4. If any errors occur, correct the endpoint accordingly.

To Validate an Entity
1. Open the Web Service Endpoints (SM207060) form.
2. Select the endpoint that contains the entity that you want to validate as follows:
a. In the Endpoint Name box, select the name of the endpoint.
 Configuring the REST API | 55

b. In the Endpoint Version box, select the version of the endpoint.

3. In the le pane, click the entity that you want to validate.
4. On the toolbar of the Fields tab of the right pane, click Validate Entity.
Once the validation is finished, the system displays a message with the results of the validation. If the
validation has failed, the error message contains the names of all fields that caused the error.
5. If any errors occur, correct the entity accordingly.

To Validate an Action
1. Open the Web Service Endpoints (SM207060) form.
2. Select the endpoint that contains the action that you want to validate as follows:
a. In the Endpoint Name box, select the name of the endpoint.
b. In the Endpoint Version box, select the version of the endpoint.
3. In the le pane, click the action that you want to validate.
4. On the toolbar of the Parameters tab of the right pane, click Validate Action.
Once the validation is finished, the system displays a message with the results of the validation. If the
validation has failed, the error message contains the names of all fields that caused the error.
5. If any errors occur, correct the action accordingly.

To Import a REST Schema to a Visual Studio Solution

You can create a Visual Studio project and use the REST schema contained in the Acumatica ERP swagger.json
files for interaction with Acumatica ERP. You import the REST schema to a Visual Studio solution in two stages:
1. You generate Visual Studio packages from the REST schema.
2. You include the generated Visual Studio packages in your Visual Studio solution.

The following sections provide instructions on these stages, as well as an example of the use of the imported REST
schema.

To Generate Visual Studio Packages from a REST Schema

1. Obtain the swagger.json file you need.
2. Open the website https://editor.swagger.io.
3. Insert the contents of the swagger.json file into the website's edit box.
The website suggests that you convert the JSON contents to YAML format.
4. Click OK to agree to the suggestion or Cancel to leave the contents in JSON format; neither of these actions
affects the result of parsing the file.
The website engine parses the REST schema contained in the swagger.json file and create the visual
representation of the REST schema.
5. On the Generate Client menu, invoke the csharp command.
The csharp-client-generated.zip archive is downloaded to your computer. The archive contains
the IO.Swagger Visual Studio solution, two Visual C# projects (IO.Swagger and IO.Swagger.Test), and other
files.
6. Extract the csharp-client-generated.zip archive.
 Configuring the REST API | 56

7. Make sure that the IO.Swagger solution can be built.

To compile the IO.Swagger and IO.Swagger.Test projects, you may have to explicitly specify the path
to the RestSharp.dll library. In addition, you may get compilation errors related to the misuse
of the override keyword and the absence of the BaseValidate method. To fix these errors,
remove the misused override keyword and the entire command that contains the nonexistent
BaseValidate method.

To Add the Generated Projects to a Visual Studio Solution

1. In Visual Studio, create a C# project.
2. In your project, add a reference to the Newtonsoft.Json library as follows:
a. In Solution Explorer, right-click your project.
b. Click Manage NuGet Packages.
c. Select the Browse tab.
d. Search for the Newtonsoft.Json library, and install it.
3. In the folders containing the unpacked contents from the csharp-client-generated.zip archives,
rename the IO.Swagger projects and the IO.Swagger namespaces to avoid the name conflict.
You do not have to add the IO.Swagger.Test projects to the solution of your C# project.
4. Add the former IO.Swagger projects to the solution of your C# project.
5. In your project, add a reference to the RestSharp.dll library that is used by either of the added projects.
6. Add your code that uses the REST API to your project.

Example of the Use of the Imported REST Schema

Following is an example of the use of the projects that are generated from swagger.json files. One
swagger.json file is related to an Acumatica ERP instance, and another swagger.json file is related to the
endpoint with the name Default and Version 18.200.001. The namespace of the instance REST API is renamed to
Instance_Api, and the namespace of the endpoint REST API is renamed to Default_18_Api. In the example,
sign-in occurs, all available sales orders are retrieved, and then sign-out is performed.

using Default_18_Api.Api;
using Default_18_Api.Model;
using Instance_Api.Api;
using Instance_Api.Model;
using System;
using System.Collections.Generic;
using System.Net;

namespace AC126585
{
class Program
{
const string SiteURL = "http://localhost/AcumaticaERP/"; // Specify your instance
const string Username = "admin";
const string Password = "123"; // Specify your admin password
const string Tenant = null;
const string Branch = null;
const string Locale = null;

static void Main(string[] args)

 Configuring the REST API | 57

{
Console.WriteLine("REST API example");

var authApi = new AuthApi(SiteURL);

try
{
authApi.Configuration.ApiClient.RestClient.CookieContainer = new
CookieContainer();

// Make an attempt to sign in

authApi.AuthLogin(new Credentials(Username, Password, Tenant, Branch,
Locale));
Console.WriteLine("Signed In...");

// Create a SalesOrderApi object to work with sales orders

SalesOrderApi salesOrderApi = new SalesOrderApi(SiteURL + "entity/
default/18.200.001");
// Use the cookies that are created while signing in
salesOrderApi.Configuration.ApiClient.RestClient.CookieContainer =
authApi.Configuration.ApiClient.RestClient.CookieContainer;
// Get all available sales orders
List<SalesOrder> salesOrders = salesOrderApi.SalesOrderGetList();
Console.WriteLine("Number of sales orders: " +
salesOrders.Count.ToString());
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
finally
{
// Signing out
authApi.AuthLogout();
Console.WriteLine("Signed Out...");
Console.ReadLine();
}
}
}
}

You can find other examples in the AcumaticaRESTAPIClientForCSharp repository on GitHub.

 REST API Examples | 58

REST API Examples

In this chapter, you can find code examples that show how to implement the integration of Acumatica ERP with
external systems through the contract-based REST API. Each example includes a short description, a user scenario
that you can implement by using this example, and a code snippet that uses the REST API to implement the
scenario. You can reuse these examples in your application.
You can find the REST examples in the Help-and-Training-Examples repository on GitHub. To test the examples, you
do the following:
1. Clone the 2021R2 branch of the repository or download its contents.
2. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
3. Find the examples in the IntegrationDevelopmentGuide.postman_collection.json file
(which is a Postman collection) of the IntegrationDevelopment\Help folder in the branch.
4. Specify the URL of the instance in the BaseURL variable of the collection.

Basic Requests

The contract-based representational state transfer (REST) application programming interface (API) of Acumatica
ERP provides the REST interface of the Acumatica ERP contract-based web services, through which external
systems can get data records from Acumatica ERP, process these records, and save new or updated records to
Acumatica ERP.
This chapter includes topics that are specific to the contract-based REST API. For general information on the
contract-based web services, see Configuring the REST API. You can find examples of how to use the contract-based
SOAP API in Working with the SOAP APIs.

Sign In to the Service

Each time your application starts working with the Acumatica ERP contract-based REST service, you have to sign in
to Acumatica ERP. To sign in to Acumatica ERP, you access the needed URL with the POST HTTP method and pass
the credentials in the request body. See details on the URL, parameters, HTTP method, HTTP headers, HTTP body,
and response format in the following sections.

Instead of directly signing in to Acumatica ERP, your application can use the OAuth 2.0 authorization.
For details about OAuth 2.0, see Authorizing Client Applications to Work with Acumatica ERP.

HTTP Method and URL

When you need to sign in to Acumatica ERP, you use the POST HTTP method and the following URL.

http://<Acumatica ERP instance URL>/entity/auth/login

You replace <Acumatica ERP instance URL> with the URL of your Acumatica ERP instance.
For example, suppose that you want to sign in to a local Acumatica ERP instance with the name AcumaticaDB. You
should use the following URL: http://localhost/AcumaticaDB/entity/auth/login.
 REST API Examples | 59

Parameters
You use no parameters when you sign in to Acumatica ERP.

HTTP Headers
You can specify the following header in the request.

Header Description

Content-Type Specifies the format of the request body, which can be one of the following:
• application/json
• text/json
• application/xml
• text/xml
• application/x-www-form-urlencoded

HTTP Body
In the request body, you pass the credentials for accessing Acumatica ERP in JSON format, as shown in the
following example.

{
"name" : "admin",
"password" : "123",
"tenant" : "MyStore",
"branch" : "MYSTORE",
"locale" : "EN-US"
}

You specify the values of the parameters as follows:

• name: The username that the application should use to sign in to Acumatica ERP, such as "admin".
• password: The password for the username, such as "123".
• tenant: The name of the tenant to which the application should sign in, such as "MyStore". You can view
the name that should be used for the tenant in the Login Name box of the Tenants (SM203520) form.
• branch: The ID of the branch to which the application should sign in. You can view the ID of the branch in the
Branch ID box of the Branches (CS102000) form.
• locale: The locale that should be used in Acumatica ERP. You should specify the locale in the
System.Globalization.CultureInfo format converted to string, as with "EN-US".

This parameter has been developed for future use. You do not need to set its value.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a sign-in request.
 REST API Examples | 60

Code Description

204 The request has been completed successfully. The response headers contain the cookies
that authorize the user to make further requests.

400 The data specified in the request is invalid.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of a sign in to Acumatica ERP through the REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST /auth/login HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity
Accept: application/json
Content-Type: application/json

{
"name" : "admin",
"password" : "123",
"tenant" : "MyTenant",
"branch" : "HEADOFFICE"
}

Usage Notes
For each attempt to sign in to Acumatica ERP as described in this topic, you must implement the signing out from
the service aer you finish your work with Acumatica ERP to close the session. For details about the signing out, see
Sign Out from the Service.

You should also take into account Acumatica ERP license API limits. For details, see License Restrictions for API
Users.

Sign Out from the Service

Each time your application finishes working with the Acumatica ERP contract-based REST service, you have to sign
out from Acumatica ERP. To sign out from Acumatica ERP, you access the needed URL address with the POST HTTP
method. See the following sections for details on the URL, parameters, HTTP method, and response format.
If your applications failed to sign out from Acumatica ERP and the maximum number of concurrent sessions
allowed by the license is reached, there is no way to forcibly terminate all sessions of the API users. Instead, a
sessions is automatically closed aer a 10-minute time-out.
 REST API Examples | 61

HTTP Method and URL

When you need to sign out from Acumatica ERP, you use the POST HTTP method and the following URL.

http://<Acumatica ERP instance URL>/entity/auth/logout

You replace <Acumatica ERP instance URL> with the URL of your Acumatica ERP instance.
For example, suppose that you want to sign out from a local Acumatica ERP instance with the name AcumaticaDB.
You should use the following URL: http://localhost/AcumaticaDB/entity/auth/logout.

Parameters
You use no parameters when you sign out from Acumatica ERP.

HTTP headers
You do not specify any header in the request.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a sign-out request.

Code Description

204 The request has been completed successfully.

400 The data specified in the request is invalid.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of a sign out from Acumatica ERP through the REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST /auth/logout HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity
Accept: application/json
Content-Type: application/json
 REST API Examples | 62

Create a Record

When you need to create a record by using the contract-based REST API, you access the needed URL address with
the PUT HTTP method and pass the record representation in JSON format in the request body. See the following
sections for details on the URL, parameters, HTTP method, HTTP body, HTTP headers, and response format.
You can create an entity with multiple detail lines by using a single PUT request. If you want to import records from
a CSV file, you can use an import scenario instead of the REST API.

HTTP Method and URL

To create a record in Acumatica ERP, you use the PUT HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to create a record.
For example, suppose that you want to create a stock item record in a local Acumatica ERP instance with the name
AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001. You should use the
following URL to create a record: http://localhost/AcumaticaDB/entity/Default/22.200.001/
StockItem.

Parameters
You can use the following parameters when you retrieve a record from Acumatica ERP:
• $expand: To specify the linked and detail entities to be expanded

In Contract Version 4, you are required to list in the $expand parameter every detail and
related entity that you are going to have in the response body. For Contract Version 2 and
3, the detail and related entities contained in the request body are also contained in the
response body, regardless of whether they are listed in the $expand parameter or not.

• $select: To specify the fields of the entity to be returned

• $custom: To specify the fields that are not defined in the contract to be returned
For detailed descriptions of the parameters, see Parameters for Retrieving Records.

HTTP Headers
You can specify the following headers in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json
 REST API Examples | 63

Header Description

Content-Type Specifies the format of the request body, which can be one of the following:
• application/json
• text/json

If-None-Match Changes the behavior of the PUT request, which normally either creates a new
record or updates an existing one. If you only want to create a new record, use the
optional If-None-Match header with the * (asterisk) value.

HTTP Body
You pass a record in JSON format in the request body. You can find details on how to represent a record in
JSON format in Representation of a Record in JSON Format. See below for an example of a customer record
representation in JSON format.

{
"CustomerID" : {value : "JOHNGOOD"},
"CustomerName" : {value : "John Good"},
"CustomerClass" : {value : "DEFAULT"},
"MainContact" :
{
"Email" : {value : "[email protected]"},
"Address" :
{
"AddressLine1" : {"value" : "4030 Lake Washington Blvd NE"},
"AddressLine2" : {"value" : "Suite 100"},
"City" : {"value" : "Kirkland"},
"State" : {"value" : "WA" },
"PostalCode" : {"value" : "98033"}
}
}
}

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that creates a record.

Code Description

200 The request has been completed successfully. The response of a successful method call
contains the created record in JSON format in the response body. The response includes
only the values of the fields of the created record that were specified during creation of
the record or that were specified to be returned by using the parameters of the request.

400 The data specified in the request is invalid.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.
 REST API Examples | 64

Code Description

412 You have used the If-None-Match header with the * value, and the record already ex-
ists.

422 This status code can be returned for Contract Version 4. The data specified in the request
is invalid and the validation errors are returned in the error fields of the response body,
as in the following example.

"CustomerID": {
"value": "ABARTENDE1",
"error": "'Customer' cannot be found in the system."
}

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of the creation of a Customer record in Acumatica ERP through the REST
API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Customer
Accept: application/json
Content-Type: application/json

{
"CustomerID" : {"value" : "JOHNGOOD"},
"CustomerName" : {"value" : "John Good"},
"CustomerClass" : {"value" : "DEFAULT"},
"MainContact" :
{
"Email" : {"value" : "[email protected]"},
"Address" :
{
"AddressLine1" : {"value" : "4030 Lake Washington Blvd NE"},
"AddressLine2" : {"value" : "Suite 100"},
"City" : {"value" : "Kirkland"},
"State" : {"value" : "WA" },
"PostalCode" : {"value" : "98033"}
}
}
}
 REST API Examples | 65

Usage Notes
A value can be set for a drop-down list (or a multiselect drop-down list) only if that value has been defined for the
control. If the value you attempt to set is not present in the control, an error message is generated. (For Contract
Version 4, the error message is added to the error field of the response.) For a multiselect drop-down list, only
internal (namely, not external or displayed) values can be specified.

Update a Record

When you need to update an existing record by using the contract-based REST API, you access the needed URL with
the PUT HTTP method and pass the record representation in JSON format in the request body. See the following
sections for details on the URL, parameters, HTTP method, HTTP body, HTTP headers, and response format.

HTTP Method and URL

If you need to update a record in Acumatica ERP, you use the PUT HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to update a record.
For example, suppose that you want to update a stock item record in a local Acumatica ERP instance with the
name AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001. You would use the
following URL to update a record: http://localhost/AcumaticaDB/entity/Default/22.200.001/
StockItem.

Parameters
You can use the following parameters when you are updating a record in Acumatica ERP:
• $filter: To specify filtering conditions that identify the record to be updated
• $expand: To specify the linked and detail entities to be expanded

In Contract Version 4, you must list in the $expand parameter every detail and related entity
that you are going to have in the response body. For Contract Version 2 and 3, the detail
and related entities contained in the request body are also contained in the response body,
regardless of whether they are listed in the $expand parameter or not.

• $select: To specify the fields of the entity to be returned

• $custom: To specify the fields that are not defined in the contract to be returned
For detailed descriptions of the parameters, see Parameters for Retrieving Records.

HTTP Headers
You can specify the following headers in the request.
 REST API Examples | 66

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Content-Type Specifies the format of the request body, which can be one of the following:
• application/json
• text/json

If-Match Changes the behavior of the PUT request, which normally either creates a new
record or updates an existing one. If you only want to update a record, use the op-
tional If-Match header with the * value.

HTTP Body
You pass a record in JSON format in the request body. You can find details on how to represent a record in JSON
format in Representation of a Record in JSON Format.
To make it possible for the record to be found by Acumatica ERP, you can use any of the following approaches:
• Specify the values of the key fields in the record representation in JSON format.
• Specify the value of the ID property in the record representation in JSON format.
• Specify the filtering conditions that identify the record in the $filter parameter of the method. For details on
the parameter, see the Parameters section in this topic.
If you want to delete a detail line during update, you should specify true as the value of the delete property
of the corresponding detail entity: "delete" : true. To identify the detail line to be deleted, you can specify
either the values of the key fields of the detail line or the value of the ID property.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that updates a record.

Code Description

200 The request has been completed successfully. The response body contains the updated
record in JSON format.

400 The data specified in the request is invalid.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

412 You have used the If-Match header with the * value, and the record does not exist.
 REST API Examples | 67

Code Description

422 This status code can be returned for Contract Version 4. The data specified in the request
is invalid and the validation errors are returned in the error fields of the response body,
as in the following example.

"CustomerID": {
"value": "ABARTENDE1",
"error": "'Customer' cannot be found in the system."
}

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of the update of an existing customer record that has the
[email protected] email address.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$filter=MainContact/Email%20eq%20'[email protected]'&
$select=CustomerID,CustomerClass,MainContact/Email&$expand=MainContact HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Customer
Accept: application/json
Content-Type: application/json

{
"CustomerClass" : {"value" : "ECCUSTOMER"}
}

Usage Notes
A value can be set for a drop-down list (or a multiselect drop-down list) only if that value has been defined for the
control. If the value you attempt to set is not present in the control, an error message is generated. (For Contract
Version 4, the error message is added to the error field of the response.) For a multiselect drop-down list, only
internal (namely, not external or displayed) values can be specified.

Retrieve a Record by Key Fields

To retrieve a record by the values of its key fields from Acumatica ERP by using the contract-based REST API, you
access the needed URL with the GET HTTP method and specify the fields that should be returned in the parameters
of the method. See the following sections for details on the URL, parameters, HTTP method, HTTP headers, and
response format.
 REST API Examples | 68

HTTP Method and URL

If you need to obtain a particular record with the known key fields, you use the GET HTTP method and the
following URL

http://<Base endpoint URL>/<Top-level entity>/<Key value 1>/<Key value 2>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to retrieve a record.
• <Key value 1> and <Key value 2> are the values of the key fields of the record to be retrieved. You
use the number and order of key fields as they are defined on the corresponding Acumatica ERP form.

You can pass the key fields separated by a vertical bar (|) instead of a slash (/). If the value of a
key field contains a slash, you need to refer to a record by its entity ID instead of the values of
its key fields.

For example, suppose that you want to retrieve the sales order with order type SO and order number 000123 from
a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default
and Version 22.200.001. You should use the following URL to retrieve the sales order: http://localhost/
AcumaticaDB/entity/Default/22.200.001/SalesOrder/SO/000123.

Parameters
You can use the following parameters when you retrieve a record from Acumatica ERP:
• $expand: To specify the linked and detail entities to be expanded
• $custom: To specify the fields that are not defined in the contract to be returned
• $select: To specify the fields of the entity to be returned
For detailed descriptions of the parameters, see Parameters for Retrieving Records.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves a record by the
values of key fields.
 REST API Examples | 69

Code Description

200 The request has been completed successfully. The response contains the requested
record.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of the retrieval of a SalesOrder record through the REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /SO/000001?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

Retrieve a Record by ID

To retrieve a record by the value of the entity ID from Acumatica ERP by using the contract-based REST API, you
access the needed URL with the GET HTTP method and specify the fields that should be returned in the parameters
of the method. See the following sections for details on the URL, parameters, HTTP method, HTTP headers, and
response format.

The entity ID is a GUID that is assigned to each entity you work with during an Acumatica ERP session.
You can obtain the value of the entity ID from the ID property of an entity returned from Acumatica
ERP.
The records of top-level entities that you retrieve through the contract-based REST API have
persistent IDs, which are the values in the NoteID column of the corresponding database tables.
That is, you can use the value from the ID property of a top-level entity returned from Acumatica
ERP throughout different sessions with Acumatica ERP. However, if a record does not have a note ID
(which could be the case for detail entities, entities that correspond to generic inquiries, or custom
entities), this record is assigned the entity ID that is new for each new session. That is, aer a new
login to Acumatica ERP, you cannot use the entity ID that you received in the previous session to work
with the entity.

Any REST API response contains the _links/self field for every top-level entity it returns. The value of this field
is part of the URL of a GET request to retrieve this top-level entity by its ID. The same URL can be used in a DELETE
request to delete this entity.
 REST API Examples | 70

HTTP Method and URL

If you need to obtain a particular record with the entity ID, you use the GET HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>/<Entity ID>

The URL has the following components:

• <Base endpoint URL> is the URL of a contract-based endpoint through which you are going to work
with Acumatica ERP. This URL has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to retrieve a record.
• <Entity ID> is the ID of the record to be retrieved.
For example, suppose that you want to retrieve the sales order with entity ID a6295b33-c7f6-e811-
b817-00155d408001 from a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint
with the name Default and Version 22.200.001. You should use the following URL to retrieve the sales order:
http://localhost/AcumaticaDB/entity/Default/22.200.001/SalesOrder/a6295b33-
c7f6-e811-b817-00155d408001.

Parameters
You can use the following parameters when you retrieve a record from Acumatica ERP:
• $expand: To specify the linked and detail entities to be expanded
• $select: To specify the fields of the entity to be returned
• $custom: To specify the fields that are not defined in the contract to be returned
For detailed descriptions of the parameters, see Parameters for Retrieving Records.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves a record by its
entity ID.

Code Description

200 The request has been completed successfully. The response body contains the requested
record.

401 The user is not signed in to the system.

 REST API Examples | 71

Code Description

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of the retrieval of a SalesOrder record with detail records by the entity
ID through the REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /a6295b33-c7f6-e811-b817-00155d408001?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

Retrieve Records by Conditions

To retrieve records that satisfy the specified conditions from Acumatica ERP by using the contract-based REST API,
you access the needed URL address with the GET HTTP method and specify filtering conditions in the parameters
of the method. See the following sections for details on the URL, parameters, HTTP method, HTTP headers, and
response format.

HTTP Method and URL

If you need to retrieve the list of records that satisfies the specified conditions, you use the GET HTTP method and
the following URL.

http://<Base endpoint URL>/<Top-level entity>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to retrieve the list of records.
For example, suppose that you want to retrieve the list of stock item records from a local Acumatica ERP instance
with the name AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001. You
should use the following URL to retrieve the list of records: http://localhost/AcumaticaDB/entity/
Default/22.200.001/StockItem.
 REST API Examples | 72

Parameters
You can use the following parameters when you retrieve records from Acumatica ERP:
• $filter: To specify filtering conditions on the records to be returned
• $skip: To specify the number of records to be skipped from the list of returned records
• $top: To specify the number of records to be returned in the list
• $expand: To specify the linked and detail entities to be expanded
• $select: To specify the fields of the entity to be returned
• $custom: To specify the fields that are not defined in the contract to be returned
For detailed descriptions of the parameters, see Parameters for Retrieving Records.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves records by
conditions.

Code Description

200 The request has been completed successfully. The response body contains the list of
records that satisfy the specified conditions.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of the retrieval of StockItem records that are Active and that have been
modified since the specified date.
 REST API Examples | 73

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$expand=WarehouseDetails&$filter=ItemStatus%20eq%20'Active'%20and%20LastModified%20gt
%20
datetimeoffset'2019-08-18T23%3A59%3A59.999%2B04%3A00' HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json

Usage Notes
When multiple records are retrieved from Acumatica ERP through an endpoint with Contract Version 3 or 4, the
system tries to optimize the retrieval of the records and obtain all needed records in one request to the database
(instead of requesting the records one by one). If the optimization fails, the system returns an error, which specifies
the entities or fields that caused the failure of the optimized request. To prevent the error from occurring, you can
do any of the following:
• If you do not need to retrieve the entities or fields that caused the failure, you can exclude these entities or
fields from the request as follows:
• Exclude the entities from the entities specified in the $expand parameter.
• Explicitly specify the other fields to be returned (while excluding the fields that caused the failure) by
using the $select parameter.
• If you need to retrieve the entities or fields that caused the failure, you can retrieve the needed records one
by one either Retrieve a Record by Key Fields, or Retrieve a Record by ID.

Retrieve Data from an Inquiry Form

To retrieve data from an inquiry form of Acumatica ERP by using the contract-based REST API, you access the
needed URL with the PUT HTTP method and pass the parameters of the inquiry in JSON format in the request
body. See the following sections for details on and examples of the URL, parameter, HTTP method, HTTP body,
HTTP headers, and response format.

HTTP Method and URL

If you need to retrieve data from an inquiry form, you use the PUT HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>

The URL includes the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity that corresponds to the inquiry form from which you are
going to retrieve data.
For example, suppose that you want to retrieve data from the Inventory Summary (IN401000) form in a local
Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default and
Version 22.200.001. You would use the following URL to retrieve data: http://localhost/AcumaticaDB/
entity/Default/22.200.001/InventorySummaryInquiry.
 REST API Examples | 74

Parameter
When you are retrieving data from an inquiry form, you should use the $expand parameter to expand the detail
entity, which contains the results of the inquiry. For a detailed description of the parameter, see Parameters for
Retrieving Records.

HTTP Headers
You can specify the following headers in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Content-Type Specifies the format of the request body, which can be one of the following:
• application/json
• text/json

HTTP Body
You pass parameters of the inquiry in JSON format in the request body. See below for an example of the
representation of parameters of the Inventory Summary inquiry form in JSON format.

{
"InventoryID" : {"value" : "APJAM08" } ,
"WarehouseID" : {"value" : "RETAIL" }
}

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves data from an
inquiry form.

Code Description

200 The request has been completed successfully. The response body contains the data re-
trieved from the inquiry form.

400 The data specified in the request is invalid.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).
 REST API Examples | 75

Code Description

500 An internal server error has occurred.

Example
The following request shows an example of the retrieval of data from the Inventory Summary (IN401000) inquiry
form.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Results HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/InventorySummaryInquiry
Accept: application/json
Content-Type: application/json

{
"InventoryID" : {"value" : "APJAM08" } ,
"WarehouseID" : {"value" : "RETAIL" }
}

Retrieve Records with Attributes

In Acumatica ERP, some records have attributes that are visible on the Attributes tab of the data entry form. For
details about attributes, see Attributes.
You may have to retrieve the records along with their attributes by using the contract-based REST API. To do this,
you access the needed URL with the GET HTTP method, and in the parameters of the request, you specify the
desired record fields and the fields that correspond to the needed attributes and attribute values. See the following
sections for details on and examples of the URL, parameters, HTTP method, HTTP headers, and response.

HTTP Method and URL

When you retrieve records from Acumatica ERP, you use the GET HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>

In this URL:
• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to retrieve the list of records
along with their attributes.
For example, suppose that you want to retrieve the list of contacts along with their attributes from a local
Acumatica ERP instance with the name AcumaticaDB, and you want to use the system endpoint with the
name Default and Version 22.200.001. You would use the following URL: http://localhost/AcumaticaDB/entity/
Default/22.200.001/Contact.
 REST API Examples | 76

Parameters
When you retrieve records along with their attributes, you should use the following parameters:
• $select: To list the desired record fields and the fields that correspond to the needed attributes and attribute
values
• $expand: To expand the detail entity that contains the fields that correspond to the attributes and attribute
values
For example, for the Contact entity, to retrieve the values of attributes of records, you need to specify
Attributes/AttributeID and Attributes/Value (or Attributes/ValueDescription) in the
$select parameter, and Attributes in the $expand parameter. To learn the exact names of the fields that
correspond to the attributes for a particular entity, you should review the fields of this entity on the Web Service
Endpoints (SM207060) form or refer to the OpenAPI specification of the endpoint. For more information on the
attribute fields, see Create a Contact with Attributes, section Usage Notes.
You can use other parameters as well; see Retrieve Records by Conditions. For a detailed description of the $select
and $expand parameters, see Parameters for Retrieving Records.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves records along
with their attributes.

Code Description

200 The request has been completed successfully. The response body contains the data re-
trieved from the Acumatica ERP instance in JSON format.

400 The data specified in the request is invalid.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

 REST API Examples | 77

Example
The following request is an example of the retrieval of the FirstName, LastName, and JobTitle fields of
contacts (that is, the Contact top-level entity), and the AttributeID and Value fields of the contacts’
attributes.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$expand=Attributes&$select=FirstName,LastName,JobTitle,Attributes/
AttributeID,Attributes/Value HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Contact
Accept: application/json

Following is an example of a response.

[
...
{
"id": "6a47c888-0b10-e911-9fbe-7c5cf8918e20",
"rowNumber": 20,
"note": {
"value": ""
},
"Attributes": [
{
"id": "dfe79fb3-b6a0-43a9-afa2-6641b943424d",
"rowNumber": 1,
"note": null,
"AttributeID": {
"value": "INTEREST"
},
"Value": {},
"custom": {}
}
],
"FirstName": {
"value": "Stephane"
},
"JobTitle": {
"value": "Customer Service & Network Manager"
},
"LastName": {
"value": "Sans"
},
"custom": {}
},
...
]
 REST API Examples | 78

Usage Notes
In the Default/20.200.001 and Default/22.200.001 endpoints, the attributes of top-level entities are exposed in the
AttributeValue entities. An AttributeValue entity has the following fields:
• AttributeID : The attribute identifier. Both internal values and external values can be used to set this
field, but only the internal value can be retrieved.
• AttributeDescription: The external value of the attribute identifier. The field is read-only.
• Value: The attribute value. When the value is retrieved, the internal value is returned. To set the value, the
internal value and the external value (for control types other than multi-select combo boxes) can be used.
For multi-select combo boxes, an external value can be accepted only if it contains a single value without
commas. For various control types, the following rules apply to the Value field:
• For check boxes, 0 is returned if the check box is not selected, and 1 is returned if the check box is
selected. For setting a value, 0, 1, false (case-insensitive), or true (case-insensitive) can be used.
• For multi-select combo boxes, values separated by commas (namely, Value1,Value2,Value3) compose the
internal value.
• For selectors, the values are set and retrieved in the same way as they are for text boxes.
• For date edit boxes, the internal values must be parsable through the use of the
System.Globalization.CultureInfo.InvariantCulture Microso .NET object.
• For combo boxes of all types, date edit boxes, and check boxes, an error message is written to the error
field when an attempt is made to set an unsupported value.
• ValueDescription: The external value of the attribute. The field is read-only. The external value is
based on the control type as follows:
• For text boxes and date edit boxes, the external value is the same as the internal value.
• For check boxes, the external value can be either True or False.
• For combo boxes, the label is used as the external value.
• For multi-select combo boxes, labels separated by commas and spaces aer commas (namely, Label1,
Label2, Label3) compose the external value.
• Required: An indicator of whether the attribute is mandatory. This field is read-only.
• RefNoteID: The value of the NoteID field of the object to which this attribute is referred. This field is
read-only.

Related Links
• Create a Contact with Attributes

Remove a Record by Key Fields

In the contract-based REST API, you can delete a record by the values of its key fields. To delete a record from
Acumatica ERP, you access the needed URL address with the DELETE HTTP method. See the following sections for
details on the possible URL, parameters, HTTP method, and response format.

If you need to delete a detail line of a record, you should use the PUT HTTP method, as described in
Update a Record.

HTTP Method and URL

If you need to delete a record with known key fields, you use the DELETE HTTP method and the following URL.
 REST API Examples | 79

http://<Base endpoint URL>/<Top-level entity>/<Key value 1>/<Key value 2>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to delete a record.
• <Key value 1> and <Key value 2> are the values of the key fields of the record to be deleted. You
use the number and order of key fields as they are defined on the corresponding Acumatica ERP form.

You can pass the key fields separated by a vertical bar (|) instead of a slash (/). If the value of a
key field contains a slash, you need to refer to a record by its entity ID instead of the values of
its key fields.

For example, suppose that you want to delete the sales order with order type SO and order number 000123 from
a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default
and Version 22.200.001. You should use the following URL to delete the sales order: http://localhost/
AcumaticaDB/entity/Default/22.200.001/SalesOrder/SO/000123.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that removes the record by the
values of its key fields or by its entity ID.

Code Description

204 The request has been completed successfully. The record is removed.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of the removal of the CGFEEDER stock item by the value of the key field.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

DELETE /CGFEEDER HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json
 REST API Examples | 80

Remove a Record by ID

In the contract-based REST API, you can delete a record by its session identifier. To delete a record from Acumatica
ERP, you access the needed URL address with the DELETE HTTP method. See the following sections for details on
the possible URL, parameters, HTTP method, and response format.
Any REST API response contains the _links/self field for every top-level entity it returns. The value of this field
is part of the URL of a GET request to retrieve this top-level entity by its ID. The same URL can be used in a DELETE
request to delete this entity.

If you need to delete a detail line of a record, you should use the PUT HTTP method, as described in
Update a Record.

HTTP Method and URL

If you need to delete a record with a known entity ID, you use the DELETE HTTP method and the following URL. For
details about entity IDs, see Retrieve a Record by ID.

http://<Base endpoint URL>/<Top-level entity>/<Entity ID>

You replace <Base endpoint URL> with the URL of the contract-based endpoint through which you are going
to work with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/. You replace <Top-level entity> with the name
of the entity for which you are going to retrieve the list of records. You replace <Entity ID> with the entity ID
(which is the GUID that you can obtain from the ID property of an entity returned from Acumatica ERP).
For example, suppose that you want to delete the sales order with entity ID 03efa858-2351-4bd5-ae06-3d9fb3b3c1e6
from a local Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the
name Default and Version 22.200.001. You should use the following URL to delete the sales order: http://
localhost/AcumaticaDB/entity/Default/22.200.001/SalesOrder/03efa858-2351-4bd5-
ae06-3d9fb3b3c1e6.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that removes a record by its
entity ID.

Code Description

204 The request has been completed successfully. The record is removed.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

 REST API Examples | 81

Example
The following request shows an example of the removal of the sales order with the ID 286F2AF0-21F5-
EB11-9DF1-9828A61840C3.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

DELETE /286F2AF0-21F5-EB11-9DF1-9828A61840C3 HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

Execute an Action That Is Present in an Endpoint

To perform an action that is present in an endpoint by using the contract-based REST API, you access the needed
URL with the POST HTTP method and pass the record representation in JSON format and the parameters of the
action in the request body. See the following sections for details on the URL, parameters, HTTP method, HTTP
body, HTTP headers, and response format.

HTTP Method and URL

If you need to perform an action on an Acumatica ERP form, you use the POST HTTP method and the following
URL.

http://<Base endpoint URL>/<Top-level entity>/<Action name>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to perform an action.
• <Action name> is the name of the action that you are going to perform.
For example, suppose that you want to confirm a shipment in a local Acumatica ERP instance with the
name AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001. You
would use the following URL to confirm a shipment: http://localhost/AcumaticaDB/entity/
Default/22.200.001/Shipment/ConfirmShipment.

HTTP Headers
You can specify the following headers in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json
 REST API Examples | 82

Header Description

Content-Type Specifies the format of the request body, which can be one of the following:
• application/json
• text/json

HTTP Body
You pass the record to which the action should be applied and the parameters of the action in the request body in
JSON format as follows.

{
"entity" : <record in JSON format>,
"parameters" : <parameters in JSON format>
}

You can find details on how to represent a record in JSON format in Representation of a Record in JSON Format.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that performs an action.

Code Description

202 The operation is in progress. The Location header of the response contains the URL
that you can use to check the status of the operation by using the GET HTTP method.
When the GET HTTP method with this URL returns 204 No Content, the operation is com-
pleted.

204 The operation that has been initiated by the action has completed or was not created.

400 The data specified in the request is invalid.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

404 The action with this name does not exist.

422 This status code can be returned for Contract Version 4. The data specified in the request
is invalid and the validation errors are returned in the error fields of the response body,
as in the following example.

"CustomerID": {
"value": "ABARTENDE1",
"error": "'Customer' cannot be found in the system."
}

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).
 REST API Examples | 83

Code Description

500 An internal server error has occurred.

Example

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

The following request shows an example of the reopening a Completed sales order through the REST API.

POST /ReopenSalesOrder HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"entity" :
{
"OrderType" : {"value" : "SO"},
"OrderNbr" : {"value" : "000001"}
},
"parameters" :
{}
}

The following request retrieves the status of the reopening operation.

GET /ReopenSalesOrder/status/a6295b33-c7f6-e811-b817-00155d408001 HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

Execute a Custom Action

Contract Version 4 allows you to execute actions that are not present in the endpoint. These actions can be defined
in the forms' graphs or in customization projects.
To perform an action by using the contract-based REST API, you access the needed URL with the POST HTTP
method and pass the record representation in JSON format and the parameters of the action in the request body.
See the following sections for details on the URL, parameters, HTTP method, HTTP body, HTTP headers, and
response format.
If an action is defined for a UI element, you can find out the action name as follows: on the title bar of the form,
you click Customization > Inspect Element and click the needed element on the form. In the Element Properties
dialog box, which opens, you find the action name in the Action Name element.
If an action is executed with parameters, you must also know the parameters' names and the view in which the
parameters are defined. For an action defined for a UI element, you can find out this information as follows:
Execute the action from the UI, press Ctrl+Alt, and click the parameter’s input box. In the Element Properties
 REST API Examples | 84

dialog box, which opens, you find the parameter name in the Data Field element and the view name in the View
Name element.

HTTP Method and URL

If you need to perform an action on an Acumatica ERP form, you use the POST HTTP method and the following
URL.

http://<Base endpoint URL>/<Top-level entity>/<Action name>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to perform an action.
• <Action name> is the name of the action that you are going to perform.
For example, suppose that you want to invoke the Close action of some Case entity in a local Acumatica ERP
instance with the name AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001.
You should use the following URL to invoke the action: http://localhost/AcumaticaDB/entity/
Default/22.200.001/Case/Close.

HTTP Headers
You can specify the following headers in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Content-Type Specifies the format of the request body, which can be one of the following:
• application/json
• text/json

HTTP Body
For the invocation of a custom action, an HTTP body with the following pattern is used.

{
"entity": {
"id": "<entity id>"
},
"parameters": {
"custom": {
...
}
}
}

In this pattern, the following information is provided:

 REST API Examples | 85

• <entity id> is the identifier of the entity for which you need to invoke a custom action. For more
information, see Retrieve a Record by ID. You can also use the key fields to define the entity.
• The custom collection contains the parameters of the action that are normally entered in a dialog box that
the system displays upon the execution of the action.
You can find details on how to represent a record in JSON format in Representation of a Record in JSON Format.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that performs an action.

Code Description

202 The operation is in progress. The Location header of the response contains the URL
that you can use to check the status of the operation by using the GET HTTP method.
When the GET HTTP method with this URL returns 204 No Content, the operation is com-
pleted.

204 The operation that has been initiated by the action has completed or was not created.

400 The data specified in the request is invalid.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

404 The action with this name does not exist.

422 This status code can be returned for Contract Version 4. The data specified in the request
is invalid and the validation errors are returned in the error fields of the response body,
as in the following example.

"CustomerID": {
"value": "ABARTENDE1",
"error": "'Customer' cannot be found in the system."
}

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
For example, suppose that you want to invoke the Close action of some Case entity in a local Acumatica ERP
instance with the name AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001.
The Close action has the only Reason parameter, which is defined in the FilterPreview view. Following is an
example of a request.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.
 REST API Examples | 86

POST / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Case/Close
Accept: application/json
Content-Type: application/json

{
"entity": {
"id": "e3f46a39-1a14-e911-816f-bc920a5e0ac8"
},
"parameters": {
"custom": {
"FilterPreview": {
"Reason": {
"type" : "CustomStringField",
"value" : "Abandoned"
}
}
}
}
}

Retrieve a File Attached to a Record

To retrieve a file that is attached to a record from Acumatica ERP by using the contract-based REST API, you
access the URL address of the file with the GET HTTP method. See the following sections for details on the URL,
parameters, HTTP method, HTTP header, and response format.

HTTP Method and URL

If you need to obtain a file attached to a record, you use the GET HTTP method and the following URL.

http://<Base endpoint URL>/files/<File identifier>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <File identifier> is the internal identifier of the file in the system.
To get this URL for a particular file attached to a record, you should obtain the record from Acumatica ERP and,
in the returned JSON representation of the record, find the value of the href property of the needed file in the
files array. For information on how to retrieve a record from Acumatica ERP, see Retrieve a Record by Key Fields
and Retrieve a Record by ID.
For example, suppose that you retrieved the stock item record that contains the following files array from a local
Acumatica ERP instance with the name AcumaticaDB.

{
...,
"files":[
{
"id":"9be45eb7-f97d-400b-96a5-1c4cf82faa96",
"filename":"Stock Items (AAMACHINE1)\\T2MCRO.jpg",
"href":
 REST API Examples | 87

"/AcumaticaDB/entity/Default/22.200.001/files/9be45eb7-f97d-400b-96a5-1c4cf82faa96"
}
]
}

You should use the following URL to retrieve the T2MCRO.jpg file attached to the stock item record: http://
localhost/AcumaticaDB/entity/Default/22.200.001/files/9be45eb7-f97d-400b-96a5-1c4cf82faa96.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves a file attached to
a record.

Code Description

200 The request has been completed successfully. The response contains the requested file.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

The following request shows an example of the retrieval of the list of files attached to the JUICER20C stock item.

GET /JUICER20C?$select=InventoryID,files&$expand=files HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json

Suppose that the request above returns the following response body.
 REST API Examples | 88

{
"id": "a0f8594a-7de2-e811-b816-00155d408001",
"rowNumber": 1,
"note": {
"value": ""
},
"InventoryID": {
"value": "EJECTOR03"
},
"custom": {},
"files": [
{
"id": "0a8ac74e-53d3-4f13-ba02-dbbf419da119",
"filename": "Stock Items (EJECTOR03 )\\T2MCRO.jpg",
"href": "[/<Acumatica ERP instance name>]/entity/Default/22.200.001/
files/dbcf82e7-660a-4d56-9b64-1cb654660ddb"
}
]
}
{
"id": "eb01ae69-7ee2-e811-b816-00155d408001",
"rowNumber": 1,
"note": {
"value": ""
},
"InventoryID": {
"value": "JUICER20C"
},
"custom": {},
"_links": {
"self": "/<Acumatica ERP instance name>/entity/Default/22.200.001/
StockItem/eb01ae69-7ee2-e811-b816-00155d408001",
"files:put": "/<Acumatica ERP instance name>/entity/Default/22.200.001/
files/PX.Objects.IN.InventoryItemMaint/Item/eb01ae69-7ee2-e811-b816-00155d408001/
{filename}"
},
"files": [
{
"id": "e77c0c80-2296-4ef9-9588-877692933f31",
"filename": "Stock Items (JUICER20C )\\commercial_citrus_juicer.jpg",
"href": "/<Acumatica ERP instance name>/entity/Default/22.200.001/
files/e77c0c80-2296-4ef9-9588-877692933f31"
}
]
}

The following request retrieves the commercial_citrus_juicer.jpg file attached to the JUICER20C stock
item by the ID of the file.

GET /e77c0c80-2296-4ef9-9588-877692933f31 HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/files
Accept: application/octet-stream
Content-Type: application/json
 REST API Examples | 89

Attach a File to a Record

When you need to attach a file to a record by using the contract-based REST API, you access the needed URL with
the PUT HTTP method and pass the file in the request body. See the following sections for details on the URL,
parameters, HTTP method, HTTP header, and response format.

HTTP Method and URL

If you need to attach a file to a top-level or detail record of any nesting level in Acumatica ERP, you use the PUT
HTTP method.
To get the URL for attaching a file to a particular record, you should obtain the record from Acumatica ERP and, in
the returned JSON representation of the record, find the value of the _links/files:put field. For information
on how to retrieve a record from Acumatica ERP, see Retrieve a Record by Key Fields and Retrieve a Record by ID.
The value of the _links/files:put field for the desired record is part of the URL template that must be used in
a request for attaching a file.
For example, suppose that you retrieved the stock item record that contains the following _links/
files:put field value from a local Acumatica ERP instance with the name AcumaticaDB: /AcumaticaDB/entity/
Default/22.200.001/files/PX.Objects.IN.InventoryItemMaint/Item/cae53ce0-1614-e511-9b82-c86000dddf0b/{filename}.
If you want to attach the file.dat file to this record, you use the following URL: http://AcumaticaDB/entity/
Default/22.200.001/files/PX.Objects.IN.InventoryItemMaint/Item/cae53ce0-1614-e511-9b82-c86000dddf0b/file.dat.

There is also an old way to attach a file to a top-level record in Acumatica ERP that is le for backward
compatibility. Following it, you use the PUT HTTP method and the following URL: http://<Base
endpoint URL>/<Top-level entity>/<Key value 1>/<Key value 2>/files/
<File name>. You address a record to which you are going to attach the file <File name> by the
values <Key value 1> and <Key value 2> of its key fields.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept The format of the response body, which can be one of the following:
• application/json
• text/json

Content-Type Specifies the format of the request body, which should be applica-
tion/octet-stream.

HTTP Body
You pass the file to be attached in the request body.

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that attaches a file to a record.
 REST API Examples | 90

Code Description

204 The request has been completed successfully. The file is attached. The Location head-
er of the response contains the URL that you can use to retrieve the file from the system.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

The following request shows an example of the retrieval of the EJECTOR03 stock item.

GET /EJECTOR03?$select=InventoryID HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json

Suppose that the request above returns the following response body.

{
"id": "a0f8594a-7de2-e811-b816-00155d408001",
"rowNumber": 1,
"note": {
"value": ""
},
"InventoryID": {
"value": "EJECTOR03"
},
"custom": {},
"_links": {
"self": "/<Acumatica ERP instance name>/entity/Default/22.200.001/
StockItem/a0f8594a-7de2-e811-b816-00155d408001",
"files:put": "/<Acumatica ERP instance name>/entity/Default/22.200.001/
files/PX.Objects.IN.InventoryItemMaint/Item/a0f8594a-7de2-e811-b816-00155d408001/
{filename}"
}
}

The following request attaches the T2MCRO.jpg file to the EJECTOR03 stock item.

PUT /a0f8594a-7de2-e811-b816-00155d408001/T2MCRO.jpg HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/files/
 REST API Examples | 91

PX.Objects.IN.InventoryItemMaint/Item
Accept: application/json
Content-Type: application/octet-stream

"<file contents here>"

Retrieve the Schema of Custom Fields

To retrieve the schema of custom fields of an entity—that is, the field name, view name, and type of the fields that
are not defined in the contract of the endpoint for this entity—by using the contract-based REST API, you access
the needed URL with the GET HTTP method. See the following sections for details on and examples of the URL,
parameters, HTTP method, HTTP header, and response format.

Custom fields can correspond to the following elements:

• The predefined elements on an Acumatica ERP form that are not included in the entity
definition
• The elements that were added to the Acumatica ERP form in a customization project
• The user-defined fields

HTTP Method and URL

If you need to obtain the schema of custom fields of an entity, you use the GET HTTP method and the following
URL.

http://<Base endpoint URL>/<Top-level entity>/$adHocSchema

The URL includes the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to retrieve the schema of custom
fields.
For example, suppose that you want to obtain the schema of custom fields of a stock item entity from a local
Acumatica ERP instance with the name AcumaticaDB by using the system endpoint with the name Default
and Version 22.200.001. You would use the following URL to retrieve the schema: http://localhost/
AcumaticaDB/entity/Default/22.200.001/StockItem/$adHocSchema.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json
 REST API Examples | 92

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves the schema of
the custom fields of an entity.

Code Description

200 The request has been completed successfully. The response contains the field name,
view name, and type of the fields that are not defined in the contract of the endpoint for
the entity.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request shows an example of the retrieval of the schema of custom fields of the StockItem entity.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /$adHocSchema HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json

Retrieve a Record with Custom Fields

To retrieve a record with custom fields by using the contract-based REST API, you access the needed URL with the
GET HTTP method. For more information on retrieval of records, see Retrieve a Record by Key Fields, Retrieve a
Record by ID, Retrieve Records by Conditions.

HTTP Method and URL

To retrieve a record with custom fields, you use the GET HTTP method and the same URL and HTTP headers as you
would use to retrieve a record that contains only those fields that are defined in the endpoint (see Retrieve a Record
by Key Fields, Retrieve a Record by ID, Retrieve Records by Conditions).

Parameters
To retrieve a record with custom fields, you use the $custom parameter. For more information on the use of the
$custom parameter, see $custom Parameter.
 REST API Examples | 93

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves records by
conditions.

Code Description

200 The request has been completed successfully. The response body contains the list of
records that satisfy the specified conditions.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
Suppose that you have customized the Sales Orders (SO301000) form by adding the PRODUCT field to it. The
following request shows an example of the retrieval of sales order's fields along with the PRODUCT field.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /SO/000029?$custom=Document.AttributePRODUCT HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

Related Links
• $custom Parameter
 REST API Examples | 94

Create a Record with Custom Fields

To create a record with custom fields by using the contract-based REST API, you access the needed URL with the
PUT HTTP method. For more information on the creation of records, see Create a Record.

HTTP Method and URL

To create a record in Acumatica ERP, you use the PUT HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to create a record.
For example, suppose that you want to create a stock item record in a local Acumatica ERP instance with the name
AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001. You should use the
following URL to create a record: http://localhost/AcumaticaDB/entity/Default/22.200.001/
StockItem.

Parameters
To create a record with custom fields, you use the $custom parameter. For more information on the use of the
$custom parameter, see $custom Parameter.

HTTP Headers
You can specify the following headers in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Content-Type Specifies the format of the request body, which can be one of the following:
• application/json
• text/json

If-None-Match Changes the behavior of the PUT request, which normally either creates a new
record or updates an existing one. If you only want to create a new record, use the
optional If-None-Match header with the * (asterisk) value.

HTTP Body
To create a record with custom fields, you compose the HTTP body as described in Representation of a Record in
JSON Format, section Custom Fields.
 REST API Examples | 95

Response Status Codes

For the information on possible response status codes, see Create a Record.

Example
Suppose that you have customized the Sales Orders (SO301000) form by adding the PRODUCT field to it. The
following request shows an example of creation of a sales order that contains the PRODUCT field.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$custom=Document.AttributePRODUCT HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CustomerID": {
"value": "GOODFOOD"
},
"Hold": {
"value": false
},
"LocationID": {
"value": "MAIN"
},
"OrderType": {
"value": "SO"
},
"PaymentMethod": {
"value": "CHECK"
},
"custom": {
"Document": {
"AttributePRODUCT": {
"type": "CustomStringField",
"value": "Apple jam 8 oz."
}
}
}
}

Change the Business Date or Current Branch

When you use the contract-based REST API, the current date is used as the business date, and the branch that you
specified when signing in is used as the current branch. When you create or update a record by using the contract-
based REST API, you may need to use other values of the business date or current branch. To do this, you use the
custom HTTP headers PX-CbApiBusinessDate and PX-CbApiBranch in the HTTP requests you make. See the following
sections for details on the URL, headers, HTTP method, body, and response format.
 REST API Examples | 96

The new values that you specify for the business date or current branch are valid only for the current
HTTP request.

HTTP Method and URL

When you create or update a record in Acumatica ERP, you use the PUT HTTP method and the following URL:
http://<Base endpoint URL>/<Top-level entity>.
The URL has the following components:
• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to create or update a record.
For example, suppose that you want to update a stock item record in a local Acumatica ERP instance with the
name AcumaticaDB by using a system endpoint with the name Default and Version 22.200.001. You would use the
following URL to update a record: http://localhost/AcumaticaDB/entity/Default/22.200.001/StockItem.

Headers
You can use the following optional headers for changing the business date or current branch.

Header Description

PX-CbApiBusiness- Optional. Specifies the new business date. The date can be specified in any format.
Date If you omit this header, the current date is used as the business date.

PX-CbApiBranch Optional. Specifies the new current branch. The branch should be specified as a
branch name. If you omit this header, the branch that you specified when signing in
is used as the current branch.

Parameters
For information on the request parameters, see the corresponding section in Create a Record and Update a Record.

HTTP Body
For information on the request body, see the corresponding section in Create a Record and Update a Record.

Response Status Codes

For information on possible response status codes, see the corresponding section in Create a Record and Update a
Record.

Example
The following request is an example of creating a new journal transaction with SweetLife Store set as the new
current branch and 01-Jan-2018 set as the business date.
 REST API Examples | 97

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/JournalTransaction
Accept: application/json
Content-Type: application/json
PX-CbApiBusinessDate: 2022/01/01
PX-CbApiBranch: SweetLife Store

{
"Description": {"value": "Test transaction description"},
"PostPeriod": {"value": "01-2022"}
}

Retrieve the Acumatica ERP Version and the List of Endpoints

To obtain the Acumatica ERP version and the list of contract-based endpoints available in this version by using the
REST API, you access the needed URL with the GET HTTP method. The remainder of this topic provides details on
and examples of the URL, the parameters, the headers, and the format of the response.
If the request is sent without the authentication information, the list contains only the endpoints available in
the system by default. If the request is sent with the authentication information for a particular tenant, the list
also includes the custom endpoints configured in this tenant of the Acumatica ERP instance. You can obtain the
response in JSON or XML format.

HTTP Method and URL

To retrieve the Acumatica ERP version and the list of contract-based endpoints available in this version, you use the
GET HTTP method and the following URL.

http://<Acumatica ERP instance URL>/entity

In this URL, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance for which you want to obtain
information about the version and endpoints.
For example, suppose that you work with a local Acumatica ERP instance with the name AcumaticaDB. You would
use the following URL to retrieve the information: http://localhost/AcumaticaDB/entity.

Parameters
You use no parameters when you retrieve the Acumatica ERP version and the list of contract-based endpoints
available in this version.

HTTP Headers
You can specify the following header in the request.
 REST API Examples | 98

Header Description

Accept Optional. Specifies the format of the response body, which can be one of the fol-
lowing:
• application/json (default)
• text/json
• application/xml
• text/xml

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves the Acumatica
ERP version and the list of endpoints.

Code Description

200 The request has been completed successfully. The response body contains the Acumati-
ca ERP version and the list of contract-based endpoints available in this version.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
The following request obtains the Acumatica ERP version and the list of contract-based endpoints available in this
version.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /entity HTTP/1.1

Host: [<Acumatica ERP instance URL>]
Accept: application/json

Following is an example of a response in JSON format.

{
"version": {
"acumaticaBuildVersion": "20.206.0011",
"databaseVersion": "20.206.0011"
},
"endpoints": [
{
"name": "Default",
"version": "17.200.001",
"href": "/AcumaticaERP/entity/Default/17.200.001/"
},
{
"name": "DeviceHub",
 REST API Examples | 99

"version": "17.200.001",
"href": "/AcumaticaERP/entity/DeviceHub/17.200.001/"
},
{
"name": "POS",
"version": "17.200.001",
"href": "/AcumaticaERP/entity/POS/17.200.001/"
},
{
"name": "MANUFACTURING",
"version": "18.100.001",
"href": "/AcumaticaERP/entity/MANUFACTURING/18.100.001/"
},
{
"name": "Default",
"version": "18.200.001",
"href": "/AcumaticaERP/entity/Default/18.200.001/"
},
{
"name": "DeviceHub",
"version": "19.200.001",
"href": "/AcumaticaERP/entity/DeviceHub/19.200.001/"
},
{
"name": "Default",
"version": "20.200.001",
"href": "/AcumaticaERP/entity/Default/20.200.001/"
},
{
"name": "eCommerce",
"version": "20.200.001",
"href": "/AcumaticaERP/entity/eCommerce/20.200.001/"
},
{
"name": "MANUFACTURING",
"version": "20.200.001",
"href": "/AcumaticaERP/entity/MANUFACTURING/20.200.001/"
}
]
}

Retrieve the List of Records in Batches

To retrieve a large number of records of the same type by using the contract-based REST API, you can use several
approaches. There are two extremes in performing this task:
• You make a single request that retrieves the whole information you need. In this case there is a risk of an
operation timeout.
• You make many requests, each of which retrieves a single record you need. In this case the whole task takes
a lot of time.
A balanced approach combines these two extremes: you make multiple requests with the $top and $skip
parameters, each of which retrieves a part of the records you need. The number of records to retrieve in a single
request you select empirically to optimize the performance of the whole task or to paginate records.
 REST API Examples | 100

HTTP Method and URL

If you need to retrieve the list of records that satisfies the specified conditions, you use the GET HTTP method and
the following URL.

http://<Base endpoint URL>/<Top-level entity>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to retrieve the list of records.
For example, suppose that you want to retrieve the list of stock item records from a local Acumatica ERP instance
with the name AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001. You
should use the following URL to retrieve the list of records: http://localhost/AcumaticaDB/entity/
Default/22.200.001/StockItem.

Parameters
For the information on the request parameters, see $top Parameter and $skip Parameter.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves records by
conditions.

Code Description

200 The request has been completed successfully. The response body contains the list of
records that satisfy the specified conditions.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

 REST API Examples | 101

Example
Suppose that you want to retrieve the sales orders in batches of five. The following example shows how to retrieve
the second batch of five sales orders.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$top=5&$skip=5 HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

Specify Localized Values of a Multi-Language Field

For some text boxes on Acumatica ERP forms, users can type values in multiple languages if multiple locales
are configured in Acumatica ERP. For example, if your Acumatica ERP instance has English and French locales
activated and multilingual user input configured, you can specify the value of the Description box on the Stock
Items (IN202500) form in English and French. For the list of elements that support multiple languages, see Boxes
that Have Multi-Language Support. For details on how to turn on multilingual user input, see Enabling Multilingual
User Input.

HTTP Method and URL

To create a record in Acumatica ERP, you use the PUT HTTP method and the following URL.

http://<Base endpoint URL>/<Top-level entity>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to create a record.
For example, suppose that you want to create a stock item record in a local Acumatica ERP instance with the name
AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001. You should use the
following URL to create a record: http://localhost/AcumaticaDB/entity/Default/22.200.001/
StockItem.

HTTP Headers
For the information on HTTP headers to use, see Create a Record or Update a Record depending on the operation
you perform (creation or update of a record).

HTTP Body
In the HTTP body, you specify values in the following format: [{language_code1:value1},
{language_code2:value2},...]. As the language code, you use the two-letter ISO code of the language
with which the value should be associated.
 REST API Examples | 102

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that creates a record.

Code Description

200 The request has been completed successfully. The response of a successful method call
contains the created record in JSON format in the response body. The response includes
only the values of the fields of the created record that were specified during creation of
the record or that were specified to be returned by using the parameters of the request.

400 The data specified in the request is invalid.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

412 You have used the If-None-Match header with the * value, and the record already ex-
ists.

422 This status code can be returned for Contract Version 4. The data specified in the request
is invalid and the validation errors are returned in the error fields of the response body,
as in the following example.

"CustomerID": {
"value": "ABARTENDE1",
"error": "'Customer' cannot be found in the system."
}

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
In the example that is mentioned at the beginning of the topic, if you need to specify values in English and French in
the Description box on the Stock Items form, you specify the value of the Description field of the StockItem
entity in the following format: [{en:English description},{fr:French description}]. See below
for an example of a stock item record with localized Description field values in JSON format.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json

{
"InventoryID" : {"value" : "BASESERV" },
 REST API Examples | 103

"ItemClass" : {"value" : "COMPUTERS" },

"Description" : {"value" : "[{en:Item},{fr:Pièce}]" }
}

Usage Notes
In the JSON-formatted string, you should specify the actual values of the field in all languages that are configured
for multilingual user input. If you specify the values of the field in particular languages, the values of the field in
other languages configured for multilingual user input become empty. For example, suppose that in your instance
of Acumatica ERP, multi-language fields can have values in English and French. If you pass the value of a field in the
following format [{en:English description}], the French value of the field becomes empty.
If you specify the value of a multi-language field as plain text, this text is saved as the value of the corresponding
box in the current language of Acumatica ERP (that is, the language that you specified when you logged in to
Acumatica ERP). For details on how to specify the language on login through the contract-based REST API, see Sign
In to the Service.

Related Links
• Locales and Languages
• Boxes that Have Multi-Language Support
• Custom Fields

Retrieve Localized Values of a Multi-Language Field

For some text boxes on Acumatica ERP forms, users can type values in multiple languages if multiple locales
are configured in Acumatica ERP. For example, if your Acumatica ERP instance has English and French locales
activated and multilingual user input configured, you can specify the value of the Description box on the Stock
Items (IN202500) form in English and French. For the list of elements that support multiple languages, see Boxes
that Have Multi-Language Support. For details on how to turn on multilingual user input, see Enabling Multilingual
User Input.

HTTP Method and URL

If you need to retrieve the list of records that satisfies the specified conditions, you use the GET HTTP method and
the following URL.

http://<Base endpoint URL>/<Top-level entity>

The URL has the following components:

• <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work
with Acumatica ERP, which has the following format: http://<Acumatica ERP instance URL>/
entity/<Endpoint name>/<Endpoint version>/.
• <Top-level entity> is the name of the entity for which you are going to retrieve the list of records.
For example, suppose that you want to retrieve the list of stock item records from a local Acumatica ERP instance
with the name AcumaticaDB by using the system endpoint with the name Default and Version 22.200.001. You
should use the following URL to retrieve the list of records: http://localhost/AcumaticaDB/entity/
Default/22.200.001/StockItem.

Parameters
You retrieve localized values by using the $custom parameter in which you specify the name of a custom field.
 REST API Examples | 104

To find out the field name and the view name of the needed custom field with localized values, you find out the
field name and the view name of the multi-language text box and append Translations to the field name. (For
details on how to find out the field name and the view name of an element on the form, see Custom Fields.) For
example, the multi-language Description box on the Stock Items form has the Descr field name and the Item view
name; therefore, the custom field that contains the localized descriptions of a stock item has the DescrTranslations
field name and the Item view name. So you should use the following parameter string in the request URL:
$custom=Item.DescrTranslations.
You can also retrieve all localized values of all requested fields. To do this, you add the $expand=Translations
parameter to the request. If you use the $filter parameter to narrow the result, then add Translations to the value of
the $filter parameter to get the localized values in the response.

HTTP Headers
You can specify the following header in the request.

Header Description

Accept Specifies the format of the response body, which can be one of the following:
• application/json
• text/json

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that retrieves records by
conditions.

Code Description

200 The request has been completed successfully. The response body contains the list of
records that satisfy the specified conditions.

401 The user is not signed in to the system.

403 The user has insufficient rights to access the Acumatica ERP form that corresponds to the
entity.

429 The number of requests has exceeded the limit imposed by the license (see License Re-
strictions for API Users).

500 An internal server error has occurred.

Example
For example, suppose that you want to retrieve the localized values of the Description box on the Stock Items form.
Following is an example of a request.

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

GET ?$custom=Item.DescrTranslations HTTP/1.1

 REST API Examples | 105

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem

Accept: application/json
Content-Type: application/json

The returned value of a Translations custom field is a string in JSON format with the available localized values
of the field. The language to which the value belongs is identified by the two-letter ISO code of the language. For
example, suppose that for a particular record, the Description element of the Stock Items form has the value
Item in English and Pièce in French. In this case, the value of the DescrTranslations custom field, which
corresponds to the Description element, is the following string: [{en:Item},{fr:Pièce}].
You can also use the following request to retrieve all localized values on the Stock Items form.

GET ?$expand=Translations HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json

If for a particular record, the Description element of the Stock Items form has the value Item in English and Pièce in
French (as in the previous example), the response has the following data for this record.

...
"Description": {
"value": "Item",
"translations": {
"en": "Item",
"fr": "Pièce"
}
...

Related Links
• Locales and Languages
• Boxes that Have Multi-Language Support
• Custom Fields

Parameters for Retrieving Records

When you retrieve records from Acumatica ERP by using the contract-based REST API, you can use the following
URL parameters to filter records by the conditions you specify, expand particular entities, and retrieve the values of
fields that are not defined in the contract of the endpoint:
• $filter Parameter
• $top Parameter
• $skip Parameter
• $expand Parameter
• $select Parameter
• $custom Parameter
 REST API Examples | 106

$filter Parameter

When you retrieve records from Acumatica ERP by using the contract-based REST API, you use the $filter parameter
to specify the conditions that determine which records should be selected from Acumatica ERP. You use OData URI
conventions to specify the value of the parameter.

You can specify multiple conditions for the same field or different fields in a filter by using the AND and OR
operators.
When you specify the value of the parameter, you can use the following functions as they are defined in OData:
• substringof
• startswith
• endswith
You can also use the following custom function to filter records by the values of elements that are not defined in the
contract of the endpoint: cf.<Type name>(f='<View name>.<Field name>'), where <Type name>
is the type of the custom element, <View name> is the name of the data view that contains the element, and
<Field name> is the name of the element.

Example: Simple Condition

To obtain stock item records that have the Active status in Acumatica ERP, you use the following filter:
$filter=ItemStatus eq 'Active'.

Example: Condition on a Linked Entity

To obtain a customer record that has the [email protected] email address, you use the following filter:
$filter=MainContact/Email eq '[email protected]'. (The Email field is defined in a linked entity, which is available
through the MainContact property.)

Filtering on detail records is not supported. If you specify a filter on detail records, the result of the
request cannot be predicted.

Example: Multiple Conditions

To obtain stock item records that have the Active status in Acumatica ERP and have been modified
later than July 15, 2016, you use the following filter: $filter=ItemStatus eq 'Active' and LastModified gt
datetimeoffset'2016-07-15T10%3A31%3A28.402%2B03%3A00'.

You should encode date and time values in URL format before passing them as the
value of the parameter. For example, you can encode the current date and time
by using the System.Net.WebUtility.URLEncode() method as follows:
WebUtility.UrlEncode(new DateTimeOffset(DateTime.Now).ToString("yyyy-
MM-ddTHH:mm:ss.fffK")).

Example: Condition on a Field Not Defined in the Endpoint

Suppose that in an extension of the Default/20.200.001 endpoint, you added the RepairItemType field to the
top-level StockItem entity. This field corresponds to the Repair Item Type custom element that has been added
to the General tab (the Item Defaults section) of the Stock Items (IN202500) form. If you want to obtain all records
 REST API Examples | 107

on the Stock Items form for which the value of the custom Repair Item Type element is equal to Battery, you would
use the following parameter string: $filter=cf.String(f='ItemSettings.UsrRepairItemType') eq 'Battery'.

For details on how to find out the name of a custom element and the name of its data view, see
Custom Fields.

Related Links
• OData URI conventions

$top Parameter

When you retrieve records from Acumatica ERP by using the contract-based REST API, you use the $top parameter
to specify the number of records to be returned from Acumatica ERP. That is, if you specify N as the value of this
parameter, the first N records will be returned from Acumatica ERP.
If you do not use the $top parameter in a request, all records will be returned. However, limits can be specified in
SQL Server Resource Governor; if the number of available records exceeds the limit, and error will be returned.

Example: Retrieval of the First Five Records

To obtain only first five records from the list, you use the following parameter string: $top=5.

$skip Parameter

When you retrieve records from Acumatica ERP by using the contract-based REST API, you use the $skip parameter
to specify the number of records to be skipped from the list of returned records. That is, if you specify N as the value
of this parameter, the first N records will be skipped from the list of returned records.
If you use the $skip and $top parameters together, the $skip parameter is applied first.
By using the $skip and $top parameters, you can implement pagination of records. However, there is no parameter
to learn the number of records that meet the request.

Example: Skipping the First Five Records

If you want to skip the first five records from the list and obtain the rest of the records, you use the following
parameter string: $skip=5.

$expand Parameter

When you retrieve records from Acumatica ERP by using the contract-based REST API, you use the $expand
parameter to specify the linked and detail entities that should be expanded. By default, no linked or detail entities
are expanded; that is, only fields of the top-level entity are returned.
You use OData URI conventions to specify the value of the $expand parameter.
You explicitly specify each linked or detail entity to be expanded.
If you use the $expand parameter in a request, its use will not cause the concurrent request limit or rate limit
imposed by the license to be exhausted sooner.
 REST API Examples | 108

Contract Version 4 requires that you use the $expand=files parameter (for a top-level entity) or the
$expand=details/files parameter (for a detail or linked entity) to retrieve the data of the files attached
to the entity.

Example: Expanding Detail Lines

To obtain the values of the warehouse detail lines of stock item records, you use the following parameter string:
$expand=WarehouseDetails.

Example: Nested Expanding

If you specify $expand=MainContact for the Customer entity, only the Contact linked entity of the Customer
entity is expanded, but the Address linked entity within MainContact is not. To expand the Address entity,
you should explicitly specify the Address entity to be expanded as follows: $expand=MainContact,MainContact/
Address.
Related Links
• OData URI conventions

$select Parameter

When you retrieve records from Acumatica ERP by using the contract-based REST API, you use the $select
parameter to specify the fields of the entity to be returned from Acumatica ERP. By default, all fields of the entity
are returned.
You use OData URI conventions to specify the value of the $select parameter.

Example
To obtain only the order types and order numbers of sales orders, you use the following parameter string:
$select=OrderType,OrderNbr.
Related Links
• OData URI conventions

$custom Parameter

When you retrieve records from Acumatica ERP by using the contract-based REST API, you use the $custom
parameter to specify the fields that are not defined in the contract of the endpoint to be returned from Acumatica
ERP. That is, you can use this parameter to obtain the values of the predefined elements on an Acumatica ERP form
that are not included in the entity definition, the values of user-defined fields, and the values of elements that were
added to the Acumatica ERP form in a customization project.
You use one of the following formats to specify the element whose value should be returned:
• If a top-level entity contains the custom field that corresponds to the element: <View name>.<Field
name>, where you replace <View name> with the name of the data view that contains the element and
<Field name> with the internal name of the element.
• If a linked or detail entity contains the custom field that corresponds to the element: <Entity name>/
<View name>.<Field name>, where you replace <Entity name> with the name of the linked
 REST API Examples | 109

or detail entity that contains the field, <View name> with the name of the data view that contains the
element, and <Field name> with the internal name of the element.

If you want to obtain the value of a custom field of a linked or detail entity, in addition to
specifying the $custom parameter, you have to specify this entity in the $expand parameter.

• If the element is a user-defined field: <View name>.Attribute<AttributeID>, where you replace

<View name> with the name of the data view that contains the element, and <AttributeID> with the
ID of the attribute that corresponds to the user-defined field.
For details about user-defined fields, see User-Defined Fields.
If you want to obtain the values of multiple custom elements, you specify the custom elements to be returned,
separated by commas. For details on how to find out the field name and the name of the data view, see Custom
Fields.

Example: Custom Field of a Top-Level Entity

Suppose that in an extension of the Default/20.200.001 endpoint, you added the RepairItemType field to the
top-level StockItem entity. This field corresponds to the Repair Item Type custom element that has been added
to General tab of the Stock Items (IN202500) form. If you want to obtain the value of this element, you use the
following parameter string: $custom=ItemSettings.UsrRepairItemType.

Example: Custom Field of a Detail Entity

Suppose that in an extension of the Default/20.200.001 endpoint, you added the RepairItemType field to the
SalesOrderDetail detail entity. This field corresponds to the Repair Item Type custom column, which has
been added to the Details tab of the Sales Orders (SO301000) form. If you want to obtain the value of this element,
you use the following parameter string: $custom=Details/Transactions.UsrRepairItemType. You also use the $expand
parameter as follows: $expand=Details.

Example: User-Defined Field

Suppose that on the Sales Orders (SO301000) form, you have added a user-defined field for the OPERATSYST
attribute. If you want to obtain the value of this user-defined field, you use the following parameter string:
$custom=Document.AttributeOPERATSYST.
Related Links
• Custom Fields

Account

This chapter presents code examples showing requests that use the Account entity.

Add an Account to an Account Group

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can add an account to an account group.
 REST API Examples | 110

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to add the 40000 account to the ACCG02 account group through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Account
Accept: application/json
Content-Type: application/json

{
"AccountCD" : {"value" : "40000"},
"AccountGroup" : {"value" : "ACCG02"}
}

Retrieve the List of Accounts in a Group

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve the list of accounts in a group.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve the list of accounts of the ACCG02 account group through the
contract-based REST API.
 REST API Examples | 111

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Account?
$filter=AccountGroup%20eq%20'ACCG02'&$select=AccountCD
Accept: application/json
Content-Type: application/json

Remove an Account from a Group

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can remove an account from a group.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to remove the 40010 account from the ACCG02 account group through
the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Account
Accept: application/json
Content-Type: application/json

{
"AccountCD" : {"value" : "40010"},
"AccountGroup" : {"value" : null}
}

AccountDetailsForPeriodInquiry

This chapter presents code examples showing requests that use the AccountDetailsForPeriodInquiry
entity.
 REST API Examples | 112

Get General Ledger Transactions for Some Period

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve general ledger transactions for the specified period from Acumatica ERP. For this purpose, you
can use the Account Details for Period (GL404001) generic inquiry.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve general ledger transactions made from March to April 2021
through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Results HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/
AccountDetailsForPeriodInquiry
Accept: application/json
Content-Type: application/json

{
"FromPeriod": { "value": "032021" },
"ToPeriod": { "value": "042021" }
}

AccountGroup

This chapter presents code examples showing requests that use the AccountGroup entity.

Create an Account Group

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create an account group.
 REST API Examples | 113

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create an account group with the ACCG02 identifier through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/AccountGroup
Accept: application/json
Content-Type: application/json

{
"AccountGroupID" : {"value" : "ACCG02"},
"Description" : {"value" : "Test Account Group"}
}

Specify the Default Account of an Account Group

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can specify the default account of an account group.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to specify the 40000 account as the default account of the ACCG02
account group through the contract-based REST API.
 REST API Examples | 114

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/AccountGroup
Accept: application/json
Content-Type: application/json

{
"DefaultAccountID" : {"value" : "40000"},
"AccountGroupID" : {"value" : "ACCG02"}
}

Activity

This chapter presents code examples showing requests that use the Activity entity.

Create an Activity that Is Linked to a Case

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can establish the relationship of the Activity, Event, Task, and Email objects with cases in
Acumatica ERP. You can also establish this relationship by using the Create Activity, Create Event, Create Task, or
Create Email button on Activities tab of the Cases (CR306000) form. For details about the management of cases,
see Case Management: General Information.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create an activity that is linked to a case through the contract-based
REST API. In the RelatedEntityNoteID field, you use the ID value of the case for linking. This ID value is
present, for example, in the response body when you Create a Case.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Activity
Accept: application/json
 REST API Examples | 115

Content-Type: application/json

{
"Summary": {"value": "Automated Test"},
"Type": {"value": "M"},
"RelatedEntityNoteID": {"value": "{{NoteID}}"},
"RelatedEntityType": {"value": "PX.Objects.CR.CRCase"},
"ActivityDetails":{"value": "Automated Test"}
}

Usage Notes
In the Default/20.200.001 and Default/22.200.001 endpoints, you use the following fields of the Activity entity:
• RelatedEntityNoteID: The NoteID value of the object with which the relationship is established.
• RelatedEntityType: The full name of the type of the object with which the relationship is established
(namely, PX.Objects.CR.CRCase).
• RelatedEntityDescription: The description of the related object. This field is read-only.

Create an Activity that Is Linked to a Customer

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can establish the relationship of the Activity, Event, Task, and Email objects with customers in
Acumatica ERP. You can also establish this relationship by using the Create Activity, Create Event, Create Task, or
Create Email button on Activities tab of the Customers (AR303000) form.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create an activity that is linked to a customer through the contract-
based REST API. In the RelatedEntityNoteID field, you use the ID value of the customer for linking. This ID
value is present, for example, in the response body when you Create a Customer.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Activity
Accept: application/json
Content-Type: application/json

{
 REST API Examples | 116

"Summary": {"value": "Automated Test 2"},

"Type": {"value": "M"},
"RelatedEntityNoteID": {"value": "f37200d6-35ea-eb11-9dee-9828a61840c3"},
"RelatedEntityType": {"value": "PX.Objects.AR.Customer"},
"ActivityDetails":{"value": "Automated Test 2"}
}

Usage Notes
In the Default/20.200.001 and Default/22.200.001 endpoints, you use the following fields of the Activity entity:
• RelatedEntityNoteID: The NoteID value of the customer with which the relationship is established.
• RelatedEntityType: The full name of the type of the object with which the relationship is established
(namely, PX.Objects.AR.Customer). This field is optional, but we recommend using it. The field can
be omitted because an object with which the relationship is established has a persisting note record in the
database.
• RelatedEntityDescription: The description of the related object. This field is read-only.

Create an Activity that Is Linked to a Lead

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can establish the relationship of the Activity, Event, Task, and Email objects with leads in
Acumatica ERP. You can also establish this relationship by using the Create Activity, Create Event, Create Task,
or Create Email button on Activities tab of the Leads (CR301000) form. For more information about the creation of
activities, see Emails and Activities: Activities.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create an activity that is linked to a case through the contract-based
REST API. In the RelatedEntityNoteID field, you use the ID value of the case for linking. This ID value is
present, for example, in the response body when you Create a Lead.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Activity
Accept: application/json
Content-Type: application/json

{
 REST API Examples | 117

"Summary": {"value": "Automated Test"},

"Type": {"value": "M"},
"RelatedEntityNoteID": {"value": "{{NoteID}}"},
"RelatedEntityType": {"value": "PX.Objects.CR.CRLead"},
"ActivityDetails":{"value": "Automated Test"}
}

Usage Notes
In the Default/20.200.001 and Default/22.200.001 endpoints, you use the following fields of the Activity entity:
• RelatedEntityNoteID: The NoteID value of the lead with which the relationship is established.
• RelatedEntityType: The full name of the type of the object with which the relationship is established
(namely, PX.Objects.CR.CRLead).
• RelatedEntityDescription: The description of the related lead. This field is read-only.

Bill

This chapter presents code examples showing requests that use the Bill entity.

Create a Bill for Particular Lines of a Purchase Order

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create bills for particular lines of purchase orders. For details about the processing of inventory
purchases, see Purchases of Stock Items: General Information.
To create an AP bill for particular lines of a purchase order, you need to specify the line numbers in the request by
using the POLine property of the BillDetail detail entity of the Bill entity.

If you want to add all lines of a purchase order to an AP bill, in the BillDetail detail entity of the
Bill entity, you need to specify only the order type and number of the purchase order.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Make sure the financial periods are open for the year for which you are creating an AP bill. If the
financial periods are not open, the creation of the AP fill fails with an error, such as Post Period cannot
be empty. For details about how to open financial periods, see an example in Opening Financial
Periods: Process Activity.
 REST API Examples | 118

Request
You can use the following example of an HTTP request to create an AP bill for a line of a purchase order.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$select=ReferenceNbr,Details/POOrderNbr,Details/POOrderNbr,
Details/InventoryID,Details/Qty&$expand=Details HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Bill
Accept: application/json
Content-Type: application/json

{
"Vendor": {
"value": "PRINTICO"
},
"VendorRef": {
"value": "123"
},
"Description": {
"value": "Bill for particular lines of a purchase order"
},
"Details": [
{
"POOrderType": {
"value": "Normal"
},
"POOrderNbr": {
"value": "000001"
},
"POLine": {
"value": 1
},
"Qty":
{
"value": 5
}
}
]
}

Create a Bill for Particular Lines of a Purchase Receipt

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create bills for particular lines of purchase receipts. For details about the processing of inventory
purchases, see Purchases of Stock Items: General Information.
To create an AP bill for particular lines of a purchase receipt, you need to specify the line numbers in the request by
using the POReceiptLine property of the BillDetail detail entity of the Bill entity.
 REST API Examples | 119

If you want to add all lines of a purchase receipt to an AP bill, in the BillDetail detail entity of the
Bill entity, you need to specify only the receipt number of the purchase receipt.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Make sure the financial periods are open for the year for which you are creating an AP bill. If the
financial periods are not open, the creation of the AP fill fails with an error, such as Post Period cannot
be empty. For details about how to open financial periods, see an example in Opening Financial
Periods: Process Activity.

Request
You can use the following example of an HTTP request to create an AP bill for a line of a purchase receipt.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$select=ReferenceNbr,Details&$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Bill
Accept: application/json
Content-Type: application/json

{
"Vendor": {
"value": "OFFICEUP"
},
"VendorRef": {
"value": "123"
},
"Description": {
"value": "Bill for particular lines of a purchase receipt"
},
"Details": [
{
"POReceiptNbr": {
"value": "000001"
},
"POReceiptLine": {
"value": 1
}
}
]
 REST API Examples | 120

Usage Notes
In the request above, you can specify the Details/POReceiptType value to create a bill for particular lines of a
purchase receipt or purchase return. If you do not specify this value, the Receipt value is used by default.

Create a Bill with Tax Parameters Overridden

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create bills with the tax parameters overridden.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the SalesDemo dataset. For details on deploying an instance, see
To Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the PRODWHOLE branch.

To further prepare the system, you need to create a tax and a tax category that uses this tax, and modify the existing
tax zone so that it will use the new tax. You perform these tasks as follows:
1. On the Taxes (TX205000) form, create a tax with the tax schedule as follows:
a. Create a tax with the following parameters:
• Tax ID: PST
• Description: Tax ID for testing
• Tax Type: VAT
• Include in VAT Taxable Total: Selected
• Exclude from Tax on Tax Calculation: Selected
• Tax Agency: CANADABC
b. On the Tax Schedule tab of the form, add two rows with the following data.

Column First Row Second Row

Start Data 1/1/1900 1/1/1900

Tax Rate 5 5

Min. Taxable Amount 0 0

Max. Taxable Amount 0 0

Reporting Group Input Tax (purchases) Output Tax (sales)

Group Type Input Output

 REST API Examples | 121

c. Click Save.
2. On the Tax Categories (TX205500) form, create the TEST tax category with the Tax category for test
description and add the CAGST and PST taxes to the tax category.
3. On the Applicable Taxes tab of the Tax Zones (TX206000) form, add the PST tax to the CANADABC tax zone.

Request
You can use the following example of an HTTP request to create an AP bill with the tax parameters that are different
from those registered in the system.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details,TaxDetails HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Bill
Accept: application/json
Content-Type: application/json

{
"Amount": { "value": 1120.0 },
"CashDiscountDate": { "value": "11/18/2021" },
"CurrencyID": { "value": "USD" },
"Date": { "value": "10/18/2021" },
"DueDate": { "value": "11/18/2021" },
"Hold": { "value": false },
"LocationID": { "value": "MAIN" },
"PostPeriod": { "value": "102021" },
"Status": { "value": "Balanced" },
"TaxAmount": { "value": 120.0 },
"Terms": { "value": "30D" },
"Type": { "value": "Bill" },
"Vendor": { "value": "AAVENDOR" },
"VendorRef": { "value": "test-API22" },
"Description": { "value": "test-API" },
"IsTaxValid": {
"value": true
},
"Details": [
{
"Account": { "value": "50000" },
"Branch": { "value": "PRODWHOLE" },
"CostCode": { "value": null },
"ExtendedCost": { "value": 1000.0 },
"Project": { "value": "X" },
"Subaccount": { "value": "000000" },
"TaxCategory": { "value": "TEST" },
"IsTaxValid": { "value": true }
}
],
"TaxDetails": [
{
"TaxID": { "value": "CAGST" },
"TaxableAmount": { "value": 1000.0 },
"TaxAmount": { "value": 150.0 },
 REST API Examples | 122

"ExpenseAmount": { "value": 0.0 }

},
{
"TaxID": { "value": "PST" },
"TaxableAmount": { "value": 1000.0 },
"TaxAmount": { "value": 150.0 },
"custom": {
"Taxes": {
"CuryExpenseAmt": {
"type": "CustomDecimalField",
"value": 70
}
}
}
}
],
"custom": {
"CurrentDocument": {
"TaxZoneID": {
"type": "CustomStringField",
"value": "CANADABC"
}
}
}
}

Usage Notes
In the request above, you have set the IsTaxValid value to true to use in the bill the tax parameters specified in
the TaxDetails field. If you do not specify this value, the tax parameters that are registered in the system will be
used instead. In particular, the tax amounts equal to 50 will be set both for the CAGST and PST taxes in the created
bill.

BillOfMaterial

This chapter presents code examples showing requests that use the BillOfMaterial entity.

Create a Bill of Material

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create bills of material (BOMs). For details about the management of bills of material, see Managing
Bills of Material.

Testing of the Request

Before you test the code in the following section, you need to perform the actions described in the System
Preparation section of Bills of Material: Implementation Activity.
 REST API Examples | 123

Requests

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

You can use the following HTTP request example to create a BOM containing information about an operation and a
material used.

PUT ?$expand=Operations,Operations/Material HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/MANUFACTURING/21.200.001/BillOfMaterial
Accept: application/json
Content-Type: application/json

{
"BOMID": { "value": "<NEW>" },
"Description": { "value": "Test BOM" },
"Hold": { "value": true },
"InventoryID": { "value": "CFJCITRUS" },
"Operations": [
{
"OperationNbr": { "value": "010" },
"WorkCenter": { "value": "WCR10" },
"OperationDescription": {
"value": "Work center for assembly of juicers"
},
"Material" :[
{
"InventoryID": { "value": "JCREAMER" },
"UOM":{ "value": "EA" }
}
]
}
],
"Revision": { "value": "A" },
"Warehouse": { "value": "WORKHOUSE" }
}

In this example, the <NEW> value is specified for the BOMID field, and the next identifier is assigned to this field for
the newly created BOM. You can also specify an empty string as a value for the BOMID field, which will lead to the
same result.

{
"BOMID": { "value": "" },
...
}
 REST API Examples | 124

Retrieve the Bills of Material

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve the list of available bills of material (BOMs). For details about the management of bills of
material, see Managing Bills of Material.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Manufacturing feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

You can use the following HTTP request example to retrieve the list of BOMs registered in the system along with
their operations.

GET ?$expand=Operations HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/MANUFACTURING/21.200.001/BillOfMaterial
Accept: application/json
Content-Type: application/json

If you want to retrieve additional details of the operations of BOMs, you cannot specify the Operations/
Material, Operations/Overheads, Operations/Steps, or Operations/Tools fields in the $expand
parameter of the above request, because this would cause the Optimization cannot be performed error to be
generated. Instead, you should retrieve a single BOM and specify these fields in the $expand parameter of the
request.

BusinessAccount

This chapter presents code examples showing requests that use the BusinessAccount entity.

Retrieve the List of Business Accounts

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve the list of available business accounts along with their data from Acumatica ERP. This list is
exposed by the Business Accounts (CR3030PL) generic inquiry. The Business Accounts (CR303000) form displays the
data of an individual business account.
 REST API Examples | 125

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following HTTP request example to retrieve data of the business account with the ABAKERY ID.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$expand=Activities,Campaigns,Cases,Orders
&$filter=BusinessAccountID%20eq%20'ABAKERY' HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/BusinessAccount
Accept: application/json
Content-Type: application/json

Case

This chapter presents code examples showing requests that use the Case entity.

Create a Case

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create cases in Acumatica ERP. For more information about the creation of cases, see Creating Cases.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a case through the contract-based REST API.
 REST API Examples | 126

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Case
Accept: application/json
Content-Type: application/json

{
"ClassID": {"value": "JREPAIR"},
"BusinessAccount": {"value": "ABAKERY"},
"ContactID": {"value": "100211"},
"Subject": {"value": "Some Subject"},
"custom": {
"Case": {
"AttributeMODEL": {
"value": "JUICER15:Commercial juicer with a prod rate of 1.5 l per min"
}
}
}
}

Link a Case to Another Case

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create cases in Acumatica ERP and link them to another case defined in Acumatica ERP. For details
about the relations between cases, see Case Management: General Information.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a case and link it to another case through the contract-based
REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Case
Accept: application/json
 REST API Examples | 127

Content-Type: application/json

{
"ClassID": {
"value": "SERVCONS"
},
"BusinessAccount": {
"value": "GOODFOOD"
},
"Subject": {
"value": "Billing plan"
},
"RelatedCases": [
{
"CaseID": {
"value": "000004"
}
}
]
}

Usage Notes
To create a case and establish its relation with another case, you need to specify the case ID of the related case by
using the CaseID field of the RelatedCases detail entity of the Case entity.

The ParentCaseID field of the RelatedCases detail entity of the Case entity is never returned
by the system and cannot be used for the assignment of values.

Related Links
• Case Management: General Information

CompaniesStructure

This chapter presents code examples showing requests that use the CompaniesStructure entity.

Retrieve the Companies' Structure

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve information about the companies' structure—that is, the structure of the companies and
branches in the tenant.. For this purpose, the Company Branch (CS401000) generic inquiry is used.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
 REST API Examples | 128

2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

You can use the following HTTP request example to retrieve the companies’ structure.

PUT ?$expand=Results HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/CompaniesStructure
Accept: application/json
Content-Type: application/json

{}

Contact

This chapter presents code examples showing requests that use the Contact entity.

Create a Contact with Attributes

Through the contract-based REST API, external systems can create contacts with attributes.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Customer Management feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create the Brent Edds lead through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Contact
Accept: application/json
Content-Type: application/json
 REST API Examples | 129

{
"FirstName": {"value": "Brent"},
"LastName": {"value": "Edds"},
"Email": {"value": "[email protected]"},
"ContactClass": {"value": "ENDCUST"},
"Attributes": [
{
"AttributeID": {"value": "INTEREST"},
"Value": {"value": "Jam,Maint"}
}
]
}

Usage Notes
In the Default/20.200.001 and Default/22.200.001 endpoints, the attributes of top-level entities are exposed in the
AttributeValue entities. An AttributeValue entity has the following fields:
• AttributeID : The attribute identifier. Both internal values and external values can be used to set this
field, but only the internal value can be retrieved.
• AttributeDescription: The external value of the attribute identifier. The field is read-only.
• Value: The attribute value. When the value is retrieved, the internal value is returned. To set the value, the
internal value and the external value (for control types other than multi-select combo boxes) can be used.
For multi-select combo boxes, an external value can be accepted only if it contains a single value without
commas. For various control types, the following rules apply to the Value field:
• For check boxes, 0 is returned if the check box is not selected, and 1 is returned if the check box is
selected. For setting a value, 0, 1, false (case-insensitive), or true (case-insensitive) can be used.
• For multi-select combo boxes, values separated by commas (namely, Value1,Value2,Value3) compose the
internal value.
• For selectors, the values are set and retrieved in the same way as they are for text boxes.
• For date edit boxes, the internal values must be parsable through the use of the
System.Globalization.CultureInfo.InvariantCulture Microso .NET object.
• For combo boxes of all types, date edit boxes, and check boxes, an error message is written to the error
field when an attempt is made to set an unsupported value.
• ValueDescription: The external value of the attribute. The field is read-only. The external value is
based on the control type as follows:
• For text boxes and date edit boxes, the external value is the same as the internal value.
• For check boxes, the external value can be either True or False.
• For combo boxes, the label is used as the external value.
• For multi-select combo boxes, labels separated by commas and spaces aer commas (namely, Label1,
Label2, Label3) compose the external value.
• Required: An indicator of whether the attribute is mandatory. This field is read-only.
• RefNoteID: The value of the NoteID field of the object to which this attribute is referred. This field is
read-only.

Activate a Contact

By using the contract-based REST API, you can activate and deactivate contacts in Acumatica ERP. You do this by
setting the Active field of a Contact object to true or false, respectively.
 REST API Examples | 130

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to deactivate the Brent Edds contact through the contract-based REST
API. The creation of a contact is described in Create a Contact with Attributes.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT $filter=FirstName%20eq%20'Brent'%20and%20LastName%20eq%20'Edds' HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Contacts
Accept: application/json
Content-Type: application/json

{
"Active": {"value": false}
}

Retrieve the List of Contacts

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve the list of available contacts, along with their data, from Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve the detailed information about the 100073 contact through
the contract-based REST API.
 REST API Examples | 131

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$expand=Activities,Address,Campaigns,Cases,Notifications,Opportunities&
$filter=ContactID%20eq%20100073 HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Contact
Accept: application/json
Content-Type: application/json

Link Multiple Contacts to a Customer

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can link multiple contacts to a customer in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to link the 100196 contact to the ABAKERY business account through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Contact
Accept: application/json
Content-Type: application/json

{
"BusinessAccount": {"value": "ABAKERY"},
"ContactID": {"value": 100196}
}

Customer

This chapter presents code examples showing requests that use the Customer entity.
 REST API Examples | 132

Create a Customer

By using the contract-based REST API, you can create a customer in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a customer through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Customer
Accept: application/json
Content-Type: application/json

{
"CustomerID": {"value": "Cust01"},
"CustomerName": {"value": "Customer 01"},
"CustomerClass": {"value": "DEFAULT"}
}

Retrieve the List of Customers with Contacts

By using the contract-based REST API, external systems can retrieve the list of customers with contacts from
Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
 REST API Examples | 133

Request
You can use the following request example to retrieve the list of contacts through the contract-based REST API. For
each contact, the main contact, including the address, is retrieved.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET $expand=MainContact,MainContact/Address HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Customer
Accept: application/json
Content-Type: application/json

Update a Customer

By using the contract-based REST API, external systems can update a customer record in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to update a customer record that has the [email protected] email
address through the contract-based REST API. By this request, the customer class and the billing contact of the
customer are modified.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT $expand=MainContact,BillingContact&
$filter=MainContact/Email%20eq%20'[email protected]' HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Customer
Accept: application/json
Content-Type: application/json

{
"CustomerClass": {"value": "INTL"},
"BillingContactOverride": {"value": true},
"BillingContact": {
"Email": {"value": "[email protected]"},
"Attention": {"value": "Mr. Jack Green"},
"JobTitle": {"value": ""}
}
 REST API Examples | 134

Retrieve the Shipping Contact of a Customer

By using the contract-based REST API, external systems can retrieve the shipping contact of a customer from
Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve the shipping contact of the ABAKERY customer through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$expand=ShippingContact&$filter=CustomerID%20eq%20'ABAKERY' HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Customer
Accept: application/json
Content-Type: application/json

Employee

This chapter presents code examples showing requests that use the Employee entity.

Create an Employee

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create employees in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
 REST API Examples | 135

2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following HTTP request example to create an employee, Jane Doe.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Employee
Accept: application/json
Content-Type: application/json

{
"Status": {"value": "Active"},
"EmployeeID": {"value": "ExampleID"},
"EmployeeName": {"value": "Doe, Jane"},
"FinancialSettings":
{
"APAccount": {"value": "20000"},
"APSubaccount": {"value": "000000"},
"CashAccount": {"value": "10200WH"},
"ExpenseAccount": {"value": "63000"},
"ExpenseSubaccount": {"value": "000000"},
"PaymentMethod": {"value": "CHECK"},
"PrepaymentAccount": {"value": "20000"},
"PrepaymentSubaccount": {"value": "000000"},
"SalesAccount": {"value": "40000"},
"SalesSubaccount": {"value": "000000"},
"TaxZone": {},
"Terms": {"value": "7D"}
},
"EmployeeSettings":
{
"BranchID": {"value": "HEADOFFICE"},
"Calendar": {"value": "MAIN"},
"CurrencyID": {"value": "USD"},
"CurrencyRateTypeID": {"value": "SPOT"},
"DepartmentID": {"value": "AFTERSALES"},
"EmployeeClass": {"value": "EMPHOURLY"}
},
"ContactInfo":
{
"LastName": {"value": "Doe"}
}
}
 REST API Examples | 136

Retrieve Information about an Employee

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve information about employees from Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following HTTP request example to retrieve the data of the employee with the EP00000001 ID.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$expand=ContactInfo,Delegates,EmployeeSettings,EmploymentHistory,
FinancialSettings&$filter=EmployeeID eq 'EP00000001' HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Employee
Accept: application/json
Content-Type: application/json

{}

InventorySummaryInquiry

This chapter presents code examples showing requests that use the InventorySummaryInquiry entity.

Get a Summary of an Inventory Item

By using the contract-based REST API, external systems can retrieve the summary information about an inventory
item from Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
 REST API Examples | 137

2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve the summary information about the APJAM08 inventory item
through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Results HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/InventorySummaryInquiry
Accept: application/json
Content-Type: application/json

{
"InventoryID": { "value": "APJAM08" }
}

Invoice

This chapter presents code examples showing requests that use the Invoice entity.

Create an Invoice with Tax Parameters Overridden

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create invoices with the tax parameters overridden.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the SalesDemo dataset. For details on deploying an instance, see
To Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the PRODWHOLE branch.

To further prepare the system, you need to create a tax and a tax category that uses this tax, and modify the existing
tax zone so that it will use the new tax. You perform these tasks as follows:
1. On the Taxes (TX205000) form, create a tax with the tax schedule as follows:
a. Create a tax with the following parameters:
• Tax ID: PST
• Description: Tax ID for testing
 REST API Examples | 138

• Tax Type: VAT

• Include in VAT Taxable Total: Selected
• Exclude from Tax on Tax Calculation: Selected
• Tax Agency: CANADABC
b. On the Tax Schedule tab of the form, add two rows with the following data.

Column First Row Second Row

Start Data 1/1/1900 1/1/1900

Tax Rate 5 5

Min. Taxable Amount 0 0

Max. Taxable Amount 0 0

Reporting Group Input Tax (purchases) Output Tax (sales)

Group Type Input Output

c. Click Save.
2. On the Tax Categories (TX205500) form, create the TEST tax category with the Tax category for test
description and add the CAGST and PST taxes to the tax category.
3. On the Applicable Taxes tab of the Tax Zones (TX206000) form, add the PST tax to the CANADABC tax zone.

Request
You can use the following example of an HTTP request to create an invoice with the tax parameters that are
different from those registered in the system.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details,TaxDetails HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Invoice
Accept: application/json
Content-Type: application/json

{
"CreatedDateTime": {
"value": "1900-01-01T03:00:00+03:00"
},
"Customer": {
"value": "AACUSTOMER"
},
"Date": {
"value": "2022-01-23T00:00:00+03:00"
},
"Description": {
"value": "Invoice with Taxes"
},
 REST API Examples | 139

"Details": [
{
"Account": {
"value": "40000"
},
"Amount": {
"value": 1000
},
"Branch": {
"value": "PRODWHOLE"
},
"ExtendedPrice": {
"value": 1000
},
"InventoryID": {
"value": "CONSULTING"
},
"LineNbr": {
"value": 1
},
"ProjectTask": {},
"Qty": {
"value": 10
},
"TransactionDescription": {
"value": "Project Consulting"
},
"UnitPrice": {
"value": 100
},
"UOM": {
"value": "HOUR"
}
}
],
"Hold": {
"value": false
},
"IsTaxValid": {
"value": true
},
"LocationID": {
"value": "MAIN"
},
"PostPeriod": {
"value": "012022"
},
"TaxDetails": [
{
"TaxID": {
"value": "CAGST"
},
"TaxableAmount": {
"value": 1000.0
},
"TaxAmount": {
"value": 150.0
 REST API Examples | 140

},
"ExpenseAmount": {
"value": 0.0
}
},
{
"TaxID": {
"value": "PST"
},
"TaxableAmount": {
"value": 1000.0
},
"TaxAmount": {
"value": 150.0
}
}
],
"Type": {
"value": "Invoice"
},
"custom": {
"CurrentDocument": {
"TaxZoneID": {
"type": "CustomStringField",
"value": "CANADABC"
}
}
}
}

Usage Notes
In the request above, you have set the IsTaxValid value to true to use in the invoice the tax parameters specified
in the TaxDetails field. If you do not specify this value, the tax parameters that are registered in the system
will be used instead. In particular, the tax amounts equal to 50 will be set both for the CAGST and PST taxes in the
created bill, and the CABCPST tax of the amount 70 will be applied as well.

Retrieve the List of Invoices

By using the contract-based REST API, external systems can retrieve the list of available invoices from Acumatica
ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
 REST API Examples | 141

Request
You can use the following request example to retrieve the full list of invoices through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Invoice
Accept: application/json
Content-Type: application/json

Release an AR Invoice

By using the contract-based REST API, external systems can release AR invoices in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
3. On the Invoices and Memos (AR301000) form, create an invoice, save it, and click Remove Hold.
4. In the database, in the ARInvoiceNbr table, learn the RefNoteID value that corresponds to the
reference number of the created invoice, which is stored in the RefNbr column.

Request
You can use the following request example to release an invoice through the contract-based REST API. You specify
the RefNoteID value of the invoice in the id field of the request body.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST /ReleaseInvoice HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Invoice
Accept: application/json
Content-Type: application/json

{
"entity": { "id": "8beb2af9-fa58-ec11-9e16-9828a61840c3" }
}
 REST API Examples | 142

Specify the Tax Zone for an Invoice

By using the contract-based REST API, external systems can specify the tax zone for an invoice in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to set the tax zone of the 000097 invoice (whose id is 8deb6bf9-2072-
eb11-b83e-00155d408001) to AVALARA through the contract-based REST API. This request also clears the Don't Print
box (in the Print and Email Options section of the Financial tab) of the Invoices and Memos (AR301000) form for
the invoice.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$custom=CurrentDocument.TaxZoneID,CurrentDocument.DontPrint HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Invoice
Accept: application/json
Content-Type: application/json

{
"id": "8deb6bf9-2072-eb11-b83e-00155d408001",
"custom": {
"CurrentDocument": {
"TaxZoneID": {
"value": "AVALARA"
},
"DontPrint": {
"value": false
}
}
}
}

ItemWarehouse

This chapter presents code examples showing requests that use the ItemWarehouse entity.
 REST API Examples | 143

Override Values in the Item–Warehouse Details

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can specify item–warehouse details, mark particular fields as overridden, and set new values for these
fields.

Testing of the Request

Before you test the code below, you do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management, Inventory,
and Multiple Warehouses features are enabled.
3. To sign in to the instance in the client application, use the tenant name that you specified when you created
the instance and the HEADOFFICE branch.

Request

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

You can use the following example of an HTTP request to specify item–warehouse details for the APPLES inventory
item and the RETAIL warehouse. This request marks the MaxQty, ReorderPoint, and SafetyStock
fields as overridden and specifies their new values. The specification of the new values for the MSRP,
ReplenishmentMethod, ReplenishmentSource, Seasonality, PreferredLocation,
PreferredVendor, and ServiceLevel fields in the request body has no effect because these fields are not
marked as overridden.
PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ItemWarehouse
Accept: application/json
Content-Type: application/json

{
"InventoryID": { "value": "APPLES" },
"OverrideMaxQty": { "value": true },
"MaxQty": { "value": 2222 },
"OverridePrice": { "value": false },
"MSRP": { "value": 600 },
"OverrideReorderPoint": { "value": true },
"ReorderPoint": { "value": 14 },
"ReplenishmentClass": { "value": "PURCHASE" },
"OverrideReplenishmentSettings": { "value": false },
"ReplenishmentMethod": { "value": "Min./Max." },
"ReplenishmentSource": { "value": "Purchase" },
"Seasonality": { "value": "NONE" },
"OverrideSafetyStock": { "value": true },
"SafetyStock": { "value": 244 },
"PreferredLocation": { "value": "MAIN" },
 REST API Examples | 144

"PreferredVendor": { "value": "ALLFRUITS" },

"ServiceLevel": { "value": 87 },
"WarehouseID": { "value": "RETAIL" }
}

JournalTransaction

This chapter presents code examples showing requests that use the JournalTransaction entity.

Create a GL Transaction with a Project Code That Does Not Produce a Project
Transaction

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can import to Acumatica ERP general ledger transactions with project codes that do not produce project
transactions.
To create a general ledger transaction with a project code that does not produce a project transaction, you set the
IsNonPM field of the JournalTransaction entity to true.
This setting could be used in the following user scenario: A construction company has built an integrated solution
of Acumatica ERP with an external payroll system. The external payroll system calculates payoffs, including
benefits, additions, deductions, and taxes. Once a week, the construction company needs to import general ledger
transactions with project information from this payroll system to Acumatica ERP, where they are verified and
released. The construction company doesn't want to update the project subledger in Acumatica ERP with the
information from general ledger transactions (for example, if the standard labor costs have already been posted to
the project subledger from time entries).

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a general ledger transaction through the contract-based REST
API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/JournalTransaction
Accept: application/json
Content-Type: application/json
 REST API Examples | 145

{
"Module" : {"value" : "GL"},
"TransactionDate" : {"value" : "2019-08-15T00:00:00"},
"Description" : {"value" : "Transaction description"},
"BranchID" : {"value" : "HEADOFFICE"},
"Details" : [
{
"BranchID" : {"value" : "HEADOFFICE"},
"Account" : {"value" : "10200"},
"CostCode" : {"value" : "0000"},
"IsNonPM" : {"value" : true}
}
]
}

Lead

This chapter presents code examples showing requests that use the Lead entity.

Create a Lead

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a lead in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a lead through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Lead
Accept: application/json
Content-Type: application/json

{
"FirstName": {"value": "Brent"},
"LastName": {"value": "Edds"},
 REST API Examples | 146

"Email": {"value": "[email protected]"}

}

Ledger

This chapter presents code examples showing requests that use the Ledger entity.

Retrieve the List of Ledgers

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve a list of ledgers. For details about the management of ledgers, see Managing Ledgers.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

You can use the following HTTP request example to retrieve a list of the available ledgers. This request also
retrieves information about the companies associated with each ledger and the branches that can post to each
ledger.

GET ?$expand=Branches,Companies&$select=LedgerID,Branches/BranchID,Branches/BranchName,
Branches/CompanyName,Companies/Company,Companies/CompanyName HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Ledger
Accept: application/json
Content-Type: application/json

Opportunity

This chapter presents code examples showing requests that use the Opportunity entity.

Create a Sales Order from an Opportunity

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a sales order from an opportunity in Acumatica ERP.
 REST API Examples | 147

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a sales order from the 000003 opportunity through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST /CreateOpportunitySalesOrder HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Opportunity
Accept: application/json
Content-Type: application/json

{
"entity": { "id": "f8e643f0-2110-e911-9fbe-7c5cf8918e20" }
}

Usage Notes
You can learn the value of the id field for the needed opportunity by viewing the CROpportunity database
table.

Create a Business Account from an Opportunity

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a business account from an opportunity in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
 REST API Examples | 148

Request
You can use the following request example to create a business account from the 000002 opportunity through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST /CreateAccountFromOpportunity HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Opportunity
Accept: application/json
Content-Type: application/json

{
"entity": { "id": "e11f3abe-2110-e911-9fbe-7c5cf8918e20",
"custom": {
"AccountInfo": {
"BAccountID": { "value": "11111" },
"AccountName": { "value": "asdqwe" }
},
"ContactInfo": {
"LastName": { "value": "test" }
}
}
}
}

Usage Notes
You can learn the value of the id field for the needed opportunity by viewing the CROpportunity database
table.

Payment

This chapter presents code examples showing requests that use the Payment entity.

Create an AR Payment

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create accounts receivable payments in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
 REST API Examples | 149

2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create an AR payment through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Payment
Accept: application/json
Content-Type: application/json

{
"Branch": { "value": "HEADOFFICE" },
"CardAccountNbr": {},
"CashAccount": { "value": "10200WH" },
"CurrencyID": { "value": "USD" },
"CustomerID": { "value": "ABAKERY" },
"Description": { "value": "Consumer Good Toy Order" },
"PaymentAmount": { "value": 159821.6000 },
"PaymentMethod": { "value": "CHECK" },
"ProcessingCenterID": {},
"Type": { "value": "Payment" }
}

Retrieve Payments One by One

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve payments one by one from Acumatica ERP. In this case, the key fields—namely, the payment
type and reference number—are specified in a request. When a single payment is retrieved by using the contract-
based REST API, the following information can be retrieved as well: documents to apply, orders to apply,
application history, credit card processing information, and credit card transaction information.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve the 000068 credit memo, along with detailed information
about it, through the contract-based REST API.
 REST API Examples | 150

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /Credit%20Memo/000068?$expand=ApplicationHistory,CreditCardProcessingInfo,
CreditCardTransactionInfo,DocumentsToApply,OrdersToApply HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Payment
Accept: application/json
Content-Type: application/json

ProFormaInvoice

This chapter presents code examples showing requests that use the ProFormaInvoice entity.

Send a Pro Forma Invoice by Email

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create pro forma invoices and send them by email. For details about pro forma invoices, see Pro Forma
Invoice: General Information.

Testing of the Request

Sending a pro forma invoice by email is a final stage of a more common task of creating and sending a pro forma
invoice by email.
If you were performing the overall process of creating and sending a pro forma invoice by email, you (or another
employee) would perform the following general steps:
1. Create a Project from a Project Template
2. Make a Project Active
3. Specify the Next Billing Date for a Project
4. Retrieve a Project Task
5. Activate a Project Task
6. Specify the Progress of a Project Task
7. Invoke Project Billing
8. Retrieve the List of Pro Forma Invoices of a Project
9. Send a Pro Forma Invoice by Email

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
 REST API Examples | 151

Requests
You can use the following sequence of examples of HTTP requests to send a pro forma invoice by email through the
contract-based REST API. You will use the RefNbr value of the pro forma invoice that is retrieved in Retrieve the
List of Pro Forma Invoices of a Project.

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

Do the following:
1. Send the pro forma invoice by email.

POST /EmailProFormaInvoice HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProFormaInvoice
Accept: application/json
Content-Type: application/json

{
"entity" : {
"RefNbr": {
"value": "000019"
}
}
}

HTTP/1.1 202 Accepted

Location: [/<Acumatica ERP instance URL>]/entity/Default/22.200.001/
ProFormaInvoice/EmailProFormaInvoice/status/a4caa455-0eed-4c11-a5a9-2a8333e53db1

2. Monitor the status of the operation until the system returns the 204 No Content code.

GET /EmailProFormaInvoice/status/a4caa455-0eed-4c11-a5a9-2a8333e53db1 HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProFormaInvoice
Accept: application/json
Content-Type: application/json

HTTP/1.1 204 No Content

Usage Notes
For a pro forma invoice to be created from the project, the project must have the Customer, BillingRule,
BillingPeriod, and NextBillingDate values specified, and must have the Active status. Because of data
validation in the project, NextBillingDate cannot be specified for a project with the In Planning status, and
you cannot change the customer in a project with the Active status. Therefore, these settings can be specified only
in multiple API calls.
Related Links
• Pro Forma Invoice: General Information
 REST API Examples | 152

Project

This chapter presents code examples showing requests that use the Project entity.

Create a Project from a Project Template

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a project from a project template. This step can be part of the larger process of creating and
sending a pro forma invoice by email, which is described in Send a Pro Forma Invoice by Email.
For details about project templates, see Project Templates and Common Tasks: General Information.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to create a project from the PROGRESS project template and
specify the Customer, BillingRule, and BillingPeriod settings of the project through the contract-based
REST API.
In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

{
"ProjectID" : {"value" : "TESTPR3"},
"ProjectTemplateID" : {"value" : "PROGRESS"},
"Customer" : {"value" : "COFFEESHOP"},
"BillingAndAllocationSettings" :
{
"BillingRule" : {"value" : "PROGRESS"},
"BillingPeriod" : {"value" : "Month"},
}
}
 REST API Examples | 153

Related Links
• Pro Forma Invoice: General Information
• Project Billing: General Information

Make a Project Active

For a pro forma invoice to be created from a project, the project must have Customer, BillingRule,
BillingPeriod, and NextBillingDate specified, and must have the Active status. If you are using the
contract-based REST API to integrate Acumatica ERP with external systems, these external systems can create make
a project active. This step can be part of the larger process of creating and sending a pro forma invoice by email,
which is described in Send a Pro Forma Invoice by Email.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
4. Implement the Create a Project from a Project Template example as a prerequisite to the current example.
The project must exist before you can make it active.

Request
You can use the following example of an HTTP request to make the TESTPR3 project active through the contract-
based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

{
"ProjectID" : {"value" : "TESTPR3"},
"Hold" : {"value" : false}
}

Specify the Next Billing Date for a Project

For a pro forma invoice to be created from a project, the project must have Customer, BillingRule,
BillingPeriod, and NextBillingDate specified, and must have the Active status. If you are using the
contract-based REST API to integrate Acumatica ERP with external systems, these external systems can specify
 REST API Examples | 154

various settings for a project, such as the next billing date. This step can be part of the larger process of creating
and sending a pro forma invoice by email, which is described in Send a Pro Forma Invoice by Email.

The next billing date of a project is specified on the Summary tab (Billing and Allocation Settings
section) of the Projects (PM301000) form.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
4. Implement the Make a Project Active example as a prerequisite to the current example. Because of data
validation in the project, NextBillingDate is specified for the project aer it is assigned the Active
status.

Request
You can use the following example of an HTTP request to specify the next billing date for a project.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

{
"ProjectID" : {"value" : "TESTPR3"},
"BillingAndAllocationSettings" :
{
"NextBillingDate" : {"value" : "2021-08-15"}
}
}

Related Links
• Project Billing: General Information

Invoke Project Billing

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can invoke project billing. This step can be part of the larger process of creating and sending a pro forma
invoice by email, which is described in Send a Pro Forma Invoice by Email.
 REST API Examples | 155

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name that you specified when you created
the instance and the HEADOFFICE branch.
4. Implement the Specify the Progress of a Project Task example as a prerequisite to the current example.

Requests
You can use the following sequence of examples of HTTP requests to run project billing and check the
completeness of this operation through the contract-based REST API:

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

1. Invoke project billing to create a pro forma invoice.

POST /RunProjectBilling HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

{
"entity" : {
"ProjectID": {
"value": "TESTPR3"
}
}
}

HTTP/1.1 202 Accepted

Location: [/<Acumatica ERP instance URL>]/entity/Default/22.200.001/
Project/RunProjectBilling/status/6952c6d1-04be-4330-a26e-c6b855ba332c

2. Monitor the status of the operation until the system returns the 204 No Content code.

GET /RunProjectBilling/status/6952c6d1-04be-4330-a26e-c6b855ba332c HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

HTTP/1.1 204 No Content

Related Links
• Pro Forma Invoice: General Information
• Project Billing: General Information
 REST API Examples | 156

Retrieve the List of Pro Forma Invoices of a Project

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve the list of the pro forma invoices of a project. This step can be part of the larger process of
creating and sending a pro forma invoice by email, which is described in Send a Pro Forma Invoice by Email.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
4. Implement the Invoke Project Billing example as a prerequisite to the current example, so that the TESTPR3
project will be created with a pro forma invoice.

Request
You can use the following example of an HTTP request to retrieve the list of pro forma invoices of a project through
the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /TESTPR3?$expand=Invoices HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

To obtain the list of pro forma invoices of the project with the TESTPR3 project ID, you can also use the
GET request for the ProFormaInvoice entity with the $filter=ProjectID eq 'TESTPR3'
parameter.

ProjectBudget

This chapter presents code examples showing requests that use the ProjectBudget entity.

Specify the Progress of a Project Task

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can specify the progress of a project task. This step can be part of the larger process of creating and
sending a pro forma invoice by email, which is described in Send a Pro Forma Invoice by Email.
 REST API Examples | 157

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
4. Implement the Activate a Project Task example as a prerequisite to the current example. In this prerequisite
example, you will prepare the project task for which the progress will be specified.

Request
You can use the following example of an HTTP request to specify the progress of a project task through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProjectBudget
Accept: application/json
Content-Type: application/json

{
"ProjectTaskID" : {"value" : "PHASE1"},
"ProjectID" : {"value" : "TESTPR3"},
"InventoryID" : {"value" : "<N/A>"},
"Completed" : {"value" : 25},
"PendingInvoiceAmount" : {"value" : 725}
}

ProjectTask

This chapter presents code examples showing requests that use the ProjectTask entity.

Retrieve a Project Task

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve a project task that meets some conditions. This retrieval step can be part of a larger process of
creating and sending a pro forma invoice by email, which is described in Send a Pro Forma Invoice by Email.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
 REST API Examples | 158

1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to retrieve a project task with the TESTPR3 project ID and the
PHASE1 task ID through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$filter=ProjectID%20eq%20'TESTPR3'%20and%20ProjectTaskID%20eq%20'PHASE1' HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProjectTask
Accept: application/json
Content-Type: application/json

Activate a Project Task

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can activate a project task. This activation task can be part of a more common task of creating and sending
a pro forma invoice by email, which is described in Send a Pro Forma Invoice by Email.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
4. Implement the Retrieve a Project Task example as a prerequisite to the current example. You need to learn
the ID of the project task to activate.

Request
You can use the following example of an HTTP request to activate a project task with a certain ID through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST /Activate HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProjectTask
 REST API Examples | 159

Accept: application/json
Content-Type: application/json

{
"entity":
{
"id": "35b72591-64ed-eb11-9dee-9828a61840c3"
},
"parameters": {}
}

Related Links
• Pro Forma Invoice: General Information
• Project Billing: General Information

PurchaseOrder

This chapter presents code examples showing requests that use the PurchaseOrder entity.

Create a Purchase Order

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create purchase orders. For details about the management of purchase documents, see Managing
Purchase Documents.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

You can use the following example of an HTTP request to create a purchase order and release it from hold at once.
PUT ?$expand=Details HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseOrder
Accept: application/json
Content-Type: application/json

{
 REST API Examples | 160

"VendorID": { "value": "GOODFRUITS" },

"Location": { "value": "MAIN" },
"Details": [
{
"BranchID": { "value": "HEADOFFICE" },
"InventoryID": { "value": "APPLES" },
"OrderQty": { "value": 1 },
"WarehouseID": { "value": "WHOLESALE" },
"UOM": { "value": "LB" }
}
],
"Hold": { "value": false }
}

Create a Purchase Order with Tax Parameters Overridden

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create purchase orders. In the orders, these systems can override the tax details that are calculated by
the system.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

You can use the following example of an HTTP request to create a purchase order and set the amount of the
NYSTATETAX tax to 0.
PUT ?$expand=Details,TaxDetails HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseOrder
Accept: application/json
Content-Type: application/json

{
"Branch": { "value": "HEADOFFICE" },
"Details": [
{
"BranchID": { "value": "HEADOFFICE" },
"InventoryID": { "value": "APPLES" },
"LineType": { "value": "Goods for IN" },
 REST API Examples | 161

"OrderQty": { "value": 20 },
"OrderType": { "value": "RO" },
"TaxCategory": { "value": "TAXABLE" },
"UnitCost": { "value": 2.29 },
"UOM": { "value": "LB" },
"WarehouseID": { "value": "WHOLESALE" }
}
],
"Hold": { "value": true },
"IsTaxValid": { "value": true },
"Location": { "value": "MAIN" },
"TaxDetails": [
{
"TaxableAmount": { "value": 45.8 },
"TaxAmount": { "value": 0 },
"TaxID": { "value": "NYSTATETAX" },
"TaxRate": { "value": 0 }
}
],
"Terms": { "value": "30D" },
"Type": { "value": "Normal" },
"VendorID": { "value": "ALLFRUITS" },
"VendorTaxZone": { "value": "NYZONE" }
}

Usage Notes
During the creation or update of a purchase order with a REST API request, the value of the IsTaxValid field of
the PurchaseOrder entity is used to determine how the tax details are calculated.
If the IsTaxValid field is specified in the request body, its value is set to true, and an external tax zone is
specified, then the tax details from the request body are used without modification, and no other taxes are applied.
If the IsTaxValid field is specified in the request body, its value is set to true, and an internal tax zone is
specified, then the tax details from the request body are compared to those calculated by the system. If the taxes
specified in the request body are present among those calculated by the system, then the tax details from the
request body are used without modification and no other taxes are applied.
If the IsTaxValid field is not specified in the request body or its value is not set to true, tax calculation is
performed by the system.

PurchaseReceipt

This chapter presents code examples showing requests that use the PurchaseReceipt entity.

Create a Purchase Receipt

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create purchase receipts. For details about the management of purchase documents, see Managing
Purchase Documents.
 REST API Examples | 162

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

You can use the following example of HTTP requests to create a purchase receipt from the purchase order. The
creation of a purchase order is described in Create a Purchase Order.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"VendorID": { "value": "GOODFRUITS" },
"Location": { "value": "MAIN" },
"Details": [
{
"POOrderNbr": { "value": "000030" },
"POOrderType": { "value": "Normal" }
}
]
}

Insert Lines with Allocations (with Location) in a PO Receipt

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create purchase receipts and specify the locations of items in them. For details about the management
of purchase documents, see Managing Purchase Documents.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
 REST API Examples | 163

2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to create a purchase receipt and specify the locations of
particular items.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details,Details/Allocations HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"Type": {"value": "Receipt"},
"VendorID": {"value": "AAVENDOR"},
"CreateBill": {"value": "False"},
"Description": {"value": "Test receipt with allocations"},
"Details": [
{
"InventoryID": {"value": "CONBABY1"},
"ReceiptQty": {"value": "11"},
"Allocations": [
{
"Location": {"value": "DOCK"},
"Qty": {"value": "5"}
},
{
"Location": {"value": "R1S1"},
"Qty": {"value": "6"}
}
]
},
{
"InventoryID": {"value": "CONBOTTLE1"},
"ReceiptQty": {"value": "15"},
"Allocations": [
{
"Location": {"value": "DROPSHIP"},
"Qty": {"value": "7"}
},
{
"Location": {"value": "RECEIVING"},
"Qty": {"value": "8"}
}
]
}
]
 REST API Examples | 164

Insert Lines with Allocations (with Expiration Dates) in a PO Receipt

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create purchase receipts and specify the expiration dates of the items in them. For details about the
management of purchase documents, see Managing Purchase Documents.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management and Lot
and Serial Tracking features are enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to create a purchase receipt and specify the expiration dates
of particular goods.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details,Details/Allocations HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"Type": {"value": "Receipt"},
"VendorID": {"value": "GOODFRUITS"},
"CreateBill": {"value": "False"},
"Description": {"value": "Test receipt with Expiration Date in Allocations"},
"Details": [
{
"Branch": {"value": "HEADOFFICE"},
"InventoryID": {"value": "ORANGES"},
"ReceiptQty": {"value": 2},
"Warehouse": {"value": "WHOLESALE"},
"LotSerialNbr": {"value": ""},
"ExpirationDate": {"value": ""},
"Allocations": [
{
"Location": {"value": "MAIN"},
"Qty": {"value": 1},
"LotSerialNbr": {"value": "a"},
 REST API Examples | 165

"ExpirationDate": {"value": "2020-04-25"}

},
{
"Location": {"value": "MAIN"},
"Qty": {"value": 1},
"LotSerialNbr": {"value": "b"},
"ExpirationDate": {"value": "2020-04-27"}
}
]
}
]
}

Create a Purchase Return from a Purchase Receipt Record

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create purchase returns from purchase receipt records. For details about the management of purchase
documents, see Managing Purchase Documents.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to create a purchase return by using the purchase receipt
number (the POReceiptNbr field) and the purchase receipt line number (the POReceiptLineNbr field). Thus,
a specific line of a purchase receipt will be added to the purchase return being created.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"Type": {"value": "Return"},
"VendorID": {"value": "GOODFRUITS"},
"CreateBill": {"value": "False"},
"Description": {"value": "Test return (one PR line)"},
"ProcessReturnWithOriginalCost": {"value": "True"},
"Details": [
 REST API Examples | 166

{
"POReceiptNbr": {"value": "000016"},
"POReceiptLineNbr": {"value": "1"}
}
]
}

Create a Purchase Return from a Purchase Receipt

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create purchase returns from purchase receipts. For details about the management of purchase
documents, see Managing Purchase Documents.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to create a purchase return by using the purchase receipt
number (the POReceiptNbr field). Thus, the whole purchase receipt will be used in the purchase return being
created.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"Type": {"value": "Return"},
"VendorID": {"value": "GOODFRUITS"},
"CreateBill": {"value": "False"},
"Description": {"value": "Test return (all PR lines)"},
"ProcessReturnWithOriginalCost": {"value": "True"},
"Details": [
{
"POReceiptNbr": {"value": "000013"}
}
]
 REST API Examples | 167

Create a Purchase Return for Particular Items

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create purchase returns by specifying items to return. For details about the management of purchase
documents, see Managing Purchase Documents.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to create a purchase return by specifying items to return. In
the request, no information about the original purchase receipts is specified.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"Type": {"value": "Return"},
"VendorID": {"value": "GOODFRUITS"},
"CreateBill": {"value": "False"},
"Description": {"value": "Test return"},
"ProcessReturnWithOriginalCost": {"value": "True"},
"Details": [
{
"Branch": {"value": "HEADOFFICE"},
"InventoryID": {"value": "APPLES"},
"Warehouse": {"value": "WHOLESALE"},
"Location": {"value": "MAIN"},
"ReceiptQty": {"value": "1"},
"ExtendedCost": {"value": "3"}
}
]
}
 REST API Examples | 168

Create a Purchase Receipt in a Non-Base Currency

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a purchase receipt in a non-base currency. For details about the management of purchase
documents, see Managing Purchase Documents.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to create a purchase receipt in a non-base currency by
using the CurrencyID and CurrencyRate fields. In the example, you will override cost-related values (such as
UnitCost or ExtendedCost).

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"Type": {"value": "Receipt"},
"VendorID": {"value": "GOODFRUITS"},
"CreateBill": {"value": "False"},
"CurrencyID": {"value": "EUR"},
"CurrencyRate": {"value": "1.2"},
"Description": {"value": "Test receipt in non-base currency and with new cost fields"},
"Details": [
{
"Branch": {"value": "HEADOFFICE"},
"InventoryID": {"value": "APPLES"},
"Warehouse": {"value": "WHOLESALE"},
"ReceiptQty": {"value": 1.0},
"ExpirationDate": {"value": "2021-04-25"},
"UnitCost": {"value": "111"},
"ExtendedCost": {"value": "333"}
}
]
 REST API Examples | 169

Create a Transfer Receipt with Allocations for a Transfer Order

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create transfer receipts with allocations in Acumatica ERP in a single API call. For details about the
creation of transfer receipts, see Two-Step Transfers: General Information.
For a detailed description of a user scenario when transfer receipts with allocations can be created, see Sales from
Multiple Warehouses: General Information.

Testing of the Request

Before you test the code below, you do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management, Inventory,
and Multiple Warehouses features are enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

To further prepare the system, you need to create a sales order with items allocated in different warehouses; to
fulfill this sales order, you need to create a transfer order and transfer receipt. You perform these tasks as follows:
1. On the Warehouses (IN204000) form, open the RETAIL warehouse. On the Locations tab, clear the Receiving
Location box. In the warning dialog box that is displayed, click Yes; click Save.
2. On the Sales Orders (SO301000) form, create a sales order with items as follows:
a. Create a sales order of the SO order type for the GOODFOOD customer and MAIN location.
b. On the Details tab of the form, click Add Items on the table toolbar.
c. In the Inventory Lookup dialog box, which opens, select the unlabeled check box in the line containing
the APJAM08 inventory ID and the RETAIL warehouse, and specify 12 in the Qty. Selected column. Click
Add & Close.
d. On the Details tab, click the line the system has added to the table, and click Line Details on the table
toolbar.
e. In the Line Details dialog box, which opens, in the only line, select the check box in the Allocated
column. In the automatically added line, select the check box in the Allocated column, and specify
WHOLESALE in the Alloc. Warehouse column; leave 1 in the Quantity column. Click OK.
f. Save the sales order.
3. On the More menu (under Replenishment), click Create Transfer Order.
4. On the Create Transfer Orders (SO509000) form, which opens, in the table, select the unlabeled check box
for the transfer request that the system just created, and click Process on the form toolbar.
5. On the Sales Orders (SO301000) form, which opens for the created transfer order, click Create Shipment on
the form toolbar. In the Specify Shipment Parameters dialog box, leave the parameter values as they are,
and click OK.
6. On the Shipments (SO302000) form (which opens for the created shipment), on the form toolbar, click
Confirm Shipment and then click Update IN.
 REST API Examples | 170

Request
You can use the following example of an HTTP request to create a transfer receipt with allocations for the transfer
order that was just created. Half of the APJAM08 inventory item (0.5 units) will be moved to the JS1 location, and the
other half of the APJAM08 inventory item will be moved to the JS2 location.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details,Details/Allocations HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"Type": {
"value": "Transfer Receipt"
},
"Warehouse": {
"value": "RETAIL"
},
"Details": [
{
"TransferOrderType": {
"value": "TR"
},
"TransferOrderNbr": {
"value": "000064"
},
"TransferOrderLineNbr": {
"value": "1"
},
"TransferShipmentNbr": {
"value": "000059"
},
"ReceiptQty": {
"value": "1"
},
"Allocations": [
{
"Location": {
"value": "JS1"
},
"Qty": {
"value": 0.5
}
},
{
"Location": {
"value": "JS2"
},
"Qty": {
"value": 0.5
}
 REST API Examples | 171

}
]
}
]
}

Release a Purchase Receipt

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can release a purchase receipt in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to invoke the release process for the purchase receipt through the
contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST /ReleasePurchaseReceipt HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"entity":{ "id": {{id}} }
}

Usage Notes
You can learn the value of the id field for the needed purchase receipt by viewing the POReceipt database table.

SalesInvoice

This chapter presents code examples showing requests that use the SalesInvoice entity.
 REST API Examples | 172

Create a Credit Memo

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a credit memo in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a credit memo through the contract-based REST API. This
credit memo will be created to return all units of the item listed in the 000005 invoice, all units of the item listed in
line 1 of the 000008 invoice, and 50 units of the item listed in line 2 of the 000012 invoice.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesInvoice
Accept: application/json
Content-Type: application/json

{
"CustomerID": { "value": "GOODFOOD" },
"Details": [
{
"OrigInvNbr": { "value": "000005" },
"OrigInvType": { "value": "Invoice" }
},
{
"OrigInvNbr": { "value": "000008" },
"OrigInvType": { "value": "Invoice" },
"OrigInvLineNbr": { "value": 1 }
},
{
"OrigInvNbr": { "value": "000012" },
"OrigInvType": { "value": "Invoice" },
"OrigInvLineNbr": { "value": 2 },
"Qty": { "value": 50 }
}
],
"LocationID": { "value": "MAIN" },
 REST API Examples | 173

"Project": { "value": "X" },

"Type": { "value": "Credit Memo" }
}

SalesOrder

This chapter presents code examples showing requests that use the SalesOrder entity.

Create a Sales Order with the Unit of Measure Specified

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create sales orders and specify the units of measure for the sales order items.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following example of an HTTP request to create a sales order of two small jars of jam. The unit of
measure for the sales order item is PIECE.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details&$select=CustomerID,Details/Branch,Details/InventoryID,
Details/OrderQty,OrderNbr HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CustomerID": { "value": "GOODFOOD" },
"Details": [
{
"Branch": { "value": "HEADOFFICE" },
"InventoryID": { "value": "APJAM08" },
"OrderQty": { "value": 2 },
"UOM": { "value": "PIECE" },
"WarehouseID": { "value": "WHOLESALE" }
}
 REST API Examples | 174

]
}

Create a Sales Order with a Credit Card Payment

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create sales orders with credit card payments in a single API call. For details about the creation of sales
orders, see Reserving Payments for Sales Orders.

A sales order is created with a payment in one transaction. If a payment cannot be created, the sales
order will not be created either.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the SalesDemo dataset. For details on deploying an instance, see
To Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the PRODWHOLE branch.

Request
You can use the following example of an HTTP request to create a sales order with a credit card payment.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CustomerID": {"value": "WIDGETCC"},
"Date": {"value": "2020-05-10T00:00:00"},
"Description": {"value": "Internal CC Payment"},
"Details": [
{
"Branch": {"value": "PRODWHOLE"},
"DiscountAmount": {"value": 10.00},
"ExtendedPrice": {"value": 500.00},
"FreeItem": {"value": false},
"InventoryID": {"value": "AACOMPUT01"},
"OrderQty": {"value": 1.00},
"UnitPrice": {"value": 500.00},
"UOM": {"value": "EA"},
"WarehouseID": {"value": "WHOLESALE"}
 REST API Examples | 175

},
{
"Branch": {"value": "PRODWHOLE"},
"DiscountAmount": {"value": 10.00},
"ExtendedPrice": {"value": 500.00},
"FreeItem": {"value": false},
"InventoryID": {"value": "AALEGO500"},
"OrderQty": {"value": 50.00},
"UnitPrice": {"value": 50.00},
"UOM": {"value": "EA"},
"WarehouseID": {"value": "WHOLESALE"}
}
],
"Hold": {"value": false},
"LocationID": {"value": "MAIN"},
"OrderType": {"value": "SO"},
"Payments": [
{
"ApplicationDate": {"value": "2020-08-11T00:00:00+03:00"},
"AppliedToOrder": {"value": 480.00},
"CashAccount": {"value": "10600"},
"PaymentAmount": {"value": 980.00},
"PaymentMethod": {"value": "VISATOK"},
"PaymentRef": {"value": "ABC CreditCard"}
}
],
"RequestedOn": {"value": "2020-05-10T00:00:00"}
}

Create a Sales Order with a Captured Credit Card Payment

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a sales order with payments in a single API call. For details about the creation of sales orders,
see Reserving Payments for Sales Orders.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the SalesDemo dataset. For details on deploying an instance, see
To Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the PRODWHOLE branch.

Request
You can use the following example of an HTTP request to create in one call a sales order with an internal credit card
payment that will be captured. To capture a payment, you set the Capture parameter of the payment to true. The
operation you create by this call is asynchronous.
 REST API Examples | 176

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CustomerID": {"value": "WIDGETCC"},
"Date": {"value": "2020-05-10T00:00:00"},
"Description": {"value": "Internal CC Payment (Capture)"},
"Details": [
{
"Branch": {"value": "PRODWHOLE"},
"DiscountAmount": {"value": 10.00},
"ExtendedPrice": {"value": 500.00},
"FreeItem": {"value": false},
"InventoryID": {"value": "AACOMPUT01"},
"OrderQty": {"value": 1.00},
"UnitPrice": {"value": 500.00},
"UOM": {"value": "EA"},
"WarehouseID": {"value": "WHOLESALE"}
},
{
"Branch": {"value": "PRODWHOLE"},
"DiscountAmount": {"value": 10.00},
"ExtendedPrice": {"value": 500.00},
"FreeItem": {"value": false},
"InventoryID": {"value": "AALEGO500"},
"OrderQty": {"value": 50.00},
"UnitPrice": {"value": 50.00},
"UOM": {"value": "EA"},
"WarehouseID": {"value": "WHOLESALE"}
}
],
"Hold": {"value": false},
"LocationID": {"value": "MAIN"},
"OrderType": {"value": "SO"},
"Payments": [
{
"ApplicationDate": {"value": "2020-08-11T00:00:00+03:00"},
"AppliedToOrder": {"value": 480.00},
"CashAccount": {"value": "10600"},
"PaymentAmount": {"value": 980.00},
"PaymentMethod": {"value": "VISATOK"},
"PaymentRef": {"value": "ABC CreditCard"},
"Capture": {"value": true}
}
],
"RequestedOn": {"value": "2020-05-10T00:00:00"}
}
 REST API Examples | 177

Create a Sales Order with an Authorized Credit Card Payment

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a sales order with payments in a single API call. For details about the creation of sales orders,
see Reserving Payments for Sales Orders.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the SalesDemo dataset. For details on deploying an instance, see
To Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the PRODHOLE branch.

Request
You can use the following example of an HTTP request to create in one call a sales order with an internal credit card
payment that will be authorized. To authorize a payment, you set the Authorize parameter of the payment to
true. The operation you create by using this call is asynchronous.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CustomerID": {"value": "WIDGETCC"},
"Date": {"value": "2020-05-10T00:00:00"},
"Description": {"value": "Internal CC Payment (Capture)"},
"Details": [
{
"Branch": {"value": "PRODWHOLE"},
"DiscountAmount": {"value": 10.00},
"ExtendedPrice": {"value": 500.00},
"FreeItem": {"value": false},
"InventoryID": {"value": "AACOMPUT01"},
"OrderQty": {"value": 1.00},
"UnitPrice": {"value": 500.00},
"UOM": {"value": "EA"},
"WarehouseID": {"value": "WHOLESALE"}
},
{
"Branch": {"value": "PRODWHOLE"},
"DiscountAmount": {"value": 10.00},
 REST API Examples | 178

"ExtendedPrice": {"value": 500.00},

"FreeItem": {"value": false},
"InventoryID": {"value": "AALEGO500"},
"OrderQty": {"value": 50.00},
"UnitPrice": {"value": 50.00},
"UOM": {"value": "EA"},
"WarehouseID": {"value": "WHOLESALE"}
}
],
"Hold": {"value": false},
"LocationID": {"value": "MAIN"},
"OrderType": {"value": "SO"},
"Payments": [
{
"ApplicationDate": {"value": "2020-08-11T00:00:00+03:00"},
"AppliedToOrder": {"value": 480.00},
"CashAccount": {"value": "10600"},
"PaymentAmount": {"value": 980.00},
"PaymentMethod": {"value": "VISATOK"},
"PaymentRef": {"value": "ABC CreditCard"},
"Capture": {"value": true}
}
],
"RequestedOn": {"value": "2020-05-10T00:00:00"}
}

Create a Sales Order with an External Credit Card Payment

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a sales order with payments in a single API call. For details about the creation of sales orders,
see Reserving Payments for Sales Orders.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the SalesDemo dataset. For details on deploying an instance, see
To Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the PRODHOLE branch.

Request
You can use the following example of an HTTP request to create in one call a sales order with an external credit
card payment. You specify the external credit card payment parameters in the CreditCardTransactionInfo
structure.
 REST API Examples | 179

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CustomerID": {"value": "WIDGETCC"},
"Date": {"value": "2020-05-10T00:00:00"},
"Description": {"value": "External CC payment"},
"Details": [
{
"Branch": {"value": "PRODWHOLE"},
"DiscountAmount": {"value": 10.00},
"ExtendedPrice": {"value": 500.00},
"FreeItem": {"value": false},
"InventoryID": {"value": "AACOMPUT01"},
"OrderQty": {"value": 1.00},
"UnitPrice": {"value": 500.00},
"UOM": {"value": "EA"},
"WarehouseID": {"value": "WHOLESALE"}
},
{
"Branch": {"value": "PRODWHOLE"},
"DiscountAmount": {"value": 10.00},
"ExtendedPrice": {"value": 500.00},
"FreeItem": {"value": false},
"InventoryID": {"value": "AALEGO500"},
"OrderQty": {"value": 50.00},
"UnitPrice": {"value": 50.00},
"UOM": {"value": "EA"},
"WarehouseID": {"value": "WHOLESALE"}
}
],
"Hold": {"value": false},
"LocationID": {"value": "MAIN"},
"OrderType": {"value": "SO"},
"Payments": [
{
"ApplicationDate": {"value": "2020-08-11T00:00:00+03:00"},
"AppliedToOrder": {"value": 480.00},
"CashAccount": {"value": "10600"},
"CreditCardTransactionInfo": [
{
"NeedValidation": {"value": true},
"TranDate": {"value": "2020-08-11T00:00:00+03:00"},
"TranNbr": {"value": "40050474170"},
"TranType": {"value": "AUT"}
}
],
"PaymentAmount": {"value": 980.00},
"PaymentMethod": {"value": "VISATOK"},
"PaymentRef": {"value": "ABC CreditCard"}
 REST API Examples | 180

}
],
"RequestedOn": {"value": "2020-05-10T00:00:00"}
}

Apply Discounts to a Sales Order

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can apply the available discounts to a document (such as a sales order or AR invoice) in a single API call.
For details about the configuration and application of discounts, see Configuring and Applying Customer Discounts.
A user scenario involving the need to apply discounts can be the following: Through an external system, a manager
of the company needs to import sales orders or other documents to Acumatica ERP and apply the available
discounts to them. For details about the preparation of data for the import, creation, and running of import
scenarios, see Preparing Data for Import and Export by Using Scenarios, Configuring Import Scenarios, and Data
Import.

Although discounts can be applied to other types of documents, in this example, sales orders will be
imported.

Testing of the Request

Before you test the code below, you do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management, Inventory,
and Customer Discounts features are enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

To continue preparing the system, you need to create a discount code and a discount based on this discount code,
and then import a sales order to which the discount is applicable and another sales order to which the discount is
not applicable. You perform these tasks as follows:
1. On the Discount Codes (AR209000) form, add a row, and create a discount code of the Line discount type
that is applicable to Customer and Item. In the row, leave the four check boxes cleared for the discount
code. It is especially important that the check box in the Manual column be cleared so that the system will
calculate the discount automatically. Click Save on the form toolbar.
2. On the Discounts (AR209500) form, select the discount code created in the previous instruction; then, in the
Sequence box, type the name and description for a new sequence, and click Save on the form toolbar.
3. Specify the following settings in the Summary area:
• Discount By: Percent
• Break By: Amount
• Active: Selected
• Promotional: Selected
• Effective Date: Today's date
• Expiration Date: Any future date
4. On the Discount Breakpoints tab, add a row to the table, and specify the following settings in the row:
 REST API Examples | 181

• Break Amount: 500

• Discount Percent: 5
5. On the Items tab, add a row to the table, and in the Inventory ID column of the row, select APJAM32.
6. On the Customers tab, add a row to the table, and in the Customer column, select GOODFOOD.
7. On the form toolbar, click Save.
8. Create a CSV file with the following contents.

ORDER NBR;ORDER TYPE;CUSTOMER;LOCATION;BRANCH;INVENTORY ID;QUANTITY

SO0001;SO;GOODFOOD;MAIN;HEADOFFICE;APJAM32;10
SO0002;SO;CANDYY;MAIN;HEADOFFICE;APJAM32;10

9. On the Data Providers (SM206015) form, create a data provider as follows:

a. In the Name box, specify a data provider name.
b. In the Provider Type box, select CSV Provider.
c. Save the data provider.
d. Drag the CSV file that you have created onto the form.
e. On the Parameters tab, set the value of the Delimiter parameter to ;.
f. On the Schema tab, fill the schema of the data provider as follows:
a. On the le pane toolbar, click Fill Schema Objects.
b. In the Active column of the Source Objects table, select the check boxes in every row.
c. On the right pane toolbar, click Fill Schema Fields.
g. On the form toolbar, click Save.
10.On the Import Scenarios (SM206025) form, create an import scenario. In the Summary area, specify the
following settings for it (other settings in the area should remain unchanged):
• Screen Name: Sales Orders (the Screen ID is SO.30.10.00)
• Provider: The data provider you created
• Provider Object: The CSV file used as the source for the data provider
11.Click Save on the form toolbar.
12.For the created import scenario, on the Mapping tab, add rows with the settings shown in the following
table (leaving the Active check box selected in each row).

Target Object Field / Action Name Source Field / Value

Order Summary Key: OrderType =[Document.OrderType]

Order Summary Key: OrderNbr =[Document.OrderNbr]

Order Summary Action: Cancel  

Order Summary Order Nbr. ORDER NBR

Order Summary Action: Cancel  

Order Summary Order Type ORDER TYPE

Order Summary Customer CUSTOMER

Order Summary Location LOCATION

 REST API Examples | 182

Target Object Field / Action Name Source Field / Value

Details <Line Number> =-1

Details Branch BRANCH

Details Inventory ID INVENTORY ID

Details Quantity QUANTITY

Order Summary Action: Save  

13.Click Save on the form toolbar.

14.On the Import by Scenario (SM206036) form, select the import scenario you have created, click Prepare,
make sure that the table on the Prepared Data tab contains the correct data of two sales orders, and click
Import.

Request
You can use the following example of an HTTP request to apply available discounts to both imported sales orders.
To affect both sales orders, you need to call the HTTP request twice, each time specifying the proper order number
as the value of the entity/OrderNbr field.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder/
AutoRecalculateDiscounts
Accept: application/json
Content-Type: application/json

{
"entity" :
{
"OrderType" : {"value" : "SO"},
"OrderNbr" : {"value" : "000065"}
},
"parameters":
{
}
}

Check the imported sales orders. Notice that the discount you created affected the imported sales order whose
OrderNbr is specified in the request, but the discount did not affect the other imported sales order.
 REST API Examples | 183

Create a Return for Credit Without Validation of the Card Refund Against the
Original Transaction

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create refunds of credit card payments without validation against the original transactions.
You can verify whether the original transaction number specified for a refund is related to the payment made. You
can do this in one of the following ways (specified in ascending order of efficiency):
1. On the Processing Centers (CA205000) form, select the Allow Unlinked Refunds check box for the payment
method's default processing center.
2. On the Order Types (SO201000) form, clear the Validate Card Refunds Against Original Transactions check
box for the sales order type that is used to create a refund.
3. In a contract-based REST API request, set the ValidateCCRefundOrigTransaction value of the
SalesOrderPayment entity to false.

Testing of the Request

Before you test the code below, deploy a new Acumatica ERP instance with the SalesDemo dataset. For details on
deploying an instance, see To Deploy an Acumatica ERP Instance in the Installation Guide.

Request
You can use the following example of an HTTP request to make a refund. In this request, you will do the following:
• Set Date to today's date
• Set Hold to false
• In Details, specify the inventory items for which the refund must be made
• Set Payments/Refund to true
• Specify the Payments/OrigTransactionNbr, Payments/CardAccountNbr, and Payments/
CashAccount values from the information of a payment that is not related to the inventory items from
Details
• Set Payments/DocType to Customer Refund
If you run the following example of an HTTP request with Payments/ValidateCCRefundOrigTransaction
set to true, the system will generate an error that indicates that the return for credit to be created has no items that
were paid with the transaction specified as the original.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details,Payments HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CurrencyID": {
"value": "USD"
},
 REST API Examples | 184

"CustomerID": {
"value": "WIDGETCC"
},
"Date": {
"value": "2021-07-29T00:00:00+03:00"
},
"Hold": {
"value": false
},
"Details": [
{
"Branch": {
"value": "PRODWHOLE"
},
"InventoryID": {
"value": "AACOMPUT01"
},
"OrderQty": {
"value": 5.000000
},
"UnitPrice": {
"value": 500.000000
},
"UOM": {
"value": "EA"
},
"WarehouseID": {
"value": "WHOLESALE"
}
}
],
"OrderType": {
"value": "RC"
},
"PaymentMethod": {
"value": "VISATOK"
},
"Payments": [
{
"ApplicationDate": {
"value": "2021-07-29T00:00:00+03:00"
},
"AppliedToOrder": {
"value": 40.0000
},
"CardAccountNbr": {
"value": "2329"
},
"CashAccount": {
"value": "10600"
},
"Currency": {
"value": "USD"
},
"DocType": {
"value": "Customer Refund"
},
 REST API Examples | 185

"Hold": {
"value": false
},
"OrigTransactionNbr": {
"value": "60170494402"
},
"PaymentAmount": {
"value": 40.0000
},
"PaymentMethod": {
"value": "VISATOK"
},
"PaymentRef": {
"value": "601704533664"
},
"ProcessingCenterID": {
"value": "AUTHNETAPI"
},
"Refund": {
"value": true
},
"ValidateCCRefundOrigTransaction": {
"value": true
}
}
]
}

If you change the Payments/ValidateCCRefundOrigTransaction value to false, the request will be

executed successfully.

Create a Shipment from a Sales Order

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a shipment from a sales order in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a shipment from the 000029 sales order (whose ID is 42bb9a17-
a402-e911-b818-00155d408001) through the contract-based REST API.
 REST API Examples | 186

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

POST /SalesOrderCreateShipment HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"entity":{
"id": "42bb9a17-a402-e911-b818-00155d408001"
},
"parameters": {
"ShipmentDate": { "value": "2022-08-20T00:00:00+03:00" },
"WarehouseID": { "value": "WHOLESALE" }
}
}

Usage Notes
You can learn the value of the id field for a sales order by viewing the SOOrder database table.

Create a Return Order for Invoices

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a return order (that is, a return for credit) for any number of invoices in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a return order through the contract-based REST API. This
return order will be created to refuse the INSTALL service included in the 000062 invoice and return 50 units of the
ORANGESproduct included in the 000030 invoice.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details HTTP/1.1

 REST API Examples | 187

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder

Accept: application/json
Content-Type: application/json

{
"CustomerID": { "value": "GOODFOOD" },
"Description": { "value": "Return Order for Invoices" },
"Details": [
{
"InvoiceType": { "value": "Invoice" },
"InvoiceNbr": { "value": "000062" },
"InventoryID": { "value": "INSTALL" }
},
{
"InvoiceType": { "value": "Invoice" },
"InvoiceNbr": { "value": "000030" },
"InventoryID": { "value": "ORANGES" },
"OrderQty": { "value": "50" }
}
],
"LocationID": { "value": "MAIN" },
"OrderType": { "value": "RC" }
}

ServiceOrder

This chapter presents code examples showing requests that use the ServiceOrder entity.

Retrieve a Service Order

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve service orders from Acumatica ERP.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Service Management feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve the service order with the 000019 ID through the contract-
based REST API.
 REST API Examples | 188

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$filter=ServiceOrderNbr%20eq%20'000019' HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ServiceOrder
Accept: application/json
Content-Type: application/json

Shipment

This chapter presents code examples showing requests that use the Shipment entity.

Create a Shipment for Two Sales Orders with Allocations and Package
Specifications

Through the contract-based REST API, external systems can create a shipment with allocations and package
specifications in a single API call.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Also, in this example, a shipment will be created for two sales orders. Before you create the shipment, you need to
create two sales orders. You can do this on the Sales Orders (SO301000) form or Create a Sales Order with the Unit of
Measure Specified. The sales orders must have the following settings.

Element Sales Order 1 Sales Order 2

Order Type SO SO

Customer GOODFOOD GOODFOOD

Branch column (in the only row on HEADOFFICE HEADOFFICE

the Details tab)

Inventory ID column (in the only APJAM08 APJAM32

row on the Details tab)

Quantity column (in the only row 2 1

on the Details tab)
 REST API Examples | 189

Element Sales Order 1 Sales Order 2

UOM column (in the only row on PIECE BOX

the Details tab)

Warehouse column (in the only WHOLESALE WHOLESALE

row on the Details tab)

Request
You can use the following example of an HTTP request to create a shipment for the two sales orders that you
created. For the first sales order (in this example, its ID is 000071; if the sales order you added has a different
number, it should be used in the code), you take one jar of jam from the L2R3S1 location and another jar of jam
from the L3R2S1 location. For the second sales order (in this example, its ID is 000072; if the sales order you added
has a different number, it should be used in the code), you take jars of jam from the L1R3S2 location. Also, you
indicate that all jars of jam of both sales orders should be packed into one large box.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details,Details/Allocations,Packages,Packages/PackageContents HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Shipment
Accept: application/json
Content-Type: application/json

{
"CustomerID": { "value": "GOODFOOD" },
"Details": [
{
"OrderNbr": { "value": "000071" },
"OrderType": { "value": "SO" },
"OrderLineNbr": { "value": 1 },
"Allocations": [
{
"InventoryID": { "value": "APJAM08" },
"LocationID": { "value": "L2R3S1" },
"Qty": { "value": 1 },
"UOM": { "value": "PIECE" }
},
{
"InventoryID": { "value": "APJAM08" },
"LocationID": { "value": "L3R2S1" },
"Qty": { "value": 1 },
"UOM": { "value": "PIECE" }
}
]
},
{
"OrderNbr": { "value": "000072" },
"OrderType": { "value": "SO" },
"OrderLineNbr": { "value": 1 },
"Allocations": [
{
"InventoryID": { "value": "APJAM32" },
 REST API Examples | 190

"LocationID": { "value": "L1R3S2" },

"Qty": { "value": 6 },
"UOM": { "value": "PIECE" }
}
]
}
],
"LocationID": { "value": "MAIN" },
"Operation": { "value": "Issue" },
"Packages": [
{
"BoxID": { "value": "LARGE" },
"UOM": { "value": "KG" },
"Weight": { "value": 15 },
"PackageContents": [
{
"InventoryID": { "value": "APJAM08" },
"LotSerialNbr": { "value": "" },
"Quantity": { "value": 1 },
"UOM": { "value": "PIECE" },
"OrigOrderType": { "value": "SO" },
"OrigOrderNbr": { "value": "000071" }
},
{
"InventoryID": { "value": "APJAM08" },
"LotSerialNbr": { "value": "" },
"Quantity": { "value": 1 },
"UOM": { "value": "PIECE" },
"OrigOrderType": { "value": "SO" },
"OrigOrderNbr": { "value": "000071" }
},
{
"InventoryID": { "value": "APJAM32" },
"LotSerialNbr": { "value": "" },
"Quantity": { "value": 6 },
"UOM": { "value": "PIECE" },
"OrigOrderType": { "value": "SO" },
"OrigOrderNbr": { "value": "000072" }
}
]
}
],
"WarehouseID": { "value": "WHOLESALE" }
}

If you intend to use the Picked field of the Shipment entity, note that its value may be incorrect in
scenarios other than batch picking or wave picking.

Read the Tracking Number from a Shipment

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve a shipment from Acumatica ERP and read its tracking number.
 REST API Examples | 191

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve the 000001 shipment, along with the tracking number of its
package, through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$expand=Packages&$select=Packages/TrackingNbr
&$filter=ShipmentNbr%20eq%20'000001' HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Shipment
Accept: application/json
Content-Type: application/json

Write the Tracking Number to a Shipment

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can set the tracking number of a package of a shipment in Acumatica ERP.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
3. On the Shipments (SO302000) form, for the shipment with the 000058 number, on the Packages tab, add a
package with the SMALL box ID.

Request
You can use the following request example to specify the tracking number of the package with the ec062915-9061-
ec11-9e19-9828a61840c3 ID, which is shipped in the shipment with the 5d79d031-8763-ea11-b82d-00155d408001 ID
through the contract-based REST API.
 REST API Examples | 192

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Packages&$select=Packages/TrackingNbr HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Shipment
Accept: application/json
Content-Type: application/json

{
"id": "5d79d031-8763-ea11-b82d-00155d408001",
"Packages": [
{
"id": "ec062915-9061-ec11-9e19-9828a61840c3",
"TrackingNbr": { "value": "398305336619" }
}
]
}

Usage Notes
You can learn the value of the id field of the shipment in the SOShipment database table, and the value of the id
field of the package in the SOPackageDetail database table.

Update the Freight Cost or Price

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can update the freight cost or freight price of a shipment in Acumatica ERP.

Testing of the Request

Before you test the code below, do the following to configure your client application and the Acumatica ERP
instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
3. On the Details tab of the Ship via Codes (CS207500) form, for the LOCAL ship via code, select the Manual
calculation method, and save your changes.
4. On the Shipping tab of the Shipments (SO302000) form, for the 000058 shipment, specify LOCAL in the Ship
Via box and save your changes.

Request
You can use the following request example to specify the freight cost and freight price of the 000058 shipment
through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.
 REST API Examples | 193

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Shipment
Accept: application/json
Content-Type: application/json

{
"FreightAmount": { "value": 2.0000 },
"FreightCost": { "value": 1.0000 },
"OverrideFreightPrice": { "value": true },
"ShipmentNbr": { "value": "000058" }
}

Usage Notes
In the Default/20.200.001 and Default/22.200.001 endpoints, you use the following fields of the Shipment entity:
• FreightAmount: The freight price
• FreightCost: The freight cost
• OverrideFreightPrice: The field that makes the FreightAmount field either read-only (when its
value is false) or available for editing (when its value is true)

Create Separate Shipments for Each Sales Order

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create separate shipments for multiple sales orders in a single API call.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Also, in this example, two shipments will be created for two sales orders. Before you create shipments, you need to
create two sales orders. You can do this on the Sales Orders (SO301000) form or Create a Sales Order with the Unit of
Measure Specified. The sales orders must have the following settings.

Element Sales Order 1 Sales Order 2

Order Type SO SO

Customer GOODFOOD GOODFOOD

Branch column (in the only row on HEADOFFICE HEADOFFICE

the Details tab)
 REST API Examples | 194

Element Sales Order 1 Sales Order 2

Inventory ID column (in the only APJAM08 APJAM32

row on the Details tab)

Quantity column (in the only row 20 3

on the Details tab)

UOM column (in the only row on PIECE BOX

the Details tab)

Warehouse column (in the only WHOLESALE WHOLESALE

row on the Details tab)

Request
You can use the following example of an HTTP request to create two separate shipments for the two sales orders
that you created. In this example, the number of the first sales order is 000063, and the number of the second sales
order is 000064; if the sales order you added has a different number, it should be used in the code.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Shipment
Accept: application/json
Content-Type: application/json

{
"CustomerID": { "value": "GOODFOOD" },
"Details": [
{
"OrderNbr": { "value": "000063" },
"OrderType": { "value": "SO" }
},
{
"OrderNbr": { "value": "000064" },
"OrderType": { "value": "SO" }
}
],
"LocationID": { "value": "MAIN" },
"Operation": { "value": "Issue" },
"WarehouseID": { "value": "WHOLESALE" },
"CreateNewShipmentForEveryOrder": { "value": true}
}

Usage Notes
You set the CreateNewShipmentForEveryOrder field of the Shipment entity to true to
specify that a separate shipment must be created for every sales order listed in Details. You set the
CreateNewShipmentForEveryOrder field to false to specify that a single shipment must be created for all
sales order listed in Details. The default value is false.
 REST API Examples | 195

StockItem

This chapter presents code examples showing requests that use the StockItem entity.

Retrieve the List of Modified Stock Items

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve the list of stock items that are modified within a particular period from Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
3. On the Stock Items (IN202500) form, open the BLADE12 item, edit the value in the Description box (for
example, change it to Blade Holder V1.2), and save the changes.

Request
You can use the following request example to retrieve the stock item that was changed today through the contract-
based REST API. (Specify today's date instead of 2019-11-14.) The only stock item that the response will contain
will be BLADE12, which you have just changed.
In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem?

$expand=WarehouseDetails&
$select=InventoryID,Description,WarehouseDetails/WarehouseID,
WarehouseDetails/QtyOnHand,ItemClass,BaseUOM&
$filter=LastModified gt datetimeoffset'2019-11-14T00:00:00.000' HTTP/1.1
Host: localhost
Accept: application/json
Content-Type: application/json

Retrieve Stock Items with Attributes

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve stock items along with their attributes from Acumatica ERP.
 REST API Examples | 196

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve the APL-16OZ-GBT stock item, along with its attributes
through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /APL-16OZ-GBT?$expand=Attributes HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json

Retrieve Unit Conversion Rules from a Stock Item

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve unit conversion rules from a stock item in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve unit conversion rules from the PLUMJAM96 stock item
through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET /PLUMJAM96?$expand=UOMConversions HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
 REST API Examples | 197

Accept: application/json
Content-Type: application/json

Retrieve Stock Items with Prices and Quantities by Warehouse

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve stock items with details by using the identifier of the warehouse specified as the default for
the item from Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve stock items whose default warehouse is WHOLESALE, along
with their default prices and quantities, through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$filter=DefaultWarehouseID%20eq%20'WHOLESALE'&$expand=WarehouseDetails
&$select=DefaultPrice,WarehouseDetails/QtyOnHand,
WarehouseDetails/WarehouseID HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/StockItem
Accept: application/json
Content-Type: application/json

TaxCategory

This chapter presents code examples showing requests that use the TaxCategory entity.

Update a Tax Category

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can update tax categories in Acumatica ERP.
 REST API Examples | 198

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to update the TAXABLE tax category through the contract-based REST
API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/TaxCategory
Accept: application/json
Content-Type: application/json

{
"Active": { "value": true },
"Description": { "value": "Taxable Goods and Services v2" },
"ExcludeListedTaxes": { "value": true },
"TaxCategoryID": { "value": "TAXABLE" }
}

TimeEntry

This chapter presents code examples showing requests that use the TimeEntry entity.

Read Employee Time Activities

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can read employee time activities in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
 REST API Examples | 199

2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve all available time activities through the contract-based REST
API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/TimeEntry
Accept: application/json
Content-Type: application/json

Write Employee Time Activities

Through the contract-based REST API, the time spent on the tasks of projects can be imported to Acumatica ERP
from an external system. For more information about tracking time on projects, see Employee Time Billing: General
Information.

Testing of the Request

Before you test the code below, you configure your client application and the Acumatica ERP instance to be used as
follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects Accounting and Time Management
features are enabled.
3. On the Users (SM201010) form, open the bloom user, and add the Administrator role to the user, which
grants it access to the Time Entry (PM209100) form.
4. Sign in as bloom with the 123 password to the instance in the client application by using the tenant name
(which you specified when you created the instance) and the SWEETEQUIP branch.

Request
You can use the following request example to track time through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/TimeEntry
Accept: application/json
Content-Type: application/json
 REST API Examples | 200

{
"Summary" : {"value" : "Time entry summary"},
"Date" : {"value" : "2019-08-17T05:50:43.233" },
"Employee" : {"value" : "EP00000002" },
"ProjectID" : {"value" : "TOMYUM1" },
"ProjectTaskID" : {"value" : "PHASE1" },
"CostCode" : {"value" : "00-000" },
"EarningType" : {"value" : "RG" },
"TimeSpent" : {"value" : "01:30" },
"BillableTime" : {"value" : "00:30" },
}

Usage Notes
The TimeSpent, BillableTime, and BillableOvertime fields of the TimeEntry entity have the
StringValue type. These fields accept values in the following format: hh:mm, where hh is the number of hours,
and mm is the number of minutes.
The TimeEntryID field has the GuidValue type; however, its value is a sequentially generated string that looks
like a GUID. Therefore, the global uniqueness of the values is not guaranteed.

Search for Time Entries by Date

Through the contract-based REST API, the time spent on project tasks can be retrieved from Acumatica ERP to
an external system. For more information about tracking time on projects, see Employee Time Billing: General
Information.

Testing of the Request

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to obtain time entries through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$filter=cf.DateTime(f='Items.Date')%20ge%20datetimeoffset'2019-08-17'
%20and%20cf.DateTime(f='Items.Date')%20le%20
datetimeoffset'2019-08-18T23%3A59%3A59.999%2B04%3A00'&
$select=Date,ProjectID,TimeSpent,BillableTime HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/TimeEntry
Accept: application/json
 REST API Examples | 201

Content-Type: application/json

Usage Notes
To filter time entries by date, you cannot use the TimeEntry.Date field of the Default/22.200.001 system
endpoint. Instead of this field, you should use the custom Items.Date field, as shown in this example.

Vendor

This chapter presents code examples showing requests that use the Vendor entity.

Retrieve the List of Vendors

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can retrieve the list of the vendors that are available in Acumatica ERP.

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to retrieve vendors that meet a condition (the CashAccount field
must be equal to 10200TG) through the contract-based REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

GET ?$filter=CashAccount%20eq%20'10200TG' HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Vendor
Accept: application/json
Content-Type: application/json

Create a Vendor

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a vendor in Acumatica ERP.
 REST API Examples | 202

Testing of the Request

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

Request
You can use the following request example to create a vendor with the TESTVENDOR ID through the contract-based
REST API.

In the request example below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the
URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Vendor
Accept: application/json
Content-Type: application/json

{
"APAccount": { "value": "20000" },
"APSubaccount": { "value": "000000" },
"CashAccount": { "value": "10200WH" },
"CurrencyID": { "value": "USD" },
"CurrencyRateType": { "value": "SPOT" },
"EnableCurrencyOverride": { "value": true },
"EnableRateOverride": { "value": false },
"F1099Vendor": { "value": false },
"ForeignEntity": { "value": false },
"LandedCostVendor": { "value": false },
"LastModifiedDateTime": { "value": "2020-08-11T10:47:41.17-04:00" },
"LocationName": { "value": "Primary Location" },
"MaxReceipt": { "value": 100.000000 },
"MinReceipt": { "value": 0.000000 },
"PaymentBy": { "value": "Due Date" },
"PaymentLeadTimedays": { "value": 0 },
"PaymentMethod": { "value": "CHECK" },
"PaySeparately": { "value": false },
"PrintOrders": { "value": false },
"ReceiptAction": { "value": "Accept but Warn" },
"RemittanceAddressOverride": { "value": false },
"RemittanceContactOverride": { "value": false },
"SendOrdersbyEmail": { "value": false },
"ShippingAddressOverride": { "value": false },
"ShippingContactOverride": { "value": false },
"Status": { "value": "Active" },
"TaxCalculationMode": { "value": "Tax Settings" },
"Terms": { "value": "30D" },
"ThresholdReceipt": { "value": 100.000000 },
 REST API Examples | 203

"VendorClass": { "value": "SUBCON" },

"VendorID": { "value": "TESTVENDOR" },
"VendorIsLaborUnion": { "value": false },
"VendorIsTaxAgency": { "value": false },
"VendorName": { "value": "TESTVENDOR" }
}

Scenarios

This chapter describes various Acumatica ERP contract-based API usage scenarios related to the following areas:
• Inventory and Order Management
• Project Accounting

Inventory and Order Management

You can use the contract-based REST API for the integration of inventory and order management in Acumatica
ERP with external systems. For details on inventory and order management, see Inventory Management and Order
Management.

The following topics present examples of the integration of inventory and order management in Acumatica ERP
with external systems:
• Creation of a Purchase Receipt from a Purchase Order
• Creation of a Shipment with Allocations and Package Specifications
• Creation of a Purchase Receipt with Allocations

Creation of a Purchase Receipt from a Purchase Order

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a purchase order and a purchase receipt (from the purchase order). For details about the
management of purchase documents, see Managing Purchase Documents.

Testing of the Requests

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.
 REST API Examples | 204

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

Step 1: Create a Purchase Order

By using the following code, you create a purchase order and release it from hold at once.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseOrder
Accept: application/json
Content-Type: application/json

{
"VendorID": { "value": "GOODFRUITS" },
"Location": { "value": "MAIN" },
"Details": [
{
"BranchID": { "value": "HEADOFFICE" },
"InventoryID": { "value": "APPLES" },
"OrderQty": { "value": 1 },
"WarehouseID": { "value": "WHOLESALE" },
"UOM": { "value": "LB" }
}
],
"Hold": { "value": false }
}

Step 2: Create a Purchase Receipt from the Purchase Order

You create a purchase receipt from the purchase order that you just created by using the following code.

PUT ?$expand=Details HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"VendorID": { "value": "GOODFRUITS" },
"Location": { "value": "MAIN" },
"Details": [
{
"POOrderNbr": { "value": "000030" },
"POOrderType": { "value": "Normal" }
}
]
}
 REST API Examples | 205

Creation of a Shipment with Allocations and Package Specifications

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a shipment with allocations and package specifications.

Testing of the Requests

Before you test the code below, you need to do the following to configure your client application and the
Acumatica ERP instance to be used:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Inventory and Order Management feature is
enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

Step 1: Create the Sales Orders That Will Be Added to a Shipment

First, you need to create the sales orders that you will add to a shipment. In this example, you will create two sales
orders.
You can use the following example of an HTTP request to create a sales order of two small jars of jam.

PUT ?$expand=Details&$select=CustomerID,Details/Branch,Details/InventoryID,
Details/OrderQty,OrderNbr HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CustomerID": { "value": "GOODFOOD" },
"Details": [
{
"Branch": { "value": "HEADOFFICE" },
"InventoryID": { "value": "APJAM08" },
"OrderQty": { "value": 2 },
"UOM": { "value": "PIECE" },
"WarehouseID": { "value": "WHOLESALE" }
}
]
}

You can also use the following example of an HTTP request to create a sales order of a box containing six bigger jars
of jam.

PUT ?$expand=Details&$select=CustomerID,Details/Branch,Details/InventoryID,
 REST API Examples | 206

Details/OrderQty,OrderNbr HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
"CustomerID": { "value": "GOODFOOD" },
"Details": [
{
"Branch": { "value": "HEADOFFICE" },
"InventoryID": { "value": "APJAM32" },
"OrderQty": { "value": 1 },
"UOM": { "value": "BOX" },
"WarehouseID": { "value": "WHOLESALE" }
}
]
}

Step 2: Create a Shipment for the Two Sales Orders with Allocations and a Package
You can use the following example of an HTTP request to create in one call a shipment for the two created sales
orders. For the first sales order, you take one jar of jam from the L2R3S1 location and another jar of jam from the
L3R2S1 location. Also, you indicate that all jars of jam of both sales orders should be packed into one large box.

If you intend to use the Picked field of the Shipment entity, note that its value may be incorrect in
scenarios other than batch picking or wave picking.

PUT ?$expand=Details,Details/Allocations,Packages,Packages/PackageContents HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Shipment
Accept: application/json
Content-Type: application/json

{
"CustomerID": { "value": "GOODFOOD" },
"Details": [
{
"OrderNbr": { "value": "000071" },
"OrderType": { "value": "SO" },
"OrderLineNbr": { "value": 1 },
"Allocations": [
{
"InventoryID": { "value": "APJAM08" },
"LocationID": { "value": "L2R3S1" },
"Qty": { "value": 1 },
"UOM": { "value": "PIECE" }
},
{
"InventoryID": { "value": "APJAM08" },
"LocationID": { "value": "L3R2S1" },
"Qty": { "value": 1 },
"UOM": { "value": "PIECE" }
}
]
},
{
"OrderNbr": { "value": "000072" },
 REST API Examples | 207

"OrderType": { "value": "SO" },

"OrderLineNbr": { "value": 1 },
"Allocations": [
{
"InventoryID": { "value": "APJAM32" },
"LocationID": { "value": "L1R3S2" },
"Qty": { "value": 6 },
"UOM": { "value": "PIECE" }
}
]
}
],
"LocationID": { "value": "MAIN" },
"Operation": { "value": "Issue" },
"Packages": [
{
"BoxID": { "value": "LARGE" },
"UOM": { "value": "KG" },
"Weight": { "value": 15 },
"PackageContents": [
{
"InventoryID": { "value": "APJAM08" },
"LotSerialNbr": { "value": "" },
"Quantity": { "value": 1 },
"UOM": { "value": "PIECE" },
"OrigOrderType": { "value": "SO" },
"OrigOrderNbr": { "value": "000071" }
},
{
"InventoryID": { "value": "APJAM08" },
"LotSerialNbr": { "value": "" },
"Quantity": { "value": 1 },
"UOM": { "value": "PIECE" },
"OrigOrderType": { "value": "SO" },
"OrigOrderNbr": { "value": "000071" }
},
{
"InventoryID": { "value": "APJAM32" },
"LotSerialNbr": { "value": "" },
"Quantity": { "value": 6 },
"UOM": { "value": "PIECE" },
"OrigOrderType": { "value": "SO" },
"OrigOrderNbr": { "value": "000072" }
}
]
}
],
"WarehouseID": { "value": "WHOLESALE" }
}
 REST API Examples | 208

Creation of a Purchase Receipt with Allocations

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create a purchase receipt with allocations in Acumatica ERP in a single API call. For details about the
creation of purchase receipts, see Purchases for Sale: General Information.

Testing of the Requests

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

Step 1: Create a Purchase Order

You use the following code to create a purchase order and open it.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseOrder
Accept: application/json
Content-Type: application/json

{
"VendorID": { "value": "GLORYFRUIT" },
"Type": { "value": "Normal" },
"Date": { "value": "2018-01-30" },
"Description": { "value": "Purchase of apples, 20 lb" },
"Details": [
{
"Branch": { "value": "HEADOFFICE" },
"InventoryID": { "value": "APPLES" },
"WarehouseID": { "value": "WHOLESALE" },
"OrderQty": { "value": 20 },
"UnitCost": { "value": 9.95 }
}
],
"Hold": { "value": false }
}

Step 2: Create a Purchase Receipt with Allocations

Next, you create a purchase receipt with allocations for the order as follows.
 REST API Examples | 209

PUT ?$expand=Details,Details/Allocations HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/PurchaseReceipt
Accept: application/json
Content-Type: application/json

{
"Type": { "value": "Receipt" },
"VendorID": { "value": "GLORYFRUIT" },
"Details": [
{
"InventoryID": { "value": "APPLES" },
"LotSerialNbr": { "value": "" },
"Warehouse": { "value": "WHOLESALE" },
"Allocations": [
{
"ExpirationDate": { "value": "2021-05-29T00:00:00+03:00" },
"Qty": { "value": 10 },
"LotSerialNbr": { "value": "FRT000862" }
},
{
"ExpirationDate": { "value": "2021-05-29T00:00:00+03:00" },
"Qty": { "value": 10 },
"LotSerialNbr": { "value": "FRT000877" }
}
]
}
]
}

Project Accounting

You can use the contract-based REST API for the integration of Acumatica ERP projects with external systems. For
details on projects and project accounting, see Projects.
The following topics present examples of the integration of Acumatica ERP projects with external systems:
• Creation of a Pro Forma Invoice
• Management of Account Groups

Creation of a Pro Forma Invoice

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create pro forma invoices and send them by email. For details about pro forma invoices, see Pro Forma
Invoice: General Information.

For a pro forma invoice to be created from a project, the project must have Customer, BillingRule,
BillingPeriod, and NextBillingDate specified, and must have the Active status. Because of data
validation in the project, NextBillingDate cannot be specified for a project with the In Planning status, and
you cannot change the customer in a project with the Active status. Therefore, these settings can be specified only
in multiple API calls, as shown in the code examples below.
A ProFormaInvoice entity can be created through the invocation of the RunProjectBilling action of the
Project entity. Because email settings are not mapped to any fields of the Project entity, you have to prepare
 REST API Examples | 210

a project template with the specified email settings on the Project Templates (PM208000) form and then use this
template for the creation of the project through the API. The project template can also contain preconfigured
project tasks, as is the case with the PROGRESS template, which is preconfigured in the U100 dataset and used in
this example. For details about project templates, see Project Templates and Common Tasks: General Information.

Testing of the Requests

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

Step 1: Create a Project

You first need to create a project from the project template and specify the Customer, BillingRule, and
BillingPeriod settings of the project as follows.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

{
"ProjectID" : {"value" : "TESTPR3"},
"ProjectTemplateID" : {"value" : "PROGRESS"},
"Customer" : {"value" : "COFFEESHOP"},
"BillingAndAllocationSettings" :
{
"BillingRule" : {"value" : "PROGRESS"},
"BillingPeriod" : {"value" : "Month"},
}
}

Step 2: Make the Project Active

You make the project active, as shown in the following code.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

{
"ProjectID" : {"value" : "TESTPR3"},
"Hold" : {"value" : false}
 REST API Examples | 211

Step 3: Specify the Next Billing Date for the Project

You specify NextBillingDate for the project, as shown in the following code.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

{
"ProjectID" : {"value" : "TESTPR3"},
"BillingAndAllocationSettings" :
{
"NextBillingDate" : {"value" : "2021-08-15"}
}
}

Step 4: Retrieve a Project Task

You retrieve the project task associated with the created project and the PHASE1 task as follows.

GET ?$filter=ProjectID%20eq%20'TESTPR3'%20and%20ProjectTaskID%20eq%20'PHASE1' HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProjectTask
Accept: application/json
Content-Type: application/json

Step 5: Activate a Project Task

You activate the project task as follows.

POST /Activate HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProjectTask
Accept: application/json
Content-Type: application/json

{
"entity":
{
"id": "35b72591-64ed-eb11-9dee-9828a61840c3"
},
"parameters": {}
}

Step 6: Specify the Progress of the Project Task

You use the following code to specify the progress of the project task.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProjectBudget
Accept: application/json
Content-Type: application/json
 REST API Examples | 212

{
"ProjectTaskID" : {"value" : "PHASE1"},
"ProjectID" : {"value" : "TESTPR3"},
"InventoryID" : {"value" : "<N/A>"},
"Completed" : {"value" : 25},
"PendingInvoiceAmount" : {"value" : 725}
}

Step 7: Invoke Project Billing

You invoke project billing to create a pro forma invoice as follows.

POST /RunProjectBilling HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

{
"entity" : {
"ProjectID": {
"value": "TESTPR3"
}
}
}

HTTP/1.1 202 Accepted

Location: [/<Acumatica ERP instance URL>]/entity/Default/22.200.001/
Project/RunProjectBilling/status/6952c6d1-04be-4330-a26e-c6b855ba332c

Step 8: Monitor the Operation Status

You use the following code to monitor the status of the operation until the system returns the 204 No Content code.

GET /RunProjectBilling/status/6952c6d1-04be-4330-a26e-c6b855ba332c HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

HTTP/1.1 204 No Content

Step 9: Retrieve the List of Pro Forma Invoices

You obtain the list of pro forma invoices of the project (which currently contains only one pro forma invoice) by
adding $expand=Invoices to the endpoint address, as shown in the following code. For details about parameters,
see $expand Parameter.

GET /TESTPR3?$expand=Invoices HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Project
Accept: application/json
Content-Type: application/json

Step 10: Send the Pro Forma Invoice by Email

You use the following code to send the pro forma invoice by email.
 REST API Examples | 213

POST /EmailProFormaInvoice HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProFormaInvoice
Accept: application/json
Content-Type: application/json

{
"entity" : {
"RefNbr": {
"value": "000019"
}
}
}

HTTP/1.1 202 Accepted

Location: [/<Acumatica ERP instance URL>]/entity/Default/22.200.001/
ProFormaInvoice/EmailProFormaInvoice/status/a4caa455-0eed-4c11-a5a9-2a8333e53db1

Step 11: Monitor the Sending Operation Status

You use the following code to monitor the status of the operation.

GET /EmailProFormaInvoice/status/a4caa455-0eed-4c11-a5a9-2a8333e53db1 HTTP/1.1

Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/ProFormaInvoice
Accept: application/json
Content-Type: application/json

HTTP/1.1 204 No Content

Management of Account Groups

If you are using the contract-based REST API to integrate Acumatica ERP with external systems, these external
systems can create, modify, and remove account groups. For more information about account groups, see Account
Groups: General Information.

The AccountGroup entity supports the creation, retrieval, update, and removal of the entity itself; however, you
cannot modify the list of accounts of a particular account group by using the AccountGroup entity. Instead, you
have to use the AccountGroup property in the Account entity. You can use the DefaultAccountID property
of the AccountGroup entity to specify the default account for the group.

The removal of the default account from the group does not cause the DefaultAccountID
property to be updated automatically. If you remove the default account from the group, you have to
update the DefaultAccountID property.

Testing of the Requests

Before you test the code below, you need to configure your client application and the Acumatica ERP instance to be
used as follows:
1. Deploy a new Acumatica ERP instance with the U100 dataset. For details on deploying an instance, see To
Deploy an Acumatica ERP Instance in the Installation Guide.
2. On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
 REST API Examples | 214

3. To sign in to the instance in the client application, use the tenant name (which you specified when you
created the instance) and the HEADOFFICE branch.

In the request examples below, <Acumatica ERP instance URL> is the URL of the Acumatica
ERP instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of
the website.

Step 1: Create an Account Group

You start by creating an account group with the ACCG02 identifier, as shown in the following code.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/AccountGroup
Accept: application/json
Content-Type: application/json

{
"AccountGroupID" : {"value" : "ACCG02"},
"Description" : {"value" : "Test Account Group"}
}

Step 2: Add Accounts to the Account Group

Now you need to add accounts to the account group. You add the 40000 account to the ACCG02 account group as
follows.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Account
Accept: application/json
Content-Type: application/json

{
"AccountCD" : {"value" : "40000"},
"AccountGroup" : {"value" : "ACCG02"}
}

Next, you add the 40010 account to the ACCG02 account group, as shown in the following code.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Account
Accept: application/json
Content-Type: application/json

{
"AccountCD" : {"value" : "40010"},
"AccountGroup" : {"value" : "ACCG02"}
}

Step 3: Specify the Default Account of the Account Group

You need to specify the 40000 account as the default account of the ACCG02 account group, as shown in the
following code example.
 REST API Examples | 215

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/AccountGroup
Accept: application/json
Content-Type: application/json

{
"DefaultAccountID" : {"value" : "40000"},
"AccountGroupID" : {"value" : "ACCG02"}
}

Step 4: Retrieve the List of Accounts of the Account Group

You need to obtain the list of accounts of the ACCG02 account group as follows.

GET / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Account?
$filter=AccountGroup%20eq%20'ACCG02'&$select=AccountCD
Accept: application/json
Content-Type: application/json

Step 5: Remove an Account from the Group

Finally, you remove the 40010 account from the ACCG02 account group, as shown in the following code.

PUT / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/22.200.001/Account
Accept: application/json
Content-Type: application/json

{
"AccountCD" : {"value" : "40010"},
"AccountGroup" : {"value" : null}
}

Related Links
• Account Groups: General Information
 Authorizing Client Applications to Work with Acumatica ERP | 216

Authorizing Client Applications to Work with Acumatica

ERP
Acumatica ERP supports the OAuth 2.0 mechanism of authorization for applications that are integrated with
Acumatica ERP through an application programming interface (API) or OData interface. When a client application
of Acumatica ERP uses the OAuth 2.0 mechanism of authorization, the client application does not operate with
the Acumatica ERP credentials to sign in a user to Acumatica ERP; instead, the application obtains an access token
from Acumatica ERP and uses this token when it requests data from Acumatica ERP.
Depending on the OAuth 2.0 flow that the client application implements, the client application either has no
information on the credentials of an Acumatica ERP user or uses this information only once to obtain the access
token. The OAuth 2.0 mechanism of authorization improves the security of the Acumatica ERP data accessed by the
application and simplifies the management of access rights.
The client application that implements the OAuth 2.0 or OpenID Connect (OIDC) authorization mechanism can use
one of the authorization flows supported by Acumatica ERP, which are the following:
• Authorization code (OAuth 2.0 and OIDC)
• Implicit (OAuth 2.0 and OIDC)
• Resource owner password credentials (OAuth 2.0)
• Hybrid (OIDC)
In this chapter, you can find details on the authorization flows and information about how to register the OAuth 2.0
or OIDC client applications and revoke access of the applications.

Authorization Code Flow

When you implement OAuth 2.0 or OIDC authorization in a client application to make the application work with
Acumatica ERP, you can use the authorization code flow. With this authorization flow, the client application never
gets the credentials of the applicable Acumatica ERP user. Aer the user is authenticated in Acumatica ERP, the
client application receives an authorization code, exchanges it for an access token, and then uses the access token
to work with data in Acumatica ERP. When the access token expires, the client application can request a new access
token by providing a refresh token.
The following diagram illustrates the authorization code flow, whose steps are described in the sections of this
topic.
 Authorizing Client Applications to Work with Acumatica ERP | 217

Figure: Authorization code flow

For details on the OAuth 2.0 authorization mechanism, see the specification at https://tools.ietf.org/html/rfc6749.
For details on the OIDC authorization mechanism, see the specification at https://openid.net/specs/openid-connect-
core-1_0.html#Authentication.

Granting Permission to a Client Application

Before an OAuth 2.0 or OIDC client application can work with Acumatica ERP, you must register this application in
Acumatica ERP and provide credentials to the application, as described in To Register a Client Application with the
Authorization Code Flow. Aer the registration, you have the client ID and the secret value of the client application.
 Authorizing Client Applications to Work with Acumatica ERP | 218

• According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client
application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is
required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the
OAuth 2.0 client application can work with data in Acumatica ERP. For more information, see
Setting Up an HTTPS Service in Web Server (IIS).
• When you are registering the client application, you have to be logged in to the tenant whose
data the client application needs to access.

Connecting to the Authorization Endpoint

The client application connects to the authorization endpoint of Acumatica ERP with the GET method by specifying
the following URL with parameters:
• URL
The client application can use one of the following options:
• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the authorization endpoint address, which is https://
<Acumatica ERP instance URL>/identity/connect/authorize. In this address,
<Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client
application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the authorization endpoint
address is https://localhost/AcumaticaDB/identity/connect/authorize.
• URL Parameters
The client application should specify the following URL parameters.

Parameter Description

response_type The type of the flow, which must be set to code for the authorization code flow.

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

redirect_uri The URI in the client application to which the response to the request should be
sent. The URI must exactly match one of the values specified for the application in
the Redirect URI column on the Redirect URIs tab of the Connected Applications
(SM303010) form.

scope The access scope that is requested by the client application. The scope can be a
combination of the following values, delimited by spaces:
 Authorizing Client Applications to Work with Acumatica ERP | 219

Parameter Description
• openid: If this scope is granted, the OpenID Connect protocol is used. Without
this scope, the OAuth 2.0 protocol is used.
• api: Requests access to a web services API or OData interface. If a user grants
this scope to the application, the client application can work with the following
types of the web services API: contract-based SOAP API, screen-based SOAP API,
or contract-based REST API.

For the contract-based API request, you must specify api for the
scope parameter.

If this scope is granted and the api:concurrent_access scope is not grant-

ed, Acumatica ERP manages the sessions of the application through tokens.
Acumatica ERP issues the first access token along with the session ID. If the client
application requests a new access token by presenting a refresh token, Acumati-
ca ERP reuses the session ID that was issued for the first access token issued with
the refresh token. That is, the system uses a single session for each access grant-
ed to the client application. For details about the license limitations related to
the number of sessions for client applications, see License Restrictions for API
Users.
• offline_access: Requests that a refresh token be granted. If a user grants
this scope to the application, Acumatica ERP issues to the client application a
refresh token along with the access token. (For information on issuing the ac-
cess token, see Connecting to the Token Endpoint in this topic.) When the ac-
cess token has expired, the client application can request a new access token by
sending a request to the token endpoint and providing the refresh token. The
whole chain for the refresh token expires 30 days after the initial authentication
process.
• api:concurrent_access: Requests permission for the concurrent use of
multiple types of web service APIs. If a user grants this scope to the application,
the client application can access data in Acumatica ERP in concurrent mode. In
this case, Acumatica ERP can maintain multiple sessions for the client applica-
tion, managing session IDs through cookies. We recommend that the client appli-
cation request this scope only if concurrent access is required for the client appli-
cation. For details about the license limitations related to the number of sessions
for client applications, see License Restrictions for API Users.

An example of a URL with parameters is shown below. (Line breaks are for display purposes only.)

https://localhost/AcumaticaDB/identity/connect/authorize?
response_type=code
&client_id=4B1DFD71-C5EE-0B21-A6BE-9A1F060A93BD
&redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Flocalhost%2Fclientapp%2F
&scope=api%20offline_access

Authorizing a User in Acumatica ERP and Granting Access

The authorization endpoint directs the user of the client application to the login page of Acumatica ERP, where the
user should enter the credentials to log in to a company configured in the Acumatica ERP instance.

The user must log in to the company that was specified in the client_id URL parameter passed to
the authorization endpoint. (This company is selected by default on the login page.)
 Authorizing Client Applications to Work with Acumatica ERP | 220

If the credentials are accepted by Acumatica ERP, the system displays the consent form, where the user can confirm
that the application has access to the requested scopes. Only the scopes that were requested by the application are
displayed on the consent form.

Receiving the Authorization Code

Once the user grants access to the requested scopes, Acumatica ERP redirects the client application to the
redirect_uri address that was specified in the request, and adds the authorization code in the code URL
parameter.

Connecting to the Token Endpoint

The client application connects to the token endpoint of Acumatica ERP with the POST method by specifying the
following URL, HTTP header, and the following parameters in the request body:
• URL
The client application can use one of the following options:
• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the token endpoint address, which is https://<Acumatica
ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP
instance URL> is the URL of the Acumatica ERP instance to which the client application is going to
connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint
address is https://localhost/AcumaticaDB/identity/connect/token.
• HTTP header
You use the following HTTP header.

Key Value

Content-Type application/x-www-form-urlencoded

• Parameters in the Request Body

You specify the following parameters in the request body.

Parameter Description

grant_type The type of the OAuth 2.0 flow, which must be set to authorization_code for
the authorization code flow.
 Authorizing Client Applications to Work with Acumatica ERP | 221

Parameter Description

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

code The authorization code that the client application has received from the authoriza-
tion endpoint.

client_secret The value of the secret that was created for the client application during the regis-
tration of the application in Acumatica ERP.

redirect_uri The URI in the client application to which the response to the request should be
sent. The URI must exactly match one of the values specified for the application in
the Redirect URI column on the Redirect URIs tab of the Connected Applications
(SM303010) form.

Receiving the Access Token

Acumatica ERP verifies the provided application credentials and issues the access token, which the client
application should provide with each data request to Acumatica ERP. During authentication in Acumatica ERP,
if the user has granted to the client application the offline_access scope, Acumatica ERP issues the refresh
token along with the access token. A successful response includes the following parameters in the response body.

Parameter Description

token_type The type of the access token, which is Bearer.

access_token The access token.

expires_in The period of time during which the access token is valid.

refresh_token The refresh token. The parameter is returned only if the offline_access scope was
granted.

Requesting Data with the Access Token

The client application should include the access token in the Authorization header of each subsequent
request to Acumatica ERP, as shown in the following HTTP example.

GET /AcumaticaDB/entity/Default/18.200.001/SalesOrder/SO/000001 HTTP/1.1

Host: localhost
Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc

Refreshing the Access Token

The access token is valid for a specific period of time, which is specified in the response that returns the access
token. When the access token expires, the client application can request a new access token by providing the
 Authorizing Client Applications to Work with Acumatica ERP | 222

refresh token to the token endpoint. To request a new access token, the client application should use the POST
method and have the following URL and the following parameters specified in the request body:
• URL
The client application can use one of the following options:
• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the token endpoint address, which is https://<Acumatica
ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP
instance URL> is the URL of the Acumatica ERP instance to which the client application is going to
connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint
address is https://localhost/AcumaticaDB/identity/connect/token.
• Parameters in the Request Body
You specify the following parameters in the request body.

Parameter Description

grant_type The type of the request, which must be set to refresh_token for the request of
the refresh token.

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

client_secret The value of the secret that was created for the client application during the regis-
tration of the application in Acumatica ERP.

refresh_token The refresh token that the client application received from the token endpoint
along with the access token if the user granted the offline_access scope to
the client application.

Receiving the New Access Token

Acumatica ERP verifies the provided application credentials and issues the new access token and the new refresh
token. To request the access token once again, the client application should use the refresh token issued with the
previous access token. A successful response includes the following parameters in the response body.
 Authorizing Client Applications to Work with Acumatica ERP | 223

Parameter Description

token_type The type of the access token, which is Bearer.

access_token The access token.

expires_in The period of time during which the access token is valid.

refresh_token The refresh token.

Logging Out from Acumatica ERP

To prevent issues with licenses that limit the number of concurrent user sessions, the client application should
directly call the logout method of the Acumatica ERP web services API when the application finishes its work with
Acumatica ERP. The client application does this by using the POST method, the ASP.NET_SessionId cookie
with the value that corresponds to the session, and the following URL.

https://<Acumatica ERP instance URL>/entity/auth/logout

In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
Related Links
• RFC 6749: The OAuth 2.0 Authorization Framework

Implicit Flow

When you implement OAuth 2.0 or OIDC authorization in a client application to make the application work with
Acumatica ERP, you can use the implicit flow, which is a simplified variant of the authorization code flow.
With the implicit flow, the client application never gets the credentials of the applicable Acumatica ERP user. When
the user is authenticated in Acumatica ERP, the client application does not receive an authorization code (as with
the authorization code flow); instead, the client application directly receives an access token, and then uses the
access token to work with data in Acumatica ERP. The access token is valid for a limited period of time and cannot
be renewed.
The following diagram illustrates the implicit flow, whose steps are described in the sections later in this topic.
 Authorizing Client Applications to Work with Acumatica ERP | 224

Figure: Implicit flow

This flow can be used for clients using a scripting language (such as JavaScript) or for mobile clients. For
details on the OAuth 2.0 authorization mechanism, see the specification at https://tools.ietf.org/html/rfc6749. For
details on the OIDC authorization mechanism, see the specification at https://openid.net/specs/openid-connect-
core-1_0.html#Authentication.

Granting Permission to a Client Application

Before an OAuth 2.0 or OIDC client application can work with Acumatica ERP, you must register this application in
Acumatica ERP and provide credentials to the application, as described in To Register a Client Application with the
Implicit Flow. Aer the registration, you have the client ID of the client application.

• According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client
application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is
required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the
OAuth 2.0 client application can work with data in Acumatica ERP. For more information, see
Setting Up an HTTPS Service in Web Server (IIS).
• When you are registering the client application, you have to be logged in to the tenant whose
data the client application needs to access.

Connecting to the Authorization Endpoint

The client application connects to the authorization endpoint of Acumatica ERP with the GET method by specifying
the following URL and parameters:
• URL
The client application can use one of the following options:
 Authorizing Client Applications to Work with Acumatica ERP | 225

• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the authorization endpoint address, which is https://
<Acumatica ERP instance URL>/identity/connect/authorize. In this address,
<Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client
application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the authorization endpoint
address is https://localhost/AcumaticaDB/identity/connect/authorize.
• URL Parameters
The client application should specify the following URL parameters.

Parameter Description

response_type The type of the flow. For OAuth 2.0, it must be set to token. For OIDC, it must be set
either to id_token or id_token token.

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

redirect_uri The URI in the client application to which the response to the request should be
sent. The URI must exactly match one of the values specified for the application in
the Redirect URI column on the Redirect URIs tab of the Connected Applications
(SM303010) form.

scope The access scope that is requested by the client application. The scope can be a
combination of the following values, delimited by spaces:
• openid: If this scope is granted, the OpenID Connect protocol is used. Without
this scope, the OAuth 2.0 protocol is used.
• api: Requests access to a web services API or OData interface. If a user grants
this scope to the application, the client application can work with the following
types of the web services API: contract-based SOAP API, screen-based SOAP API,
or contract-based REST API.

For the contract-based API request, you must specify api for the
scope parameter.

If this scope is granted and the api:concurrent_access scope is not grant-

ed, Acumatica ERP manages the sessions of the application through tokens. The
system uses a single session for each access granted to the client application.
• api:concurrent_access: Requests permission for the concurrent use of
multiple types of web service APIs. If a user grants this scope to the application,
 Authorizing Client Applications to Work with Acumatica ERP | 226

Parameter Description
the client application can access data in Acumatica ERP in concurrent mode. In
this case, Acumatica ERP can maintain multiple sessions for the client applica-
tion, managing session IDs through cookies. We recommend that the client appli-
cation request this scope only if concurrent access is required for the client appli-
cation. For details about the license limitations related to the number of sessions
for client applications, see License Restrictions for API Users.

The offline_access scope is not supported by the implicit flow.

An example of the HTTP request is shown below. (Line breaks are for display purposes only.)

http://localhost/AcumaticaDB/identity/connect/authorize?
response_type=token
&client_id=4B1DFD71-C5EE-0B21-A6BE-9A1F060A93BD
&redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Flocalhost%2Fclientapp%2F
&scope=api

Authorizing a User in Acumatica ERP and Granting Access

The authorization endpoint directs the user of the client application to the login page of Acumatica ERP, where the
user should enter the credentials to log in to a company configured in the Acumatica ERP instance.

The user must log in to the company that was specified in the client_id URL parameter passed to
the authorization endpoint. (This company is selected by default on the login page.)

If the credentials are accepted by Acumatica ERP, the system displays the consent form, where the user can confirm
that the application has access to the requested scopes. Only the scopes that were requested by the application are
displayed on the consent form.

Obtaining the Access Token

Once the user grants access to the requested scopes, Acumatica ERP redirects the client application to the
redirect_uri address, which was specified in the request, and adds the access token in the URL parameters.
The redirect URL includes the following URL parameters.

Parameter Description

token_type The type of the access token, which is Bearer.

access_token The access token.

expires_in The period of time during which the access token is valid.

Refresh tokens are not supported by the implicit flow.

 Authorizing Client Applications to Work with Acumatica ERP | 227

Requesting Data with the Access Token

The client application should include the access token in the Authorization header of each subsequent
request to Acumatica ERP, as shown in the following HTTP example.

GET /AcumaticaDB/entity/Default/18.200.001/SalesOrder/SO/000001 HTTP/1.1

Host: localhost
Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc

Logging Out from Acumatica ERP

To prevent issues with licenses that limit the number of concurrent user sessions, the client application should
directly call the logout method of the Acumatica ERP web services API when the application finishes its work with
Acumatica ERP. The client application does this by using the POST method, the ASP.NET_SessionId cookie
with the value that corresponds to the session, and the following URL.

https://<Acumatica ERP instance URL>/entity/auth/logout

In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
Related Links
• RFC 6749: The OAuth 2.0 Authorization Framework

Resource Owner Password Credentials Flow

When you implement OAuth 2.0 authorization in a client application to make the application work with Acumatica
ERP, you can use the resource owner password credentials flow.
With the resource owner password credentials flow, the credentials (username and password) of the Acumatica
ERP user are provided directly to the client application, which uses the credentials to obtain the access token.
When the access token expires, the client application can request a new access token by providing a refresh token.
The following diagram illustrates the resource owner password credentials flow, whose steps are described in the
sections later in this topic.
 Authorizing Client Applications to Work with Acumatica ERP | 228

Figure: Resource owner password credentials flow

For details on the OAuth 2.0 authorization mechanism, see the specification at https://tools.ietf.org/html/rfc6749.

Granting Permission to a Client Application

Before an OAuth 2.0 client application can work with Acumatica ERP, you must register this application in
Acumatica ERP and provide credentials to the application, as described in To Register a Client Application with
the Resource Owner Password Flow. Aer the registration, you have the client ID and secret value of the client
application.

• According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client
application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is
required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the
OAuth 2.0 client application can work with data in Acumatica ERP. For more information, see
Setting Up an HTTPS Service in Web Server (IIS).
• When you are registering the client application, you have to be logged in to the tenant whose
data the client application needs to access.

Obtaining the Credentials of the Acumatica ERP User

The client application should obtain the username and password of the applicable Acumatica ERP user, which can
then be exchanged for an access token.

Connecting to the Token Endpoint

The client application connects to the token endpoint of Acumatica ERP with the POST method by specifying the
following URL, HTTP header, and the following parameters in the request body:
 Authorizing Client Applications to Work with Acumatica ERP | 229

• URL
The client application can use one of the following options:
• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the token endpoint address, which is https://<Acumatica
ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP
instance URL> is the URL of the Acumatica ERP instance to which the client application is going to
connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint
address is https://localhost/AcumaticaDB/identity/connect/token.
• HTTP header
You use the following HTTP header.

Key Value

Content-Type application/x-www-form-urlencoded

• Parameters in the Request Body

You specify the following parameters in the request body.

Parameter Description

grant_type The type of the OAuth 2.0 flow, which must be set to password for the resource
owner password credentials flow.

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

client_secret The value of the secret that was created for the client application during the regis-
tration of the application in Acumatica ERP.

username The username of an Acumatica ERP user.

password The password for the specified username.

scope The access scope that is requested by the client application. The scope can be a
combination of the following values, delimited by spaces:
• api: Requests access to a web services API or OData interface. If a user grants
this scope to the application, the client application can work with the following
 Authorizing Client Applications to Work with Acumatica ERP | 230

Parameter Description
types of the web services API: contract-based SOAP API, screen-based SOAP API,
or contract-based REST API.

For the contract-based API request, you must specify api for the
scope parameter.

If this scope is granted and the api:concurrent_access scope is not grant-

ed, Acumatica ERP manages the sessions of the application through tokens.
Acumatica ERP issues the first access token along with the session ID. If the client
application requests a new access token by presenting a refresh token, Acumati-
ca ERP reuses the session ID that was issued for the first access token issued with
the refresh token. That is, the system uses a single session for each access grant-
ed to the client application. For details about the license limitations related to
the number of sessions for client applications, see License Restrictions for API
Users.
• offline_access: Requests that a refresh token be granted. If a user grants
this scope to the application, Acumatica ERP issues to the client application a
refresh token along with the access token. (For information on issuing the ac-
cess token, see Connecting to the Token Endpoint in this topic.) When the ac-
cess token has expired, the client application can request a new access token by
sending a request to the token endpoint and providing the refresh token. The
whole chain for the refresh token expires 30 days after the initial authentication
process.
• api:concurrent_access: Requests permission for the concurrent use of
multiple types of web service APIs. If a user grants this scope to the application,
the client application can access data in Acumatica ERP in concurrent mode. In
this case, Acumatica ERP can maintain multiple sessions for the client applica-
tion, managing session IDs through cookies. We recommend that the client appli-
cation request this scope only if concurrent access is required for the client appli-
cation. For details about the license limitations related to the number of sessions
for client applications, see License Restrictions for API Users.

An example of a request is shown below. (Line breaks are for display purposes only.)

POST / HTTP/1.1
Host: [<Acumatica ERP instance URL>]/identity/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&
client_id=8E0761D9-F4EC-2D4B-A60F-BCE2708C6FDD%40CompanyB&
client_secret=O19LLT5Z0SzFbCIKLXLqQQ&username=admin&
password=123&scope=api+offline_access

Receiving the Access Token

Acumatica ERP verifies the provided application credentials and issues the access token, which the client
application should provide with each data request to Acumatica ERP. During authentication in Acumatica ERP,
if the user has granted to the client application the offline_access scope, Acumatica ERP issues the refresh
token along with the access token. A successful response includes the following parameters in the response body.
 Authorizing Client Applications to Work with Acumatica ERP | 231

Parameter Description

token_type The type of the access token, which is Bearer.

access_token The access token.

expires_in The period of time during which the access token is valid.

refresh_token The refresh token. The parameter is returned only if the offline_access scope was
granted.

Requesting Data with the Access Token

The client application should include the access token in the Authorization header of each subsequent
request to Acumatica ERP, as shown in the following HTTP example.

GET /AcumaticaDB/entity/Default/18.200.001/SalesOrder/SO/000001 HTTP/1.1

Host: localhost
Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc

Refreshing the Access Token

The access token is valid for a specific period of time, which is specified in the response that returns the access
token. When the access token expires, the client application can request a new access token by providing the
refresh token to the token endpoint. To request a new access token, the client application should use the POST
method and have the following URL and the following parameters specified in the request body:
• URL
The client application can use one of the following options:
• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the token endpoint address, which is https://<Acumatica
ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP
instance URL> is the URL of the Acumatica ERP instance to which the client application is going to
connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint
address is https://localhost/AcumaticaDB/identity/connect/token.
• Parameters in the Request Body
You specify the following parameters in the request body.
 Authorizing Client Applications to Work with Acumatica ERP | 232

Parameter Description

grant_type The type of the request, which must be set to refresh_token for the request of
the refresh token.

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

client_secret The value of the secret that was created for the client application during the regis-
tration of the application in Acumatica ERP.

refresh_token The refresh token that the client application received from the token endpoint
along with the access token if the user granted the offline_access scope to
the client application.

Receiving the New Access Token

Acumatica ERP verifies the provided application credentials and issues the new access token and the new refresh
token. To request the access token once again, the client application should use the refresh token issued with the
previous access token. A successful response includes the following parameters in the response body.

Parameter Description

token_type The type of the access token, which is Bearer.

access_token The access token.

expires_in The period of time during which the access token is valid.

refresh_token The refresh token.

Logging Out from Acumatica ERP

To prevent issues with licenses that limit the number of concurrent user sessions, the client application should
directly call the logout method of the Acumatica ERP web services API when the application finishes its work with
Acumatica ERP. The client application does this by using the POST method, the ASP.NET_SessionId cookie
with the value that corresponds to the session, and the following URL.

https://<Acumatica ERP instance URL>/entity/auth/logout

In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
Related Links
• RFC 6749: The OAuth 2.0 Authorization Framework
 Authorizing Client Applications to Work with Acumatica ERP | 233

Hybrid Flow

Client applications that can securely store client secrets may benefit from the use of the hybrid flow (defined in
section 3.3 of the OIDC spec). The hybrid flow allows an application to have immediate access to an ID token while
providing secure retrieval of access and refresh tokens. This can be useful in situations where the application needs
to immediately access information about the user, but must perform some processing before gaining access to
protected resources for a long period.
When you implement OIDC authorization in a client application to make the application work with Acumatica
ERP, you can use the hybrid flow. This authorization flow is a combination of the authorization code flow and the
implicit flow. As with the authorization flow, with the hybrid flow, the client application requests the authorization
code (and possibly other parameters) at the authorization endpoint. As with the implicit flow, with the hybrid
flow, the client application requests the ID token or access token (or both) at the token endpoint. If the ID token
is retrieved, the client application validates it by using the key that is generated on the OpenID Connection
Preferences (SM303030) form.

Granting Permission to a Client Application

Before an OIDC client application can work with Acumatica ERP, you must register this application in Acumatica
ERP and provide credentials to the application, as described in To Register a Client Application with the Hybrid Flow.
Aer the registration, you have the client ID and the secret value of the client application.

• According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client
application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is
required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the
OAuth 2.0 client application can work with data in Acumatica ERP. For more information, see
Setting Up an HTTPS Service in Web Server (IIS).
• When you are registering the client application, you have to be logged in to the tenant whose
data the client application needs to access.

Connecting to the Authorization Endpoint

The client application connects to the authorization endpoint of Acumatica ERP with the GET method by specifying
the following URL with parameters:
• URL
The client application can use one of the following options:
• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the authorization endpoint address, which is https://
<Acumatica ERP instance URL>/identity/connect/authorize. In this address,
<Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the client
application is going to connect.
 Authorizing Client Applications to Work with Acumatica ERP | 234

For example, for a local Acumatica ERP instance with the name AcumaticaDB, the authorization endpoint
address is https://localhost/AcumaticaDB/identity/connect/authorize.
• URL Parameters
The client application should specify the following URL parameters.

Parameter Description

response_type The type of the response, which can be one of the following:
• code id_token
• code token
• code id_token token

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

redirect_uri The URI in the client application to which the response to the request should be
sent. The URI must exactly match one of the values specified for the application in
the Redirect URI column on the Redirect URIs tab of the Connected Applications
(SM303010) form.

response_mode The type of the response, which can be either form_post or fragment.

scope The access scope that is requested by the client application. The scope can be a
combination of the following values, delimited by spaces:
• openid: If this scope is mandatory for the hybrid flow.
• email: Requests disclosure of user email address.
• profile: Requests disclosure of user profile information.
• address: Requests disclosure of user address.
• phone: Requests disclosure of user phone number.
• offline_access: Requests that a refresh token be granted. If a user grants
this scope to the application, Acumatica ERP issues to the client application a
refresh token along with the access token. (For information on issuing the ac-
cess token, see Connecting to the Token Endpoint in this topic.) When the ac-
cess token has expired, the client application can request a new access token by
sending a request to the token endpoint and providing the refresh token. The
whole chain for the refresh token expires 30 days after the initial authentication
process.

An example of a URL with parameters is shown below. (Line breaks are for display purposes only.)

https://localhost/AcumaticaDB/identity/connect/authorize?
response_type=code@20id_token
&client_id=4B1DFD71-C5EE-0B21-A6BE-9A1F060A93BD
&redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Flocalhost%2Fclientapp%2F
&scope=openid@20profile%20offline_access
 Authorizing Client Applications to Work with Acumatica ERP | 235

Authorizing a User in Acumatica ERP and Granting Access

The authorization endpoint directs the user of the client application to the login page of Acumatica ERP, where the
user should enter the credentials to log in to a company configured in the Acumatica ERP instance.

The user must log in to the company that was specified in the client_id URL parameter passed to
the authorization endpoint. (This company is selected by default on the login page.)

If the credentials are accepted by Acumatica ERP, the system displays the consent form, where the user can confirm
that the application has access to the requested scopes. Only the scopes that were requested by the application are
displayed on the consent form.

Authentication Response
If the user is successfully logged in to Acumatica ERP and has given his consent to access, a response is sent to the
redirect URI specified in the authorization request.
If the response_mode parameter was set to form_post in the authorization request, the response has
application/x-www-form-urlencoded format, and the method of the form attribute is POST. If the
response_mode parameter was set to fragment in the authorization request, all response parameters are
added to the fragment component of the redirect URI. The response includes the ID token (if the response_type
parameter contained id_token), the refresh token, and the access token.
The access token and refresh token are saved to the Acumatica ERP database and can be used in the same way as
by OAuth 2.0 client applications.

Connecting to the Token Endpoint

The client application connects to the token endpoint of Acumatica ERP with the POST method by specifying the
following URL and the following parameters in the request body:
• URL
The client application can use one of the following options:
• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the token endpoint address, which is https://<Acumatica
ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP
instance URL> is the URL of the Acumatica ERP instance to which the client application is going to
connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint
address is https://localhost/AcumaticaDB/identity/connect/token.
• Parameters in the Request Body
You specify the following parameters in the request body.
 Authorizing Client Applications to Work with Acumatica ERP | 236

Parameter Description

grant_type The type of the OAuth 2.0 flow, which must be set to authorization_code for
the authorization code flow.

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

code The authorization code that the client application has received from the authoriza-
tion endpoint.

client_secret The value of the secret that was created for the client application during the regis-
tration of the application in Acumatica ERP.

redirect_uri The URI in the client application to which the response to the request should be
sent. The URI must exactly match one of the values specified for the application in
the Redirect URI column on the Redirect URIs tab of the Connected Applications
(SM303010) form.

Receiving the Access Token

Acumatica ERP verifies the provided application credentials and issues the access token, which the client
application should provide with each data request to Acumatica ERP. During authentication in Acumatica ERP,
if the user has granted to the client application the offline_access scope, Acumatica ERP issues the refresh
token along with the access token. A successful response includes the following parameters in the response body.

Parameter Description

token_type The type of the access token, which is Bearer.

access_token The access token.

expires_in The period of time during which the access token is valid.

refresh_token The refresh token. The parameter is returned only if the offline_access scope was
granted.

Requesting Data with the Access Token

The client application should include the access token in the Authorization header of each subsequent
request to Acumatica ERP, as shown in the following HTTP example.

GET /AcumaticaDB/entity/Default/18.200.001/SalesOrder/SO/000001 HTTP/1.1

Host: localhost
Authorization: Bearer cde78a99a2dc6388eb8c7242a90cf9bc
 Authorizing Client Applications to Work with Acumatica ERP | 237

Refreshing the Access Token

The access token is valid for a specific period of time, which is specified in the response that returns the access
token. When the access token expires, the client application can request a new access token by providing the
refresh token to the token endpoint. To request a new access token, the client application should use the POST
method and have the following URL and the following parameters specified in the request body:
• URL
The client application can use one of the following options:
• If the client application supports OpenID Connect Discovery, the client application can use the discovery
endpoint address, which is https://<Acumatica ERP instance URL>/identity/. In this
address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the discovery endpoint
address is https://localhost/AcumaticaDB/identity/.

We recommend that the client application use the discovery endpoint address, which
eliminates the need to change the application if the authorization or token endpoint
address changes.

• The client application can directly use the token endpoint address, which is https://<Acumatica
ERP instance URL>/identity/connect/token. In this endpoint, <Acumatica ERP
instance URL> is the URL of the Acumatica ERP instance to which the client application is going to
connect.
For example, for a local Acumatica ERP instance with the name AcumaticaDB, the token endpoint
address is https://localhost/AcumaticaDB/identity/connect/token.
• Parameters in the Request Body
You specify the following parameters in the request body.

Parameter Description

grant_type The type of the request, which must be set to refresh_token for the request of
the refresh token.

client_id The client ID that was assigned to the client application during the registration
of the application in Acumatica ERP. The client ID must have the format in which
the ID was generated during the registration of the application. That is, the client
ID must include an auto-generated string and the ID of the company, such as
88358B02-A48D-A50E-F710-39C1636C30F6@MyCompany. The client ap-
plication will have access to the data of the company specified in the client ID.

client_secret The value of the secret that was created for the client application during the regis-
tration of the application in Acumatica ERP.

refresh_token The refresh token that the client application received from the token endpoint
along with the access token if the user granted the offline_access scope to
the client application.
 Authorizing Client Applications to Work with Acumatica ERP | 238

Receiving the New Access Token

Acumatica ERP verifies the provided application credentials and issues the new access token and the new refresh
token. To request the access token once again, the client application should use the refresh token issued with the
previous access token. A successful response includes the following parameters in the response body.

Parameter Description

token_type The type of the access token, which is Bearer.

access_token The access token.

expires_in The period of time during which the access token is valid.

refresh_token The refresh token.

Logging Out from Acumatica ERP

To prevent issues with licenses that limit the number of concurrent user sessions, the client application should
directly call the logout method of the Acumatica ERP web services API when the application finishes its work with
Acumatica ERP. The client application does this by using the POST method, the ASP.NET_SessionId cookie
with the value that corresponds to the session, and the following URL.

https://<Acumatica ERP instance URL>/entity/auth/logout

In this address, <Acumatica ERP instance URL> is the URL of the Acumatica ERP instance to which the
client application is going to connect.
Related Links
• OpenID Connect Core 1.0

Comparison of the Flows

The table below summarizes the characteristics of the authorization flows supported by Acumatica ERP.

Characteristic Authorization Implicit Resource Own- Hybrid

Code er Password
Credentials

The access token is returned from No Yes No Yes

the authorization endpoint.

The access token is returned from Yes No Yes No

the token endpoint.

The refresh token can be issued. Yes No Yes Yes

The client application has access No No Yes No

to Acumatica ERP credentials (user-
name and password).
 Authorizing Client Applications to Work with Acumatica ERP | 239

Characteristic Authorization Implicit Resource Own- Hybrid

Code er Password
Credentials

The client application is authen- Yes No Yes Yes

ticated in Acumatica ERP (that is,
the client application provides the
client ID and client secret).

Related Links
• Authorization Code Flow
• Implicit Flow
• Resource Owner Password Credentials Flow
• Hybrid Flow

To Register a Client Application

You use the Connected Applications (SM303010) form to register an OAuth 2.0 or OpenID Connect (OIDC) client
application.
To register a client application in Acumatica ERP, you need to know the flow that this application implements. For
more information on the flows, see Authorization Code Flow, Implicit Flow, Resource Owner Password Credentials
Flow, and Hybrid Flow.

• According to the OAuth 2.0 specification, a secure connection between an OAuth 2.0 client
application and the Acumatica ERP website with a Secure Socket Layer (SSL) certificate is
required. Therefore, you have to set up the Acumatica ERP website for HTTPS before the
OAuth 2.0 client application can work with data in Acumatica ERP. For more information, see
Setting Up an HTTPS Service in Web Server (IIS).
• When you are registering the client application, you have to be logged in to the tenant whose
data the client application needs to access.

To Register a Client Application with the Authorization Code Flow

1. In the Client Name box, type the name of the registered application.

Leave the Client ID box blank. The system will fill it in when you save your changes on the
form.

2. In the Flow box, select Authorization Code.

3. Optionally, in the Plug-In box, select the plug-in that contains custom claims.
4. On the Secrets tab, do the following for each client secret you want to add:
a. On the tab toolbar, click Add Shared Secret. The Add Shared Secret dialog box opens.
b. In the Description box, type the description of the shared secret.
c. Optional: In the Expires On (UTC) box, enter the date and time on which the secret expires.
d. Copy and save the value that is displayed in the Value box. The client application should use this client
secret for authentication in Acumatica ERP.
 Authorizing Client Applications to Work with Acumatica ERP | 240

For security reasons, the value of the secret is displayed only once: when you create the
secret by invoking this dialog box.

e. Click OK to save the secret and close the dialog box.

5. On the Redirect URIs tab, do the following for each redirect URI you want to add:
a. On the tab toolbar, click Add Row.
b. In the Redirect URI column of the new row, type the exact redirect URI to which Acumatica ERP should
redirect the client application aer the client application has been authorized. The redirect URI must be
absolute and must not have the fragment part (the part preceded with #).
6. For the OIDC client application, on the Claims tab, in the Active column, select the claims that will be
included in the ID token.
7. On the form toolbar, click Save. Notice that the client ID has been generated in the Client ID box. The client
application should use this client ID along with the client secret for authentication in Acumatica ERP.

To Register a Client Application with the Implicit Flow

1. In the Client Name box, type the name of the registered application.

Leave the Client ID box blank. The system will fill it in when you save your changes on the
form.

2. In the Flow box, select Implicit.

3. Optionally, in the Plug-In box, select the plug-in that contains custom claims.
4. On the Redirect URIs tab, do the following for each redirect URI you want to add:
a. On the tab toolbar, click Add Row.
b. In the Redirect URI column of the new row, type the exact redirect URI to which Acumatica ERP should
redirect the client application aer the client application has been authorized. The redirect URI must be
absolute and must not have the fragment part (the part preceded with #).
5. For the OIDC client application, on the Claims tab, in the Active column, select the claims that will be
included in the ID token.
6. On the form toolbar, click Save. Notice that the client ID has been generated in the Client ID box. You should
use this client ID to connect the client application to the authorization endpoint of Acumatica ERP.

To Register a Client Application with the Resource Owner Password Flow

1. In the Client Name box, type the name of the registered application.

Leave the Client ID box blank. The system will fill it in when you save your changes on the
form.

2. In the Flow box, select Resource Owner Password Credentials.

3. On the Secrets tab, do the following for each client secret you want to add:
a. On the tab toolbar, click Add Shared Secret. The Add Shared Secret dialog box opens.
b. In the Description box, type the description of the shared secret.
c. Optional: In the Expires On (UTC) box, enter the date and time on which the secret expires.
d. Copy and save the value that is displayed in the Value box. The client application should use this client
secret for authentication in Acumatica ERP.
 Authorizing Client Applications to Work with Acumatica ERP | 241

For security reasons, the value of the secret is displayed only once: when you create the
secret by invoking this dialog box.

e. Click OK to save the secret and close the dialog box.

4. On the form toolbar, click Save. Notice that the client ID has been generated in the Client ID box. The client
application should use this client ID along with the client secret for authentication in Acumatica ERP.

To Register a Client Application with the Hybrid Flow

1. In the Client Name box, type the name of the registered application.

Leave the Client ID box blank. The system will fill it in when you save your changes on the
form.

2. In the Flow box, select Hybrid.

3. Optionally, in the Plug-In box, select the plug-in that contains custom claims.
4. On the Secrets tab, do the following for each client secret you want to add:
a. On the tab toolbar, click Add Shared Secret. The Add Shared Secret dialog box opens.
b. In the Description box, type the description of the shared secret.
c. Optional: In the Expires On (UTC) box, enter the date and time on which the secret expires.
d. Copy and save the value that is displayed in the Value box. The client application should use this client
secret for authentication in Acumatica ERP.

For security reasons, the value of the secret is displayed only once: when you create the
secret by invoking this dialog box.

e. Click OK to save the secret and close the dialog box.

5. On the Redirect URIs tab, do the following for each redirect URI you want to add:
a. On the tab toolbar, click Add Row.
b. In the Redirect URI column of the new row, type the exact redirect URI to which Acumatica ERP should
redirect the client application aer the client application has been authorized. The redirect URI must be
absolute and must not have the fragment part (the part preceded with #).
6. For the OIDC client application, on the Claims tab, in the Active column, select the claims that will be
included in the ID token.
7. On the form toolbar, click Save. Notice that the client ID has been generated in the Client ID box. The client
application should use this client ID along with the client secret for authentication in Acumatica ERP.

Related Links
• Connected Applications

To Revoke the Access of a Connected Application

To revoke the access of an OAuth 2.0 or OpenID Connect client application, you use either the Connected
Applications (SM303010) form or the User Profile (SM203010) form.

On the Connected Applications form, you can revoke the access of any application registered in the current
company. On this form, you revoke all access granted to the application.
 Authorizing Client Applications to Work with Acumatica ERP | 242

On the User Profile form, you can revoke the access of any application to which you (that is, the user account
to which you are logged in) have granted access. Any access granted to this application by other users remains
unchanged.

To Revoke All Access of a Client Application

1. On the Connected Applications form, in the Client ID box, select the application whose access you want to
revoke.
2. On the form toolbar, click Revoke Access.
3. In the message box that opens, click OK to confirm that you want to revoke the access of the application.

Aer you have confirmed that you want to revoke access, all access tokens are removed from
the Acumatica ERP database, and these tokens cannot be used to access data in Acumatica
ERP. However, the client secrets remain valid until their expiration dates (if applicable), and
the application can use these secrets to request a new access token.

To Revoke Access You Have Provided

1. In the info area (in the upper-right corner of the screen), click your username, and then click User Profile.
2. On the toolbar of the User Profile form, which opens, click View Connected Applications. The list of
applications to which you have granted access is displayed on the Client Application Permissions webpage.
3. For the application whose access you want to revoke, click Revoke Access.

Aer you have revoked access, the access tokens that were created when you granted access
to the application are removed from the Acumatica ERP database, and these tokens cannot
be used to access data in Acumatica ERP. However, the client secrets remain valid until their
expiration dates (if applicable), and the application can use these secrets to request a new
access token.
 Limiting Connections of Integrated Applications | 243

Limiting Connections of Integrated Applications

Acumatica ERP licenses include limitations that affect the external applications that are integrated with Acumatica
ERP through the web services APIs. In this chapter, you can find details about these limitations and the limitations
that can also be configured for integrated applications.
For general information about Acumatica ERP licenses, see Licensing and Activating Acumatica ERP.

License Restrictions for API Users

API users are client applications that sign in to Acumatica ERP by using one of the following ways:
• The sign-in method of the contract-based REST API
• The sign-in method of the contract-based SOAP API
• The sign-in method of the screen-based SOAP API
• The OAuth 2.0 mechanism of authorization for applications
Each Acumatica ERP license includes the limits on the number of web services API users, the number of concurrent
API requests, and the number of web services API requests per minute. You can view these limits of the Acumatica
ERP license on the License Monitoring Console (SM604000) form. The trial license sets the limit on the number of
web services API users to two and imposes no other limits.
The following sections describe these limits and the lifecycle of API requests.

Number of Web Services API Users

On the License tab of the License Monitoring Console (SM604000) form, the Maximum Number of Web Services
API Users box displays the license restriction for the number of API users that can work with Acumatica ERP. When
an extra API user tries to sign in to the system and the number of API user sessions exceeds your license restriction,
an error message is returned and the sign-in process is interrupted. The following diagram shows an example of
how this limitation works with three sign-in requests when the Maximum Number of Web Services API Users is
set to 2.

Figure: Rejection of an API user

To avoid exceeding the maximum number of API users, external applications must properly implement the signing
in to and signing out from Acumatica ERP. If an external application does not close its sessions in Acumatica ERP
(that is, does not sign out from Acumatica ERP in each session), this application can prevent other applications
from signing in. For details about the implementation of signing in and signing out, see the following sources:
• Sign In to the Service for the REST API
• Login() Method for the contract-based SOAP API
 Limiting Connections of Integrated Applications | 244

• Login() Method for the screen-based SOAP API

• The descriptions of the scopes in Authorization Code Flow, Implicit Flow, and Resource Owner Password
Credentials Flow for OAuth 2.0 authorization

Number of Concurrent Web Services API Requests

All incoming API requests (except the requests to sign out from Acumatica ERP, which are processed immediately)
are placed in an internal queue. To process these requests, the server uses the API processing cores, which execute
the requests in parallel. The number of cores is no more than the maximum number of concurrent web services
API requests, which is specified in the Maximum Number of Concurrent Web Services API Requests box on the
License tab of the License Monitoring Console (SM604000) form.
The API processing cores take the requests from the queue one by one. If the limit for the number of concurrent
web services API requests has been reached (that is, if all API cores are processing the requests), the next
concurrent request waits in the queue and is processed when one of the previous requests has completed. These
requests in the queue are taken into account in the statistics of the delayed requests (see Lifecycle of the Requests).

The system sends a response to the request when the request is fully processed or declined. For
details about the lifecycle of the requests, see Lifecycle of the Requests.

The following diagram shows an example of how this limitation works with Maximum Number of Concurrent Web
Services API Requests set to 3.

Figure: Request 4 waiting in the internal queue

Number of Web Services API Requests per Minute

The maximum number of requests that can be processed per minute is specified in the Maximum Number of
Web Services API Requests per Minute box on the License tab of the License Monitoring Console (SM604000)
form. If the number of requests in a particular minute reaches 50 percent of the limit specified for the license,
the subsequent requests during this minute are delayed for the following time: 60 seconds minus the number of
seconds that have passed since the beginning of the current minute, divided by the remaining number of requests
that can be processed in the minute (per the specified maximum). These delayed requests are taken into account in
the statistics (see Lifecycle of the Requests).
For example, suppose that in a particular license, the limit of the number of web services API requests per minute
is 50. Since the beginning of the current minute, if the system has already processed 25 requests in 40 seconds and
 Limiting Connections of Integrated Applications | 245

the system receives another request, this request is delayed in the internal queue for 10 seconds, calculated as (60
- 40) / (50 - 25). Aer this delay, the request will be processed.

The system sends a response to the request when the request is fully processed or declined. For
details about the lifecycle of the requests, see Lifecycle of the Requests.

The following diagram shows an example of how this limitation works with Maximum Number of Web Services
API Requests per Minute set to 50 and with 25 requests processed in the minute.

Figure: Request 28 delayed in the internal queue

Decline of the Requests

The request will be declined only if the number of requests in the internal queue is greater than 20, or the request
remains in the queue for more than 10 minutes. Acumatica ERP gives no indication that a request is added to the
queue or being processed; the application that makes a request should stay connected and wait for the response.
For example, suppose that during one second, each of 50 external applications sends a web services API request
to one Acumatica ERP server. Suppose also that each request is processed for 1 second and that the maximum
number of concurrent web services API requests in the license is 16. In this case, the first 16 requests will be
passed to 16 API processing cores immediately. The next 20 requests will wait in the internal queue, and the last 14
requests will be declined.

Lifecycle of the Requests

The system sends a response to the request when the request is fully processed or declined. You can view the
statistics of the delayed and declined requests on the Statistics tab of the License Monitoring Console (SM604000)
form.
The following diagram shows the lifecycle of a web services API request. For details about how the sign-in requests
are processed, see Limitation of API Connections for Integrated Applications.
 Limiting Connections of Integrated Applications | 246

Figure: Lifecycle of a request

Limitation of API Connections for Integrated Applications

If an integrated application does not properly sign out from Acumatica ERP, this application can use all of the API
sessions included in the license (that is, reach the maximum number of API users, which is described in License
Restrictions for API Users), thus preventing other integrated applications from signing in. To avoid such situations,
you can limit the number of sessions for either each integration application assigned to a user type or an individual
integration application.
Before configuring these limits, on the Warnings tab of the License Monitoring Console (SM604000) form, you can
review whether any of the integrated application opens more than three sessions at a time (which is a predefined
system value for this form). If the number of sessions has not been limited for an integrated application and this
application opens more than three sessions at a time, a warning is generated and listed in the table on this tab. This
warning can indicate that you should configure a limitation for the particular integration application or review the
implementation of signing in and signing out in the application.

Configuration of the Limitations

You limit the number of sessions used by each integration application on the User Types (EP202500) form. Also, if
it is necessary to specify a different limit for a particular integration application, you can specify this limit on the
Users (SM201010) form. For details about how to limit the number of sessions in both of these ways, see To Limit the
Number of API Connections of Integrated Applications and To Limit API Connections of a Particular Application.
 Limiting Connections of Integrated Applications | 247

Lifecycle of Sign-in Requests

The lifecycle of any type of requests (including sign-in requests) is described in Lifecycle of the Requests. This
section describes peculiarities of the lifecycle of sign-in requests.
The limitations for the number of API users and the limit of the number of sessions for a particular application are
taken into account when one of the API processing cores takes the sign-in request. The API processing core then
processes the sign-in request as follows:
1. Checks whether the maximum number of API users is exceeded. For details about this limit, see License
Restrictions for API Users.
2. Checks whether the limit of the number of sessions specified for this API user is exceeded.
If the number of sessions opened by the integrated application reaches the limit specified for this integrated
application on either the User Types (EP202500) form or the Users (SM201010) form, the integrated
application cannot open any new session (that is, cannot sign in to Acumatica ERP) until it closes one of the
existing sessions. The system returns an error in the response to the sign-in request.
If no limit is specified for the integration application on the User Types form or on the Users form, the
integration application can open no more sessions than the maximum number of API users in the license.

The diagram in Lifecycle of the Requests shows how a sign-in request is processed by an API processing core.
Related Links
• To Limit the Number of API Connections of Integrated Applications
• To Limit API Connections of a Particular Application

To Limit the Number of API Connections of Integrated Applications

On the User Types (EP202500) form, you limit the number of sessions (that is, API connections) used by each of the
integrated applications. You can also specify a different limit for a particular integrated application as described in
To Limit API Connections of a Particular Application.

Before You Proceed

On the User Roles (SM201005) form, create a user role that will be used by integrated applications. For details
about user roles, see Configuring User Roles.

To Limit API Connections of Each Integrated Application

1. Open the User Types (EP202500) form.
2. Create a user type that will be used by integrated applications as described in To Add a User Type. On the
Allowed Roles tab, add the role that you created in the preliminary instructions (Before You Proceed).
3. On the Login Rules tab, specify the following settings:
• Allowed Login Type:
• API if your integration application uses the Login method of one of the web services API to sign in to
Acumatica ERP
• Unrestricted if your integration application uses OAuth 2.0 mechanism of authorization
• Max. Number of Concurrent Logins: The maximum number of sessions (API connections) you want to
allow for each integration application
• Turn Off Two-Factor Authentication: Selected
4. Save your changes.
 Limiting Connections of Integrated Applications | 248

5. On the Users (SM201010) form, create a user account for each integrated application that can work with this
Acumatica ERP instance. For each user account, specify the type that you have created in the previous steps
and add the role that you have created in the preliminary instructions (Before You Proceed). For details
about the creation of a user account, see User Access: To Add a User Account.
6. In each of the integrated applications, implement the signing in to Acumatica ERP with its own user account
(one of the user accounts created in the previous step). For details about the implementation of signing in,
see the following sources:
• Sign In to the Service for the REST API
• Login() Method for the contract-based SOAP API
• Login() Method for the screen-based SOAP API
• The descriptions of the scopes in Authorization Code Flow, Implicit Flow, and Resource Owner Password
Credentials Flow for OAuth 2.0 authorization

Related Links
• Limitation of API Connections for Integrated Applications
• To Limit API Connections of a Particular Application

To Limit API Connections of a Particular Application

On the Users (SM201010) form, you can specify a limit for the number of sessions used by a particular integrated
application.

Instead of specifying a limit for a particular integrated application, on the User Types (EP202500)
form, you can limit the number of sessions for each integrated application. For details about how
to limit the number of sessions for each integrated application, see To Limit the Number of API
Connections of Integrated Applications.

If a limit is specified on the Users form for a user account associated with an integrated application, this limit
overrides any limit specified on the User Types form. If no limit is specified on the Users form for a user account
associated with an integration application, any limit specified on the User Types form is used.

To Limit API Connections of a Particular Application

1. Open the Users (SM201010) form.
2. For the user account that the integration application uses, type the account's maximum number of sessions
in the Max. Number of Concurrent Logins box.

Related Links
• Limitation of API Connections for Integrated Applications
• To Limit the Number of API Connections of Integrated Applications
 Configuring Push Notifications | 249

Configuring Push Notifications

Acumatica ERP provides push notifications that make it possible for the external applications to track the changes
in the data in Acumatica ERP. That is, you can configure Acumatica ERP to send notifications to a destination (such
as an HTTP address) when specific data changes occur in Acumatica ERP. The external application can receive
these notifications and process the information on the data changes, if necessary. With push notifications, the
external application doesn't need to continually poll for the data to find out whether there are any changes in this
data, which helps improve the performance of the external application.
In this chapter, you can find information on how to configure Acumatica ERP to send push notifications. You can
also find information on how to configure push notifications in code.

Push Notifications

Push notifications are notifications in JSON format that are sent by Acumatica ERP to notification destinations
when specific data changes occur in Acumatica ERP. External applications can receive the notifications and process
them to retrieve the information about the changes.
To work with Acumatica ERP push notifications, you need to configure the following items:
• The data query that defines the data changes for which Acumatica ERP should send notifications
• The destination to which Acumatica ERP should send notifications
• The way the external application processes the notifications
• The definition of the push notification in Acumatica ERP, which specifies the data query and the notification
destination
The following diagram illustrates the sending of a push notification. In the diagram, rectangles with a red border
indicate the items that you need to configure to receive push notifications when changes occur.

Figure: Sending a push notification

Data Query
The data query can be defined by either a generic inquiry or a built-in definition (which is a data query defined in
code). For details on generic inquiries, see Managing Generic Inquiries. For information on how to create a built-in
definition, see To Create a Built-In Definition. You can define multiple queries for one notification destination.
The data query should adhere to the recommendations described in Recommendations for the Data Queries.
 Configuring Push Notifications | 250

Notification Destination
The following predefined notification destinations are provided: webhook (HTTP address), message queue,
SignalR hub, or commerce push destination. For more information on the predefined notification destinations, see
Push Notification Destinations. You can also create your own destination type, as described in To Create a Custom
Destination Type.

Processing of the Notifications in the External Application

The external application can process the notifications and extract the information about the data changes.
Acumatica ERP sends notifications to notification destinations in JSON format. For details on the format of the
notifications, see Push Notification Format. If your application watches notifications in the SignalR hub, you need to
connect to the hub, as described in To Connect to the SignalR Hub.

Definition of the Push Notification

In the definition of the push notification on the Push Notifications (SM302000) form, you specify the notification
destination and the data queries for which the notifications should be sent. You can also specify particular fields
that the system should track in the results of the data queries. For details on the setup of the push notifications, see
To Configure Push Notifications.

Related Links
• To Configure Push Notifications

Recommendations for the Data Queries

For optimal results, follow these recommendations when you create each data query for which you want to
configure push notifications:
• Do not use aggregation and grouping in the query; Acumatica ERP does not guarantee that push
notifications will work correctly with such queries.
• Do not use joins of multiple detail tables in the query because this may cause the system to hang.
• If you need to join multiple tables, use a le join or an inner join in the data query. If you use an inner join,
the query execution may be slower than for a le join.
• Use as simple a data query as possible.
• For a query defined by using a generic inquiry, do not use a formula on the Results Grid tab of the Generic
Inquiry (SM208000) form.
• For a query defined by using a generic inquiry, do not use description fields of selectors on the Results Grid
tab of the Generic Inquiry form. To track changes in the description value, in the generic inquiry, explicitly
join the table that contains the description and add the field from this table in the results of the generic
inquiry.
Related Links
• To Configure Push Notifications

Push Notification Destinations

When you configure a push notification on the Push Notifications (SM302000) form of Acumatica ERP, you select the
type of the notification destinations, which can be any of the predefined types described in this topic. You can also
 Configuring Push Notifications | 251

create your own destination type, as described in To Create a Custom Destination Type in the Acumatica Framework
Developer Guide.

Webhook
A webhook is an HTTP address to which Acumatica ERP sends HTTP POST requests with notification information.
For this destination type, you specify a valid HTTP address (such as http://localhost:80/main.aspx?
pushqueue) in the Address box on the Push Notifications (SM302000) form. For security reasons, you can specify a
header of the HTTP request in the Header Name and Header Value boxes.

Do not specify the Accept and Content-Type headers for the request. The values of these
headers are specified automatically by the system.

If an integrated application returns an error in reply for a push notification, the push notification is resent. If
your application processed the request and sent an error in the reply, your application receives the same push
notification again, which can lead to duplicate data in the application. Therefore, you should not reply with an error
if a push notification is successfully received.
Acumatica ERP makes at most five attempts to send a push notification automatically. If Acumatica ERP cannot
send notifications to the HTTP address, Acumatica ERP logs information on the failed notifications and displays
these notifications on the Process Push Notifications (SM502000) form. You can resend the failed notifications for
two days, aer which the notifications are removed from the Acumatica ERP database. For details on how to resend
notifications, see To Process Failed Notifications.

Message Queue
The message queue is a local or remote private Microso message queue. You specify the address of the message
queue (such as MyComputer\private$\TestQueueForPushNotificatons) in the Address box on the
Push Notifications (SM302000) form. For information on how to configure a private Microso message queue, see
the Microso documentation.
The message queue is the most reliable destination type protected from network failures. However, if Acumatica
ERP cannot send notifications to the message queue for some reason in five attempts, Acumatica ERP logs
information about the failed notifications and displays these notifications on the Process Push Notifications
(SM502000) form. You can resend the failed notifications for two days, aer which the notifications are removed
from the Acumatica ERP database. For information on how to resend notifications, see To Process Failed
Notifications.

SignalR Hub
The SignalR hub is the destination type implemented in Acumatica ERP by using the ASP.NET SignalR library. The
address of this destination type is PushNotificationsHub, which is filled in automatically in the Address box
on the Push Notifications (SM302000) form. This destination type can be used if you can expose neither an HTTP
address (webhook) nor a message queue to receive push notifications. If Acumatica ERP is configured to send
notifications to the SignalR hub, the external application can connect to Acumatica ERP through websoket or a
long-polling mechanism and receive notifications through this connection. If multiple external applications are
connected to the SignalR hub, they receive notifications simultaneously. For information on how to connect your
application to the SignalR hub of Acumatica ERP, see To Connect to the SignalR Hub.
The SignalR hub destination type is not reliable: If the connection fails or there are no clients connected to the
SignalR hub when a notification comes, this notification will not be sent and it cannot be resent later.

Commerce Push Destination

The commerce push destination is a local private Microso message queue that is used for notifications sent to
a commerce connector. The address of this destination type is Commerce, which is filled in automatically in the
 Configuring Push Notifications | 252

Address box on the Push Notifications (SM302000) form. For details about commerce push notifications, see Real-
Time Synchronization Through Push Notifications in the Plug-In Development Guide.

Acumatica ERP makes at most five attempts to send a push notification automatically. If Acumatica ERP cannot
send notifications to the commerce push destination for some reason, Acumatica ERP logs information about the
failed notifications and displays these notifications on the Process Push Notifications (SM502000) form. You can
resend the failed notifications for two days, aer which the notifications are removed from the Acumatica ERP
database. For information on how to resend notifications, see To Process Failed Notifications.

Push Notification Format

Acumatica ERP sends push notifications in JSON format. This topic describes the structure of the notifications.

Elements
The push notifications that Acumatica ERP sends include the following elements in JSON format.

Element Description

Inserted The rows that are new in the results of the query execution.

Deleted The rows that were in the results of the query execution but are missing after the latest
data transaction. You can compare the Inserted and Deleted rows to identify the
rows that have been updated.

Query The query for which Acumatica ERP has produced the notification. The value of the el-
ement can be either the name of the generic inquiry or the name of the class with the
built-in definition.

CompanyId The name of the tenant.

Id The unique identifier of the data transaction in Acumatica ERP that has initiated the noti-
fication. The external application can use this identifier to omit duplicated notifications.

TimeStamp The long value that corresponds to the date and time when the transaction that initiat-
ed the notification happened in Acumatica ERP. By using the value of this element, the
external application can define the order of notifications.

AdditionalInfo Any additional information that is added to the notification. This element can contain ad-
ditional information added by the system as well as the custom information. For more in-
formation on how to add custom additional information to push notifications, see To Add
Additional Information to Push Notifications.

Example
Suppose that push notifications are configured for the Stock Items: Last Modified Date generic inquiry (which
displays the InventoryID, StockItem, ItemStatus, and InventoryItem_lastModifiedDateTime columns).
Acumatica ERP sends the following notification when the status of the AACOMPUT01 inventory item has been
changed from Active to Inactive.

{
"Inserted":
[{
"InventoryID":"AACOMPUT01",
 Configuring Push Notifications | 253

"StockItem":true,
"ItemStatus":"Inactive",
"InventoryItem_lastModifiedDateTime":"2017-05-05T15:16:23.1"
}],
"Deleted":
[{
"InventoryID":"AACOMPUT01",
"StockItem":true,
"ItemStatus":"Active",
"InventoryItem_lastModifiedDateTime":"2017-05-05T15:16:23.103"
}],
"Query":"Stock Items: Last Modified Date",
"CompanyId":"MyTenant",
"Id":"1af4d140-5321-41f2-a2ec-50b67f577c6c",
"TimeStamp":636295833829493672,
"AdditionalInfo":{}
}

To Configure Push Notifications

To configure push notifications, you use the Push Notifications (SM302000) form.
This topic describes how to configure push notifications for the following notification destinations: webhook
(HTTP address), message queue, and SignalR hub. For details about how to configure Acumatica ERP to send push
notifications to commerce push destination, see Step 1: Defining the Data for Real-Time Synchronization.
You can configure as many push notifications as you wish; there is no limit to their number.

Before You Proceed

You need to define the data query or data queries for which Acumatica ERP should send notifications on data
changes. Each data query can be defined by either a generic inquiry or a built-in definition. For details on generic
inquiries, see Managing Generic Inquiries. For information on how to create a built-in definition, see To Create a
Built-In Definition. For details on defining the data queries, see Recommendations for the Data Queries.

You should also identify the notification destination that your external application will scan, which can be one of
the following: webhook (HTTP address), message queue, or SignalR hub. For more information on the notification
destinations, see Push Notification Destinations. You should configure your external application so that it can
process notifications sent to the destination.

To Send Notifications to an HTTP Address

1. Open the Push Notifications (SM302000) form.
2. In the Destination Name box, type the name of the target notification destination, which can be the name
of your external application.
3. In the Destination Type box, select Webhook.
4. In the Address box, type the HTTP address to which Acumatica ERP should send the push notifications,
such as http://localhost:80/main.aspx?pushqueue.
5. Optional: In the Header Name and Header Value boxes, specify the header of the HTTP POST request in
which Acumatica ERP sends the notification.
 Configuring Push Notifications | 254

Do not specify the Accept and Content-Type headers for the request. The values of these
headers are specified automatically by the system.

6. For each generic inquiry for which you want Acumatica ERP to send notifications on changes in the inquiry
results, do the following on the Generic Inquiries tab:
a. On the table toolbar of the Inquiries table, click Add Row. The new row has the Active check box
selected.
b. In the Inquiry Title column of the added row, select the generic inquiry for which you want Acumatica
ERP to send notifications.
c. Do one of the following:
• If you want the system to send push notifications for changes in any field in the results of the generic
inquiry, select the Track All Fields check box in the added row.

If all fields in the results of the generic inquiry are tracked, the system produces push
notifications for changes of any field in the results of the generic inquiry, which can
cause overflow of the push notification queue. If you need to track only particular fields
in the results of the generic inquiry, push notifications for changes in other fields are
useless for you but consume system resources. Therefore, we recommend that you
specify particular fields to be tracked in the Fields table.

• If you need to track only particular fields in the results of the generic inquiry, while the row of the
Inquiries table is still selected, do the following in the Fields table for each field that you need to
track:
a. On the table toolbar, click Add Row.
b. In the Table Name column of the added row, select the name of the table that contains the field
that the system should track.
c. In the Field Name column, select the name of the field that the system should track.
7. For each built-in definition for which you want Acumatica ERP to send notifications on changes in the
results, do the following on the Built-In Definitions tab:
a. On the table toolbar of the Definitions table, click Add Row. The new row has the Active check box
selected.
b. In the Class Name column of the added row, select the class that defines the data query for which you
want Acumatica ERP to send notifications.
c. Do one of the following:
• If you want the system to send push notifications for changes in any field in the results of the data
query defined by the class, select the Track All Fields check box in the added row.

If all fields in the results of the data query are tracked, the system produces push
notifications for changes of any field in the results of the data query, which can cause
overflow of the push notification queue. If you need to track only particular fields in the
results of the data query, push notifications for changes in other fields are useless for
you but consume system resources. Therefore, in this case, we recommend that you
specify particular fields to be tracked in the Fields table.

• If you need to track only particular fields in the results of the data query, while the row of the
Definitions table is still selected, do the following in the Fields table for each field that you need to
track:
a. On the table toolbar, click Add Row.
b. In the Table Name column of the added row, select the name of the table that contains the field
that the system should track.
 Configuring Push Notifications | 255

c. In the Field Name column, select the name of the field that the system should track.
8. On the form toolbar, click Save.

To Send Notifications to a Message Queue

1. Open the Push Notifications (SM302000) form.
2. In the Destination Name box, type the name of the target notification destination, which can be the name
of your external application.
3. In the Destination Type box, select Message Queue.
4. In the Address box, type the address of the local or remote private Microso message queue that you
have configured for receiving messages from Acumatica ERP, such as MyComputer\private$
\TestQueueForPushNotificatons.
5. For each generic inquiry for which you want Acumatica ERP to send notifications on changes in the inquiry
results, do the following on the Generic Inquiries tab:
a. On the table toolbar of the Inquiries table, click Add Row. The new row has the Active check box
selected.
b. In the Inquiry Title column of the added row, select the generic inquiry for which you want Acumatica
ERP to send notifications.
c. Do one of the following:
• If you want the system to send push notifications for changes in any field in the results of the generic
inquiry, select the Track All Fields check box in the added row.

If all fields in the results of the generic inquiry are tracked, the system produces push
notifications for changes of any field in the results of the generic inquiry, which can
cause overflow of the push notification queue. If you need to track only particular fields
in the results of the generic inquiry, push notifications for changes in other fields are
useless for you but consume system resources. Therefore, we recommend that you
specify particular fields to be tracked in the Fields table.

• If you need to track only particular fields in the results of the generic inquiry, while the row of the
Inquiries table is still selected, do the following in the Fields table for each field that you need to
track:
a. On the table toolbar, click Add Row.
b. In the Table Name column of the added row, select the name of the table that contains the field
that the system should track.
c. In the Field Name column, select the name of the field that the system should track.
6. For each built-in definition for which you want Acumatica ERP to send notifications on changes in the
results, do the following on the Built-In Definitions tab:
a. On the table toolbar of the Definitions table, click Add Row. The new row has the Active check box
selected.
b. In the Class Name column of the added row, select the class that defines the data query for which you
want Acumatica ERP to send notifications.
c. Do one of the following:
• If you want the system to send push notifications for changes in any field in the results of the data
query defined by the class, select the Track All Fields check box in the added row.
 Configuring Push Notifications | 256

If all fields in the results of the data query are tracked, the system produces push
notifications for changes of any field in the results of the data query, which can cause
overflow of the push notification queue. If you need to track only particular fields in the
results of the data query, push notifications for changes in other fields are useless for
you but consume system resources. Therefore, in this case, we recommend that you
specify particular fields to be tracked in the Fields table.

• If you need to track only particular fields in the results of the data query, while the row of the
Definitions table is still selected, do the following in the Fields table for each field that you need to
track:
a. On the table toolbar, click Add Row.
b. In the Table Name column of the added row, select the name of the table that contains the field
that the system should track.
c. In the Field Name column, select the name of the field that the system should track.
7. On the form toolbar, click Save.

To Send Notifications to a SignalR Hub

1. Open the Push Notifications (SM302000) form.
2. In the Destination Name box, type the name of the target notification destination, which can be the name
of your external application.
3. In the Destination Type box, select SignalR Hub. The Address box is filled in automatically with
PushNotificationsHub.
4. For each generic inquiry for which you want Acumatica ERP to send notifications on changes in the inquiry
results, do the following on the Generic Inquiries tab:
a. On the table toolbar of the Inquiries table, click Add Row. The new row has the Active check box
selected.
b. In the Inquiry Title column of the added row, select the generic inquiry for which you want Acumatica
ERP to send notifications.
c. Do one of the following:
• If you want the system to send push notifications for changes in any field in the results of the generic
inquiry, select the Track All Fields check box in the added row.

If all fields in the results of the generic inquiry are tracked, the system produces push
notifications for changes of any field in the results of the generic inquiry, which can
cause overflow of the push notification queue. If you need to track only particular fields
in the results of the generic inquiry, push notifications for changes in other fields are
useless for you but consume system resources. Therefore, we recommend that you
specify particular fields to be tracked in the Fields table.

• If you need to track only particular fields in the results of the generic inquiry, while the row of the
Inquiries table is still selected, do the following in the Fields table for each field that you need to
track:
a. On the table toolbar, click Add Row.
b. In the Table Name column of the added row, select the name of the table that contains the field
that the system should track.
c. In the Field Name column, select the name of the field that the system should track.
5. For each built-in definition for which you want Acumatica ERP to send notifications on changes in the
results, do the following on the Built-In Definitions tab:
 Configuring Push Notifications | 257

a. On the table toolbar of the Definitions table, click Add Row. The new row has the Active check box
selected.
b. In the Class Name column of the added row, select the class that defines the data query for which you
want Acumatica ERP to send notifications.
c. Do one of the following:
• If you want the system to send push notifications for changes in any field in the results of the data
query defined by the class, select the Track All Fields check box in the added row.

If all fields in the results of the data query are tracked, the system produces push
notifications for changes of any field in the results of the data query, which can cause
overflow of the push notification queue. If you need to track only particular fields in the
results of the data query, push notifications for changes in other fields are useless for
you but consume system resources. Therefore, in this case, we recommend that you
specify particular fields to be tracked in the Fields table.

• If you need to track only particular fields in the results of the data query, while the row of the
Definitions table is still selected, do the following in the Fields table for each field that you need to
track:
a. On the table toolbar, click Add Row.
b. In the Table Name column of the added row, select the name of the table that contains the field
that the system should track.
c. In the Field Name column, select the name of the field that the system should track.
6. On the form toolbar, click Save.

Related Links
• Push Notifications

To Process Failed Notifications

To process the push notifications that Acumatica ERP could not send, you use the Process Push Notifications
(SM502000) form. On this form, you can view the notifications that Acumatica ERP has failed to send, try to resend
them, or delete the notifications.

If a notification has failed in Acumatica ERP before it was sent (for example, if Acumatica ERP could
not retrieve the data for the notification), this notification is not displayed in the table on the Process
Push Notifications form. Acumatica ERP saves the information about these notifications in the
PushNotificationsErrors database table if the api:push-notifications:enable-
dead-message-log key is set to true in the web.config file of the Acumatica ERP instance.

To View a Notification
1. Open the Process Push Notifications (SM502000) form.
2. In the table on the form, select the row that contains the notification you want to view.
3. On the form toolbar, click Show Notification.
4. In the Notification Event dialog box, which opens, view the notification in JSON format. For details on the
format of the notification, see Push Notification Format.
 Configuring Push Notifications | 258

To Resend Notifications
1. Open the Process Push Notifications (SM502000) form.
2. Do one of the following:
• If you want to resend particular notifications, in the table on the form, select the check boxes in the rows
that correspond to the notification you want to send, and click Send on the form toolbar.
• If you want to resend all notifications, on the form toolbar, click Send All on the form toolbar.

Push notifications that have the Truncated check box selected cannot be resent.

You can also automate the process of resending failed notifications as follows: Create a generic inquiry based
on the PX.PushNotifications.UI.DAC.PushNotificationsFailedToSend data access class (it
corresponds to the Process Push Notifications form) and configure a push notification for this generic inquiry.

To Delete Notifications
1. Open the Process Push Notifications (SM502000) form.
2. Do one of the following:
• If you want to delete particular notifications, in the table on the form, select the unlabeled check boxes in
the rows that correspond to the notifications you want to delete, and click Delete on the form toolbar.
• If you want to delete all notifications, on the form toolbar, click Delete All.
3. On the form toolbar, click Save.

Related Links
• Process Push Notifications

To Create a Built-In Definition

In Acumatica ERP or an Acumatica Framework-based application, you can configure push notifications for a query
that is defined as a class in the source code of the application—that is, for a built-in definition of the query. The
built-in definition can be implemented in a project of your Acumatica ERP extension library.
To create a built-in definition, follow the instructions in this topic.

To Create a Built-In Definition

1. In a project of your Acumatica ERP extension library, define a class that implements the
PX.PushNotifications.Sources.IInCodeNotificationDefinition interface. The following
code demonstrates the definition of such a class.

using PX.PushNotifications.Sources;

public class TestInCodeDefinition : IInCodeNotificationDefinition

{
}

2. In the class that implements the IInCodeNotificationDefinition interface, implement the

GetSourceSelect() method of the interface so that the method satisfies the following requirements:
 Configuring Push Notifications | 259

• The method must return a tuple of a BqlCommand object, which defines the data query, and a
PXDataValue array, which defines the parameters that should be passed to the query.
• The data query that the method defines should adhere to Recommendations for the Data Queries in the
Integration Development Guide.
The following example shows the GetSourceSelect() method implementation.

using PX.Data;
using PX.PushNotifications.Sources;
using PX.PushNotifications.UI.DAC;

public class TestInCodeDefinition : IInCodeNotificationDefinition

{
public Tuple<BqlCommand, PXDataValue[]> GetSourceSelect()
{
return
Tuple.Create(
PXSelectJoin<PushNotificationsHook,
LeftJoin<PushNotificationsSource,
On<PushNotificationsHook.hookId,
Equal<PushNotificationsSource.hookId>>>>
.GetCommand(), new PXDataValue[0]);
}
}

3. In the class that implements the IInCodeNotificationDefinition interface, implement the

GetRestrictedFields() method of the interface so that the method satisfies the following
requirements:
• The method must return an array of IBqlField-derived types, which contains the fields that should be
returned from the query.
• If you need to return all fields, the method must return null.
The following code shows an example of the implementation of the GetRestrictedFields() method.

using PX.Data;
using PX.PushNotifications.Sources;
using PX.PushNotifications.UI.DAC;

public class TestInCodeDefinition : IInCodeNotificationDefinition

{
...

public Type[] GetRestrictedFields()

{
return new []
{
typeof(PushNotificationsHook.address),
typeof(PushNotificationsHook.type),
typeof(PushNotificationsSource.designID),
typeof(PushNotificationsSource.inCodeClass),
typeof(PushNotificationsSource.lineNbr)
};
}
}

4. Build the project of your Acumatica ERP extension library.

 Configuring Push Notifications | 260

5. On the Built-In Definitions tab of the Push Notifications (SM302000) form, make sure that you can select
the new built-in definition by its class name. The class of the built-in definition, which implements the
IInCodeNotificationDefinition interface, is detected by the system and automatically added to
the list of classes available for selection on the tab.

You can obtain the results of the data query defined with a built-in definition by using
the following endpoint: http(s)://<Acumatica ERP instance URL>/
PushNotifications/<full class name of the built-in definition>.
For example, suppose that you want to retrieve the results of the data query defined with
the PX.PushNotifications.Sources.TestInCodeDefinition class from a local
Acumatica ERP instance with the name AcumaticaDB. You should use the following URL to
obtain the data: http(s)://localhost/AcumaticaDB/PushNotifications/
PX.PushNotifications.Sources.TestInCodeDefinition. The endpoint returns
the data in JSON format.

Related Links
• To Configure Push Notifications
• IInCodeNotificationDefinition Interface

To Connect to the SignalR Hub

If you want your external application to receive push notifications from Acumatica ERP or an Acumatica
Framework-based application but you cannot publish a web hook (for example, for security reasons), the system
can send notifications to the SignalR hub, from which any connected application can receive the notifications.
To connect the external application to the SignalR hub, follow the instructions in this topic.

To Connect to the SignalR Hub

1. In your external application, set up a Basic authentication token to authenticate the application in
Acumatica ERP or an Acumatica Framework-based application, as shown in the following code.

using System;
using System.Text;

class Program
{
static void Main(string[] args)
{
var login = "admin";
var tenant = "Tenant";
var password = "123";
// Set up a Basic authentication token
var basicAuthToken = Convert.ToBase64String(
Encoding.UTF8.GetBytes(login+"@"+tenant+":"+password));
}
}

2. In your external application, connect to an instance of Acumatica ERP or an Acumatica Framework-based

application, as shown in the following code.

using System;
using System.Text;
using Microsoft.AspNet.SignalR.Client.Hubs;
 Configuring Push Notifications | 261

class Program
{
static void Main(string[] args)
{
...
//Connect to an Acumatica ERP instance
var connection = new HubConnection("http://localhost:8081/AcumaticaDB/");
connection.Headers.Add("Authorization", "Basic "+basicAuthToken);
}
}

3. In your external application, create a proxy to the SignalR hub, based on the name of the hub that was
specified in the Destination Name box when the push notification was defined on the Push Notifications
(SM302000) form.

using System;
using System.Text;
using Microsoft.AspNet.SignalR.Client.Hubs;

class Program
{
static void Main(string[] args)
{
...
//Create a proxy to hub
//Use "PushNotificationsHub" as the address of the hub
var myHub = connection.CreateHubProxy("PushNotificationsHub");
connection.Start().ContinueWith(task =>
{
if(task.IsFaulted)
{
Console.WriteLine(
"There was an error during open of the connection:{0}",
task.Exception.GetBaseException());
}
else
{
//Instead of "TestSignalR", specify the name
//that you specified on the Push Notifications form
myHub.Invoke<string>("Subscribe", "TestSignalR").Wait();
}
}).Wait();
}
}

4. In your external application, define the class for a notification, as shown in the following code. For details on
the format of the push notifications, see Push Notification Format.

public class NotificationResult

{
public object[] Inserted { get; set; }
public object[] Deleted { get; set; }
public string Query { get; set; }
public string CompanyId { get; set; }
public Guid Id { get; set; }
public long TimeStamp { get; set; }
public Dictionary<string, object> AdditionalInfo { get; set; }
 Configuring Push Notifications | 262

5. In your external application, process notifications. The following code displays the number of inserted and
updated records specified in the notification in the console application window.

using System;
using System.Text;
using Microsoft.AspNet.SignalR.Client.Hubs;

class Program
{
static void Main(string[] args)
{
...
//Process the notifications
myHub.On<NotificationResult>("ReceiveNotification", nr =>
{
Console.WriteLine("Inserted {0}", nr.Inserted.Length);
Console.WriteLine("Deleted {0}", nr.Deleted.Length);
});
Console.Read();
connection.Stop();
}
}

6. Compile and test your application.

Related Links
• To Configure Push Notifications

To Add Additional Information to Push Notifications

In Acumatica ERP or an Acumatica Framework-based application, you can add additional information to push
notifications, such as the username of the user that performed the data change or the business date when the
data transaction is performed. The additional information can be added to the AdditionalInfo element of
notifications in JSON format. For more information on the format of notifications, see Push Notification Format.

The additional information that you add to push notifications is included in all notifications that are
sent from the Acumatica ERP instance on which the additional information is configured.

The dictionary of additional information can be implemented in a project of your Acumatica ERP extension library.
To add additional information to push notifications, follow the instructions in this topic.

To Add Additional Information to Push Notifications

1. In a project of your Acumatica ERP extension library, define a class that implements the
PX.Data.PushNotifications.ICommitEventEnricher interface.
2. In the class that implements the ICommitEventEnricher interface, implement the Enrich() method
of the interface. In the method, add the properties that you want to be returned in push notifications.
 Configuring Push Notifications | 263

The Enrich() method is called in the PX.Data.PXTransactionScope.Dispose()

method. Therefore, the Enrich() method must not return data that is not accessible in this
scope.

The following code shows a sample implementation of the ICommitEventEnricher interface, which
adds the business date and the name of the user to the AdditionalInfo element of notifications in
JSON format.

using PX.Data;
using PX.Data.PushNotifications;

public class CommitEventEnricher : ICommitEventEnricher

{
public void Enrich(IQueueEvent commitEvent)
{
var businessDate = PXContext.PXIdentity?.BusinessDate;
var userName = PXContext.PXIdentity?.IdentityName;
commitEvent.AdditionalInfo.Add(nameof(businessDate), businessDate);
commitEvent.AdditionalInfo.Add(nameof(userName), userName);
}
}

3. Build the project of your Acumatica ERP extension library.

4. Run Acumatica ERP and make sure that when the results of the query change, the application includes the
additional information in the AdditionalInfo element of the notifications in JSON format, as shown in
the following notification example.

{
...
"TimeStamp":636295833829493672,
"AdditionalInfo":
{
"businessDate":"2017-05-05T15:16:23.1",
"userName":"admin"
}
}

Related Links
• To Configure Push Notifications
• Push Notification Format

To Create a Custom Destination Type

In Acumatica ERP or an Acumatica Framework-based application, you can send push notifications to the
notification destinations, which can be of a predefined type (which is webhook, message queue, SignalR hub,
commerce push destination) or of a custom type, which you can implement in the code of the application.
The notification destination of a custom type can be implemented in a project of your Acumatica ERP extension
library. To create a custom destination, follow the instructions in this topic.
 Configuring Push Notifications | 264

To Create a Custom Destination Type

1. In a project of your Acumatica ERP extension library, define a class that implements the
PX.PushNotifications.NotificationSenders.IPushNotificationSender interface,
which is a sender of push notifications.
2. In the class that implements the IPushNotificationSender interface, implement the following
methods and properties of the interface:
• The Address property, which is the address to which the system should send notifications. A user
specifies the value of this property in the Address box on the Push Notifications (SM302000) form. The
property uses the following syntax.
string Address { get; }

• The Name property, which is the name of the notification destination. A user specifies the value of this
property in the Destination Name box on the Push Notifications (SM302000) form. Use the following
syntax for the property.
string Name { get; }

• The Send method, which sends a notification synchronously and uses as the parameters the notification
to be sent and a cancellation token. The method uses the following syntax.
void Send(
NotificationResultWrapper results,
CancellationToken cancellationToken
);

• The SendAndForget method, which sends a notification without blocking the current thread. We
recommend that you use HostingEnvironment.QueueBackgroundWorkItem in the method
implementation to delegate the execution to a parallel thread. The following code shows a sample
implementation of the method.
using System;
using System.Threading;
using PX.PushNotifications;
using PX.PushNotifications.NotificationSenders;

public void SendAndForget(

NotificationResultWrapper result,
CancellationToken cancellationToken,
Action onSendingFailed,
Action finalizer)
{
try
{
Send(result, cancellationToken);
}
catch (Exception e)
{
onSendingFailed($"Send to target {Name} failed: ({e.Message})");
}
finally
{
finalizer();
}
 Configuring Push Notifications | 265

3. Define a class that implements the

PX.PushNotifications.NotificationSenders.IPushNotificationSenderFactory
interface, which creates a sender of push notifications.
4. In the class that implements the IPushNotificationSenderFactory interface, implement the
following methods and properties of the interface:
• The Create method, which creates a sender and uses as the parameters the destination address,
the name of the notification destination, and the additional parameters (such as a header for an HTTP
address). Use the following syntax for the method.
IPushNotificationSender Create(
string address,
string name,
IDictionary<string, object> additionalParameters
);

• The Type property, which is a string identifier of the destination type that is exactly four characters
long. The value of this property is stored in the database. The property uses the following syntax.
string Type { get; }

• The TypeDescription property, which is a string label of the destination type. A user selects the
value of this property in the Destination Type box on the Push Notifications (SM302000) form. Use the
following syntax for the property.
string TypeDescription { get; }

5. Build the project of your Acumatica ERP extension library.

6. Run Acumatica ERP and test the new destination type.

Related Links
• To Configure Push Notifications
 Configuring Webhooks | 266

Configuring Webhooks
A webhook helps you to integrate external applications that provide data in their own format and need to submit
this data to Acumatica ERP. For example, HubSpot collects data about email clicks and can export this data in a
specific format to a particular URL. By using a webhook, you can configure Acumatica ERP to process the data
submitted to a particular URL and save the data in Acumatica ERP.
To configure the system to process data from an external application in Acumatica ERP with webhooks, you need to
perform the following general steps:
1. Create an implementation class that will process the requests from the external application. For details, see
To Create an Implementation Class.
2. Register the implementation class on the Webhooks (SM304000) form of Acumatica ERP. For details, see To
Register an Implementation Class.
3. Copy the URL that is generated during the registration of the implementation class, and then specify this
URL in the external application so that it sends requests to this URL. For details, see To Configure the External
Application.
4. Test the processing of the requests. For details, see To Manage Request Log.

If the webhook must be used on multiple Acumatica ERP instances, you can include the webhook in a
customization project and publish this project to the needed Acumatica ERP instances. For details, see Webhooks.

API requests received by the webhooks configured on the Webhooks form are summed with other API
requests in the license restrictions.

To Create an Implementation Class

An implementation class is a custom class that processes the requests passed to a particular URL. This class must
implement the IWebhookHandler interface. For more convenient implementation, we recommend that the you
implement this interface in a graph (that is, a class of the PXGraph type).
The IWebhookHandler interface has one method with the following signature.

Task<IHttpActionResult> ProcessRequestAsync
HttpRequestMessage request, CancellationToken cancellationToken)

To Create an Implementation Class

To create an implementation class, do the following:
1. Implement the IWebhookHandler interface.
2. In the ProcessRequest method, do the following:
a. Process authentication information in the request.
b. Transform the data in the external format to data that can be saved in Acumatica ERP.
c. Invoke graph methods that save the data in Acumatica ERP.
3. Place the DLL file with the implementation class in the Bin folder of the Acumatica ERP instance.

If you already have a DLL file with the implementation class as a part of a customization project (a webhook added
as a customization item), instead of placing the DLL file in the Bin folder, you can publish the customization
project. For details, see To Add a Webhook to a Project and To Publish a Single Project.
 Configuring Webhooks | 267

To Register an Implementation Class

Aer you have created an implementation class and placed the DLL of the class in the Bin folder of your Acumatica
ERP instance, you need to register the implementation class.

To Register an Implementation Class

To register an implementation class, do the following:
1. In Acumatica ERP, open the Webhooks (SM304000) form.
2. In the Webhook Name box, enter the name of the webhook.
3. In the Implementation Class box, enter the name of the implementation class you have created.
4. On the form toolbar, click Save.
The system inserts into the URL box the URL that can be used by an external application to send data to
Acumatica ERP. You will need this URL to configure the external application.

To Configure the External Application

For an external application to send requests to Acumatica ERP, you need to configure the external application by
specifying in it the URL generated on the Webhooks (SM304000) form.

To Configure the External Application

In the external application, you should do the following:
1. Specify the URL that has been generated on the Webhooks (SM304000) form for the webhook, so that the
external application sends requests to this URL.
2. Implement requests to Acumatica ERP that satisfy the following requirements:
• The request type must be POST or GET.
• The body must contain only data that can be transferred with the HTTP protocol.
• The body of the request must be no longer than the value specified by the
webhook:maxrequestsize key of the web.config file of the Acumatica ERP instance. By
default, this value is 1 MB. You can change the default value by specifying a different value in the key of
web.config.

To Manage Request Log

On the Request History tab of the Webhooks (SM304000) form, you can remove requests from the log and check
the statuses of the processing of requests. You can also specify the type and amount of requests to be stored in the
log.

To View the Request Log

To view the request details, do the following:
1. In Acumatica ERP, open the Webhooks (SM304000) form.
 Configuring Webhooks | 268

2. In the Webhook Name box of the Summary area, select the webhook for which you want see requests.
3. On the Request History tab, select the request in the table.
4. On the table toolbar, click Show Request Details.
5. In the Request Details dialog box, which opens, view the details of the request, the response, and any
errors.
6. To close the dialog box, click Close.
7. Optional: If you want to remove all requests from the log, on the tab toolbar, click Clear History.

You can limit the length of the body of each request that is stored in the history by using the
webhook:maxbodysizetolog key of the web.config file of the Acumatica ERP instance. By
default, the length is 10 KB. In the request details stored in the history, the system trims the part of the
body that exceeds the specified length.

Webhook Configuration Example

Suppose you need to register employee time activities. For that purpose, you plan to use the Toggl app, which is
used to track employees’ time. To send data about tracked time periods from Toggl to Acumatica ERP, you need to
create a webhook. The following example shows how to implement time tracking in Acumatica ERP by using Toggl.

Step 1: Preparing Toggl

First, you need to prepare the external application, which in this case is Toggl. Do the following:
1. On toggl.com, sign up for an account, and sign in to that account.
2. Create a time entry, which you will use later to test the connection. In the entry, specify the entry
description. Otherwise, you may get the 500 Internal Server Error during testing.
3. On the Toggl website, open your profile page, and copy the API token, which is located at the bottom of the
page.

Step 2: Creating an Implementation Class

To create an implementation class, do the following:
1. In Visual Studio, create a new project called TestWebhook based on the Class Library (.NET Framework)
template.
2. In the project, create a new class with the following code.

namespace TestWebhook
{
public class ToggleWebhookHandler : IWebhookHandler
{
public async Task<System.Web.Http.IHttpActionResult> ProcessRequestAsync(
HttpRequestMessage request, CancellationToken cancellationToken)
{
using (var scope = GetAdminScope())
{
var graph = PXGraph.CreateInstance<TimeEntry>();
var timeEntry = await request.Content.ReadAsAsync<dynamic>(cancellationToken);
int duration = timeEntry.duration;
var ownerId = 2892;
DateTimeOffset date = timeEntry.at;
 Configuring Webhooks | 269

string summary = timeEntry.description;

string project = timeEntry.project?.name ?? "X";
var ta = graph.Items.Insert(new PMTimeActivity() { Date = date.LocalDateTime,
TimeSpent = duration, OwnerID = new Guid("B5344897-037E-4D58-
B5C3-1BDFD0F47BF9"),
Summary = summary });
graph.Items.Cache.SetValueExt<PMTimeActivity.projectID>(ta, project);
graph.Items.Cache.SetValueExt(ta, "NoteText", "Created from Toggle");
graph.Actions.PressSave();
}
return new OkResult(request);
}
private IDisposable GetAdminScope()
{
var userName = "admin";
if (PXDatabase.Companies.Length > 0)
{
var company = PXAccess.GetCompanyName();
if (string.IsNullOrEmpty(company))
{
company = PXDatabase.Companies[0];
}
userName = userName + "@" + company;
}
return new PXLoginScope(userName);
}
}
}

In the code above, you are implementing the ProcessRequestAsync method of the
IWebhookHandler interface. Inside the method, you are creating an instance of the TimeEntry graph,
parsing the contents of the request, inserting the parsed data in the cache, and saving your changes to the
database.
For more information on working with graphs, refer to Implementing Business Logic.
3. Add references to the PX.Data, PX.Objects, and PX.Common assemblies located in the Bin folder of
your Acumatica ERP instance.
4. Add the following using directives.

using System;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using System.Web.Http.Results;
using PX.Data;
using PX.Data.Webhooks;
using PX.Objects.CR;
using PX.Objects.PM;

5. Build the project.

Step 3: Preparing the Webhook

To prepare the webhook, do the following:
 Configuring Webhooks | 270

1. Copy the TestWebhook.dll file of the class library that you created in the previous step to the Bin
folder of your Acumatica ERP instance.
2. In Acumatica ERP, open the Webhooks (SM304000) form.
3. In the Webhook Name box, enter the name of the webhook: TestWebhook.
4. In the Implementation Class box, start typing the name of the class: ToggleWebhookHandler.
The system will suggest the name of the class based on the added DLL. Select the suggested name:
TestWebhook.ToggleWebhookHandler.
5. On the page toolbar, click Save.
In the URL box, the generated URL appears. An example of this URL is shown below.

http://localhost/PhoneRepairShop/Webhooks/
Company/3d5c2d34-26ed-48bf-9879-cd7f52163c0a

If localhost is inserted in the URL, replace it with your computer address so that the webhook is
accessible from outside your computer.

Step 4: Saving the Webhook to a Customization Project

To simplify deploying a created webhook in another environment, you can add the created webhook to a
customization project by doing the following:
1. Open a customization project in the Customization Project Editor. For details, see To Open a Project. For
details on creating a project, see To Create a New Project
2. In the navigation pane, click Webhooks.
3. On the Webhooks page, which opens, click Add New Record.
4. In the Add Webhooks dialog box, which opens, select the TestWebhook row, and click OK.
5. Add the TestWebhook.dll file as a file item:
a. In the navigation pane, click Files.
b. On the Custom Files page toolbar, click Add New Record.
c. In the Add Files dialog box, which opens, select the Bin\TestWebhook.dll file.
d. Click Save.
The dialog box is closed, and the file appears on the Custom Files page.

To deploy this webhook in a different environment, you can import and publish this customization project instead
of adding the DLL file and registering file on the Webhooks form. For details, see Managing Customization Projects
and To Add a Webhook to a Project.

Step 5: Configuring the External Application

In general, you should configure your external application by specifying the URL generated aer the webhook
registration in the external application.
However, in this case, the Toggl application cannot interact using HTTP, so you should use the Zapier application to
help connect the Toggl application and Acumatica ERP. To configure the Zapier application, do the following:
1. On zapier.com, sign up for an account, and sign in to that account.
2. Create a new zap based on the following template: zapier.com/app/editor/template/90071.

If a template is not available, create a new zap which connects the Toggle app with Acumatica
ERP.
 Configuring Webhooks | 271

In the new zap, specify the Toggl account you created in Step 1.
3. In the Customize Time Entry section of a new zap, click the Test and Review button. Make sure the test
time entry you created in Step 1 is displayed.
4. In the Customize Post section, add the URL you generated in Step 3.
Make sure the connection is valid.
5. Turn on the created zap.

Step 6: Testing the Webhook

To test the webhook you have created, do the following:
1. On the Toggl website, create a time entry and specify its description.
The information about the time entry is sent to Acumatica ERP via Zapier.

You can specify a particular project to which the time activity will be registered. To do that, you
need to specify the project name in Toggl and have a default task for this project specified on
the Tasks tab of the Projects (PM301000) form.

2. Open the Webhooks (SM304000) form. On the Request History tab, you will see the POST request sent from
Toggl.
3. To view the body of the request, in the table, select the request, and on the table toolbar, click Show
Request Details.
The request should contain the body in JSON format with the time entry details.

Related Links
• Webhooks
 Working with the SOAP APIs | 272

Working with the SOAP APIs

In this chapter, you will find information about Acumatica ERP contract-based and screen-based SOAP APIs.

Working with the Contract-Based SOAP API

The contract-based SOAP application programming interface (API) of Acumatica ERP provides the SOAP interface
of the Acumatica ERP contract-based web services through which external systems can get data records from
Acumatica ERP, process these records, and save new or updated records to Acumatica ERP.
This chapter includes the topics that are specific for the contract-based SOAP API. For general information on the
contract-based web services, see Configuring the REST API.
For the API reference, see Contract-Based SOAP API Reference.

Multi-Language Fields

For some text boxes on Acumatica ERP forms, users can type values in multiple languages if multiple locales
are configured in Acumatica ERP. For example, if your Acumatica ERP instance has English and French locales
activated and multilingual user input configured, you can specify the value of the Description box on the Stock
Items (IN202500) form in English and French. For the list of elements that support multiple languages, see Boxes
that Have Multi-Language Support. For details on how to turn on multilingual user input, see Enabling Multilingual
User Input.

Specifying Localized Values of a Multi-Language Field

When you need to specify localized values of a text box by using the contract-based SOAP API, you specify the value
of the field that corresponds to the box as a string in JSON format with the localized values. In this string, you use
the two-letter ISO code of the language with which the value should be associated.
In the example that is mentioned at the beginning of the topic, if you need to specify values in English and French in
the Description box on the Stock Items form, you specify the value of the Description field of the StockItem
entity in the following format: [{en:English description},{fr:French description}], as shown
in the following code fragment.

public static void CreateStockItem(DefaultSoapClient soapClient)

{
//Specify the values of the new stock item
StockItem stockItemToBeCreated = new StockItem
{
InventoryID = new StringValue { Value = "BASESERV" },
Description = new StringValue { Value = "[{en:Item},{fr:Pièce}]" },
ItemClass = new StringValue { Value = "STOCKITEM" },
};
//Create a stock item with the specified values
StockItem newStockItem = (StockItem)soapClient.Put(stockItemToBeCreated);
}
 Working with the SOAP APIs | 273

In the JSON-formatted string, you should specify the actual values of the field in all languages that
are configured for multilingual user input. If you specify the values of the field in particular languages,
the values of the field in other languages configured for multilingual user input become empty. For
example, suppose that in your instance of Acumatica ERP, multi-language fields can have values
in English and French. If you pass the value of a field in the following format [{en:English
description}], the French value of the field becomes empty.

If you specify the value of a multi-language field as plain text, this text is saved as the value of the corresponding
box in the current language of Acumatica ERP (that is, the language that you specified when you logged in to
Acumatica ERP). For details on how to specify the language on login through the contract-based SOAP API, see
Login() Method.

Retrieving Localized Values of a Multi-Language Field

If you need to retrieve localized values of a text box that supports multiple input languages, you retrieve the value
of a special custom field that contains all localized values of the text box and has the Translations suffix in its field
name.
To find out the field name and the view name of the needed custom field with localized values, you find out the
field name and the view name of the multi-language text box and append Translations to the field name. (For
details on how to find out the field name and the view name of an element on the form, see Custom Fields.) For
example, the multi-language Description box on the Stock Items form has the Descr field name and the Item view
name; therefore, the custom field that contains the localized descriptions of a stock item has the DescrTranslations
field name and the Item view name.
The following code shows how to retrieve the localized values of the Description element of the Stock Items form.
(The code below uses Contract Version 2.)

public static void ExportStockItem(DefaultSoapClient soapClient)

{
StockItem stockItem = new StockItem
{
InventoryID = new StringValue { Value = "BASESERV" },
//Specify the localized values to be returned
CustomFields = new[]
{
new CustomStringField
{
fieldName = "DescrTranslations",
viewName = "Item",
Value = new StringReturn(),
}
}
};
//Retrieve the stock item record
StockItem stockItemToRetrieve = (StockItem)client.Get(stockItem);
}

The returned value of a Translations custom field is a string in JSON format with the available localized values
of the field. The language to which the value belongs is identified by the two-letter ISO code of the language. For
example, suppose that the Description element of the Stock Items form has the value Item in English and Pièce in
French. In this case, the value of the DescrTranslations custom field, which corresponds to the Description
element, is the following string: [{en:Item},{fr:Pièce}].
Related Links
• Locales and Languages
• Boxes that Have Multi-Language Support
 Working with the SOAP APIs | 274

• Custom Fields

To Configure the Client Application

In this topic, you will learn how to import the WSDL description of the Acumatica ERP web services into a Visual
Studio project.
The procedure below is described based on an example of the creation of a console project with the
MyBIIntegration name that uses the Default endpoint of the 18.200.001 version. You can create another type of
Visual Studio project with another name and use any other endpoint in this procedure.
The instructions in this topic have been created for Visual Studio 2019.

Importing the WSDL File into a Visual Studio Project

To configure the client application, do the following:
1. Open Visual Studio, and create a new Visual C# console application with the MyBIIntegration name.

To create a console application, click File > New > Project on the main menu of Visual
Studio. In the Create a new project dialog box, which appears, select the Console App (.Net
Framework) C# template and click Next. In the Configure your new project dialog box, specify
the name and location of the solution, select the .NET Framework 4.8 framework version, and
click Create.

The MyBIIntegration application that you have created contains the Program.cs file with the Program
class.
2. Add to the project a reference to the Acumatica ERP web service as follows:
a. On the main menu of Visual Studio, click Project > Add Service Reference.
b. In the Address box of the Add Service Reference dialog box, which opens, specify the URL of the Default
endpoint of the 18.200.001 version (see Item 1 in the following screenshot).

To copy the URL of the service, on the Web Service Endpoints (SM207060) form, select
Default in the Endpoint Name box and 18.200.001 in the Endpoint Version box, click
View Endpoint Service > WSDL on the form toolbar, and copy the URL from the address
line in the browser for the page that opens. In this example, the URL is http://localhost/
MyStoreInstance/entity/Default/18.200.001?wsdl.

c. Click Go (Item 2) to make Visual Studio connect to the web service.

If your Acumatica ERP website uses a self-signed certificate, Visual Studio displays security
alert windows with warnings on the certificate. Click Yes in these windows to proceed.

d. In the Namespace box, type Default (3). This name will be used as a namespace for the web service
classes generated by Visual Studio based on the WSDL description of the service.
e. Click OK (4) to close the dialog box and add to the project the reference to the specified service.
 Working with the SOAP APIs | 275

Figure: Add Service Reference dialog box

Visual Studio adds to the project the Default service reference in the Connected Services project
folder, as shown in the following screenshot. Double-click the Default service reference to open the
Object Browser and view the list of objects and methods available through the service.

Figure: Solution Explorer

3. Modify the app.config file of the project as follows. Cookies are required for the client application to sign
in to Acumatica ERP.

<?xml version="1.0" encoding="utf-8" ?>

<configuration>
...
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="Acumatica" allowCookies="true"
maxReceivedMessageSize="6553600">
</binding>
</basicHttpBinding>
</bindings>
 Working with the SOAP APIs | 276

<client>
<endpoint address=
"http://localhost/MyStoreInstance/entity/Default/18.200.001"
binding="basicHttpBinding" bindingConfiguration="Acumatica"
contract="Default.DefaultSoap" name="DefaultSoap" />
</client>
</system.serviceModel>
</configuration>

To make API calls to Acumatica ERP through HTTPS, you can use the following configuration in
the app.config file. (Here you use the HTTPS address of the endpoint instead of the HTTP
address, and use the Transport security mode, which indicates that API calls to Acumatica
ERP are made through HTTPS.)

<?xml version="1.0" encoding="utf-8" ?>

<configuration>
...
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="Acumatica" allowCookies="true"
maxReceivedMessageSize="6553600">
<security mode="Transport" />
</binding>
...
</basicHttpBinding>
</bindings>
<client>
<endpoint address=
"https://localhost/MyStoreInstance/entity/Default/18.200.001"
binding="basicHttpBinding" bindingConfiguration="Acumatica"
contract="Default.DefaultSoap" name="DefaultSoap" />
</client>
</system.serviceModel>
</configuration>

4. Rebuild the project.

You have created a Visual Studio application and added to it the reference to the Acumatica ERP web service. Now
you can start developing your application. For the description of the SOAP API methods, see Contract-Based SOAP
API Reference.

Related Links
• Contract-Based SOAP API Reference

Contract-Based SOAP API Reference

In this chapter, you will find the reference information for the main objects and methods of the contract-based
SOAP API; these objects and methods are used to transfer data to and from Acumatica ERP.
This chapter covers the following methods, which are exposed by the DefaultSoapClient class:
 Working with the SOAP APIs | 277

Semantics and syntax of some methods and properties are different depending on the version of the
system contract.

• Login() Method
• Logout() Method
• SetBusinessDate() Method
• Get() Method
• GetList() Method (Contract Version 3)
• GetList() Method (Contract Version 2)
• Put() Method
• Delete() Method
• Invoke() Method
• GetProcessStatus() Method
• GetFiles() Method
• PutFiles() Method
• GetCustomFieldSchema() Method
You will also find descriptions of the following properties:
• Attributes Property
• CustomFields Property
• ReturnBehavior Property (Contract Version 3)
• ReturnBehavior Property (Contract Version 2)

Login() Method

You use the Login() method of a DefaultSoapClient object to make the client application sign in to
Acumatica ERP.

Instead of directly signing in to Acumatica ERP, your application can use the OAuth 2.0 authorization.
For details about OAuth 2.0, see Authorizing Client Applications to Work with Acumatica ERP.

Syntax

public void Login(string name, string password, string tenant, string branch, string
locale)

Parameters
• name: The username that the application should use to sign in to Acumatica ERP, such as "admin".
• password: The password for the username, such as "123".
• tenant: The name of the tenant to which the application should sign in, such as "MyStore". You can view
the name that should be used for the tenant in the Login Name box of the Tenants (SM203520) form.
• branch: The ID of the branch to which the application should sign in. You can view the ID of the branch in the
Branch ID box of the Branches (CS102000) form.
• locale: The locale that should be used in Acumatica ERP. You should specify the locale in the
System.Globalization.CultureInfo format converted to string, as with "EN-US".
 Working with the SOAP APIs | 278

This parameter has been developed for future use. You do not need to set its value.

Example
The following code causes the client to sign in to Acumatica ERP by using the parameters that are specified in the
application settings.

using (var soapClient = new DefaultSoapClient())

{
//Log in to Acumatica ERP
soapClient.Login
(
Properties.Settings.Default.UserName,
Properties.Settings.Default.Password,
Properties.Settings.Default.TenantName,
Properties.Settings.Default.BranchName,
null
);
}

Usage Notes
For each call of the Login() method, you must call the Logout() method aer you finish your work with
Acumatica ERP to close the session.
You should take into account Acumatica ERP license API limits when using the Login() method. For details, see
License Restrictions for API Users.

Related Links
• Logout() Method

Logout() Method

You use the Logout() method of a DefaultSoapClient object to make the client application sign out from
Acumatica ERP.

Syntax

public void Logout()

Example
The following code shows how to make the client application sign out from Acumatica ERP.

using (var soapClient = new DefaultSoapClient())

{
//Sign in to Acumatica ERP
...
try
{
//Work with Acumatica ERP through the web services API
 Working with the SOAP APIs | 279

}
finally
{
//Sign out from Acumatica ERP
soapClient.Logout();
}
}

Usage Notes
For each call of the Login() method, you must call the Logout() method aer you finish your work with
Acumatica ERP to close the session. Therefore, we recommend that you call the Logout() method within the
finally block.
Related Links
• Login() Method

SetBusinessDate() Method

You use the SetBusinessDate() method to specify the business date in Acumatica ERP. You can set the
business date to any date to make the system insert this date into the date fields by default. The business date is
inserted into any new document that you create and is used in the default selection parameters that appear on
processing and inquiry screens.

Syntax

public void SetBusinessDate(System.DateTime businessDate)

Parameter
• businessDate: The business date that should be used in Acumatica ERP.

Usage Notes
The business date resets to the current date of your computer aer each login. Therefore, if you need to specify a
business date in your application, you should call the SetBusinessDate() method aer each client application
login.

Get() Method

You use the Get() method to get one record that satisfies the specified conditions from Acumatica ERP. The
conditions must specify only one record in Acumatica ERP; otherwise, an error is returned. If you need to get
multiple records that satisfy the specified conditions, use the GetList() method instead.

Syntax

public Entity Get(Entity entity)

 Working with the SOAP APIs | 280

Parameter
• entity: The entity that specifies the record that should be obtained from Acumatica ERP.

Return Value
The method returns the Entity object that corresponds to the specified record.

Example
The following code gets a customer record with the specified customer ID.

Customer customer = new Customer

{
CustomerID = new StringSearch { Value = "C000000003" },
};
Customer customerData = (Customer)soapClient.Get(customer);

GetList() Method (Contract Version 3)

This topic describes the GetList() method that is available in Version 3 of the system contract.

You use the GetList() method to retrieve from an Acumatica ERP data entry form a list of records that satisfy the
specified conditions.

Do not use the GetList() method to retrieve the records from an inquiry form; instead, use the
Put() method.

Syntax

public Entity[] GetList(Entity entity)

Parameter
• entity: The entity that specifies the conditions that must be met for the records to be returned from
Acumatica ERP.

Return Value
The method returns the array of Entity objects that correspond to the specified records.

Example
The following example gets the list of stock items that have the Active status and that were modified within the past
month. The code returns only the top-level fields of each stock item record (no fields of the detail or linked entities
are returned).

//Filter the items by the last modified date and status

 Working with the SOAP APIs | 281

StockItem stockItemsToBeFound = new StockItem

{
LastModified = new DateTimeSearch
{
Value = DateTime.Now.AddMonths(-1),
Condition = DateTimeCondition.IsGreaterThan
},
ItemStatus = new StringSearch { Value = "Active" }
};

//Get the list of stock items

Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Usage Notes
• To specify the fields whose values you need to obtain for each entity, you use the ReturnBehavior
property of the entity.
• When the GetList() method is called, the system tries to optimize the retrieval of the records and obtain
all needed records in one request to the database (instead of requesting the records one by one). If the
optimization fails, the system returns an error, which specifies the entities or fields that caused the failure of
the optimized request. To prevent the error from being generated, you can do any of the following:
• If you do not need to retrieve the entities or fields that caused the failure, you can exclude these entities
or fields from the list of requested fields by setting the ReturnBehavior property to None for the
entities, or by using the Skip classes of the needed value type (such as StringSkip) for the fields.
• If you need to retrieve the entities of fields that have caused the failure, you can retrieve the needed
records one by one by using the Get() Method method.

Related Links
• ReturnBehavior Property (Contract Version 3)

GetList() Method (Contract Version 2)

This topic describes the GetList() method that is available in Version 2 of the system contract.

You use the GetList() method to retrieve from an Acumatica ERP data entry form a list of records that satisfy the
specified conditions.

Do not use the GetList() method to retrieve the records from an inquiry form; instead, use the
Put() method.

Syntax

public Entity[] GetList(Entity entity)

Parameter
• entity: The entity that specifies the conditions that must be met for the records to be returned from
Acumatica ERP.
 Working with the SOAP APIs | 282

Return Value
The method returns the array of Entity objects that correspond to the specified records.

Example
The following example gets the list of stock items that have the Active status and that were modified within the past
month. The code returns all fields of each stock item record.

//Filter the items by the last modified date and status

StockItem stockItemsToBeFound = new StockItem
{
LastModified = new DateTimeSearch
{
Value = DateTime.Now.AddMonths(-1),
Condition = DateTimeCondition.IsGreaterThan
},
ItemStatus = new StringSearch { Value = "Active" }
};

//Get the list of stock items

Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Usage Notes
• To specify the fields whose values you need to obtain for each entity, you use the ReturnBehavior
property of the entity.
• When the GetList() method is called, the system tries to optimize the retrieval of the records and obtain
all needed records in one request to the database. If the optimization fails, the system obtains the records
one by one, which may significantly increase the time of data retrieval.

Related Links
• ReturnBehavior Property (Contract Version 2)

Put() Method

You use the Put() method to create or modify a record on a data entry form of Acumatica ERP. For example, by
using the Put() method, you can create a customer record on the Customers (AR303000) form.
You also use this method to retrieve data from an inquiry form. For example, by using the Put() method, you can
retrieve data from the Inventory Summary (IN401000) form.

Syntax

public Entity Put(Entity entity)

Parameter
• entity: The entity that specifies the values of the fields of the created record, or the entity that specifies the
record that should be modified and the values of the fields that should be modified in this record.
 Working with the SOAP APIs | 283

If you use this method to create or modify a record on a data entry form, the entity must
specify only one record in Acumatica ERP. If the entity specifies more than one record or no
records, an error is returned during the execution of the method.

Return Value
The method returns the Entity object that corresponds to the created or modified record.

Example 1: Creating a Record

The following example creates a customer record with the specified field values in Acumatica ERP.

//Specify the values of a new customer record

Customer customerToBeCreated = new Customer
{
CustomerID = new StringValue { Value = "JOHNGOOD" },
CustomerName = new StringValue { Value = John Good" },
MainContact = new Contact
{
Email = new StringValue { Value = "[email protected]" },
Address = new Address
{
AddressLine1 = new StringValue { Value = "43 Lake Washington Blvd NE" },
AddressLine2 = new StringValue { Value = "Suite 100" },
City = new StringValue { Value = "Kirkland" },
State = new StringValue { Value = "WA" },
PostalCode = new StringValue { Value = "98033" }
}
}
};

//Create a customer record with the specified values

Customer newCustomer = (Customer) soapClient.Put(customerToBeCreated);

Example 2: Updating a Record

The following example searches for the needed customer record in Acumatica ERP by the email address and
updates the record with the specified customer class value.

//Select the needed customer record and

//specify the values that should be updated
var customerToBeUpdated = new Customer
{
MainContact = new Contact
{
//Search for the customer record by email address
Email = new StringSearch { Value = "[email protected]" }
},
CustomerClass = new StringValue { Value = "INTL" };
};

//Update the customer record with the specified values

var updCustomer = (Customer)soapClient.Put(customerToBeUpdated);
 Working with the SOAP APIs | 284

Example 3: Retrieving Data from an Inquiry Form

The following example retrieves the values of all elements available for a stock item from the Inventory Summary
(IN401000) inquiry form.

//Filter details by warehouse

InventorySummaryInquiry stockItemsToBeFound =
new InventorySummaryInquiry
{
InventoryID = new StringValue { Value = "AALEGO500" },
WarehouseID = new StringValue { Value = "MAIN" }
};

//Retrieve the list of stock items from the inquiry

InventorySummaryInquiry stockItems =
(InventorySummaryInquiry)soapClient.Put(stockItemsToBeFound);

foreach (InventorySummaryRow stockItem in stockItems.Results)

{
//Do something with the results
...
}

Usage Notes
When the Acumatica ERP web services receive a Put request that contains an entity with at least one Search
object, Acumatica ERP tries to search for a record by using the specified search value or values, and does one of the
following:
• If the record that satisfies the specified conditions has been found, Acumatica ERP updates the fields of the
record that are specified by using the Value objects.
• If no record has been found that satisfies the specified conditions, a new record is inserted. Note that the
values that were specified with the Search objects are inserted into the created record in the same way as
the values specified with the Value objects are inserted.
• If multiple records have been found, Acumatica ERP returns an error.
For the key fields of a record that are passed in the Put request as Value objects, the service converts the
corresponding Value objects to Search objects.
When the Acumatica ERP web services receive a Put request that contains only Value, Return, and Skip
objects without key fields specified, Acumatica ERP adds a new record with the specified values.
The workflow of a Put request is illustrated in the following diagram.
Working with the SOAP APIs | 285
 Working with the SOAP APIs | 286

Delete() Method

You use the Delete() method to delete a record from Acumatica ERP.

Syntax

public void Delete(Entity entity)

Parameter
• entity: The entity that specifies the record that should be deleted.

The entity must specify only one record in Acumatica ERP. If the entity specifies more than one
record or no records, an error is returned during the execution of the method.

Usage Notes
The Delete() method is used to delete only the records that correspond to top-level entities. If you need to
delete a detail line of a record, you should set the Delete property of the entity that corresponds to the detail line
to true and pass the top-level entity that contains this entity to Acumatica ERP by using the Put() method.

Invoke() Method

You use the Invoke() method to invoke an action on a record in Acumatica ERP (for example, to perform the
release action on a document).

Syntax

public InvokeResult Invoke(Entity entity, Action action)

Parameters
• entity: The entity that specifies the record on which the action should be invoked.

The entity must specify only one record in Acumatica ERP. If the entity specifies more than one
record or no records, an error is returned during method execution.

• action: The action that should be invoked on the record.

Return Value
The method returns an InvokeResult object, which you should use to monitor the status of the long-running
operation by using the GetProcessStatus() method.
 Working with the SOAP APIs | 287

Example
The following code releases a payment.

//Find the payment that should be released

Payment soPaymentToBeReleased = new Payment
{
Type = new StringSearch { Value = "Payment" },
ReferenceNbr = new StringSearch { Value = "000001" }
};
Payment payment = (Payment)soapClient.Get(soPaymentToBeReleased);

//Release the payment

InvokeResult invokeResult = soapClient.Invoke(payment, new ReleasePayment());

//Monitor the status of the release operation

...

Related Links
• GetProcessStatus() Method

GetProcessStatus() Method

You use the GetProcessStatus() method to monitor the status of a long-running operation (such as the
release or confirmation operation) that you invoked by using the Invoke() method.

Syntax

public ProcessResult GetProcessStatus(InvokeResult invokeResult)

Parameter
• invokeResult: An InvokeResult object that was returned by the Invoke() method.

Return Value
The method returns a ProcessResult object. You should use the Status property of this object to get the
status of the processing operation. When the status of the operation is Completed, you can get the result of
processing, which is identified by the EntityID property of a ProcessResult object.
If a synchronous operation has been invoked by the Invoke() method and the operation has been completed
successfully, the GetProcessStatus() method returns the Completed status.

Example
The following code monitors the status of the payment release processing.

...
//Release payment
InvokeResult invokeResult = soapClient.Invoke(payment, new ReleasePayment());
 Working with the SOAP APIs | 288

//Monitor the status of the process

ProcessResult processResult = soapClient.GetProcessStatus(invokeResult);
while (processResult.Status == ProcessStatus.InProcess)
{
Thread.Sleep(1000); //pause for 1 second
processResult = soapClient.GetProcessStatus(invokeResult);
}
if (processResult.Status == ProcessStatus.Completed)
{
//Get the released payment
payment = (Payment)soapClient.Get(
new Payment { ID = processResult.EntityId });
}

Related Links
• Invoke() Method

GetFiles() Method

You use the GetFiles() method to get the files that are attached to a record.

Syntax

public File[] GetFiles(Entity entity)

Parameter
• entity: The entity that specifies the record in Acumatica ERP to which the files are attached.

Return Value
The method returns an array of web service File objects that contain the properties for accessing the contents
and names of the files.

Example
The following example retrieves the files attached to a stock item record.

//Filter the items by inventory ID

StockItem stockItemToBeFound = new StockItem
{
InventoryID = new StringSearch { Value = "AAMACHINE1" }
};

//Get the stock item record

StockItem stockItem = (StockItem) soapClient.Get(stockItemToBeFound);

//Get the files that are attached to the stock item

if (stockItem != null && stockItem.ImageUrl != null)
{
//Get the attached files
File[] files = soapClient.GetFiles(stockItem);
 Working with the SOAP APIs | 289

...
};

PutFiles() Method

You use the PutFiles() method to attach files to a record in Acumatica ERP.

Syntax

public void PutFiles(Entity entity, File[] files)

Parameters
• entity: The entity that specifies the record to which the files should be attached.
• files: An array of web service File objects that specify the files to be attached.

Example
The following code attaches a file to a stock item record.

//Find the needed stock item

StockItem stockItemToBeFound = new StockItem
{
InventoryID = new StringSearch { Value = "AALEGO500" },
};
StockItem stockItem = (StockItem)soapClient.Get(stockItemToBeFound);

//Read the file data

byte[] filedata;
using (FileStream file =
System.IO.File.Open("D:\\T2MCRO.jpg", FileMode.Open))
{
filedata = new byte[file.Length];
file.Read(filedata, 0, filedata.Length);
}

//Add the file to the stock item record

Default.File[] stockItemFiles = new[]
{
//Default is the name of the service reference
new Default.File
{
Name = fileName,
Content = filedata
}
};
soapClient.PutFiles(stockItem,stockItemFiles);
 Working with the SOAP APIs | 290

GetCustomFieldSchema() Method

You use the GetCustomFieldSchema() method to obtain the list of custom fields of an entity. You can find out
the field name and view name of the needed element by using this method.

Custom fields can correspond to the following elements:

• The predefined elements on an Acumatica ERP form that are not included in the entity
definition
• The elements that were added to the Acumatica ERP form in a customization project
• The user-defined fields

Syntax

public Entity GetCustomFieldSchema(Entity entity)

Parameter
• entity: The entity for which the list of custom fields should be obtained.

Return Value
The method returns the Entity object, which contains the array of custom fields in its CustomFields property.

Example
The following example retrieves the list of custom fields of the StockItem entity.

StockItem stockItem =
(StockItem) soapClient.GetCustomFieldSchema(new StockItem());
CustomField[] customFields = stockItem.CustomFields;

Related Links
• Custom Fields
• CustomFields Property

Attributes Property

By using the Attributes property, you can view and edit the attributes of a record in Acumatica ERP. Through
this property, you work with an array of AttributeValue or AttributeDetail objects.
For the AttributeValue objects, to specify the value of an attribute, you specify the name of the attribute in the
AttributeID property, and the value of the attribute in the Value property.
For the AttributeDetail objects, to specify the value of an attribute, you specify the name of the attribute in
the Attribute property, and the value of the attribute in the Value property.
 Working with the SOAP APIs | 291

Syntax

public AttributeValue[] Attributes { set; get; }

Example
The following code shows how to edit the attributes of a stock item record.

//Specify the values of a stock item record

StockItem stockItemToBeCreated = new StockItem
{
InventoryID = new StringValue { Value = "BASESERV" },
ItemClass = new StringValue { Value = "STOCKITEM" },
Attributes = new []
{
//Specify the values of attributes of the item class (STOCKITEM)
new AttributeValue
{
AttributeID = new StringValue { Value = "Operation System" },
Value = new StringValue { Value = "Windows" }
},
new AttributeValue
{
AttributeID = new StringValue { Value = "Version Of Software" },
Value = new StringValue { Value = "Server 2012 R2" }
}
}
};

//Create a stock item with the specified values

StockItem newStockItem = (StockItem)soapClient.Put(stockItemToBeCreated);

CustomFields Property

By using the CustomFields property, you can view and edit the values of the elements that are not included in
the entity definition. That is, custom fields can correspond to the following elements:
• The predefined elements on an Acumatica ERP form that are not included in the entity definition
• The elements that were added to the Acumatica ERP form in a customization project
• The user-defined fields
Through the CustomFields property, you work with an array of CustomField objects. This property is
exposed by the Entity class—that is, all entities of the web services API expose this property.
To get or set the value of an element that is not included in the entity definition, you should use the
CustomFields property of the entity that contains this element. To work with the needed element in
the CustomFields array, you specify the values of the fieldName and viewName properties of the
CustomField object of the needed type. In the viewName property, you specify the name of the data view that
contains the element, and in the fieldName property, you specify the internal name of the element. For details
on how to find out the field name and the name of the data view, see Custom Fields.
For example, suppose that you added the Personal ID element to the Main Contact area of the Customers
(AR303000) form in a customization project. To work with this customization element through the web services
API, you should use the CustomFields property of the Contact entity, which is available through the
 Working with the SOAP APIs | 292

MainContact property of the Customer entity. The Personal ID customization element has the String type
and has the UsrPersonalID field name and belongs to the DefContact data view. Therefore, to access this
element, you should set the fieldName property of the CustomStringField object to UsrPersonalID,
and the viewName property of the CustomStringField object to DefContact.

Syntax

public CustomField[] CustomFields { set; get; }

Example
Suppose that you added the Personal ID Type, Personal ID, and Credit Record Verified elements to the
Customers form in a customization project, as shown in the following screenshot.

Figure: Custom elements

The following code shows how to specify the values of these custom elements through the web services API.

//Specify the values of a new customer record

Customer customerToBeCreated = new Customer
{
CustomerID = new StringValue { Value = "TEDSMITH" },
CustomerName = new StringValue { Value = "Ted Smith" },
//Specify the values of the custom fields

MainContact = new Contact

{
CustomFields = new[]
{
 Working with the SOAP APIs | 293

new CustomStringField
{
fieldName = "UsrPersonalIDType",
viewName = "DefContact",
Value = new StringValue { Value = "Passport" }
},
new CustomStringField
{
fieldName = "UsrPersonalID",
viewName = "DefContact",
Value = new StringValue { Value = customerPersonalID }
},
new CustomBooleanField
{
fieldName = "UsrCreditRecordVerified",
viewName = "DefContact",
Value = new BooleanValue { Value = true }
}
}
}
};

//Create a customer record with the specified values

Customer newCustomer = (Customer)soapClient.Put(customerToBeCreated);

Usage Notes
To work with elements of an object that was added in a customization project or with a custom Acumatica ERP
form, you have to create a custom endpoint for the needed form. You can create a custom endpoint on the Web
Service Endpoints (SM207060) form. For details on creation of a custom endpoint, see To Create a Custom Endpoint
and To Extend an Existing Endpoint.
Related Links
• Custom Fields
• GetCustomFieldSchema() Method

ReturnBehavior Property (Contract Version 3)

This topic describes the ReturnBehavior property that is available in Version 3 of the system
contract.

By using the ReturnBehavior property, you can specify the fields of the entity whose values should be returned
from the request to the service that is performed by the Get(), GetList(), or Put() method. This property is
exposed by the Entity class—that is, all entities of the web services API expose this property.
For each entity, you can specify one of the following options, which determine the fields for which values should be
returned:
• None: Values should not be returned for any fields of the entity. You can use this option for detail entities
and linked entities, but not for top-level entities.
• OnlySystem: Values should be returned for only the system fields (that is, the fields of the Entity class,
such as ID, RowNumber, and Note). You may need to obtain only the values of the system fields, for
example, if you want to delete the entity.
 Working with the SOAP APIs | 294

• OnlySpecified: Values should be returned for only the specified fields of the entity and the system
fields. You can specify the values to be returned by using the Return classes of the needed value type, such
as StringReturn. The values of the fields that are specified by using the Value or Search classes of the
corresponding value type, such as StringValue and StringSearch, are returned automatically.
• Default: Values should be returned for only the fields of the entity that are defined in the entity itself
(without the fields of the linked and detail entities defined within the entity). This option is used by default.
• All: Values should be returned for all fields of the entity that are defined in the contract (including
the fields of the linked and detail entities defined within the entity). No values of the custom fields (the
Acumatica ERP fields that are not defined in the contract or the fields that are defined in a customization
project) are returned. You can specify the values to be skipped by using the Skip classes of the needed
value type, such as StringSkip.
In the sections below, you can find examples of how to specify the fields whose values should be returned.

Syntax

public ReturnBehavior ReturnBehavior { set; get; }

Example: Obtaining All Fields

The following example shows how to obtain the values of all fields of all stock item records in the system.

StockItem stockItemsToBeFound = new StockItem

{
ReturnBehavior = ReturnBehavior.All
};

//Get the list of stock items with the values of all fields
//that are defined in the contract
Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Example: Obtaining Only the Fields of the Entity Itself Without Linked and Detail Fields
In the following example, only the fields of the top-level StockItem entity are retrieved from the system.

//You can omit the setting of the ReturnBehavior property to ReturnBehavior.Default

//because this option is used by default
StockItem stockItemsToBeFound = new StockItem();

//Get the list of stock items with the values of the fields
//of the StockItem entity itself (without the fields of the detail or linked entities)
Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Example: Obtaining Only Specified Fields

The following example shows how to obtain the values of the InventoryID field, the ItemStatus field, and all
WarehouseDetail fields of all stock item records in the system.

StockItem stockItemsToBeFound = new StockItem

{
ReturnBehavior = ReturnBehavior.OnlySpecified,
InventoryID = new StringReturn(),
ItemStatus = new StringSearch { Value = "Active" },
WarehouseDetails = new StockItemWarehouseDetail[]
 Working with the SOAP APIs | 295

{
new StockItemWarehouseDetail {ReturnBehavior = ReturnBehavior.All}
},
};

//Get the list of stock items with the values of the specified fields
Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Example: Obtaining All Fields Except the Specified Ones

The following example shows how to obtain the values of all fields of all stock item records in the system except the
LastModified field and all WarehouseDetail fields.

StockItem stockItemsToBeFound = new StockItem

{
ReturnBehavior = ReturnBehavior.All,
LastModified = new DateTimeSkip(),
WarehouseDetails = new StockItemWarehouseDetail[]
{
new StockItemWarehouseDetail {ReturnBehavior = ReturnBehavior.None}
},
};

//Get the list of stock items with the values of the specified fields
Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Example: Obtaining Only System Fields

The following example shows how to obtain the values of only system fields of all stock item records in the system.

StockItem stockItemToBeFound = new StockItem

{
ReturnBehavior = ReturnBehavior.OnlySystem,
};

//Get the list of stock items with the values of system fields
Entity[] stockItems = soapClient.GetList(stockItemToBeFound);

ReturnBehavior Property (Contract Version 2)

This topic describes the ReturnBehavior property that is available in Version 2 of the system
contract.

By using the ReturnBehavior property, you can specify the fields of the entity whose values should be returned
from the request to the service that is performed by the Get(), GetList(), or Put() method. This property is
exposed by the Entity class—that is, all entities of the web services API expose this property.
For each entity, you can specify one of the following options, which determine the fields for which values should be
returned:
• None: Values should not be returned for any fields of the entity. You can use this option for detail entities
and linked entities, but not for top-level entities.
 Working with the SOAP APIs | 296

• OnlySystem: Values should be returned for only the system fields (that is, the fields of the Entity class,
such as ID, RowNumber, and Note). You may need to obtain only the values of the system fields, for
example, if you want to delete the entity.
• OnlySpecified: Values should be returned for only the specified fields of the entity and the system
fields. You can specify the values to be returned by using the Return classes of the needed value type, such
as StringReturn. The values of the fields that are specified by using the Value or Search classes of the
corresponding value type, such as StringValue and StringSearch, are returned automatically.
• All: Values should be returned for all fields of the entity that are defined in the contract. No values of the
custom fields (the Acumatica ERP fields that are not defined in the contract or the fields that are added in
a customization project and are not included in the contract) are returned. You can specify the values to be
skipped by using the Skip classes of the needed value type, such as StringSkip. This option is used by
default.
In the sections below, you can find examples of how to specify the fields whose values should be returned.

Syntax

public ReturnBehavior ReturnBehavior { set; get; }

Example: Obtaining All Fields

The following example shows how to obtain the values of all fields of all stock item records in the system.

//You can omit the setting of the ReturnBehavior property to ReturnBehavior.All

//because this option is used by default
StockItem stockItemsToBeFound = new StockItem();

//Get the list of stock items with the values of all fields
//that are defined in the contract
Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Example: Obtaining Only Specified Fields

The following example shows how to obtain the values of the InventoryID field, the ItemStatus field, and all
WarehouseDetail fields of all stock item records in the system.

StockItem stockItemsToBeFound = new StockItem

{
ReturnBehavior = ReturnBehavior.OnlySpecified,
InventoryID = new StringReturn(),
ItemStatus = new StringSearch { Value = "Active" },
WarehouseDetails = new StockItemWarehouseDetail[]
{
new StockItemWarehouseDetail {ReturnBehavior = ReturnBehavior.All}
},
};

//Get the list of stock items with the values of the specified fields
Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Example: Obtaining All Fields Except the Specified Ones

The following example shows how to obtain the values of all fields of all stock item records in the system except the
LastModified field and all WarehouseDetail fields.
 Working with the SOAP APIs | 297

StockItem stockItemsToBeFound = new StockItem

{
ReturnBehavior = ReturnBehavior.All,
LastModified = new DateTimeSkip(),
WarehouseDetails = new StockItemWarehouseDetail[]
{
new StockItemWarehouseDetail {ReturnBehavior = ReturnBehavior.None}
},
};

//Get the list of stock items with the values of the specified fields
Entity[] stockItems = soapClient.GetList(stockItemsToBeFound);

Example: Obtaining Only System Fields

The following example shows how to obtain the values of only system fields of all stock item records in the system.

StockItem stockItemToBeFound = new StockItem

{
ReturnBehavior = ReturnBehavior.OnlySystem,
};

//Get the list of stock items with the values of system fields
Entity[] stockItems = soapClient.GetList(stockItemToBeFound);

Working with the Screen-Based SOAP API

The screen-based SOAP API of Acumatica ERP provides the SOAP interface of the Acumatica ERP contract-based
web services through which external systems can get data records from Acumatica ERP, process these records, and
save new or updated records to Acumatica ERP.

Screen-Based Web Services API

The screen-based web services API is a part of Acumatica ERP integration services, which provides integration with
external data sources and third-party systems by using a SOAP interface.
External applications and systems that use the Acumatica ERP web services API can access the data managed by
Acumatica ERP and the business functionality of Acumatica ERP. For example, you can integrate Acumatica ERP
with eCommerce or an online store system, so that an external system pushes all information about customers,
sales orders, and payments to Acumatica ERP, and Acumatica ERP provides information on the availability of stock
items and processes all incoming data.
The screen-based web services API works with Acumatica ERP forms. That is, it provides API objects and methods
for working with elements on Acumatica ERP forms.
To upload data to and from Acumatica ERP by using the screen-based web services API, you define the sequence of
commands for the system to work with elements on an Acumatica ERP form. This sequence of commands reflects
the sequence of actions to be executed for a data record as if the record is being manipulated by a user through an
Acumatica ERP form. That is, when you enter data into the system manually, you perform a sequence of actions.
You open the needed data entry form and start entering data. As you add a new record, you use the UI elements
one by one—you type text, select values from combo boxes, clear or select check boxes, and click buttons. In the
sequence of commands for the web services, you compose exactly the same sequence of actions by specifying a
 Working with the SOAP APIs | 298

command for each user action on the form. For more information on the commands you can use, see Working with
Commands of the Screen-Based SOAP API.

This sequence of commands is similar to the sequence of commands you configure when you create
import and export scenarios. You can find more information on import and export scenarios in
Configuring Import Scenarios and Configuring Export Scenarios.

To use screen-based web services API in your application, you should generate the WSDL file of the web service, as
described in To Generate the WSDL File of the Web Services, and import this file to your development project as
described in To Import the WSDL File Into the Development Environment. Aer that, you can start developing your
application. You can find the description of the API methods in Screen-Based SOAP API Reference.
Related Links
• API Objects Related to Acumatica ERP Forms
• Screen-Based SOAP API Reference

API Objects Related to Acumatica ERP Forms

The main object, which provides access to all other objects and methods of the Acumatica ERP web services API, is
a Screen object. By using the methods of a Screen object, you can log in to Acumatica ERP and retrieve, insert,
update, and delete data. You can also use the methods to perform any actions that are exposed by Acumatica ERP
forms available through the web service.

Screen Object
Aer you have logged in to Acumatica ERP by using the web services API, you can access data on Acumatica ERP
forms available through the web service. The Screen class provides the same set of API methods for working with
all Acumatica ERP forms available through the service. You can find out which form a method accesses by noting
the prefix in the name of the method, which is the form ID. For example, the Export() method that you use to
export data from the Stock Items (IN202500) form is IN202500Export().

Content Object
To get the description of the structure (schema) of a form, you should use the GetSchema() method of the
Screen object. This method is specific for each Acumatica ERP form, and you should use the method with
the ID of the needed form in the prefix of the method name. The method returns the schema of the form as the
corresponding Content object, which is specific for each form. For example, to get the schema of the Stock Items
form, you should call the IN202500GetSchema() method of the Screen object. You will receive the result as a
IN202500Content object, as the following code shows.

Screen context = new Screen();

...
IN202500Content stockItemsSchema = context.IN202500GetSchema();

Command Object
By using subobjects of a Content object, you configure the sequence of commands that should be executed
during data import, data export, or data processing through the web service. You configure the sequence of
commands inside an array of objects of the Command type. When you are reflecting the selection of an element on
a form in the sequence of commands, you have to select the object of the Acumatica ERP form whose element you
want to access. The objects that are available inside a Content object have names that are similar to the names of
the UI elements that you see on the form and have the ID of the form as a prefix.
 Working with the SOAP APIs | 299

For example, to be able to select the Item Class element, which is located in the Item Defaults group
on the General tab of the Stock Items form (shown in the following screenshot), you would select the
GeneralSettingsItemDefaults property of the IN202500Content object. This property provides access
to the IN202500GeneralSettingsItemDefaults object, which includes the ItemClass property.
Each element on an Acumatica ERP form (such as a text box, combo box, or table column) is associated with a
particular web services API class and is available through corresponding property of this class. The property has
a similar name to that of the corresponding box on the form, such as ItemClass, as the following screenshot
shows.

Figure: API object on an Acumatica ERP form

The following code shows an example of configuring a list of commands for the Stock Items form inside an array of
Command objects.

//stockItemsSchema is a IN202500Content object

var commands = new Command[]
{
stockItemsSchema.StockItemSummary.ServiceCommands.EveryInventoryID,
stockItemsSchema.StockItemSummary.InventoryID,
stockItemsSchema.StockItemSummary.Description,
stockItemsSchema.GeneralSettingsItemDefaults.ItemClass,
stockItemsSchema.GeneralSettingsUnitOfMeasureBaseUnit.BaseUnit
};

For more information on the commands, see Working with Commands of the Screen-Based SOAP API.

Actions Object
To insert an action to a sequence of commands, such as clicking a button, you use the corresponding property of
the special API object Actions (which has a prefix with the ID of the form in the name). The Actions object is
available through the Actions property of the Content object that corresponds to the form. The properties
of the Actions object have names that are similar to the names of corresponding buttons on the form, such as
Delete.
 Working with the SOAP APIs | 300

You can view the classes available through the web services API by using Object Browser in Visual Studio.
Related Links
• Working with Commands of the Screen-Based SOAP API

Screen-Based API Wrapper

Because of the connection of the screen-based SOAP API with Acumatica ERP forms, the applications that are
developed based on this API are sensitive to the UI changes in the system. That is, any changes made to the UI aer
the application is created require the application to be updated and recompiled. If you want your application to not
depend on the UI changes in the system, you should use the screen-based API wrapper, which is described in this
topic.

How a Client Application Based on the Screen-Based API Works

A client application that uses the screen-based web services API includes the WSDL description of the service,
which contains the API elements that the application can use to work with the service. The API elements have
names that are similar to the names of the elements in the UI of Acumatica ERP. For example, the Customer ID
element of the Customers (AR303000) form corresponds to the Customer.CustomerSummary.CustomerID
property.
When the application calls the Screen.GetSchema() method, it retrieves from Acumatica ERP the schema
of an Acumatica ERP form. The schema of the form is a Content object, which defines the correspondence
between the API elements and the internal data fields that are used for operations with data by Acumatica ERP. If
something has been changed in the schema of an Acumatica ERP form, the Content object that is returned by
the Screen.GetSchema() method contains a different correspondence between the API elements and internal
data fields than the correspondence for which the application is compiled, and the application fails.
For example, suppose that a client application requests the customer ID by the
Customer.CustomerSummary.CustomerID property. Suppose also that in an update of Acumatica ERP, the
Customer ID element of the Customers form was renamed to Customer, and therefore it should be requested by
using the Customer.CustomerSummary.Customer property from the API. The client application requests
the customer ID by using the Customer.CustomerSummary.CustomerID property and fails.

What the Screen-Based API Wrapper Is

The screen-based API wrapper is a special wrapper designed to prevent the UI changes in the system from causing
application failure. The wrapper works with any changes in the schema of an Acumatica ERP form. That is, the
wrapper makes the application work regardless of the changes in the names of UI elements and the changes in the
internal names of data fields and objects.
The wrapper is distributed as the PX.Soap.dll file, which is installed automatically during Acumatica ERP
installation. You can find the PX.Soap.dll file in the ScreenBasedAPIWrapper folder of your Acumatica ERP
installation folder.
The PX.Soap library, which the wrapper provides, includes the Helper.GetSchema() method, which you
should use instead of the Screen.GetSchema() method of the screen-based web services API. For information
on how to use the screen-based API wrapper, see To Use the Screen-Based API Wrapper.

How the Screen-Based API Wrapper Works

When the client application is executed for the first time and requests the schema of an Acumatica ERP form by
using the Helper.GetSchema() method, the wrapper requests the schema from the Acumatica ERP screen-
based web service by using the Screen.GetSchema() method of the screen-based API. The web service
interacts with the Acumatica ERP import and export engine and returns the current schema of the form. The
 Working with the SOAP APIs | 301

wrapper saves the schema in an XML file and returns the schema to the client application as a Content object.
The client application uses this schema to work with Acumatica ERP.

Instead of the Helper.GetSchema() method you can use the

Helper.ReuseStoredSchema() method to upload a schema that was saved earlier by the
wrapper.

The following diagram illustrates the way the screen-based API wrapper works during the first execution of a client
application.

Figure: First execution of an application

When the client application is executed for the second time and all subsequent times and it requests the schema
of an Acumatica ERP form by using the Helper.GetSchema() method, the wrapper retrieves the XML schema
that is saved locally and submits this schema to the Acumatica ERP screen-based web service by using the
Screen.SetSchema() method of the screen-based API. The web service interacts with the Acumatica ERP
import and export engine, which replaces the current schema of the form that is stored on the server with the one
that was saved locally. The wrapper returns the schema that was saved locally to the client application. The client
application uses the local schema to work with Acumatica ERP.

The schema that is submitted to Acumatica ERP by using the screen-based API wrapper is used on the
server during the current session and is discarded aer the end of the session.
 Working with the SOAP APIs | 302

The following diagram illustrates the way the screen-based API wrapper works during the second execution and all
subsequent executions of a client application.

Figure: Subsequent executions of the application

You should distribute the XML file with the schema along with your client application. If the wrapper
has not found the XML file, it requests the new schema.
The name of the XML file with the schema contains a hash code that depends on the WSDL
description. If you update the WSDL description in your application, the wrapper works in the same
way as it did during the first execution of the application and creates a new XML file with the schema.

Related Links
• To Use the Screen-Based API Wrapper

To Generate the WSDL File of the Web Services

The WSDL description of the Acumatica ERP screen-based web services API contains the descriptions of the API
objects and methods that you can use to access Acumatica ERP forms.
Because of the connection of the API with Acumatica ERP forms, each generated WSDL description of this API
reflects the current state of the system. That is, the WSDL description does not include any changes made to the
system aer the WSDL file was generated, and each time you change the system, you should regenerate the WSDL
description and update your application accordingly.
 Working with the SOAP APIs | 303

You can prevent breaking changes in your application and omit regeneration of the WSDL description
for each change in the system by using the screen-based API wrapper. For details on how to use the
wrapper, see To Use the Screen-Based API Wrapper.

For example, suppose that you have generated a WSDL description of the web service that contains the
definition of the CustomerID property, which corresponds to the Customer ID element on the Customers
(AR303000) form. Further, suppose that you changed the name of the Customer ID element to Customer
Identifier in a customization project. To access the Customer Identifier element on the form through the screen-
based web services API, you need to regenerate the WSDL description so that it contains the definition of the
CustomerIdentifier property (which corresponds to the Customer Identifier element) and update your
application accordingly.

For any container (that is, a form, tab, grid, tree, or panel), element, or action with the # or % title,
the generated WSDL file contains NUMBER instead of the # symbol, and PERCENT instead of the %
symbol.

You can generate the WSDL file of an Acumatica ERP web service in one of the following ways.

To Generate a WSDL File for One Acumatica ERP Form

If your application needs to work with only one Acumatica ERP form, you can generate the web service that
provides access to only this form.
To generate a WSDL file for a form, on the title bar of this form, click Tools > Web Service in the UI. This
opens the page that contains the description of the web service, with the following URL: http(s)://
<ApplicationPath>/Soap/<FormID>.asmx. In this URL, <ApplicationPath> is replaced with the
actual URL of your application, and <FormID> is replaced with the ID of the form. For example, suppose that you
generated a web service for the Customers form of the WebServiceAPITest application, which is accessed under
a secure connection and is running on a local computer. The URL of this service is https://localhost/
WebServiceAPITest/Soap/AR303000.asmx.

To Generate a WSDL File for Multiple Acumatica ERP Forms

If your application needs to work with multiple Acumatica ERP forms, you can generate one web service that
provides access to all needed forms.
To generate a WSDL file for multiple forms, on the Web Services (SM207040) form, you should do the following:
1. Type the ID of the web service in the Service ID box of the Summary area of the form. This ID will be used in
the URL of the generated service.
2. Select the Acumatica ERP forms that your application needs to use on the le pane of the form, and click
Add to Grid for each form.
3. Select the types of integration these forms should provide (which can include importing data, exporting
data, and submitting data) by selecting the appropriate check boxes (any combination of Import, Export, or
Submit) for corresponding rows on the right pane of the form.
4. Click Generate.

The functional areas that expose the selected forms should be properly configured and the forms
should open in a web browser. If a form could not be opened in a web browser, the web service
definition will not be generated for this form.

Aer the web service is generated, you can view the WSDL description by clicking View Generated on the form
toolbar. This opens the page that contains the description of the web service with the following URL: http(s)://
<ApplicationPath>/Soap/<ServiceID>.asmx. In this URL, <ApplicationPath> is replaced with
 Working with the SOAP APIs | 304

the actual URL of your application, and <ServiceID> is replaced with the ID of the service that you specified
in the Service ID box when configuring the service. For example, suppose that you generated a web service for
multiple forms with the MYSTORE service ID for the WebServiceAPITest application, which is accessed under
a secure connection and is running on a local computer. The URL of this service is https://localhost/
WebServiceAPITest/Soap/MYSTORE.asmx.

To Import the WSDL File Into the Development Environment

When the WSDL file is generated, you must import it into your development environment to generate proxy classes.
If necessary, see the documentation of your development environment to find out the correct way of building the
proxy classes based on the WSDL definition.
The procedure below is described based on an example of the creation of a console project with the
MyBIIntegrationSBAPI name that uses the MYBIINTEGRATION web service. You can create another type of Visual
Studio project with another name and use any other web service define on the Web Services (SM207040) form in
this procedure.
In this topic, you will find instructions on how to implement the proxy classes by using Visual Studio 2019.

Importing the WSDL File into a Visual Studio Project

To import the WSDL description into your development environment, proceed as follows:
1. Open Visual Studio, and create a new Visual C# console application with the MyBIIntegrationSBAPI name
and the .NET Framework 4.8 target framework.

To create a console application, click File > New > Project on the main menu of Visual
Studio. In the Create a new project dialog box, which appears, select the Console App (.Net
Framework) C# template and click Next. In the Configure your new project dialog box, specify
the name and location of the solution, select the .NET Framework 4.8 framework version, and
click Create.

The MyBIIntegration application that you have created contains the Program.cs file with the Program
class.
2. Add to the project a reference to the Acumatica ERP web service as follows:
a. On the main menu of Visual Studio, click Project > Add Service Reference.
b. In the Add Service Reference dialog box, which appears, click Advanced.
c. In the Service Reference Settings dialog box, which appears, click Add Web Reference.
d. In the URL box of the Add Web Reference dialog box, which appears, specify the URL of the
MYBIINTEGRATION web service (see item 1 in the following screenshot).

To copy the URL of the service, on the Web Services (SM207040) form, select
MYBIINTEGRATION in the Service ID box, click Generate and then View Generated
on the form toolbar, and copy the URL from the address line in the browser for the
page that opens. In this example, the URL is http://localhost/MyStoreInstance/Soap/
MYBIINTEGRATION.asmx.

e. Click Go (2) to make Visual Studio connect to the web service.

If your Acumatica ERP website uses a self-signed certificate, Visual Studio displays security
alert windows with warnings on the certificate. Click Yes in these windows to proceed.
 Working with the SOAP APIs | 305

f. In the Web reference name box, type MyBIIntegration (3). This name will be used as a namespace
for the web service classes generated by Visual Studio based on the WSDL description of the service.
g. Click Add Reference (4) to close the dialog box and add to the project the reference to the specified
service.

Figure: Add Web Reference dialog box

Visual Studio adds to the project the Web References project folder with the MyBIIntegration web
service reference in it, as shown in the following screenshot.

Figure: Solution Explorer

3. Rebuild the project.

To Use the Screen-Based API Wrapper

The screen-based SOAP API depends on the user interface of Acumatica ERP forms. That is, each generated WSDL
description of this API includes the API elements that correspond to the current names of UI elements of the
 Working with the SOAP APIs | 306

system. Therefore, if any changes have been made to the user interface of the system aer the WSDL file was
generated, the WSDL description will not include these changes, and the client application that uses this WSDL will
fail when it works with the system.
To prevent application failures and omit the regeneration of the WSDL description for each change of the user
interface of the system, you can use the screen-based API wrapper, as described in this topic. You can find more
information on the screen-based API wrapper in Screen-Based API Wrapper.

To Use the Screen-Based Web Services API Wrapper in a Client Application

1. Add to your project a reference to PX.Soap.dll.

The PX.Soap.dll file is installed automatically during Acumatica ERP installation. You can
find this file in the ScreenBasedAPIWrapper folder of your Acumatica ERP installation
folder.

2. Use the Helper.GetSchema() method from the PX.Soap library in the code of your application instead
of the corresponding Screen.GetSchema() method to obtain the schema of each form. For example,
the following code retrieves the schema of the Customers (AR303000) form by using the screen-based API
wrapper.

Screen context = new Screen();

context.CookieContainer = new System.Net.CookieContainer();
context.Url = Properties.Settings.Default.MyStoreIntegration_MyStore_Screen;
context.Login
(
Properties.Settings.Default.Login,
Properties.Settings.Default.Password
);

AR303000Content custSchema =
PX.Soap.Helper.GetSchema<AR303000Content>(context);

3. Work with the retrieved Content object by using the standard screen-based web services API methods.

Related Links
• Screen-Based API Wrapper
• To Update a Client Application that Uses Screen-Based Web Services

Working with Commands of the Screen-Based SOAP API

To upload data to and from Acumatica ERP by using the screen-based SOAP API, you should define the sequence
of commands for the system as it works with elements on an Acumatica ERP form. This sequence of commands
reflects the sequence of actions to be executed for a data record as if the record is being manipulated by a user
through an Acumatica ERP form.

Commands for Retrieving the Values of Elements

You configure the sequence of commands that should be executed during data import, data export, or data
processing through the web service by using an array of objects of the Command type.
 Working with the SOAP APIs | 307

As you specify this sequence of commands, when you need to reflect obtaining the value of an element on a form,
you should use a Field object. To specify the element whose value you need to obtain, you can do one of the
following:
• Select the needed Field object from the subobjects of the Field type of a Content object that
corresponds to the needed Acumatica ERP form
• Create an object of the Field type and specify its properties
Both of these ways are described in detail in the following sections of this topic.

Selection of the Fields Available in a Content Object

If you want to obtain the value of an element on an Acumatica ERP form, you can select the needed Field object
from the subobjects of the Field type of the Content object that corresponds to the form. For example, if you
want to export the values of the Inventory ID and Description elements on the Stock Items (IN202500) form, you
can use the following code.

//stockItemsSchema is an IN202500Content object

var commands = new Command[]
{
...
stockItemsSchema.StockItemSummary.InventoryID,
stockItemsSchema.StockItemSummary.Description,
...
};

Field Object Creation

You can retrieve the values of not only the fields that are available on the Acumatica ERP form, but also the data
fields of the data access classes (DACs) underlying the form. Some of these data fields are not available directly
through the elements of the form. That is, you cannot select the needed Field object among the subobjects of the
Content object.
If you want to retrieve the value of an element that is not available on the form, you can create a Field object and
specify its properties so that it specifies the needed data field of the DAC. You should specify the name of the object
that corresponds to the needed DAC as the ObjectName and type the name of the data field in FieldName.
The following code illustrates the creation of a Field object for the LastModifiedDateTime data field
(which specifies the date and time when a record was modified) that is available through the DAC underlying the
StockItemSummary object of the Stock Items form.

To find the names of the data fields that belong to DACs, you should read the applicable Acumatica
ERP code. You can find the source code of Acumatica ERP on the Source Code (SM204570) form or in
<ApplicationFolder>\App_Data\CodeRepository\PX.Objects\, where <ApplicationFolder> is replaced
with the path to the folder of the Acumatica ERP application instance. You can learn the details of
working with the source code of Acumatica ERP in the T300 Acumatica Customization Platform
training course.

//stockItemsSchema is an IN202500Content object

var commands = new Command[]
{
...
new Field
{
ObjectName = stockItemsSchema.StockItemSummary.InventoryID.ObjectName,
FieldName = "LastModifiedDateTime"
},
 Working with the SOAP APIs | 308

...
};

You can create Field objects for the elements that are available on a form. If you want to create
a Field object for an element available on the form, set the ObjectName property to the
ObjectName property of the needed subobject of the Field type of a Content object, and set
the FieldName property to the FieldName property of this Field object. The following code
illustrates the creation of a Field object for the InventoryID field of the Stock Items form.

new Field
{
ObjectName = stockItemsSchema.StockItemSummary.InventoryID.ObjectName,
FieldName = stockItemsSchema.StockItemSummary.InventoryID.FieldName
}

Selection of a Group of Records for Export

Each record in the system is identified by the values of the key elements on the applicable Acumatica ERP form. For
example, a record on the Stock Items (IN202500) form is identified by the value of the Inventory ID key element.
Key elements are available through the Summary object of a form. You can use the key element or elements of the
form to select all records of the form for export. The other way to specify a group of records for export is to use the
elements of the Summary area of the form in custom filters. Both ways of selecting records are described in detail
below.

Export of All Records from a Form

If you want to export every record from an Acumatica ERP form, in the array of Command objects that you pass to
the Export() method, you should insert the service command of the EveryValue type for the corresponding
key element on the form. The EveryValue service command is available through the ServiceCommands
subobject of the Summary object of the Content object that corresponds to the form. This service command
specifies that every record of the specific type should be processed during export.
For example, if you want to export all stock item records available in the system, you should insert the
EveryInventoryID service command, as the following code shows.

//stockItemsSchema is an IN202500Content object

var commands = new Command[]
{
stockItemsSchema.StockItemSummary.ServiceCommands.EveryInventoryID,
...
};

Export of a Group of Records from a Form

You can filter the data available in the Acumatica ERP database to select the records for export. For example, you
can configure the system to export only the records that have a particular status.
To define a filter for the data being exported, you should create an array of Filter objects and add the needed
filters to it. To define a filter, you should specify:
• The UI element whose value should be used for filtering (in the Field property of the Filter object).
• The value or values with which the value of the element should be compared (in the Value property or
Value and Value2 properties of the Filter object).
 Working with the SOAP APIs | 309

• The condition of comparison (in the Condition property of the Filter object).
If you define multiple filters in the array, you should also specify the logical operator (either And or Or) that defines
how to apply these filters. If filters are passed to an Export() method, during export, the system selects only the
records that conform to the specified condition (or conditions) and exports only these records.
For example, suppose that you want to export only the stock item records that have the Active status. In this case,
you can specify the filtering condition that the Item Status element should be equal to Active, as the following code
shows. During export, the system processes the records that match the filtering conditions and exports only the
records with the Active status.

var filters = new Filter[]

{
new Filter
{
Field = stockItemsSchema.StockItemSummary.ItemStatus,
Condition = FilterCondition.Equals,
Value = "Active",
}
};

For filtering records, you can use either the data fields of the Summary object of the form from which you are
exporting data, or the data fields of the data access class (DAC) underlying the Summary object. (In Acumatica
Framework, this DAC is called the main DAC of the primary data view.) If a data field of the DAC is not available
directly through the elements of the Summary object, you cannot select the needed Field object among the
subobjects of a Content object, as the previous code example shows for the ItemStatus data field. Instead,
you should create a new Field object and specify its properties as follows: Specify the name of the Summary
object as ObjectName (that is, the object name that corresponds to the object to which the key data field
belongs), and type the name of the data field as FieldName in the code directly.
The following example shows filtering by the LastModifiedDateTime data field (which specifies the date and
time when a record was modified) that is available through the DAC underlying the StockItemSummary object of
the Stock Items form.

new Filter
{
Field = new Field
{
ObjectName = stockItemsSchema.StockItemSummary.InventoryID.ObjectName,
FieldName = "LastModifiedDateTime"
},
Condition = FilterCondition.Greater,
Value = DateTime.Now.AddMonths(-1).ToLongDateString()
}

Commands for Setting the Values of Elements

As you specify the sequence of commands in an array of Command objects, when you need to specify the value of
an element on a form, you should use Value commands.
To set the value of an element on a form, you should do the following:
1. Create a Value object.
2. Specify the value of the element on the form in the Value property of the created Value object.
 Working with the SOAP APIs | 310

3. Specify the element on the form whose value should be set by using the LinkedCommand property of the
Value object.

The following code illustrates setting the value of the Customer Name element on the Customers (AR303000) form.

//custSchema is an AR303000Content object

var commands = new Command[]
{
...
new Value
{
Value = "John Good",
LinkedCommand = custSchema.CustomerSummary.CustomerName
},
...
}

Commands for Clicking Buttons on a Form

As you specify the sequence of commands in an array of Command objects, when you need to reflect the clicking of
a button on a form (such as clicking Save, Delete, or Release to perform the action on a document), you should use
the corresponding Action command. Actions are available for all buttons on the form.
In an array of Command objects, to use an Action command, you have to select the needed action in the
Actions subobject of the Content object that corresponds to the form. Actions have names that are similar to
the names of the buttons on the form.
The following code reflects the clicking of the Save button on the Customers (AR303000) form in a command.

//custSchema is an AR303000Content object

var commands = new Command[]
{
...
custSchema.Actions.Save,
...
};

Commands for Adding Detail Lines

When you need to add a detail line to an Acumatica ERP form, you can use one of the following approaches:
• Add detail lines one by one on the Details tab of the form. For example, on the Sales Orders (SO301000)
form, you can click Add Row on the Details tab and specify the values of the elements of each detail line.
• Add detail lines by using a pop-up panel. For example, on the Shipments (SO302000) form, you can use
the Add Sales Order pop-up panel, which is opened when you click Add Order on the table toolbar of the
Details tab.
In this topic, you will find the description of the NewRow command, which imitates the first approach listed above
in the screen-based API. The second approach is described in Commands for Pop-Up Panels.
 Working with the SOAP APIs | 311

NewRow Service Command

When you are specifying the sequence of commands in an array of Command objects for a processing method and
you need to add a new detail line to a document, you should use commands as follows:
1. To add a new row, use the NewRow service command, which is an available service command of the Details
subobject of a Content object.
2. To specify the values of the elements of the created row, use the Value commands corresponding to the
elements.

The following code shows an example of an order line being added to a sales order.

//orderSchema is an SO301000Content object

var commands = new Command[]
{
...
orderSchema.DocumentDetails.ServiceCommands.NewRow,
new Value
{
Value = "AALEGO500",
LinkedCommand = orderSchema.DocumentDetails.InventoryID
},
new Value
{
Value = "10.0",
LinkedCommand = orderSchema.DocumentDetails.Quantity
},
new Value
{
Value = firstItemUOM,
LinkedCommand = orderSchema.DocumentDetails.UOM
},
...
}

Commands for Pop-Up Dialog Boxes and Pop-Up Forms

In this topic, you will learn how to enter data to pop-up dialog boxes and pop-up forms by using the screen-based
SOAP API.

Pop-Up Dialog Boxes

When you update specific fields on some forms under certain circumstances, the system displays pop-up dialog
boxes where you need to respond to a question (by clicking a button) in order to proceed. For example, when you
update the Customer Class value on the Customers (AR303000) form for an existing customer, the system displays
a Warning dialog box with the text Please confirm if you want to update current customer settings with the customer
class defaults. Otherwise, original settings will be preserved. and the Yes and No buttons. You should click Yes to
proceed with changing the customer class.
When you are specifying the sequence of commands in an array of Command objects for a processing method and
you need to specify an answer to a question that would appear in a pop-up dialog box if the data was being entered
manually, you should create a Value command and set its properties as follows:
• In the Value property, specify the answer that you select in the dialog box during manual entry of a record.
 Working with the SOAP APIs | 312

• In the LinkedCommand property, use a DialogAnswer service command, which is available through the
ServiceCommands subobject of an object that invokes the appearance of the pop-up dialog box.
You should insert this Value command directly before the field that causes the appearance of the dialog box.
The following code shows how you would update the customer class in an existing customer record on the
Customers form.

//custSchema is an AR303000Content object

var commands = new Command[]
{
...
new Value
{
Value = "Yes",
LinkedCommand = custSchema.CustomerSummary.ServiceCommands.DialogAnswer
},
new Value
{
Value = "INTL",
LinkedCommand = custSchema.GeneralInfoFinancialSettings.CustomerClass
},
...
};

Pop-Up Forms
When you click specific buttons on some forms, the system opens a pop-up window with another Acumatica ERP
form where you can specify or edit the values of elements as needed. For example, if you click Add Contact on the
Contacts tab of the Customers form, the system displays the Contacts (CR302000) form.

Do not confuse a situation when the system opens a pop-up window that contains an Acumatica ERP
form with a situation when the system opens a pop-up panel (where you can specify needed settings
but no Acumatica ERP form is shown). A pop-up window that contains a form has an address line in
the browser where you can see the ID of the form. A pop-up panel looks like a dialog box and does not
have an address line.

When you are specifying a sequence of commands in an array of Command objects for a processing method and
you need to reflect the setting of values of elements of a pop-up form in these commands, you should perform the
following steps:
1. Call an action that invokes a pop-up form as follows:
a. By using the GetSchema() method of the PX.Soap.Helper class, get the Content object that
corresponds to the form that invokes a pop-up form.
b. Specify the command that invokes a pop-up form in the sequence of commands by using the
corresponding Action command.
c. Submit this sequence of commands to the form that invokes the pop-up form by using the
corresponding Submit() method.
2. Specify the values on the pop-up form as follows:
a. By using the GetSchema() method of the PX.Soap.Helper class, get the Content object that
corresponds to the form that appears as a pop-up.
b. Specify the list of commands that specifies the values of needed elements of the pop-up form.
c. Add the Save action to the list of commands.
 Working with the SOAP APIs | 313

d. Submit this sequence of commands to the pop-up form by using the corresponding Submit() method.

The following code illustrates the setting of the values of the Contacts form, which appears as a pop-up aer the
user clicks Add Contact on the Contacts tab of the Customers form.

//context is a Screen object

//custSchema is an AR303000Content object
var commands = new Command[]
{
new Value
{
Value = customerID,
LinkedCommand = custSchema.CustomerSummary.CustomerID
},

custSchema.Actions.NewContact
};
context.AR303000Submit(commands);

//contSchema is a CR302000Content object

commands = new Command[]
{
new Value
{
Value = "Green",
LinkedCommand = contSchema.DetailsSummary.LastName
},
contSchema.Actions.Save,
};
context.CR302000Submit(commands);

Commands for Pop-Up Panels

In some instances, when you click a specific button on some form, the system opens a pop-up panel, where you can
set the values of needed elements. This pop-up panel looks like a dialog box and does not contain an Acumatica
ERP form. For example, if you click Add Order on the table toolbar of the Details tab of the Shipments (SO302000)
form, the system displays the Add Sales Order pop-up panel.

Do not confuse a situation when the system opens a pop-up panel (where you can set needed settings
but no Acumatica ERP form is shown) with a situation when the system opens a pop-up window that
contains an Acumatica ERP form. A pop-up window that contains a form has an address line in the
browser where you can see the ID of the form. A pop-up panel looks like a dialog box and does not
have an address line.

When you are specifying a sequence of commands in an array of Command objects for a processing method and
you need to reflect the setting of values of elements on a pop-up panel in these commands, you should perform the
following steps:
1. Insert the DialogAnswer service command of the pop-up panel object before the action that opens the
panel, and set the Commit property to true for this command.
2. Specify the action that opens the pop-up panel, and set the Commit property of the action to true.
3. Specify the values of elements as needed on the pop-up panel.
4. Specify the action that closes the panel, and set the Commit property of the action to true.
 Working with the SOAP APIs | 314

For some pop-up panels, you need to specify only one action to select values from the pop-up
panel. For example, you need to specify only one action if you are creating a shipment by using
the Create Shipment action on the Sales Orders (SO301000) form, which displays the Specify
Shipment Parameters pop-up panel.

The following code illustrates the setting of the values on the Add Sales Order pop-up panel, which appears aer a
user clicks Add Order on the toolbar of the Details tab of the Shipments form.

//shipmentSchema is a SO302000Content object

//Force a commit for the SelectSO action
var selectSOwithCommit = shipmentSchema.Actions.SelectSO;
selectSOwithCommit.Commit = true;

//Force a commit for the AddSO action

var addSOwithCommit = shipmentSchema.Actions.AddSO;
addSOwithCommit.Commit = true;

//Configure the list of commands

var commands = new Command[]
{
...
//Open the Add Sales Order panel
new Value
{
Value = "OK",
LinkedCommand =
shipmentSchema.AddSalesOrderOperation.ServiceCommands.DialogAnswer,
Commit = true
},
selectSOwithCommit,

//Specify the first order number on the Add Sales Order panel
//and get the values of item elements
new Value
{
Value = firstOrderNbr,
LinkedCommand = shipmentSchema.AddSalesOrderOperation.OrderNbr
},
new Value
{
Value = "True",
LinkedCommand = shipmentSchema.AddSalesOrder.Selected
},
shipmentSchema.AddSalesOrder.InventoryID,
shipmentSchema.AddSalesOrder.Quantity,
shipmentSchema.AddSalesOrder.OpenQty,
shipmentSchema.AddSalesOrder.LineDescription,
};
//context is a Screen object
//Submit the commands to the form
var soLines = context.SO302000Submit(commands);

//Select all items of the first order for shipment

List<Command> commandList = new List<Command>();
for (int index = 0; index < soLines.Length; index++)
{
 Working with the SOAP APIs | 315

commandList.Add(new Value
{
Value = index.ToString(),
LinkedCommand = shipmentSchema.AddSalesOrder.ServiceCommands.RowNumber
});
commandList.Add(new Value
{
Value = "True",
LinkedCommand = shipmentSchema.AddSalesOrder.Selected,
Commit = index < soLines.Length - 1
});
}

//Add items to the shipment

commandList.Add(addSOwithCommit);
context.SO302000Submit(commandList.ToArray());

Commands for Record Searching: Filter Service Command

The system uses the key element or elements on a form to find records that belong to different documents. For
example, on the Invoices and Memos (AR301000) form, there are two key elements: Type and Reference Nbr.
If you know the values of the key element or elements of the needed record, you can select this record for update
by specifying the key values in the sequence of commands that you pass to the processing method of the web
services API. In the sequence of commands, you should first specify key element or elements to identify the record
that you are going to update. Aer you have specified the values of key element or elements, you should specify the
values of other elements in the order in which you would specify them on the form.
If you do not know the values of the key element or elements of the needed record, you can update records in
the system by searching for them using their unique field values that you know. For example, you can identify
customers by email addresses or phone numbers. To search for a record, you have to imitate the use of a column
of a Select dialog box, declare a custom key, or declare a custom field in the sequence of commands that you pass
to a processing method. In this topic, you will find a detailed description of the Filter service command, which
imitates the use of a selector column. You can find a description of two other approaches in Commands for Record
Searching: Key Command and Commands for Record Searching: Custom Field.

Filter Service Command

Selector columns on an Acumatica ERP form appear when a user clicks the Magnifier icon of the key element of
the form to bring up the Select dialog box. Service commands for selector columns have the Filter prefix in
their names. For example, to search for a customer record, you can use the FilterCity, FilterCountry,
FilterEmail, and FilterPhone1 service commands.
To use a column of a Select dialog box for a search, you have to do the following:
1. Create a Field object, and initialize its properties with the values of the properties of the key field.
2. Concatenate the FieldName property of this object (which is now equal to the value of the FieldName
property of the key field) with ! and the FieldName property of the needed Filter service command.
3. In the Value command in the array of Command objects, set the Value property to the value that should
be used for the search and the LinkedCommand property to the created Field object.

For example, the following code searches for a customer record by email address.

//custSchema is an AR303000Content object

Field customerIDSelector = custSchema.CustomerSummary.CustomerID;
customerIDSelector.FieldName += "!" +
 Working with the SOAP APIs | 316

custSchema.CustomerSummary.ServiceCommands.FilterEmail.FieldName;

var commands = new Command[]

{
new Value
{
Value = "[email protected]",
LinkedCommand = customerIDSelector
},
...
};
 Working with the SOAP APIs | 317

If you need to get the value of the field that was used for a search as a result of the processing,
you should assign an initial FieldName to the field before getting the value. For example, the
following code shows how to get the value of the Customer ID element aer you have modified the
corresponding field for the search.

//custSchema is an AR303000Content object

//Save the initial field name of the CustomerID field
string initialCustomerIDFieldName =
custSchema.CustomerSummary.CustomerID.FieldName;

//Configure the command that searches for a customer record

//by using the FilterEmail service command
Field customerIDSelector = custSchema.CustomerSummary.CustomerID;
customerIDSelector.FieldName += "!" +
custSchema.CustomerSummary.ServiceCommands.FilterEmail.FieldName;

//Configure the list of commands

var commands = new Command[]
{
//Search for the needed customer record
new Value
{
Value = customerMainContactEmail,
LinkedCommand = customerIDSelector
},

//Do the needed modifications and save changes on the form

...
};

//context is a Screen object

//Submit commands to the form
context.AR303000Submit(commands);

//Assign an initial field name to the CustomerID field

custSchema.CustomerSummary.CustomerID.FieldName = initialCustomerIDFieldName;

//Get the customer ID

commands = new Command[]
{
custSchema.CustomerSummary.CustomerID
};

//Submit commands to the form

AR303000Content customer = context.AR303000Submit(commands)[0];

Commands for Record Searching: Key Command

To search for a record, you have to imitate the use of a column of a Select dialog box, declare a custom key, or
declare a custom field in the sequence of commands that you pass to a processing method. In this topic, you will
find a detailed description of the use of the Key command, which you use to declare a custom key. You can find
descriptions of two other approaches in Commands for Record Searching: Filter Service Command and Commands
for Record Searching: Custom Field.
 Working with the SOAP APIs | 318

Key Command
If you specify the value of key elements on an Acumatica ERP form, the system does not change the current record
in the system; instead, it searches for the record, which is identified by the values of the key elements, and selects
this record. By using custom keys, you can make some elements on an Acumatica ERP form work as key elements.
You can specify custom keys to search for a record or a detail line. You can use the fields of the summary
object and the detail objects, but not the fields that belong to other objects, as custom key fields. For
example, you can find the needed customer record in the system by using the CustomerName field of the
AR303000CustomerSummary object of the Customers (AR303000) form as the custom key, but you cannot find
the record by using the Email field of the AR303000GeneralInfoMainContact object as the custom key.
To specify a custom key, you have to define the key by using the Key command as follows:
1. Create a Key command by using the operator new.
2. To specify the element that should be used as a custom key, set the ObjectName and FieldName
properties of the created Key command to the values of the ObjectName and FieldName properties of
the field corresponding to the element.
3. To specify the value of the custom key, set the Value property of the created Key command to the needed
value in the format ='<Key value>', where you should replace <Key value> with the needed value of
the key.

Below is an example of the Key command that declares the Warehouse column as the custom key on the
Document Details tab of the Sales Orders (SO301000) form.

new Key
{
ObjectName = orderSchema.DocumentDetails.Warehouse.ObjectName,
FieldName = orderSchema.DocumentDetails.Warehouse.FieldName,
Value = "='MAIN'"
},

Commands for Record Searching: Custom Field

To search for a record, you have to imitate the use of a column of a Select dialog box, declare a custom key, or
declare a custom field in the sequence of commands that you pass to a processing method. In this topic, you will
find a detailed description of the declaration of a custom field. You can find descriptions of two other approaches in
Commands for Record Searching: Filter Service Command and Commands for Record Searching: Key Command.

Custom Field
Acumatica ERP does not include Filter service commands for all selector columns that are available on
Acumatica ERP forms. To use the needed selector column for record searching, you can create a custom field as
follows:
1. Initialize the properties of a Field object with the values of the properties of the key field.
2. Concatenate the FieldName property of this object (which is now equal to the value of the FieldName
property of the key field) with ! and the internal name of the selector column that you are going to use for
the search. The internal name of the selector column is equal to the value of the FieldName property of
the corresponding element on the form.
3. In the Value command in the array of Command objects, set the Value property to the value that should
be used for the search and the LinkedCommand property to the created Field object.
 Working with the SOAP APIs | 319

For example, the following code searches for a sales order by order number.

//orderSchema is an SO301000Content object

var searchCustomerOrder = orderSchema.OrderSummary.OrderNbr;
searchCustomerOrder.FieldName +=
"!" + orderSchema.OrderSummary.CustomerOrder.FieldName;

var commands = new Command[]

{
new Value
{
Value = "SO",
LinkedCommand = orderSchema.OrderSummary.OrderType
},
new Value
{
Value = "SO248-563-06",
LinkedCommand = searchCustomerOrder
},
...
}

Commands That Require a Commit

There are two types of elements on an Acumatica ERP form: elements with a commit, and elements without a
commit. A commit is an action initiated by the form that, when triggered, sends the data to the server. On the
server, the commit causes all data on the form to be updated, including the insertion of default values and the
recalculation of the values of elements on the form.
A commit is a costly operation that causes the browser to make requests to the server and takes server time. As
such, a commit is invoked for only a limited number of elements: mainly the key elements and the elements the
other elements depend on.
In a Visual Studio project, if you specify the value of an element for which the system performs a commit by using
a Value command, the Commit property of the LinkedCommand property (which specifies this element)
is automatically set to true. You can check the value of the Commit property when you are debugging an
application if you insert a breakpoint in the code aer an array of commands has been configured. In the following
screenshot, you can see that for the command that sets the value of the Customer ID element on the Customers
(AR303000) form, the Commit property of the LinkedCommand is set to true. (The Customer ID element has the
internal field name AcctCD.)
 Working with the SOAP APIs | 320

Figure: Commit property

If the Commit property is false, the element is filled in with data but no update of the form is invoked. If the
Commit property is true, aer the element is filled in, the commit is invoked on the server and the form is
updated.
For example, when you select a customer class on the Customers form, the system assigns values to the elements
related to customer class settings, such as Statement Cycle ID and Country. When you configure a sequence of
commands for setting the values of elements on the Customers form, for elements such as Customer, the system
automatically sets the Commit property of LinkedCommand to true.
In most cases, when you compose the sequence of commands, you can use the values of the Commit property
that are set by default. However, you may need to force the system to invoke a commit to the server—for example,
when you need to commit the value of the field before entering another field value. In such cases, you should set
the Commit property to true for the command or action.

Commands for Working with Attachments

In Acumatica ERP, you can attach files to records on Acumatica ERP forms and to detail lines on master-detail
forms.
To obtain a file attached to the selected record or detail line through the web services API, you specify the Value
command in the array of Command objects as follows:
• In the FieldName property, you specify the name of the file that should be obtained.
• In the LinkedCommand property, you specify the needed Attachment service command.
To work with a file attached to a form, you use the Attachment service command of the object
that corresponds to the Summary object. For example, to obtain a file attached to a stock item
record on the Stock Items (IN202500) form, you use the Attachment service command of the
IN202500StockItemSummary object.
To work with the file attached to a detail line of a master-detail form, you use the Attachment service
command of the object that corresponds to the Details object. For example, to obtain the file attached to a
warehouse detail line of a stock item on the Stock Items form, you use the Attachment service command
of the IN202500WarehouseDetails object.
 Working with the SOAP APIs | 321

The following code shows how to retrieve the file attached to a stock item record on the Stock Items form.

//stockItemsSchema is an IN202500Content object

var commands = new Command[]
{
new Value
{
Value = "AAMACHINE1",
LinkedCommand = stockItemSchema.StockItemSummary.InventoryID
},
new Value
{
FieldName = "T2MCRO.jpg",
LinkedCommand =
stockItemSchema.StockItemSummary.ServiceCommands.Attachment
}
};
//context is a Screen object
var stockItemAttachment =
context.IN202500Export(commands, null, 1, false, true);

Commands for Working with Multi-Language Fields

For some text boxes on Acumatica ERP forms, users can type values in multiple languages if multiple locales
are configured in Acumatica ERP. For example, if your Acumatica ERP instance has English and French locales
activated and multilingual user input configured, you can specify the value of the Description box on the Stock
Items (IN202500) form in English and French. For the list of elements that support multiple languages, see Boxes
that Have Multi-Language Support. For details on how to turn on multilingual user input, see Enabling Multilingual
User Input.

Specifying Localized Values of a Multi-Language Field

When you need to specify localized values of a text box by using the screen-based SOAP API, you specify the value
of the field that corresponds to the box as a string in JSON format with the localized values. In this string, you use
the two-letter ISO code of the language with which the value should be associated.
In the example that is mentioned at the beginning of the topic, if you need to specify values in English and French in
the Description box on the Stock Items form, you specify the value of the Description field of the StockItem
entity in the following format: [{en:English description},{fr:French description}], as shown
in the following code fragment.

//stockItemSchema is an IN202500Content object

new Value
{
Value = "[{en:Item},{fr:Pièce}]",
LinkedCommand = stockItemSchema.StockItemSummary.Description
}
 Working with the SOAP APIs | 322

In the JSON-formatted string, you should specify the actual values of the field in all languages that
are configured for multilingual user input. If you specify the values of the field in particular languages,
the values of the field in other languages configured for multilingual user input become empty. For
example, suppose that in your instance of Acumatica ERP, multi-language fields can have values
in English and French. If you pass the value of a field in the following format [{en:English
description}], the French value of the field becomes empty.

If you specify the value of a multi-language field as plain text, this text is saved as the value of the corresponding
box in the current language of Acumatica ERP (that is, either the default language of the instance or the language
that you have specified by using the SetLocaleName() method). For details on how to specify the locale
through the screen-based SOAP API, see SetLocaleName() Method.

Retrieving Localized Values of a Multi-Language Field

If you need to retrieve localized values of a text box that supports multiple input languages, you retrieve the value
of an internal field that contains all localized values of the text box and has the Translations suffix in its field name.
To specify the field name and the object name of the needed internal field with localized values, you specify
the field name and the object name of the multi-language text box and append Translations to the field name.
For example, the following code shows the command that you should use to retrieve the localized values of the
Description element of the Stock Items form.

//stockItemSchema is an IN202500Content object

new Field
{
ObjectName = stockItemsSchema.StockItemSummary.Description.ObjectName,
FieldName = stockItemsSchema.StockItemSummary.Description.FieldName +
"Translations"
}

The returned value of a Translations field is a string in JSON format with the available localized values of the
field. The language to which the value belongs is identified by the two-letter ISO code of the language. For example,
suppose that the Description element of the Stock Items form has the value Item in English and Pièce in French.
In this case, the value of the DescrTranslations field, which corresponds to the Description element, is the
following string: [{en:Item},{fr:Pièce}].
Related Links
• Locales and Languages
• Boxes that Have Multi-Language Support

Screen-Based SOAP API Reference

In this chapter, you will find the reference information for the main methods of the screen-based web services API;
these methods are used to transfer data to and from Acumatica ERP.
This chapter covers the following objects, and the following methods, which are exposed by the Screen class:
• Login() Method
• Logout() Method
• SetLocaleName() Method
• SetBusinessDate() Method
• GetScenario() Method
• GetSchema() Method
 Working with the SOAP APIs | 323

• SetSchema() Method
• Export() Method
• Submit() Method
• Import() Method
• Clear() Method
• GetProcessStatus() Method

Login() Method

You use the Login() method to make the client application sign in to Acumatica ERP.

Instead of directly signing in to Acumatica ERP, your application can use the OAuth 2.0 authorization.
For details about OAuth 2.0, see Authorizing Client Applications to Work with Acumatica ERP.

Syntax

public LoginResult Login(string name, string password)

Parameters
• name: The username that the application should use to sign in to Acumatica ERP, such as "admin".
To sign in to a specific Acumatica ERP tenant, specify the name parameter as follows:
UserName@TenantName, where you should specify the username instead of UserName and the tenant
name instead of TenantName. For example, if you sign in to the tenant with the name Dollar as the user
with the name admin, you should specify the parameter as admin@Dollar. You can view the name that
should be used for the tenant in the Login Name box of the Tenants (SM203520) form.
To sign in to a certain branch in the tenant, specify the parameter as follows:
UserName@TenantName:BranchName, where you should specify the username instead of UserName,
the tenant name instead of TenantName, and the branch ID instead of BranchName. You can view the
ID of the branch in the Branch ID box of the Branches (CS102000) form. For example, if you sign in to the
East branch of the Dollar tenant as the user with the name admin, you should specify the parameter as
admin@Dollar:East.
• password: The password for the username, such as "123".

Return Value
The method returns the LoginResult object, which contains the description of errors that occurred during
signing in, if any.

Example
The following code signs in to Acumatica ERP by using the parameters that are specified in the application settings.

Screen context = new Screen();

context.CookieContainer = new System.Net.CookieContainer();
context.Url = "https://localhost/WebServiceAPITest/Soap/MYSTORE.asmx";
context.Login("admin@MyTenant:MYSTORE", "123");
 Working with the SOAP APIs | 324

Usage Notes
Before you sign in to Acumatica ERP by using the Login() method, do the following:
1. Initialize the CookieContainer property of the object with a new
System.Net.CookieContainer(). The CookieContainer property is a standard property
of an object of the HttpWebClientProtocol system type. (The Screen class is derived from the
HttpWebClientProtocol class.) This property is used to maintain the session state for a client.
2. Specify the URL of the web service in the URL property of the object. This is the same URL that you specify
when you add a web reference to the Acumatica ERP web service. You can change the URL of the service
dynamically in your application if you need to switch between multiple Acumatica ERP web services.

For each call of the Login() method, you must call the Logout() method aer you finish your work with
Acumatica ERP to close the session. Therefore, when you are working with the web services API, we recommend
that you use the pattern that is shown in the following code.

using
(
//Connect to the web services and log in to Acumatica ERP
Screen context = new Screen();
...
)
{
try
{
//Import, export, or submit data
...
}
finally
{
//Log out from Acumatica ERP
context.Logout();
}
}

You should take into account Acumatica ERP license API limits when using the Login() method. For details, see
License Restrictions for API Users.

Logout() Method

You use the Logout() method to make the client application sign out from Acumatica ERP.

Syntax

public void Logout()

Usage Notes
For each call of the Login() method, you must call the Logout() method aer you finish your work with
Acumatica ERP to close the session. Therefore, when you are working with the web services API, we recommend
that you use the pattern that is shown in the following code.

using
 Working with the SOAP APIs | 325

(
//Connect to the web services and sign in to Acumatica ERP
Screen context = new Screen();
...
)
{
try
{
//Import, export, or submit data
...
}
finally
{
//Sign out from Acumatica ERP
context.Logout();
}
}

SetLocaleName() Method

You use the SetLocaleName() method to specify the locale for Acumatica ERP to correctly recognize the
format of dates, numbers, and other country-specific data that is passed by using the web services API. By default,
Acumatica ERP uses the invariant locale, which is similar to the English (United States) locale.

Syntax

public void SetLocaleName(string localeName)

Parameter
• localeName: The locale that should be used in Acumatica ERP. You should specify the locale in the
System.Globalization.CultureInfo format converted to string, such as "EN-US".

Example
The following code shows how to specify the appropriate locale with the SetLocaleName() method of the
Screen object.

...
using System.Threading;
...
Screen context = new Screen();
context.SetLocaleName(Thread.CurrentThread.CurrentCulture.ToString());

SetBusinessDate() Method

You use the SetBusinessDate() method to specify the business date in Acumatica ERP. You can set the
business date to any date to make the system insert this date into the date fields by default. The business date is
inserted into any new document that you create and is used in the default selection parameters that appear on
processing and inquiry screens.
 Working with the SOAP APIs | 326

Syntax

public void SetBusinessDate(System.DateTime businessDate)

Parameter
• businessDate: The business date that should be used in Acumatica ERP.

Usage Notes
The business date resets to the current date of your computer aer each login. Therefore, if you need to specify a
business date in your application, you should call the SetBusinessDate() method aer each client application
login.

GetScenario() Method

You use the GetScenario() method to retrieve the list of commands of an integration scenario that is
configured in the system.

Syntax

public Command[] GetScenario(string scenario)

Parameter
• scenario: The name of the import or export scenario for which the list of commands should be retrieved.

Return Value
The method returns the list of commands of the specified integration scenario.

GetSchema() Method

You use the GetSchema() method of the Screen object to get the description of the structure (schema) of
a form. This method is specific for each Acumatica ERP form, and you should use the method with the ID of the
needed form in the prefix of the method name.

To prevent application failures because of UI changes in Acumatica ERP, you can use the
GetSchema() method of the screen-based API wrapper instead of the GetSchema() method of
the Screen object. For more information on the screen-based API wrapper, see Screen-Based API
Wrapper.

Syntax

public Content GetSchema()

 Working with the SOAP APIs | 327

Return Value
The method returns the schema of the form as the corresponding Content object, which is specific for each form.

Example
To get the schema of the Stock Items (IN202500) form, you should call the IN202500GetSchema() method of
the Screen object. You will receive the result as a IN202500Content object, as the following code shows.

Screen context = new Screen();

...
IN202500Content stockItemsSchema = context.IN202500GetSchema();

SetSchema() Method

You use the SetSchema() method of the Screen object to change the description of the structure (schema) of a
form to the one specified in the method. This method is useful when you need to work with the description of the
form that was used in previous versions of Acumatica ERP. This method is specific for each Acumatica ERP form,
and you should use the method with the ID of the needed form in the prefix of the method name.

Syntax

public void SetSchema(Content schema)

Parameter
• schema: The schema of an Acumatica ERP form.

Export() Method

You use the proper Export() method of a Screen object to export data from Acumatica ERP. You select the
needed Export() method by using in the name of the method the prefix that contains the ID of the Acumatica
ERP form from which the method exports data.

Syntax

public string[][] Export(

Command[] commands,
Filter[] filters,
int topCount,
bool includeHeaders,
bool breakOnError
)
 Working with the SOAP APIs | 328

Parameters
• commands: In this parameter, you specify the UI elements of the Acumatica ERP form whose values you
need to export. In the array of commands that you pass to the commands parameter, you can also use the
EveryValue service command, which makes the system export all records of the specific type.
• filters: In this parameter, you specify any restrictions on the data to be exported. For example, you can
configure the system to export only the records that have a particular status.
• topCount: In this parameter, you can restrict the number of records to be exported. If this parameter is set
to 0, the system exports all records that are specified by the commands and filters parameters of the
Export() method.
• includeHeaders: In this parameter, you specify whether the result of the export should include column
headers. If this parameter is set to true, the result of the export includes the names of exported elements
in the first row of the exported data.
• breakOnError: In this parameter, you specify whether the system should stop the export if an error
occurs during this process. If this parameter is set to true, the system stops exporting data when the first
error occurs during the export.

Return Value
The result of the data export is a two-dimensional string array, which represents the exported data in a table
format. Thus, if an exported record contains detail lines, the values of the detail lines are translated to multiple
rows of this table. The number of rows is equal to the number of detail lines of the source record. The table rows
that belong to one record have the same values of the elements of the summary area specified.
For example, suppose that on the Invoices (SO303000) form, an invoice has three detail lines. If you export this
invoice with detail lines, the data prepared for export will include three records for this invoice—one record for each
detail line. These records will include identical values of the elements in the summary area of the invoice, such as
the type and reference number, and different values of the detail line elements.

Submit() Method

You use the proper Submit() method of a Screen object to submit data to Acumatica ERP. You select the
needed Submit() method by using in the name of the method the prefix that contains the ID of the Acumatica
ERP form with which the method works.

Syntax

public Content[] Submit(Command[] commands)

Parameter
• commands: You use this parameter to specify the data that you are going to submit. In this parameter,
you pass to the web service an array of Command objects in which you can specify commands that do the
following:
• Set the values of elements on the form by using Value commands.
• Click buttons on the form (for example, the Save button) by using Action commands.
• Get the result of data processing by using Field commands.
 Working with the SOAP APIs | 329

Return value
The result of processing of the data submitted by using the Submit() method is returned as a Content object
specific to the form to which the data has been submitted. This object contains the values of the elements that you
specified by using Field commands in the array of Command objects, which you pass to the Submit() method.
The values of the elements that were not specified by using Field commands are null.
If you want only to submit data to an Acumatica ERP form and do not need to obtain any values of elements
aer submitting, do not specify any Field commands in the array of the Command object that you pass to a
Submit() method. In this case, the Submit() method does not return any value.

Example 1: Submitting Data and Obtaining the Result of Processing

Suppose that you want to submit a customer record to the Customers (AR303000) form and obtain as a
result of processing the values of the Customer Name and Customer Class elements. You pass the list of
commands, which includes Field commands for the CustomerName and CustomerClass fields, to the
AR303000Submit() method, as the following code shows. In this example, the AR303000Submit() method
returns a AR303000Content object that has non-null values of the CustomerName and CustomerClass
fields. The values of the other elements of the returned AR303000Content object are null.

AR303000Content custSchema = context.AR303000GetSchema();

var commands = new Command[]
{
...
custSchema.Actions.Save,
custSchema.CustomerSummary.CustomerName,
custSchema.GeneralInfoFinancialSettings.CustomerClass
};
AR303000Content customer = context.AR303000Submit(commands)[0];

Example 2: Submitting Data without Obtaining the Result of Processing

Suppose that you want to create a customer record on the Customers form and do not need to get the values of any
element on the form aer the customer record is created. You pass the list of commands, which sets the needed
values and saves the changes on the form (the list of commands does not include any Field commands), to the
AR303000Submit() method, as the following code shows. In this example, the AR303000Submit() method
does not return any value.

AR303000Content custSchema = context.AR303000GetSchema();

var commands = new Command[]
{
new Value
{
...
},
custSchema.Actions.Save
};
context.AR303000Submit(commands);
 Working with the SOAP APIs | 330

Import() Method

To import data to Acumatica ERP by using the web services API, you should use the proper Import() method
of a Screen object. You select the needed Import() method by using in the name of the method a prefix that
contains the ID of the Acumatica ERP form to which the method imports data.

Syntax

public ImportResults[] Import(

Command[] commands,
Filter[] filters,
string[][] data,
bool includedHeaders,
bool breakOnError,
bool breakOnIncorrectTarget
)

Parameters
• commands: In this parameter, you specify the UI elements of the Acumatica ERP form to which you need to
import data by using Field commands. You can click buttons on the form (for example, the Save button)
by using Action commands.
• filters: In this parameter, you specify any restrictions on the data to be imported. For example, you can
configure the system to import only the records that have the CUST prefix in the customer ID field.
• data: In this parameter, you specify the data that should be imported in a two-dimensional string
array. Each row of the array should contain the values of the fields in the order that you specified in the
commands parameter.
• includeHeaders: In this parameter, you specify whether the imported data include column headers.
If this parameter is set to true, this signals to the system that the data, which is imported, includes the
names of the imported elements in the first row.
• breakOnError: In this parameter, you specify whether the system should stop the data import if an error
occurs during this process. If this parameter is set to true, the system stops importing data when the first
error occurs during the import.
• breakOnIncorrectTarget: In this parameter, you specify whether the system should stop the data
import if the record does not meet the condition specified for the imported record. If this parameter is set to
true, the system stops processing records and displays an error.

Return Value
The result of the processing of the data imported by using the Import() method is returned as a
ImportResults object specific to the form to which the data has been imported. This object contains the result
of the processing.

Clear() Method

You use the Clear() method to clear all changes on the form. The method works in the same way as the Cancel
button on the toolbar of an Acumatica ERP form does. This method is specific to the particular Acumatica ERP
form, and you should use the method with the ID of the needed form in the prefix of the method name.
 Working with the SOAP APIs | 331

Syntax

public void Clear()

GetProcessStatus() Method

You use the GetProcessStatus() method to monitor the status of a long-running operation (such as the
release or confirmation operation).

Syntax

public ProcessResult GetProcessStatus()

Return Value
The method returns a ProcessResult object. You should use the Status property of this object to get the
status of the processing operation. When the status of the operation is Completed, you can get the result of
processing.