Create schedule and generate links
  • 17 Apr 2024
  • 4 Minutes to read
  • Contributors
  • Dark
  • PDF

Create schedule and generate links

  • Dark
  • PDF

Article summary

POST /schedule

NameData TypeDescription
Content-type:application/jsonfor all requests
Authorization:EAPI {token}for all requests

Request Parameters (for message body)

Parameters indicated with a * are mandatory

Data Type
WorkflowString[enum]Workflow for current schedule. Possible values: DEFAULT, EXTERNAL_ATTEMPTS

DEFAULT - by default, used for simple Cirrus schedule workflow.
EXTERNAL_ATTEMPTS - allows to have AttemptExtId for each candidate to support external scheduling logic.
UpsertBooleanIf set to true, creates a new schedule when no schedules with externalId, otherwise existing schedule is updated
False - by default
Schedule*ObjectContains schedule information
A timed planning/booking to take an assessment / exam
Schedule.AssessmentExtId*string (64)Alphanumeric Dashes
Schedule.Titlestring (100)Schedule title (will be generated if not set)
Schedule.ScheduleExtIdstring (64)Alphanumeric Dashes
Every time a new request is made to API this ScheduleExtID must be unique. If you provide a ScheduleExtID that was already passed or an error will occur “Bad request”.
Schedule.StartDateTime*DateTimeDateTime string representation according to RFC 3339
2021-04-21T07:30:00.000Z (UTC)
Schedule.EndDateTimeDateTimeDateTime string representation according to RFC 3339

2021-04-21T07:30:00.000Z (UTC)

If EndDateTime isn’t specified it will be calculated automatically as: SDT + Dur (duration of the assessment) + 60 min
the duration between scheduling startDate and endDate must be greater than duration of the assessment + any extra time. (See get assessment info > example "MaxTimePerAttempt": 120,"ExtraTime": 60.
Schedule.GroupExtId*string (64)Alphanumeric Dashes
When/if adding users, they will be added to the Hierarchy (group) in Cirrus
Schedule.GroupName*string (500)When/if adding users, they will be added to the Hierarchy Group title (name) in Cirrus
Schedule.ScheduleGroupExtIdstring (64)Hierarchy in Cirrus which will be attached to the schedule. If not set the schedule will be connected to the root hierarchy.
Schedule.ScheduleGroupNamestring (500)Group title (name) in Cirrus
Schedule.LockExamOnConnectionLossBooleantrue or false
Defines if the exam will be locked on connection loss
Schedule.Ownerstring (500)Schedule owner UserName. This field overrides Schedule owner from External API settings of Cirrus app. (Owner must be set in settings or in this field)
Schedule.PINstring (4)PIN for candidates
Schedule.UseProctorIobooleanDefines if exam should be integrated with Proctorio
If not provided, value from assessment options will be used
Schedule.ProctorioTemplateExternalIdstring (64)Alphanumeric. Defines which proctorio template will be used for this exam
If not provided. Default template will be used from global settings > Proctorio
Schedule.UseKeyCodebooleanTrue when logging in with a keycode, provided by an invigilator via the keycode slips. More info about keycode
Candidates*arrayContains an array of candidates to be scheduled
Candidates[].UserNamestring(500)If not set Candidate UserName = CandidateExtId
Candidates[].CandidateExtId*string (500)Alphanumeric Dashes
User ID in Cirrus
Candidates[].FirstName*string (500)First name user
Candidates[].LastName*string (500)Last name user
Candidates[].Email*string (500)A valid email
Candidates[].Passwordstring (500)If provided can be used for manual logging into system as candidate.

The password is salted, hashed and stored in database.
Candidates[].SpecialNeedsstring (500)true or false

Defines if a Candidate has special needs and requires extra time for schedule
Candidates[].ReasonableAdjustmentPercentageintSetup a % to add extra time, for example 20% on 60 min will result in 12 min extra time. Parameter can only be sent if SpecialNeeds=true
Candidates[].AttemptExtIdstring (500)This field is used for external scheduling logic

Required for EXTERNAL_ATTEMPT workflow
Cannot be used with DEFAULT workflow
Candidates[].Photostring (500)Any string
Candidates[].Companystring (500)Any string
Candidates[].Citystring (500)Any string
Candidates[].Statestring (500)Any string
Candidates[].CountryCodestring (500)Any string
Candidates[].PostalCodestring (500)Any string
Candidates[].AddressLine1string (500)Any string
Candidates[].AddressLine2string (500)Any string
Candidates[].PhoneNumberstring (500)Any string
Candidates[].RegistrationNumberstring (500)Any string
Candidates[].VoucherIdstring (500)Any string
Candidates[].CompIdstring (500)Any string
Candidates[].ProctorUIdsArray of strings["1235", "234"]

Sample Request URL

Simple Sample Request

  "Schedule": {
    "UseKeyCode": true
  "Candidates": [
        "SpecialNeeds": true,
       "ReasonableAdjustmentPercentage": 20

Extended Sample Request

  "Schedule": {
    "AssessmentExtId": "NORTH000",
    "ScheduleExtId": "WINTER000",
    "StartDateTime": "2015-04-21T07:30:00.000Z",
    "GroupExtId": "WINTERFELL",
    "GroupName": "Winterfell",
    "UseKeyCode": true
  "Candidates": [
       "CandidateExtId": "eddardstark",
       "FirstName": "Eddard",
       "LastName": "Stark",
       "RegNumber": "34394",
       "Photo": "-----",
       "Email": "",
       "Password": "WinterIsComing",
       "Photo": "",
       "RegistrationNumber": "3325",
       "CompId": "COMP00102006",
       "ProctorUIds": ["1235", "234"]
       "CandidateExtId": "catelynstark",
       "FirstName": "Catelyn",
       "LastName": "Stark",
       "Email": "",
       "RegistrationNumber": "3326",
       "CompId": "COMP00102006",
       "ProctorUIds": ["1235", "234"]
       "CandidateExtId": "johnsnow",
       "FirstName": "John",
       "LastName": "Snow",
       "Email": "",
       "RegistrationNumber": "3327",
       "CompId": "COMP00102006",
       "ProctorUIds": ["1235", "234"]

StartupLink - part of an URL for getting right into the exam.
LaunchUrl"- URL for exam with Proctorio

The format of the StartupLink is:
Example of LaunchUrl:

Example of StartupLink:

Sample Response

    "Content": "EXT_sch_1",
    "Success": true,
    "Errors": null    

Response codes

200Successful operation
403Not allowed to use external API
400Possible errors:
Invalid input data (all fields in message body are empty)
Schedule hasn't been found by external id
Can’t update activated schedule
Hierarchy hasn't been found by external id
Scheduler hasn’t been set in External API settings
Selected scheduler no longer has permission to create, update and delete schedules
Workflow can not be changed > A schedule is already available with a different workflow, either create new schedule or keep same workflow
249: ReasonableAdjustmentPercentage is invalid. Must be a value between 0 and 999
250: ReasonableAdjustmentPercentage cannot be set for candidate with SpecialNeeds = false
Hierarchy must be active
500Internal server error

Was this article helpful?