Skip to main content

Update Guide: Existing Server-to Server Users of REST APIs

Michelle Stabler-Havener avatar
Written by Michelle Stabler-Havener
Updated over a week ago

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.

A screenshot of a computer

AI-generated content may be incorrect.

3. Select the generate API Key icon under Actions.

A screenshot of a computer

AI-generated content may be incorrect.

4. Select Generate to confirm you want to generate an API Key.

A screenshot of a computer

AI-generated content may be incorrect.

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.

A screenshot of a computer

AI-generated content may be incorrect.

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

Fixed-Length String Response Format

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

"?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

"?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.


Did this answer your question?