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 request and the response.

HTTP Method and URL

When you create or update a record in MYOB Acumatica, you use the PUT HTTP method and the following URL.

PUT 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 MYOB Acumatica, which 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 create or update a record.

For example, suppose that you want to update a stock item record in a local MYOB Acumatica instance with the name AcumaticaDB by using a system endpoint with the name Default and Version 23.200.001. You would use the following HTTP method and URL to update a record.

PUT http://localhost/AcumaticaDB/entity/Default/23.200.001/StockItem

Parameters

You can use the following parameters when you are updating a record in MYOB Acumatica:
  • $filter: To specify filtering conditions that identify the record to be updated. For details about the parameter, see $filter Parameter.
  • $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.

HTTP Headers

You can specify the following headers in the request.

Header Description
Accept

Specifies the format of the response body, which should be application/json.
Content-Type

Specifies the format of the request body, which should be application/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 optional 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 MYOB Acumatica, 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 MYOB Acumatica form that corresponds to the entity.
412 You have used the If-Match header with the * value, and the record does not exist.
422

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 Restrictions 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 demo@gmail.com email address.
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.
PUT ?$filter=MainContact/Email%20eq%20'demo@gmail.com'&
   $select=CustomerID,CustomerClass,MainContact/Email&$expand=MainContact HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.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.