Cambridge English Results Service Integration

Cambridge English Qualifications are based on research into effective teaching and learning.

Each exam focuses on a level of the Common European Framework of Reference (CEFR). Cambridge English exam results can be imported into Slate via the Cambridge English Results Service API.

Cambridge English scores can be imported into Slate using an API call that is configured as a source format. This article outlines the necessary steps to configure this process within Slate.

💬 Questions? Contact Cambridge English via their Cambridge English Request Form.

Step 1: Obtaining your Client ID and Client Secret

To automatically fetch the data via the API, you need the Client ID and Client Secret.

1. Inform Cambridge English that your institution would like to register for the API.

2. Go to the ACM Developer Portal.

3. Select Log in.

4. Select Create new account.

5. Fill out the Create a My Cambridge account form. Use the same email address you used for the APIGEE Developer portal.

6. Select Continue. A verification email is sent to your account.

7. Verify your email using the link provided, then sign in.

8. Select My Applications in the top menu bar.

9. On a registered Cambridge English (CE) application, select View on the right side.

10. Select Copy to copy your credentials.

11. Select Reset Credentials if new credentials are needed.

📝 Note

Cambridge English renews your Client ID and Secret every 12 months, so the authorization header in the source format must be updated annually. For additional information and support, please reference the CE Candidate Result Verification API page of the Cambridge API Development portal.

Step 2: Adding Cambridge English Test Types to your database

There are three standard Cambridge English test types that store the test results based on which exam was taken:

• Cambridge English First (B2 First)

• Cambridge English Advanced (C1 Advanced)

• Cambridge English Proficiency (C2 Proficiency)

To add these to your database:

1. Go to Database → Suitcase.

2. Select Import.

3. Paste the following Suitcase ID of the shared Suitcase item:

   eaf77331-e776-46f7-8941-56cb3f85c10d:slate-examples

4. Select Retrieve.

The new test types are available in Database → Tests.

Step 3: Adding the source format to your database

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

Add the source format

To add the Cambridge English Results Service source format to your database:

1. Go to Database → Source Format Library.

2. Add the Cambridge English Results Service (JSON) source format.

Perform Base64 encoding on 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.

1. Join your Client ID and Client Secret values with a colon: CLIENT_ID:CLIENT_SECRET.

2. Open your operating system’s terminal.

3. Depending on your operating system, use one of the following examples to encode the combined value, replacing CLIENT_ID:CLIENT_SECRET in these examples with your combined value:

   • Windows (PowerShell):

     [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("CLIENT_ID:CLIENT_SECRET"))

   • macOS or Linux:

     printf '%s' 'CLIENT_ID:CLIENT_SECRET' | base64

4. Keep the return value in a secure location—you’ll need to paste it in the next section.

Configure HTTP headers

1. On the source format overview page, select Edit.

2. Select the Import Automation tab.

3. Do not edit the Import Remote Server.

4. In the HTTP Headers field, paste the following tag:

   <t name="Authorization">Basic YOUR_BASE64_ENCODED_VALUE</t>

5. In the pasted tag, replace YOUR_BASE64_ENCODED_VALUE with the return value you generated earlier. Note that, in the following screenshot, while the base-64 encoded value wraps to the next line, there is in fact a single space between the word Basic and this value—make sure to include this space.
   

6. Select Override to override the Last Remote Server Fetch setting to be the approximate date of the last Cambridge English scores that were imported into Slate. This date cannot be more than one year in the past. Overriding this value will limit the fetch to just those since the last import.
   

7. Enter the case-sensitive confirmation message.

8. In the Last Remote Server Fetch field, enter the approximate timestamp that the source format should send to Cambridge English to restrict the data that is retrieved during the first data fetch.

   • The timestamp should be in the UTC timezone in the format: yyyy-MM-ddTHH:mm:ss (for example, 2022-08-29T00:00:00)

   • Only one year of data can be fetched using this method. For results that occurred prior to one year ago, data must be downloaded manually.
     

9. Select Save.

Step 4: 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. Some institutions may wish to accept only certain exam types. If you choose to prevent the particular exam types from importing into Slate, you may map the ExamType source field to  a second destination: Custom: Skip Import, within the System menu.

This source field is also used to map the Exam Subtype. That destination mapping must remain.

On the Value Mappings page, map any exam types that your institution will not accept to Skip Import to prevent these tests and associated records from importing. If your institution has not yet received data with this value, you may use the Append Values link to add this value as an option to map. The full list of all exam types that Cambridge English reports, regardless of their use in higher education, is in the Exam Types section below.

Set the Remap Active flag to Active on the Source Format once you are finished mapping the Source Format. This will run the import using the Remap settings configured above for all files uploaded on or after the Remap As Of Date value.

Exam types

Cambridge English has a broad spectrum of exam types, ranging from novice English speakers to those who are highly proficient. Many of these exam types are for testing proficiency levels at a more basic level than what is necessary for higher education. 

While it’s likely that you’ll receive only results for exam types meant for testing English skills at a level required for a higher education institution with English language instruction, the full list of exam types that the API supports is:

• A2 Key for Schools

• B1 Business Preliminary

• B1 Preliminary

• B1 Preliminary for Schools

• B2 Business Vantage

• B2 First

• B2 First for Schools

• BULATS

• C1 Advanced

• C1 Business Higher

• C2 Proficiency

• Cambridge English: Financial (ICFE)

• Cambridge English: Legal (ILEC)

• CELTA

• Delta

• Delta Module One

• ICELT

• Linguaskill

• Teaching Knowledge Test (TKT)