intelliHR

Getting Started with the intelliHR API

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

Please note

This is an initial beta version of the documentation. The documentation and the API are still in active development, and will be subject to multiple and frequent changes in the near future.

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.

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 Portal.
  2. Using the main menu on your left, go to: Settings -> Public API Access Key.
  3. Click Create Access Key button.
  4. When prompted, enter a name for the Access Key.
  5. 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 postman to try and send some test API requests. Take a look at an example below.

  1. After starting postman, create a new request tab or use the default one.
  2. Use POST as request method.
  3. Use https://api.intellihr.io as the request URL.
  4. Below, in the "Headers" tab, you'll need to set 2 headers with your request:
    • Authorization => Bearer <your_api_access_token>
    • Tenant => Your organisation tenant name which will be the subdomain part of your application URL for example: https://<tenant>.intellihr.net
    Get list of people in Postman

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


{
  "data": [
    {
      "type": "people",
      "id": "00000000-0000-0000-0000-000000000000",
      "attributes": {
        "preferredName": "Batman",
        "preferredOrFirstName": "Batman",
        "firstName": "Bruce",
        "middleNames": "Thomas",
        "lastName": "Wayne",
        "displayName": "Bruce (Batman) Wayne",
        "legalName": "Bruce Wayne",
        "dateOfBirth": "1939-07-23",
        "gender": "Male",
        "employeeNumber": "00000",
        "title": "Mr",
        "createdAt": "2008-01-01T12:00:27+00:20",
        "emergencyContact": {
          "name": "Selina Kyle",
          "relationship": "colleague ¬‿¬",
          "phone": "00 0000 0000",
          "email": "selina.kyle@catwoman.org"
        },
        "profilePictureId": "00000000-0000-0000-0000-000000000000",
        "profileCoverPictureId": "00000000-0000-0000-0000-000000000000",
        "workRightExpiryDate": "2008-01-01T12:00:27+00:20",
        "id": "00000000-0000-0000-0000-000000000000",
        "personalEmailAddresses": [{
          "name": "Batman email",
          "email": "dark.knight@batman.org",
          "isPrimary": false,
          "isPersonal": false,
          "id": "string"
        }],
        "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"
        }]
      }
    },
    ... 9 more records of "type": "people" ...
  ],
  "meta": {
    "pagination": {
        "total": 306,
        "count": 10,
        "per_page": 10,
        "current_page": 1,
        "total_pages": 31
    }
  },
  "links": {
      "self": "http://api.intellihr.io/people?limit=10&page=1",
      "first": "http://api.intellihr.io/people?limit=10&page=1",
      "next": "http://api.intellihr.io/people?limit=10&page=2",
      "last": "http://api.intellihr.io/people?limit=10&page=31"
  }
}
                

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/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/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/people
                        

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