We expose an API that developers can use to retrieve data from embedADAPT - allowing them to create custom integrations, visualisations or analysis.

Documentation

The technical documentation of the API is stored in an OpenAPI/Swagger format and is available here.

Available Data

The following entities are available using the API:

• Organisation
  • Organisation
  • Purpose & Vision
  • Objectives
  • Values Constitution
• Organisation Design
  • Key Functions
  • Systems
  • Roles
• People
  • People
  • Connections
  • Contacts
  • Profile Categories
  • Profile Items
  • Profile Item Values
  • Profile Image
• Teams
• Culture
  • Cultural Indexes (and Cultural Index Configuration details)
  • Career Valuations
  • Cultural Leaders
  • Surveys
  • Peer Catch Ups

Note: currently all data is read-only

Token Permissions and Restrictions

Each API token is assigned to a person within your organisation. The API token will have the same access permissions as the person you select. If you would like full data access for the token, assign the token to a Leader person. Alternatively, you can assign it to a Participant or Collaborator for limited access.

Only one token is permitted for a certain person within an organisation. 

If you misplace the token for a specific person, there is no way to recover that token. In this situation, you are able to delete, then re-create the token. This procedure is detailed below.

There is rate-limiting enabled for all API access, which is detailed further in the technical documentation linked at the beginning of this article.

Enabling API Access for an Organisation

Only people with Administrator access can configure API Access.

1. Click the settings cog in the bottom-left corner.
2. Click “Configure Organisation”
3. Select the “Developer API” configuration area.
4. Tick the “Enable Developer API” checkbox.
5. Save your changes.
6. After enabling and saving, you can create tokens for applicable people (described below)

Creating API Access Tokens

After following the above steps to enable the developer API for your organisation, do the following to create a new API Access Token:

1. Navigate to the “Developer API” configuration area by following the above steps.
2. Click the “Add API Token” button.
   
3. Select the person that is represented by this API Token, then click “Add”.
   
4. A popup will appear with the API token visible. 
   Make sure to save/copy the token to somewhere you can access it. For security reasons, the token will not be shown again after closing the popup. You can click the Copy button (1) to copy the token to your clipboard automatically.
   Click “OK” (2) to close the popup.
   
5. A table will be visible that contains all the API tokens you have created. From here, you can see when the token was created and when it was last used. You can also delete the token, which is detailed below.
   

Deleting Access Tokens

Any token you have previously created can be deleted. This may be desirable if the token is now unused, you would like to change the represented person, or if you have lost the token.

1. Navigate to the “API Access” configuration area by following the above steps.
2. Click the “Delete” button for the token you would like to revoke.
   
3. You will be prompted to confirm deletion of the API token. This is permanent; however, you may re-create the token following the above steps. Press “OK” to delete the token.
   

Usage Examples

Power BI

In this example, we show how to add an API query to Power BI, which you can then visualise in any format you'd like.

For the example, we will be fetching the latest Career Valuations for the organisation, then showing them in a scatter graph.

This assumes you are using Power BI Desktop.

1. Select “Get data” from the Home ribbon, then select “Web”.
   
2. Fill out the “From Web" form as shown:
   1. Select the “Advanced” option.
   2. Input the API URL for the endpoint you would like to use into the “URL parts” field.
      We are using the following URL in this example: 
      https://api.adaptbydesign.com.au/v1/CareerValuations?latestOnly=true&activeOnly=true
   3. Input “Authorization” into the first “HTTP request header parameters” input.
   4. Input “Bearer YOUR-TOKEN” into the adjacent input. Replace YOUR-TOKEN with your API access token.
   5. Click “OK” when done.
      
3. The "Power Query Editor" will open. Here we can confirm the data is as expected. We don't need to do any filtering work here for this example, so go ahead and click “Close & Apply”.
   NOTE: The data returned here is dependent on the access permissions of the person who is assigned to the token. Depending on your organisation configuration, and the access level of the person, the data may be anonymised (no PersonId or Notes values) or may not include the ActualTotal values. If this is the case, you can create another token with more permissions.
   
4. Select “Scatter chart” under “Visualizations”
   
5. Select your scatter chart on your page.
6. Expand the “CareerValuations…” under “Fields”.
7. Drag "ActualTotal" to the “Y Axis” field.
   
8. Drag “CreationDate” to the “X Axis" field, then click the down arrow, and select “CreationDate”.
   
    
9. You should have a graph that looks something like this: