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.