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, include the following headers in your requests to authenticate and communicate with the API correctly:

  • 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 a 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


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 a 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 reauthorise 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.

Pagination

Pagination is a technique used in API responses to break down a large set of data into smaller, more manageable chunks or pages. This allows to retrieve and display data incrementally rather than all at once, improving efficiency and reducing the burden on both the server and the client.

The ApprovalMax API uses limit and continuationToken as parameters for pagination.

Adding a limit to a request determines how many items are to be on each page, and the server responds with a continuationToken indicating where to start fetching the next set of items. The combination of continuationToken and limit allows to navigate through a larger dataset in manageable chunks.

The maximum Limit is 100.

Here's an example:
Initial request:
  1. The client sends a request to the server to retrieve a certain number of items (as per the set limit), which cannot exceed 100.
  2. The response includes the requested items and a continuationToken that indicates the position or index of the last item on the current page.
  1. {
  2. "continuationToken": 0,
  3. "limit": 3,
  4. "items": [
  5.   '32a0e872-9510-4bfa-9799-66c7bbedf3e1',
  6.   'de31faee-063d-4daa-b3d9-33de7eb1c2ee',
  7.   '8bc631d0-f7ef-4ec6-bb6d-09e120fe162c'
  8. ]
  9. }

Subsequent requests:
  1. The client uses the received continuationToken to request the next page of items.
  2. The server responds with the next set of items and an updated continuationToken.
  1. json{
  2. "continuationToken": 3,
  3. "limit": 3,
  4. "items": [
  5.   'cd99fa72-ec00-42fd-a7f9-8e3ae1754c4a',
  6.   '01288f26-a329-4d3c-815f-3b10ee942a40',
  7.   'ff197941-0799-4e93-8f32-64f5c2c88e76'
  8. ]
  9. }
  10. {
  11. "continuationToken": 6,
  12. "limit": 3,
  13. "items": [
  14.   '377e1107-2820-420a-9896-a799a0fa2c42',
  15.   '90fc782a-177c-48ab-9449-846331a693e0',
  16.   '763a4c75-02fd-41b5-bca8-e5a2bd63f1dd'
  17. ]
  18. }

End of pagination:
The process continues until the continuationToken is null or an empty array is returned, indicating that there are no more pages.
  1. {
  2. "continuationToken": 8,
  3. "limit": 3,
  4. "items": []
  5. }
  6. {
  7. "continuationToken": 8,
  8. "limit": 3,
  9. "items": []
  10. }


Rate limit

Accessing the Public API is currently restricted to 1000 requests per minute.
When this limit is reached, the error code 429 is returned along with the message: "Too many requests. Please try again after N second(s)."

    • Related Articles

    • Public API Guide

      Our Public API Guide is available on our website, please follow this link to find it: ApprovalMax – Public API Guide

    • What does "Xero API call rate exceeded" mean?

      Xero has set a limit for how many times we can call its API. When this limit is reached, the error message "Xero API call rate exceeded" appears. In this case, you’ll need to wait until it’s gone. If the error is HTTP TooManyRequests - Too many ...

    • 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 ...

    • A list of endpoints available in the Public API

      For making calls against the API, please refer to the endpoints below, or to the swagger : Endpoints Description GET /ping This endpoint is used for checking the overall availability and responsiveness of the ApprovalMax Public API. When a GET ...

    • What does the ApprovalMax Public API do?

      The ApprovalMax API enables other systems to retrieve data from ApprovalMax and display it in their own systems without any manual action by a person. This seamless integration facilitates the automation of data transfers by pulling the relevant ...