API v2 - Developer Resources

API Developer Resources

Related Helpguide Pages

• Integrate with the accessplanit API v2 Feeds - Overview

Welcome to our developer guide on using the accessplanit API v2 feeds!

This page will walk you through how to access and utilise the accessplanit API v2 feeds, to integrate your accessplanit data seamlessly into other applications and software. Whether you're integrating a new tool or connecting with an existing service, this guide provides the essential information to get you started, supported with examples.

Here’s what you’ll find within this guide:

• Accessing the API Feeds
  How to gain access to the feeds, authenticate your requests, and understand what endpoints are available to you

• Using the API Feeds
  How to run GET, POST, PUT, and DELETE requests, featuring examples and code snippets to support you retrieving and managing data through the feeds

• FAQs and further support
  Answers to commonly asked questions about the feeds, and how you can get in touch with our team for any additional support.

Open

Follow this page to access the developer information for using the accessplanit v2 APIs.

Introduction to the Feeds

Access to the API Feeds

To gain access to the API Feeds for your platform, you will be provided with a username/ID and a password for a user account which has the required roles, you can then use these credentials to generate a token to access the feeds or to log in to your platform to create an API Key.

Access within the platform is matched to your data access within the API Feeds, this means that the data you can view and update when you are logged into the platform, can also be viewed and updated through API requests.

As API access is an additional module, to request access to the feeds, please contact the Customer Success team at accessplanit.

Authorisation using a token

API requests can be authorised using a token, or by creating an API key.

To generate a token you will use your platform username and password in a GET request to https://platformname.accessplanit.com/accessplan/api/v2/token

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

Use the following parameters in your request:

1. grant_type = password

2. username = enter your user ID for your platform

3. password = enter your password for your platform

Open

Once you have generated a token, it can be used for API Requests using the authorisation type of ‘Bearer Token’.
Your token will be valid for 60 minutes.

Authorisation using API Keys

API requests can be authorised using a token, or by creating an API key.

To create an API Key:

1. Open the ‘Administration’ menu from the Profile options at the top-right of your platform

   Open

   

    

2. Open the ‘API Keys’ menu option to access the page where you can create an manage API Keys

4. Click the ‘Add API Key’ button

   Open

   

    

5. ‘Label’ the API Key clearly
   When creating a new API key, give it a clear and descriptive label.
   We recommend including the name of the integrating software (for example, "Salesforce Integration" or "Finance System - Xero") so it’s easy to identify the purpose of each key later.

   Open

   

    

6. Select the ‘User’
   Use the 'User' option to select which platform User the API Key should be linked to.
   All requests made using this API key will act on behalf of the selected User and will inherit their level of access, so make sure you choose a User with appropriate permissions for the actions the integration will need to complete.

   Open

   

    

7. Copy the ‘API Key’
   Copy the API key immediately, for security reasons, the key will not be displayed again after you save.
   If you lose the key, you will need to generate a new one.

   Open

   

8. ‘Enable’ the API Key
   Check the 'Enable' checkbox to activate the API key.
   You can disable an API key at any time by unchecking this box, this will instantly revoke its access without needing to delete it!

   Open

   

    

9. Set an 'Expiration Date'
   You have the option to set an expiration date for the API key, we recommend setting your API keys to expire every 6 months as a best practice, but you can choose a different timeframe based on your organisation's security policies.

   When a key expires, you will need to generate a new one and update any connected systems with the new key.

   Open

   

    

10. Define the allowed IP Addresses using the ‘IP Whitelist'
    You can specify which IP addresses are allowed to use the API key by adding them to the whitelist.
    Whitelisting IP addresses restricts where requests using this API key can originate from, this adds an important layer of protection. If no IP addresses are specified for your API Key, the key can be used from any location, which increases risk to your platform’s security.
    We recommend always setting allowed IP addresses to ensure that only known/trusted locations can access your platform’s data via the API.

    Open

    

Viewing the modules that are available to you

You can run a request to generate a list of API endpoints that are available for you to access, these endpoints match directly to the data modules in the accessplanit platform.

To access a list of all data modules available for you to access within the feeds, run a GET request using your bearer token or your API Key to https://platformname.accessplanit.com/accessplan/apihelp/v2/modules

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

This will provide you with a comprehensive list of the names of the modules that you can access using the API feeds.

Open

Viewing the available fields for each module

To access a list of the fields that are available in a particular module, run a GET request using your bearer token or your API Key to https://platformname.accessplanit.com/accessplan/apihelp/v2/modules/coursedate

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to view

This will provide you with a list of the fields available within for your chosen module and supporting information for each; including whether each field can be sorted, filtered, and it’s data type.

Open

Response Codes

HTTP Status codes are used to provide feedback about API requests:

HTTP Verbs

The accessplanit API uses HTTP verbs appropriate for each action:

Retrieve data from your accessplanit platform using GET requests

Running a GET request

To read data from a particular module, run a GET request using your bearer token or your API Key to

https://platformname.accessplanit.com/accessplan/api/v2/coursedate

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to view

By default, each GET request will retrieve the first 50 records from that module, with pre-defined fields included in the returned data.

Open

Open

Please see Updating the number of records returned for how to retrieve more or less records.

Please see Specifying fields to return in your GET request with $select to learn how to define the fields that are included in the returned data.

Understand how many records are available for a GET request

To include total of the number of records that are available for your GET request, add the parameter '$count' with the value ‘true’ to your GET request

https://platformname.accessplanit.com/accessplan/api/v2/coursedate?$count=true

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to view

Open

This will provide the following additional information at the end of the results body

• Page index (this starts from 0)

• Total number of records that could be displayed on this page

• Total number of records that meet the criteria of the request

Open

Specifying fields to return in your GET request with $select

To change which fields are included for your data, add the parameter '$select' to your GET request with the names of the required fields comma separated as the value:

https://platformname.accessplanit.com/accessplan/api/v2/coursedate?$select=label,startdate,status,spacesleft

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to view

4. Replace ‘label,startdate,status,spacesleft’ with the required fieldnames, in the order you would like them to be returned

Open

Open

Filtering your GET requests with $filter

To filter out unwanted data, add the parameter '$filter' to your GET request, including the field that should be filtered and how it should be filtered. There are many filter operators available for you to work with, the format required for each is detailed in the following table:

Open

Filtering on multiple fields

To filter on multiple fields, you can add additional filters within the same parameter by using ‘and’ & ‘or’

Example filter where two requirements must be met:

…/api/v2/coursedate?$filter=StartDate gt '2025-01-01T10:00:00' and status eq 'Available'

Example filter where either of the two requirements must be met:

…/api/v2/coursedate?$filter=StartDate gt '2025-01-01T10:00:00' or status eq 'Available'

Open

Please note that filter logic using parenthesis is not supported.

Sorting your GET requests with $orderby

To change how your records are ordered/sorted, add the parameter '$orderby' to your GET request with the names of the field you would like to sort by, followed by whether it should be sorted ascending (asc) or descending (desc)

https://platformname.accessplanit.com/accessplan/api/v2/coursedate?$orderby=startdate desc

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to view

4. Replace ‘startdate’ with the required field

5. Add ‘desc' if you would like to sort descending (you do not need to provide asc to sort ascending)

Open

Sorting on multiple fields

To sort by multiple fields; add the fields and their sorting order, in order of priority within the same parameter, each sorted field should be separated with a comma

e.g. https://platformname.accessplanit.com/accessplan/api/v2/coursedate?$orderby=startdate desc,label asc

Open

Updating the number of records returned with $top

The default number of records that are returned for a GET request is 50

To retrieve more or less records, use the parameter ‘$top’ to your GET request with the number of records you would like to return.

https://platformname.accessplanit.com/accessplan/api/v2/coursedate?$top=20

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to view

4. Replace ‘20’ with the number of records to return

Open

To maintain performance within your platform and the feeds, we recommend not getting more than 50 records at a time:

1. Use the $filter parameter to ensure your request is accurate.

2. Use the $count parameter to understand how many records meet the criteria of your request.

3. Use the $skip parameter to retrieve subsequent data sets.

Pagination with $skip

The default number of records that are returned for a GET request is 50, if there are more records available they can be accessed by making a GET request to the next page.

To view subsequent pages, use the parameter ‘$skip’ in your GET request with the page number you would like to jump to.

Example: https://platformname.accessplanit.com/accessplan/api/v2/coursedate?$skip=1

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to view

4. Replace ‘1’ with the page number you would like to skip to

Open

To include total of the number of records that are available for your GET request, please see Understand how many records are available for a GET request.

Insert data into your accessplanit platform using POST requests

To create a new record in your accessplanit platform, for example to create a new course date, run a POST request using your bearer token or your API Key to: https://platformname.accessplanit.com/accessplan/api/v2/coursedate

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to insert a new record into

Within the body of your request, provide the details of the record you are creating.

Open

Open

A successful POST request will return the ID of the new record in the response.

Open

A course has been created, it’s ID is 2024

Open

Update data in your accessplanit platform using PUT requests

To make updates to an existing record in your accessplanit platform, for example to change the start date of a course, run a PUT request using your bearer token or your API Key to: https://platformname.accessplanit.com/accessplan/api/v2/coursedate/2024

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to insert a new record into

4. Replace 2024 with the ID of the record you are updating (e.g. the User ID, the Course ID, the Company ID)

Within the body of your request, provide the fields that are being updated, and the value that they are being updated to.

Open

Open

Your PUT requests only need to include the fields that are being updated, any fields that you do not include will be left unchanged following your request.

🔁 Insert or Update data in your accessplanit platform using upsert POST requests

When using the $upsert parameter, the API will check for a single matching record using the filter you provide (the same syntax as $filter),

1. If exactly one match is found, the existing record will be updated

2. If no match is found, a new record will be created (as with a standard POST)

3. If more than one match is found, the request will return a 400 Bad Request to prevent unexpected updates

Example usage

Let’s say you want to make sure a user with the email address john.smith@my_company.com exists in your platform. Instead of checking for the user first (GET request) and deciding whether to insert or update, you can now send:

Remember to:

• Replace ‘platformname’ with your platform’s name

• Replace ‘accessplan’ with ‘accessplansandbox’ if you're working in your sandbox environment

• Replace 'user' with the module you're working with

• Update the $upsert parameter to use the field and value you are identifying records with

Include the full record data you want to insert or update in the body of your POST request.

Delete data in your accessplanit platform using DELETE requests

To permanently delete an existing record from your accessplanit platform, run a DELETE request using your bearer token or your API Key to: https://platformname.accessplanit.com/accessplan/api/v2/coursedate/2024

1. Replace ‘platformname’ with your platform’s name

2. Replace the ‘accessplan’ with ‘accessplansandbox’ if you are working on your sandbox environment

3. Replace 'coursedate' with the module you would like to insert a new record into

4. Replace 2024 with the ID of the record you are deleting (e.g. the User ID, the Course ID, the Company ID)

Open

Open

FAQs

• Is the data provided by the API v2 feeds in real-time?
  Yes, each API GET request you make will return real time data for that moment
  
  

• Can I access historical data in the API v2 feeds?
  Yes, you can adjust your filters of your request to include or exclude historical data
  
  

• What data formats are supported by the API v2?
  JSON
  
  

• How is the data transmitted via the API to keep it secure?
  The APIs can only be accessed by users with API permissions, additionally the range of access is them limited by roles, this means that not every API User can access all endpoints.
  
  

• Do the API v2 Feeds follow OData best practices?
  Yes the feeds follow a similar framework and uses the same parameters that are used in OData
  
  

• How do I get access to the API v2 feeds?
  Your initial API Access will be granted alongside the module purchase
  For any additional API Users please speak to your Optimise CSM and they will ensure your access is set up promptly
  
  

Support

If you have any questions or need any further support with using the v2 API Feeds, please ask an administrator with support desk access to raise a ticket directly with our support team.

• Please include details about what you are looking to achieve (e.g. retrieve user information)

• Please include details about the requests you have tried (e.g. the parameters that have been tried)

• Please let us know the name of the system(s) you are looking to integrate with