EthicalJobs Autoposter (XML) API

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 note 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 Jobs' end.

Core Resources

Create a Job

POSThttps://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 indicating 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. You may now provide more than one location by including multiple `<location>` elements (one location slug per element). A single `<location>` element is still accepted. See the location vocabulary for valid slugs.
worktype (string)	The type of work, e.g. parttime, fulltime. More than one may be provided by including multiple `<worktype>` elements.
classification (string)	The classification for the job ad, e.g. socialenterprise. More than one may be provided by including multiple `<classification>` elements.
sector (string)	The sector that your job ad is in. Can be one of: socialenterprise, notforprofit, forprofit. More than one may be provided by including multiple `<sector>` elements.

What’s new: multiple locations. The API now accepts more than one location for a job ad. Provide each location as its own <location> element, using the slug from the location vocabulary below — the same way <worktype>, <classification> and <sector> already work. A single <location> element continues to work exactly as before, so existing integrations do not need to change.

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

One or more locations may be supplied. Include a separate <location> element for each location, using the slug below.

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

Request

Headers

Header	Value
Content-Type	application/xml
X-EJ-Authorization	your-api-key

Example request body

This example posts a job ad in two locations (Sydney and Melbourne) by including two <location> elements. It also shows multiple <worktype>, <classification> and <sector> values, which follow the same repeated-element pattern.

JavaScript&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;job&gt;
    &lt;employerid&gt;EthicalJobs&lt;/employerid&gt;
    &lt;jobid&gt;7865gd68729h982j32d2938498h&lt;/jobid&gt;
    &lt;title&gt;This is the job title&lt;/title&gt;
    &lt;description&gt;This is the job description, its a little bit longer.&lt;/description&gt;
    &lt;body&gt;&lt;![CDATA[This is the job body, its a little bit longer then the description.]]&gt;&lt;/body&gt;
    &lt;toapply&gt;&lt;![CDATA[This is how to apply for this job &lt;a href="http://seek.com.au"&gt;apply here&lt;/a&gt;]]&gt;&lt;/toapply&gt;
    &lt;hide-expiry&gt;false&lt;/hide-expiry&gt;
    &lt;featured&gt;true&lt;/featured&gt;
    &lt;closingdate&gt;2016-12-25 20:35&lt;/closingdate&gt;
    &lt;location&gt;NSW&lt;/location&gt;
    &lt;location&gt;VIC&lt;/location&gt;
    &lt;worktype&gt;FULLTIME&lt;/worktype&gt;
    &lt;worktype&gt;PARTTIME&lt;/worktype&gt;
    &lt;classification&gt;communicationsandmarketing&lt;/classification&gt;
    &lt;classification&gt;fundraising&lt;/classification&gt;
    &lt;sector&gt;socialenterprise&lt;/sector&gt;
    &lt;sector&gt;Not For Profit (NFP)&lt;/sector&gt;
&lt;/job&gt;

Single location still works. If a job ad has only one location, simply include a single <location> element, for example <location>NSW</location>.

Responses

201 Created

A successful request returns the created job ad as JSON. When multiple locations are supplied, they are returned in the location_ids array (alongside categories, workTypes and sectors, which behave the same way).

JavaScript{
    "source": "AUTOPOST",
    "source_id": "7865gd68729h982j32d2938498h",
    "source_provider": "N/A",
    "organisation_uid": "EthicalJobs",
    "title": "This is the job title",
    "summary": "This is the job description, its a little bit longer.",
    "description": "This is the job body, its a little bit longer then the description.",
    "application": "This is how to apply for this job &lt;a href=\"http://seek.com.au\"&gt;apply here&lt;/a&gt;",
    "featured": 1,
    "expiration_hidden": 0,
    "location_ids": [
        "NSW",
        "VIC"
    ],
    "categories": [
        "communicationsandmarketing",
        "fundraising"
    ],
    "workTypes": [
        "FULLTIME",
        "PARTTIME"
    ],
    "sectors": [
        "socialenterprise",
        "Not For Profit (NFP)"
    ],
    "expires_at": 1482698100000,
    "id": 80474
}

403 Forbidden

JavaScript{
    "message": "403 Forbidden",
    "statusCode": 403
}

Staging Environment

A staging environment is available for testing your integration before going live. It behaves the same as production — post the same XML job body (see above), using your staging API key.

POSThttps://api.staging.ethicalstg.com.au/xml/jobs

Headers

Header	Value
Content-Type	application/xml
X-EJ-Authorization	your-staging-api-key

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.