How to build a custom job portal on your site using the CATS API

Your career portal is the page on your website where candidates can apply to your open jobs. CATS gives you a few different ways to handle this: 1) Using our hosted career portal 2) using our job widget and 3) building a custom solution using our API, which will be covered below.

Why build a custom solution using the API? The primary advantage is that it gives you the ability to create a career portal directly onto any page on your site, built to fit seamlessly into the rest of your site, with nearly unlimited customization option. The API provides you with the job data you need and the ability to submit applications, and those two things together can be used as the basis for any custom-designed career portal. All you will need is a web developer with access to you site and familiarity with REST APIs.

Job Applications

Most job portals start with a list of jobs, and the CATS API makes this easy by giving you a single endpoint to fetch all the jobs you have published to a portal. To do this, you will need to know the id of the portal you are publishing your jobs to. If you don’t know your portal id, you can pull up a list of all your portals with the following call:

GET https://api.catsone.com/v3/portals

We see here that I have 4 portals on my site, and I’m interested in using the last one as my website job portal. All I need to do is note down that id for it: 78617. Once I have that id I can now build the url I need to fetch all the jobs from that portal. Note the portal id in the url, and replace with your portal id:

GET https://api.catsone.com/v3/portals/78617/jobs

00%20PM

I currently have 2 jobs published to that portal. While portals can have up to 500 jobs on that at a time, this call will only return 25 total jobs by default. If you foresee having more than 25 jobs on your portal, you will want to fetch multiple pages of jobs using ?page= and per_page= query parameters. Fetching the second page of 100 jobs (jobs #101-200) would look like this:

GET https://api.catsone.com/v3/portals/78617/jobs?per_page=100&page=2

Helpful pagination links will also be included in the _links section of the result JSON if they exist.

Now that you have all your published jobs, it’s up to you how you want to display them on your site. You can build a jobs listing page with the data as well as individual job pages. It is highly recommended that for any public facing pages that are querying the CATS API, that you cache your results, otherwise you could quickly hit your API call limit. Querying the jobs endpoint and then saving those results for as little as 5 minutes could result in significantly less API usage depending on how much traffic your site gets.

Now that you have all your job listings, you’ll want to be able to generate an application form. Because we embed various bits of relevant data in all of the JSON you pull down from the API, from you previous call you already have the application id[s] (you can have 1 more applications tied to a job). In the following screenshot you can see an example of where in the JSON to find the applications:

This job only has one application associated with it, so it will be easy. If your job has more than one application associated with it, you’ll want to repeat the following step for each application to get all of the fields.

To get the applications for a job we’ll need to take that application id and make the following call with it:

https://api.catsone.com/v3/jobs/applications/119811/fields

With this list of fields (9 in this case) you should now be able to create an application form on your site. You’ll want to store this data, since you will need to reference it when actually submitting the application, which we will deal with next.

Once your site visitor has filled out and submitted their application, you will need to submit it to the API. Here’s what an example of what the request would look like:

POST https://api.catsone.com/v3/portals/78617/jobs/11573513

As you can see most fields are submitted in a simple format with the id of the field and the value you wish to submit for it. There are a couple special cases, one of which is uploading files, where the value is a base64 encoded version of the file and there is an additional parameter for the name of the file. For other field types that might be slightly different than a typical text field, you can check out the documentation for this endpoint at https://docs.catsone.com/api/v3/#portals-submit.

Registration

If you want users to be able to register in your system, but not to a specific job, you can use the built-in registration functionality in CATS. In the CATS UI when creating applications, you can define one as your registration application. This application can then be fetched and submitted without referencing a job.

First, to fetch you will make the following call (replacing 78617 with your portal id):

GET https://api.catsone.com/v3/portals/78617/registration

You’ll notice that this response is formatted like normal application object. You can build a JSON object to submit exactly like you would for the normal submit endpoint. However, we will be submitting this registration application to its own submit endpoint, like so:

POST https://api.catsone.com/v3/portals/78617/registration

And that’s it! More detail about all these endpoints can be found in our API documentation.