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/v2/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:

Component	Description
The HTTP Method	`GET`. Requests data from a resource. `POST`. Submits data to a resource to process. `PUT`. Updates a resource. `PATCH`. Partially updates a resource. `DELETE`. Deletes a resource.
The URL to the API service	https://<publicapi_url>/rest/api/v2 The <publicapi_url> depends on the customer environment and is provided by RecruitNow.
The URI to the resource	The resource to query, submit data to, update, or delete. For example, companies/companies-12-A/companycontacts
Query parameters	Optional. Use to filter, limit the size of the data in an API response.
A JSON request body	Required for most `POST`, `PUT`, and `PATCH` calls.

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:

Status code	Description
`200 OK`	The request succeeded.
`201 Created`	A `POST` method successfully created a resource. If the resource was already created by a previous execution of the same method, for example, the server returns the HTTP `200 OK` status code.
`204 No Content`	The server successfully executed the method but returns no response body.

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:

Status code	Cause
`400 Bad Request`	The server could not understand the request.
`403 Forbidden`	The client is not authorized to access this resource although it might have valid credentials.
`404 Not Found`	The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available.
`405 Method Not Allowed`	The service does not support the requested HTTP method.
`406 Not Acceptable`	The server cannot use the client-request media type to return the response payload.
`415 Unsupported Media Type`	The API cannot process the media type of the request payload.
`500 Internal Server Error`	A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server.

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/v2/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.

Select the GET method.
Enter the https://<publicapi_url>/rest/api/v2/companies request URL.
On the 'Headers' tab, add the X-API key header with the supplied API key
Click Send.
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/v2/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/v2/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/v2/Departments
https://<publicapi_url>/rest/api/v2/Users
https://<publicapi_url>/rest/api/v2/WebHookFilters
https://<publicapi_url>/rest/api/v2/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/v2/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/v2/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/v2/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/v2/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/v2/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"
        }
      ]
    }
  }"

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

Parameter	Description
start	specifies the number of documents to skip in the resultlist. If this parameter is not provided or left empty the value = 0
limit	specifies the maximum number of documents to fetch. If this parameter is not provided or left empty, the maximum number of documents retrieved in one single call = 100. Maximum value of this parameters = 1000
filter	Text based filter to filter the contents of the retrieved documents for existance of the text specified in the filter.

Versioning

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

Sample Version 1:

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

Sample Version 2:

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

The old version v2 will still be available for a transition period 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/v2/WorkflowStatus?type=<type>

Parameter	Description
type	The type of the entity for which the workflow status is used. Currently only "Company" is supported.

Webhooks

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

Documentation about Webhooks

Browser not supported