Connecting to LinkedIn...

Overview

This guide shows how data can be imported and exported from the Volcanic Platform using our secure API, bespoke Apps, and our powerful Developer Console.

How to use the Volcanic Platform API

To POST data into the Volcanic Platform API, or to GET data from our API, you will need a valid API Key and a valid URL for the relevant website. To request an API Key, please contact Volcanic ( support@volcanic.co.uk ) and we will send you a valid API Key and the base URL for the relevant website - for example:

http://abc-website.production.volcanic.uk

Once the website is live, if it is using an SSL certificate, we recommend you change the URL you send requests to so that they are encrypted to ensure security of data - for example:

https://abc-website.com

When you begin integrating with the Volcanic Platform REST based API, you can see the response of your API requests in the website’s Developer Console to help with any debugging needed. There are no rate limits on API requests.

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/jobs.json \
  -H 'Content-Type: application/json' \
  -d '{"job":{"api_key":"e1328e043a08472ebb7396d68ee49697", "job_title":"New Job", "job_type":"permanent", "discipline":"sector-1"}}'

Jobs

The Volcanic Platform stores Job details in a flexible and uniquely powerful way to enable accurate and fast Job searching on our websites.

Jobs on our Platform contain the basic information such as title, Job reference, Job description, business sector, location, salary and more. Jobs can also be assigned to specific Clients and Consultants within your website.

Custom categories allow additional data to be assigned to Job listings which can then be used to filter by when performing a Job search.

Getting Job data into the Volcanic Platform

API

The Volcanic Platform offers a secure and stable API for getting data into the Platform for any of the websites we host. Any 3rd Party with a valid API Key (provided by Volcanic) can post Job data to your website by sending the required data to the Job Create API address.

3rd party Job Posting tools such as Broadbean, Idibu and LogicMelon are already integrated with our API and successfully post thousands of Job details to the Volcanic Platform every day. The Job Create API parameters required are listed against the endpoint below.


Jobs Index

GET → /api/v1/jobs.json
GET → /api/v1/jobs.xml

Parameters

search
optional
This will limit the jobs returned to those matching the search query
Example Values:
Testing Engineer
search[disciplines_all]
optional
Sending any value for this parameter will return matching jobs from all disciplines
Example Values:
true
search[job_types_all]
optional
Sending any value for this parameter will return matching jobs from all job types
Example Values:
true
per_page
optional
By default this request will return 5 jobs per page of results. Include a value to increase the number of jobs returned per page.
Example Values:
10
page
optional
Include a value to select which page of results should be returned
Example Values:
2

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/jobs.json \
  -H 'Content-Type: application/json'

Example Responses

{  
   "total":1,
   "page_count":1,
   "current_page":1,
   "jobs":[  
      {  
         "application_email":"bob.12345.123@smith.aplitrak.com",
         "application_url":null,
         "benefits":null,
         "cached_slug":"test-engineer-6",
         "client_id":null,
         "contact_email":"bob@smith.com",
         "contact_name":"Bob Smith",
         "contact_telephone":"020 7987 6900",
         "contact_url":null,
         "created_at":"2014-02-19T12:54:00.000Z",
         "dataset_id":8,
         "discipline_id":null,
         "exclusive_until":null,
         "expiry_date":"2014-03-21",
         "hot":true,
         "id":84,
         "job_description":"This is the detailed description",
         "job_duration":"6 Months",
         "job_industry":null,
         "job_location":"London",
         "job_reference":"abc123",
         "job_startdate":"ASAP",
         "job_title":"Test Engineer",
         "job_type":null,
         "job_type_id":null,
         "keyword_cache":"abc123 test engineer",
         "lat":"51.5112139",
         "lng":"-0.1198244",
         "retired":false,
         "retired_at":null,
         "salary_benefits":"Bonus and Pension",
         "salary_currency":"GBP",
         "salary_free":"£25000 - £330000 per annum + Bonus and Pension",
         "salary_hidden":null,
         "salary_high":25000,
         "salary_low":30000,
         "salary_per":"annum",
         "segment_id":null,
         "unique_id":null,
         "updated_at":"2014-02-27T12:54:51.000Z",
         "views":6
      }
   ],
   "pagination_html":"\u003cnav class='pagination'\u003e\n\n\n\u003cspan class='page current'\u003e\n1\n\u003c/span\u003e\n\n\u003cspan class='page'\u003e\n\u003ca data-remote=\"true\" href=\"/api/v1/jobs.json?api_key=d3ae49b87f1d23627b949acac66ee232\u0026amp;page=2\" rel=\"next\"\u003e2\u003c/a\u003e\n\u003c/span\u003e\n\n\u003cspan class='page'\u003e\n\u003ca data-remote=\"true\" href=\"/api/v1/jobs.json?api_key=d3ae49b87f1d23627b949acac66ee232\u0026amp;page=3\"\u003e3\u003c/a\u003e\n\u003c/span\u003e\n\n\u003cspan class='page'\u003e\n\u003ca data-remote=\"true\" href=\"/api/v1/jobs.json?api_key=d3ae49b87f1d23627b949acac66ee232\u0026amp;page=4\"\u003e4\u003c/a\u003e\n\u003c/span\u003e\n\n\u003cspan class='page'\u003e\n\u003ca data-remote=\"true\" href=\"/api/v1/jobs.json?api_key=d3ae49b87f1d23627b949acac66ee232\u0026amp;page=5\"\u003e5\u003c/a\u003e\n\u003c/span\u003e\n\n\u003cspan class='page gap'\u003e\n\u0026hellip;\n\u003c/span\u003e\n\n\u003cspan class='next'\u003e\n\u003ca data-remote=\"true\" href=\"/api/v1/jobs.json?api_key=d3ae49b87f1d23627b949acac66ee232\u0026amp;page=2\" rel=\"next\"\u003eNext \u0026rsaquo;\u003c/a\u003e\n\u003c/span\u003e\n\n\u003cspan class='last'\u003e\n\u003ca data-remote=\"true\" href=\"/api/v1/jobs.json?api_key=d3ae49b87f1d23627b949acac66ee232\u0026amp;page=85\"\u003eLast \u0026raquo;\u003c/a\u003e\n\u003c/span\u003e\n\n\u003c/nav\u003e\n"
}

Show job

GET → /api/v1/jobs/office-manager.json?api_key=e1328e043a08472ebb7396d68ee49697
GET → /api/v1/jobs/office-manager.xml?api_key=e1328e043a08472ebb7396d68ee49697

Retrieve an individual job vacancy

Parameters

Info
There are no parameters for this request

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/jobs.json?api_key=e1328e043a08472ebb7396d68ee49697 \
  -H 'Content-Type: application/json'

Example Responses

{  
   "id":190213,
   "dataset_id":231,
   "discipline_id":null,
   "job_type_id":531,
   "views":26,
   "contact_name":"Sally Jane Miller",
   "contact_email":"sally.miller@beyond.co.nz",
   "contact_telephone":"+64 21 192 7456",
   "contact_url":"",
   "application_email":"permanentak@beyond.co.nz",
   "application_url":"",
   "job_reference":"AK47043",
   "job_title":"Senior Account Manager",
   "job_type":{  
      "name":"Permanent",
      "id":531,
      "dataset_id":231,
      "position":0,
      "cached_slug":"permanent-144",
      "retired":false,
      "retired_at":null,
      "created_at":"2016-02-04T08:44:07.000Z",
      "updated_at":"2016-02-24T12:12:03.000Z",
      "reference":"permanent"
   },
   "job_startdate":"",
   "job_description":"Marketing Internship position available...",
   "job_location":"Auckland - Manukau and East Auckland",
   "job_industry":null,
   "lat":"-36.9941017",
   "lng":"174.87266",
   "created_at":"2016-06-22T10:31:00.000Z",
   "updated_at":"2016-06-24T09:21:49.000Z",
   "expiry_date":"2016-07-24",
   "cached_slug":"senior-account-manager",
   "retired":false,
   "retired_at":null,
   "salary_free":"",
   "keyword_cache":"marketing internship",
   "salary_high":90000,
   "salary_low":70000,
   "salary_hidden":null,
   "hot":true,
   "benefits":null,
   "client_id":null,
   "exclusive_until":null,
   "unique_id":null,
   "segment_id":null,
   "job_duration":"",
   "salary_currency":null,
   "salary_per":"0",
   "salary_benefits":"",
   "user_id":null,
   "extra":null,
   "paid":null,
   "applications_count":0,
   "source":"data_source_24",
   "deleted_at":null,
   "salary_id":null,
   "currency_id":null,
   "base_all_location_id":null,
   "remote_id":null
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}

Create/Update Job

POST → /api/v1/jobs.json
POST → /api/v1/jobs.xml

Parameters

All parameters need to be nested within a 'job' parameter. For example: job: { api_key: '123' ... }.

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
job_title
required
string
This is required and will be used to generate a user friendly URL when the job is created. Max 255 characters.
Example Values:
Test Engineer
job_type
required
string
Usually 3 job types are setup: contract, permanent and temp. This required field must match up againt job types configured within the admin area which can by retrieved from the Job Type API endpoint.
Example Values:
contract
discipline
required
string
Include a comma seperated list of disciplines to assign the job to multiple disciplines. You can include the discipline ID (e.g. 34) or discipline reference (e.g. hr) which can by retrieved from the Disciplines API endpoint.

A minimum of 1 valid discipline is required.
Example Values:
hr,34,35
client_id
string
Should be a single Client ID. A list of clients associated with your site can be found on the Clients API endpoint.

To remove a client association from an existing job set the client_id to "0" or and empty string. If the client_id is invalid the Job will be created/updated with no client association.

Example Values:
"34"
job_reference
optional
string
Usually displayed within search results and on the job show page. This field is used to determine if the Job being POSTed already exists and if so, updates that Job.
Example Values:
WRT234-12
job_duration
optional
string
Presented in plain text form to the user. Maybe used within the search results and usually displayed on the job show page.
Example Values:
6 Months
job_startdate
optional
string
Presented in plain text form to the user.
Example Values:
ASAP, Within 3 Months
job_description
optional
text
Although this field is not required it is stongly recommended that you always include a job description. Embedded HTML is allowed and will be displayed within the job descripiton.

The preview text used within the search results will display a truncated, sanitised version of this job description.
Example Values:
This is the <b>detailed</b> description
lat
optional
float
You can optionally set the latitude for this job. This will be automatically be calculated based on the job_location if omitted.
Example Values:
53.345987
lng
optional
float
You can optionally set the longitude for this job. This will be automatically be calculated based on the job_location if omitted.
Example Values:
1.234543
job_location
optional
string
This is usually displayed on the job search results page and on the job show page. If you don't specify lat, lng data the job_location field will also be used to geo-locate the job.
Example Values:
London, SK4 1NN
salary_free
optional
string
A free text version of the salary, currenty + benefits. This is displayed to the user.
Example Values:
£35-37k per annum + company car
salary_low
optional
integer
Lowest offered Salary. For a job £35-37k, this field would be 35000.
Example Values:
35000
salary_high
optional
integer
Highest offered Salary. For a job £35-37k, this field would be 37000.
Example Values:
37000
salary_currency
optional
string
Multicurrency sites only - this is used within the advanced search. This is not necessarily displayed to the user, as they are presented with salary_free
Example Values:
GBP
salary_benefits
optional
string
Benefits that are offered in addition to the salary.
Example Values:
Company Car + Pension
contact_name
optional
string
The Individual's name who is advertising the job.
Example Values:
Robert Wilde
contact_email
optional
string
This email is displayed on the job show page next to the contact name. This is not used for job application emails.
Example Values:
bob.smith@example.com
contact_telephone
optional
string
Displayed on the job show page.
Example Values:
0161 217 1517
application_email
optional
string
Not displayed to the user. This email is used as the sole recipient for job applications.
Example Values:
bob.12345.123@smith.aplitrak.com
days_to_advertise
optional
integer
The number of days to advertise the job for. When the job is created the expiry date is calculated based on the number of days to advertise. Default value: 30
Example Values:
30
seo_location_id
optional
integer
Include a single ID of the Custom location to link to this job. You must include the ID value which can by retrieved from the SEO Locations API endpoint.
Example Values:
44
job_titles
optional
string
Include a comma seperated list of job title IDs to indicate the job titles that relate to this job. Job title IDs can by retrieved from the Available Job Attributes API endpoint.
Example Values:
3,12
languages
optional
string
Include a comma seperated list of languages to indicate the language in which the job is written. You must include the language reference which can by retrieved from the Language API endpoint.
Example Values:
english
remote_id
optional
string
Optional value by which to identify a job, this will usually be a unique id held on your own system. This value will be used in preference to job_reference.
Example Values:
de12cf

Job Boards

client_token
required
string
The client token of the employer who is POSTing the job. The employer can retrieve their client token from their account on the Job Board.
Example Values:
123asd456
job_functions
required
string
Include a comma seperated list of job functions to assign the job to multiple job functions. You can include the job function ID (e.g. 34) or job function reference (e.g. hr) which can by retrieved from the Job Function API endpoint.

A minimum of 1 valid job function is required if your site uses job functions.
Example Values:
admin,34,35


Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/jobs.json \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"e1328e043a08472ebb7396d68ee49697", "job":{"job_title":"New Job", "job_type":"permanent", "discipline":"sector-1"}}'

Example Responses

{
  "response": {
    "status": "success",
    "job_url": "http://abc-website.production.volcanic.uk/jobs/test-engineer",
    "alerts": "",
    "updating_existing_job": true,
    "created_at": "2016-06-24 13:53:13 UTC"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "status": "error",
    "reason": "Your JSON or XML was incomplete",
    "errors": "Disciplines can't be blank",
    "updating_existing_job": false,
    "created_at": null
  }
}

Expire Job

POST → /api/v1/jobs/expire.json
POST → /api/v1/jobs/expire.xml

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
job_reference
required
string
This is required and will be used to identify the job to expire.
Example Values:
WD1223-201
remote_id
optional
string
Optional value by which to identify a job, this will usually be a unique id held on your own system. This value will be used in preference to job_reference.
Example Values:
de12cf

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/jobs/expire.json \
  -H 'Content-Type: application/json' \
  -d '{"job":{"api_key":"e1328e043a08472ebb7396d68ee49697", "job_reference":"WD1223-201"}}'

Example Responses

{
  "response": {
    "message": "Job Successfully Expired (WD1223-201)",
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "message": "Job Doesn't Exist (job_reference: WD1223-201)",
    "status": "error"
  }
}

Delete Job

POST → /api/v1/jobs/delete.json
POST → /api/v1/jobs/delete.xml

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
job_reference
required
string
This is required and will be used to identify the job to delete. You can also provide the job ID.
Example Values:
WD1223-201, 21
remote_id
optional
string
Optional value by which to identify a job, this will usually be a unique id held on your own system. This value will be used in preference to job_reference.
Example Values:
de12cf

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/jobs/delete.json \
  -H 'Content-Type: application/json' \
  -d '{"job":{"api_key":"e1328e043a08472ebb7396d68ee49697", "job_reference":"WD1223-201"}}'

Example Responses

{
  "response": {
    "message": "Job Successfully Deleted (WD1223-201)",
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "message": "Job Doesn't Exist (job_reference: WD1223-201)",
    "status": "error"
  }
}

Available Job Attributes

GET → /api/v1/available_job_attributes.json?api_key=e1328e043a08472ebb7396d68ee49697
GET → /api/v1/available_job_attributes.xml?api_key=e1328e043a08472ebb7396d68ee49697

This endpoint will give you a complete set of values for the main attributes that are used when creating a job. It may be that not all attributes have values set, where this is the case these attributes are not required.

Parameters

Info
There are no parameters for this request

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/available_job_attributes.json?api_key=e1328e043a08472ebb7396d68ee49697 \
  -H 'Content-Type: application/json'

Example Responses

{  
  "disciplines":{  
    "name":"Disciplines",
    "attribute":"discipline",
    "response_format":"comma-separated string",
    "values":[  
       {  
          "id":2334,
          "name":"Senior Management Positions",
          "reference":"senior-management",
          "children":null
       },
       {  
          "id":4213,
          "name":"Executive Search",
          "reference":"executive-search",
          "children":null
       },
       {  
          "id":8427,
          "name":"Service Management",
          "reference":"service-management",
          "children":null
       }
    ]
  },
  "job_functions":{  
    "name":"Job Functions",
    "attribute":"job_functions",
    "response_format":"comma-separated string",
    "values":[  

    ]
  },
  "job_titles":{  
    "name":"Job Titles",
    "attribute":"job_titles",
    "response_format":"comma-separated string",
    "values":[  
       {  
          "id":8247,
          "name":"UX Designer"
       },
       {  
          "id":8299,
          "name":"Vendor Manager"
       },
       {  
          "id":8293,
          "name":"VP Engineering"
       },
       {  
          "id":8281,
          "name":"Windows Engineer"
       }
    ]
  },
  "clients": {
    "name": "Clients",
    "attribute": "client_id",
    "response_format": "single ID",
    "values": [
      {
        "id": 123,
        "name": "Volcanic"
      },
      {
        "id": 124,
        "name": "EventBeat"
      }
    ]
  },
  "custom_1":{  
    "name":"Domain",
    "attribute":"custom_1",
    "response_format":"comma-separated string",
    "values":[  
       {  
          "id":106,
          "name":"Banking",
          "reference":"banking",
          "children":null
       },
       {  
          "id":107,
          "name":"Defence",
          "reference":"defence",
          "children":null
       }
    ]
  },
  "job_types": {
    "name": "Job Types",
    "attribute": "job_type",
    "response_format": "single reference string",
    "values": [
      {
        "id": 226,
        "name": "Permanent",
        "reference": "permanent"
      },
      {
        "id": 227,
        "name": "Temporary",
        "reference": "temporary"
      },
      {
        "id": 228,
        "name": "Contract",
        "reference": "contract"
      }
    ]
  },
  "languages": {
    "name": "Languages",
    "attribute": "languages",
    "response_format": "comma-separated string",
    "values": [
      {
        "id": 3,
        "name": "English",
        "reference": "english"
      },
      {
        "id": 4,
        "name": "Français",
        "reference": "fr"
      }
    ]
  },
  "extra_categorisation_filters": {
    "name": "Extra Categorisation Filters",
    "attribute": "extra_categorisation",
    "response_format": "comma-separated string",
    "values": [
      {
        "reference": "gb"
      },
      {
        "reference": "fr"
      },
      {
        "reference": "es"
      }
    ]
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}

Job Types

GET → /api/v1/job_types.json?api_key=e1328e043a08472ebb7396d68ee49697
GET → /api/v1/job_types.xml?api_key=e1328e043a08472ebb7396d68ee49697

Parameters

Info
There are no parameters for this request

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/job_types.json?api_key=e1328e043a08472ebb7396d68ee49697 \
  -H 'Content-Type: application/json'

Example Responses

[
    {
        "id": "123",
        "name": "Permanent",
        "reference": "permanent"
    },
    {
        "id": "456",
        "name": "Contract",
        "reference": "contract"
    },
    {
        "id": "789",
        "name": "Temporary",
        "reference": "temp"
    }
]
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}

Create Job Type

POST → /api/v1/job_types.json
POST → /api/v1/job_types.xml

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
name
required
string
This is required and will be displayed to the user. Max 255 characters.
Example Values:
Permanent
reference
required
string
Permanent string used to identify the job type. Max 255 characters.
Example Values:
permanent

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/job_types.json \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"e1328e043a08472ebb7396d68ee49697", "job_type":{ "name":"Permanent", "reference":"permanent"}}'

Example Responses

{  
  "response": {  
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "status": "error",
    "reason": "Your JSON or XML was incomplete",
    "errors": "Reference can't be blank"
  }
}

Job Functions

GET → /api/v1/job_functions.json?api_key=e1328e043a08472ebb7396d68ee49697
GET → /api/v1/job_functions.xml?api_key=e1328e043a08472ebb7396d68ee49697

Parameters

Info
There are no parameters for this request

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/job_functions.json?api_key=e1328e043a08472ebb7396d68ee49697 \
  -H 'Content-Type: application/json'

Example Responses

[
  {
    "id":10,
    "reference":"business-analysis",
    "name":"Business Analysis",
    "parent_id":null,
    "position":0
  },
  {
    "id":24,
    "reference":"consultancy",
    "name":"Consultancy",
    "parent_id":null,
    "position":1
  },
  {
    "id":31,
    "reference":"customer-services",
    "name":"Customer Services",
    "parent_id":null,
    "position":2
  }
]
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}

Create Job Function

POST → /api/v1/job_functions.json
POST → /api/v1/job_functions.xml

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
name
required
string
This is required. Max 255 characters.
Example Values:
Administration
position
required
integer
Used to display the job_functions in this order
Example Values:
3
reference
required
string
Permanent string used to identify the job_functions. When posting a job via the API, you can use this reference string to assign the job to multiple job_functions (comma seperated).
Example Values:
admin

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/job_functions.json \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"e1328e043a08472ebb7396d68ee49697", "job_function":{ "name":"Administration", "reference":"admin", "position":"3"}}'

Example Responses

{  
  "response": {  
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "status": "error",
    "reason": "Your JSON or XML was incomplete",
    "errors": "Reference can't be blank"
  }
}

Disciplines

GET → /api/v1/disciplines.json?api_key=e1328e043a08472ebb7396d68ee49697
GET → /api/v1/disciplines.xml?api_key=e1328e043a08472ebb7396d68ee49697

Parameters

Info
There are no parameters for this request

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/disciplines.json?api_key=e1328e043a08472ebb7396d68ee49697 \
  -H 'Content-Type: application/json'

Example Responses

[
    {
        "id": 29,
        "name": "Main Contractors",
        "parent_id": 42,
        "position": 3,
        "reference": "main_contractors"
    },
    {
        "id": 30,
        "name": "Specialist Trades",
        "parent_id": 42,
        "position": 4,
        "reference": "specialist_trades"
    },
    {
        "id": 31,
        "name": "Mechanical & Electrical",
        "parent_id": 42,
        "position": 5,
        "reference": "mechanical_electrical"
    }
]
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}

Create Discipline

POST → /api/v1/disciplines.json
POST → /api/v1/disciplines.xml

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
name
required
string
The display name of the discipline. Max 255 characters.
Example Values:
Human Resources
position
required
integer
Used to display the disciplines in this order
Example Values:
3
reference
required
string
Permanent string used to identify the disciplines. When posting a job via the API, you can use this reference string to assign the job to multiple disciplines (comma seperated).
Example Values:
hr

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/disciplines.json \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"e1328e043a08472ebb7396d68ee49697", "discipline":{"name":"Human Resources", "reference":"hr", "position":"3"}}'

Example Responses

{  
  "response": {  
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "status": "error",
    "reason": "Your JSON or XML was incomplete",
    "errors": "Reference can't be blank"
  }
}

Custom Locations

GET → /api/v1/seo_locations.json?api_key=e1328e043a08472ebb7396d68ee49697
GET → /api/v1/seo_locations.xml?api_key=e1328e043a08472ebb7396d68ee49697

Parameters

Info
There are no parameters for this request

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/seo_locations.json?api_key=e1328e043a08472ebb7396d68ee49697 \
  -H 'Content-Type: application/json'

Example Responses

[  
   {  
      "id":1919,
      "name":"UK Regions",
      "parent_id":null,
      "position":null,
      "lat":"53.091139",
      "lng":"-2.426358",
      "type":"Regions",
      "content":""
   },
   {  
      "id":1920,
      "name":"Overseas",
      "parent_id":null,
      "position":null,
      "lat":"53.4781587",
      "lng":"-2.2499947",
      "type":"Regions",
      "content":null
   },
   {  
      "id":2023,
      "name":"UK Cities",
      "parent_id":null,
      "position":null,
      "lat":"51.4280216",
      "lng":"-0.0374146",
      "type":"Regions",
      "content":""
   },
   {  
      "id":1921,
      "name":"London (Greater)",
      "parent_id":1919,
      "position":null,
      "lat":"51.5073509",
      "lng":"-0.1277583",
      "type":"Counties",
      "content":null
   }
]
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}

Create Custom Location

POST → /api/v1/seo_locations.json
POST → /api/v1/seo_locations.xml

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
name
required
string
This is required. Max 255 characters.
Example Values:
Manchester
content
optional
integer
Text content to display if you have a custom template that supports it.
Example Values:
Lorem Ipsum ...
parent_id
optional
integer
ID of the SEO Location that is the parent of this SEO Location in the hierarchy
Example Values:
123
lat
optional
string
Latitude value to use for this SEO location. override_lat_lng must be set to true to use this.
Example Values:
52.094758
lng
optional
string
Longitude value to use for this SEO location. override_lat_lng must be set to true to use this.
Example Values:
-0.2357262
override_lat_lng
optional
boolean
Enables override of Lat/Long calculations and uses supplied values instead.
Example Values:
true
id
optional
integer
If the ID of an existing SEO location is passed in here, then that SEO location will be updated with the provided values. If left blank, excluded, or contains an invalid ID, then a new record with be created instead.
Example Values:
123

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/seo_locations.json \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"e1328e043a08472ebb7396d68ee49697", "seo_location":{ "name":"Manchester", "content":"Lorem Ipsum ..."}}'

Example Responses

{  
  "response": {  
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "status": "error",
    "reason": "Your JSON or XML was incomplete",
    "errors": "Name can't be blank"
  }
}

Salaries

POST → /api/v1/salaries.json
POST → /api/v1/salaries.xml
Create a salary

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
name
required
string
This is required and will be used to generate a user friendly URL when the job is created. Max 255 characters.
Example Values:
£20-30k
lower
required
integer
Lower salary range
Example Values:
20000
upper
required
integer
Upper salary range
Example Values:
30000

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/salaries.json \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"e1328e043a08472ebb7396d68ee49697", "salary":{ "name":"£20-30k", "lower":"20000", "upper":"30000"}}'

Example Responses

{  
  "response": {  
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "status": "error",
    "reason": "Your JSON or XML was incomplete",
    "errors": "Name can't be blank"
  }
}

Searches

GET → /api/v1/searches/search.json?api_key=e1328e043a08472ebb7396d68ee49697
GET → /api/v1/searches/search.xml?api_key=e1328e043a08472ebb7396d68ee49697
Retrieve a search

Parameters in URL

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
search[query]
optional
string
This is the string of Keywords to search against.
Example Values:
Management, Accountancy, Ruby Developer
search[location]
optional
string
This is the location to base the search on.
Example Values:
London, SW1A 1AA, Chester
search[discipline]
optional
integer
This is the id for the selected Discipline.
Example Values:
123
search[job_type]
optional
integer
This is the id for the selected Job Type.
Example Values:
321
page
optional
integer
This is the page number for the results needed.
Example Values:
3

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/searches.json?api_key=e1328e043a08472ebb7396d68ee49697&search[location]=London&page=1 \
  -H 'Content-Type: application/json'

Example Responses

{
  "results": [
    {
      "job_reference": "Office Assistant",
      "job_title": "Office Assistant",
      "job_type": "Internship",
      "startdate": "ASAP",
      "job_description": "Great Job in great location...",
      "job_location": "Shoreditch, London",
      "salary_free": "",
      "cached_slug": "office-assistant",
      "user": {
        "id": 1234,
        "registration_answer_hash": {
          "where-did-you-hear-about-us-3": "Other",
          "receive-newsletter": "Ticked"
        }
      }
    },
    {
      "job_reference": "",
      "job_title": "Graduate Project Manager",
      "job_type": "Full Time",
      "startdate": "August/September 2013",
      "job_description": "Project Manage your heart out...",
      "job_location": "London, E1.",
      "salary_free": "£25K plus generous performance related commission.",
      "cached_slug": "graduate-project-manager",
      "user": {
        "id": 5678,
        "registration_answer_hash": {
          "where-did-you-hear-about-us-3": "Twitter ",
          "receive-newsletter": "Ticked"
        }
      }
    },
    {
      "job_reference": "IT Support Engineer 1",
      "job_title": "IT Support Engineer",
      "job_type": "Full Time",
      "startdate": "ASAP",
      "job_description": "Support our IT folks...",
      "job_location": "London",
      "salary_free": "Competitive",
      "cached_slug": "it-support-engineer-1",
      "user": {
        "id": 9876,
        "registration_answer_hash": {
          "where-did-you-hear-about-us-3": "Google",
          "receive-newsletter": "Ticked"
        }
      }
    }
  ],
  "page": "1"
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}

Candidates

The Volcanic Platform requires the following core data from all Candidates: first name, last name, email address, password and terms and conditions response. Candidates are also able to upload an avatar image and a CV document for their account. If they register through LinkedIn, the Volcanic Platform also stores the recent Work History information from their LinkedIn account.

Additional custom registration questions can be created to gather further information when Candidates register or update their details.

The above data is able to be pushed into the Volcanic Platform, or retrieved in the various ways described below.

Getting Candidate data into the Volcanic Platform

Candidates can be imported to the Volcanic Platform using the API with a valid API Key. Candidate data can also be updated via the API allowing the ability to synchronise data between 3rd Party CRM tools and your website. The parameters which can be posted to the API to update Candidate data are listed against the endpoint below.

Getting Candidate data out of the Volcanic Platform and the Candidate Dead Drop

Candidate data can be queried via the user retrieve API endpoint, however for a more complete integration the Volcanic platform can send a rich payload of candidate information as users complete actions such as registration or job application. We refer to this as a Candidate Dead Drop


Retrieve a user

GET → /api/v1/users/123.json?api_key=e1328e043a08472ebb7396d68ee49697
GET → /api/v1/users/123.xml?api_key=e1328e043a08472ebb7396d68ee49697

Parameters in URL

remote_id
optional
string
Optional value by which to identify a user, this will usually be a unique id held on your own system. This value will be used in preference to the user id.
Example Values:
de12cf

Example Request

curl -X GET -i http://abc-website.production.volcanic.uk/api/v1/users/123.json?api_key=e1328e043a08472ebb7396d68ee49697 \
  -H 'Content-Type: application/json'

Example Responses

{
  "id": 123,
  "email": "name@example.com",
  "user_type": "candidate",
  "first_name": "Fred",
  "last_name": "Mercury",
  "avatar_url": "/s3/W1siZiIsIjIwMTQvMDUvMDEvMTEvMjEvMDEvOTg3L1Byb2ZpbGVfUGljdHVyZS5qcGci123",
  "registration_answer_hash": {
    "facebook-profile-url": "https://www.facebook.com/blah.blah",
    "gender": "Male",
    "eligible-to-live-and-work-in-the-uk": "Ticked"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}

Registration Questions

POST /api/v1/registration_questions.json
POST /api/v1/registration_questions.xml
Create a registration question

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
label
required
string
The label for the question
Example Values:
Hobbies
question_type
required
string
The type of question
Allowed Values:
'Text', 'Number', 'Text Box', 'Radio Buttons', 'Horizontal Radio Buttons', 'Checkbox', 'Multi-Checkbox', 'Horizontal Multi-Checkbox', 'Drop Down', 'Multi-Select Drop Down', 'File Upload', 'Date', 'Discipline Drop Down', 'Location Autosuggest', 'Location Autosuggest - Cities Only'
hint
string
A hint displayed along with the question
Example Values:
Any activities you get up to in your spare time

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/registration_questions.json \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"e1328e043a08472ebb7396d68ee49697", "registration_question":{ "label":"Hobbies", "question_type":"string", "hint":"Any activities you get up to in your spare time"}}'

Example Responses

{  
  "response": {  
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "status": "error",
    "reason": "Your JSON or XML was incomplete",
    "errors": "Label can't be blank"
  }
}

Registrations

POST → /api/v1/users.json
POST → /api/v1/users.xml
Register a candidate

Parameters

api_key
required
A valid API Key is required for this request. API Keys can be requested from Volcanic: support@volcanic.co.uk.
Example Values:
e1328e043a08472ebb7396d68ee49697
user[email]
required
string
This is required and will be used to authenticate the User. Max 255 characters.
Example Values:
test@example.com
user[password]
required
string
This is required and will be used to authenticate the User. Min 8 characters.
Example Values:
passw0rd
user[password_confirmation]
required
string
This is required and must be the same as the password field. Min 8 characters.
Example Values:
passw0rd
remote_id
optional
string
Optional value by which to identify a user, this will usually be a unique id held on your own system. This value will be used in preference to the user id.
Example Values:
de12cf
user[terms_and_conditions]
required
boolean
This is required and must be true.
Example Values:
true
user[user_type]
optional
string
This will be used to set the user_type od the User record. Useful if the site has multiple user types.
Example Values:
graduate
user[user_profile_attributes][first_name]
required
string
This is required.
Example Values:
William
user[user_profile_attributes][last_name]
required
string
This is required.
Example Values:
Shatner
user[registration_answers_attributes][registration_id]
required if registration_answers_attribute exists
integer
This value corresponds to the Registration Question which the answer is in response to.
Example Values:
123
user[registration_answers_attributes][answer]
required if registration_answers_attribute exists
string
This is the answer the User gives for the related Registration Question
Example Values:
England

Example Request

curl -X POST -i http://abc-website.production.volcanic.uk/api/v1/users.json \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"e1328e043a08472ebb7396d68ee49697", "user":{"email":"test2@example.com", "password":"passw0rd", "password_confirmation":"passw0rd", "terms_and_conditions":true, "user_type":"graduate", "user_profile_attributes":{"first_name":"Ben", "last_name":"Gibbs"}, "registration_answers_attributes":[{"registration_question_id":"51", "answer":"name@exampledomain.com"}, {"registration_question_id":"222", "answer":"Geoff"}, {"registration_question_id":"281", "answer":"Facebook"}, {"registration_question_id":"79", "answer":"Ticked"}]}}'

Example Responses

{  
  "response": {  
    "status": "success"
  }
}
{
  "response": {
    "status": "Unauthorised",
    "reason": "Your API key is not valid."
  }
}
{
  "response": {
    "status": "error",
    "reason": "Your JSON or XML was incomplete",
    "errors": "Email can't be blank"
  }
}

Platform Status

The status of the Volcanic Platform API and Developer Console is published publicly on our status page: http://status.volcanic.co.uk

Our status page also shows the response time of our Platform, the Error rate and the Throughput (rate of requests). We also publish details of any Incidents which affects the Platform’s functionality.