Getting Started

Authentication

You will need a user name, password and customer code. If you are developing an API application to an ERPLY customer, please ask the customer to provide their customer code, and to create a user account for you. “Customer code” is a number consisting of up to 6 digits, eg.: 7704 or 100123.

First, perform an API “verifyUser” call to authenticate and receive a session key. This session key must be included in all subsequent API calls, as a simple POST parameter. Our sample PHP wrapper class does this automatically for you — authenticates when needed and adds session key to your API calls.

When the session expires (it is typically valid for 1 hour), your API calls start returning a 1054 or 1055 error. If you are developing an API wrapper class from scratch, we recommend you to make it automatically re-authenticate and re-issue an API call upon that kind of error.

If you do not have an Erply account yet, create it here.

Request and response format

Every API call is a HTTP POST request in traditional parameter1=value1&parameter2=value2 format. Server responds by sending an XML or JSON document that contains response metadata and requested records.

  • Request – HTTP POST
  • Response – JSON / XML document (you get to choose which). JSON is the default option.

We also advise you to add input parameter sendContentType=1 to every API call. This ensures that server will respond with an appropriate Content-Type header:

  • application/json; charset=UTF-8 for JSON;
  • application/xml; charset=UTF-8 for XML.

For backward compatibility reasons, API does not return that header by default.

Language specific API wrapper

If your language is not listed, check out the cURL example. It is really easy to write your own wrapper.

Limits

API allows at most 1000 requests per hour, per account. Once you reach that limit, all API calls will start returning error code 1002.

If your application hits the limit, the recommended course of action is to wait until the beginning of next hour and resume operations. For example, you may configure your application to retry every 10 minutes until the limit clears.