Retrieve a Record by ID

To retrieve a record by the value of the entity ID from MYOB Acumatica 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.

Note:

The entity ID is a GUID that is assigned to each entity you work with during an MYOB Acumatica session. You can obtain the value of the entity ID from the ID property of an entity returned from MYOB Acumatica.

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 MYOB Acumatica throughout different sessions with MYOB Acumatica. 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, after a new login to MYOB Acumatica, 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.

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 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 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 MYOB Acumatica instance with the name AcumaticaDB by using the system endpoint with the name Default and Version 23.200.001. You should use the following URL to retrieve the sales order.

http://localhost/AcumaticaDB/entity/Default/23.200.001/SalesOrder/a6295b33-c7f6-e811-b817-00155d408001

Parameters

You can use the following parameters when you retrieve a record from MYOB Acumatica:

$expand: To specify the linked and detail entities to be expanded. For more information, see $expand Parameter.
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.
$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.

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 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.
403	The user has insufficient rights to access the MYOB Acumatica 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 with detail records by the entity ID through the REST API.

Tip:

In the request example below, <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 /a6295b33-c7f6-e811-b817-00155d408001?$expand=Details HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/SalesOrder
Accept: application/json
Content-Type: application/json