Introduction

Getting Started

Our Careers Page API is a RESTful-based API designed to help you integrate your Careers Page with your organisation's website.

By connecting your Employment Hero Careers Page to your organisation's website, any new job ads or edits to existing job ads will be available on your website.

Base URL: https://api.employmenthero.com

Obtain API Access Token

To get started, you'll need to generate an API Access Token. You can do this by:

Clicking 'General Settings' on the left-hand menu

Selecting 'Recruitment Settings'

Ensuring that you've enabled your Careers Page, you should now be able to see your API Access Token

API Access Token

ATS API

Get Countries

Returns a collection of the countries listed in the role for an organisation

GET

https://api.employmenthero.com/ats/api/v1/embedded/organisations/:organisation_id/countries

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

Query Parameters

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

A hash with a data property that contains an item array of the countries listed in the role for an organisation. Each entry in the array is a separate country object.

dataobject

itemsobject[]

idstring

The country code

namestring

The country name

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X GET \  "https://api.employmenthero.com/ats/api/v1/embedded/organisations/:organisation_id/countries" \  -H "X_ATS_TOKEN: a9207tx3NBr8L-bEi9Ed-g"

Response

{  "data": {    "items": [      {        "id": "AU",        "name": "Australia"      },      {        "id": "NZ",        "name": "New Zealand"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 2,    "total_pages": 1  }}

Get Departments

Returns a collection of the public departments for an organisation

GET

https://api.employmenthero.com/ats/api/v1/embedded/organisations/:organisation_id/departments

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

Query Parameters

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

A hash with a data property that contains an item array of public departments for an organisation. Each entry in the array is a separate department object.

dataobject

itemsobject[]

iduuid

The ID of the department

namestring

The name of the department

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X GET \  "https://api.employmenthero.com/ats/api/v1/embedded/organisations/:organisation_id/departments" \  -H "X_ATS_TOKEN: a9207tx3NBr8L-bEi9Ed-g"

Response

{  "data": {    "items": [      {        "id": "aa477f75-6e62-4f5d-abc0-7ef7542e4fb6",        "name": "Engineer"      },      {        "id": "aa477f76-6c64-4f5e-acc2-7e4f542e4fb8",        "name": "Marketing"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 2,    "total_pages": 1  }}

Get Roles

Returns a collection of the public jobs for an organisation

GET

https://api.employmenthero.com/ats/api/v1/embedded/organisations/:organisation_id/jobs

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

Query Parameters

querystring

Query string to filter

country_codesstring[]

The array of country codes to filter

department_idsstring[]

The array of department ids to filter

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

A hash with a data property that contains an item array of public jobs for an organisation. Each entry in the array is a separate job object.

dataobject

itemsobject[]

titlestring

The title of the job

departmentstring

The department of the job

industrystring

The industry of the job

remoteboolean

Whether the job is remote

country_codestring

The country code of the job

country_namestring

The country name of the job

citystring

The city of the job

employment_type_namestring

The employment type of the job

employment_term_namestring

The employment term of the job

experience_level_namestring

The experience level of the job

hide_pay_rateboolean

Whether the pay rate is hidden

salary_currencystring

The currency of the job

salary_minnumber

The minimum salary of the job

salary_maxnumber

The maximum salary of the job

salary_rate_namestring

The rate of the salary of the job

descriptionstring

The description of the job

created_atdatetime

The date and time when the job was created

recruitment_logostring

The logo of the job

application_urlstring

The URL to apply for the job

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X GET \  "https://api.employmenthero.com/ats/api/v1/embedded/organisations/:organisation_id/jobs" \  -H "X_ATS_TOKEN: a9207tx3NBr8L-bEi9Ed-g"

Response

{  "data": {    "items": [      {        "title": "Senior full stack Developer",        "department": "Engineer",        "industry": "Aerospace",        "remote": false,        "country_code": "AU",        "country_name": "Australia",        "city": "Sydney, New South Wales 2000",        "employment_type_name": "Full-time",        "employment_term_name": "Permanent",        "experience_level_name": "Associate",        "hide_pay_rate": false,        "salary_currency": "AUD",        "salary_min": 50000,        "salary_max": 100000,        "salary_rate_name": "Annum",        "description": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.",        "created_at": "2021-04-14T03:27:17Z",        "recruitment_logo": "https://eh.com/logo.png",        "application_url": "https://jobs.employmenthero.com/jobs/97c42fdb-8af9-4f58-9d16-fe3fed472a85"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}