Introduction
The Ethical Jobs XML API is designed to translate from XML input to JSON output to maintain compatibility with a wide range of job posting distribution systems.
Our API has predictable, resource-oriented URLS and uses standard HTTP response codes to indicate API errors.
We use simple API Key based authentication and only the HTTP POST verb to create new Job ads. JSON is returned by all API responses including errors.
Authentication
Authenticate your account when using the API by including your secret API key in the request. API keys can be organised by contacting your relationships manager. Do not share your secret API key in any publicly accessible areas such as GitHub, client-side code or public repositories.
Authentication to the API is performed by simply including the X-EJ-Authorization header in your request with your API key as the value. All requests to the API must also include your organisation username in the body of the request as the employerid.
All API requests must be made over HTTPS. Please not that calls made over plain HTTP will fail. API requests without any authentication headers will also fail with a 403 Forbidden error.
Errors
Ethical Jobs uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Ethical Jobs' servers.
HTTP status code summary
Status Code | Summary |
201 Created | Success, a new job was created. |
403 Forbidden | The API key was not provided or is invalid. |
404 Not Found | The XML API url is wrong. |
422 Unprocessable Entity | Unable to process the entity in question. Could be due to not setting the content type or due to providing a source ID. |
500, 502, 503, 504 - Server Errors | Something went wrong on Ethical Job's end |
Core Resources
POST /xml/jobs
https://api.ethicaljobs.com.au/xml/jobs
Jobs
To create a new advertisement with Ethical Jobs, you create a Job object. You can only create objects and not retrieve or edit them. Jobs are uniquely identified by their provided jobid.
The Job Object
Attributes
Attribute | Description |
|---|---|
jobid (string) required | A unique identifier for your job ad. |
employerid (string) required | A unique username for your organisation, is provided by your relationships manager. |
title (string) | The title for your job ad. |
description (string) | The description of your job ad. |
body (string) | The main body of the job ad, can contain HTML. |
toapply | Instructions for how to apply for the job ad, can contain HTML. |
hide-expiry (boolean) | Flag indicating if you want the expiry date hidden or shown |
featured (boolean) | Flag indiciating if you would like your job ad to be featured. Featuring an ad costs an extra job credit. |
closingdate (timestamp) | Time at which the job ad should close. The timestamp must be provided in the UTC timezone without any timezone offset. Use the ISO 8601 format for the timestamp, e.g., 2024-03-27T20:35:00 |
location (string) | The location for the job |
worktype (string) | The type of work e.g. parttime, fulltime |
classification (string) | The classification for the job ad e.g. socialenterprise |
sector (string) | The sector that your job ad is in. Can be one of: socialenterprise, notforprofit, forprofit |
Vocabularies
It is best to use the slug in your XML to ensure data integrity.
classification
Title | Slug |
|---|---|
Administration | administration |
Advocacy and Campaigns | advocacy |
Aged Care and Seniors Rights | agedcare |
Alcohol and Other Drugs | alcoholandotherdrugs |
Animal Welfare and Protection | animalwelfareandprotection |
Business Development and Sales | businessdevelopment |
Care and Support Work | careandsupportservices |
Co-ops and Credit Unions | coopsandcreditunions |
Communications and Marketing | communicationsandmarketing |
Community Development | communityanddevelopment |
Conservation and Land Management | conservationandmanagement |
Corporate Social Responsibility | corporatesocialresponsibility |
Disability Services | disabilityservices |
Early Childhood | earlychildhood |
Eco-Tourism | ecotourism |
Education and Training | educationandtraining |
Environment and Sustainability | environmentandsustainability |
Executive and Senior Management | executiveseniormanagement |
Family Services | familyservices |
FairTrade and Organic | fairtradeorganicandecoretail |
Finance and Accounting | financeandaccounting |
Fundraising | fundraising |
LGBTQIA+ | glbt |
Green Architecture/Property | greenarchitectureandproperty |
Green Energy | greenenergy |
Green Products and Services | greenproductsandservices |
Health Care and Allied Health | healthcare |
Health Promotion | healthpromotion |
Housing and Homelessness | housing |
Retail and Hospitality | retailandhospitality |
HR and Employment Services | hrandemploymentservices |
Indigenous | indigenous |
International Aid and Development | internationalaidandevelopment |
Information Technology & Digital | itandcommunicationtechnology |
Legal and Human Rights | legalandhumanrights |
Management | management |
Media and Arts | mediaartsandentertainment |
Medical Research | medicalresearch |
Mental Health and Counselling | mentalhealthandcounselling |
Multiculturalism and Diversity | multiculturalismdiversity |
Nursing | nursing |
Operations and Risk Management | operationsriskmanagement |
Organic Farming and Gardening | organicfarmingandgardening |
Policy and Research | policyandresearch |
Project Management | projectmanagement |
Recycling and Waste Management | recyclingandwastemanagement |
Social Work | socialwork |
Sustainable Transport | sustainabletransport |
Trades and Services | tradesandservices |
Unions and Workers Rights | unionsandworkersrights |
Volunteer Management | volunteermanagement |
Womens Organisations and Services | womensorganisationsandservices |
Youth | youthservices |
Domestic & Family Violence | domesticfamilyviolence |
Events Management | events |
location
Title | Slug |
|---|---|
Melbourne | VIC |
Regional VIC | REGVIC |
Sydney | NSW |
Regional NSW | REGNSW |
Brisbane & Gold Coast | QLD |
Regional QLD | REGQLD |
Perth | WA |
Regional WA | REGWA |
Adelaide | SA |
Regional SA | REGSA |
Hobart | TAS |
Regional TAS | REGTAS |
Darwin | NT |
Regional NT | REGNT |
Canberra & ACT | ACT |
International | INTERNATIONAL |
worktype
Title | Slug |
|---|---|
Casual | CASUAL |
Contract | CONTRACT |
Full Time | FULLTIME |
Graduate | GRADUATE |
Part Time | PARTTIME |
Volunteer | VOLUNTEER |
Board Member | BOARDMEMBER |
Remote / Work from home | REMOTE |
sector
Title | Slug |
|---|---|
Business/Private Sector | Business and Private Sector |
Federal Government | Federal Government |
Local Government | Local Government |
Not For Profit (NFP) | Not For Profit (NFP) |
Social Enterprise | socialenterprise |
State Government | State Government |
University & Higher Education | university |
HEADERS
Content-Type application/xml
X-EJ-Authorization your-api-key
Body raw
POST Staging - XML API - Post Example
https://api.staging.ethicalstg.com.au/xml/jobs
Jobs
See above.
HEADERS
Content-Type application/xml
X-EJ-Authorization qweqweasdasdzxczxc
Body raw
Example request
Example response
Making edits to a job ad already live on EthicalJobs.com.au
Jobs that were previously sent to EthicalJobs.com.au via the XML API, which are currently live on the site, can be updated on the original platform and re-submitted with the updates to EthicalJobs.com.au via the XML API.
When updating a live job ad with edits, ensure the submitted job:
Has all required fields complete (not just the updated fields)
Has the same EmployerID and JobID as the live job
This will not result in additional job ad credit charges. Unless the update is to Feature the job ad, or adding additional locations.