Toggle document index

Survey applicants app

Here's a quick walk through of what's required to write a survey app in Talent App store - e.g. an app that sends a survey to applicants who have been unsuccessful in order to understand candidate care levels.

About TAS

Writing an app may sound intimidating, but its not. You're not actually creating a downloadable app that the customer runs themselves. Instead you're just producing and consuming RESTful APIs on your own servers - in a way that looks like an app to the customer.

For example, when a customer clicks install on your app in Talent App Store, you'll receive an incoming API call to your own server telling you that you have a new customer. From this point you can start making API calls to fetch data for that customer.

All your app's code runs on your own servers, and we (Aotal) don't perform any review or testing of your code, nor do we need any IP rights to it. Also the APIs you will use are all open source, so you're free to use them in any way you see fit. And of course you can write and host your app using whatever tools and technologies you already use.

For more about TAS, see


Here are the typical steps you would go through to build this app.

Define your data gathering strategy

Your survey will be triggered by an applicant being marked as unsuccessful in their application for a job. There are two ways you can learn about unsuccessful applicants:

Pull (polling)

You periodically (e.g. once an hour, overnight) call the API GET /applications/byPhase/decline/complete, passing in a date. The response includes all applications that have been declined since that date - typically the date you pass in will be the date of the previous poll operation.

This approach is not real time, but that's probably not a concern for this kind of app - you may want to allow some time for the candidate to absorb the fact that they've been unsuccessful before approaching them.

Push (delta ping)

You produce the API GET /applications/byPhase/decline/complete, which is called in real time each time a candidate is declined.

This approach requires high availability of your app. If your app is down at the point when a candidate is declined, you'll miss the message, and you would have to use GET /applications/byPhase/decline/complete when your app came back up again.

In this example, we'll use the pull approach.

Create your app and fetch declined candidates

1) Create a developer account at

2) Define your app, giving it a name, logo etc. Make a note of your app's secret key - you'll need this later. Don't share this with anyone. Finally, define the APIs that your app consumes - in this case, GET /applications/byPhase/decline/complete (make sure you specify source of truth == true):

Later on, you'll write some code and then attach your actual servers. But for now, lets install your app and start making some API calls from the command line. In Talent App Store, your app can't do much at all until its installed by a tenant. So to develop and test your app, and make API calls, you'll need a tenant of your own (its free to create one).

3) Back at the app, in the developer site, click the install link.

4) You'll be guided to create an account at Create a tenant, and finally install your app into your new tenant. You'll see a couple of other apps pre-installed for you.

Next, for your app to consume this API, some other app needs to produce it. In a production tenant, that app might be an applicant tracking system (ATS). Since installing an ATS and getting test data into it can be something of a big deal, we (Aotal) provide a simple test app that produces the APIs you're going to use and is pre-loaded with test data.

5) Click here to install the mock applications app into your tenant.

Now you're ready to make an API call to fetch declined applications. We'll use the familiar curl command.

6) At the command line, type the following (substituting your own app, tenant and secret key):

# as the app "myapp",
# and acting for tenant "acme",  
# call the API GET /applications/byPhase/decline/complete
# fetching declined applications in the last week
# including application, job and candidate details  
# as defined by the developer "tas"

curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" \

You should see a list of applications come back, ordered by ID. If not, check the preceding steps. If you get an empty set back, you might need to scan further back in time to find some valid test data. If you're stuck, you can ask for help on the forums linked to the developer site.

Paging through the result set

In a live system you'll see a lot of data. The API only returns a maximum of 100 applications each time you call it, so if you do see that many applications in the response, call the API again, this time passing in the minID parameter set to the ID of the last application in the previous response. Keep doing this until you've fetched all the applications.

Next result set

The next time your app pulls declines, you'll pass in a new value for the since parameter - most likely the point in time of your previous run. Again, page through the results, 100 at a time, until you've fetched all the declines.

Decode each job's category values

If you need to correlate your surveys in some way to some characteristic of each application's job (e.g. department), you'll likely do that using the job's categories.

If you look closely at each job's details, 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 to often, or your app might be throttled.

7) At the developer site, update your app so that it consumes these APIs (again, as source of truth).

To test this out, you can call these APIs using curl as above, e.g.:

curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" -H 'tazzy-tenant: acme'

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

curl -H "tazzy-secret: V83s9zScl1BKc2pl9pO4ELEtVNarzVkJYaTsU1a9" -H 'tazzy-tenant: acme'

Multiple applications

Its possible (and normal) for a candidate to apply to multiple jobs, and therefore to be declined multiple times. Also, a candidate could be declined for multiple jobs within a very short period of time (e.g. if all the applications were waiting on a single drug test result). You may want to apply some policy in your app that considers this.

Internal candidates

Some candidates are internal, i.e. already employed by the customer. If you want to treat internals differently, you can identify them via the candidate details that are passed back.