Create a Record

When you need to create a 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

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>

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 24.200.001. You should use the following URL to create a record: http://localhost/AcumaticaDB/entity/Default/24.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.
  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 can specify the following headers in the request.

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.

"CustomerID": {
 "value": "ABARTENDE1",
 "error": "'Customer' cannot be found in the system."
}

Example

The following request shows an example of the creation of a Customer record in MYOB Acumatica through the REST API.

PUT / HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/24.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

Note the following about creation of records through the REST API:

• You can create a record with multiple detail lines by using a single PUT request.

• If you need to create or update documents with a large number of detail lines by using the contract-based REST API, note that the following approaches may have performance implications:

  • You make a single request that contains all information you need to pass. In this case, the operation could time out.
  • You make many requests, each of which contains a single detail line you need to add or alter. In this case, the whole task takes a lot of time.

  A more balanced approach is a compromise between these two: You make multiple requests, each of which contains a part of the detail lines you need to add or alter. You select the number of detail lines in a single request to optimize the performance of the whole task. For example, if you need to send a sales order containing 10,000 detail lines to the server, you can make requests, each of which contains 500 detail lines.

• You can specify a value 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 returned in the error field of the response. For a multiselect drop-down list, only internal (namely, not external or displayed) values can be specified.

• In a customization project, you can add custom fields to MYOB Acumatica forms. You can also add user-defined fields to MYOB Acumatica forms and include them in a customization project. (For details about user-defined fields, see User-Defined Fields.)

  To specify the values of custom and user-defined fields through the contract-based REST API, you specify the values of these fields in the body of the PUT request, as shown in Create a Record with Custom Fields.

• For some text boxes on MYOB Acumatica forms, users can type values in multiple languages if multiple locales have been configured in MYOB Acumatica. For details about how to specify the values of multi-language fields in REST API requests, see Specify Any Number of Localized Values of a Multilingual Field and Specify All Localized Values of a Multilingual Field.