Create schedule and generate links

  • Updated on Apr 17, 2024
  • Published on Jun 30, 2021
  • 4 minute(s) read
  • Jeroen Habets
 Prev Next
POST /schedule

Header

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