Authenticate

Prerequisites

For API authentication, you need:

• Your account number (customer code). This is typically a six-digit number.
• Your user name.
• Your password.

You can authenticate with the same credentials that you use for logging into Erply. 

If you are a third-party developer building an application for an Erply customer, please ask the customer to provide their customer code, and to create a user account for your integration.

If you do not have an Erply account yet, sign up here.

Authentication steps

Make a “verifyUser” call to Erply API. This is a HTTP POST request; username and password must be specified as POST parameters. 

Below is a command-line example with CURL.

curl -L -X POST 'https://<ACCOUNT_NUMBER>.erply.com/api/' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-F 'request="verifyUser"' \
-F 'clientCode="<ACCOUNT_NUMBER>"' \
-F 'sendContentType="1"' \
-F 'username="<USERNAME>"' \
-F 'password="<PASSWORD>"'

Here is the same call set up in Postman:

“form-data” and “x-www-form-urlencoded” methods are both supported.

API returns a JSON document that contains a session key. For all subsequent requests, you will need the session key.

Sample response:

{
    "status": {
        "request": "verifyUser",
        ...
    },
    "records": [
        {
            "userID": "5",
            ...
            "sessionKey": "9eb92794770bb5e91e3c96aca3e3ad4b752b0c09",
            ...
        }
    ]
}

Session lifetime

The session is valid for a limited time: 1 hour by default.

When the session expires, API calls will start returning an error (HTTP status code 403, or Erply API response codes 1054 or 1055). This is expected behavior. Please set up your integration to re-authenticate automatically with the same credentials, and obtain a new session key.

Re-authentication is only necessary when API responds that the session has expired. Do not issue a new “verifyUser” request for each API call.

Next steps

We advise to create a separate user account for each API integration. This lets you adjust permissions if needed, and makes it clearer who has made a change or created a document.