Skip to main content

Add New Custom Integration

Michelle Stabler-Havener avatar
Written by Michelle Stabler-Havener
Updated this week

We're glad you're part of TOEFL Access community! To add a new a custom integration, follow the instructions below.

REST Service Summary

  • Base URL: https://toeflaccess-api.ets.org/scores

  • Protocol: REST/HTTP

  • Format: JSON or fixed-length string (based on format parameter)

  • Authentication: Header-based with authcode

Generate API Key in TOEFL Access

TOEFL scores can be imported using an API call configured as a Source Format. To automatically fetch the data via API, you will need to add a new custom integration and generate an API Key in TOEFL Access.

To add a new custom integration and generate an API Key, follow these instructions:

1. Sign in to TOEFL Access and select Integrations in the sidebar menu to go the Integrations Hub.

2. Select + Add Integration.

3. On the Custom Integration page, select + Add New Account and enter the requested information.

4. Select Verify Details and select Submit.

5. Under Finalize Details, copy the API Key by selecting the clipboard icon.

  • Important! Keep the API Key handy for the next step in the integration process.

  • Pro Tip: You can use the clipboard under Actions to copy the API key later.

6. Select Okay to see your new account on the Custom Integration page.

Troubleshooting: If the connection from the TOEFL source formats breaks, the API Key likely expired. To resolve this, generate a new key by following the instructions in the Generate New API Key article.

ScoreLink Layout

Here is the ScoreLink layout article. Keep it handy. You will need it everywhere "score link layout" is referenced.

API Details

1. Update Endpoint URL

Use the following REST URL:

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

2. Request Method

  • HTTP GET with query parameters

3. Update Parameters

The REST service uses query string parameters instead of SOAP body parameters:

Parameter

Type

Required

Description

Example

startdate

string

Yes

Start date in ISO 8601 format

2025-04-21T16:45:03

enddate

string

Yes

End date in ISO 8601 format

2025-04-22T16:52:13

type

string

Yes

Report type identifier

TOEFL

reportby

string

Yes

Report grouping method

scorelinkbyreportdate

format

string

No

Response format (json or omit for fixed-length)

json

4. Update Authentication

  • Method: HTTP Header

  • Header Name: authcode

  • Value: Your assigned authentication code

5. Handle Response Format

The REST service supports two response formats:

  • JSON Format: Include format=json parameter for structured JSON response

  • Fixed-Length String: Omit format parameter for traditional fixed-length string response following the score link layout

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

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

Testing Your Implementation

  1. Verify Parameters: Ensure all required parameters are included in the query string.

  2. Check Authentication: Confirm the authcode header is properly set.

  3. Validate Dates: Ensure date parameters follow ISO 8601 format.

  4. Test Error Handling: Verify your application handles HTTP error responses appropriately.

Important Notes

  • Date Format: Use ISO 8601 format (YYYY-MM-DDTHH:mm:ss) for date parameters.

  • Response Format: Choose between JSON (with format=json) or fixed-length string format.

  • URL Encoding: Ensure proper URL encoding for query parameters.

  • Authentication: Keep your authcode secure and do not expose it in client-side code.

  • Fixed-Length Parsing: For fixed-length responses, refer to the score link layout documentation for proper parsing.

  • Error Handling: HTTP status codes will indicate success/failure instead of SOAP faults.

Questions? Please contact us at help.toeflaccess@ets.org.

Did this answer your question?