Submitting feedback

The API supports submitting feedback which is associated with an existing text submission. This facilitates associating manual marks which were assigned to the piece of text by a person (an examiner).

Request

Method and URI:

PUT /VERSION/account/ACCOUNT_ID/text/ID/feedback

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 existing text submission which the feedback should be associated with (for example, a UUID).

Request body JSON:

The request body JSON will vary depending on the type of feedback submitted. Specifically, the content of the mark attribute will vary. There could be an overall mark, or there could be a set of marks for different aspects of the text (language, content etc.). In any case, the submitted JSON will be validated against the format defined for the feedback being submitted. A simple example with only a single overall mark follows.

{"examiner_id": 2, "mark": {"holistic": "3.5"}}

The attribute values are as follows:

Attribute name	Required?	Format	Description
`examiner_id`	Yes	An integer > 0	An ID which uniquely identifies the examiner
`mark`	Yes	A JSON object	A specification of the marks assigned. Format depends on feedback type.

A text submission can have multiple feedback submissions associated with it. This enables feedback from multiple examiners to be submitted for the same piece of text. However, if feedback is submitted for an examiner_id for which there's existing feedback for the same text submission, the newly-submitted feedback replaces the existing feedback for that examiner for the piece of text, rather than allowing multiple current marks from the same examiner for the same piece of text.

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 too long"}

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

Reason	HTTP status code	JSON response
No submission found with the specified id	`404`	`{"type": "error", "code": 404, "message": "id not found"}`
JSON does not match format for feedback type (possible error messages vary depending on feedback format)	`400`	`{"type": "error", "code": 400, "message": "must specify mark"}`

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 feedback