NAV
cURL

Introduction

Welcome to the Talentoday Partners API developers guide. This API will enable your company to automate user management, questionnaire lifecycle and result downloads, all within the scope of your Talentoday subscription.

This guide's goal is to help you build your Talentoday integration faster by providing detailed walkthrough for most common scenarios.

You can view curl examples on the right side of this page. Some front-end integrations are also described using the typescript language.

Access the full definition of the API's endpoints here.

The API spec gives you the detailed description of available endpoints as well as required and optional arguments and headers needed to use the APIs.

Language

Pass an Accept-Language header on each request

curl "api_endpoint_here" \
  -H "Accept-Language: fr-FR"

With this you can download reports in french for instance

Most endpoints use a language Header to determine how to serve questionnaires or generate reports:

Accept-Language: %preferred-language%.

Talentoday's MyPrint questionnaire and reports are available in 7 languages:

Name Code
English en-US
French fr-FR
German de-DE
Spanish es-ES
Portuguese pt-BR
Italian it-IT
Chinese simplified zh-CN

Some endpoints such as for member management will accept a language parameter to create or update a user.

Authentication

Pass the correct header with each request

curl "api_endpoint_here" \
  -H "Authorization: Bearer <api-token>"

You must replace <api-token> with your API token.

The Talentoday Partners API is only available for partner companies. Please contact sales@talentoday.com if you do not have an access token.

Talentoday uses Bearer authentication to authenticate API calls.

Pass your issued API key on every request by adding the following Header:

Authentication: Bearer %api-token%.

Embedding questionnaires

Talentoday Partners API enables you to manage users and generate unique, pre-authentified links for them to take the questionnaire.

The generated link can be embedded directly within your application using an iframe. The link can also be transferred to members directly using email or CRM/ATS software.

Let's walk through the process of creating a link.

1. Create a user

First step is to provision the user that needs to take the Talentoday questionnaire

curl -H "Authorization: Bearer toto" \
     -H "Content-Type: application/json" \
     --request POST \
     --data '{"first_name":"xyz","last_name":"xyz","gender":"other","language":"es-ES"}' \
     https://app.talentoday.com/partners-api/v1/members

The above command returns JSON structured like this:

{
  "data": {
    "id": 144,
    "first_name": "Xyz",
    "last_name": "Xyz",
    "email": "talentoday-d8156f6ed8a39e9353c34063037a1ef7@api-bounces.talentoday.com",
    "gender": "other",
    "location": null,
    "foreigner_id": null,
    "language": "es-ES",
    "registration_status": {
      "pre_registered": false,
      "post_registered": false
    },
    "secondary_email": null,
    "date_of_birth": null
  }
}

HTTP Request

POST https://app.talentoday.com/partners-api/v1/members/create (details)

URL Parameters

Parameter Description
first_name First name for the member
last_name Last name for the member
gender male, female or other
language One of the 7 language codes available - see above
foreigner_id Use this string field to set a custom application ID
secondary_email Primary email is auto generated. Use this to show the right email on the Talentoday Manager

First step is to provision the user that needs to take the Talentoday questionnaire

curl -H "Authorization: Bearer toto" \
     -H "Content-Type: application/json" \
     --request POST \
     --data '{"skip_registration":"all"}' \
     https://app.talentoday.com/partners-api/v1/members/144/opmi/embed

The above command returns JSON structured like this:

{
  "url": "https://app-light.talentoday.com/embed/opmi?token=eyJhbGciOi..."
}

HTTP Request

POST https://app.talentoday.com/partners-api/v1/members/{member_id}/opmi/embed (details)

The returned url is valid for 2 months.

URL Parameters

Parameter Description
skip_registration Set it to all for the member to not see any registration form
show_results_after Set it to false to prevent the user from seing the "one pager" results at the end. Forced to false for personality and motivations scenarios. Defaults to true
scenario Have the user take either the personality only, the motivations only, or the full questionnaire (default)

3. Embed as an iframe

Add the following snippet in your template's HTML:

<iframe src="{https://app-light.talentoday.com/embed/opmi?token=eyJhbGciOi...}"></iframe>

You are now able to integrate the questionnaire and results as a webview within your app using an iframe.

Monitoring progress

The Partners API offers a number of ways for your application to be reactive to events that occur on the Talentoday app (redirect the user after completion, trigger an email...).

Using the list endpoint

Get the list of users that updated their data or completed a questionnaire since the start of your subscription:

curl -H "Authorization: Bearer toto" \
     --request GET \
     https://app.talentoday.com/partners-api/v1/subscription/people_assessed/list

The above command returns JSON structured like this:

{
  "meta": {
    "pagination": {
      "delta_token": null,
      "next_page_token": "eyJmcm9tX3RpbWVzdGFtcCI6MCwiZnV0dXJlX2RlbHRhX3Rva2VuX3RpbWVzdGFtcCI6MTYwNDY1NDk5OSwicGFnZV9udW1iZXIiOjJ9"
    }
  },
  "data": [
    {
      "id": 16,
      "email": "ktreble2-mock@cnbc.com",
      "first_name": "Krishnah",
      "last_name": "Treble",
      "location": null,
      "gender": "male",
      "date_of_birth": null,
      "foreigner_id": null
    },
    {
      "id": 26,
      "email": "aapplegatec-mock@independent.co.uk",
      "first_name": "Adey",
      "last_name": "Applegate",
      "location": null,
      "gender": "female",
      "date_of_birth": null,
      "foreigner_id": null
    },
    ...
  ]
}

Use the provided next_page_token to go through all updates

curl -H "Authorization: Bearer toto" \
     --request GET \
     -G \
     -d "next_page_token=eyJmcm9tX3RpbWVzdGFtcCI6MCwiZnV0dXJlX2RlbHRhX3Rva2VuX3RpbWVzdGFtcCI6MTYwNDY1NDk5OSwicGFnZV9udW1iZXIiOjJ9" \
     https://app.talentoday.com/partners-api/v1/subscription/people_assessed/list

The above command returns JSON structured like this:

{
  "meta": {
    "pagination": {
      "delta_token": "eyJkZWx0YV90b2tlbl90aW1lc3RhbXAiOjE2MDQ2NTQ5OTl9",
      "next_page_token": null
    }
  },
  "data": [
    {
      "id": 144,
      "email": "talentoday-d8156f6ed8a39e9353c34063037a1ef7@api-bounces.talentoday.com",
      "first_name": "Xyz",
      "last_name": "Xyz",
      "location": null,
      "gender": "other",
      "date_of_birth": null,
      "foreigner_id": null
    }
  ]
}

There currently are no more updates (next_page_token is null). Consider storing the delta_token and use it on the next visit to pull only members with updates.

Use this method to regularily list members that changed since your last visit (member update, questionnaire state change).

HTTP Request

GET https://app.talentoday.com/partners-api/v1/subscription/people_assessed/list (details)

URL Parameters

Parameter Description
delta_token Provided by a previous query. Store it and use it on your next visits to view only newly updated members
next_page_token Provided by a previous query. Use it to exhaust all users updated before getting a new delta_token

Using the questionnaire status endpoint

curl -H "Authorization: Bearer toto" \
     --request GET \
     https://app.talentoday.com/partners-api/v1/members/144/opmi/questionnaire/status

The above command returns JSON structured like this:

{
  "data": {
    "member_id": 144,
    "next_questionnaire_at": "2021-05-05T15:49:37.450Z",
    "last_questionnaire": {
      "id": 98,
      "completed_at": "2020-11-06T15:49:37.450Z",
      "completion_time": 155,
      "status": "completed",
      "started_at": "2020-11-06T15:49:33.857Z",
      "completion_progress": {
        "personality": true,
        "motivations": true
      }
    },
    "completed_questionnaires": [
      {
        "id": 98,
        "completed_at": "2020-11-06T15:49:37.450Z",
        "completion_time": 155,
        "status": "completed",
        "started_at": "2020-11-06T15:49:33.857Z",
        "completion_progress": {
          "personality": true,
          "motivations": true
        }
      }
    ]
  }
}

While a user is taking a questionnaire, you can opt to continuously poll the individual questionnaire status endpoint.

HTTP Request

GET https://app.talentoday.com/partners-api/v1/members/{member_id}/opmi/questionnaire/status (details)

Use the last_questionnaire's status to determine the completion state of the questionnaire for the member.

Dynamic integrations

Use this typescript example as a starting point to build your front-end application

interface TtProgressEvent extends MessageEvent {
    data: {
        event: 'questionnaire_progress';
        payload: {
            progress: number;
        }
    }
}

interface TtStateChangeEvent extends MessageEvent {
    data: {
        event: 'state_change';
        payload: {
            new_state: 'registration'|'complete'|'wait_after_completion'|'opmi_registration'|'results';
        }
    }
}

const allowedOrigins = ['https://app.talentoday.com', 'https://app-light.talentoday.com'];

const processMessage = (message: TtProgressEvent|TtStateChangeEvent): void => {
    if (allowedOrigins.indexOf(message.origin) === -1) {
        throw 'not from Talentoday!'
    }

    if (message.data.event === 'questionnaire_progress') {
        console.log(`Questionnaire completed by ${message.data.payload.progress}%`);
        return;
    }

    if (message.data.event === 'state_change') {
        console.log(`Entered new state: ${message.data.payload.new_state}%`);
        return;
    }
}

You can use the typescript playground to convert this code to vanilla javascript.

Once the Talentoday iframe is loaded and the user starts interacting with it, it will emit a number of events using the PostMessage API. The parent application can listen to this event and perform updates to its own backend, UI or redirect the user to an other page.

An event is emitted on init and every time the state of the questionnaire changes:

During the complete state (questionnaire completion in progress), an event will be emitted each time an answer is processed. Its payload contains the progress percentage.

Reports

Report generation and download is a two step process. The generation process is run asynchronously every time your application requests it, so your application has to wait for this process to complete before receiving a download link.

Generation

Use the below request to request a "one pager" report for member with ID 144

curl -H "Authorization: Bearer toto" \
     --request POST \
     https://app.talentoday.com/partners-api/v1/members/144/opmi/reports/basic

The above command returns JSON structured like this:

{
  "code": 202,
  "url": "https://app.talentoday.com/partners-api/v1/reports/status?download_token=t9xSug88aESUk8VS5nmWd97v",
  "message": "Report generating... use url field to ping for status."
}

Use the provided url to poll and wait for a report download link

Individual One Pager Report

POST https://app.talentoday.com/partners-api/v1/members/{member_id}/opmi/reports/basic (details)

Individual Detailed Report

POST https://app.talentoday.com/partners-api/v1/members/{member_id}/opmi/reports/detailed (details)

Collaboration Report

POST https://app.talentoday.com/partners-api/v1/members/{member_id}/opmi/reports/collaboration/{other_member_id} (details)

Download

After polling on the reports/status a few times, you will receive the download link

curl -H "Authorization: Bearer toto" \
     --request GET \
     http://app.talentoday.com/partners-api/v1/reports/status?download_token=t9xSug88aESUk8VS5nmWd97v

The above command returns JSON structured like this:

{
  "code": 200,
  "url": "http://app.talentoday.com/downloads/2ca24fc1c3b783feac6d1/talentoday-2020-11-06_17-02-opmi-xyz-xyz.pdf",
  "message": "Report generated... use url field to download."
}

Poll the reports/status endpoint with the provided download_token until it answers with status 200.

We advise a polling frequency of 2 seconds.

HTTP Request

GET https://app.talentoday.com/partners-api/v1/reports/status (details)