POST tests

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 `weight` 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. You must have an 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.