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
- The API Key of the Integration you're using.
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
- The code of the language you want to test. All language codes can be fetched using the Fetch available languages endpoint.
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 name	Usually called	Level code	Lowest rating	Highest rating
A1 Low	A1.1	A1L	/	849
A1 High	A1.2	A1H	850	949
A2 Low	A2.1	A2L	950	1049
A2 High	A2.2	A2H	1050	1149
B1 Low	B1.1	B1L	1150	1249
B1 Mid-Low	B1.2	B1ML	1250	1349
B1 Mid-High	B1.3	B1MH	1350	1449
B1 High	B1.4	B1H	1450	1549
B2 Low	B2.1	B2L	1550	1649
B2 Mid-Low	B2.2	B2ML	1650	1749
B2 Mid-High	B2.3	B2MH	1750	1849
B2 High	B2.4	B2H	1850	1949
C1 Low	C1.1	C1L	1950	2049
C1 High	C1.2	C1H	2050	2149
C2 Low	C2.1	C2L	2150	2249
C2 High	C2.2	C2H	2250	/

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

Fetch available languages​

Send/create an invitation to a placement test​

The Callback URL​

Levels used in Linguapop​

Fetch available languages

Send/create an invitation to a placement test

The Callback URL

Levels used in Linguapop