Aptem is focused on helping our customers maximise the efficiency of their delivery, and ensuring data consistency. One way in which this can be achieved is through integration with third-party systems that our customers may be using.

Aptem has been developed to open-API standards making integrations with other systems easy to achieve. Many of our customers integrate with third-party systems such as CRMs, student record systems and HR systems. Using the APIs, customers can ensure that systems are consistent, and that their data is accurate and easy to maintain.

How it works

If you wish to integrate with Aptem:

• Aptem provides a series of API endpoints which allow you to perform certain read/write functions.
• Connecting to the API endpoints must be done securely using an API token for authentication.
• API tokens can be created within Aptem, each containing a unique scope and level of access.
• Integration with our APIs should be completed against an integration tenant which can be provided upon request.
• Any integration work is completed by the provider or third-party.
• Before integrating with a third-party, you may wish to review a list of our existing integrations which can be found here. 

Getting started

To get started making use of the Aptem APIs we would suggest the following steps:

1. Provision of an integration tenant

Development of an integration with Aptem should not be carried out against a production tenant. Aptem can provide an integration tenant for you to develop against - this eliminates the risk of affecting existing customer data.

You can request an integration tenant by contacting the Support Team.

Please note that an integration tenant will not contain any existing customer data such as: programmes, groups, organisations, administrator or user accounts. If you require a clone of your existing production tenant, there will be additional charges for the work to clone the tenant.

2. Create a service account

A service account is essentially an administrator account purely for the purpose of connecting to the Aptem APIs from a third-party system. The benefit of using a service account is that it allows you to control what actions the service calling the API endpoint is allowed to perform - read/save/etc. and what records the service is able to return.

For guidance on creating an administrator account read: Creating an Administrator Account.

3. Request an API token

Any call to an API endpoint must be authenticated to ensure that the service making the request has the permission to perform the action associated with the endpoint. To do this, an API token must be passed in the headers of the request with the key "X-API-Token".

You must raise a request to the Support team when you would like an API token to be generated. When making the request, please provide the following information:

• The website URL of your tenant, e.g. https://{customer-name}.aptem.co.uk
• The username of the service account
• The scope(s) you would like set for the API token (see below)

Understanding scope

Setting the scope determines which API endpoints are available to the service account. This allows you to ensure that a service is only able to perform the actions that are appropriate for that service. The following scopes are available:

• Groups
• Jobs
• Users
• Organisations
• OData
• Admins

4. Calling API endpoints

Any call to an API endpoint must be authenticated to ensure that the service making the request has the permission to perform the action associated with the endpoint. To do this, an API token must be passed in the headers of the request with the key "X-API-Token".

Calling an API endpoint with an invalid token i.e., an incorrect token or a token that does not include the scope of the endpoint you are calling, will result in a 403 unauthorized error response. 

The API endpoints are divided into two main areas: REST and OData.

The OData API endpoints can be used to query read-only data and allow for the ability to specify which fields to return and what filters to apply to the query. The OData API for your tenant is available at: https://{customer-name}.aptem.co.uk/odata/1.0/$metadata.

The REST API endpoints provide the ability to Create, Read, Update and Delete certain types of records. For detailed information on the REST API endpoints, refer to: https://aptem.co.uk/api.html.