Quick Start

Prerequisites

The following are required to invoke the API:

An existing account for your organization along with an employee with the appropriate Developer Admin permissions to generate an app key. Refer to the App keys, client ID, and client secret topic for more information.
If you have not already done so, be sure to understand the basic structure of our API outlined in the Foundations topic.

Call the API

Before you make an API call, it is helpful to understand the flow typical of every interaction between an application and the API. After the flow is described, we move on to exercises and code examples.

Anatomy of an API call

Every API call follows this basic flow:

Your application requests and receives an OAuth 2.0 token from the authentication server.
Your application invokes the API by making a properly-formatted call consisting of an verb (HTTP method) and a noun (API resource in the form of a URL) along with all necessary HTTP headers, parameters, and any required JSON body.
Your authorization token is validated.
If valid, the system receives and processes your application's API request.
The system returns an API response to your application.

Exercises

The following exercises illustrate simple calls against the API. If you have access to the API, feel free to follow along and try out a call yourself.

Generate a token

Note: This exercise uses the Postman extension for Google Chrome.

Note: If you are using a token provided by a federated identity management system, include the federated token as your access_token value just as you would use a normally-generated access_token.

To obtain an access token:

Open Postman
Create and Save a Request
Change the METHOD to POST
Add the authentication URL: https://<<hostName>>/api/authentication/access_token

Note: Remember to replace <<hostName>> with the unique portion of your tenant's URL.
Select Headers and add the following key/value pairs:
- Content-Type : application/x-www-form-urlencoded
- appkey : <<appkey>>
  
  Note: Replace <<appkey>> with the app key generated by an employee with the appropriate Developer Admin permissions. Refer to the App keys, client ID, and client secret topic for more information.
Select Body
Choose content type x-www-form-urlencoded
Add the following key/value pairs:
- username : <<username>>
- password : <<password>>
- client_id : <<client ID>>
- client_secret : <<client password>>
- grant_type : password
- auth_chain : OAuthLdapService
Select Send to generate and receive an access token

Note: You should select and copy your access token before you leave this screen.

Refer to the Authentication and security topic for more information about generating and refreshing an access token.

Call an API resource

Once you have an access token, you're ready to call an API resource. The following exercises step you through a set of sample calls.

First exercise

Note: This exercise uses the Postman extension for Google Chrome.

This exercise calls the Retrieve Person by ID operation using the GET HTTP method.

To call the API:

Open Postman
Ensure the METHOD is GET
Add the URL: https://<<hostName>>/api/v1/commons/persons/<<personId>>

Note: The URL is composed of two parts: a root (https://<<hostName>>/api) and an endpoint (/v1/commons/persons/<<personId>>). The Developer Hub documents all available endpoints.

Note: Remember to replace <<hostName>> with the unique portion of your tenant's URL and <<personId>> with a valid person number.
Select Headers and add the following key/value pairs:

content-type : application/json
appkey : <<app_key>>

Note: Replace <<appkey>> with the app key generated by an employee with the appropriate Developer Admin permissions. Refer to the App keys, client ID, and client secret topic for more information.
Authorization : <<access_token>>

Note: Replace <<access_token>> with the token generated during the Generate a token exercise.

Select Send to call the API

This call returns a response body similar to the following example:

{
    "personIdentity": {
        "personKey": 210
    },
    "personInformation": {
        "accessAssignment": {},
        "employmentStatusList": [
            {
                "effectiveDate": "2016-08-13",
                "employmentStatusName": "Active",
                "expirationDate": "3000-01-01"
            }
        ],
        "expectedHoursList": [
            {
                "quantity": 8,
                "timePeriodTypeName": "Daily"
            },
            {
                "quantity": 40,
                "timePeriodTypeName": "Weekly"
            },
            {
                "quantity": 80,
                "timePeriodTypeName": "Pay Period"
            }
        ],
...
}

Second exercise

Note: This exercise uses the Postman extension for Google Chrome.

This exercise calls the Retrieve Aggregated Data operation using the POST HTTP method and a JSON request body.

To call the API:

Open Postman
Ensure the METHOD is POST
Add the URL: https://<<hostName>>/api/v1/commons/data/multi_read

Note: The URL is composed of two parts: a root (https://<<hostName>>/api) and an endpoint (/v1/commons/data/multi_read). The Developer Hub documents all available endpoints.

Note: Remember to replace <<hostName>> with the unique portion of your tenant's URL.
Select Headers and add the following key/value pairs:

content-type : application/json
appkey : <<app_key>>

Note: Replace <<appkey>> with the app key generated by an employee with the appropriate Developer Admin permissions. Refer to the App keys, client ID, and client secret topic for more information.
Authorization : <<access_token>>

Note: Replace <<access_token>> with the token generated during the Generate a token exercise.

Select Body
Choose body type raw
Add the call body

{
  "select": [
    {"key": "EMP_COMMON_FULL_NAME"},
    {"key": "EMP_COMMON_PRIMARY_JOB"},
    {"key": "EMP_COMMON_PRIMARY_ORG"},
    {"key": "PEOPLE_HIRE_DATE"}],
  "from": {
    "view": "EMP",
    "employeeSet": {
      "hyperfind": {
        "id": "1"
      },
      "dateRange": {
        "symbolicPeriod": {
          "id": 5
        }
      }
    }
  },
  "where": [
    {
      "key": "EMP_COMMON_PRIMARY_JOB",
      "operator": "STARTS_WITH",
      "values": [
        "Apprentice"
      ]
    }
  ]
}

Select Send to call the API

This call returns a response body similar to the following example:

{
    "metadata": {
        "lastRefreshed": "2017-10-18T14:45:23.713785328",
        "numNodes": "39",
        "metadataKey": "ce1ed033-3ccb-4d61-90c6-abd49de4eca0",
        "cacheKey": "ce1ed033-3ccb-4d61-90c6-abd49de4eca0",
        "totalNodes": "39",
        "totalElements": "39"
    },
    "data": {
        "key": {
            "ROOT": "-1"
        },
        "coreEntityKey": {},
        "attributes": [],
        "children": [
            {
                "key": {
                    "PEOPLE": "91"
                },
                "coreEntityKey": {
                    "EMP": {
                        "id": "91"
                    }
                },
...
}

Code examples

Request Type: HTTP GET
Content Type: application/json
External URL: https://<<hostName>>/api/v1/commons/persons/<<personId>>

The following code examples demonstrate an API call.

cURL

curl -X GET \
  https://<<hostName>>/api/v1/commons/persons/<<personId>> \
  -H 'appkey: <<app_key>>' \
  -H 'authorization: <<access_token>>' \
  -H 'content-type: application/json'

Java OkHttp

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://<<hostName>>/api/v1/commons/persons/<<personId>>")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("appkey", "<<app_key>>")
  .addHeader("authorization", "<<access_token>>")
  .build();

Response response = client.newCall(request).execute();
}

This call returns a response body similar to the following example:

{
    "personIdentity": {
        "personKey": 210
    },
...
}