Using the Job API

JobLink's Job API (Application Programming Interface) processes raw job posting data so that job postings do not have to be created manually using the JobLink 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 JobLink 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. Log in to your employer account and select My Employer Profile from the top navigation menu. The My Employer Profile displays.
  2. Scroll down to the Job API section. It includes a link to Read more about the Job API and a button to generate a API token.
  3. Select Generate Token. A confirmation message displays at the top of the page. The My Employer Profile page reloads and the Job API section now shows a Display Token button.
  4. Select 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 JobLink has a unique endpoint. If you wish to post jobs across multiple states using JobLink, you must use separate endpoints for each state:

  • Arizona: https://www.azjobconnection.gov/api/jobs
  • Arkansas: https://www.arjoblink.arkansas.gov/api/jobs
  • Delaware: https://joblink.delaware.gov/api/jobs
  • Idaho: https://idahoworks.gov/api/jobs
  • Illinois: https://illinoisjoblink.illinois.gov/api/jobs
  • Kansas: https://www.kansasworks.com/api/jobs
  • Maine: https://joblink.maine.gov/api/jobs
  • Oklahoma: https://okjobmatch.com/api/jobs
  • Vermont: https://www.vermontjoblink.com/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/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 JobLink server.

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

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

{

"username": "string",
"api_token": "string",
"number_of_positions_available": 0,
"education_level_id": 0,
"license_type_id": 0,
"employment_type": "string",
"position_type": "string",
"alien_recruiting": "string",
"made_public_on": "string",
"absolute_expiration_on": "string",
"is_day_shift": true,
"is_evening_shift": true,
"is_night_shift": true,
"is_split_shift": true,
"is_no_preference_shift": true,
"is_rotating_shift": true,
"wage_upper_bound": 0,
"wage_lower_bound": 0,
"is_sent_to_jobcentral": true,
"is_staff_assistance_requested": true,
"applicant_reply_method": [
"string"
],
"application_description": "string",
"driving_required": true,
"is_wage_displayed": true,
"wage_type": "string",
"company_work_description": "string",
"title": "string",
"company_name": "string",
"city": "string",
"state": "string",
"zip": "string",
"address": "string",
"email": "string",
"phone": "string",
"fax": "string",
"url": "string",
"description": "string",
"average_hours": 0
}

DELETE Body

{
"username": "string",
"api_token": "string"
}

About Job API Data

The following table (select 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.

Job API Data

Job API Data
Key Data Type Value Constraints
username string Employer's JobLink username 6-20 characters
api_token string Employer's JobLink Job API token 35 characters
number_of_positions_available integer How many positions are available? 1-2 digits
education_level_id integer What education level is required for this position?
  • 3 = Some high school or less
  • 4 = High school diploma or equivalent
  • 5 = Vocational certificate or credential
  • 6 = Some college
  • 7 = Associate's degree
  • 8 = Bachelor's degree
  • 9 = Masters degree
  • 10 = PhD
  • 11 = MD, OD or related
  • 12 = DDS DMD or related
  • 13 = JD
1-2 digits
license_type_id integer

If a driver's license is required, what class should it be:

  • 1 = Class A
  • 2 = Class B
  • 3 = Class C
  • 4 = Non-commercial driver's license
  • 5 = Class G
  • 6 = Class L
  • 7 = Class M
  • 8 = Class V
1 digit
employment_type string Is this job full time, part time, or both?
  • F = full time
  • P = part time
  • N = full or part time
  • 8 = see job description
1 character
position_type string Is this job temporary, permanent, or both?
  • P = permanent
  • T = temporary
  • B = both
  • 8 = see job description
1 character
alien_recruiting string Is this job supporting an H-1B, H-2A, or H-2B recruitment activity?
  • 1 = H-1B
  • 2 = H-2A
  • 3 = H-2B
  • 0 = No
1 character
made_public_on string What date do you want this job made public? YYYY/MM/DD
absolute_expiration_on string What is the expiration date of this job? YYYY/MM/DD
is_day_shift boolean Is this a day shift? 0 = No, 1 = Yes 1 character
is_evening_shift boolean Is this an evening shift? 0 = No, 1 = Yes 1 character
is_night_shift boolean Is this a night shift? 0 = No, 1 = Yes 1 character
is_split_shift boolean Is this a split shift? 0 = No, 1 = Yes 1 character
is_no_preference_shift boolean Is this an undefined shift? 0 = No, 1 = Yes 1 character
is_rotating_shift boolean Is this a day shift? 0 = No, 1 = Yes 1 character
wage_upper_bound integer What is the maximum starting wage or salary? Decimals and digits (e.g., 12.50 or 30000)
wage_lower_bound integer What is the minimum starting wage or salary? Decimals and digits
is_sent_to_jobcentral boolean Should this job be posted on US.jobs by Direct Employer? 0 = No, 1 = Yes 1 character
is_staff_assistance_requested boolean Is staff assistance requested for managing this posting? 0 = No, 1 = Yes 1 character
applicant_reply_method string How should the applicant respond to this posting?
  • a = American Job Center
  • c = phone
  • e = email
  • f = fax
  • m = mail
  • p = in person
  • r = throught recruiter
  • w = website
15 characters
application_description string Describe any additional materials or information the applicant should provide. 16 characters
driving_required boolean Is driving an essential function of this job? 0 = No, 1 = Yes 1 character
is_wage_displayed boolean Should the wage be displayed for this position? 0 = No, 1 = Yes 1 character
wage_type string How are wages paid for this position?
  • A = annual
  • H = hourly
  • O = other
1 character
company_work_description string What is the company description? 3000 characters
title string What is the title of the position? 150 characters
company_name string What is the name of the company? 50 characters
city string What city is the position located in? 25 characters
state string What state is the position located in? 2 characters
zip string What is the ZIP code of the position location? 9 characters
address string What is the street address of the position location? 50 characters
email string What is the company's email address? 100 characters
phone string What is the company's phone number? 10 characters
fax string What is the company's fax number? 10 characters
url string What is the URL of the job posting, if available on an external website? 5000 characters
description string What is the job description? 4000 characters
average_hours integer How many hours are in the average work week? (1-99) 2 characters

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 JobLink job posting builder as shown in the table above. The API processes successful requests immediately. Once the job posting is created in JobLink, 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.