Create schedule and generate links

Updated on 17 Apr 2024
4 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

POST /schedule

Name	Data Type	Description
Content-type:	application/json	for all requests
Authorization:	EAPI {token}	for all requests

Request Parameters (for message body)

Parameters indicated with a * are mandatory

Name	Data Type	Description
Workflow	String[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.
Upsert	Boolean	If set to true, creates a new schedule when no schedules with externalId, otherwise existing schedule is updated False - by default
Schedule*	Object	Contains schedule information A timed planning/booking to take an assessment / exam
Schedule.AssessmentExtId*	string (64)	Alphanumeric Dashes
Schedule.Title	string (100)	Schedule title (will be generated if not set)
Schedule.ScheduleExtId	string (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*	DateTime	DateTime string representation according to RFC 3339 2021-04-21T07:30:00.000Z (UTC)
Schedule.EndDateTime	DateTime	DateTime 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.ScheduleGroupExtId	string (64)	Hierarchy in Cirrus which will be attached to the schedule. If not set the schedule will be connected to the root hierarchy.
Schedule.ScheduleGroupName	string (500)	Group title (name) in Cirrus
Schedule.LockExamOnConnectionLoss	Boolean	true or false Defines if the exam will be locked on connection loss
Schedule.Owner	string (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.PIN	string (4)	PIN for candidates
Schedule.UseProctorIo	boolean	Defines if exam should be integrated with Proctorio If not provided, value from assessment options will be used
Schedule.ProctorioTemplateExternalId	string (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.UseKeyCode	boolean	True when logging in with a keycode, provided by an invigilator via the keycode slips. More info about keycode
Candidates*	array	Contains an array of candidates to be scheduled
Candidates[].UserName	string(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[].Password	string (500)	If provided can be used for manual logging into system as candidate. The password is salted, hashed and stored in database.
Candidates[].SpecialNeeds	string (500)	true or false Defines if a Candidate has special needs and requires extra time for schedule
Candidates[].ReasonableAdjustmentPercentage	int	Setup 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[].AttemptExtId	string (500)	This field is used for external scheduling logic Required for EXTERNAL_ATTEMPT workflow Cannot be used with DEFAULT workflow
Candidates[].Photo	string (500)	Any string
Candidates[].Company	string (500)	Any string
Candidates[].City	string (500)	Any string
Candidates[].State	string (500)	Any string
Candidates[].CountryCode	string (500)	Any string
Candidates[].PostalCode	string (500)	Any string
Candidates[].AddressLine1	string (500)	Any string
Candidates[].AddressLine2	string (500)	Any string
Candidates[].PhoneNumber	string (500)	Any string
Candidates[].RegistrationNumber	string (500)	Any string
Candidates[].VoucherId	string (500)	Any string
Candidates[].CompId	string (500)	Any string
Candidates[].ProctorUIds	Array of strings	["1235", "234"]

Sample Request URL

https://api.cirrusplatform.com/api/v1/integrations/schedule

Simple Sample Request

{
  "Schedule": {
   "AssessmentExtId":"1111", 
   "ScheduleExtId":"sch1111",
   "StartDateTime":"2018-11-02T15:30:00Z", 
   "GroupExtId":"CPI", 
   "GroupName":"ComputerInc",
    "UseKeyCode": true
  }, 
  "Candidates": [
    {
        "CandidateExtId":"ddmwhite", 
        "FirstName":"Dima", 
        "LastName":"White", 
        "Email":"ddmwhite@winterfell.com",
        "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": "estark@winterfell.com",
       "Password": "WinterIsComing",
       "Photo": "https://secure.skypeassets.com/content/dam/scom/images/newhome/promo2.jpg",
       "RegistrationNumber": "3325",
       "CompId": "COMP00102006",
       "ProctorUIds": ["1235", "234"]
    },
    {
       "CandidateExtId": "catelynstark",
       "FirstName": "Catelyn",
       "LastName": "Stark",
       "Email": "cstark@winterfell.com",
       "RegistrationNumber": "3326",
       "CompId": "COMP00102006",
       "ProctorUIds": ["1235", "234"]
    },
    {
       "CandidateExtId": "johnsnow",
       "FirstName": "John",
       "LastName": "Snow",
       "Email": "jsnow@winterfell.com",
       "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:
https://{siteName}.cirrusplatform.com/delivery/external-login?session={accessToken}
Example of LaunchUrl:
"https://getproctorio.com?d603645bf7d642a6bcc240f98694c4c9%2Ch%2BUid22fX%2B1hSQWQzrQa5g%3D%3D%2CjZM0CPcQq5Ab3282oUPjPDETBdzqe0Htay%2BgT4MxTET31sXSxRRFer0DYYoaKkOS4qGyEG0XPSVwRFfkHCJRpG4jLJ63FgafIpSHDmGorjfmqq%2FO3xsrpSz%2FT9kTl8TK%2F6eDyl2QwE1r4zATT64C7YPtpu3KZL2LepKwddK8AC5hBQtTdjzMWYVNXy5zoIAOR1zwtWPUYKqp0v5zWC%2BVpCOXZBf1MOpan6AevI%2BJzdPxXWzWQrDXqQlkRrlTCXQtmc4M17uQyqSEgijh0tUBI%2F7MeV28slm48uq9QTl2%2BzmFO9wxiTkGKbC1dGur3Fk0aHb9CKjNXo0aBven4ZIXlDxkunkLnH6%2F6AnNzdY%2BBMzygQAmHIjmA9eiOuOi0W%2BFWQwh5Ya3iOpj7K3EpjshQlzdp1%2FcYzwzr09uhhM1NunUbWgHU2cbJ5fqIgxPJz%2F2BDk%2BrulXSfsLcopZ9jFu8K%2BUBVEC%2Fh0TPWCqEIai5DwamRlo2CrHCAVGw3lPvax8Jjfya08da0o4ishFQkP2pWgtVXQ42F%2BX7yOZ0K2h9lSiSlvMD%2F7CfbKiwgkPor7lQMDcB%2FoaTiptk13gpB3ArWSyq5vzKoTe%2BiCGLNgtxP5wwwq0oqQc5BdMRJcTnjb6CSivQU7LMvsigT7BvGAK1WfS9%2BtUGeUBfmWpdyt7DzOPwiaRJuM2gtPvNZYpjP8XxJ7frOLcMl3oslUtQlA%2BFSTVQH%2BtWxH4Bb2sJM99roDUhy7LePr5iY7vhqnbyS8TGQHnOKlG3gOOxBa%2F1ygC8GvcXyP3UNS2aH6eIKTA%2FhDBtEk9FlQFBKQIBfIoz2TLV8EaJrhgeV9f2NsNOag5%2BKj%2BLyUlewKhNTKwOoY4aoU%3D#proctorio-24-03-1",

Example of StartupLink:
https://demo.cirrusplatform.com/delivery/external-login?session=2B5D59A9138B4382AF7799C62901EBB5F58317D64F354692AA7276E559D55C91

Sample Response

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

Response codes

Code	Description
200	Successful operation
403	Not allowed to use external API
400	Possible 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
500	Internal server error

Was this article helpful?

What's Next

Create Non published schedule

Table of contents

Header
Request Parameters (for message body)
Sample Request URL
Simple Sample Request
Extended Sample Request
Sample Response
Response codes