Get started with the RecruitNow Cockpit PublicAPI

An API is an application programming interface - in short, it’s a set of rules that lets programs talk to each other, exposing data and functionality across the internet in a consistent format.

REST stands for Representational State Transfer. This is an architectural pattern that describes how distributed systems can expose a consistent interface.
When people use the term ‘REST API,’ they are generally referring to an API accessed via HTTP protocol at a predefined set of URLs.
These URLs represent various resources - any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images.
Often, resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT and DELETE.

The RecruitNow Cockpit PublicAPI - in short PublicAPI - consist of a collection of HTTP-based RESTful APIs that uses an API key for authorization. API request and response bodies are formatted in JSON.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Important: You cannot run the sample requests in this guide as-is. Replace call-specific parameters such as keys and Ids with your own values.

Authentication and authorization

The PublicAPI REST API uses API key authentication to authorize calls.
When you create an application which requires access to the PublicAPI, RecruitNow will generate an API key for your application for the requested environment.
With this API key the RESTful API can be called. You pass the API key in the Authorization header with the API key authorization scheme to make authorized REST calls.

This sample request uses an API key to list companies:

curl -X GET \
	-H 'Accept: application/json' \
	-H 'X-Api-Key: <API key>' \
	'https://<publicapi_url>/rest/api/v1/Companies'

API keys Access tokens have an infinite lifetime, until revoked by Recruitnow.

When an API key is incorrect or revoked by RecruitNow, a HTTP 401 Unauthorized status code will be returned from any request made.

API Requests

To construct a REST API request, combine these components:

https://<publicapi_url>/rest/api/v1

companies/companies-12-A/companycontacts

API Responses

The PublicAPI calls return JSON response bodies that include information about the resource.

HTTP status codes

Each REST API request returns a success or error HTTP status code.

Success

In the responses, the PublicAPI returns these HTTP status codes for successful requests:

Error

In the responses for failed requests, the PublicAPI returns HTTP 4XX or 5XX status codes.

In the responses, the PublicAPI returns these HTTP status codes for failed requests:

Validation errors

For validation errors, then PublicAPI returns the HTTP 400 Bad Request status code.

Sample of validation response:

{
  "errors": {
    "Limit": [
      "'Limit' must be between 1 and 1000. You entered -1000."
    ],
    "Start": [
      "'Start' must be greater than or equal to '0'."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "|8821207b-41d44082f0e99a82."
}

Make your first call

To make REST API calls to the PublicAPI, you need to get an API key.

Use the API key for authentication when you make REST API calls.

To make a call, you can use either cUrl on the command line or the Postman app.

cURL example

Tips:

• If you use Windows, use a Bash shell to make cURL calls.
• If you use a command-line tool other than cURL, set content-type to application/x-www-form-urlencoded.

Download cURL for your environment. From the command line, run the command below. This sample call returns all companies in the RecruitNow Cockpit application.

The X-Api-Key in the header of the call is an API key provider by RecruitNow to authenticate the request:

curl -X GET \
	-H 'Accept: application/json' \
	-H 'X-Api-Key: <API Key>' \
	'https://<publicapi_url>/rest/api/v1/Companies'

A successful call returns a JSON-formatted response body with a list of companies. For example:

{
  "resultCount": 3,
  "totalResults": 3,
  "skippedResults": 0,
  "results": [
    {
      "id": "companies-1-A",
      "name": "Microsoft"
    },
    {
      "id": "companies-2-B",
      "name": "Oracle"
    },
    {
      "id": "companies-3-A",
      "name": "Apple"
    }
}

Postman example

Download the latest version of Postman for your environment, and open Postman and perform the following actions.

1. Select the GET method.

2. Enter the https://<publicapi_url>/rest/api/v1/companies request URL.

3. On the 'Headers' tab,  add the X-API key header with the supplied API key

4. Click Send.

5. View the response 

Multi tenancy (MCE)

As for the RecruitNow Cockpit PublicAPI , there are multiple versions available. One of these versions is the Multiple Client Edition MCE.

A Cockpit MCE version consists of one cockpit instance in which one or more administrations / agencies are managed. To request data from - or to change data for a certain agency, a so-called tenantId must be included in the header of the call with every RESTful request.

This tenantId consists of the ID of the relevant agency. The available agency Id's in Cockpit can be retrieved using the following sample request:

curl -X GET "https://<publicapi_url>/rest/api/v1/Departments" 
     -H  "accept: application/json" 
	 -H  "X-Api-Key: <API Key>"

This request will provide us with a list of available agencies:

{
  "resultCount": 3,
  "totalResults": 3,
  "skippedResults": 0,
  "results": [
    {
      "id": "departments-677-A",
      "name": "Arnhem"
    },
    {
      "id": "departments-674-A",
      "name": "Den Haag"
    },
    {
      "id": "departments-676-A",
      "name": "Ede"
    }
}	

Note that for this request, the tenantId is not needed

After selecting the correct tenantId (departmentId), for example the candidates of the selected agency can be retrieved using the following sample request where the selected tenantId is put in the X-Tenant-Id header:

curl -X GET "https://<publicapi_url>/rest/api/v1/Candidates" 
    -H  "accept: application/json" 
	-H  "X-Api-Key: <API Key>"
	-H 'X-Tenant-Id: departments-677-A' 

Sample Response

{
  "resultCount": 2,
  "totalResults": 2,
  "skippedResults": 0,
  "results": [
    {
      "id": "candidates-12258-A",
      "name": "Scott Hanselman"
    },
    {
      "id": "candidates-11047-A",
      "name": "Mark Russinovich"
    }
}

Note: for non MCE versions the X-tenant-Id header is obsolete

None: for the following endpoints is the X-tenant-Id header not applicable:

• https://<publicapi_url>/rest/api/v1/Departments
• https://<publicapi_url>/rest/api/v1/Users
• https://<publicapi_url>/rest/api/v1/WebHookFilters
• https://<publicapi_url>/rest/api/v1/WebHookRegistrations

Ownership

Each document in Cockpit has an owner. For each request posted to the PublicAPI, an owner object needs to be included in the request. An owner object consist of the following properties:

• OwnerId - Id of the user which becomes the owner of the document
• OwnerDepartmentId - Id of the department which becomes the owner of the document

Sample request with ownership

curl -X POST "http://<publicapi_url>/rest/api/v1/Candidates" 
     -H  "accept: application/json" 
	 -H  "X-Api-Key: <API Key>" 
	 -H  "Content-Type: application/json" -d"
{
  "owner": {
    "userId": "users-cfc4d7da-41e3-4fa8-a7a6-524fa8c72edd",
    "departmentId": "departments-41-A"
  },
  "firstName": "Mark",
  "middleName": null,
  "lastName": "Russinovich",
  ..........................................}"

MatchFields

Updateable RecruitNow Cockpit objects, including candidates, companies, applications, etc require so called matchfields in a request body. Matchfields are reference data that is used in the Cockpit matching process to match candidates to vacancies and vice versa.
A matchfield contains a value and type.

To get the available matchfield types, use the following sample request:

curl -X GET "https://<publicapi_url>/rest/api/v1/MatchFields/types"
-H "accept: application/json"
-H "X-Api-Key: <API Key>"

This will provide us with al list of all the matchfield types

[
"ContractType",
"EmploymentType",
"JobType",
"EducationLevel",
"ExtendedEducationLevel",
"JobRequestCreationReason",
"ExperienceLevel",
"Sector",
"Category",
"ProfessionalLevel",
"WorkingDay",
"IntellectualAbilityLevel",
"DriversLicense",
"MeanOfTransport",
"ISCO08-4",
"ISCO08-3",
"ISCO08-2",
"ISCO08-1",
"Country",
"Region",
"SalaryInterval",
"Origin",
"NoticePeriod",
"ShiftServices",
"JDCOCode",
"PublicationChannel",
"RNCOCode"
]

With this list we can list matchfields on a certain type, for example, to list all the employment types available in Cockpit, use the following sample:

curl -X GET "https://<publicapi_url>/rest/api/v1/MatchFields?type=EmploymentType"
-H "accept: application/json"
-H "X-Api-Key: <API Key>"

Sample Response

{
  "resultCount": 2,
  "totalResults": 2,
  "skippedResults": 0,
  "results": [
    {
      "id": "MatchFields-10-A",
      "name": "Full time"
    },
    {
      "id": "MatchFields-11-A",
      "name": "Part time"
    }
  ]
}

to get the details of a a matchfield, run the following sample:

Retrieve matchfield by id

curl -X GET "https://<publicapi_url>/rest/api/v1/MatchFields/MatchFields-10-A"
-H "accept: application/json"
-H "X-Api-Key: <API Key>"

Response

{
  "id": "MatchFields-10-A",
  "name": "Full time",
  "type": "EmploymentType"
}

The following example request shows how to use the matchfields in a request body to insert or update for example a candidate in Cockpit using the PublicAPI

curl -X POST "https://<publicapi_url>/rest/api/v1/Candidates"
     -H "accept: application/json"
     -H "X-Api-Key: <API Key>"
     -H "Content-Type: application/json" -d"
     {
       "owner": 
       {
         "userId": "users-cfc4d7da-41e3-4fa8-a7a6-524fa8c72edd",
         "departmentId": "departments-41-A"
       },
       "firstName": "Mark",
       "middleName": null,
       "lastName": "Russinovich",
       "initials": "M",
       "remoteId": "string",
       "gender": "Male",
       "dateOfBirth": "1966-12-22",
       "address": 
       {
         "street": "Hogeweg",
         "housenumber": 182,
         "housenumberSuffix": null,
         "zipcode": "3815LZ",
         "city": "Amersfoort",
         "countryCode": "NL",
         "region": "Utrecht"
       },
       "primaryEmailAddress": "mark.russinovich@microsoft.com",
       "primaryPhoneNumber": 
       {
         "number": "033-1234567",
         "countryCode": "NL"
       },
       "primaryMobilePhoneNumber": 
       {
         "number": "06-12345678",
         "countryCode": "NL"
       },
       "preference": 
       {
         "sectors": [
           {
             "id": "MatchFields-99-A"
           },
           {
             "id": "MatchFields-994-A"
           },
        ],
        "functions": [
          {
            "id": "MatchFields-11090-A"
          }
       ],
       "contractTypes": [
         {
           "id": "MatchFields-1089-A"
         },
         {
           "id": "MatchFields-13-A"
         }
      ],
      "workingDays": [
        {
          "id": "MatchFields-116-A"
        },
        {
          "id": "MatchFields-117-A"
        },
        {
          "id": "MatchFields-121-A"
        }
      ],
      "noticePeriod": 
      {
        "id": "MatchFields-1058-A"
      },
      "availableFrom": "2021-07-15T13:56:34.918Z",
      "travelDistance": 5,
      "hoursPerWeek": 
      {
        "min": 10,
        "max": 23
      }
    },
    "experience": 
    {
      "driversLicenses": [
        {
          "id": "MatchFields-63-A"
        },
        {
          "id": "MatchFields-62-A"
        }
      ],
      "meansOfTransport": [
        {
          "id": "MatchFields-71-A"
        },
        {
          "id": "MatchFields-73-A"
        }
      ],
      "experienceLevel": 
      {
        "id": "MatchFields-2-A"
      },
      "educationLevel": 
      {
        "id": "MatchFields-76-A"
      },
      "intellectualAbilityLevels": [
        {
          "id": "MatchFields-85-A"
        }
      ],
      "professionalLevels": [
        {
          "id": "MatchFields-8-A"
        },
        {
          "id": "MatchFields-9-A"
        }
      ]
    }
  }"

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list candidates, list companies, and list matchfields. These list API methods share a common structure, taking these three parameters: limit, start, and filter.

The Public API utilizes cursor-based pagination via the start and limit parameters. Both parameters take a numeric value. The filter parameter filters the fetched documents based on the value of the filter parameter.

Sample request with pagination:

curl -X GET "https://<publicapi_url>/rest/api/v1/Candidates?start=10&limit=10&filter=Test"
-H "accept: application/json"
-H "X-Api-Key: <API Key>"

Each 'list' request can contain the following parameters

Versioning

When backwards-incompatible changes are made to the API, a new version is released. The current version is v1.
The version number is part of the request to the PublicAPI.

Sample current version:

https://<publicapi_url>/rest/api/v1/candidates

If for example version v2 is released, the rest request will be:

https://<publicapi_url>/rest/api/v2/candidates

The old version v1 will still be available for backwards-compatibility

Workflow Status/Creating companies with an active status

When creating Job Requests, it is mandatory that the provided company has an active status. Right now it is not possible to manipulate the status of an entity via an endpoint. One exception is made for creating companies. It is possible to provide an initial status while creating a company.

Query the following endpoint to retrieve the available workflow statuses:

https://<publicapi_url>/rest/api/v1/WorkflowStatus?type=<type>

Webhooks

for documentation about the PublicAPI and webhooks, go to the webhooks section by selection the link below.

Documentation about Webhooks