Asperion REST API

Asperion has made an API available for third party software developers that intend to connect their commercial applications to the Asperion accounting software platform.

If you want to be an API partner with Asperion, then sign up via: https://www.asperion.nl/partners/api/ 

Your application will be evaluated and, if succesfull, you’ll receive the details for a test account (sandbox) and a client ID. This ID gives you access to the sandbox environment and the needed support and documentation to make your app a real success!

Do you have questions or need help with the integration of Asperion? Contact the API support team via: api-support@asperion.nl

The following documentation helps with the implementation of the REST API.

For more information about the available EndPoints, use this link : API Endpoints

SSL

All connections with Asperion go via HTTPS. Minimum level is TLS1.3. Unencrypted traffic is not allowed. 

Language Header

To specify the language in which you want to receive error messages and validations from the API, you can use the Accept-Language header. This header determines the language of the API responses.

Example using cURL:

curl -X GET "https://api.asperion.nl/some-endpoint" \
     -H "Accept-Language: en-US"

In this example, the language is set to English (United States). You can adjust the language code to your desired language (e.g., nl-NL for Dutch (Netherlands)).

Make sure to include this header in all your API requests to receive the appropriate language-specific responses. 

For more information, you can visit to the MDN documentation on Accept-Language: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language

Authorization

In order to use the API, access must be validated. The API partner requires the Client-ID for this.
This is released upon request by our API-support department.

For the authorization of the user data, Asperion API uses the protocol oAuth 2.0.
oAuth is a authentication standard in the industry. For more information, take a look at: https://oauth.net/

Api authentication

All API requests must contain an authorization header.
This header must contain a Bearer token (access token). This accesstoken kan be requested using the Asperion authentication service.
You can retrieve the data of an administration (Tenant) by adding a parameter X-Tenant-Id in the header.

Authentication endpoint is available via: 

• https://identity-sandbox.asperion.nl (SandBox / Test Environment)
• https://identity.asperion.nl (Production)

Authentication process

The oAuth2 Authorization Code Flow is used

1. The user will be redirected to a login page (Authorize Endpoint)
2. The user will be authenticated.
3. User will be send back to the client, with an authorization code.
4. This authorization code will be validated by the authentication server (Token Endpoint)
5. An access_token (and refresh_token) will be send back to the client

An access_token has a limited validity and it’s possible to request a new access_token (without the interference of a user) with the help of a refresh_token.

Endpoints

Authorize Endpoint

The user will be redirected by the client application to this url to start an authentication. If all parameters are correct, the user will be able to login.

GET /connect/authorize?
    client_id=client&
    scope=asperion-api offline_access&
    response_type=code&
    redirect_uri=https://myapp/callback

Parameters

• client_id
  Unique identifier of the client (issued by Asperion)
  
  
• scope
  One or multiple scopes, for access to the api, the scope: asperion-api will be requested.
  In order to access a refresh_token, the scope offline_access should be requested.
  
  
• response_type
  This has to be 'code', corresponding with the Authorization Code Flow
  
  
• redirect_uri
  The uri to be redirected after the user has logged in, this has to be an uri that has been signed up at Asperion
  
  

Token Endpoint (authorization_code)

POST /connect/token

   CONTENT-TYPE application/x-www-form-urlencoded

    client_id=client
    &client_secret={secret}
    &grant_type=authorization_code
    &code={received code}
    &redirect_uri=https://myapp.com/callback

(Form-encoding removed and line breaks added for readability)

Parameters

• client_id
  Unique identifier of the client (issued by Asperion)
  
  
• client_secret
  Secret string to validate the client (issued by Asperion)
  
  
• grant_type
  Description of the way to retrieve the token.
  In order to retrieve an access_token with an authorization code, an authorization_code is expected
  
  
• code
  The code given via the de redirect_uri of Authorize Endpoint
  
  
• redirect_uri
  The same redirect uri as with the Authorize Endpoint

Response

If all parameters are correct and valid, the POST request above will result in an access_token and a refresh_token

Token Endpoint (refresh_token)

POST /connect/token
    client_id=client&
    client_secret=secret&
    grant_type=refresh_token&
    refresh_token=token

Parameters

• client_id
  Unique identifier of the client (name given by Asperion) 
  
  
• client_secret
  Secret string to validate the client. (issued by Asperion)
  
  
• grant_type
  Description of the way to retrieve the token.
  In order to retrieve an access_token with a refresh_token
  
  
• refresh_token
  The refresh_token issued by the token endpoint (authorization_code).

Response

If all parameters are correct and valid, the POST request above will result in a new, valid access_token and refresh_token.

Asperion API

The Asperion API is a way to get access to the data from the Asperion accounting application for external software.

The API is based on REST (REpresentational State Transfer)

Structure

• REST based, via HTTPS
  
  
• With the help of endpoints and the HTTP methods, objects can be requested and modified.
  
  • GET - Request
  • PUT / PATCH - Modify
  • POST - Add
  • DELETE - Delete
    
    
• The API is available via the following url’s (endpoins)
  • https://api.asperion.nl  (production environment)
  • https://api-sandbox.asperion.nl  (sandbox/test environment)
    
    
    

Technical documentation (Swagger)

• Technical documentation is available. (See: https://api-sandbox.asperion.nl/swagger/v1/swagger.json )
• This documentation is generated based on the available endpoints based on Swagger
• This allows us to generate code in every programming language available (See: https://swagger.io/tools/swagger-codegen/ )
• A swagger UI is also available: (See: https://api-sandbox.asperion.nl/swagger/index.html )

HTTP Methods

GET /objects

• Sorting (changing the order of the result)
• Filtering (carrying out specific queries)
• Fields (which field of the object are requested)
• Pagination (giving up the page number and page size)

GET /countries?page=1&pageSize=2
{
  "_data": [
    {
      "id": 1,
      "name": "The Netherlands",
      "code": "NL ",
      "_meta": {
        "self": "https://api.asperion.nl/v1/countries/1"
      }
    },
    {
      "id": 2,
      "name": "Belgium",
      "code": "BE ",
      "_meta": {
        "self": "https://api.asperion.nl/v1/countries/2"
      }
    }
  ],
  "_meta": {
    "previousPage": null,
    "nextPage": "https://api.asperion.nl/v1/countries?pageSize=2&page=2",
    "totalCount": 246,
    "pageCount": 123,
    "self": "https://api.asperion.nl/v1/countries?pageSize=2&page=1",
    "administrationId": 1234,
    "administrationName": "Test",
    "profileName": "UserName"
  }
}

* MetaOnly

With GET, you’re getting the opportunity to impart a MetaOnly (bool) property. 
With the MetaOnly bool, only the de _meta data will be returned, so only the numbers will be returned and the data object will be left out.

GET /objects/{id}

Retrieving a single object based on the Identifier, the parameters here are:

• Fields (which fields of the object are requested)

GET /countries/1
{
  "id": 1,
  "name": "The Netherlands",
  "code": "NL ",
  "_meta": {
    "self": "https://localhost:44366/v1/countries/1",
    "administrationId": 1234,
    "administrationName": "Test",
    "profileName": "UserName"
  }
}

POST /objects

• POST in order to add an object
• The body of the request will be provided with the updated object
• What fields are available via the Swagger documentation.

POST /countries
{
  "name": "The Netherlands",
  "code": "NL "
}

If the object is succesfully created, it will be returned via the response body with a status code 201. A location header will be available with the url of the newly created object.
A 400 (Bad Request) will be brought up if the validation rules and standards of the object aren’t met (together with the reasons why).

PUT /objects/{id}

• Edit an existing object
• The url refers to an existing object
• The body of the request will be provided with the updated object

POST /countries/1
{
  "name": "Nederland",
  "code": "NL "
}

PATCH /object/{id}

• Existing object will be partially deleted
• The url refers to an existing object
• The body of the request will be provided with updated fields of the object
• Only the specified fields will be modified, the rest will keep the existing values.

PATCH /countries/1
{
  "name": "Nederland"
}

DELETE /objects/{id}

• Delete object
• This will delete the object, (if the validation rules are followed)

DELETE /countries/1

API Endpoints overview

API Endpoints