Retrieving Acumatica ERP Data in the OData Version 4.0 Interface

In the OData Version 3.0 interface, you can request data from generic inquiries that are configured in MYOB Acumatica. In the OData interface based on the OData Version 4.0 protocol, you can request data from MYOB Acumatica by directly accessing DACs without configuring any generic inquiry.

Tip:
Password fields are retrieved encrypted.

Retrieval of the Full Set of Metadata of the Instance

You can use the following request to get the metadata of the MYOB Acumatica instance, which includes the following:

  • The full list of DACs
  • The fields of the DACs
  • The fields' types
  • The navigation properties of DACs, which represent the relationships between the DACs
GET https://<Acumatica ERP instance URL>/odatav4/<tenant>/$metadata
Tip:
In this URL and other URLs presented in this topic, the tenant can be omitted if the MYOB Acumatica instance has only one tenant.

The navigation properties contain detail entities in the <detail_entity_type>Collection format and related entities in the <related_entity_type>By<master_entity_field> format. For example, the definition of the PX.Objects.SO.SOOrder DAC has the SOLineCollection navigation property, which states that the PX.Objects.SO.SOLine DAC is a detail entity. The definition of the PX.Objects.SO.SOOrder DAC also has the BAccountByCustomerID navigation property, which links the CustomerID field of the PX.Objects.SO.SOOrder DAC with the BAccountID field of the PX.Objects.CR.BAccount DAC.

Retrieval of All Records of a DAC

You can use the following request to get all records of a DAC.
GET https://<Acumatica ERP instance URL>/odatav4/<tenant>/<DAC>
In this URL, the DAC is specified by its fully qualified name, by its display name, or by its short name (which does not include the namespace). For example, the use of either of the following URLs leads to the same result of receiving the contents of the SOOrder entity:
  • https://localhost/AcumaticaERP/odatav4/SOOrder
  • https://localhost/AcumaticaERP/odatav4/PX_Objects_SO_SOOrder

Retrieval of a Record by the Key Fields

You can retrieve a record with certain values of key fields by specifying these fields and their values in the URL.

The following sample request retrieves the sales order whose OrderType field value is SO and whose OrderNbr field value is 000058. 
GET https://localhost/AcumaticaERP/odatav4/SOOrder(OrderType='SO',OrderNbr='000058')

Specification of a Filter

You can obtain the records that meet a particular filter’s criteria by specifying this filter in the URL in the $filter parameter.

The following sample URL retrieves the sales orders whose OrderType field value is IN. 
GET https://localhost/AcumaticaERP/odatav4/SOOrder?
$filter=(OrderType eq 'IN')
Attention:
You cannot sort and filter by the fields that were calculated using a formula in the source generic inquiry.

Retrieval of Related Data

If a master entity has a detail entity, you can obtain the records of the master entity, along with their details, in a single query by using the $expand parameter.

The following sample request retrieves sales orders along with their detail information. 
GET https://localhost/AcumaticaERP/odatav4/SOOrder?
$filter=(OrderType eq 'IN')&
$expand=SOLineCollection
The following sample request retrieves sales orders along with their customers’ information. 
GET https://localhost/AcumaticaERP/odatav4/SOOrder?
$filter=(OrderType eq 'IN')&
$expand=BAccountByCustomerID

Specification of Particular Fields in a Response

In a request, you can specify the DAC fields that you want the response to contain. You do this by specifying the desired fields in the $select parameter.

The following sample request retrieves customers and provides the AcctCD, AcctName, and CustomerClassID fields in the response. 
GET https://localhost/AcumaticaERP/odatav4/PX_Objects_AR_Customer?
$select=AcctCD,AcctName,CustomerClassID

To list the fields of the detail entities, you use the following format of the request:

  • In the $expand parameter, you specify the nested entity as the navigation property.
  • After the property, in parentheses, you specify the DAC fields as the values of the $select parameter.
The following sample URL retrieves customers along with the default addresses. 
GET https://localhost/AcumaticaERP/odatav4/PX_Objects_AR_Customer?
$select=AcctCD,AcctName,CustomerClassID&
$expand=AddressByDefAddressID(
$select=AddressLine1,AddressLine2,City,State,PostalCode)
The response includes the customers' AcctCD, AcctName, and CustomerClassID fields and the addresses' AddressLine1, AddressLine2, City, State, and PostalCode fields.

Retrieval of Records in Batches

To export records in batches from MYOB Acumatica by using OData Version 4.0, you need to use the $top and $skip parameters of the request along with the $orderby parameter.

Note:
The $orderby parameter is required for retrieving batches of records.

The following example retrieves a batch of warehouse detail records. It indicates that the records should be ordered by the inventory ID in ascending order. The response will contain the top 500 records, excluding the first 50 records.

GET https://localhost/AcumaticaERP/odatav4/PX_Objects_IN_INSiteStatus?
$skip=50&
$top=500&
$orderby=InventoryID

Retrieval of Multilingual Fields

If an entity has multilingual fields, you can obtain the values of these fields in any available language. You can do this in either of the following ways:

  • By using the Accept-Language HTTP header and specifying the desired locale as its value
  • By using the locale URL parameter and specifying the desired locale as its value

If neither the Accept-Language HTTP header nor the locale URL parameter is used, the values of multilingual fields are returned in the default language (see Setting Up Languages). If both the Accept-Language HTTP header and the locale URL parameter are used, the locale specified in the locale URL parameter is taken into account.

The following sample URL retrieves the AACOMPUT01 inventory item with French values of the multilingual fields. 
GET https://localhost/AcumaticaERP/ODatav4/PX_Objects_IN_InventoryItem?
locale=fr-FR&
$filter=InventoryCD eq 'AACOMPUT01'

The use of the following request has the same effect.

GET /AcumaticaERP/ODatav4/PX_Objects_IN_InventoryItem?
$filter=InventoryCD eq 'AACOMPUT01' HTTP/1.1
Host: localhost
Accept-Language: fr-FR

Retrieval of Archived Records

You can retrieve archived records along with non-archived ones. To make archived records visible for requests, you use the PX-ApiArchive HTTP header with the SHOW value.

The following sample request retrieves the shipments (including archived ones) that were created before December 31, 2022.

GET /AcumaticaERP/ODatav4/PX_Objects_SO_SOShipment?
$filter=ShipDate gt 2022-12-31T00:00:00%2b03:00
&$select=ShipmentNbr,ShipDate HTTP/1.1
Host: localhost
PX-ApiArchive: SHOW

Restriction of Data Access Through OData 4.0

Through the OData Version 4.0 protocol, users have access to the same data that is visible to them via the UI based on their access rights.