Using the ETP Performance Reporting API’s

JobLink's ETP (Eligible Training Provider) Reporting API (Application Programming Interface) enables users to process ETP performance reporting data, so that reporting data does not have to be entered manually within JobLink. You can also use the ETP Programs API to retrieve relevant training programs and program Id’s. You must develop, purchase, or use an open-source RESTful client to use the API. Using the ETP API requires basic knowledge of software development and web services.

You or the provider whose performance results are being posted must have an approved Training Provider account in each JobLink website in which you want to post results. Once your provider account has been approved, you must generate an ETP API token to use the API or to authorize a third-party to use the API on your behalf. If you are managing your Providers Program Performance results, you will use your unique token with your username to submit requests to the ETP API.

 

Creating/Viewing an API Token

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

  1. Log in to your ETP JobLink account and select My Profile from the top navigation menu. The My ETP Profile displays.

  1. Scroll down to the ETP API section. It includes a link to Read more about the ETP API and a button to generate an API token.

  1. Select Generate Token. A confirmation message displays at the top of the page. The My ETP Profile page reloads and the ETP API section now shows a Display Token button.

  1. Select Display Token. The token displays.

How the ETP API Works

To use the ETP 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 ETP API, each state using JobLink has a unique endpoint.

If you wish to post ETP performance results across multiple states using JobLink, you must use separate endpoints for each state:

  • Arizona: https://www.azjobconnection.gov/api/training_program_performances

  • Arkansas: https://www.arjoblink.arkansas.gov/api/training_program_performances

  • Delaware: https://joblink.delaware.gov/api/training_program_performances

  • Idaho: https://idahoworks.gov/api/training_program_performances

  • Illinois: https://illinoisjoblink.illinois.gov/api/training_program_performances

  • Kansas: https://www.kansasworks.com/api/training_program_performances

  • Maine: https://joblink.maine.gov/api/training_program_performances

  • Oklahoma: https://okjobmatch.com/api/training_program_performances

  • Vermont: https://www.vermontjoblink.com/api/training_program_performances

     

Method

The request methods for the ETP API are POST (create performance record), DELETE (delete a performance record) and GET (used to retrieve Provider’s Program names and Program ID’s from Joblink).

The URL for deleting performances is:

DELETE- https://[state URL]/api/training_program_performances/TRAINING_PROGRAM_PERFORMANCE_ID_[training program performance ID]

Header

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

ETP API Headers

Header Name

Header Value

Content-Type

application/json; v1

Accept

application/json; v1

Body

The request body contains the ETP posting data the client is sending to the JobLink server.

Select the POST Body link below to expand the Version 1 body.

The Username and api_token can be passed in header as well as in body.

{

"username":"string",
"api_token":"string",
"training_program_id":"{TRAINING_PROGRAM_ID}",
"performance_type":"CONTINUED",
"performance_year":integer,
"start_date":"2022-06-30",
"end_date":"2022-6-30",
"number_of_participants":integer,
"number_of_participants_who_exited":integer,
"number_of_participants_who_completed":integer,
"number_employed_after_2_quarters":integer,
"number_employed_after_4_quarters":integer,
"number_who_attained_credential":integer,
"median_wage_after_2_quarters":integer,
"average_earnings_after_2_quarters":integer,
"average_earnings_after_4_quarters":integer,
"employment_rate_q2_denominator":integer,
"employment_rate_q4_denominator":integer,
"credential_rate_denominator":integer

}

About ETP API Data

The following table (select link to expand) provides the keys and values accepted in the body of ETP 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.

ETP API Data

ETP API Data

Key

Data Type

Value

Constraints

username

string

Training Provider's JobLink username

6-20 characters

api_token

string

Training Provider's JobLink ETP API token

35 characters

training_program_id

integer

Program ID

1-5 digits

 

 

 

 

performance_type

boolean

Annual =0

If 0, need performance year populated

Continued = 1

If 1, need start and end dates populated

1 digit

performance_year

integer

Year reporting on

1-4 digits

start_date

date

The begin date of the reporting period

Must be before end date YYYY/MM/DD

end_date

date

The end date of the reporting period

 

Must be after begin date YYYY/MM/DD

number_of_participants

integer

Total number of individuals served

0-99999

number_of_participants_who_exited

integer

Total number of individuals who exited

0-99999

number_of_participants_who completed

integer

Total number of individuals who exited and completed their program of study

0-99999

number_employed_after_2_quarters

integer

Number employed in the 2nd quarter after exit

0-99999

number_employed_after_4_quarters

integer

Number employed in the 4th quarter after exit

0-99999

number_who_attained_credential

integer

Total number of individuals who attained a credential

0-99999

median_wage_after_2_quarters

integer

Median Wage after two quarters

0-999999.99

average_earnings_after_2_quarters

integer

Average earnings after 2 quarters

0-999999.99

average_earnings_after_4_quarters

integer

Average earnings after 4 quarters

0-999999.99

employment_rate_q2_denominator

integer

Employment rate Q2 denominator

0-999999.99

employment_rate_q4_denominator

integer

Employment rate Q4 denominator

0-999999.99

credential_rate_denominator

integer

Credential rate denominator

0-999999.99

Notes

  • Performance type will accept mixed uppercase and lowercase, eg “CoNtinuEd."

  • If Performance type is not a valid type, such as “abcd,” it will throw an error.

    • Must be one of: annual or continued

  • Performance type and performance year must be blank for initial performance (the first created performance).

  • Program id must match with username and provided token or an error will be thrown.

  • Start date and end date are required for initial performance and continued performance.

  • Start date and end date must be blank for annual performance.

  • Number completed cannot be greater than number exited

  • Date constraints:

    • End date cannot be before start date

    • End date cannot be after current date

    • Acceptable date formats

      • “2021-04-30”

      • “2021/04/30”

    • Invalid date formats

      • “04-30-2021”

      • “2021-13-04”

      • 04302021

      • “a”

      • “ ”

  • API token constraint- when passed header can be done in 2 formats –

    • Token MY_PROVIDED_TOKEN

    • Token token= MY_PROVIDED_TOKEN

       

Submitting a Successful API Request

Using your RESTful client, send a request to the ETP API endpoint(s). All requests must include a valid ETP 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 Program Performance page as shown in the table above. The API processes successful requests immediately.

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.

 

Get Request

Used by Training Provider to retrieve current list of training programs and program ID’s which will be reported on.

 

ETP API Headers

Header Name

Header Value

Content-Type

application/json; v1

Accept

application/json; v1

curl --location --request GET 'https://stateurlbelow.gov/api/training_programs' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json; v1' \
--header 'username: TankOne57' \
--header 'Authorization: Token token=5ba20299123abd120a6c2081fcb75c1b' \
--data-raw ''

Unique URLs for each state:

  • Arizona: https://www.azjobconnection.gov/api/training_programs

  • Arkansas: https://www.arjoblink.arkansas.gov/api/training_programs

  • Delaware: https://joblink.delaware.gov/api/training_programs

  • Idaho: https://idahoworks.gov/api/training_programs

  • Illinois: https://illinoisjoblink.illinois.gov/api/training_programs

  • Kansas: https://www.kansasworks.com/api/training_programs

  • Maine: https://joblink.maine.gov/api/training_programs

  • Oklahoma: https://okjobmatch.com/api/training_programs

  • Vermont: https://www.vermontjoblink.com/api/training_programs