How to call the API?

How to call the API?

Please refer to the Swagger page or the list of available endpoints to find endpoints and their data models.


To successfully make API calls, ensure that you include the following headers in your requests:

  • Authorisation header: this is crucial for authentication. Include the access token obtained during the OAuth flow as a bearer token. The format of the header should be "Bearer + <access_token>".

  • Accept header: allows you to specify the desired response format from the API. Specify the type of response you expect from the API, such as "application/json" for JSON response. The server will then provide the response in the specified format.

  1. GET https://public-api.approvalmax.com//ping authorization: Bearer access_token accept: application/json

Make sure to include these headers in your API requests to authenticate and communicate with the API correctly.

Access and refresh tokens

Access tokens have an expiration time of 1 hour. If your application is granted the "offline_access" scope during the initial user authorisation, it can automatically refresh the access token using a refresh token without requiring any user interaction.


To refresh the access token, your application needs to make a POST request to the token endpoint. Here's how you can do it:

  1. Ensure that you have stored the refresh token securely. It is crucial to protect this sensitive information, such as storing it in the keychain of the operating system, to prevent unauthorised access.
  2. Make a POST request to the token endpoint using the appropriate parameters. 

To refresh the access token, you need to make a POST request to the token endpoint:

  1. POST https://identity.approvalmax.com/connect/token

When refreshing an access token using a refresh token, the request body must include:

  • grant_type=refresh_token. Set this parameter to "refresh_token" to indicate that you are refreshing a token.

  • refresh_token=YOURREFRESHTOKEN. Include the stored refresh token in this parameter obtained during the initial authorisation flow.

  • clientId: Client app key from your application created in the Developer Portal.

  • clientSecret: App secret key from your application created in the Developer Portal.

  1. POST https://identity.approvalmax.com/connect/token
  2. Content-Type: application/x-www-form-urlencoded 
  3. grant_type=refresh_token
  4. &refresh_token=YOURREFRESHTOKEN
  5. &client_id=client_id
  6. &client_secret=client_secret


When refreshing an access token using a refresh token, the response from the token endpoint will include a new access token and refresh token. It is crucial for your application to save both tokens in order to maintain access to the ApprovalMax API.
If your application fails to receive the response or encounters issues while saving the new tokens, you have a grace period of 1 hour. During this grace period, you can retry using your existing refresh token to obtain a new access token. However, after the grace period of 1 hour has elapsed, your previous refresh token will expire. To continue accessing the ApprovalMax API, the user will need to re-authorise your application, which will generate a new refresh token. Handling this scenario is important to ensure uninterrupted access to the API.

You can decode your token here.

    • Related Articles

    • Prerequisites for using the Public API

      Before proceeding with the authorisation process for the ApprovalMax Public API feature, there are certain prerequisites that need to be met. These include: 1. Granting access to the Developer Portal: in order to access the Developer Portal and ...

    • The list of endpoints available in Public API

      To make calls against the APIs, please refer to the endpoints below or to the swagger: Endpoints Description GET /ping In the ApprovalMax Public API, the GET /ping endpoint is a simple endpoint used for checks the overall availability and ...

    • What does the ApprovalMax Public API do?

      The ApprovalMax API provides for other systems the capability to retrieve data from ApprovalMax and display it in their own systems without requiring manual actions from individuals. This allows for a seamless integration and enables the automation ...

    • How to grant access to an Organisation in the ApprovalMax Public API

      The process of granting access to an Organisation consists of the following steps: 1. Initiate user authorisation: generate an URL with the necessary parameters. This URL will direct account owners/ account managers to the ApprovalMax Public API ...

    • How to verify authorised Organisations with access permissions

      To determine which Organisations the Account Owner has authorised, you can make a call to the /companies endpoint using the received token. In response, you will receive a list of Organisations UUIDs to which access has been granted. To retrieve ...