Design & usage overview
Assessments take time so the results are not immediately available. This means that rather than submitting text for assessment and receiving results in the response, results are instead either retrieved in a subsequent API call after submission, or notified via a preconfigured webhook. An overview of these two approaches is given below and links are given to details of the API calls discussed. A fuller set of examples and discussion of the structure of submissions can be found in Example Interaction. Availability of further API calls can vary and assessment results can also vary depending on API clients' requirements (for example, whether CEFR levels or IELTS scores are required in text assessment results).
Interaction using webhooks
This is the recommended integration approach as results will be available as soon as they are available without the API client needing to poll for results. In this case, a webhook first needs to be configured by the API client. The interaction is shown in the following diagram. See Configuring webhooks for details.
Once the API client has configured a webhook, the API client can submit text and, assuming submission was successful, the API client's webhook endpoint will be notified of assessment results once assessment of the text has completed. The following diagram shows the interaction. See Submitting text for assessment for details and Handling webhook notifications for details.
Interaction without using webhooks
This approach is only recommended for situations where an API client is unable to provide webhooks to receive notifications. In this case, an API client calls 2 API endpoints:
- Text to be assessed is submitted by the API client. See Submitting text for assessment for details.
- Assuming submission is successful, results can be retrieved using a subsequent API call. If results are not yet ready, this call will need to be repeated. See Retrieving text assessment results for details.
The following diagram show the interaction, assuming the assessment results are ready the first time the API client requests them:
