API Manual

This manual describes how to interact with LexBase API. The purpose of LexBase API is to facilitate process automation through machine to machine (M2M) communication. It's not intended to provide realtime updates to Web apps. Therefore, a throttling mechanism exists to safeguard fair usage.

Authentication

LexBase API leverages OAuth2 authentication. It currently supports the client_credentials grant. Client id and secret can be obtained from the LexBase web application (https://www.lexbase.nl). Contact your sales specialist at Lexmond Trading BV for API access. With API access you can create one set of client id and secret within the LexBase web application. Currently, with this authentication flow no refresh tokens are distributed. This might change in the future.

An access token can directly be obtained by POST-ing client id and secret to the OAuth2 server.

POST /oauth HTTP/1.1
Host: api.lexbase.nl
Accept: application/json
Content-Type: application/json

{
    "client_id": "77196db3-8cfa-4447-9be6-79fd757a71f7",
    "client_secret": "9Y6GSe2VeLNUM2oRdN1mvkNh",
    "grant_type" : "client_credentials"
}
    

The OAuth2 server will respond with an access token in the body.

{
    "access_token": "6cfa6e6c26cd7857b8ec69599e25211cdecc7957",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null
}
    

The access token can be used as long as it's not expired for any API call that requires authentication. Just add it to the Authorization header after the word 'Bearer'. Authorization: Bearer [access_token]

The authentication flow can be tested with the /who-am-i endpoint.

GET /who-am-i HTTP/1.1
Host: api.lexbase.nl
Accept: application/json
Authorization: Bearer 6cfa6e6c26cd7857b8ec69599e25211cdecc7957
Content-Type: application/json
    

{
    "CustomerNumber": "xxxxx",
    "Name": "xxxxx",
    "Email": "xxxx@xxxxxxxxxxxxxx.xx"
}
    

Downloads

For delivering large amounts of data at once and non-JSON data, downloads are being offered through this API. Each download is created on demand by triggering the download creation process through the /download endpoint. The status of the download creation process can subsequently by queried through the /download-status endpoint. Whenever the file is ready for download a download link is returned in the status response.

The JSON response will have non-ASCII characters encoded with their unicode points to ensure safe transport.

Testing

Testing the API can be achieved by adding a test request parameter to the API call. With the test request parameter added to an API call, throttling is disengaged and the request won't get relayed to any back-end system. Although not having any meaning, the response will be properly formatted. This should help development to validate communication. For example, to test the order creation endpoint, simply add ?test to the URI. https://api.lexbase.nl/order?test