Skip to content

Where companies and creative professionals meet to make a better web.™

API Documentation

Provided below is documentation for the implementation and use of the official Authentic Jobs API. You need your own API key to use the Authentic Jobs API, and you can request an API key here if you haven't already done so. Please feel free to join our official mailing list as well.

The Basics

Every call to the AJ API consists of the following:

  • The base URL is: http://www.authenticjobs.com/api/
  • An API key, passed as the parameter api_key (e.g. api_key=a446a0eefe6f5699283g34f4d5b51fa0). You can request an API key from the application page
  • The method to call, passed as the parameter method (e.g. method=aj.jobs.search). See the methods section below for a list of available methods.
  • An (optional) response format, passed as the parameter format. Valid formats are: rest, json, and php. The default is rest.
  • All requests must currently be GET requests
  • All replies are in utf8

Response Formats

There are currently three valid response formats: rest, json, and php. The default format is rest.

rest

Example:

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<categories>
	<category id="1" name="Design" />
	<category id="2" name="Development" />
</categories>
</rsp>

json

Example:

{"categories":{"category":[{"id":"1","name":"Design"},{"id":"2","name":"Development"}]},"stat":"ok"}

php

The php response format is serialized php. Simply call unserialize() on the response to get a php array. Example:

a:2:{s:10:"categories";a:1:{s:8:"category";a:2:{i:0;a:2:{s:2:"id";s:1:"1";s:4:"name";s:6:"Design";}i:1;a:2:{s:2:"id";s:1:"2";s:4:"name";s:11:"Development";}}}s:4:"stat";s:2:"ok";}

Methods

aj.jobs.getCompanies

Returns a list of companies that are currently advertising positions.

Parameters:

  • category: The id of a job category to limit to. See aj.categories.getList
  • type: The id of a job type to limit to. See aj.types.getList
  • sort: Accepted values are: date-posted-desc (the default) and date-posted-asc
  • company: Free-text matching against company names. Suggested values are the ids from aj.jobs.getCompanies
  • location: Free-text matching against company location names. Suggested values are the ids from aj.jobs.getLocation
  • telecommuting: Set to 1 if you only want telecommuting jobs
  • keywords: Keywords to look for in the title or description of the job posting. Separate multiple keywords with commas. Multiple keywords will be treated as an OR
  • begin_date: Unix timestamp. Listings posted before this time will not be returned
  • end_date: Unix timestamp. Listings posted after this time will not be returned

Example:

http://www.authenticjobs.com/api/?api_key=a446a0eefe6f5699283g34f4d5b51fa0&method=aj.jobs.getcompanies

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<companies>
	<company id="86peoplelimited" name="86 People Limited" url="http://www.86people.com" />
	<company id="academiaedu" name="Academia.edu" url="http://www.academia.edu">
		<location id="sanfranciscocaus" name="Wayne, NJ" city="San Francisco" country="US" lat="37.7749" lng="-122.419" state="CA" />
	</company>
	<company id="aiderss" name="AideRSS" url="http://www.aiderss.com/">
		<location id="waterloooncanada" name="Waterloo, ON, Canada" />
	</company>
	<company id="allianceforcommunitytrees" name="Alliance for Community Trees" url="http://actrees.org" />
	<company id="amoncartermuseum" name="Amon Carter Museum" url="http://www.cartermuseum.org">
		<location id="fortworthtxus" name="Wayne, NJ" city="Fort Worth" country="US" lat="32.7254" lng="-97.3208" state="TX" />
	</company>
	<company id="appleinc" name="Apple Inc." url="http://www.apple.com/jobs">
		<location id="cupertinocaus" name="Wayne, NJ" city="Cupertino" country="US" lat="37.323" lng="-122.032" state="CA" />
	</company>
</companies>
</rsp>

aj.jobs.getLocations

Returns a list of locations for companies that are currently advertising positions.

Parameters:

  • category: The id of a job category to limit to. See aj.categories.getList
  • type: The id of a job type to limit to. See aj.types.getList
  • sort: Accepted values are: date-posted-desc (the default) and date-posted-asc
  • company: Free-text matching against company names. Suggested values are the ids from aj.jobs.getCompanies
  • location: Free-text matching against company location names. Suggested values are the ids from aj.jobs.getLocation
  • telecommuting: Set to 1 if you only want telecommuting jobs
  • keywords: Keywords to look for in the title or description of the job posting. Separate multiple keywords with commas. Multiple keywords will be treated as an OR
  • begin_date: Unix timestamp. Listings posted before this time will not be returned
  • end_date: Unix timestamp. Listings posted after this time will not be returned

Example:

http://www.authenticjobs.com/api/?api_key=a446a0eefe6f5699283g34f4d5b51fa0&method=aj.jobs.getlocations

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<locations>
	<location id="albuquerquenmus" name="Albuquerque, NM" city="Wayne" country="US" lat="40.9254" lng="-74.2765" state="NJ" />
	<location id="alexandriavaus" name="Alexandria, VA" city="Wayne" country="US" lat="40.9254" lng="-74.2765" state="NJ" />
	<location id="anywheresfcaaplus)" name="Anywhere (SF, CA a plus)" />
	<location id="anywherenewyorknypreferred" name="Anywhere - New York, NY preferred" />
	<location id="australiaau" name="Australia" city="Wayne" country="US" lat="40.9254" lng="-74.2765" />
	<location id="baltimoremd or hoboken, nj" name="Baltimore, MD or Hoboken, NJ" />
	<location id="bloomingtoninus" name="Bloomington, IN" city="Wayne" country="US" lat="40.9254" lng="-74.2765" state="NJ" />
	<location id="bostonmaus" name="Boston, MA" city="Wayne" country="US" lat="40.9254" lng="-74.2765" state="NJ" />
</locations>
</rsp>

aj.jobs.search

Returns a list of current positions, filtered by optional parameters. The response is split into multiple pages, if necessary.

Parameters:

  • category: The id of a job category to limit to. See aj.categories.getList
  • type: The id of a job type to limit to. See aj.types.getList
  • sort: Accepted values are: date-posted-desc (the default) and date-posted-asc
  • company: Free-text matching against company names. Suggested values are the ids from aj.jobs.getCompanies
  • location: Free-text matching against company location names. Suggested values are the ids from aj.jobs.getLocation
  • telecommuting: Set to 1 if you only want telecommuting jobs
  • keywords: Keywords to look for in the title or description of the job posting. Separate multiple keywords with commas. Multiple keywords will be treated as an OR
  • begin_date: Unix timestamp. Listings posted before this time will not be returned
  • end_date: Unix timestamp. Listings posted after this time will not be returned
  • page: The page of listings to return. Defaults to 1.
  • perpage: The number of listings per page. The default value is 10. The maximum value is 100.

Example:

http://www.authenticjobs.com/api/?api_key=a446a0eefe6f5699283g34f4d5b51fa0&method=aj.jobs.search&keywords=php,mysql&perpage=1

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<listings total="10" perpage="1" page="1" pages="10">
	<listing id="1569" title="You bring the talent and we'll provide the adventure..." description="..." perks="..." howto_apply="..." post_date="2007-12-07 14:13:27">
		<category id="1" name="Design" />
		<type id="1" name="Full-time" />
		<company id="yakabodinc" name="Yakabod, Inc." url="http://www.yakabod.com">
			<location id="frederickmdus" name="Frederick, MD" city="Frederick" country="US" lat="39.4142688" lng="-77.4105409" state="MD" />
		</company>
	</listing>
</listings>
</rsp>

aj.jobs.get

Returns a position.

Parameters:

  • id: The id of a job.

Example:

http://www.authenticjobs.com/api/?api_key=a446a0eefe6f5699283g34f4d5b51fa0&method=aj.jobs.get&id=1569

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<listings total="10" perpage="1" page="1" pages="10">
  <listing id="1569" title="You bring the talent and we'll provide the adventure..." description="..." perks="..." howto_apply="..." post_date="2007-12-07 14:13:27">
    <category id="1" name="Design" />
    <type id="1" name="Full-time" />
    <company id="yakabodinc" name="Yakabod, Inc." url="http://www.yakabod.com">
      <location id="frederickmdus" name="Frederick, MD" city="Frederick" country="US" lat="39.4142688" lng="-77.4105409" state="MD" />
    </company>
  </listing>
</listings>
</rsp>

aj.types.getList

Returns a list of supported job types. Takes no arguments. Example:

http://www.authenticjobs.com/api/?api_key=a446a0eefe6f5699283g34f4d5b51fa0&method=aj.types.getlist

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<types>
	<type id="1" name="Full-time" />
	<type id="2" name="Freelance" />
</types>
</rsp>

aj.categories.getList

Returns a list of supported job categories. Takes no arguments. Example:

http://www.authenticjobs.com/api/?api_key=a446a0eefe6f5699283g34f4d5b51fa0&method=aj.categories.getlist

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<categories>
	<category id="1" name="Design" />
	<category id="2" name="Development" />
</categories>
</rsp>

aj.company_types.getList

Returns a list of supported company types. Takes no arguments. Example:

http://www.authenticjobs.com/api/?api_key=a446a0eefe6f5699283g34f4d5b51fa0&method=aj.company_types.getlist

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<company_types>
	<company_type id="1" name="Startup" />
	<company_type id="2" name="Studio" />
</company_types>
</rsp>

Error Handling

All API responses indicate whether or not the call was successful. Examine the stat value in the top-level rsp response. Successful calls will report ok, and unsuccessful ones will report error. Error responses will include an error code and description.

Example successful response:

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
<listings total="0" perpage="10" page="1" pages="1">
</listings>
</rsp> 

Example error response:

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="error">
	<err code="1" desc="API key not found" />
</rsp>

Possible Errors

There is a small list of errors that all methods can return. Individual methods can have their own error responses, and those will be described in their documentation.

  • Code: 0, Description: API temporarily disabled (maintenance)
  • Code: 1, Description: API key not found
  • Code: 2, Description: API key disabled
  • Code: 3, Description: API signature invalid
  • Code: 4, Description: No method specified
  • Code: 5, Description: Unknown method: <method_name>
  • Code: 6, Description: Invalid parameters: 'id' is required
  • Code: 7, Description: No listing with id: <id>

Security

All methods require an API key, and each separate application should have its own key. Methods do not currently require signing, but some or all may in the future. To sign an api call, perform the following steps:

  1. Take your list of parameters and sort it alphabetically. For example, if you’re passing the api_key, method, company, and perpage parameters, alphabetical order would be: api_key, company, method, perpage. All parameters must be included, with the exception of api_sig.
  2. Concatenate together your sorted list of key/value parameters. For example, api_key=foo, method=aj.jobs.search, company=flickr, and perpage=api_keyfoocompanyflickrmethodaj.jobs.searchperpage100.
  3. Append your shared secret to the end of your concatenated string. (Note: Shared secrets are currently not being distributed.)
  4. Create an md5 signature of your string. This is your signature.
  5. Append the signature to your API call as the api_sig parameter.

Rules

  • Please try to not call a given method more than once per minute. For calls to methods that do not change often (e.g. aj.types.getList), heavy caching is recommended. Other methods should be cached as appropriate.
  • Please use a separate API key per application
  • Please do not give your API key or shared secret to anyone else
  • API keys can be disabled, and will be if they are causing problems
  • API keys for any websites that involve adult content will be terminated immediately
  • All applications must link back to the Authentic Jobs website in a prominent location

Credits

Sections in this documentation:

Need an API key? Request one here.