POST tests

POST Defines a new test. A test consists of a fixed number of questions taken from one or more drills. The user taking the test answers each question, but will not receive any feedback while doing so. When finished, a score is calculated based on the number of correct answers.

Resource URL

https://www.drillster.com/api/2/tests

Parameters

Field Type Description
drill
required, repeatable
String

The drill to test. Can be specified multiple times to test multiple drills in a single test.

Example value: yy9p1ivLSMGGvoX8PkBsv

title
optional
String

The title of the test. If not specified, the name of the drill is used, or the subject if more than one drill is specified.

Example value: Testing my geography

instructions
optional
String

An instruction text that will be presented just before the test starts. These typically contain directions for the user taking the test.

Example value: Carefully read the test questions, and take your time to select the correct answer.

disclosure
optional
String

The disclosure defines what test results the user will see after finishing the test. Two components can be displayed:

  • Test score — the user's score for the test (0-100%)
  • Detailed results — the test metadata, the evaluation of each answer, plus the score per drill if multiple drills were tested.
The possible values are:
  • FULL — The test score and the detailed results (default)
  • PARTIAL — Only the test score
  • NONE — No results are displayed

direction
optional
String

The enforced direction for the questions of this test. If the drill of this test has an enforced direction, this will be used instead of the provided direction.

  • PRODUCTIVE — Reproduce what you've learned: questions are picked from the known column
  • RECEPTIVE — Recognize what you've learned: questions are picked from the unknown column(s)
  • BIDIRECTIONAL — Questions are picked from both the known and unknown columns (default)
style
optional
String

The answer style for the questions of this test. If the drill(s) of this test have a enforced style, this style will be used instead of the provided style.

  • MULTIPLE_CHOICE — The user has to select the correct answer from two or more presented answers (default)
  • OPEN_ENDED — The user has to enter the correct answer
column
optional, repeatable
String

The name of the unknown column to include in the test questions. If the drill that is tested has more than one unknown column, you can limit the questions that will appear in the test by specifying the name of the unknown column. You can specify this parameter multiple times if you want to include multiple unknown columns.

Omitting this parameter will include all available unknown columns in the test.

Example value: French

tag
optional, repeatable
String

The entry tag to include in the test questions. Entry tags can be attached to specific drill entries in the drill editor. Each drill specified for this test must have at least one of the entry tags you specify. You can specify this parameter multiple times if you want to include multiple entry tags.

Omitting this parameter will include all available entries in the test.

Example value: grammar

questions
optional, repeatable
Integer

The number of questions to include in the test. This can't be higher than the number of entries in the drill(s). If omitted, 40 questions will be selected by default (or less if the drill does not have 40 entries). The questions will be selected randomly from the specified drill(s).

If more than one drill is specified, and this parameter is provided once, the number of questions taken from each drill is proportional to the size (number of entries) of the drill. If, for example, you specify 2 drills, one having 20 entries and the other 40, and you specify questions once, with value 30, 10 questions will be taken from the 1st drill, and 20 from the 2nd.

However, if the parameter is provided more than once (while specifying more than one drill), the number of questions taken from each drill is the value of each parameter. This means that for each drill, one questions parameter must be specified – no more, and no less. The first parameter value specifies the number of questions taken from the first drill, the second parameter value specifies the number of questions from the second drill, etc. So, for example, you specify drill A and B (in that order), and you specify questions=15 and questions=20 (in that order), 15 questions will be taken from drill A, and 20 from drill B.

For adaptive tests, this parameter must be specified exactly once, and indicates the number of questions that will be taken from each drill.

weights
optional, repeatable
Integer

The weight of each drill on the result of the test. When more than one drill is specified, you can set a weight for each drill. The weight of the drill is used to adjust the contribution of the answers for the drill to the overall score. The value of the weight can anything between 0 and 100 (inclusive). By default, the weight of each drill is 100.

If the test contains two drills, and the first drill's weight is 50, and the second is 100, the answers on questions from the second drill will have twice the impact of answers on the first drill.

The number of specified weight values must match the number of specified drill values. The order of the weight values must match that of the drill values, so the first weights value applies to the first drill, etc.

adaptive
optional
Boolean

Specify TRUE for an adaptive test, or FALSE (or omit) for standard a test.

  • TRUE
  • FALSE (default)
timeLimit
optional
ISO 8601 duration

Specifies the maximum time that the user is allowed to complete the test. Answers submitted after this time limit (or not submitted) are considered incorrect. The time is measured from the moment the first question is presented. It is not possible to configure a time limit for adaptive tests (adaptive = TRUE), or for tests that contain drills with answer time limits.

If a time limit is specified, allowUnansweredQuestions must be TRUE.

Example values:

  • PT10M30S (10 minutes 30 seconds)
  • PT1H (1 hour)

allowQuestionNavigation
optional
Boolean

Specify TRUE (or omit) to allow the user to navigate (go back and forth) between the questions of the test, or FALSE to force the user to see and answer all questions in the order defined by the test.

It is not possible to allow question navigation for adaptive tests, nor for tests with drills containing answer time limits. For these tests, FALSE must be specified.

  • TRUE (default)
  • FALSE
allowUnansweredQuestions
optional
Boolean

Specify TRUE allow the user to complete the test while one or more questions are unanswered, or FALSE (or omit) to force the user to answer all questions before completing the test.

  • TRUE
  • FALSE (default)

Response

The ID of the created test is returned.

Example request

POST https://www.drillster.com/api/2/tests
drill=1J-_acRwTnmyN03eMS5IHw&drill=FHh6PtOzQFWK-LH_Roe0xw&title=Testing+all+european+capitals&disclosure=PARTIAL&questions=12&questions=8

Response

{
  "id" : "HCg9aaeZRdGEw16dLXUowQ"
}

Error responses

The following error situations are possible:

ID Description
drill_not_released You are setting up an anonymous test, but one of the specified drills has not been released yet. Anonymous drills can only be set up for released drills.
drills_missing You did not specify any drills.
inaccessible_drill You specified one or more drills that you are not allowed to use. It might be a private drill of another user.
empty_drill The drills you specified don't have any entries.
invalid_direction The specified direction is not one of the possible values.
invalid_disclosure The specified disclosure is not one of the possible values.
invalid_nr_of_questions The specified question value(s) is invalid, e.g. more than the available number of drill entries, or in case you specified more than one question parameters, the number of parameters does not match the number of drills.
invalid_style The specified style is not one of the possible values.
invalid_test_type The specified test type is not one of the possible values.
invalid_time_limit The specified time limit is not a valid ISO 8601 duration.
no_permission Your Drillster account does not allow setting up tests. For an individual test, you must have a Drillter Premium Account, and for an anonymous test you must have a Educational or Business Account.
non_public_drill You are setting up an anonymous test, but you specified one or more drills that are not public. For anonymous tests, all drills must be public, otherwise the users taking the test can't access them.
unable_to_set_time_limit It is not possible to set a time limit for this test, since it contains one or more drills that have answer time limits configured.
unknown_drill You specified one or more non-existing drills.