Skip to main content

API

The Linguapop API allows you to integrate Linguapop with your existing management software (CRM, LMS, etc.) or your website.

With it, you can create and send placement test invitations, and fetch the list of available languages

Fetch available languages

Send a GET request to:

https://app.linguapop.eu/api/actions/getLanguages

The endpoint returns a list of available languages:

Response
[
{
"name": "English",
"code": "eng"
},
{
"name": "Italian",
"code": "ita"
},
{
"name": "Spanish",
"code": "spa"
},
{
"name": "German",
"code": "ger"
},
{
"name": "French",
"code": "fra"
}
]

You should use the code property of the language when sending invitations via the API.

These codes aren't planned to change, however additional languages are planned. With this in mind, hard-coding for languages you offer is okay, as long as you keep up-to-date with new languages in case you want to offer placement tests in these languages.

Send/create an invitation to a placement test

You can create an invitation and send it to your candidate by sending a POST request to:

https://app.linguapop.eu/api/actions/sendInvitation

The request should have its Content-Type header set to application/json.

Within the request body, you should include the following:

Request body
{
"apiKey": "INTEGRATION_API_KEY",
"externalIdentifier": "EXTERNAL_IDENTIFIER",
"name": "CANDIDATE_NAME",
"email": "CANDIDATE_EMAIL",
"languageCode": "LANGUAGE_CODE",
"sendEmail": true,
"generateKioskCode": true,
"testReading": false,
"testListening": false,
"callbackUrl": "https://YOUR_CALLBACK_URL",
"returnUrl": "https://YOUR_RETURN_URL"
}

Descriptions of the request object's fields:

  • apiKey - required, string
  • externalIdentifier - optional, string, max length 500
    • This is an ID you can generate from your CRM to uniquiely identify your candidate.
  • email - required, string
    • The candidate's email address. This can also be used to identify your candidate.
  • languageCode - required, string
  • sendEmail - required, boolean
    • This determines whether Linguapop sends an invitation email to your candidate.
  • generateKioskCode - optional, boolean
    • This determines whether Linguapop will generate and return a kiosk code for your candidate.
    • If set to true, ensure that a Kiosk has been enabled and set up within Customization.
  • testReading - optional, boolean
    • This determines whether the test will include a reading section.
    • If not provided, the default option set in your Customization will be used.
  • testListening - optional, boolean
    • This determines whether the test will include a listening section.
    • If not provided, the default option set in your Customization will be used.
  • callbackUrl - optional, string, max length 1000
    • This is the callback URL to which a POST request will be sent with the results of the placement test once the test is completed.
  • returnUrl - optional, string, max length 1000
    • The URL the candidate will be redirected to after completing the placement test. The redirect is triggered by a button on the results screen.
    • If not provided, the button will not be visible.

The Linguapop API will respond with the following JSON object:

Response
{
"invitationId": INVITATION_ID,
"externalIdentifier": "EXTERNAL_IDENTIFIER",
"url": "https://app.linguapop.eu/accept-placement-test-invitation/INVITATION_TOKEN",
"emailSent": false,
"kioskCode": "000000"
}

Descriptions of the response object's fields:

  • invitationId - number (integer)
    • The unique ID of the created invitation.
    • You can save this property to track this particular placement test.
  • url - string
    • A direct URL to the placement test invitation.
    • This is the same URL used witihn Linguapop's placement test invitation emails.
    • You can provide this URL to your candidate in an automated workflow, such as a "Take a placement test" page on your website, or if you are using your own email sending service.
  • emailSent - boolean
    • Determines whether an email has been successfully sent
    • Is always false if you set sendEmail to false
  • kioskCode - string or null
    • The Kiosk Code that your candidate can use to access the placement test through your configured Kiosk
    • Is null if you set generateKioskCode to false
tip

You don't have to send emails!

One of the best parts of Linguapop's API integration is that you get a direct link to the placement test for each invitation you send.

Instead of sending emails, you can simply provide the candidate with this link while they are on your website, or you can even further customize your emails beyond what Linguapop provides

With Linguapop being charged only for completed tests, you will not incur additional charges by providing website visitors with a self-service placement test.

This makes Linguapop an ideal tool for acquiring high-quality leads.

The Callback URL

Upon the completion of a placement test, Linguapop can optionally send the results of the placement test back to your software.

All you need to do to enable this is provide the callbackUrl property as part of your request body for the Send/create an invitation to a placement test request.

If a callbackUrl has been provided, Linguapop will make an HTTP POST request with a Content-Type header set to application/json, and the following body structure:

Callback request body
{
"externalIdentifier": "EXTERNAL_IDENTIFIER",
"invitationId": INVITATION_ID,
"placementTestId": PLACEMENT_TEST_ID,
"name": "CANDIDATE_NAME",
"email": "CANDIDATE_EMAIL",
"phone": "CANDIDATE_PHONE",
"finalLevel": "B2 High",
"finalLevelCode": "B2H",
"reading": null,
"readingMax": null,
"listening": null,
"listeningMax": null,
"rating": 1652.7278254974933,
"completedOn": "2023-08-14T13:58:06.391139Z",
"publicResultsUrl": "PUBLIC_RESULTS_URL",
"adminResultsUrl": "ADMIN_RESULTS_URL"
}

Descriptions of the callback request object's fields:

  • externalIdentifier - string, can be null, max length 500
    • This is an ID you can generate from your CRM to uniquiely identify your candidate.
  • invitationId - number (integer)
    • The unique ID of the invitation. Same ID as the one you receive from Linguapop.
  • placementTestId - number (integer)
    • The unique ID of the placement test. You can use this to identify the placement test within the Linguapop app.
  • name - string
    • The name of the tested candidate.
  • email - string
    • The email of the tested candidate.
  • phone - string
    • The phone number of the tested candidate.
  • finalLevel - string
    • The final level Linguapop determined for the candidate, as a human-readable string.
  • finalLevelCode - string
    • The final level Linguapop determined for the candidate, as a unique machine-readable code.
  • reading - number (integer), can be null
    • The number of questions answered correctly for the reading task, if any.
    • Will be null if no reading task was performed.
  • readingMax - number (integer), can be null
    • The total number of question for the reading task.
    • Will be null if no reading task was performed.
  • listening - number (integer), can be null
    • The number of questions answered correctly for the reading task, if any.
    • Will be null if no reading task was performed.
  • listeningMax - number (integer), can be null
    • The total number of question for the listening task.
    • Will be null if no listening task was performed.
  • rating - number (floating point)
    • The system-determined rating for the candidate.
    • This rating corresponds to the level from the finalLevel and finalLevelCode fields.
    • For details, see Levels used in Linguaopop
  • completedOn - string, ISO 8601-formatted UTC timestamp without offset
    • The date and time when the placement test has been completed.
    • This is an ISO 8601-formatted UTC timestamp, without an offset component.
  • publicResultsUrl - string
    • This is a direct link to the results page that your candidate can access.
  • adminResultsUrl - string
    • Use this URL if you want to display detailed results from within an iframe inside your application.
    • This link displays the candidate's name, email address and phone number, and should only be used to display detailed results to users who would normally be able to access the data through Linguapop.

Levels used in Linguapop

Linguapop is aligned with the CEFR, displaying final results to candidates as one of the 6 main levels: A1, A2, B1, B2, C1, C2.

However, internally Linguapop tracks these levels in a more fine-grained manner, splitting the 6 main CEFR levels into 16 sub-levels:

Level nameUsually calledLevel codeLowest ratingHighest rating
A1 LowA1.1A1L/849
A1 HighA1.2A1H850949
A2 LowA2.1A2L9501049
A2 HighA2.2A2H10501149
B1 LowB1.1B1L11501249
B1 Mid-LowB1.2B1ML12501349
B1 Mid-HighB1.3B1MH13501449
B1 HighB1.4B1H14501549
B2 LowB2.1B2L15501649
B2 Mid-LowB2.2B2ML16501749
B2 Mid-HighB2.3B2MH17501849
B2 HighB2.4B2H18501949
C1 LowC1.1C1L19502049
C1 HighC1.2C1H20502149
C2 LowC2.1C2L21502249
C2 HighC2.2C2H2250/

You can use this table together with the rating result to create graphical representations of the candidate's rating within your own software.