Troubleshooting Integration Errors | TOEFL Access Help Center

This article addresses common integration challenges institutions face when connecting their CRM systems to TOEFL Access for automated score retrieval. Learn more on troubleshooting and resolving these issues quickly to ensure reliable score imports for your admissions workflows.

Error Code Reference

400 - Bad Request

Sample Response	Reason	Resolution Steps
`startdate is required`	startdate parameter is missing from query string	Follow resolution steps below
`enddate is required`	enddate parameter is missing from query string	Follow resolution steps below
`type/program is required`	type parameter missing from query string	Follow resolution steps below
`reportby is required`	reportby parameter missing from query string	Follow resolution steps below
`Invalid credentials format`	authcode is not in correct format	Generate a new API key and pass it in headers

400 - Resolution Steps

Date Format Requirements:
- Use ISO 8601 format: YYYY-MM-DDTHH:mm:ss (e.g., 2025-04-21T16:45:03).
- Ensure startdate chronologically comes before enddate.
- All timestamps must be in UTC timezone.
CRM-Specific Considerations:
- Slate users: Verify timestamp format in "Last Remote Server Fetch (UTC)" field matches ISO 8601.

Complete API Call Example:

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

Required Parameters Checklist:
✅ startdate (ISO 8601 format, UTC)
✅ enddate (ISO 8601 format, UTC, after startdate)
✅ type (e.g., "TOEFL")
✅ reportby (e.g., "scorelinkbyreportdate")
✅ authcode (in headers, not URL parameters)

401 - Unauthorized

Sample Response	Reason	Mitigation Steps
`authcode is required`	authcode/API key missing from headers	Add authcode to request headers
`Authcode validation failed`	authcode is incorrect or expired	Use correct authcode/API key or generate new one
`Authcode validation failed due to an error`	Account inactive or system error	Use correct authcode/API key, generate new one, or contact help desk
`User is not authenticated`	Authentication failed	Use correct authcode/API key or generate new one

401 - Resolution Steps

New Account Setup

If you recently created your server-to-server account, you must wait two business days before the account becomes active for score retrieval. The account status will show as "pending" during this period.

If you're still unable to access scores after two business days, contact the TOEFL Access team at help.toeflaccess@ets.org.

Expired or Invalid API Key

You will need to regenerate a new API key. To do so, follow the steps below:

Navigate to: TOEFL Access → Integrations → View Integration → Actions
Click the generate icon under Actions to create a new API key.
Update your CRM configuration with the new authcode.
Test the connection with a small date range first.

Authentication Header Issues

Correct header name: authcode (not Authorization or Bearer)
Format verification: Ensure no extra space, line breaks, or hidden characters
Example format:
```
Headers:
authcode: YOUR_AUTH_CODE_HERE
```

API Endpoint Verification

Current endpoint: https://toeflaccess-api.ets.org/scores
Legacy endpoint migration: If you're still using old endpoints, update to the current one:
- ❌ Old SOAP: https://datamanager.ets.org/TOEFLWebService/TOEFLEdm.wsdl
- ❌ Old REST: https://datamanager-api.ets.org/api/v1/scores/testtakers
- ✅ Current: https://toeflaccess-api.ets.org/scores

403 - Forbidden

Sample Response	Reason	Mitigation Steps
`Forbidden`	Technical error or insufficient permissions	Contact technical support

403 - Resolution Steps

This error typically indicates a server-side permission issue or technical problem. If receive this error, contact technical support and provide them with:

Your institution name and account details
Exact timestamp of the error
Complete error message received
API request details (without exposing your API key)

500 - Internal Server Error

Sample Response	Reason	Mitigation Steps
`Internal Server Error`	Server-side technical error	Contact technical support

500 - Resolution Steps

This indicates a problem with the TOEFL Access API servers. Steps to take:

Immediate actions:
- Wait 5-10 minutes and retry the request.
- Try with a smaller date range to reduce server load.
- Check if the issue persists across different time periods.
If a problem persists:
- Contact technical support.
- Provide the exact timestamp when the error occurred.
- Include details about your request (date range, parameters used).
- Mention if this is a recurring issue or first occurrence.

Best Practices for Reliable Integration

Request Optimization

Limit date ranges to 30 days or less per request.
Implement exponential backoff for retry logic.
Cache successful responses to avoid duplicate requests.

Monitoring and Alerting

Set up monitoring for authentication failures.
Alert on 500 consecutive errors.
Track API response times for performance issues.

Maintenance Schedule

Rotate API keys quarterly as a security best practice.
Test integration after any CRM updates.
Document any custom configurations for future reference.

Contact Us

For technical support and assistance, email us at help.toeflaccess@ets.org, and ask to connect with a member of the team. Please include the following in your message to help us assist you better:

Institution Name and DI Code
Specific error message received
Timeline when the issues started
Steps taken to resolve the issue

Update Guide: SOAP to REST Service

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