Job distribution

This article describes how to build a sourcing app in Talent App Store. That is, an app that:

Pulls jobs from an upstream ATS
Creates a link for each job that a candidate can click on to reach the tenant's career site (and eventually apply)
Embeds tracking information into each link, so that when candidates click through from your site, the tenant knows they came via you

Pulling the jobs

There are two approaches you can use:

Job feed

Use the tenant's job feed (an XML document containing details for all open jobs)

Individual APIs

Use individual APIs, such as GET /jobs, GET /categories, etc. This gives you more control but requires more code.

When to pull jobs

Your app should not poll either the feed or the GET /jobs API to look for changes to the jobs. Instead, it should sign up for real-time notifications of changes by producing the POST /jobs/byID/{}/deltaPings API. Then your app will receive an incoming API call whenever a job is changed at the source.

In response your app might:

if using the GET /jobs API, call GET /jobs/byID/{id} to re-fetch just the changed job.
if using the feed API, then call GET /jobs/feed/full to re-fetch the feed.

Don't pull the feed too agressively. e.g. queue the fetches to avoid overloading the upstream app.

Setup

Let's start by installing some apps and entering some test data.

When installing apps, the apps that have links are sandbox apps that you install via their install token - the other apps can be found publicly listed (find them with "Browse apps").

Install apps and prepare test data

First, follow these instructions to install Developer ATS and create a job application.
Create some more jobs, so that you have useful test data.
Now install the Feed app ("Browse apps").
Finally, to see the XML feed on a web page, install the Agile feed viewer app, using this install token: eyJhbGciOiJSUzUxMiJ9.YWdpbGVmZWVkdmlld2Vy.dP2CZUOGIeS9QAaDtaUTxeugYY8jaGS2Bm9dXrm7EYKV7rlFCHixtWdIrrXC7Q6pGUBWwi_Ilupk6zy6zmd0uDtkJyW_WCSwF8XWg2oQI9tdGx6-r85wk2D6V2OFV-iP4MHIubgd7TxZLbweIyeUP2cEjOcJtghcIuCcD6UpXHn0gIopUBau1mCK9dp8ss1o8i6VkZod4HkTJTvrSWUySl3q6WHCCroZ4oSOhNHSZjIIkHKJZjrZZk0u-0LSKQ1IT6UCoDHXZa7qOBjegpnN9B8z7OrBTuge_jfMwBVJBGs8nAzlx5UhjSw87pv4xMfsR5Ddc87yXC_a9BqcteS6Zw
From the storefront, click to the feed viewer app and you should be able to see the XML feed.

API flow to/from your app

Installing your app

Diagram describing API calls when your app is installed

Fetching jobs with the feed APIs

Fetching jobs with the GET /jobs APIs

Diagram describing API flow for fetching jobs with the Get / jobs API

Implementing the APIs

Produced APIs

These are APIs that your app exposes for other apps to consume them.

POST /tenants

The first API call incoming to your app is to tell you that a tenant has installed it.

Typically you might handle this API call by inserting into your customer table, sending an email to customer support team, etc. You might show the "setup required" icon and a settings page to facilitate this.

See installing and controlling setup and launch pages for more.

POST /jobs/open/externally/byID/{id}/deltaPings

Your app produces this API to learn about changes to jobs, so it can re-fetch them.

To produce a tenant API like this (see the programming guide):

From our developer portal, make your app produce this API (as non-SoT)
Create an endpoint in your server at /t/{tenant}/devs/tas/jobs/open/externally/byID/{id}/deltaPings
On the tazzy tab of your app, set the backend server to point to your server on the Internet

Your endpoint will now be hit every time a change is made to an upstream job (e.g. recruiter in the ATS marks the job as closed).

In response you can fetch just the changed job, or, if you are using the feed APIs, all jobs.

GET /jobs/feeds/full

When using the feed APIs, you fetch all of the upstream jobs as XML in one API call.

First have your app consume the API

-- CODE language-curl --
# as the app "getjobstest",
# and acting for tenant "acme",
# call the API GET /jobs/feeds/full
# as defined by the developer

"tas"curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9"
https://getjobstest.tazzy.io/t/acme/devs/tas/jobs/feeds/full

GET /jobs

Instead of the feed, you can also access jobs using individual API calls.

Have your app consume GET /jobs. Then fetch the first 100 open jobs

You should see a list of jobs come back.

-- CODE language-curl --
# as the app "getjobstest",
# and acting for tenant "acme",
# call the API GET /jobs
# as defined by the developer

"tas"curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9"
https://getjobstest.tazzy.io/t/acme/devs/tas/jobs

Decode each job's category values

On each returned job, you'll see that the job's category values (e.g. its location) are identified by ids. To obtain the mapping from those ids into actual values (e.g. 2013 == Auckland), you'll need to call two more APIs.

GET /categories

This API gives you the list of categories - e.g., that this tenant has categorised their jobs by location and by expertise.

GET /categories/byID/{}/values

This API gives you all of the values for any single category - e.g., all the locations that this tenant has set up.

You should cache the results of these APIs so that you don't need to make the API calls too often, or your app might be throttled.

-- CODE language-curl --
curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9"
https://getjobstest.tazzy.io/t/acme/devs/tas/categories

One of the categories returned above was 100001999, so to get the values for this category, call:

-- CODE language-curl --
curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9"
https://getjobstest.tazzy.io/t/acme/devs/tas/categories/byID/100001999/values

Create a link back to the career site

The next step in building your app is to compose a link leading back to the job. The tenant may have many career sites (e.g. graduate site, main site, campaign site for a new store opening). One of these will be marked as the default - your app learns which by calling an API.

GET /careerSites/primary

Your app consumes this API to learn which career site is the primary.

GET /careerSites/forApp/byID/{site}/jobLinks

The /careerSites/forApp/byID/{site}/jobLinks API lets you fetch the links for an array of jobs in a single API call.

Pass in the array of jobs that you want links for as parameters. Cache the results to minimise API traffic.

Add your own trackers

This step is optional

So far you have extracted a list of jobs, and for each one, you've built a link that the candidate can click on to lead them to the job (on the primary careers site).

When the candidate reaches the primary career site, their browser will add your site (in the referer http header), so there's a fair chance that any candidate job applications made via your app will be attributed as the source of any resulting job applications (by the career site checking the referer header set by the candidate's browser).

However you may want to make sure that source detection works correctly - or add additional tracking information that you can use later - by attaching a tracker to the link. Trackers get passed through to any job applications resulting from clicking on your link. As a result:

The tenant knows the application came via you (i.e. in their sourcing statistics)
Other APIs may give you visibility into "your" applications (how many, at what stage, etc.)

You can also embed your own information into trackers. For example, if your app is a kind of social referral app, then you could embed in the tracker the details of the person who shared the job. Then, when someone is hired after applying using that shared link, you could pay the referrer a bounty.

Learn more about trackers.