This document is directed at employees at PeoplePath' customers or their partners, trying to integrate functionality with the PeoplePath platform. The document is technical in nature and assumes that the reader is well known to the HTTP protocol, REST, JSON and OAuth.
This document contains a description of PeoplePath's REST API based on the HTTP protocol granting access to the module endpoints.
Please keep in mind, that this API will be further developed and enhanced by new features. Don't rely on order of tags in resource JSON, also new items will be added to resource JSON. Of course, all development will respect backward compatibility of API.
This document contains description of general principles used in PeoplePath REST API. Detailed, up to date documentation of method calls and resources is available online-as described in this document.
In case you need assistance in understanding and implementing our API, please do not hesitate to contact customer support at support@peoplepath.com.
The following URI Templates describe how to construct URIs to identify resources exposed via our REST API. All URIs in this document point to your instance of our product.
PeoplePath REST API rate limit is defined to 1 000 requests per hour for development purposes. For our partners, the value can be adjusted individually.
The documentation is divided into parts by versions of our REST API. Each version then contains modules and resources documentation.
Module documentation contains description common for all available resources and general info of the module.
Resource documentation consists of description with general information about resources provided by resource. Bellow description are displayed available parameters.
Authenticate with your instance using OAuth 2.0 Client Credentials grant type.
The Client ID and Client Secret for your application will be provided by PeoplePath upon request.
To obtain an Access Token, the Client sends an HTTP POST request to the Server's Access Token URL.
Credentails_base64 = base64(<client id>:<client secret>)
curl -H'Authorization: Basic <Credentails_base64>' --data 'grant_type=client_credentials&scope=api' https://us.intraworlds.com/talents_us/oauth/token
curl -H'Authorization: Bearer <access_token>' https://us.intraworlds.com/talents_us/rest/v1/users/af
Do not obtain a new Access token for each individual request. Instead, store the Access Token and use it for requests until the token expires. Only then obtain a new one.
This section describes the semantics of operations in our REST API.
The HTTP request method GET is used to retrieve the representation of the resource. The response to such a request contains an JSON representation of the resource, or an error message in case something went wrong, in the response body.
The HTTP request method POST is used to create new resources. The response to such a request contains the JSON with newly created resource, or an error message in case an error occurred, in the response body.
The HTTP request method PUT is used to update existing resources. The response to such a request contains the new JSON representation of the updated fields, or an error message in case an error occurred, in the response body.
The HTTP request method DELETE is used to delete an existing resource. The response to such a request contains HTTP response code 200 OK in case of success, or an error message in the response body when something went wrong.
In general, the API communicates with default language setting of API user (user logged in).
This can be changed by adding header to HTTP request.
IW-Language: DE
The set of available languages depends on portal configuration. The language is typically represented by the ISO country code. Additionally we are using internal codes for some specific languages (for example DE is the German language and D2 is an informal German language).
Networks are the main entities in the portal. In general, the API communicates with API user's default network.
This can be changed by adding header to HTTP request.
IW-Network-Id: 1
The set of available networks depends on portal configuration. If you want to work in a specific network then the header must be used in all requests.
In the resource URI prescription are URI parameters inserted into {}. The value in {} is replaced in request mostly by resource identifier.
Regular HTTP request parameters are expected after ? character in URI. Used e.g. for filtering options. The parameters are characterized by following options:
Describe attributes of JSON in request body when using POST or PUT operations.
The parameters are characterized by following options:
We support JSON representation of the response. Bellow is attached JSON example.
{
"foo" : "value",
"bar" : []
}
When getting list of entities, we support
The HTTP response codes are main indicators of the result of the operation.
| Status Code | Description |
|---|---|
| 200 OK | Request was successfully processed. |
| 201 Created | New resource was created. |
| 400 Bad Request | HTTP request had a bad structure. This response code can be returned because of the following reasons: malformed input JSON, missing some required fields in the request, etc. |
| 401 Unauthorized | Missing or bad OAuth parameters: unknown OAuth Consumer, invalid request signature, etc. Requester was denied access to the resource because it does not have permission to access the given network. |
| 403 Forbidden | This indicates authorization issue or invalid CSRF token. |
| 404 Not Found | Resource not found. |
| 409 Conflict | The server understood the request, but is refusing to fulfill it, because of conflict in versions. |
| 413 Request Entity Too Large | The length of entity is out off the limit. |
| 500 Internal Server Error | Some sort of an internal error occurred. When this happens, please contact customer support. |
| 501 Not Implemented | Requested feature or operation is not implemented. |