JobRelay integration

This page outlines how to integrate with JobRelay and is relevant for any Applicant Tracking Service wanting to integrate with the JobRelay service.

The JobRelay job feed requires your API to send one job at a time to the JobRelay endpoint in a JSON format.

The JobRelay endpoint

Each job should be posted to the JobRelay endpoint URL which is:

https://jobrelay.io/api/jobrelay/

The feed consists of a number of required and optional fields which are outlined below.

Anyone posting a job to job relay must include the following fields in the feed. These fields are necessary to validate the JobRelay user so that we know they are a valid user and which site to send on the job to.

Required fields

JSON nodeData typeExample valueNotes
subscription_idinteger1The client subscription ID with JobRelay. This can be found on their subscriptions page in “My Account”.
license_keystringdfdf343fsfThe license key assigned to the JobRelay user when they signed up. This should be included in their welcome email but can also be found on the purchase history page
site_urlstring/urlhttps://site.url/The URL of the site to which this users jobs should be ‘relayed’ too. Users should first add this site to their JobRelay My Account > Purchase history > View licenses > Manage sites area.
job_referencestringREF-123A unique reference assigned to this job.
job_titlestringWordPress DeveloperThe job title – no HTML allowed.
job_descriptionstringthe main description of the job. It can contain the following HTML elements
<img>
<a>
<strong>
<em>
<ul>
<ol>
<li>
commandstringaddWither add, update or delete.
application_emailstringtracking123@site.urlThis is the email address used to track applications to this job.
application_urlstringhttps://site.url/apply?job=12334The URL of the application form for this job, if not using a tracking email address.

It is worth noting that the subscription_id, license_key and site_url are the same for a client for every job they send. Therefore it makes sense that somewhere in the user account on your system, these can be added once and they attached to the feed for each job, rather than having the user add them each time when writing a job.

If any of the above fields are missing when a job is posted, or the field is sent but is empty, the job will fail once it reaches the JobRelay service. It will not be “relayed” onto the client site.

Optional fields

As well as the required fields above, there are a number of optional fields that can be sent across and will there be added to the job. These are outlined below.

JSON nodeData typeExample valueNotes
job_short_descriptionstring
contact_namestringJane SmithThe recruiters name.
contact_emailstringjane.smith@mail.comThe recruiters email
contact_telephonestring01234567890The recruiters telephone number.
contact_urlstring/urlhttps://site.urlThe recruiters website URL.
company_namestringJobRelayThe company name where the position is.
company_taglinestringRelaying JobsThe company tagline where the position is.
company_websitestring/urlhttps://jobrelay.ioThe company website where the position is.
company_twitterstring@jobrelayThe company twitter handle where the position is including the @ symbol.
company_logostring/urlhttps://img.com/im.jpgThe company logo where the position is. This should be a hosted image URL.
company_videostring/urlhttps://youtube.com/videoidA link to a video on a video sharing site such as Youtube.
expiry_datedate2020-12-01When the job expires or no longer takes applications. Should be in the format of YYY-MM-DD.
start_datedate2021-01-10When the job starts. Should be in the format of YYY-MM-DD.
salary_currencystringGBPCurrency code for the salary
salary_fromfloat10000A number (float) for the lower salary.
salary_tofloat15000A number (float) for the upper salary.
salary_perstringannumFor more information please see our Default Values.
salary_benefitsstringLaptop & healthcareFreetext, additional salary information.
salaryfloat15000A number (float) for the salary.
featuredboolean11 to mark as featured or 0 (default) to not be featured.
job_locationstringLondon, UK
job_typestringContractA pipe (|) separated list of job types.
job_industrystringITA pipe (|) separated list of job industries.
job_sourcestringAwesome Job Posting ServiceA string representing the source of the job (where it was written). For example Broadbean, LogicMelon or Idibu
custom_datastringSome custom dataThis is an open text field for any additional information.

Example JSON

Adding/posting a job

{  
	"command":"add",
	"subscription_id":"1",
	"license_key":"22f7b1d3411f741d851457d83c6bd3de",
	"site_url":"jobrelayclient.test/",
	"job_reference":"abc123",
	"job_title":"Test Engineer",
	"job_description":"<p>This is the <strong>detailed</strong> <a href=\"#\">description</a></p>",
	"job_short_description":"<p>This is the short description.</p>",
	"contact_name":"Bob Smith",
	"contact_email":"bob@smith.com",
	"contact_telephone":"020 7987 6900",
	"contact_url":"www.smith.com",
	"company_name":"Highrise Digital",
	"company_website":"https://url.com",
	"company_tagline":"WordPress development",
	"company_twitter":"@highrisedigital",
	"company_logo":"https://highrise.digital/content/uploads/2018/08/wordpress-development-team-150x150.jpg",
	"company_video":"https://www.youtube.com/watch?v=w-vBUGsLXEQ",
	"expiry_date":"2019-12-10",
	"start_date":"2019-12-31",
	"application_email":"bob.12345.123@smith.aplitrak.com",
	"application_url":"http://www.url.com/ad.asp?adid=12345123",
	"salary_currency":"GBP",
	"salary_from":"25000",
	"salary_to":"30000",
	"salary_per":"annum",
	"salary_benefits":"Bonus and Pension",
	"salary":"£25000 - £30000 per annum + Bonus and Pension",
	"featured":"1",
	"job_location":"London",
	"job_type":"Contract",
	"job_industry":"Marketing",
        "job_source":"Broadbean"
}

Response

{
    "status": "success",
    "source": "client",
    "action": "added",
    "job_id": "52",
    "message": "The job was added with a URL of http://jobrelayclient.test/job/test-engineer-52/.",
    "notes": []
}

The job_id in the response is the unique job ID the job has on the website. This is optional, but your system could then save that job ID and use that in any update or delete commands.

If this is used, the job reference must be sent as well.

Editing or updating a job

{  
	"command":"add",
	"subscription_id":"1",
	"license_key":"22f7b1d3411f741d851457d83c6bd3de",
	"site_url":"jobrelayclient.test/",
	"job_reference":"abc123",
        "job_id": "52",
	"job_title":"Test Engineer",
	"job_description":"<p>This is the <strong>detailed</strong> <a href=\"#\">description</a></p>",
	"job_short_description":"<p>This is the short description.</p>",
	"contact_name":"Bob Smith",
	"contact_email":"bob@smith.com",
	"contact_telephone":"020 7987 6900",
	"contact_url":"www.smith.com",
	"company_name":"Highrise Digital",
	"company_website":"https://url.com",
	"company_tagline":"WordPress development",
	"company_twitter":"@highrisedigital",
	"company_logo":"https://highrise.digital/content/uploads/2018/08/wordpress-development-team-150x150.jpg",
	"company_video":"https://www.youtube.com/watch?v=w-vBUGsLXEQ",
	"expiry_date":"2019-12-10",
	"start_date":"2019-12-31",
	"application_email":"bob.12345.123@smith.aplitrak.com",
	"application_url":"http://www.url.com/ad.asp?adid=12345123",
	"salary_currency":"GBP",
	"salary_from":"25000",
	"salary_to":"30000",
	"salary_per":"annum",
	"salary_benefits":"Bonus and Pension",
	"salary":"£25000 - £30000 per annum + Bonus and Pension",
	"featured":"1",
	"job_location":"London",
	"job_type":"Contract",
	"job_industry":"Marketing",
        "job_source":"Broadbean"
}

Again, not the job_id is optional, depending on whether you are saving this value from the job added response.

Response

{
    "status": "success",
    "source": "client",
    "action": "updated",
    "job_id": "52",
    "message": "The job was added with a URL of http://jobrelayclient.test/job/test-engineer-52/.",
    "notes": []
}

Deleting a job

{  
	"command":"delete",
	"subscription_id":"1",
	"license_key":"22f7b1d3411f741d851457d83c6bd3de",
	"site_url":"jobrelayclient.test/",
	"job_reference":"abc123"
}

Response

{
    "status": "success",
    "source": "client",
    "action": "deleted",
    "message": "The job titled Test Engineer with the ID of 52 was successfully deleted."
}

Querying for field listings

As some of the fields in the feed may have a set list of options the client wants to choose from, your integration needs to query for these options in order to populate your interface with them.

The clients site (where the job is relayed on to) has an endpoint to show the field listings. The endpoint URL is:

{site_url}/jobrelay/field-listings

Where {site_url} is the site url of the client site (where the job is posted too) as saved in their clients user profile.

Response

{
  "job_type": {
    "2": "Full Time",
    "3": "Part Time",
    "4": "Temporary",
    "5": "Freelance",
    "6": "Internship",
    "8": "Contract"
  },
  "job_industry": {
    "9": "Marketing"
  }
}

The response is a JSON multidimensional array. In the array you will find each field name that has specific field listings. Inside each array of the field listing options for that field as an array with the key being the internal idea and the value the field option label.

When sending data to these fields for adding or updating a job, the ID is not needed. The value can be sent. The IDs here are purely for reference if needed.

We would recommend that the endpoint is queried for every field on the write job screen (this request could be cached for a number of minutes/hours).