If you are a server-to-server REST API user, you will need to perform a one-time update to your URL.
We will still support legacy APIs for some time, but we highly recommend updating the URL to ensure a smooth transition to TOEFL Access. This document outlines the steps to update your REST API.
There are two steps to updating your REST API:
1. Generate the API Key in TOEFL Access.
2. Update your URL.
Step 1: Generate API Key in TOEFL Access
To generate an API Key in TOEFL Access, follow these instructions:
1. Sign into TOEFL Access and select Integrations in the sidebar menu to go the Integrations Hub.
2. Select View Integration on the integration card that applies to you.
3. Select the generate API Key icon under Actions.
4. Select Generate to confirm you want to generate an API Key.
5. Copy the API Key that appears.
Important! Keep the API Key handy.
Pro Tip: You can use the clipboard under Actions to copy the API key later.
6. Select Okay to close the window.
Troubleshooting: If the connection from the TOEFL source formats breaks, the API Key likely expired. To resolve this, follow the steps above to generate a new key.
Step 2: Generate API Key in TOEFL Access
Ask mentioned, as a server-to-server REST API user, you will need to perform a one-time update to your URL.
To do this, replace the entire URL:
from
to
IMPORTANT! Copy the new URL exactly as shown above. Do NOT add or remove any spaces, characters, or line breaks.
Implementation Examples
Example REST API Calls
JSON Response Format
GET https://toeflaccess-api.ets.org/scores?startdate=2025-04-21T16:45:03&enddate=2025-04-22T16:52:13&type=TOEFL&reportby=scorelinkbyreportdate&format=json
Headers:
authcode: YOUR_AUTH_CODE_HERE
Fixed-Length String Response Format
GET https://toeflaccess-api.ets.org/scores?startdate=2025-04-21T16:45:03&enddate=2025-04-22T16:52:13&type=TOEFL&reportby=scorelinkbyreportdate
Headers:
authcode: YOUR_AUTH_CODE_HERE
Sample Code Updates
Before (SOAP - C#)
// Old SOAP client code
var client = new TOEFLEdmSoapClient();
var request = new GetScoresRequest
{
StartDate = DateTime.Parse("2025-04-21T16:45:03"),
EndDate = DateTime.Parse("2025-04-22T16:52:13"),
Type = "TOEFL",
ReportBy = "scorelinkbyreportdate"
};
var response = client.GetScores(request);
After (REST - Multiple Languages)
C#
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Add("authcode", "YOUR_AUTH_CODE_HERE");
// For JSON response
var jsonUrl = "https://toeflaccess-api.ets.org/scores" +
"?startdate=2025-04-21T16:45:03" +
"&enddate=2025-04-22T16:52:13" +
"&type=TOEFL" +
"&reportby=scorelinkbyreportdate" +
"&format=json";
var response = await client.GetAsync(jsonUrl);
var jsonContent = await response.Content.ReadAsStringAsync();
var data = JsonConvert.DeserializeObject<YourResponseType>(jsonContent);
// For fixed-length string response
var fixedUrl = "https://toeflaccess-api.ets.org/scores" +
"?startdate=2025-04-21T16:45:03" +
"&enddate=2025-04-22T16:52:13" +
"&type=TOEFL" +
"&reportby=scorelinkbyreportdate";
var fixedResponse = await client.GetAsync(fixedUrl);
var fixedContent = await fixedResponse.Content.ReadAsStringAsync();
// Parse fixed-length string according to score link layout
}
Java
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.time.Duration;
import com.fasterxml.jackson.databind.ObjectMapper;
// Create HTTP client
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(30))
.build();
// For JSON response
String jsonUrl = "https://toeflaccess-api.ets.org/scores" +
"?startdate=2025-04-21T16:45:03" +
"&enddate=2025-04-22T16:52:13" +
"&type=TOEFL" +
"&reportby=scorelinkbyreportdate" +
"&format=json";
HttpRequest jsonRequest = HttpRequest.newBuilder()
.uri(URI.create(jsonUrl))
.header("authcode", "YOUR_AUTH_CODE_HERE")
.GET()
.build();
HttpResponse<String> jsonResponse = client.send(jsonRequest,
HttpResponse.BodyHandlers.ofString());
ObjectMapper mapper = new ObjectMapper();
YourResponseType data = mapper.readValue(jsonResponse.body(), YourResponseType.class);
// For fixed-length string response
String fixedUrl = "https://toeflaccess-api.ets.org/scores" +
"?startdate=2025-04-21T16:45:03" +
"&enddate=2025-04-22T16:52:13" +
"&type=TOEFL" +
"&reportby=scorelinkbyreportdate";
HttpRequest fixedRequest = HttpRequest.newBuilder()
.uri(URI.create(fixedUrl))
.header("authcode", "YOUR_AUTH_CODE_HERE")
.GET()
.build();
HttpResponse<String> fixedResponse = client.send(fixedRequest,
HttpResponse.BodyHandlers.ofString());
String fixedData = fixedResponse.body();
// Parse fixed-length string according to score link layout
Python
import requests
import json
from datetime import datetime
# Set up parameters
base_url = "https://toeflaccess-api.ets.org/scores"
headers = {
"authcode": "YOUR_AUTH_CODE_HERE"
}
# For JSON response
json_params = {
"startdate": "2025-04-21T16:45:03",
"enddate": "2025-04-22T16:52:13",
"type": "TOEFL",
"reportby": "scorelinkbyreportdate",
"format": "json"
}
json_response = requests.get(base_url, headers=headers, params=json_params)
if json_response.status_code == 200:
data = json_response.json()
print("JSON Success:", data)
# For fixed-length string response
fixed_params = {
"startdate": "2025-04-21T16:45:03",
"enddate": "2025-04-22T16:52:13",
"type": "TOEFL",
"reportby": "scorelinkbyreportdate"
}
fixed_response = requests.get(base_url, headers=headers, params=fixed_params)
if fixed_response.status_code == 200:
fixed_data = fixed_response.text
print("Fixed-length Success:", fixed_data)
# Parse fixed-length string according to score link layout
Questions? Please contact us at help.toeflaccess@ets.org.