Using the Job API

AJL's Job API (Application Programming Interface) processes raw job posting data so that job postings do not have to be created manually using the AJL job posting builder. You can also use the Job API to edit or delete job postings. Typically, third-party recruiters or large employers with a great number of job postings use the Job API. You must develop, purchase, or use an open-source RESTful client to use the API. Using the Job API requires basic knowledge of software development and web services.

You (or the employer whose job postings you manage) must also have an approved employer account in each AJL website in which you want to post jobs. Once your employer account has been approved, you must generate a Job API token to use the API or to authorize a third-party to use the API on your behalf. If you are managing your company's job postings, you will use your unique token with your username to submit requests to the Job API. If you are a third party managing jobs for multiple employers, you will need the username and API token for each employer you serve.

  • If you have used the Job API in the past, we recommend updating to Version 2. This includes updated Headers and Body text, as described below. However, Version 1 is still supported.

Creating/Viewing an API Token

Do not create an API token unless you are ready to use the Job API yourself or if you plan to allow a third party to post your jobs.

  1. Navigate to My Company Profile. Click the Job API accordion. The Job API section expands.
  2. Click Display Token. A confirmation message displays at the top of the page.
  3. Click the Job API accordion. The Job API section expands.
  4. Click Display Token. The token displays.

How the Job API Works

To use the Job API, you need a RESTful client, which is a program that lets you build HTTP requests. To make a request, you need to include the URL, Header, Method, and Body. The body will vary depending on the method.

URL

An endpoint is a unique URL that makes up part of an API. For the Job API, each state using AJL has a unique endpoint. If you wish to post jobs across multiple states using AJL, you must use separate endpoints for each state:

  • Alabama: https://joblink.alabama.gov/ada/r/api/jobs
  • Arizona: https://www.azjobconnection.gov/ada/r/api/jobs
  • Arkansas: https://www.arjoblink.arkansas.gov/ada/r/api/jobs
  • Delaware: https://joblink.delaware.gov/ada/r/api/jobs
  • Idaho: https://idahoworks.gov/ada/r/api/jobs
  • Illinois: https://illinoisjoblink.illinois.gov/ada/r/api/jobs
  • Kansas: https://www.kansasworks.com/ada/r/api/jobs
  • Maine: https://joblink.maine.gov/ada/r/api/jobs
  • Oklahoma: https://okjobmatch.com/ada/r/api/jobs
  • Vermont: https://www.vermontjoblink.com/ada/r/api/jobs

Method

The request methods for the Job API are POST (create job posting[s], PATCH (update an existing job posting), and DELETE (delete the job posting).

  • If you need to patch or delete a posting, select PATCH or DELETE and add the job posting ID in braces to the endpoint (e.g., https://www.kansasworks.com/ada/r/api/jobs{10608445}).

Header

Headers provide meta information about the request. Add the following headers to your RESTful client:

Job API Headers
Header Name Header Value
Content-Type vnd.joblink.v2+json
Accept application/json; v2

Body

The request body contains the job posting data the client is sending to the AJL server.

  • Please note that if you were using Version 1 of the Job API, you can update the body text for additional fields.

Click the POST/PATCH Body link below to expand the Version 2 body.

About Job API Data

The following table (click link to expand) provides the keys and values accepted in the body of Job API requests. There are three types of data: string (group of characters and digits), integer (group of digits), and boolean (true or false). Accepted values are provided, as well as any constraints, such as character limits.

Submitting a Successful API Request

Using your RESTful client, send a request to the Job API endpoint(s). All requests must include a valid employer username and API token; if this information is not valid, the request will not be successful. To be successful, POST requests must also include accepted values for all of the required fields in the AJL job posting builder as shown in the table above. The API processes successful requests immediately. Once the job posting is created in AJL, both self-service employers and staff can view, edit, and delete the job posting like any other job. Job seekers can also search for and view the job posting like any other job, depending on the value submitted for “What date do you want this job made public?” and veterans’ preference settings in the state.

Status Codes

After submitting a request, a status code will display indicating the success of the request.

  • 200: The request has been fulfilled, resulting in the creation of a new resource.
  • 401: The request contained an unauthorized token, and access is denied.
  • 422: The request instance was invalid and validation messages are provided.
  • 500: An error indicating a general problem on our server during specific steps in processing.