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.

Throughout this article, the API Key is referred to as an authentication code or authcode.

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.

6. Select Okay to close the window.

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

https://datamanager-api.ets.org/api/v1/scores/testtakers

to

https://toeflaccess-api.ets.org/scores

Parameters

The REST service uses query string parameters:

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

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);

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

​