We're updating from our legacy SOAP web service to a new REST API to provide better performance, simplified integration, and modern standards compliance. This guide provides step-by-step instructions for updating your client applications.

Service Changes Summary

Old SOAP Service

WSDL URL: https://datamanager.ets.org/TOEFLWebService/TOEFLEdm.wsdl
Protocol: SOAP 1.1/1.2
Format: XML request/response
Authentication: [Previous authentication method]

New REST API

API 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

Before you begin, you will need to generate a new API Key in TOEFL Access. Read the Generate New API Key article to learn how.

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

ScoreLink Layout

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

Required Changes

1. Update Endpoint URL

Replace your SOAP endpoint with the new REST URL:

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

2. Change Request Method

Old: SOAP POST with XML envelope
New: 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
Old: XML response within SOAP envelope

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

Update Checklist

☐ Update service endpoint URL

☐ Change from SOAP POST to HTTP GET

☐ Implement query string parameters

☐ Add authcode header authentication

☐ Update response parsing from XML to JSON or fixed-length string

☐ Test with sample data

☐ Update error handling for HTTP status codes

☐ Verify date format compatibility (ISO 8601)

☐ Update any service references or generated client code

☐ Test authentication with provided authcode

Testing Your Implementation

Verify Parameters: Ensure all required parameters are included in the query string
Check Authentication: Confirm the authcode header is properly set
Validate Dates: Ensure date parameters follow ISO 8601 format
Test Error Handling: Verify your application handles HTTP error responses appropriately
Compare Results: Cross-reference initial results with previous SOAP responses to ensure data consistency

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

If you have any questions, please email us: help.toeflaccess@ets.org.

Add New Slate Integration

Update Guide for Existing Slate Integration Users

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

Add New Custom Integration

Update Guide: SOAP to REST Service