1. Introduction
  2. How to Invoke the API
    1. On Behalf of Yourself
    2. On Behalf of Other JyMob Users
  3. Development Mode and Production Mode Settings


Welcome to the JyMob API. Our goal is to create a RESTful API that you developers will love. Most of the JyMob core abstractions (e.g. JobPosts, JobApplications, ScreeningTests) are exposed through the API. The idea is that you can integrate JyMob's offerings in your website without having to make any database calls. All you need is accessing this API in a secure manner by making REST calls over HTTP(S)!

Please let us know your feedback. If you already know how to invoke the API, just browse it here.

How to Invoke the API

Calling the API is easy and secure. The authorization is based on the OAuth 2 standard. In short, it revolves around the so-called access token, which acts like a valet key.

Although calling the API is easy, developers have much to learn and it may seem complicated at first. If you have ideas about how to further simplify the procedure, please let us know.

Basic idea is that you call the API as an app authorized by a JyMob user. The authorized app itself is associated with a JyMob user account. So, the first step is to let JyMob know that you want to be an app by creating your JyMob account. In OAuth lingo, such an app is called an OAuth Client and has a unique identifier (Client ID) and a secret. And since any JyMob user can wish to be an app, these credentials are already created for you once you sign up. Here are the initial steps:

  1. Register at JyMob as a user. Do this now.
  2. Let's call this user app_user . This user is like any other JyMob user, it's just that the main intent of this user is to call JyMob programmatically using REST API.
  3. Go to your Settings page and see the OAuth Client Application tab. You'll see three settings. Note the Client ID and Client Secret. Paste buttons are provided on that screen for your convenience.
Setting Detail
Client ID JyMob generated, unique, read-only. DO NOT SHARE.
Client Secret JyMob generated, unique, read-only. DO NOT SHARE.
An Optional Redirect URI Optional. Configured and maintained by you. Required if you plan to call JyMob API from your website. Leave this blank if you want to use curl/wget as your app. We will redirect to this URI after actual user approves/denies authorization request.

Two API acccess cases are of interest and thankfully, they are equivalent:

  1. Making API calls on behalf of your own JyMob user account
  2. Making API calls as an app authorized by another JyMob user

On Behalf of Your Own JyMob User Account

This is just a piece of cake with JyMob and is much more secure than HTTP Basic Auth! Access Token is already created for you when you sign up for JyMob. We use this method all the time to call the API ourselves. We get the access token and call curl like mad on our API tests. Here is the simple 1-2-3 process:

ID Details
1 Register, sign in and then go to the oauth client settings page.
2 On that screen you have your access token along with the handy clippy (for copy + paste).
3 Call API like: https://api.jymob.com/v1/job_posts.json?access_token=<access_token>

If you think you compromised your access token, no problem. Just go to your Authorized Apps page, find your own app (tagged YOUR OWN APP! ) and just revoke its authorization. When you go back to your oauth client settings page, you'll be given a new access token. Snappy, isn't it? You never had to divulge or change your JyMob password. Also, you didn't have to put your password in a file in clear! That's the benefit of using OAuth.

As an Authorized Webapp or Mobile App

This is a typical B2B API-usage scenario, but you'll need to do a little more work. You have a website or mobile app and you want to integrate with JyMob website so that user's resources are nicely compartmentalized but they amicably cooperate with each other. For instance, user's screening tests reside on JyMob and you get to display them to that user when s/he logs on to your website. This user has accounts on both your website and JyMob and s/he authorizes you, the user app_user, to access her/his account. Once you get the authorization, JyMob gives you an access token if you asked for it immediately as you learn that the user authorized you. Thus, access token is king. And your entire pursuit is to get the access token to act on another user's behalf after his/her consent.

This interaction typically happens on a web browser or mobile device and three parties are involved: Your website, JyMob website and the end user via a web browser. We assume that you have followed the process to register as a JyMob App or OAuth Client. Let's also assume that a human user Joe has user account on both your website and JyMob. Now follow these steps:


0. Understand Prerequisites

  1. Always use SSL and SSL only. All non-SSL requests will be redirected to SSL. Be prepared to handle redirects.
  2. API Endpoint is this website -- https://api.jymob.com/v1
  3. Current API version: v1
  4. The responses and request URL's are JSON and XML only.
  5. If you leave out the "version part" of the URL, the current default implementation is invoked.

1. Request an Authorization from Joe

We suggest that you do this (usually) one-time activity over the web browser or mobile device because this involves the sophisticated OAuth song-and-dance and it is easier to just do it in the browser. You can do it using curl or command line, but you'll need cookie handling, which we strongly discourage.

Request: GET

URL: https://jymob.com/oauth/authorize?response_type=code&client_id=<client-id>&client_secret=<client-secret>&redirect_uri=<redirect-uri>

Send this exact request and there will be no complications.

Response Status Code (you must provide the redirect_uri parameter)

302: Found

Response Headers (Joe Approves App's Authorization) Yes, I Authorize

Location: <redirect_uri>?code=<authorization-code>
for example, if Google integrated with JyMob, the Location header would be something like: http://google.com/jymob_callback?code=9FFYjCmjwSUFIxN3fHXDIQkJ

Response Headers (Joe Denies App's Authorization) No, thanks

Location: <redirect_uri>?error=access_denied

Response Body


2. Obtain the Authorization Code

The first step sends a redirect to the browser or mobile app and it then should redirect the end user to that redirect_uri, which belongs to your own server.

Thus, the returned Location header is of essence. Note the code sent (e.g. 9FFYjCmjwSUFIxN3fHXDIQkJ) in that header.

3. Immediately Request Access Token

Using this code, you must request an access token immediately. If you fail to do so, the auth code may expire and your request to obtain access token will be invalidated.


URL: https://jymob.com/oauth/access_token

Request Body


Response Status Code: Case -- Success

200: OK

Response Headers

Content-Type: application/json Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Response: Body (JSON) Case -- Success


Thus this time the access token is sent in the body and if you used SSL, this should be secure. Parse the JSON response and get the "access_token" from it.

There! You got the access token. Remember, with great power, comes great responsibility.

4. Securely Save Access Token

Save the access token along with user Joe's account on your website. This allows you to call the API using access token in future without Joe's repeated involvement in granting/denying the access. Note that access token is like password to some extent and you should save it securely.

5. Refresh Access Token

TBD ... (Note that the default token validation period is 1 month, which is expressed in expires_in whose value is 2592000 seconds).

6. Call API Like Crazy!

Now you can call the API like this:

Access Token is King!


This of course works till the user Joe continues to have your app authorized to access his account. It is assumed that Joe gives an implicit permission to you to access his JyMob resources as long as you have a valid access token (controlled by an "Authorization"). Thus, subsequent interactions can happen without explicit grant of authorization.

That's it. Browse the API.

Development and Production

We want to make every attempt to make it easier for you to develop your own interfaces easily, using our API. We know that you want to test out the integration before you put it in production. As of now, we don't have any staging environment as such, so all of JyMob's production data is available and you can call the API's on that. Don't worry, it is like creating a user or two at http://jymob.com and then trying things out. Go ahead, do that. The question about the redirect_uri can also be easily answered. Either you can use the same redirect_uri, or create two different user accounts (one for development and one for production) and use the production URI e.g. https://mywebsite.com/jymob_callback and development URI like http://localhost:4444/jymob_callback to handle the OAuth callback.