Contract-based REST API

Specify the value of a system field (such as ID, RowNumber, and Note) of an entity in the following format.

<Field name > : <Value>

For example, if you need to specify the note Imported for an entity, use the following string.

"Note" : "Imported"

Specify the value of a general field (that is, a field that is not a system field) of an entity in the following format.

<Field name > : {value : <Value>}
For example, if you need to specify JOHNGOOD as the customer ID of a customer record, use the following string.
"CustomerID" : {value : "JOHNGOOD"}

Specify the values of the fields of a linked entity in the following format.
<Field name > :
{
<List of fields of the linked entity with values
}
For example, if you need to specify the values of an email address and the address of a customer main contact, use the following string.
"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" }
}
}

Specify the values of the fields of a detail entity in the following format.
<Field name > : [
{
<List of fields of the detail entity with the values}
},
{
<List of fields of the detail entity with the values>
},
…
]
For example, if you need to specify the values of two detail lines of a sales order, use the following string.
"Details" : [
{
"InventoryID" : {value: "AALEGO500"},
"Quantity" : {value: 10}, "UOM" : {value: "PIECE"},
},
{
"InventoryID" : {value: "CONGRILL"},
"Quantity" : {value: 1},
"UOM" : {value: "PIECE"},
}

Specify the values of the custom fields (that is, the fields that are not included in the contract of the endpoint) in the following format.
"custom" :
{
<View name >:
{
<Field name > :
{
"type" : <value>,
"value" : <value>
}
}
}

Use this block in the JSON representation of the entity (top-level, detail, or linked) that contains this custom field. For example, suppose that you added the Personal ID element to the Main Contact area of the Customers form (AR.30.30.00) in a customization project. The Contact entity, which is available through the MainContact property of the Customer entity, contains the Personal ID custom element. This element has the String type and the UsrPersonalID field name and belongs to the DefContact data view. Therefore, to specify the value AB123456 of the Personal ID custom element for the customer with ID JOHNGOOD through the REST API, use the following string.

{
"CustomerID" : {value : "JOHNGOOD" } ,
"MainContact" :
{
"custom" :
{
"DefContact" :
{
"UsrPersonalID" :
{
"type" : "String",
"value" : "AB123456"
}
}
}
}
}

When you need to log in to MYOB Advanced, use the following URL:
http://<MYOB Advanced URL>/entity/auth/login
Replace <MYOB Advanced URL> with the URL of your MYOB Advanced instance.
For example, suppose that you want to log in to a local MYOB Advanced instance with the name AdvancedDB. You should use the following URL:
http://localhost/AdvancedDB/entity/auth/login.

Use no parameters when you log in to MYOB Advanced.

Use the POST HTTP method and pass the credentials for accessing MYOB Advanced in JSON format, as shown in the following example.
{
"name " : {value : "admin" } ,
"password" : {value : "123" },
"company" : {value : "MyCompany" },
"branch" : {value : "MYSTORE" }
}

The response of a successful method call is 204 No Content.

The following code shows an example of a class that implements a login to MYOB Advanced through the REST application programming interface (API).
public class RestService: IDisposable
{
private readonly HttpClient _httpClient;

private readonly string _acumaticaBaseUrl;

public RestService(
string acumaticaBaseUrl, string userName, string password,
string company, string branch)
{
_acumaticaBaseUrl = acumaticaBaseUrl;
_httpClient = new HttpClient(
New HttpClientHandler
{
UseCookies = true,
CookieContainer = new CookieContainer()
})
{
BaseAddress = new Uri(acumaticaBaseUrl +
"/entity/Default/6.00.001/"),
DefaultRequestHeaders =
{
Accept = {MediaTypeWithQualityHeaderValue.Parse("text/json")}
}
};

//Log in to MYOB Advanced
_httpClient.PostAsJsonAsync(
acumaticaBaseUrl + "/entity/auth/login", new
{
name = userName,
password = password,
company = company,
branch = branch
}).Result
.EnsureSuccessStatusCode();
}

 
void IDisposable.Dispose()
{
_httpClient.PostAsync(_acumaticaBaseUrl + "/entity/auth/logout",
New ByteArrayContent(new byte[0])).Wait();
_httpClient.Dispose();
}
}
The following code logs in to MYOB Advanced when an instance of the RestService class, which is defined in the code fragment above, is created.
RestService rs = new RestService( Properties.Settings.Default.AcumaticaBaseUrl, Properties.Settings.Default.UserName, Properties.Settings.Default.Password, Properties.Settings.Default.Company, Properties.Settings.Default.Branch
);

When you need to log out from MYOB Advanced, use the following URL.
http://<MYOB Advanced URL>/entity/auth/logout
Replace < MYOB Advanced URL> with the URL of your MYOB Advanced instance.
For example, suppose that you want to log out from a local MYOB Advanced instance with the name AdvancedDB. You should use the following URL:
http://localhost/AdvancedDB/entity/auth/logout

No parameters are required when you log out from MYOB Advanced.

Use the POST HTTP method to log out from MYOB Advanced.

The response of a successful method call is 204 No Content.

The following code shows an example of a class that implements a logout from MYOB Advanced through the REST application programming interface (API). Logout is performed each time an instance of the RestService class is released.
public class RestService: IDisposable
{
private readonly HttpClient _httpClient;

private readonly string _acumaticaBaseUrl;

public RestService(
string acumaticaBaseUrl, string userName, string password,
string company, string branch)
{
_acumaticaBaseUrl = acumaticaBaseUrl;
_httpClient = new HttpClient(
new HttpClientHandler
{
UseCookies = true,
CookieContainer = new CookieContainer()
})
{
BaseAddress = new Uri(acumaticaBaseUrl +
"/entity/Default/6.00.001/"),
DefaultRequestHeaders =
{
Accept =
{MediaTypeWithQualityHeaderValue.Parse("text/json")}
}
};

_httpClient.PostAsJsonAsync(
acumaticaBaseUrl + "/entity/auth/login", new
{
name = userName,
password = password,
company = company,
branch = branch
}).Result
.EnsureSuccessStatusCode();
}

//Log out from MYOB Advanced
void IDisposable.Dispose()
{
_httpClient.PostAsync(_acumaticaBaseUrl + "/entity/auth/logout",
new ByteArrayContent(new byte[0])).Wait();
_httpClient.Dispose();
}
}

If you need to create a record in MYOB Advanced, use the following URL:
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 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 create a record.

For example, suppose that you want to create a stock item record in a local MYOB Advanced instance with the name AdvancedDB by using the system endpoint with the name Default and Version 6.00.001. You should use the following URL to create a record:
http://localhost/AdvancedDB/entity/Default/6.00.001/StockItem.

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
• $custom: To specify the fields that are not defined in the contract to be returned

Use the PUT HTTP method and 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" },
"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" }
}
}
}

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.

The following code shows an example of a class that implements the creation of a record in Acumatica ERP through the REST API.
public class RestService: IDisposable
{
private readonly HttpClient _httpClient;

private readonly string _acumaticaBaseUrl;

public RestService(
string acumaticaBaseUrl, string userName, string password,
string company, string branch)
{
_acumaticaBaseUrl = acumaticaBaseUrl;
_httpClient = new HttpClient(
new HttpClientHandler
{
UseCookies = true,
CookieContainer = new CookieContainer()
})
{
BaseAddress = new Uri(acumaticaBaseUrl +
"/entity/Default/6.00.001/"),
DefaultRequestHeaders =
{
Accept =
{MediaTypeWithQualityHeaderValue.Parse("text/json")}
}
};
_httpClient.PostAsJsonAsync(
acumaticaBaseUrl + "/entity/auth/login", new
{
name = userName,
password = password,
company = company,
branch = branch
}).Result
.EnsureSuccessStatusCode();
}

void IDisposable.Dispose()
{
_httpClient.PostAsync(_acumaticaBaseUrl + "/entity/auth/logout",
new ByteArrayContent(new byte[0])).Wait();
_httpClient.Dispose();
}

 
//Data submission
public string Put(string entityName, string parameters,
string entity)
{
var res = _httpClient
.PutAsync(_acumaticaBaseUrl + "/entity/Default/6.00.001/" +
entityName + "?" + parameters,
new StringContent(entity, Encoding.UTF8,
"application/json"))
.Result
.EnsureSuccessStatusCode();

return res.Content.ReadAsStringAsync().Result;
}
}
The following code uses the RestService.Put() method, which is defined in the previous code fragment, to create a customer record.
public static void CreateCustomer()
{
//Path to a source text file that contains
//the new customer record in JSON format
string entitySource = @"..\..\Input\Customer.txt";

//Initialize the REST service
RestService rs = new RestService(
Properties.Settings.Default.AcumaticaBaseUrl,
Properties.Settings.Default.UserName,
Properties.Settings.Default.Password,
Properties.Settings.Default.Company,
Properties.Settings.Default.Branch
);
using (StreamReader sr = new StreamReader(entitySource))
{
//Read the customer record in JSON format from the file
string entityAsString = sr.ReadToEnd().ToString();

//Create a customer record
string customer = rs.Put("Customer", null, entityAsString);

}

If you need to update a record in MYOB Advanced, use the following URL.
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 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 update a record.

For example, suppose that you want to update a stock item record in a local MYOB Advanced instance with the name AdvancedDB by using the system endpoint with the name Default and Version 6.00.001. You would use the following URL to update a record:
http://localhost/AdvancedDB/entity/Default/6.00.001/StockItem.

You can use the following parameters when you are updating a record in MYOB Advanced:

• $filter: To specify filtering conditions that identify the record to be updated
• $expand: To specify the linked and detail entities to be expanded
• $custom: To specify the fields that are not defined in the contract to be returned

Use the PUT HTTP method and 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 Advanced, 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.

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.

The response of a successful method call contains the updated record in JSON format in the response body. The response includes only the values of the fields of the updated record that were specified during the update or that were specified to be returned by using the parameters of the request.

The following code shows an example of a class that implements the update of a record in MYOB Advanced through the REST API.
public class RestService: IDisposable
{
private readonly HttpClient _httpClient;
private readonly string _acumaticaBaseUrl;

public RestService(
string acumaticaBaseUrl, string userName, string password,
string company, string branch)
{
_acumaticaBaseUrl = acumaticaBaseUrl;
_httpClient = new HttpClient(
new HttpClientHandler
{
UseCookies = true,
CookieContainer = new CookieContainer()
})
{
BaseAddress = new Uri(acumaticaBaseUrl +
"/entity/Default/6.00.001/"),
DefaultRequestHeaders =
{
Accept =
{MediaTypeWithQualityHeaderValue.Parse("text/json")}
}
};
_httpClient.PostAsJsonAsync(
acumaticaBaseUrl + "/entity/auth/login", new
{
name = userName,
password = password,
company = company,
branch = branch
}).Result
.EnsureSuccessStatusCode();
}

void IDisposable.Dispose()
{
_httpClient.PostAsync(_acumaticaBaseUrl + "/entity/auth/logout",
new ByteArrayContent(new byte[0])).Wait();
_httpClient.Dispose();
}

//Data submission
public string Put(string entityName, string parameters, string
entity)
{
var res = _httpClient
.PutAsync(_acumaticaBaseUrl + "/entity/Default/6.00.001/" +
entityName + "?" + parameters,
new StringContent(entity, Encoding.UTF8,
"application/json"))
.Result

.EnsureSuccessStatusCode();
return res.Content.ReadAsStringAsync().Result;
}
}
The following code uses the RestService.PutWithFilter() method, which is defined in the previous code fragment, to update an existing customer record that has the demo@gmail.com email address.
public static void UpdateCustomer()
{
//Path to a source text file that contains an updated customer record in JSON format
string entitySource = @"..\..\Input\Customer_Upd.txt";

//REST service initialization
RestService rs = new RestService(
Properties.Settings.Default.AcumaticaBaseUrl,
Properties.Settings.Default.UserName,
Properties.Settings.Default.Password,
Properties.Settings.Default.Company,
Properties.Settings.Default.Branch
);

using (StreamReader sr = new StreamReader(entitySource))
{
//Read customer record in JSON format from file
string entityAsString = sr.ReadToEnd().ToString();

//Specify filtering parameters that identify the customer
string parameter = "$filter=MainContact/Email eq
'demo@gmail.com'";

//Update the customer record
string customer = rs.Put("Customer", parameter, entityAsString);
}
}

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

A

Content in here is hidden by default

If there's only one expandable on the page, you can leave it open by default.