1 JobAdder Developer Account

JobAdder partners are required to register for a JobAdder Developer Account:

Accessibility will be determined based on the information provided when registering for a developer account. It is important that correct and factual information is provided for your solution in order to be approved for accessibility.

When/if granted access for a developer account, partners will have the ability to create API credentials that will be used for their web application.

Based on the accessibility granted, partners will have access to only specific areas of the JobAdders API based on the resources needed by your solution.

2 Things to Consider

The following describe important items which should be noted and highlighted into your design and requirements decision.

Items	Description
Action Button level	Action buttons created are on the JobAdder account level (not user level)
Button Naming	Cannot be longer than 100 characters.
No. of action buttons	This should be consulted with our API team, we recommend no more than 10 action buttons.
Visibility	Action button upon creation may take up to 5 minutes before it appears in the JobAdder account.
Side Drawer / Modal / Page (Opening New Tab)	One record can only be selected at a time if your integration is using the sidedrawer, popup (modal) or page (new tab) configuration for your action button(s). For added security when opening the url, please see: Partner Action Security Hashed URL If you require for the user to have the ability to multiselect records, you must not specify a URL and its URL type – this will create an action button in JobAdder where when selected, will just show a submission notice.
JobAdder User Deletion	The user that granted access to your application via oAuth2 can be deleted at any time (due to resignation etc.) by an administrator on the account. Users that has granted your application and then removed / deleted at a later stage will return a ‘invalid_grant’ / ‘invalid_request’ error from the API when the refresh token is used, you’ll be required to handle this in your integration.
Modal	If you are utilizing our modal popup to display a view from your application, ensure that you have allowed loading of the resources in iframe outside of your domain.
Removable of Action Button(s)	Your integration solution should also include the removal process of these buttons, when a user chooses to disable your integration.
Re-authentication	An account for any reason may re-authenticate with the same JobAdder account which may trigger a new request to add the same action button. This will cause an error response from the API if the same reference, button name etc is used.

3 Action Buttons

The following process provides an overview on steps to add Action Buttons in the JobAdder UI.

These action buttons will appear as a sub-menu under a parent / main menu created by JobAdder.

Your sub-menu naming convention must be easy to follow and is consistent to its purpose – In common cases, the parent menu is named after your product with its sub-menu named as the actions it will perform.

Precondition

You have registered and have been approved for a developer account with JobAdder
You have been granted ‘partner_ui_action’ scope and have included this scope into your OAuth2 authorization URL
A JobAdder admin user has granted your application access and you have obtained an access token

Step 1: Adding Action Buttons

To create an Action Button, hit the following URL with a POST request:

https://api.jobadder.com/v2/partners/actions/{type}

The following types {type} are available to append to the endpoint: Job, JobAd, Candidate, JobApplication, Placement, Company or Contact – Types are ‘sections’ in JobAdder where the action button will sit and be triggered from.

If you are looking to include a modal or a new window for when your action button is selected, you must specify in your request body the URL and the URL type (Popup or Page) with your POST request.

You can include the following template variables into your URL which will be replaced by its values:

Section	Variables	Description
Jobs	{jobId}	The Job Id of the selected record/s
Job Ads	{adId}	The Ad Id of the selected record/s
Candidates	{candidateId}	The Candidate Id of the selected record/s
Job Applications	{applicationId}	The Application Id of the selected record/s
Placements	{placementId}	The Placement Id of the selected record/s
Companies	{companyId}	The Company Id of the selected record/s
Contacts	{contactId}	The Contact Id of the selected record/s
User Id	{userId}	The user id of the user performing the action

All available options for the request body are defined in this following section of our API document:

https://api.jobadder.com/v2/docs#operation/AddPartnerAction

Example cURL Request Adding a Modal Button in the Candidate Section:

curl -X POST \
  'https://api.jobadder.com/v2/partners/actions/Candidate' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
  "actionName": "Test Menu",
  "reference": "2",
  "url": "https://test.com/jobadder/?candidateId={candidateId}"
  "urlType": "Popup",
  "webhookData": { "test": "data" }
}'

In this example, an action partner button will be created in the Candidate section of the JobAdder UI. When this button is triggered, a modal will appear loading a view as specified in the above example request.

If you require a standard action button (without modal or new window), you’ll need to exclude specifying the URL and URL Type.

Tips for Modals Buttons: If you have an id stored in your database against the JobAdder account (access token + refresh token), you may want to pass this id as your query parameter included in your URL at button creation:

https://test.com/jobadder/?candidateId={candidateId}&uid={id}

This will allow you to identify which account has sent the GET request allowing you to map this id value back on your end, identifying which client has triggered the action button.

Make sure you have the proper authentication setup when your URL is accessed for security reasons.

Step 2: Action Button Stages

Action buttons have several stages that is used to track the progression of your workflow, these stages are:

Submitted (Default)
In Progress
Completed
Rejected
Cancelled

When an action button is selected, an ‘submitted’ stage is stored against the record, these stages are typically updated to reflect the workflow status on your end.

As an example – You may want to move a record with an action in stage ‘submitted’ to ‘in progress’ as you are processing this on your end which can / may take a couple of days for the results to come back. When the final results are returned, you may then update this same record and its action to a ‘completed’ stage when you have the results.

JobAdder users that are using your integration will have the visibility to see this action stage value of the record/s (see appendix ‘Results Column’) so it is important that the correct stage is updated.

Action stages can be retrieve in several ways, depending on your action button configuration, popup, page or none, the recommended approaches are described below.

Modal/New Window

Integrations using the action button with a modal or new window will have a URL defined in its configuration.

When the action button/s are selected (with a record), a modal or a new window will be displayed via the jobAdder UI.

Using the example from step 1, its URL includes a query string (candidate id) that is used to define which candidate record has been selected. With this, your application, on document ready can extract the candidate id from the query parameters and make a GET request to JobAdder to retrieve the full candidate information for your application to process when the view is loading.

Example cURL Request to get Candidate Info

curl -X GET \
  'https://api.jobadder.com/v2/candidates/{CANDIDATE_ID}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \

Example Response

{
    "candidateId": 10320,
    "firstName": "test",
    "lastName": "test",
    "email": "test@test.com",
    "mobile": "123-456-459101",
    "address": {
        "country": "Australia"
    },
    [....]
    "partnerActions": [
        {
            "actionId": "8a94ae25-d2f3-4997-bb50-74ea712950af",
            "actionName": "Test Menu",
            "reference": "Ref-123",
            "stage": "Submitted",
            "submittedAt": "2018-10-16T00:47:47Z",
            "submittedBy": {
                "userId": 1055,
                "firstName": "test",
                "lastName": "test",
                "email": "test@test.com"
            }
        }
    ],
    [....]
}

NB: The partnerActions object of that record will then have an assigned stage of ‘submitted’. If your solution does not require to process this record and can retrieve / provide an outcome immediately, ideally you must update the action stage of this record to ‘completed’.

Standard Action Button

Integrations using the standard action buttons will require to poll for records that has an ‘submitted’ action stages.

There are several ways to retrieve records that have been assigned a ‘submitted’ action:

Get records with a submitted stage using query parameters. Using the step 1 action button example created in the Candidate section, you can hit the following URL with the following query parameters:

https://api.jobadder.com/v2/candidates?partnerAction.stage=submitted

This will return a list of candidates with the partner action stage in submitted.

Example cURL Request to get Candidates that has an assigned submitted action:

curl -X GET \
  'https://api.jobadder.com/v2/candidates?partnerAction.stage=submitted' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \

Example Response

{
    "items": [
        {
            "candidateId": 18220,
            "firstName": "test",
            "lastName": "test",
            "email": "test@test.com"
            [...]
     }
    ],
    "totalCount": 1,
    "links": {
        "first": "https://api.jobadder.com/v2/candidates?partnerAction.stage=submitted"
    }
}

Note: Using this example, once you have processed the array of candidates, you’ll need to update its partner actions defined in step 3. Not handling this may result in your application pulling duplicate candidate records that may have already been processed.

Get all records with a ‘submitted’ stage for an action button. To do this you must first retrieve the action id of your action button, hit the following URL with a GET request:

https://api.jobadder.com/v2/partners/actions

This will return a list of action buttons you have created for the account.

Example cURL Request to get Action Buttons

curl -X GET \
  'https://api.jobadder.com/v2/partners/actions' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \

Example Response

{
    "items": [
        {
            "actionId": "d1581720-f161-40ce-a2c1-d6c91de3d88a",
            "actionType": "Candidate",
            "actionName": "Test",
             [....]
            "reference": "3",
            "webhookData": {},
            "createdAt": "2018-11-16T03:25:31Z"
 		        [....]
     }
		]
}

Using the action id and the action type value from the JSON response (you can iterate through the array), hit the following URL with a GET request to get all records with a submitted action stage:

https://api.jobadder.com/v2/partners/actions/{actionId}/{actionType}?stage=submitted

Example cURL Request to get submitted action records for a button

curl -X GET \
  'https://api.jobadder.com/v2/partners/actions/ d1581720-f161-40ce-a2c1-d6c91de3d88a/Candidate?stage=submitted' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \

Example Response

{
    "items": [
        {
            "candidateId": 18220,
            "firstName": "Pon",
            "lastName": "Submitted",
            "email": "pon+test@jobadder.com",
            "phone": "12344",
             [....]
            "partnerActions": [
                {
                    "actionId": "d1581720-f161-40ce-a2c1-d6c91de3d88a",
                    "actionName": "Test",
                    "reference": "3",
                    "stage": "Submitted",
                    "submittedAt": "2018-11-16T03:25:58Z",
                    "submittedBy": {
                        "userId": 1055,
                        "firstName": "Pon",
                        "lastName": "Yuntawai",
                        "email": "pon@jobadder.com"
                    }
                }
            ]
        }
    ],
    "totalCount": 1,
    "links": {
        "first": "https://api.jobadder.com/v2/partners/actions/d1581720-f161-40ce-a2c1-d6c91de3d88a/Candidates?stage=submitted"
    }
}

You may extract and update the action stage from the partnerActions object for that record once you have processed it as defined in step 3.

Step 3: Progressing / Completing Action Stages

Actions can be updated to different stages via a PUT request.

You are able to include a URL and a URL type (popup or page) in your request body which will act similarly to the action button e.g. if a URL and its type is passed, the stage value will be hyperlinked with the ability for users to click on the text to either open a modal or a new window.

You may exclude the URL and URL type if you do not require this functionality.

To update an action stage for a record, hit the following URL with a PUT request:

https://api.jobadder.com/v2/partners/actions/{actionId}/{actionType}/{recordId}/{actionStage}

Example cURL Request to Update Action to In-Progress Stage:

curl -X PUT \ 'https://api.jobadder.com/v2/partners/actions/8a94ae25-d2f3-4997-bb50-74ea712950af/Candidates/16864/progress' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": ""
}'

NB: A success response will return a 204 HTTP status.This will effectively move that particular record with the action, into an in-progress stage.

Example cURL Request to Update Action to Completed Stage:

curl -X PUT \
'https://api.jobadder.com/v2/partners/actions/8a94ae25-d2f3-4997-bb50-74ea712950af/Candidates/16864/completed' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": ""
}'

NB: A success response will return a 204 HTTP status.This will move this record with the action into a completed stage.

The action stage value is visible to the customer via a field that they can enable (show) on their grid table column.

With this the column will the stage value and if a URL is specified will be hyperlinked (See appendix ‘Results Column’).