Exemples d'intégrations pouvant être faites avec notre API v2

Voici deux exemples d'intégrations qu'il est possible de faire depuis notre API ou nos iFrames.

Toutes les actions possibles depuis nos API sont disponibles dans cette documentation technique.

 

Process classique d'utilisation de notre API

Process depuis une iFrame

 

Utilisation de l'API pour se servir d'AssessFirst comme d'un outil d'évaluation dans un ATS :

Graphique avec les liens vers notre documentation API

Voilà un exemple d'une intégration classique faite par nos partenaires.

3 étapes :

1/ Récupération des modèles prédictifs

Il est nécessaire de récupérer le modèle prédictif propre à chaque client pour que, dès qu’un candidat termine ses questionnaires, les rapports et les scores soient calculés avec le bon modèle.

Nous recommandons d'afficher cette liste dans une "liste déroulante", soit au niveau des offres ou lors de l'envoi de l'invitation.

Endpoint -> GET/predictive-models

Réponse :

{
  "data": [
    {
      "uuid": "1d9c92277e264fe49a4ce330e51e6ac7",
      "name": "web designer",
      "assessments": {
        "swipe": true,
        "drive": true,
        "brain": true,
        "voice": true
      },
      "is_public": 1,
      "created_at": "2025-03-27 13:49:40"
    },
    {
      "uuid": "465bfe38970542138ac208a087bf18bf",
      "name": "developpeur web",
      "assessments": {
        "swipe": true,
        "drive": true,
        "brain": true,
        "voice": false
      },
      "is_public": 1,
      "created_at": "2025-04-28 09:22:55"
    }
}

2/ Envoi de l'invitation

Permettre d'envoyer une invitation. Plusieurs possibilités, soit :

- lors d'un changement de statut (Ex lors du changement d'un statut New à Screening)

- lors de la création d'un nouveau candidat

- lors d'un clic sur un bouton spécifique (ex : AssessFirst)

 

Endpoint : POST/candidate/send-invitation

Request :

curl --location 'https://app.assessfirst.com/betty-V2/candidate/send-invitation' \
--header 'AF-Token;' \
--data-raw '{
    "email": "rooky@hotmail.fr",
    "first_name": "Firstname",
    "last_name": "Lastname",
    "gender": "n",
    "recruiter_email": "myrecruiter@yopmail.fr",
    "predictive_model_uuid": "9228c56c5f464457a84dcc40891ba80d"
}'

 

Réponse :

{
  "uuid": "3c1db191b6af4de4b04df708e1bf10c6",
  "last_invited_at": "2025-05-16T09:15:43.000000Z",
  "status": "invitation_sent"
}

Plusieurs réponses possibles (Status) :

3/ Récupération des résultats

Selon le statut obtenu lors de l’envoi de l’invitation, vous allez pouvoir récupérer les résultats.

Dans un 1er temps, lors de l'activation de l'intégration, il est important de s'abonner aux webhooks suivant pour que vous puissiez recevoir les différentes notifications :

- assessment.finished : Dès qu'un candidat termine un questionnaire

- user.linked : Lorsqu'un candidat accepte l'invitation du recruteur

- user.completed : Lorsqu'un candidat a terminé tous les questionnaires (Optionnel, selon votre usage)

 

Endpoint : POST /webhooks

Request :

curl --location 'https://app.assessfirst.com/betty-V2/webhooks' \
--header 'AF-Token;' \
--data '{
    "name": "Test API V2",
    "url": "https://webhook.site/0adbd59d-5c49-44da-9368-24413ea555b3",
    "actions": [
        "assessment.finished",
        "user.completed",
        "user.linked"
    ]
}'

 

En fonction du statut que vous allez récupérer dans le POST send-invitation, vous allez pouvoir récupérer les résultats à différents moments :

1/ Le candidat n'a pas de compte AssessFirst => Invitation_sent

Dans ce cas-là, vous allez pouvoir venir récupérer les résultats d'un candidat dès que vous recevez le webhook assessment.finished.

Vous recevrez aussi un user.completed une fois que le candidat aura terminé tous les questionnaires demandés.

2/ Le candidat a déjà un compte, mais il n'est pas partagé avec le client => ask_share

Vous devez attendre de recevoir un webhook user.linked pour indiquer que le candidat a accepté de partager ses résultats. Vous pouvez à ce moment-là, voir si le candidat a terminé ses questionnaires, si oui, vous pouvez aller récupérer les résultats, si non, vous pouvez attendre un assessment.finished

3/ Le candidat partage déjà ses résultats avec le client => already_completed ou added_to_network

Vous ne recevrez pas de webhook pour ce cas, sachant que le candidat a terminé tous ses questionnaires et qu'il partage déjà ses résultats avec le client. Vous pouvez donc directement récupérer les résultats ou ne rien faire selon le besoin.

 

EndPoint pour récupérer les résultats :

Il y a plusieurs façons de récupérer les résultats d'un candidat

• Des liens que vous affichez dans votre application et qui redirigent directement vers les PDFs sur l'application AssessFirst.
  Endpoint : GET/candidate/{uuid}/reports
  Réponse :

[
  {
    "id": 20,
    "name": "Summary of findings",
    "assessment": "All assessments",
    "web_link": "https://report-simu.assessfirst.com/report/summary_report/47d94f75d607489aab9da13781ad2bb9/company/0bf7cb0aa2734be5988035a794272cd4?from=api"
  },
  {
    "id": 1,
    "name": "In-depth analysis",
    "assessment": "Personality",
    "web_link": "https://report-simu.assessfirst.com/report/swipe_depth/47d94f75d607489aab9da13781ad2bb9/company/0bf7cb0aa2734be5988035a794272cd4?from=api"
  }, ...

• Récupérer directement les PDFs sur vos serveurs
  Endpoint : GET/candidate/{uuid}/report/{report_id}
  Voir la request et les numéros de rapport dans la documentation technique
• Récupérer la synthèse et les scores au format json
  Endpoint : GET/candidate/{uuid}/synthesis
  Endpoint : GET/candidate/{uuid}/scores
• Récupérer la partie adequation avec les taux d'adequation et les PDFs
  Endpoint : GET/candidate/{uuid}/adequacies/{pm_uuid}
  Réponse :

{
  "adequacies": {
    "adequacy_shape": 27.27,
    "adequacy_drive": 37.5,
    "adequacy_brain": 30,
    "global_adequacy": 31.59,
    "success_adequacy": 28.64,
    "fulfillment_adequacy": 37.5
  },
  "reports": [
    {
      "id": 17,
      "name": "Summary",
      "web_link": "https://report-simu.assessfirst.com/report/adequacy/ab4699c9169d469c81082accfbe91584/pm/8c9c22a012284569bf4917668e62fb90/company/9da3dcdd775440c7aab3a2219a8961e4?from=api"
    },
    {
      "id": 18,
      "name": "In-depth analysis",
      "web_link": "https://report-simu.assessfirst.com/report/adequacy/ab4699c9169d469c81082accfbe91584/pm/8c9c22a012284569bf4917668e62fb90/company/9da3dcdd775440c7aab3a2219a8961e4?short=1?from=api"
    }
  ]
}

 

 

iFrame - Intégration d'AssessFirst en marque blanche sur une plateforme partenaire :

 

Graphique avec les liens vers notre documentation API

Voici un exemple d'intégration de nos tests en iframe :