Submitting text for assessment

A sample text submission call is shown below. See the subsequent sections for details of the request and response formats.

$ curl -H "Authorization: Token token=YOUR_TOKEN" -X PUT -H "Content-Type: application/json" -d '{
  "author_id": "learner1",
  "task_id": "task1",
  "session_id": "unique-session-id-for-this-user",
  "sequence_id": 0,
  "sequence_count": 1,
  "question_text": "Can you tell us about some famous people from your country?",
  "text": "There are many famos people from my country.  Where to begin? Im not shure."
}' https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/test-id-1

# response
# {
#   "type": "success",
#   "code": 200
# }

Request

Method and URI:

PUT /VERSION/account/ACCOUNT_ID/text/ID

Request parameters:

Parameter	Required?	Format	Description
`version`	Yes		The desired API version.
`account_id`	Yes		Your API account ID.
`id`	Yes	max. 40 characters (alphanumeric or hyphen)	an ID which uniquely identifies the piece of text being submitted (for example, a UUID). A new ID must always be used when submitting a new piece of text. For example, if your system allows users to edit and resubmit their texts, a new ID must be used when resubmitting.

Example request body JSON:

{"text": "Some text to be assessed", "author_id": "id-of-the-author", "task_id" : "id-of-the-task", "session_id" : "a-session-id", "sequence_id" : 0, "sequence_count" : 1, "question_text": "The text of the question being asked"}

The JSON attributes are specified in the following table. For further discussion of the various IDs, see Structure of Submissions:

Attribute name	Required?	Format	Description
`text`	Yes	Maximum 10,000 UTF-8 characters, excluding most control characters except horizontal tab, line feed and carriage return	The text to be assessed as a JSON string.
`author_id`	Yes	Maximum 40 characters (alphanumeric or hyphens)	The unique id of the original author.
`task_id`	Yes	Maximum 40 characters (alphanumeric or hyphens)	Should identify the task for which the text was submitted. For example, the client system may present a number of different writing tasks for users to try -- this attribute would indicate which task the text was written for.
`session_id`	Yes if sequence_id is specified	Maximum 40 characters (alphanumeric or hyphens)	Should identify the user session for which the text was submitted. For example, the end user may have several attempts at a particular task. This id should distinguish each of their sessions/attempts.
`sequence_id`	No (but required if sequence_count is specified)	Maximum 4 digits (0 - 9999)	Should identify the ordering of the question within the task, if the task represents a logical grouping of questions. This should be in the form of integers which will be sortable e.g. 0, 1, 2, 3 etc. Unique combinations of `task_id` & `sequence_id` indicate a set of grouped questions. For questions that are not logically grouped, they should be submitted with separate, unique `task_id`s.
`sequence_count`	Yes if sequence_id is specified	Integer 1 - 1000 inclusive	Must specify the number of related answers being submitted as a group (i.e. with the same `task_id` and differing `sequence_id` values).
`question_text`	Yes	Maximum 10,000 UTF-8 characters, excluding most control characters except horizontal tab, line feed and carriage return	The text of the question being asked as a JSON string.
`test`	No	`1`	If present, this must be the value `1` and indicates that the submission is a test (dummy) submission rather than a live submission from a learner.

Response

Successful submission

HTTP status code: 200

Response body JSON:

{"type": "success", "code": 200}

Failed submission

Submission can fail for a number of reasons. The general response format is as follows:

HTTP status code: 400

Example response body JSON:

{"type": "error", "code": 400, "message": "id already exists"}

type is always "error". The message attribute value can vary depending on the specific error as shown by the examples below.

Error	Code	Example message	Additional attributes
Submissions cannot be made using the same ID more than once unless the remaining parameters are identical. This allows for retry in the case of network errors, but disallows reusing the same ID for different submissions.	`400`	"existing answer (id id created at utc_timestamp) has same id but other attributes differ"
Can't make a submission with a different ID with the same uniquely-identifying information as a previous submission	`400`	"existing answer (id id created at utc_timestamp) for same author_id, task_id, session_id, sequence_id"
Associated answers can't supply differing sequence counts	`400`	"existing answer (id id created at utc_timestamp) for same author_id, task_id, session_id has different sequence_count"
Can't submit further associated answers when the number expected have already been submitted	`400`	"sequence_count answers have already been uploaded for same author_id, task_id, session_id"
A previous submission was made with the same ID but different text	`400`	"the text does not match any answers already submitted for this response_id"
Length limits are exceeded for any parameters.	`400`	"text too long"
A required attribute is missing or empty	`400`	"text missing"
A `sequence_id` value has been specified, but no `sequence_count` has been specified	`400`	"sequence_id supplied but no sequence_count supplied"
Disallowed characters are present	`400`	"text contains invalid characters"	Name `invalid_characters` with a value which is a JSON object, with names of the attributes containing invalid characters and values which are an array consisting of the string containing invalid characters, followed by one or more arrays containing the character indices of invalid characters. For example: `"invalid_characters": {"text": ["Hel\x0Clo th\u001F\uFFFEere", [3, 4], [9, 10], [10, 11]]}`

Some errors can occur before the validation of each attribute is performed:

Error	Code	Message	Additional attributes
The request body is not valid JSON	`400`	`invalid_json`
The request body contains byte sequences which are not valid UTF-8	`400`	`invalid_encoding`	`invalid_attributes`: an array of invalid attribute names, with invalid byte sequences encoded using `\xHH` notation, where `H` is a hex digit. For example: `"invalid_attributes": ["tex\xC2t", "task\xE3\x80_id"]` `invalid_values`: a JSON object where the attributes are the attributes with invalid values and the values are the invalid values, with invalid byte sequences encoded using `\xHH` notation, where `H` is a hex digit. For example: `"invalid_values": {"question_text": "Some \xC2text", "task\xE3\x80_id": "id\xC2three"}` with the second element showing the case where both an attribute name and its value happen to contain invalid UTF-8 (the attribute name would also appear in the `invalid_attributes` array).

Submitting text for assessment