JSON Layout | TOEFL Score User Help

This article is applicable only to Custom Integrations as of now and not Slate Integrations.

The JSON layout for Server-to-Server data files is shown below. Use it to identify the fields and structure in the JSON response. If the Server-to-Server file needs to be mapped in your CRM or another application, this layout can be used to understand how the data is structured.

Preparing for Updates

ETS is introducing significant updates to the TOEFL iBT® test, including a new 1–6 score scale and adaptive testing features. These updates impact how score data is structured and delivered including through our technical integrations.

You can proactively prepare for the updates to minimize disruptions to your workflows by:

Proactively review updated file specifications
Testing data parsing with new fields
Planning integration updates for January 2026
Familiarizing yourself with 1–6 scale interpretation
Reviewing CEFR alignment guidelines
Considering score requirement adjustments for your school

To help you prepare, see the article TOEFL iBT® Score Scale Update: What You Need to Know.

JSON File Format

The JSON file format used in REST API's Server-to-Server integrations includes:

New 1–6 scale section and total scores
CEFR level mappings
Comparable 0–120 scores during transition period
Enhanced metadata fields in a structured format

The JSON schema includes iBT26* and MyBest iBT26* scores. After January 21, 2026, these fields will contain TOEFL iBT Data. We encourage you to make these updates now to help ensure a smooth rollout of the new score scale.

*iBT26 refers to the enhancements being made to the test January 21, 2026.

Test Environment Access

For testing and integration purposes, use the following test environment credentials:

Environment: TST (Test)

URL:

https://toeflaccess-tst-api.ets.org/scores/sample-data?enddate=2023-07-26T23:59:59&reportby=scorelinkbyreportdate&startdate=2023-07-25T00:00:00&type=TOEFL&format=JSON

Sample Authorization Code:

ZXh0c3lzaWJ0MjZ0c3Q6cGFzczAxMDIwMw==

JSON Schema Structure

The JSON response contains a data array with score records. Each record includes the following structure:

Root Level Fields

Field	Type	Description
institutionCode	String	Institution code (4 characters)
departmentCode	String	Department code (2 characters)
departmentDescription	String	Description of the department
appointmentNo	String	Registration or Appointment Number (16 characters)
reportDate	String	Report date (YYYYMMDD format)
scoreStatus	String	Score status (C=Cancelled; R=Reported)

candidateInfo Object

Field	Type	Description
lastName	String	Candidate's last (family) name
firstName	String	Candidate's first (given) name
middleName	String	Candidate's middle name
address	Object	Address information (see below)
nativeCountryCode	String	Native country code (ISO format)
nativeCountryName	String	Native country name
nativeLanguageCode	String	Native language code (ISO format)
nativeLanguageName	String	Native language name
dob	String	Date of birth (YYYYMMDD format)
gender	String	Gender (1=Male, 2=Female, 3=Non-binary, 4=Prefer to self-describe, 5=Prefer not to answer, 0=No Response)
email	String	Email address
securityId	Object	Security identification information (see below)

address Object

Field	Type	Description
address1	String	Address line 1
address2	String	Address line 2
address3	String	Address line 3
address4	String	Address line 4
city	String	City
state	String	State/Province
countryCode	String	Country code (ISO format)
countryName	String	Country name
zip	String	Zip/Postal code

securityId Object

Field	Type	Description
type	String	ID type (e.g., PASSPORT, National ID)
number	String	ID number (last 4 digits displayed)
issuingCountry	String	Issuing country code

testInfo Object

Field	Type	Description
testDate	String	Test date (YYYYMMDD format)
testType	String	Test type (I=iBT; E=Essentials; C=Paper Edition; K=iBT26)
listeningAccommodationInd	String	Listening accommodation indicator (Blank or L=No Listening Score)
speakingAccommodationInd	String	Speaking accommodation indicator (Blank or S=No Speaking Score)
testMode	String	Test mode (e.g., Test Center, Home Edition)
testCenterCode	String	Test center code
testCenterCountryName	String	Test center country name

Score Objects (iBT, iBT26, Essentials)

ibt26 Object (when testType is K)

Field	Type	Description
listeningScore	String	Listening score (1.0 to 6.0, increments of 0.5)
readingScore	String	Reading score (1.0 to 6.0, increments of 0.5)
speakingScore	String	Speaking score (1.0 to 6.0, increments of 0.5)
writingScore	String	Writing score (1.0 to 6.0, increments of 0.5)
totalScore	String	Total score (1.0 to 6.0, increments of 0.5)
totalCEFR	String	CEFR level (A1, A2, B1, B2, C1, C2)
totalScoreIbtEquivalent	String	iBT equivalent score (000 to 120)
mbs	Object	MyBest Scores object (see below)

ibt Object (when testType is I)

Field	Type	Description
listeningScore	String	Listening score (0 - 30)
readingScore	String	Reading score (0 - 30)
speakingScore	String	Speaking score (0 - 30)
writingScore	String	Writing score (0 - 30)
totalScore	String	Total score (0 - 120)
mbs	Object	MyBest Scores object (see below)

essentials Object (When testType is E)

Field	Type	Description
listeningScore	String	Listening score (1 - 12)
readingScore	String	Reading score (1 - 12)
speakingScore	String	Speaking score (1 - 12)
writingScore	String	Writing score (1 - 12)
totalScore	String	Total score (1 - 12)
listeningCEFR	String	Listening CEFR level.
readingCEFR	String	Reading CEFR level.
writingCEFR	String	Writing CEFR level.
speakingCEFR	String	Speaking CEFR level.
totalCEFR	String	Overall CEFR level.
sentenceStructure	String	Sentence structure score.
vacabularyKnowledge	String	Vocabulary knowledge score.
mbs	Object	MyBest Scores object (see below)

mbs (MyBest Scores) Object

Field	Type	Description
listeningScore	String	MyBest listening score (1.0 to 6.0)
listeningTestDate	String	MyBest listening test date (YYYYMMDD)
readingScore	String	MyBest reading score (1.0 to 6.0)
readingTestDate	String	MyBest reading test date (YYYYMMDD)
writingScore	String	MyBest writing score (1.0 to 6.0)
writingTestDate	String	MyBest writing test date (YYYYMMDD)
speakingScore	String	MyBest speaking score (1.0 to 6.0)
speakingTestDate	String	MyBest speaking test date (YYYYMMDD)
totalScore	String	MyBest total score (1.0 to 6.0)
totalScoreIbtEquivalent	String	MyBest iBT equivalent score (000 to 120)
totalCEFR	String	MyBest CEFR level (A1, A2, B1, B2, C1, C2)
asOfDate	String	MyBest as of date (YYYYMMDD)

Sample JSON Response

{
  "data": [
    {
      "institutionCode": "1230",
      "departmentCode": "99",
      "departmentDescription": "For any other department not listed",
      "appointmentNo": "2025071621000001",
      "reportDate": "20250716",
      "candidateInfo": {
        "lastName": "Konatham",
        "firstName": "Srinivasa",
        "middleName": "",
        "address": {
          "address1": "666 Rosedale rd",
          "address2": "Attn: Admissions Dept",
          "address3": "",
          "address4": "",
          "city": "Los Angeles",
          "state": "CA",
          "countryCode": "USA",
          "countryName": "UNITED STATES",
          "zip": "06309"
        },
        "nativeCountryCode": "MEX",
        "nativeCountryName": "MEXICO",
        "nativeLanguageCode": "SPA",
        "nativeLanguageName": "SPANISH",
        "dob": "20070127",
        "gender": "1",
        "email": "tracy.choi@sampleinbox.co",
        "securityId": {
          "type": "PASSPORT",
          "number": "0380",
          "issuingCountry": "MEX"
        }
      },
      "testInfo": {
        "testDate": "20250627",
        "testType": "K",
        "listeningAccommodationInd": "",
        "speakingAccommodationInd": "",
        "testMode": "Test Center",
        "testCenterCode": "STNRPMEX",
        "testCenterCountryName": "MEXICO"
      },
      "ibt26": {
        "listeningScore": "5.0",
        "readingScore": "5.0",
        "speakingScore": "5.0",
        "writingScore": "4.5",
        "totalScore": "5.0",
        "totalCEFR": "C1",
        "totalScoreIbtEquivalent": "100",
        "mbs": {
          "listeningScore": "5.0",
          "listeningTestDate": "20231114",
          "readingScore": "5.0",
          "readingTestDate": "20231114",
          "writingScore": "4.5",
          "writingTestDate": "20231114",
          "speakingScore": "5.0",
          "speakingTestDate": "20231114",
          "totalScore": "5.0",
          "totalScoreIbtEquivalent": "100",
          "totalCEFR": "C1",
          "asOfDate": "20250711"
        }
      },
      "scoreStatus": "R"
    }
  ]
}

TOEFL iBT® Score Scale Update: What You Need to Know

TOEFL PGP Layout

ScoreLink Layout

TOEFL iBT® Updates for PGP Layout

TOEFL iBT® Updates for ScoreLink Layout