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.

Using Integration Logs for Troubleshooting

TOEFL Access provides real-time integration monitoring through the Integration Log Management. This helps you proactively identify and diagnose integration connection issues before they impact your admissions workflows.

Getting Started

You can access integration logs by following the steps below:

Navigate to your profile and select Institution Settings
Select the tab Integration Logs Management

You can also click on the Export CSV button to download log data for sharing with your IT team or TOEFL Access Support.

Integration Activity Table

The Integration Activity log provides detailed information about each API request:

Column	Description	How to use it
User ID	The integration account identifier making the request	Useful if you have multiple integrations configured
Parameter	Key parameters from the request (e.g., enddate:2023-...)	Quickly identify which parameter caused an error without viewing full request details
Timestamp	When the request was made	Correlate errors with CRM scheduled job times or manual refresh attempts
Action	Type of request (typically "Data Pull Request")	Distinguishes between different API operations
Status	Success or Error	Filter to show only failed requests for troubleshooting
Response Time	How long the API took to respond	Identify performance degradation trends
Applicants	Number of applicant records returned	Verify expected data volume; 0 may indicate date range issues
Details	Specific error message text	Links directly to the error codes and resolution steps below
Code	HTTP status code (400, 401, 403, 500)	Jump to the relevant error section in this article (see below)

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: