Toggle document index


This recipe describes building an sourcing app in Talent App store - i.e. an app that:

  1. pulls jobs from an upstream ATS
  2. creates a links for each job that a candidate can click on to reach the tenant's career site (and eventually apply)
  3. 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:

  1. Use the tenant's job feed (an XML document containing details for all open jobs)
  2. 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.

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

Set up

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

Note: 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 the first few steps (up to and including creating a job) of these instructions.

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:


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

note right of app: a tenant installs your app core->app: POST /tenants

Fetching jobs with the feed APIs

note right of app: your app learns that some job may have changed ats->app: POST /jobs/open/externally/byID/{}/deltaPings note right of app: your app fetches all publicly visible jobs app->feed: GET /jobs/feeds/full

Fetching jobs with the GET /jobs APIs

note right of app: your app fetches details of each category and its values app->ats: GET /categories app->ats: GET /categories/{}/values app->ats: GET /categories/{}/values note right of app: your app fetches each stripe of open jobs (max 100 per stripe) app->ats: GET /jobs/open/externally app->ats: GET /jobs/open/externally note right of app: your app builds a tracker for each job, with itself as the source app->tracker: POST /trackers note right of app: your app asks which is the primary careers site app->switchgear: GET /careerSites/primary note right of app: your app gets links to the jobs at the careers site app->careersite: GET /careerSites/forApp/byID/{site}/jobLinks note right of app: your app learns that a job may have changed ats->app: GET /jobs/open/externally/byID/{}/deltaPings

Implementing the APIs

Produce 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


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):

  1. At, make your app produce this API (as non-SoT)
  2. Create an endpoint in your server at /t/{tenant}/devs/tas/jobs/open/externally/byID/{id}/deltaPings
  3. On the "tazzy" tab of your app, set the back end 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.

e.g. (first have your app consume the API):

# 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"

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:

# 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"

You should see a list of jobs come back.

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.

The GET /categories API gives you the list of categories - e.g., that this tenant has categorized their jobs by location and by expertise.

The GET /categories/byID/{}/values 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.


curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9"

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

curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9"

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 aditional 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 here.