examina.io API (1.0)

Download OpenAPI specification:

Ratelsoft Inc.: info@examina.io URL: https://www.examina.io/#contact Terms of Service

Use the examina.io REST API to manage exams, examinees, groups, assignments, settings, and login tokens from your server-side applications.

The production base URL is https://www.examina.io/api/v1.

Authentication

Send every request over HTTPS with the API Secret Key through Basic Authentication. The username is always api; the password is the organization's API Secret Key.

Keep the API Secret Key secure

Never commit it to version control or include it in browser code, a public repository, a mobile application, or a documentation screenshot.

A missing Authorization header returns HTTP 401. An invalid API Secret Key returns HTTP 403, and malformed Basic credentials return HTTP 415. See the API keys and webhooks guide for a working request and security guidance.

Request conventions

Send and accept application/json unless an operation specifies another media type.
Successful operations return HTTP 200 or 201 and a boolean status field.
List operations are one-based. Use the pagination fields returned by the API instead of assuming a fixed page size.

Exams

Create, inspect, configure, tag, and assign exams.

Get the first page of exams

Returns the same first page as GET /exams/1.

Authorizations:

apiSecretKey

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"exams": [{"id": "string",
"examCode": "string",
"examTitle": "string",
"version": "string",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "string",
"fileSize": 0,
"examPaperFlow": "string",
"papers": [{"property1": 0,
"property2": 0
}
],
"questionsToAnswer": [{"property1": 0,
"property2": 0
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "string",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "string",
"tabletExamPage": "string"
},
"showAnswersAfterExam": true,
"showResultsAfterExam": true,
"requirePreverification": true,
"examiner": {"property1": "string",
"property2": "string"
},
"internetDisconnectionPolicy": {"onDisconnect": "string",
"after": 0
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "string",
"after": 0
}
}
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Get Exams

Get all exams created in your organization. Response is paginated and is 1-based. You can specify the optional page path param to load exams on that page.

Authorizations:

apiSecretKey

path Parameters

page

required

string

One-based page number to load.

Responses

Response samples

200

Content type

application/json

{"maxPageCount": 25,
"total": 1,
"current": 1,
"code": "OK",
"exams": [{"id": "5eea55f4cb305a365eb98850",
"examCode": "SAMPLEEXAM",
"examTitle": "SAMPLE EXAM",
"version": "1.0.0",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "2020-06-17T17:42:12.687+0000",
"fileSize": 4378,
"examPaperFlow": "Client Controlled",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "MOBILE",
"tabletExamPage": "REGULAR"
},
"showAnswersAfterExam": false,
"showResultsAfterExam": true,
"requirePreverification": false,
"examiner": {"Examiner Name": "examiner@example.com"
},
"internetDisconnectionPolicy": {"onDisconnect": "PAUSE_EXAM",
"after": 1
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "LOGOUT_EXAMINEE",
"after": 30
}
},
"papers": [{"Driving Test": 20
},
{"Basic ICT": 20
}
],
"questionsToAnswer": [{"Driving Test": 10
},
{"Basic ICT": 10
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "https://www.examina.io/client/5eea55f4cb305a365eb98850"
}
],
"pages": 1,
"page": 1,
"status": true
}

Create Exam

Create new Exam from .smex file. Request should be sent as multipart/form-data

Authorizations:

apiSecretKey

Request Body schema: multipart/form-data
required

The required Exam .smex file sent as a multipart request with the handle: file

file

required

string <binary>

Responses

Response samples

201
409
422
500

Content type

application/json

{"exam": {"id": "5eea55f4cb305a365eb98850",
"examCode": "SAMPLEEXAM",
"examTitle": "SAMPLE EXAM",
"version": "1.0.0",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "2020-06-17T17:42:12.687+0000",
"fileSize": 4378,
"examPaperFlow": "Client Controlled",
"settings": {"visibility": false,
"handheldSettings": {"allowPhone": false,
"allowTablet": false,
"phoneExamPage": "MOBILE",
"tabletExamPage": "MOBILE"
},
"showAnswersAfterExam": false,
"showResultsAfterExam": true,
"requirePreverification": false,
"examiner": null,
"internetDisconnectionPolicy": {"onDisconnect": "DO_NOTHING",
"after": 0
},
"inExamLiveProcturing": false,
"proctorPolicy": {"onDisconnect": "DO_NOTHING",
"after": 0
}
},
"papers": [{"Driving Test": 20
},
{"Basic ICT": 20
}
],
"questionsToAnswer": [{"Driving Test": 10
},
{"Basic ICT": 10
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "https://www.examina.io/client/5eea55f4cb305a365eb98850"
},
"code": "OK",
"status": true
}

Get the details of an Exam

Get Exam details using either the Exam Code or Exam ID

Authorizations:

apiSecretKey

path Parameters

id

required

string

The Exam Code or Exam ID

Responses

Response samples

200

Content type

application/json

{"exam": {"id": "5eea55f4cb305a365eb98850",
"examCode": "SAMPLEEXAM",
"examTitle": "SAMPLE EXAM",
"version": "1.0.0",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "2020-06-17T17:42:12.687+0000",
"fileSize": 4378,
"examPaperFlow": "Client Controlled",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "MOBILE",
"tabletExamPage": "REGULAR"
},
"showAnswersAfterExam": false,
"showResultsAfterExam": true,
"requirePreverification": false,
"examiner": {"Examiner Name": "examiner@example.com"
},
"internetDisconnectionPolicy": {"onDisconnect": "PAUSE_EXAM",
"after": 1
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "LOGOUT_EXAMINEE",
"after": 30
}
},
"papers": [{"Driving Test": 20
},
{"Basic ICT": 20
}
],
"questionsToAnswer": [{"Driving Test": 10
},
{"Basic ICT": 10
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "https://www.examina.io/client/5eea55f4cb305a365eb98850"
},
"code": "OK",
"status": true
}

Delete an Exam

Delete an Exam using either the Exam Code or Exam ID

Authorizations:

apiSecretKey

path Parameters

id

required

string

The Exam Code or Exam ID

Responses

Response samples

200

Content type

application/json

{"code": "OK",
"status": true
}

Get the first page of exams with a tag

Returns the same first page as GET /exams/tag/{tag}/1.

Authorizations:

apiSecretKey

path Parameters

tag

required

string

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"exams": [{"id": "string",
"examCode": "string",
"examTitle": "string",
"version": "string",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "string",
"fileSize": 0,
"examPaperFlow": "string",
"papers": [{"property1": 0,
"property2": 0
}
],
"questionsToAnswer": [{"property1": 0,
"property2": 0
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "string",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "string",
"tabletExamPage": "string"
},
"showAnswersAfterExam": true,
"showResultsAfterExam": true,
"requirePreverification": true,
"examiner": {"property1": "string",
"property2": "string"
},
"internetDisconnectionPolicy": {"onDisconnect": "string",
"after": 0
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "string",
"after": 0
}
}
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Get Exams having Tag

Find all exams having this tag. This is a paginated response and so an optional page number can be added to the request

Authorizations:

apiSecretKey

path Parameters

tag required	string The exam tag to use for the search
page required	integer The page number to load.

Responses

Response samples

200
422

Content type

application/json

{"code": "string",
"status": true,
"exams": [{"id": "string",
"examCode": "string",
"examTitle": "string",
"version": "string",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "string",
"fileSize": 0,
"examPaperFlow": "string",
"papers": [{"property1": 0,
"property2": 0
}
],
"questionsToAnswer": [{"property1": 0,
"property2": 0
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "string",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "string",
"tabletExamPage": "string"
},
"showAnswersAfterExam": true,
"showResultsAfterExam": true,
"requirePreverification": true,
"examiner": {"property1": "string",
"property2": "string"
},
"internetDisconnectionPolicy": {"onDisconnect": "string",
"after": 0
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "string",
"after": 0
}
}
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Get Examinees mapped to this Exam

Retrieve Examinees mapped to the exam specified by the examId. This returns a paginated response and so an optional page number can be specified.

Authorizations:

apiSecretKey

path Parameters

examId required	string The Exam ID for the Exam.
page required	string The page number to retrieve.

Responses

Response samples

200

Content type

application/json

{"maxPageCount": 25,
"total": 1,
"current": 1,
"code": "OK",
"pages": 1,
"examinees": [{"id": "5ec0b77182ae4f4d01109319",
"examineeCode": "RICH",
"passcode": "hidden",
"firstName": "Richboy",
"middleName": "Kaycee",
"lastName": "David",
"dob": {"year": 2011,
"month": 7,
"day": 8
},
"gender": 1,
"timeAdded": "2020-05-17T04:02:57.046+0000",
"imagePath": "https://url/to/image",
"phoneNumber": "",
"email": "",
"mappedExams": ["5ed05438195e655f28c56f04",
"5ed0ff34763d8c506f5c4b45"
],
"addedGroups": ["5ec030da685c6765d6b440c3"
],
"proctorApprovedExams": [ ],
"proctorExemptedExams": null,
"fullName": "Richboy Kaycee David"
}
],
"page": 1,
"status": true
}

Add tags to an Exam

This allows adding tags to an Exam. Tagging an exam gives you flexibility while working with exams. You can later request for exams with a specific tag.

This returns an array of all the tags currently added to the exam. Duplicate tags are ignored. Tags can have spaces but no commas or path separators.

If an error is discovered in any of the tags, none would be added.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

The Exam ID of the target Exam

Request Body schema: application/json

Send a JSON array payload with the tags you want to add to the Exam. This works as a transaction in that if there is any error in one tag, none will be added.

Array

string

Responses

Request samples

Payload

Content type

application/json

["ratelsoft inc",
"examina.io"
]

Response samples

200
415
422

Content type

application/json

{"code": "OK",
"status": true,
"tags": ["ratelsoft",
"examina.io",
"ratelsoft inc"
]
}

Delete tags from an Exam

This allows you to remove tags from an Exam. This returns a response with all the tags currently available in the Exam after the delete.

No error is reported if a specified tag does not exist as part of the Exam tags.

Tags can have spaces but no commas or path separators.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

The Exam ID of the target Exam

Request Body schema: application/json

Send a JSON array payload with the tag(s) you want to remove from Exam.

Array

string

Responses

Request samples

Payload

Content type

application/json

["examina.io"
]

Response samples

200
415

Content type

application/json

{"code": "OK",
"status": true,
"tags": ["ratelsoft",
"ratelsoft inc"
]
}

Get all tags for an Exam

This retrieves all the tags added to an Exam as an array.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

The Exam ID of the target Exam

Responses

Response samples

200

Content type

application/json

{"code": "OK",
"status": true,
"tags": ["ratelsoft",
"ratelsoft inc"
]
}

Get the first page of exams assigned to an examinee

Returns the same first page as GET /examinee/{id}/exams/1. The identifier may be an examinee ID or code.

Authorizations:

apiSecretKey

path Parameters

id

required

string

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"exams": [{"id": "string",
"examCode": "string",
"examTitle": "string",
"version": "string",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "string",
"fileSize": 0,
"examPaperFlow": "string",
"papers": [{"property1": 0,
"property2": 0
}
],
"questionsToAnswer": [{"property1": 0,
"property2": 0
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "string",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "string",
"tabletExamPage": "string"
},
"showAnswersAfterExam": true,
"showResultsAfterExam": true,
"requirePreverification": true,
"examiner": {"property1": "string",
"property2": "string"
},
"internetDisconnectionPolicy": {"onDisconnect": "string",
"after": 0
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "string",
"after": 0
}
}
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Get all Exams Mapped to Examinee

Get all the exams mapped to an Examinee using either the Examinee ID or Code as means of matching.

This is a paginated response and allows specifying an optional page number as path parameter.

Authorizations:

apiSecretKey

path Parameters

id required	string The Examinee ID or Code whose mapping information is to be obtained.
page required	string One-based page number to load in the paginated response.

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"exams": [{"id": "string",
"examCode": "string",
"examTitle": "string",
"version": "string",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "string",
"fileSize": 0,
"examPaperFlow": "string",
"papers": [{"property1": 0,
"property2": 0
}
],
"questionsToAnswer": [{"property1": 0,
"property2": 0
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "string",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "string",
"tabletExamPage": "string"
},
"showAnswersAfterExam": true,
"showResultsAfterExam": true,
"requirePreverification": true,
"examiner": {"property1": "string",
"property2": "string"
},
"internetDisconnectionPolicy": {"onDisconnect": "string",
"after": 0
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "string",
"after": 0
}
}
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Delete all tags from an Exam

Authorizations:

apiSecretKey

path Parameters

examId

required

string

The exam ID for the target Exam.

Responses

Response samples

200

Content type

application/json

{"code": "OK",
"status": true,
"tags": [ ]
}

Create an Exam Login token for an Examinee with Code

This endpoint allows you to create a login token to allow Examinee auto login for an exam. This is particularly useful when embedding the client App widget on your website and you do not want the client to login twice.

This endpoint uses the Examinee Code of the examinee. If you did not specify one when creating the Examinee, one will be autogenerated.

Authorizations:

apiSecretKey

path Parameters

examId required	string The ID of the Exam which the login token is being created for.
examineeCode required	string The Examinee Code as autogenerated/specified in Manager.

query Parameters

duration

string

Examples: duration=1440s duration=30m duration=2h

Optional token lifetime. Use seconds (1440s), minutes (30m), or hours (2h), up to 24 hours. When omitted, the exam duration is used.

Responses

Response samples

200
422

Content type

application/json

{"expires": "2020-06-18T17:41:24.518+0000",
"code": "OK",
"status": true,
"token": "63m44vhVWQN3cpt2bYfGwS2T624rZzTZ"
}

Create an Exam Login Token for an Examinee with ID

This endpoint allows you to create a login token to allow Examinee auto login for an exam. This is particularly useful when embedding the client App widget on your website and you do not want the client to login twice.

This endpoint uses the global unique ID of the examinee to create the token.

Authorizations:

apiSecretKey

path Parameters

examId required	string The ID of the Exam which the login token is being created for.
examineeId required	string The global unique ID for this Examinee.

query Parameters

duration

string

Examples: duration=1440s duration=30m duration=2h

Optional token lifetime. Use seconds (1440s), minutes (30m), or hours (2h), up to 24 hours. When omitted, the exam duration is used.

Responses

Response samples

200
422

Content type

application/json

{"expires": "2020-06-18T17:41:24.518+0000",
"code": "OK",
"status": true,
"token": "63m44vhVWQN3cpt2bYfGwS2T624rZzTZ"
}

Replace Exam settings

This is to replace all of the exam settings. If you do not supply a value for any settings, they would be set to the default.

All invalid/unrecognized settings are ignored without warning. However, Examiner information is required when requirePreverification is enabled.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

The ID of the target Exam.

Request Body schema: application/json

All missing settings are set to their defaults. All invalid settings are silently ignored. However, Examiner information is required when requirePreverification is enabled.

Options for phoneExamPage and tabletExamPage are MOBILE and REGULAR and are not case sensitive.

Options for internetPolicyDisconnect and proctorPolicyDisconnect are DO_NOTHING, PAUSE_EXAM and LOGOUT_EXAMINEE. The values are not case sensitive and could be without the underscore or be replaced with hyphens and/or spaces. These would also work: donothing, Pause Exam, logout-Examinee.

The minimum value for internetPolicyAttempts is 1.

visibility	boolean
allowPhone	boolean
allowTablet	boolean
phoneExamPage	string
tabletExamPage	string
showAnswersAfterExam	boolean
showResultsAfterExam	boolean
requirePreverification	boolean
examinerName	string
examinerEmail	string
internetPolicyDisconnect	string
internetPolicyAttempts	integer
inExamLiveProcturing	boolean
proctorPolicyDisconnect	string
proctorPolicySeconds	integer

Responses

Request samples

Payload

Content type

application/json

{"visibility": true,
"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "MOBILE",
"tabletExamPage": "REGULAR",
"showAnswersAfterExam": false,
"showResultsAfterExam": true,
"requirePreverification": false,
"examinerName": "Peter Jones",
"examinerEmail": "examiner@example.com",
"internetPolicyDisconnect": "PAUSE_EXAM",
"internetPolicyAttempts": 1,
"inExamLiveProcturing": true,
"proctorPolicyDisconnect": "LOGOUT_EXAMINEE",
"proctorPolicySeconds": 30
}

Response samples

200

Content type

application/json

{"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "MOBILE",
"tabletExamPage": "REGULAR"
},
"showAnswersAfterExam": false,
"showResultsAfterExam": true,
"requirePreverification": false,
"examiner": {"Examiner Name": "examiner@example.com"
},
"internetDisconnectionPolicy": {"onDisconnect": "PAUSE_EXAM",
"after": 1
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "LOGOUT_EXAMINEE",
"after": 30
}
},
"code": "OK",
"status": true
}

Get Exam Settings

This allows you to get the current Exam settings for the target Exam.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

The ID of the target Exam.

Responses

Response samples

200

Content type

application/json

{"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "MOBILE",
"tabletExamPage": "REGULAR"
},
"showAnswersAfterExam": false,
"showResultsAfterExam": true,
"requirePreverification": false,
"examiner": {"Examiner Name": "examiner@example.com"
},
"internetDisconnectionPolicy": {"onDisconnect": "PAUSE_EXAM",
"after": 1
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "LOGOUT_EXAMINEE",
"after": 30
}
},
"code": "OK",
"status": true
}

Change Exam settings

This is to change some or all of the exam settings. You only need to pass on the settings you want to change and ignore the rest.

All invalid/unrecognized settings are ignored without warning. However, Examiner information is required when requirePreverification is enabled.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

The ID of the target Exam.

Request Body schema: application/json

You only need to pass on the settings you want to modify. All invalid settings are silently ignored. However, Examiner information is required when requirePreverification is enabled.

Options for phoneExamPage and tabletExamPage are MOBILE and REGULAR and are not case sensitive.

Options for internetPolicyDisconnect and proctorPolicyDisconnect are DO_NOTHING, PAUSE_EXAM and LOGOUT_EXAMINEE. The values are not case sensitive and could be without the underscore or be replaced with hyphens and/or spaces. These would also work: donothing, Pause Exam, logout-Examinee.

The minimum value for internetPolicyAttempts is 1.

visibility	boolean
allowPhone	boolean
allowTablet	boolean
phoneExamPage	string
tabletExamPage	string
showAnswersAfterExam	boolean
showResultsAfterExam	boolean
requirePreverification	boolean
examinerName	string
examinerEmail	string
internetPolicyDisconnect	string
internetPolicyAttempts	integer
inExamLiveProcturing	boolean
proctorPolicyDisconnect	string
proctorPolicySeconds	integer

Responses

Request samples

Payload

Content type

application/json

{"visibility": true,
"allowPhone": true,
"proctorPolicyDisconnect": "LOGOUT_EXAMINEE",
"proctorPolicySeconds": 30
}

Response samples

200

Content type

application/json

{"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "MOBILE",
"tabletExamPage": "REGULAR"
},
"showAnswersAfterExam": false,
"showResultsAfterExam": true,
"requirePreverification": false,
"examiner": {"Examiner Name": "examiner@example.com"
},
"internetDisconnectionPolicy": {"onDisconnect": "PAUSE_EXAM",
"after": 1
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "LOGOUT_EXAMINEE",
"after": 30
}
},
"code": "OK",
"status": true
}

Get Exam Examinee Mapping Details

Get Mapping information for an Examinee.

Authorizations:

apiSecretKey

path Parameters

examId required	string
examineeId required	string

Responses

Response samples

200

Content type

application/json

{"mapping": {"examId": "5ed05438195e655f28c56f04",
"startTime": "Anytime",
"papers": ["Computer Science"
],
"examineeId": "5ed05438195e655f28c56f04"
},
"code": "OK",
"status": true
}

Delete Exam Examinee Mapping

Delete Exam mapping for an Examinee

Authorizations:

apiSecretKey

path Parameters

examId required	string
examineeId required	string

Responses

Response samples

200

Content type

application/json

{"code": "OK",
"status": true
}

Get the first page of examinees assigned to an exam

Returns the same first page as GET /exam/{examId}/examinees/1.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"examinees": [{"id": "string",
"examineeCode": "string",
"passcode": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"dob": {"year": 0,
"month": 0,
"day": 0
},
"gender": 0,
"timeAdded": "string",
"imagePath": "string",
"phoneNumber": "string",
"email": "string",
"mappedExams": ["string"
],
"addedGroups": ["string"
],
"proctorApprovedExams": ["string"
],
"proctorExemptedExams": ["string"
],
"fullName": "string"
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Map multiple Examinees to an Exam

Add multiple examinees to take an exam with same papers and time.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

Request Body schema: application/json

The payload is an object with three keys:

ids: The IDs for all the examinees you want to map.

papers: A list of all the papers which the examinees would be taking. The titles of the papers are case sensitive. To map all available papers, supply an empty list.

startTime: ISO valid date-time timestamp. If a timezone portion is not supplied, UTC would be assumed. You can also pass on Anytime or null as the value to allow examinees to take the exam anytime. Seconds and Nano seconds are ignored and always set to 0.

startTime examples:

2020-12-10T10:30:00
2020-12-10T10:30:00.000+01:00
2020-12-10T10:30:00+01:00[Europe/Paris]
Anytime
null

The supplied startTime would be converted to a UTC date-time for the same instant using Africa/Accra as reference.

ids required	Array of strings A list of Examinee IDs to be mapped.
papers required	Array of strings A case-sensitive list of the Paper titles to map.
startTime required	string ISO valid date-time timestamp string for the Start Time for the Exam. You can use `Anytime` to allow examiness to start at anytime.

Responses

Request samples

Payload

Content type

application/json

Example

Sample Payload

{"ids": ["5ec31d64c7c54971270e0d70"
],
"papers": ["General"
],
"startTime": "2020-12-10T10:30:00+01:00"
}

Response samples

200

Content type

application/json

{"code": "OK",
"startTime": "2020-12-10T09:30:00.000+00:00",
"examinees": ["5ec31d64c7c54971270e0d70"
],
"papers": ["General"
],
"status": true
}

Delete Exam Mapping for multiple Examinees

This does not delete examinees or exams. It only removes examinees from taking an exam.

Deleting Exam mapping also deletes the exam results for the selected examinees.

Any examinee in the payload that does not exist or has not been mapped would be silently skipped. If the payload list is empty, all mapped examinees would be affected.

The response returns a list of the examinee IDs that existed and were mapped and were unmapped.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

Request Body schema: application/json

Accepts an array of examinee ids that are already mapped to this exam.

To delete mapping for all examinees already mapped to this exam, pass on an empty list.

Array

string

Responses

Request samples

Payload

Content type

application/json

Example

Sample Payload

["5ec31d64c7c54971270e0d70",
"5ec0b77182ae4f4d01109319"
]

Response samples

200

Content type

application/json

{"code": "OK",
"status": true,
"examinees": ["5ec31d64c7c54971270e0d70",
"5ec0b77182ae4f4d01109319"
]
}

Map Examinees in a Group to an Exam

Authorizations:

apiSecretKey

path Parameters

examId

required

string

Request Body schema: application/json

The payload is an object with three keys:

ids: The IDs for all the groups from which all examinees you want to map would be obtained.

papers: A list of all the papers which the examinees would be taking. The titles of the papers are case sensitive. To map all available papers, supply an empty list.

startTime: ISO valid date-time timestamp. If a timezone portion is not supplied, UTC would be assumed. You can also pass on Anytime or null as the value to allow examinees to take the exam anytime. Seconds and Nano seconds are ignored and always set to 0.

startTime examples:

2020-12-10T10:30:00
2020-12-10T10:30:00.000+01:00
2020-12-10T10:30:00+01:00[Europe/Paris]
Anytime
null

The supplied startTime would be converted to a UTC date-time for the same instant using Africa/Accra as reference.

ids required	Array of strings A list of Group IDs from which to pull examinees to be mapped.
papers required	Array of strings A case-sensitive list of the Paper titles to map.
startTime required	string ISO valid date-time timestamp string for the Start Time for the Exam. You can use `Anytime` to allow examiness to start at anytime.

Responses

Request samples

Payload

Content type

application/json

{"ids": ["5ec861b33145820f14bb9ba3"
],
"papers": [ ],
"startTime": "2020-12-10T10:30:54.567"
}

Response samples

200

Content type

application/json

{"code": "OK",
"startTime": "2020-12-10T10:30:00.000+0000",
"examinees": ["5eff4a0ee8cc912519e2dbf7",
"5eff4a0ee8cc912519e2dbf8",
"5eff4a0de8cc912519e2dbe2",
"5eff4a0ee8cc912519e2dbf3",
"5eff4a0de8cc912519e2dbe1",
"5eff4a0ee8cc912519e2dbf4",
"5eff4a0ee8cc912519e2dbf5",
"5eff4a0de8cc912519e2dbf0",
"5eff4a0ee8cc912519e2dbf6",
"5eff4a0de8cc912519e2dbef",
"5eff4a0de8cc912519e2dbee",
"5eff4a0de8cc912519e2dbed",
"5eff4a0de8cc912519e2dbec",
"5eff4a0de8cc912519e2dbeb",
"5eff4a0de8cc912519e2dbea",
"5eff4a0de8cc912519e2dbe6",
"5eff4a0de8cc912519e2dbe5",
"5eff4a0de8cc912519e2dbe4",
"5eff4a0ee8cc912519e2dbf1",
"5eff4a0de8cc912519e2dbe3",
"5eff4a0ee8cc912519e2dbf2",
"5eff4a0de8cc912519e2dbe9",
"5eff4a0de8cc912519e2dbe8",
"5eff4a0de8cc912519e2dbe7"
],
"papers": ["General"
],
"status": true
}

Examinees

Manage examinees and the exams assigned to them.

Get the first page of examinees

Returns the same first page as GET /examinees/1.

Authorizations:

apiSecretKey

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"examinees": [{"id": "string",
"examineeCode": "string",
"passcode": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"dob": {"year": 0,
"month": 0,
"day": 0
},
"gender": 0,
"timeAdded": "string",
"imagePath": "string",
"phoneNumber": "string",
"email": "string",
"mappedExams": ["string"
],
"addedGroups": ["string"
],
"proctorApprovedExams": ["string"
],
"proctorExemptedExams": ["string"
],
"fullName": "string"
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Get Examinees

This endpoint is paginated. For other pages you need to specify the page number path parameter.

Authorizations:

apiSecretKey

path Parameters

page

required

integer

One-based page number from which examinees are retrieved.

Responses

Response samples

200

Content type

application/json

{"maxPageCount": 25,
"total": 1,
"current": 1,
"code": "OK",
"pages": 1,
"examinees": [{"id": "5ec0b77182ae4f4d01109319",
"examineeCode": "RICH",
"passcode": "hidden",
"firstName": "Richboy",
"middleName": "Kaycee",
"lastName": "David",
"dob": {"year": 2011,
"month": 7,
"day": 8
},
"gender": 1,
"timeAdded": "2020-05-17T04:02:57.046+0000",
"imagePath": "https://url/to/image",
"phoneNumber": "",
"email": "",
"mappedExams": ["5ed05438195e655f28c56f04",
"5ed0ff34763d8c506f5c4b45"
],
"addedGroups": ["5ec030da685c6765d6b440c3"
],
"proctorApprovedExams": [ ],
"proctorExemptedExams": null,
"fullName": "Richboy Kaycee David"
}
],
"page": 1,
"status": true
}

Get Examinees mapped to this Exam

Retrieve Examinees mapped to the exam specified by the examId. This returns a paginated response and so an optional page number can be specified.

Authorizations:

apiSecretKey

path Parameters

examId required	string The Exam ID for the Exam.
page required	string The page number to retrieve.

Responses

Response samples

200

Content type

application/json

{"maxPageCount": 25,
"total": 1,
"current": 1,
"code": "OK",
"pages": 1,
"examinees": [{"id": "5ec0b77182ae4f4d01109319",
"examineeCode": "RICH",
"passcode": "hidden",
"firstName": "Richboy",
"middleName": "Kaycee",
"lastName": "David",
"dob": {"year": 2011,
"month": 7,
"day": 8
},
"gender": 1,
"timeAdded": "2020-05-17T04:02:57.046+0000",
"imagePath": "https://url/to/image",
"phoneNumber": "",
"email": "",
"mappedExams": ["5ed05438195e655f28c56f04",
"5ed0ff34763d8c506f5c4b45"
],
"addedGroups": ["5ec030da685c6765d6b440c3"
],
"proctorApprovedExams": [ ],
"proctorExemptedExams": null,
"fullName": "Richboy Kaycee David"
}
],
"page": 1,
"status": true
}

Get Examinee Details with ID or Code

This allows fetching information about an Examinee using either the Examinee ID or the Examinee Code.

Authorizations:

apiSecretKey

path Parameters

id

required

string

This can either be the ID of the Examinee or the Examinee Code.

Responses

Response samples

200
404

Content type

application/json

{"code": "OK",
"examinee": {"id": "5ec0b77182ae4f4d01109319",
"examineeCode": "RICH",
"passcode": "hidden",
"firstName": "Richboy",
"middleName": "Kaycee",
"lastName": "David",
"dob": {"year": 2011,
"month": 7,
"day": 8
},
"gender": 1,
"timeAdded": "2020-05-17T04:02:57.046+0000",
"imagePath": "https://url/to/image",
"phoneNumber": "",
"email": "",
"mappedExams": ["5ed05438195e655f28c56f04",
"5ed0ff34763d8c506f5c4b45"
],
"addedGroups": ["5ec030da685c6765d6b440c3"
],
"proctorApprovedExams": [ ],
"proctorExemptedExams": null,
"fullName": "Richboy Kaycee David"
},
"status": true
}

Delete an Examinee using ID or Code

This allows deleting an Examinee using either the Examinee ID or the Examinee Code.

Authorizations:

apiSecretKey

path Parameters

id

required

string

This can either be the ID of the Examinee or the Examinee Code.

Responses

Response samples

200
404

Content type

application/json

{"code": "OK",
"status": true
}

Get the first page of exams assigned to an examinee

Returns the same first page as GET /examinee/{id}/exams/1. The identifier may be an examinee ID or code.

Authorizations:

apiSecretKey

path Parameters

id

required

string

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"exams": [{"id": "string",
"examCode": "string",
"examTitle": "string",
"version": "string",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "string",
"fileSize": 0,
"examPaperFlow": "string",
"papers": [{"property1": 0,
"property2": 0
}
],
"questionsToAnswer": [{"property1": 0,
"property2": 0
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "string",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "string",
"tabletExamPage": "string"
},
"showAnswersAfterExam": true,
"showResultsAfterExam": true,
"requirePreverification": true,
"examiner": {"property1": "string",
"property2": "string"
},
"internetDisconnectionPolicy": {"onDisconnect": "string",
"after": 0
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "string",
"after": 0
}
}
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Get all Exams Mapped to Examinee

Get all the exams mapped to an Examinee using either the Examinee ID or Code as means of matching.

This is a paginated response and allows specifying an optional page number as path parameter.

Authorizations:

apiSecretKey

path Parameters

id required	string The Examinee ID or Code whose mapping information is to be obtained.
page required	string One-based page number to load in the paginated response.

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"exams": [{"id": "string",
"examCode": "string",
"examTitle": "string",
"version": "string",
"brandingImage": null,
"brandingColor": null,
"timeAdded": "string",
"fileSize": 0,
"examPaperFlow": "string",
"papers": [{"property1": 0,
"property2": 0
}
],
"questionsToAnswer": [{"property1": 0,
"property2": 0
}
],
"tags": null,
"mappedExaminees": null,
"examLink": "string",
"settings": {"visibility": true,
"handheldSettings": {"allowPhone": true,
"allowTablet": true,
"phoneExamPage": "string",
"tabletExamPage": "string"
},
"showAnswersAfterExam": true,
"showResultsAfterExam": true,
"requirePreverification": true,
"examiner": {"property1": "string",
"property2": "string"
},
"internetDisconnectionPolicy": {"onDisconnect": "string",
"after": 0
},
"inExamLiveProcturing": true,
"proctorPolicy": {"onDisconnect": "string",
"after": 0
}
}
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Create an Exam Login token for an Examinee with Code

This endpoint allows you to create a login token to allow Examinee auto login for an exam. This is particularly useful when embedding the client App widget on your website and you do not want the client to login twice.

This endpoint uses the Examinee Code of the examinee. If you did not specify one when creating the Examinee, one will be autogenerated.

Authorizations:

apiSecretKey

path Parameters

examId required	string The ID of the Exam which the login token is being created for.
examineeCode required	string The Examinee Code as autogenerated/specified in Manager.

query Parameters

duration

string

Examples: duration=1440s duration=30m duration=2h

Optional token lifetime. Use seconds (1440s), minutes (30m), or hours (2h), up to 24 hours. When omitted, the exam duration is used.

Responses

Response samples

200
422

Content type

application/json

{"expires": "2020-06-18T17:41:24.518+0000",
"code": "OK",
"status": true,
"token": "63m44vhVWQN3cpt2bYfGwS2T624rZzTZ"
}

Create an Exam Login Token for an Examinee with ID

This endpoint allows you to create a login token to allow Examinee auto login for an exam. This is particularly useful when embedding the client App widget on your website and you do not want the client to login twice.

This endpoint uses the global unique ID of the examinee to create the token.

Authorizations:

apiSecretKey

path Parameters

examId required	string The ID of the Exam which the login token is being created for.
examineeId required	string The global unique ID for this Examinee.

query Parameters

duration

string

Examples: duration=1440s duration=30m duration=2h

Optional token lifetime. Use seconds (1440s), minutes (30m), or hours (2h), up to 24 hours. When omitted, the exam duration is used.

Responses

Response samples

200
422

Content type

application/json

{"expires": "2020-06-18T17:41:24.518+0000",
"code": "OK",
"status": true,
"token": "63m44vhVWQN3cpt2bYfGwS2T624rZzTZ"
}

Get Exam Examinee Mapping Details

Get Mapping information for an Examinee.

Authorizations:

apiSecretKey

path Parameters

examId required	string
examineeId required	string

Responses

Response samples

200

Content type

application/json

{"mapping": {"examId": "5ed05438195e655f28c56f04",
"startTime": "Anytime",
"papers": ["Computer Science"
],
"examineeId": "5ed05438195e655f28c56f04"
},
"code": "OK",
"status": true
}

Delete Exam Examinee Mapping

Delete Exam mapping for an Examinee

Authorizations:

apiSecretKey

path Parameters

examId required	string
examineeId required	string

Responses

Response samples

200

Content type

application/json

{"code": "OK",
"status": true
}

Get the first page of examinees assigned to an exam

Returns the same first page as GET /exam/{examId}/examinees/1.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"examinees": [{"id": "string",
"examineeCode": "string",
"passcode": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"dob": {"year": 0,
"month": 0,
"day": 0
},
"gender": 0,
"timeAdded": "string",
"imagePath": "string",
"phoneNumber": "string",
"email": "string",
"mappedExams": ["string"
],
"addedGroups": ["string"
],
"proctorApprovedExams": ["string"
],
"proctorExemptedExams": ["string"
],
"fullName": "string"
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Map multiple Examinees to an Exam

Add multiple examinees to take an exam with same papers and time.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

Request Body schema: application/json

The payload is an object with three keys:

ids: The IDs for all the examinees you want to map.

papers: A list of all the papers which the examinees would be taking. The titles of the papers are case sensitive. To map all available papers, supply an empty list.

startTime: ISO valid date-time timestamp. If a timezone portion is not supplied, UTC would be assumed. You can also pass on Anytime or null as the value to allow examinees to take the exam anytime. Seconds and Nano seconds are ignored and always set to 0.

startTime examples:

2020-12-10T10:30:00
2020-12-10T10:30:00.000+01:00
2020-12-10T10:30:00+01:00[Europe/Paris]
Anytime
null

The supplied startTime would be converted to a UTC date-time for the same instant using Africa/Accra as reference.

ids required	Array of strings A list of Examinee IDs to be mapped.
papers required	Array of strings A case-sensitive list of the Paper titles to map.
startTime required	string ISO valid date-time timestamp string for the Start Time for the Exam. You can use `Anytime` to allow examiness to start at anytime.

Responses

Request samples

Payload

Content type

application/json

Example

Sample Payload

{"ids": ["5ec31d64c7c54971270e0d70"
],
"papers": ["General"
],
"startTime": "2020-12-10T10:30:00+01:00"
}

Response samples

200

Content type

application/json

{"code": "OK",
"startTime": "2020-12-10T09:30:00.000+00:00",
"examinees": ["5ec31d64c7c54971270e0d70"
],
"papers": ["General"
],
"status": true
}

Delete Exam Mapping for multiple Examinees

This does not delete examinees or exams. It only removes examinees from taking an exam.

Deleting Exam mapping also deletes the exam results for the selected examinees.

Any examinee in the payload that does not exist or has not been mapped would be silently skipped. If the payload list is empty, all mapped examinees would be affected.

The response returns a list of the examinee IDs that existed and were mapped and were unmapped.

Authorizations:

apiSecretKey

path Parameters

examId

required

string

Request Body schema: application/json

Accepts an array of examinee ids that are already mapped to this exam.

To delete mapping for all examinees already mapped to this exam, pass on an empty list.

Array

string

Responses

Request samples

Payload

Content type

application/json

Example

Sample Payload

["5ec31d64c7c54971270e0d70",
"5ec0b77182ae4f4d01109319"
]

Response samples

200

Content type

application/json

{"code": "OK",
"status": true,
"examinees": ["5ec31d64c7c54971270e0d70",
"5ec0b77182ae4f4d01109319"
]
}

Client access

Create secure login tokens for the exam client.

Create an Exam Login token for an Examinee with Code

This endpoint allows you to create a login token to allow Examinee auto login for an exam. This is particularly useful when embedding the client App widget on your website and you do not want the client to login twice.

This endpoint uses the Examinee Code of the examinee. If you did not specify one when creating the Examinee, one will be autogenerated.

Authorizations:

apiSecretKey

path Parameters

examId required	string The ID of the Exam which the login token is being created for.
examineeCode required	string The Examinee Code as autogenerated/specified in Manager.

query Parameters

duration

string

Examples: duration=1440s duration=30m duration=2h

Optional token lifetime. Use seconds (1440s), minutes (30m), or hours (2h), up to 24 hours. When omitted, the exam duration is used.

Responses

Response samples

200
422

Content type

application/json

{"expires": "2020-06-18T17:41:24.518+0000",
"code": "OK",
"status": true,
"token": "63m44vhVWQN3cpt2bYfGwS2T624rZzTZ"
}

Create an Exam Login Token for an Examinee with ID

This endpoint allows you to create a login token to allow Examinee auto login for an exam. This is particularly useful when embedding the client App widget on your website and you do not want the client to login twice.

This endpoint uses the global unique ID of the examinee to create the token.

Authorizations:

apiSecretKey

path Parameters

examId required	string The ID of the Exam which the login token is being created for.
examineeId required	string The global unique ID for this Examinee.

query Parameters

duration

string

Examples: duration=1440s duration=30m duration=2h

Optional token lifetime. Use seconds (1440s), minutes (30m), or hours (2h), up to 24 hours. When omitted, the exam duration is used.

Responses

Response samples

200
422

Content type

application/json

{"expires": "2020-06-18T17:41:24.518+0000",
"code": "OK",
"status": true,
"token": "63m44vhVWQN3cpt2bYfGwS2T624rZzTZ"
}

Groups

Organize examinees and manage group assignments.

Create a new Group

Authorizations:

apiSecretKey

Request Body schema: application/json

name is the name of the Group. desc is optional and is the description for the group. If this is not specified, the name is used as the description.

name required	string
desc	string

Responses

Request samples

Payload

Content type

application/json

{"name": "Juniors"
}

Response samples

201
409

Content type

application/json

{"code": "OK",
"groups": [{"id": "5efe39249ae73336c03b2b3f",
"userId": "5ebcc66b61636c132abecc41",
"creatorName": "David Echomgbe",
"name": "Juniors",
"desc": "Juniors",
"timeAdded": "2020-07-02T19:44:36.062+0000",
"examinees": null
}
],
"status": true
}

Get Groups

Get all groups added in your organization. Response is paginated and is 1-based. You can specify the optional page path param to load groups on that page.

Authorizations:

apiSecretKey

path Parameters

page

required

string

Only used for the Get request. The page from which to retrive the groups.

Responses

Response samples

200

Content type

application/json

{"maxPageCount": 25,
"total": 2,
"current": 2,
"code": "OK",
"pages": 1,
"groups": [{"id": "5efe6179183be72cde888e6b",
"userId": "5ebcc66b61636c132abecc41",
"creatorName": "David Echomgbe",
"name": "Seniors",
"desc": "A Group for the senior classes",
"timeAdded": "2020-07-02T22:36:41.417+0000",
"examinees": ["5ec31d64c7c54971270e0d70",
"5ec0b77182ae4f4d01109319"
]
},
{"id": "5efe39249ae73336c03b2b3f",
"userId": "5ebcc66b61636c132abecc41",
"creatorName": "David Echomgbe",
"name": "Juniors",
"desc": "Juniors",
"timeAdded": "2020-07-02T19:44:36.062+0000",
"examinees": null
}
],
"page": 1,
"status": true
}

Create multiple groups (compatibility route) Deprecated

Compatibility alias for POST /groups. The page value is ignored; new integrations should use POST /groups.

Authorizations:

apiSecretKey

path Parameters

page

required

string

Only used for the Get request. The page from which to retrive the groups.

Request Body schema: application/json
required

Array

name required	string
desc	string

Responses

Request samples

Payload

Content type

application/json

[{"name": "string",
"desc": "string"
}
]

Response samples

201

Content type

application/json

{"code": "string",
"groups": [{"id": "string",
"userId": "string",
"creatorName": "string",
"name": "string",
"desc": "string",
"timeAdded": "string",
"examinees": ["string"
]
}
],
"status": true
}

Get all the Examinees in this Group

This allows you to get the IDs of all examinees in a Group

Authorizations:

apiSecretKey

path Parameters

groupId

required

string

Responses

Response samples

200

Content type

application/json

{"code": "OK",
"examinees": ["5eefc6f4e23b88151efc9326",
"5ec0b77182ae4f4d01109319"
],
"status": true
}

Add Examinees to a Group

This allows you to add examinees to a group. If any examinee does not exist, or is already a member of the group, it is silently ignored.

Authorizations:

apiSecretKey

path Parameters

groupId

required

string

Request Body schema: application/json

You pass a list of Examinee IDs to add to the group.

Array

string

Responses

Request samples

Payload

Content type

application/json

["5ec0b77182ae4f4d01109319",
"5eefc6f4e23b88151efc9326"
]

Response samples

200

Content type

application/json

{"code": "OK",
"examinees": ["5eefc6f4e23b88151efc9326",
"5ec0b77182ae4f4d01109319"
],
"status": true
}

Remove Examinees from a Group

This allows you to remove examinees from a group. Any examinee that was not found will be silently ignored.

To remove all examinees, send an empty list as the payload.

Note that this does not delete the examinees. This only detaches examinees from the group. The group and the examinees would all still exist.

Authorizations:

apiSecretKey

path Parameters

groupId

required

string

Request Body schema: application/json

A list of examinee IDs to remove from the group.

Array

string

Responses

Request samples

Payload

Content type

application/json

Example

Sample Payload

["5ec0b77182ae4f4d01109319",
"5eefc6f4e23b88151efc9326"
]

Response samples

200

Content type

application/json

{"code": "OK",
"examinees": ["5eefc6f4e23b88151efc9326",
"5ec0b77182ae4f4d01109319"
],
"status": true
}

Get Group details

Authorizations:

apiSecretKey

path Parameters

groupId

required

string

Responses

Response samples

200

Content type

application/json

{"code": "OK",
"status": true,
"group": {"id": "5efe6179183be72cde888e6c",
"userId": "5ebcc66b61636c132abecc41",
"creatorName": "David Echomgbe",
"name": "Applicants July 2020",
"desc": "A Group for the July 2020 applicants",
"timeAdded": "2020-07-02T22:36:41.498+0000",
"examinees": ["5ec0b77182ae4f4d01109319",
"5eefc6f4e23b88151efc9326"
]
}
}

Delete a Group

This does not delete the examinees in the group. The examinees are removed from the group and then the group is deleted.

Authorizations:

apiSecretKey

path Parameters

groupId

required

string

Responses

Response samples

200

Content type

application/json

{"code": "OK",
"status": true
}

Add Groups to Group

This allows you to aggregate examinees in one or more groups and add them to a single group. Duplicate examinees are silently ignored. Groups that do not exist are also silently ignored.

A list of the IDs of all added examinees are returned.

Authorizations:

apiSecretKey

path Parameters

groupId

required

string

Request Body schema: application/json

A list of Group IDs from which to get examinees and add to this group.

Array

string

Responses

Request samples

Payload

Content type

application/json

["5ec02dd0685c6765d6b440c1",
"5ec030da685c6765d6b440c3"
]

Response samples

200

Content type

application/json

{"code": "OK",
"examinees": ["5ec31d64c7c54971270e0d70",
"5ec0b77182ae4f4d01109319"
],
"status": true
}

Get the first page of groups

Returns the same first page as GET /groups/1.

Authorizations:

apiSecretKey

Responses

Response samples

200

Content type

application/json

{"code": "string",
"status": true,
"groups": [{"id": "string",
"userId": "string",
"creatorName": "string",
"name": "string",
"desc": "string",
"timeAdded": "string",
"examinees": ["string"
]
}
],
"maxPageCount": 0,
"total": 0,
"current": 0,
"pages": 0,
"page": 0
}

Create multiple Groups

Create multiple Groups at once

Authorizations:

apiSecretKey

Request Body schema: application/json

A List of JSON objects with name and an optional desc

Array

name required	string
desc	string Description of the group.

Responses

Request samples

Payload

Content type

application/json

[{"name": "Seniors",
"desc": "A Group for the senior classes"
},
{"name": "Applicants July 2020",
"desc": "A Group for the July 2020 applicants"
}
]

Response samples

201
409

Content type

application/json

{"code": "OK",
"groups": [{"id": "5efe6179183be72cde888e6b",
"userId": "5ebcc66b61636c132abecc41",
"creatorName": "David Echomgbe",
"name": "Seniors",
"desc": "A Group for the senior classes",
"timeAdded": "2020-07-02T22:36:41.417+0000",
"examinees": null
},
{"id": "5efe6179183be72cde888e6c",
"userId": "5ebcc66b61636c132abecc41",
"creatorName": "David Echomgbe",
"name": "Applicants July 2020",
"desc": "A Group for the July 2020 applicants",
"timeAdded": "2020-07-02T22:36:41.498+0000",
"examinees": null
}
],
"status": true
}

Map Examinees in a Group to an Exam

Authorizations:

apiSecretKey

path Parameters

examId

required

string

Request Body schema: application/json

The payload is an object with three keys:

ids: The IDs for all the groups from which all examinees you want to map would be obtained.

papers: A list of all the papers which the examinees would be taking. The titles of the papers are case sensitive. To map all available papers, supply an empty list.

startTime: ISO valid date-time timestamp. If a timezone portion is not supplied, UTC would be assumed. You can also pass on Anytime or null as the value to allow examinees to take the exam anytime. Seconds and Nano seconds are ignored and always set to 0.

startTime examples:

2020-12-10T10:30:00
2020-12-10T10:30:00.000+01:00
2020-12-10T10:30:00+01:00[Europe/Paris]
Anytime
null

The supplied startTime would be converted to a UTC date-time for the same instant using Africa/Accra as reference.

ids required	Array of strings A list of Group IDs from which to pull examinees to be mapped.
papers required	Array of strings A case-sensitive list of the Paper titles to map.
startTime required	string ISO valid date-time timestamp string for the Start Time for the Exam. You can use `Anytime` to allow examiness to start at anytime.

Responses

Request samples

Payload

Content type

application/json

{"ids": ["5ec861b33145820f14bb9ba3"
],
"papers": [ ],
"startTime": "2020-12-10T10:30:54.567"
}

Response samples

200

Content type

application/json

{"code": "OK",
"startTime": "2020-12-10T10:30:00.000+0000",
"examinees": ["5eff4a0ee8cc912519e2dbf7",
"5eff4a0ee8cc912519e2dbf8",
"5eff4a0de8cc912519e2dbe2",
"5eff4a0ee8cc912519e2dbf3",
"5eff4a0de8cc912519e2dbe1",
"5eff4a0ee8cc912519e2dbf4",
"5eff4a0ee8cc912519e2dbf5",
"5eff4a0de8cc912519e2dbf0",
"5eff4a0ee8cc912519e2dbf6",
"5eff4a0de8cc912519e2dbef",
"5eff4a0de8cc912519e2dbee",
"5eff4a0de8cc912519e2dbed",
"5eff4a0de8cc912519e2dbec",
"5eff4a0de8cc912519e2dbeb",
"5eff4a0de8cc912519e2dbea",
"5eff4a0de8cc912519e2dbe6",
"5eff4a0de8cc912519e2dbe5",
"5eff4a0de8cc912519e2dbe4",
"5eff4a0ee8cc912519e2dbf1",
"5eff4a0de8cc912519e2dbe3",
"5eff4a0ee8cc912519e2dbf2",
"5eff4a0de8cc912519e2dbe9",
"5eff4a0de8cc912519e2dbe8",
"5eff4a0de8cc912519e2dbe7"
],
"papers": ["General"
],
"status": true
}

examina.io API (1.0)

Authentication

Request conventions

Exams

Get the first page of exams

Authorizations:

Responses

Response samples

Get Exams

Authorizations:

path Parameters

Responses

Response samples

Create Exam

Authorizations:

Request Body schema: multipart/form-datarequired

Responses

Response samples

Get the details of an Exam

Authorizations:

path Parameters

Responses

Response samples

Delete an Exam

Authorizations:

path Parameters

Responses

Response samples

Get the first page of exams with a tag

Authorizations:

path Parameters

Responses

Response samples

Get Exams having Tag

Authorizations:

path Parameters

Responses

Response samples

Get Examinees mapped to this Exam

Authorizations:

path Parameters

Responses

Response samples

Add tags to an Exam

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Delete tags from an Exam

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Get all tags for an Exam

Authorizations:

path Parameters

Responses

Response samples

Get the first page of exams assigned to an examinee

Authorizations:

path Parameters

Responses

Response samples

Get all Exams Mapped to Examinee

Authorizations:

path Parameters

Responses

Response samples

Delete all tags from an Exam

Authorizations:

path Parameters

Responses

Response samples

Create an Exam Login token for an Examinee with Code

Authorizations:

path Parameters

Request Body schema: multipart/form-data
required