Examples of integrations that can be done with our API v2

Here are two examples of integrations that can be made using our API or iFrames.

All actions available through our APIs are detailed in this technical documentation.

 

Using the API to use AssessFirst as an evaluation tool in an ATS

iFrame - White-label integration of AssessFirst on a partner platform

Using the API to use AssessFirst as an evaluation tool in an ATS

Graph with links to our API documentation

3 steps:

1/ Retrieval of predictive models

It is necessary to retrieve the predictive model specific to each client so that, as soon as a candidate completes their questionnaires, the reports and scores are calculated with the correct model.

We recommend displaying this list in a “dropdown list”, either at the level of the job offers or when sending the invitation.

 

Endpoint -> GET/predictive-models

Response:

{
  "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"
    }
}

Display all the name fields in the dropdown list and save the ID once the predictive model is selected on the offer or when sending the invitation.

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"
}'

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

3/ Retrieving the results

Depending on the status obtained when sending the invitation, you will be able to retrieve the results.

Initially, when activating the integration, it is important to subscribe to the following webhooks so that you can receive the different notifications:

• assessment.finished: As soon as a candidate finishes a questionnaire

• user.linked: When a candidate accepts the recruiter’s invitation

• user.completed: When a candidate has completed all the questionnaires (Optional, depending on your use case)

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"
    ]
}'

Depending on the status you retrieve from the POST send-invitation, you will be able to retrieve the results at different times:

1/ The candidate does not have an AssessFirst account → Invitation_sent

In this case, you will be able to retrieve a candidate’s results as soon as you receive the assessment.finished webhook.

You will also receive a user.completed once the candidate has completed all the required questionnaires.

2/ The candidate already has an account, but it is not shared with the client → ask_share

You must wait to receive a user.linked webhook, indicating that the candidate has accepted to share their results.

At that moment, you can check if the candidate has completed their questionnaires.

• • • If yes, you can retrieve the results.

    • If not, you can wait for an assessment.finished.

3/ The candidate is already sharing their results with the client → already_completed ou added_to_network

You will not receive a webhook in this case, knowing that the candidate has already completed all questionnaires and is already sharing their results with the client.

You can therefore directly retrieve the results — or do nothing, depending on your need.

Endpoint to retrieve the results:

There are several ways to retrieve a candidate’s results:

• Links that you display in your application and that redirect directly to the PDFs on the AssessFirst platform.

Endpoint: GET/candidate/{uuid}/reports

Response:

[
  {
    "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"
  }, ...

• Retrieve PDFs directly on your servers

Endpoint: GET/candidate/{uuid}/report/{report_id}

See the request and report numbers in the technical documentation.

• Retrieve the synthesis and scores in JSON format

Endpoint: GET/candidate/{uuid}/synthesis

Endpoint: GET/candidate/{uuid}/scores

• Retrieve the matching section with fit scores and PDFs

Endpoint: GET/candidate/{uuid}/adequacies/{pm_uuid}

Response:

{
  "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 - White-label integration of AssessFirst on a partner platform

 

Graph with links to our API documentation

Here is an example of our tests integrated in iframe: 

 

The iFrame links are identical for the three questionnaires Swipe (Shape) / Drive / Brain, as they redirect to a stepper that allows starting each questionnaire.

 

However, it is possible to provide direct access to the desired tests by adding the questionnaire name as a parameter ?id={assessment name}.

Example: https://app.assessfirst.com/betty/auth-iframe/vdjy36Tj...3ux2XK?id=swipe

 

{Assessment name} -> swipe or drive or adaptive_brain