IELTS Results Service Integration

The International English Language Testing System (IELTS) measures the language proficiency of people who want to study or work where English is used as a language of communication. It uses a nine-band scale, from non-user (band score 1) through expert (band score 9). This article outlines the necessary steps to configure automated imports of IELTS results in Slate.

📝 Note
Cambridge University Press and Assessments is piloting a program with some institutions to allow IELTS results to import automatically into Slate via the IELTS Results Service API. This program may not be available to your institution.

Before you begin

If you haven’t done so already, register for the API with the IELTS Results Service API Registration Form.

IELTS scores can be imported into Slate using an API call configured as a source format. To fetch the data automatically via the API, you’ll need the Client ID and Client Secret.

Step 1: Obtaining your Client ID and Client Secret

Go to the Cambridge API Portal at https://cambridge.my.site.com/s/apis.
Select Log in.
Select Create new account.
Fill out the Create a My Cambridge account form. Use the same email address you used for the Cambridge API Portal.
Select Continue. Cambridge sends a verification email to your account.
Verify your email using the link provided, then sign in.
Select My Applications in the top menu bar.
On a registered application, select View on the right side.
Select Copy to access your credentials. Select Reset Credentials if you need new credentials.

💡 Questions about accessing your institution's Client ID and Client Secret?
Contact Cambridge University Press and Assessments using the IELTS Results Service Support Request Form. Select I'm having difficulty enabling API integration with my institution's management system, e.g., CRM.

Answer Slate Storage Questions

The IELTS Results Service API Registration Form includes questions about the way Slate stores and manages data. Answer these questions with the following:

Q: How will your system store the IELTS result data?
- A: All data in Slate is stored in encrypted databases on encrypted filesystems in secure datacenters, using 256-bit AES encryption.
Q: Have you or your external system provider had any regulatory action for information incidents or breaches?
- A: No.
Q: If your system is provided by a third party will the external system provider be sharing IELTS Results data?
- A: No.

📝 Cambridge University Press and Assessments renews your Client ID and Client Secret every 12 months, so you must update the authorization header in the source format annually.

For more information, see the IELTS Results Verification API page on the Cambridge API Development portal.

Step 2: Encoding your Client ID and Client Secret

To include the Client ID and Client Secret in the HTTP headers used during the import, you must encode them in Base64.

Combine your Client ID and Client Secret values with a colon: CLIENT_ID:CLIENT_SECRET.
Open your operating system’s terminal.
Depending on your operating system, encode the combined value with one of the following commands, replacing CLIENT_ID:CLIENT_SECRET with that value:
- Windows (PowerShell):
```
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("CLIENT_ID:CLIENT_SECRET"))
```
- macOS or Linux:
```
printf '%s' 'CLIENT_ID:CLIENT_SECRET' | base64
```
Copy the returned value to your clipboard. You’ll copy a different value in the next step, so store this one in a secure notes program or text file where you can re-copy it later if needed. Delete the note or file after completing all steps for security reasons.

Step 3: Adding the IELTS test type

Go to Database → Suitcase Import.
Copy and paste the following Suitcase ID into the Suitcase or Briefcase ID field:
```
68ce34a8-ca3e-4747-91e7-080d38effc4a:slate-examples
```
Select Import.

📝 Don’t make any changes to the test type after adding.

Step 4: Adding the source format

This source format automatically fetches score results shared with your institution.

Go to Database → Source Format Library.
Search for IELTS.
Add the IELTS Results Service (JSON) source format.

Step 5: Configuring the import

Go to Database → Source Formats.
Select the IELTS Results Service (JSON) source format.
Select Edit.
In the pop-up that opens, select the Import Automation tab.
If you weren’t contacted to migrate your account to the new API service, you can leave the Import Remote Server setting as is.
If you were contacted, copy the text below and paste it in the Import Remote Server field:
```
https://apis.cambridgeassessment.org.uk/v1/ielts/result-verification?startDateTime={{dtstart|date:'s'}}&endDateTime={{dtend|date:'s'}}&photoFlag=Y
```
📝 Note: The new API endpoint looks similar to the old. The only differences are that api becomes apis and the forward slash preceding the query string parameters is removed. Take care to make sure your updated endpoint is the correct one.
Add the authorization header to the HTTP Headers box using the base-64 encoded value you created in Step 2. The full text of the HTTP Headers will read <t name="Authorization">Basic {{BASE64-ENCODED-VALUE}}</t>.
📝 Note: The base-64 encoded value may wrap to the next line. Leave a single space between the word Basic and the value. Don’t add the braces to the value. Paste the value exactly as it’s generated.

Optional: Overriding the last remote server fetch

By default, the first fetch sends all currently valid IELTS scores released to your institution. Overriding this value limits the fetch to those scores since the specified date and time.

Open the Import Automation tab.
Beside the Last Remote Server Fetch (UTC) timestamp, select Override.
Enter the confirmation message, then press Enter or select OK. This is case-sensitive.
In the Last Remote Server Fetch field, enter the approximate timestamp of your institution’s most recently imported scores. The first fetch retrieves only scores released on or after this timestamp. 📝 Note: The timestamp uses the UTC timezone in the format yyyy-MM-ddTHH:mm:ss (for example, 2025-06-16T00:00:00)
Select Save.

Step 6: Remapping the source format

Configure the Remap settings for the Format Definition. Many items have been pre-mapped. As always, feel free to customize how the data will be imported.
To accept only IELTS scores from the Academic module, map the Module source field to the Custom: Skip Import destination.
On the Value Mappings page, map General Training to Skip Import to prevent these tests from importing. If your institution hasn’t yet received data with this value, use the Append Values link to add it as an option to map.
Set the Remap Active flag to Active on the source format once you finish mapping it. The import runs using the remap settings you configured for all data on or after the Remap As Of Date value.