Retrieve a Record by Key Fields

To retrieve a record by the values of its key fields from MYOB Advanced 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 request and the response.

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 MYOB Advanced, which has the following format: http://<MYOB Advanced 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 MYOB Advanced form.
Note: 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 MYOB Advanced 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 MYOB Advanced:

$expand: To specify the linked and detail entities to be expanded
Note: 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.
$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.

Request Headers

You can 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 a record by the values of key fields.


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 MYOB Advanced form that corresponds to the 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 a SalesOrder record through the REST API.

Tip: In the request example below, <MYOB Advanced instance URL> is the URL of the MYOB Advanced 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 /SO/000001?$expand=Details HTTP/1.1
Host: [<MYOB Advanced instance URL>]/entity/Default/22.200.001/SalesOrder
Accept: application/json
Content-Type: application/json