Template Submission endpoint

Programmatically create new sessions.

Endpoints:

Template Submission

Usage

The format of requests to the Data API use the following syntax:

https://data.learnosity.com/{LTS_VERSION}/{endpoint}

For example, to use the v2025.1.LTS version and the itembank/items endpoint, you would create a request like so:

https://data.learnosity.com/v2025.1.LTS/itembank/items

Important Data API is not a REST API. All requests must use the POST method with the action request body parameter specifying the operation to use. The Learnosity SDK must be used to make requests to Data API.

Note Data API usage is subject to rate limits.

Getting Started with the Data API
See Release Cadence and Version Lifecycle for more information on available LTS versions.

Template Submission

Create new sessions. This accepts a template object retrieved from the GET sessions/templates endpoint, and one or more sets of learner responses for the Items contained in that template.

You would want to use this to set up and prepare sessions for paper-based assessments, for example.

The endpoint will create a job to be completed asynchronously, which can be polled for using the GET /jobs endpoint and the returned job_reference to check the status of the job.

The following Question types are supported:

association
choicematrix
clozeformula
clozeinlinetext
clozetext
formulaV2
gridded
longtext
longtextV2
mcq
orderlist
plaintext
shorttext

Contact Learnosity Support if you want to use other Question types not listed above.

Endpoint	/{LTS_VERSION}/sessions
HTTP method	POST
Action type	`"set"`

Request body parameters

Body content type: application/json

data_format string

The format of the request payload.

Must be set to "from_template".

Possible values
- from_template
data array[object]

A list of sessions and responses to create programmatically against the given template.

Maximum entries: 50
- user_id string
  
  The identifier for the user.
- activity_id string
  
  The identifier for the Activity.
- session_id string (uuid)
  
  The identifier for the session.
- responses array[object]
  
  A list of Question response objects corresponding to the set of Questions contained in the template.
  
  The response format for each object varies with each Question type, but the question_id, field is common across all Question types.
  - question_id string
    
    The identifier of the Question that this response is for.
    
    Must match one of the question.id values in the template object.
  - type string
    
    The response data type value.
    
    Must be set to "array" for: association, clozeinlinetext, clozetext, choicematrix, clozeformula, mcq, orderlist.
    
    Must be set to "string" for: formulaV2, gridded, longtext, longtextV2, plaintext, shorttext.
  - value array[*] string
    
    The response value to store for this Question. The format varies for each of the supported Question types.
    - association clozeinlinetext clozetext array[string]
      
      Array of one or more strings. Each string value must match one of the possible options as defined in the Question. To create an unattempted Question, set the value to null.
    - choicematrix array[array[integer]]
      
      Array of arrays of one or more integers representing the response(s) that should be recorded for each of the sub-questions.
    - clozeformula array[array[string]]
      
      Array of arrays of one or more full formulas built based on the learner's responses. These formulas are the scoreable answers.
    - formulaV2 string
      
      The response string which is URL-encoded.
      
      Note Use + instead of spaces.
    - gridded string
      
      A string representing the number entered, including . as the decimal point, if relevant.
    - longtext longtextV2 plaintext string
      
      The response string which is URL-encoded.
      
      Note Use + instead of spaces.
    - mcq array[string]
      
      Array of one or more strings. Each string value must match one of the possible options as defined in the Question.
    - orderlist array[integer]
      
      Array of one or more integers representing the selected position of the response.
      
      The array should be in the original order as the data.list array.
      
      For example, if data.list = ['a', 'b', 'c', 'd'] and the learner chose the order: d, b, a, c, the response array will contain [3, 1, 0, 2].
    - shorttext string
      
      The response string which is URL-encoded.
      
      Note Use + instead of spaces.
  - responses array[array[string]]
    
    A list of each of the individual response box values. Required only for clozeformula.
    
    The responses that should be recorded for this Question. Array of arrays of the responses that is provided for each individual response box.
  - characterCount integer
    
    The character count of value. Required only for shorttext.
  - wordCount integer
    
    The word count of value. Required only for longtext, longtextV2, and plaintext.
ignore_response_revisions boolean

Controls whether to ignore the revision value inside a recorded response.

See Understanding Submission and Scoring for more information.

Default: false
template object

Session template retrieved from the GET /sessions/templates endpoint.

Request body example

/**
* Example session submission for an Activity containing a multi-select MCQ, a shorttext and a plaintext response.
*/
{
    "data_format": "from_template",
    "template": {
        /* Template returned by the GET session/template endpoint */
    },
    "data": [
        {
            "user_id": "1f4b4e68-5986-4468-90da-50f9901cc7ae",
            "activity_id": "example-paper-based-activity",
            "session_id": "cb6ffc66-8fdb-4beb-a712-cffc31725e57",
            "responses": [
                /* mcq, clozetext or clozeinlinetext */
                {
                    "question_id": "91c92c18e3725773844d8acaf12303ae",
                    "type": "array",
                    "value": ["0", "1"]
                },
                /* shorttext */
                {
                    "question_id": "3f45ee6e3d2e4ca2b3a84df3c53c45a6",
                    "type": "string",
                    "value": "makka+pakka",
                    "characterCount": 11
                },
                /* longtextV2, plaintext or longtext */
                {
                    "question_id": "811c7d8cd2f870eaa7ba922ba622e9",
                    "type": "string",
                    "value": "upsy+daisy"
                    "wordCount": 2
                },
                /* gridded */
                {
                    "question_id": "7578fd3697ac4648babc0b0d37b69e69",
                    "type": "string",
                    "value": "1234.56"
                },
                /* choicematrix */
                {
                    "question_id": "AC745C70FEC74331AA8A829D066BD06E"
                    "type": "array",
                    "value": [[0, 1], [0], [1], [0]]
                }
            ]
        }
    ]
}

Responses

Response example

{
    "meta": {
        "status": true,
        "timestamp": 1497929288
    },
    "data": {
        "job_reference": "248966d0-b1a3-4c0b-a569-76423d7cae74"
    }
}