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

Depending on the endpoints, you will need to choose the language in which the member you provision will be able to see the MyPrint or the results in as well as the language the report will be generated with.

When a member is created or updated, a language parameter can be defined. The language provided will be used for both the MyPrint questionnaire and the results shown to the member.

Other endpoints, such as for report generation, require you to pass the wanted language as a Accept-Language header:

Accept-Language: %preferred-language%.

Talentoday's MyPrint questionnaire, member "One Pager" results, and reports are available in 7 languages:

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

2. Generate a link

Generate an embed link

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

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

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 processEvent = (event: TtProgressEvent|TtStateChangeEvent): void => {
    if (allowedOrigins.indexOf(event.origin) === -1) {
        throw 'not from Talentoday!'
    }

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

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

window.addEventListener("message", (event) => processEvent(event));

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:

• registration: the user is viewing the initial registration page
• complete: the user is reading the instructions or taking the questionnaire
• opmi_registration: the user is viewing the detailed registration page
• wait_after_completion: the user is seing a spinner and waiting to be redirected by the parent application
• results: results snapshot as a "one pager"

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.

Customize the appearance

Upload a logo

HTTP Request

POST https://app.talentoday.com/partners-api/v1/subscription/customizations/logo (details)

Use the provided token to create a customization item.

Create a reusable customization

curl -H "Authorization: Bearer toto" \
     -H "Content-Type: application/json" \
     --request POST \
     --data '{"title":"green-feeling", "customizations": {"--myprint-primary-color": "50,205,50", "--myprint-primary-color-opacity": "0,255,0", "--myprint-secondary-color": "34,139,34"}}' \
     https://app.talentoday.com/partners-api/v1/subscription/customizations

The above command returns JSON structured like this:

{
  "code":201,
  "message":"success",
  "data": {
    "id": "76413d0d-b08e-4a38-a691-1755c3f37967",
    "title": "green-feeling",
    "customizations":
    {
      "--myprint-primary-color": "50,205,50",
      "--myprint-primary-color-opacity": "0,255,0",
      "--myprint-secondary-color": "rgb(34,139,34)"
    }
  }

For more details and visuals regarding the customizations' effects, please take a look at this presentation.

HTTP Request

POST https://app.talentoday.com/partners-api/v1/subscription/customizations (details)

Body payload (JSON)

Use a customization

See the generate a link part. Use the customization_id parameter to override the questionnaire page's colors and/or logo.

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)

Custom Report

Use the below command to upload a logo for future use with a custom detailed report generation.

curl -H "Authorization: Bearer toto" \
     -H "Content-Type: multipart/form-data" \
     --request POST \
     --form 'attachment=@"/path/to/your/file.jpg"' \
     https://app.talentoday.com/partners-api/v1/reports/custom_logo

The above command returns a JSON structured like this:

{
  "logo_token":"1Vb15AUqjjDptgskaFZkANy6",
  "message":"Logo generated, add this token to your custom report request with 'detailed_cover_type' set to 'client_logo'"
}

With the Custom Report, you can choose the sections of a Detailed Report that you want to show/hide.

Create a custom logo

POST https://app.talentoday.com/partners-api/v1/reports/custom_logo (details)

The retrieved token can then be used to link a logo to a report when requesting a custom report generation for the client_logo detailed_cover_type (see below).

Custom Report HTTP Request

Example of a custom report request for member with id 64, in french, with a custom logo, no introduction and no motivations information.

curl -H "Authorization: Bearer toto" \
     -H "Content-Type: application/json" \
     --request POST \
     --data-raw '{
       "configuration": {
         "language": "fr-FR",
         "detailed_cover_type": "client_logo",
         "detailed_introduction": false,
         "detailed_motivations_scales": false,
         "detailed_motivations_poles": false,
         "detailed_logo": {
           "token": "1Vb15AUqjjDptgskaFZkANy6"
         }
       }
     }' \
     https://app.talentoday.com/partners-api/v1/members/64/opmi/reports/custom

The above command returns a JSON structured like this:

{
  "code": 202,
  "url": "https://app.talentoday.com/partners-api/v1/reports/status?download_token=fNiED113GAinodHN69MSgDP5",
  "message": "Report generating... use url field to ping for status.",
  "configuration": {
    "language": "fr-FR",
    "detailed_cover_type": "client_logo",
    "detailed_introduction": false,
    "detailed_table_of_contents": true,
    "detailed_personality_axes": true,
    "detailed_personality_poles": false,
    "detailed_motivations_scales": false,
    "detailed_motivations_poles": false,
    "detailed_behaviors_introduction": true,
    "detailed_behaviors_summary": true,
    "detailed_behaviors_matrices": true,
    "detailed_about_company": false,
    "detailed_logo": {
      "token": "Avu16RBc8qtHdfTqzXR6fbJm"
    }
  }
}

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

configuration object parameters

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)

Group DNAs

Use the below command to create a Custom Group DNA.

curl -H "Authorization: Bearer toto" \
     -H "Content-Type: application/json" \
     --request POST \
     --data-raw '{
        "member_ids": [
          1,
          2,
          3
        ],
        "title": "A Group DNA title",
        "description": "A Group DNA description"
      }' \
     https://app.talentoday.com/partners-api/v1/group_dnas/opmi

The above command returns a JSON structured like this:

{
  "data": {
    "id": 1,
    "slug": "a-group-dna-title",
    "title": "A Group DNA title",
    "description": "A Group DNA description",
    "gdna_type": "custom",
    "member_ids": [1, 2, 3]
  }
}

Create a Custom Group DNA

Our Partners API allows you to create Group DNAs. The group DNA exhibits the 13 personality traits and 11 needs that are the most common among a given population. To create your Custom Group DNA, you'll need to specify:

• member_ids from users of your subscription who have completed the questionnaire
• title of your Group DNA
• description of your Group DNA (optionnal)

More HTTP Requests

To know more about what you can do with Group DNAs, check the Technical Specs:

GET https://app.talentoday.com/partners-api/v1/group_dnas/opmi (details)

Retaking the questionnaire

Talentoday MyPrint results can evolve with time. It is interesting to take the questionnaire regularly to have an up-to-date view of the results and be able to observe one's evolution.

We recommend a minimal interval of 6 months between two questionnaires and this limit is enforced by the Partners API. Your integration will need to take into account this interval.

1. Checking for a member eligibility

Use this request to get a member's questionnaire status

curl -H "Authorization: Bearer toto" \
     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": null,
    "last_questionnaire": null,
    "completed_questionnaires": []
  }
}

Here the member hasn't started or completed any questionnaire yet. next_questionnaire_at is null meaning the member is not eligible for retake.

Calling the same endpoint after the member takes the questionnaire:

curl -H "Authorization: Bearer toto" \
     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": "2020-12-02T09:51:27.290Z",
    "last_questionnaire": {
      "id": 115,
      "completed_at": "2020-06-05T09:51:27.290Z",
      "status": "completed",
      ...
    },
    "completed_questionnaires": [
      ...
    ]
  }
}

next_questionnaire_at indicates when the user will be eligible for retake.

Use the questionnaire's status endpoint to determine whether a member is eligible to retake.

HTTP Request

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

Notes

next_questionnaire_at can be either:

• null, there is an ongoing questionnaire or the member hasn't started (not eligible to retake)
• a given date, the member is eligible if the given date is in the past

2. Generate a retake link

See the generate a link part. Use the allow_retake parameter to let the member retake the questionnaire.

3. Embedding the results

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

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

The above command returns JSON structured like this:

{
  "url": "https://app-light.talentoday.com/opmi/questionnaires/eyJhbGciOi..."
}

Using last as questionnaire_id will always take the member to the results of the last completed questionnaire.

If a member has an ongoing questionnaire, the embed questionnaire endpoint will always produce a link that will redirect to the last not-answered question. To be able to consistently direct members to their "One Pager" webview of a past completed questionnaire, this other embed endpoint is at your disposal.

HTTP Request

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

URL Parameters