intelliHR

Getting Started with the intelliHR API

Welcome! This guide will show you how to get started with the intelliHR public API.

V1 released!

Version 1 of the intelliHR public API is now released! This version can be considered stable and production ready for integrations with third party systems.

Note that future endpoints and data models may be added to this API in the near future, but no breaking changes will be made to any endpoints on v1.

If you have any suggestions, feedback or complaints, please contact us at support@intellihr.co, and mention that you have an enquiry about our public API and we can put you in touch directly with the development team.

(If you still need access to the beta documentation for legacy integrations, it can be accessed here.)

Introduction:

Welcome to the intelliHR API! Our public API will give you access to multiple endpoints, such as the People API (to lookup, list or create a person), or the Jobs API (to retrieve or insert Job related information).

The API is organised around REST. All requests should be made over HTTPS. All request response bodies, including errors are encoded in JSON.

To learn more about the API endpoints, proceed to our API docs page.

API Authentication:

intelliHR is using a string based authentication token for API request authorisation. In order to use the intelliHR API, you will have to send a token generated for your organisation with every request. Here is how you can obtain one for your system:

Get API Access Key
  1. Use your intelliHR credentials to login to the intellihr platform.
  2. Using the main menu on your left, go to: Settings.
  3. Under the settings menu, go to: Public Api Access Keys.
  4. Click Create Access Key button.
  5. When prompted, enter a name for the Access Key.
  6. Copy the generated Access Key somewhere safe. (Keep in mind that you won't be able to regenerate the same Access Key again, so make sure you save it.)

You can now send API requests to intelliHR using the generated Access Key. Note that currently there is no support for permission scopes - any API token can access all endpoints and should be considered the same as full system administrator access. Please email us at support@intellihr.co to tell us about your use case for permission scoped tokens!

Usage:

To quickly test your access tokens and get familiar with the API, we recommend using insomnia to try and send some test API requests. Take a look at an example below.

  1. After starting insomnia, create a new request.
  2. Use GET as the request method.
  3. Use https://api.intellihr.io/v1 as the request URL.
  4. In the "Authentication" tab, you'll need to select Bearer Token and set your API access token:
    • TOKEN => <your_api_access_token>
    Authentication example in Insomnia
  5. In the "Header" tab, you'll need to set your tenant name:
    • tenant => Your organisation tenant name which will be the subdomain part of your application URL for example: https://<tenant>.intellihr.net
    Header example in Insomnia

After you send this request you should be getting a response that follows the following format:


{
  "meta": {
    "pagination": {
        "count": 10,
        "current_page": 1,
        "per_page": 10,
        "total": 306,
        "total_pages": 31
    }
  },
  "links": {
      "self": "http://api.intellihr.io/v1/people?limit=10&page=1",
      "first": "http://api.intellihr.io/v1/people?limit=10&page=1",
      "next": "http://api.intellihr.io/v1/people?limit=10&page=2",
      "last": "http://api.intellihr.io/v1/people?limit=10&page=31"
  },
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "displayName": "Bruce (Batman) Wayne",
      "firstName": "Bruce",
      "middleName": "Thomas",
      "lastName": "Wayne",
      "preferredName": "Batman",
      "dateOfBirth": "1939-07-23",
      "gender": "Male",
      "employeeNumber": "00000",
      "autoIncrementingIntellihrId": 1234,
      "title": "Mr",
      "emergencyContact": {
        "name": "Selina Kyle",
        "relationship": "colleague ¬‿¬",
        "phone": "00 0000 0000",
        "email": "selina.kyle@catwoman.org"
      },
      "employmentStatus": "Current Staff",
      "jobs": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "Software Engineer",
          "startDate": "2003-02-11T14:00:00+00:00",
          "endDate": "2017-02-11T14:00:00+00:00",
          "jobStatus": "Current Job",
          "link": "http://api.intellihr.io/v1/jobs/00000000-0000-0000-0000-000000000000"
        }
      ],
      "primaryEmailAddress": "dark.knight@batman.org",
      "createdAt": "2019-08-28T04:32:20+00:00",
      "updatedAt": "2019-08-28T04:32:20+00:00"
    },
    ... 9 more records of "type": "people" ...
  ]
}
                

Note how every request will return meta and links attributes with pagination specific information.

The links section will provide you with pagination links, however prev and next pages may not always be displayed. For instance, in the example above prev page is not provided, because the current page displayed is the first one. Similarly, when you hit the last page, the API will not provide you with a link to the next page.

To see the full API documentation please go to our API docs page.

Examples:

Below are examples of programmatic API calls.

  • JavaScript
    
    fetch('http://api.intellihr.io/v1/people', {
      method: 'GET',
      headers: {
        Authorization: 'Bearer your-secret-access-token',
        Tenant: 'your-tenant-key',
      },
    })
      .then(
        function(response) {
          jsonFormatterResponse = response.json();
    
          console.log(jsonFormatterResponse);
        }
      );
                        
  • Python
    
    import urllib.request
    
    url = 'http://api.intellihr.io/v1/people'
    headers = {
      'Authorization': 'Bearer your-secret-access-token',
      'Tenant': 'your-tenant-key'
    }
    req = urllib.request.Request(url, None, headers)
    
    with urllib.request.urlopen(req) as response:
      list_of_people_result = response.read()
      print(list_of_people_result)
                        
  • Curl
    
    curl \
      -H "Authorization: Bearer your-secret-access-token" \
      -H "Tenant: your-tenant-key" \
      https://api.intellihr.io/v1/people
                        

To see the full API documentation please go to our API docs page.