Introduction

Welcome to the Talenteca API guide documentation.

This guide will help you to integrate your apps with Talenteca for sharing job ads, candidates, recruiters and company information securely and productively.

Talenteca is a job board for publishing job ads and connect companies with good new employees.

This guide is intended for developers with experience with HTTP, JSON, OAuth, REST, security and programming.

To continue you may click or touch the next page buttons or even use the left and right arrows of your keyboard to advance.

If you need help, please do not hesitate to write us to support@talenteca.com

Getting Started

The Talenteca API provide services for publishing job ads and recieve candidates using JSON over HTTPS connections.

An app can make calls to Talenteca following these steps:

First, get your security credentials from Talenteca
With your security credentials you can get access tokens from Talenteca users.
Using a valid access token you may now make calls to Talenteca.

1. Security Credentials

The security credentials includes an app ID and an app secret with a list of scopes of services you are entitled to access.

Please contact Talenteca via support@talenteca.com for more information and for getting your security credentials.

Once you get your security credentials, keep the app secret encrypted, hidden and safely stored, it's your responsability to keep this information secure and safe, if not, Talenteca will revoke your access.

2. Access Tokens

An access token is just a long random string with your app ID and the Talenteca user ID inside for granting permissions to call the Talenteca API.

For getting an access token you need to redirect your user to Talenteca using your app ID.

This redirect contains what is called a challenge code, which is simply another long random string used to identify your permission request.

It's important to notice that a challenge code it's only valid for a couple of minutes. This is for reducing exposure of sensible data between your system, our users and Talenteca.

Once the user grants your app with the right permissions, you may exchange the challenge code while is valid and active, for a long lasting valid access token.

3. Make Talenteca API calls

With a valid access token, now you can make calls to Talenteca.

A call to Talenteca API has the following characteristics:

The Talenteca API calls use JSON endpoints over HTTPS.
For making the calls easier, only the HTTP POST method is required.
The only response codes we use are OK (200), Bad Request (400) and Server Error (500).

Services

The Talenteca API services are published at https://www.talenteca.com/api for helping on handling data for recruiters, job ads, candidates and applications.

1. Recruiters

Recruiters are the Talenteca users in charge of publishing, editing and managing job ads including the candidates that apply to their job ads.

2. Job ads

Job Ads are open positions offered by a company requiring new employees.

3. Candidates

Candidates are potential new employees than can apply to a job ad.

4. Applications

Applications are candidates intentions to enroll in new positions published on job ads.

Next steps

Now you can continue with the guide to learn more about security and the available services to call.

Anatomy of a call

Let's see how a Talenteca API call is componsed for getting the list of job ads of a Talenteca recruiter.

Once you got your security credentials from Talenteca, the steps to perform are:

Obtain a challenge code
Request permission to the recruiter
Get a valid access token
Call the job ads endpoint using the valid access token

1. Obtain a challenge code

Once you have your app ID and secret you can request a new challenge code, for this, please send a post message to: http://www.talenteca.com/api/v1/oauth/recruiter/challenge-code

with the body similar to:

{
  "app_id" : "MY_APP_ID",
  "app_secret" : "MY_APP_SECRET"
}

Please find a reference in the code at RecruiterApp::getChallengeCode() on how to do it.

This is only necessary once per new recruiter you want to connect and authorize

2. Request permission to the recruiter

Using the new challenge code you can request authorization to the recruiter for using your app, for this, redirect the recruiter to:

http://www.talenteca.com/auth/recruiter-app?recruiter_app_id=MY_APP_ID&challenge_code=NEW_CHALLENGE_CODE&redirect=$MY_CALLBACK_PAGE

For recruiter_app_id use your assigned app ID.

For challenge_code use the challenge code obtained in the previous step.

For redirect, use the page that will receive the result of the authorization (only registered domains are valid)

3. Get a valid access token

Once the recruiter authorize your application you can get the access token sending a post message to:

https://www.talenteca.com/api/v1/oauth/recruiter/access-token

with the body similar to:

{
  "app_id" : "MY_APP_ID",
  "app_secret" : "MY_APP_SECRET",
  "challenge_code" : "CHALLENGE_CODE"
}

Once you get the access token, please store it encrypted and safely associated to your recruiter user.

This is only necessary one per recruiter you want to connect using your app

IMPORTANT: If you compromise or leak one or more access tokens or receive an attack, please inform Talenteca immediatly to support@talenteca.com for regenerating new tokens, the access tokens are very sensible and should be stored and kept safe.

4. Call the job ads endpoint using the valid access token

With the access token you can make calls to Talenteca in behalf of your recruiter users, simple include the access token per recruiter as the header Bearer in each request.