Retrieve Records by Conditions
To retrieve the records that satisfy the specified conditions from MYOB Acumatica by using the contract-based REST API, you access the needed URL address with the
GET
HTTP method; if necessary, you also specify filtering conditions in
the parameters of the method. See the following sections for details on the request and the
response.
HTTP Method and URL
If you need to retrieve the list of records, you use the GET
HTTP method and the
following URL.
GET http://<Base endpoint URL>/<Top-level entity>
- <Base endpoint URL> is the URL of the contract-based endpoint through which you are going to work with MYOB Acumatica. This URL has the following format: http://<MYOB Acumatica 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 MYOB Acumatica instance with the name AcumaticaDB by using the system endpoint with the name Default and Version 24.200.001. You should use the following URL to retrieve the list of records: http://localhost/AcumaticaDB/entity/Default/24.200.001/StockItem.
Parameters
- $filter: To specify the filtering conditions that identify the record to be updated. For details about this parameter, see $filter Parameter.
- $skip: To specify the number of records to be skipped from the list of returned records. For more information about the parameter, see $skip Parameter.
- $top: To specify the number of records to be returned in the list. For details about the parameter, see $top Parameter.
- $expand: To specify the linked and detail
entities to be expanded. For more information, see $expand Parameter.Attention:You must list in the $expand parameter every detail and related entity that you are going to have in the response body.
- $select: To specify the fields of the entity to be returned. For more information about the parameter, see $select Parameter.
- $custom: To specify the fields that are not defined in the contract to be returned. For details about the parameter, see $custom Parameter.
Request Headers
You specify the following header in the request.
Header | Description |
---|---|
Accept |
Specifies the format of the response body, which should be application/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 MYOB Acumatica form that corresponds to the API entity. |
429 | The number of requests has exceeded the limit imposed by the license (see License Restrictions 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.
<MYOB Acumatica instance URL>
is the URL of the MYOB Acumatica
instance (such as https://my.acumatica.com/MyInstance). You can omit the instance
name in the URL (that is, you can use https://my.acumatica.com) if the instance
is installed in the root of the website.GET /entity/Default/24.200.001/StockItem?
$expand=WarehouseDetails&
$filter=ItemStatus%20eq%20'Active'%20and
%20LastModified%20gt%20datetimeoffset'2024-08-18T23%3A59%3A59.999%2B04%3A00'
HTTP/1.1
Host: [<MYOB Acumatica instance URL>]
Accept: application/json
Content-Type: application/json
Usage Notes
- 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 by key fields or by IDs. For more information, see Retrieve a Record by Key Fields and Retrieve a Record by ID.