Every Erply API call requires at least two parameters:
- clientCode - Your ERPLY account number (for example, "2881")
- request - Name of the API call (getCustomers, verifyUser, getRelatedProducts etc).
To authenticate, make a “verifyUser” call and pass your client code, user name and password:
curl -X POST https://[your client code].erply.com/api/ \
-d "clientCode=[your client code]&username=[username]&password=[password]&request=verifyUser&sendContentType=1"This call will return a session key. Include the session key in all subsequent calls.
{
"status":{
"request":"verifyUser",
"requestUnixTime":1370517868,
"responseStatus":"ok",
"errorCode":0,
"generationTime":0.069983959197998,
"recordsTotal":1,
"recordsInResponse":1
},
"records":[
{
"userID":"6",
"userName":"demo",
"employeeID":"4",
"employeeName":"Clara Smith",
"groupID":"7",
"groupName":"sales representatives",
"sessionKey":"awdz94248de6f27afec27dbb2b0e1f83a5d969f594eb",
"sessionLength":3600,
"loginUrl":"https:\/\/s3.erply.com\/eng\/"
}
]
}Sessions have a default lifetime of 3600 seconds. If the session has expired, API calls will return an error code 1054 or 1055 (see the list of error codes). To continue using the API, reauthenticate with the “verifyUser” call.
Sample API call: data retrieval
The “getCustomerGroups” API call returns the hierarchy of customer groups:
curl -X POST https://[your client code].erply.com/api/ \
-d "clientCode=[your client code]&sessionKey=[session key]&request=getCustomerGroups&sendContentType=1"The response starts with meta-information:
| Field | Explanation |
|---|---|
| request | Name of the API call. |
| requestUnixTime | Server time at the end of the request. |
| responseStatus | “ok” or “error”. |
| errorCode | Indicates the error encountered; 0 means a successful request. |
| errorField | If the error was a validation error, indicates which one of the fields failed the validation. |
| generationTime | Time in seconds spent assebling the response |
| recordsTotal | Total number of records that match the supplied filters. (If the call is a data modification call, “recordsTotal” will be 1 by convention.) |
| recordsInResponse | Number of records actually returned in the response. The API does not return larger datasets all at once; it is necessary to “paginate” through the records. |
{
"status":{
"request":"getCustomerGroups",
"requestUnixTime":1370518306,
"responseStatus":"ok",
"errorCode":0,
"generationTime":0.0026619434356689,
"recordsTotal":3,
"recordsInResponse":3
},
"records":[
{
"clientGroupID":"17",
"customerGroupID":"17",
"parentID":"0",
"name":"Loyal Customers",
"pricelistID":"0",
"added":"1283248838",
"lastModified":"1306833659"
},
{
"clientGroupID":"18",
"customerGroupID":"18",
"parentID":"0",
"name":"One-time Customers",
"pricelistID":"0",
"added":"1283248848",
"lastModified":"1306833655"
},
{
"clientGroupID":"20",
"customerGroupID":"20",
"parentID":"0",
"name":"Campaign sign-ups",
"pricelistID":"0",
"added":"1283248917",
"lastModified":"1306833695"
}
]
}
Sample API call: data modification
Let us call a function that also needs an input parameter, saveCustomerGroup:
curl -X POST https://[your client code].erply.com/api/ \
-d "clientCode=[your client code]&sessionKey=[session key]&request=saveCustomerGroup&name=Possible%20leads&sendContentType=1"If the call is successful, the result will be as follows:
{
"status":{
"request":"saveCustomerGroup",
"requestUnixTime":1370518630,
"responseStatus":"ok",
"errorCode":0,
"generationTime":0.090903997421265,
"recordsTotal":0,
"recordsInResponse":0
},
"records":[
{
"id":31,
"customerGroupID":31
}
]
}API returns the ID of created item.