Quick Start

Quickly get up an running by creating a candidate and apply to a vacancy using the REST API in our sandbox system.

Scenario

Create a candidate application using Oleeo’s REST API in our sandbox system with the interactive Swagger documentation.

In this scenario we will create a candidate application for a vacancy.

  1. Authenticate a user for Swagger for a system (default sandpit)
  2. Add a candidate user
  3. Create an initial application for the candidate to a vacancy
  4. Add application details

Swagger Interactive Documentation

Open the REST API page and you will be initially assigned the sandbox system to try out the API calls.

This page will display all the available endpoints grouped under headings such as Applications.

Click the Authorize button with the padlock and provide your username and password. (Contact your Oleeo representative if you don’t have these.)

Once authorised you will be able to interact with the swagger documentation and make calls to the endpoints.

A simple endpoint to test is the GET /{appType} which gets a list of applications. Follow these steps:

  1. From the REST API page scroll to the applications heading and click to expand the available endpoints.
  2. Select GET ​/{appType} from the list to expand it and Click Try it out button. Scroll down and click the Execute button below the optional attributes being displayed.
  3. You should then see the Responses, along with the Curl and Request URLs you can use in your code or via tools such as the Postman API client if you wish.
  4. Note if you haven’t authorised correctly you’ll most likely see a 401 response - Error Unauthorized.

If you’d rather use your own Oleeo Recruit system rather than the sandbox provided, Click the CHANGE SYSTEM button. You will need to know the URL of your ATS and it’s associated authorisation credentials.

Add a candidate user

The first step is to create a candidate by calling the POST /candidates ENDPOINT.

Find the candidates header in the Swagger document and click to expose the associated endpoints. Select the POST /candidates endpoint and then click try it out.

For this simple exercise use something like the body shown opposite in the code panel and enter it into the Request body -> Candidate details text area.

Click Execute button to POST these details to the API endpoint.

The response will return the candidateID which can then be used in the next step to assign that candidate against a specific vacancy.

POST /candidates - Add a candidate user
Request body:
{
  "GivenName": "Bobby",
  "FamilyName": "Smith",
  "Email": [
    {
      "Address": "bobby@example.com",
      "Label": "personal",
      "Preferred": "primary"
    }
  ],
  "UserArea": {
    "UsernameEmail": "bobby@example.com"
      }
}

Response body:
{
  "CandidateID": "46",
  "Email": [
    {
      "Address": "bobby@example.com"
    }
  ],
  "CandidateURI": "https://developer-portal-base-config.tal.net/vx/api/v1/candidates/46",
  "GivenName": "Bobby",
  "FamilyName": "Smith",
  "UserArea": {
    "RegistrationDateTime": "2021-11-18T10:56:49Z",
    "UsernameEmail": "bobby@example.com"
  }
}

Add a candidate application

The next step is to create an initial application between the candidate and the vacancy by calling the POST /vacancies/{vacancyId}/applications ENDPOINT. See the Candidates & Applications concept for more information on the differences between an application and a candidate.

In the swagger document find the vacancies header in the Swagger document and click to expose the associated endpoints. Select the POST /vacancies/{vacancyId}/applications endpoint and then click try it out.

For this exercise use vacancy id 1 which is an Implementation Consultant. This id is used in the call as shown opposite. In Swagger the id is entered as a parameter in the Vacancy Id text box.

To view other vacancies call the GET ​/vacancies endpoint to review a list of vacancies in the system.

POST ​/vacancies​/1​/applications

Request body:
{
  "candidate_id": 46
}

Response body
{
  "application": {
    "id": 47,
    "url": "https://developer-portal-base-config.tal.net/vx/api/v1/applications/47",
    "vacancy": {
      "url": "https://developer-portal-base-config.tal.net/vx/api/v1/vacancies/1",
      "id": 1,
      "title": "Implementation Consultant"
    },
    "user": {
      "lastname": "smith",
      "firstname": "bobby",
      "id": 46,
      "email": "bobby@example.com",
      "url": "https://developer-portal-base-config.tal.net/vx/api/v1/candidates/46"
    },
    "process_state": {
      "rules": [
        {
          "form_id": 13686,
          "id": 88,
          "label": "Add candidate form",
          "default_action": "progress",
          "action_type": "WCN::DBIC::AbstractForm::ApplicationForm"
        }
      ],
      "state": {
        "id": 162,
        "title": "Manually added, application not complete",
        "url": "https://developer-portal-base-config.tal.net/vx/api/v1/states/162",
        "is_terminal": false
      },
      "process": {
        "id": 12,
        "title": "Standard Application Process"
      },
      "actions": [
        "progress"
      ]
    },
    "votes": {
      "rank": 0,
      "up_count": 0,
      "votes_store": "Candidate",
      "my_vote": null,
      "count": 0,
      "down_count": 0
    },
    "submitted_dt": null
  }
}

Add application details

The final step is to add any details you have for the application. The fields to populate will depend on how your system’s application forms have been configured. In this simple example we’ll use an add candidate short form that’s been added to the system which has an id of 13686.

In the swagger document find the applications header in the Swagger document and click to expose the associated endpoints. Select the POST ​/{appType}​/{appId}​/form_values endpoint and then click try it out.

In order to update the relevant forms/form items you’ll of course first need to know their corresponding IDs/values. For this exercise we’ll use address line 1 which is item id:8 and city which is item id:329

POST /applications/47/form_values

Request body:
{
  "log_history": true,
  "transaction": [
    {
      "item_id": 8,
      "values": [
        {
          "instance": 1,
          "value": "15 The Street",
          "log_history": false
        }
      ]
    },
    {
      "item_id": 329,
      "values": [
        {
          "instance": 1,
          "value": "London",
          "log_history": false
        }
      ]
    }
  ]
}

Request body:
{
  "msg": "Form values succesfully updated"
}
Finally we can check the values were added by calling GET applications/47/form_values with Form id attribute set to 13686
GET /applications/47/form_values?form=13686
[
  {
    "values": [
      {
        "value": "bobby@example.com",
        "instance": 1,
        "form_instance": 1
      }
    ],
    "item": {
      "data_type": "FREETEXT",
      "title": "Personal Details - Email",
      "id": 3,
      "code": null
    }
  },
  {
    "item": {
      "data_type": "FREETEXT",
      "title": "Personal Details - Address Line 1",
      "code": null,
      "id": 8
    },
    "values": [
      {
        "value": "15 The Street",
        "instance": 1,
        "form_instance": 1
      }
    ]
  },
  {
    "values": [
      {
        "instance": 1,
        "form_instance": 1,
        "value": "London"
      }
    ],
    "item": {
      "code": null,
      "id": 329,
      "title": "Personal Details - City/Town",
      "data_type": "FREETEXT"
    }
  }
]