Create a Record

When you need to create a record by using the contract-based REST API, you access the needed URL address 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.

You can create an entity with multiple detail lines by using a single PUT request. If you want to import records from a CSV file, you can use an import scenario instead of the REST API.

HTTP Method and URL

To create 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 a record.

For example, suppose that you want to create a stock item record in 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 create a record.

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

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 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-None-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 create a new record, use the optional If-None-Match header with the `*` (asterisk) value.

Request 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. See below for an example of a customer record representation in JSON format.

{
  "CustomerID" : {value : "JOHNGOOD"},
  "CustomerName" : {value : "John Good"},
  "CustomerClass" : {value : "DEFAULT"},
  "MainContact" : 
    {
      "Email" : {value : "demo@gmail.com"},
      "Address" : 
        {
          "AddressLine1" : {"value" : "4030 Lake Washington Blvd NE"},
          "AddressLine2" : {"value" : "Suite 100"},
          "City" : {"value" : "Kirkland"},
          "State" : {"value" : "WA" },
          "PostalCode" : {"value" : "98033"}
        }      
    }  
}

Response Status Codes

The following table lists the HTTP status codes that the system returns for a request that creates a record.


Code	Description
200	The request has been completed successfully. The response of a successful method call contains the created record in JSON format in the response body. The response includes only the values of the fields of the created record that were specified during creation of the record or that were specified to be returned by using the parameters of the request.
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-None-Match header with the `*` value, and the record already exists.
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 creation of a Customer record in MYOB Acumatica 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.

PUT / HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/Customer
Accept: application/json
Content-Type: application/json

{
  "CustomerID" : {"value" : "JOHNGOOD"},
  "CustomerName" : {"value" : "John Good"},
  "CustomerClass" : {"value" : "DEFAULT"},
  "MainContact" : 
    {
      "Email" : {"value" : "demo@gmail.com"},
      "Address" : 
        {
          "AddressLine1" : {"value" : "4030 Lake Washington Blvd NE"},
          "AddressLine2" : {"value" : "Suite 100"},
          "City" : {"value" : "Kirkland"},
          "State" : {"value" : "WA" },
          "PostalCode" : {"value" : "98033"}
        }      
    }  
}

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.