Navbar

Overview

Welcome to the Measure API Reference!

Things you should know before getting started:

  • The API is organized around REST.
  • All requests should be made over SSL.
  • All request and response bodies, including errors, are encoded in JSON.
    • You still require the Content-Type header to be set to application/json
  • Follow ISO 8601 format for timestamps.

Authentication

Authentication is accomplished via an API key. If you’re a Site Owner, you can view the Account API Token under the Settings tab.

Response Format

All responses are returned using JSON. JSON, or JavaScript Object Notation, allows us to access collections of data in a human-readable way. Plus, it’s easy for machines to parse and generate. Win-win.

Webhooks

Yardstick Measure allows you to export information as it happens via a series of Webhooks. Webhooks can be defined in Measure’s Administration Portal under the Settings tab and then by selecting WebHooks in the following submenu.

Here you can define a URL to send the relevant infomration to. Then everytime something relevant (to the selected record type) occurs - Yardstick Measure will send a POST request to the configured URL. Example payloads for each record type can be found in their relevant sections below.

Errors

Our API returns standard HTTP success or error status codes. For errors, we include a short explanation about what went wrong in the JSON response. The various HTTP status codes you may encounter while using the Measure API are listed below.

HTTP Status Codes

Code Title Description
200 OK The request was successful
201 Created The resource was successfully created
202 Async created The resource was asynchronously created
400 Bad request Bad request
401 Unauthorized Your API key is invalid
404 Not found The resource does not exist
405 Not allowed You made an unsupported request (for example, using GET for an action requiring POST)
422 Validation error A validation error occurred
50# Internal server error An error occurred within our API

Error Response

Example error response

  {
    "error": "user is required but not specified"
  }

All errors are returned in the form of JSON with a message explaining why the error occurred.

A Typical Integration

Below is a diagram of our most standard integration scenarios. Most if not all integrations use at least the following workflow.

(Click image for fullsize version.)

Single Sign-On

WS-Federation

In order to configure your Measure site to allow candidates to sign in through your WS-Fed Identity Provider you will to configure Measure with the following:

  • ID Claim
  • Certificate Fingerprint
  • Endpoint (URL)
  • Certificate Issuer

You can configure this in Measure’s Administrator portal under the Settings tab, followed by the Single Sign On sub-tab. If the Single Sign On tab is not available please contact our customer support team.

Measure expects the following attributes to be passed through the WSFed payload. All of the below fields are required. We do not currently support passing any attributes beyond what is found in the following table.

Parameter Measure Expected Name
User Name uid
Email email
First Name givenname
Last Name surname

Yardstick Custom SSO

Details coming soon. Refer to our old API docs for now.

Sites

Index Sites

Get a list of sites associated with your api token.

Example response

[
    {
        "unlock_url": "https://beta.ysasecure.com/proctors/unlock/{your token}",
        "name": "Measure Demo",
        "domain": "https://measure-demo.ysasecure.com",
        "short_name": "measure-demo",
        "id": 0
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/sites

HTTP Get Params

Parameter Description
token
string
Your Measure API token

Who Am I

Self

Example response

{
    "first_name": "Demo",
    "klass": "AdminUser",
    "roles": [
        "super",
        "exam_editor"
    ],
    "account_id": 1,
    "email": "demo@getyardstick.com",
    "id": 51,
    "last_name": "User"
}

HTTP Request

GET https://api.ysasecure.com/v2/whoami

HTTP Get Params

Parameter Description
token
string
Your Measure API token

Admin Users

Returns the user information for the owner of the API token.

Example response

{
    "first_name": "Demo",
    "roles": [
        "super",
        "exam_editor"
    ],
    "account_id": 1,
    "email": "demo@getyardstick.com",
    "id": 51,
    "last_name": "User"
}

HTTP Request

GET https://api.ysasecure.com/v2/admin_users/whoami

HTTP Get Params

Parameter Description
token
string
Your Measure API token

Nomad Users

Returns the user information for the owner of the API token.

Example response

{
    "first_name": "Demo",
    "roles": [
        "super",
        "exam_editor"
    ],
    "account_id": 1,
    "email": "demo@getyardstick.com",
    "id": 51,
    "last_name": "User"
}

HTTP Request

GET https://api.ysasecure.com/v2/nomad_users/whoami

HTTP Get Params

Parameter Description
token
string
Your Measure API token

Exam Form Assignments

Example Response

[
    {
        "exam": {
            "name": "Tutorial",
            "id": 1089
        },
        "exam_id": 1089,
        "name": "Tutorial Form",
        "id": 2102
    },
    {
        "exam": {
            "name": "Demo Exam",
            "id": 3033
        },
        "exam_id": 3033,
        "name": "Form 1",
        "id": 8867
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/whoami/exam_form_assignments

HTTP Get Params

Parameter Description
token
string
Your Measure API token
administration_id
integer, optional
ID number of the administration associated with an exam form assignment

Auths

Token

Returns the API token associated with an account.

Example response

{
    "token": "YOUR TOKEN"
}

HTTP Request

PUT https://api.ysasecure.com/v2/auth/token

HTTP Put Params

Parameter Description
email
string
Your email
password
string
Your password
roles
array, optional
User roles

Proctoring

Returns the API token associated with a proctoring account.

Example response

{
    "token": "YOUR TOKEN"
}

If the email/password combination is incorrect, you will receive a 401 Unauthorized error.

{
    "error": "Invalid email/password combination"
}

HTTP Request

PUT https://api.ysasecure.com/v2/auth/proctoring

HTTP Put Params

Parameter Description
email
string
Your email
password
string
Your password
roles
array, optional
User roles

Nomad Users

Example response

{
    "token": "YOUR TOKEN"
}

If the email/password combination is incorrect, you will receive a 401 Unauthorized error.

{
    "error": "Invalid email/password combination"
}

HTTP Request

PUT https://api.ysasecure.com/v2/nomad_users/auth

HTTP Put Params

Parameter Description
email
string
Your email
password
string
Your password

Users

You can manage candidate records for your site remotely using this endpoint.

Create User

Example response

{
    "first_name": null,
    "alternate_email": null,
    "username": "testuser",
    "created_at": "2017-06-19T20:17:21Z",
    "active": true,
    "deleted_at": null,
    "email_verified": false,
    "metadata": {},
    "updated_at": "2017-06-19T20:17:21Z",
    "email": null,
    "address": null,
    "user_groups": [],
    "preferred_language": "en",
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": null,
    "site_id": 19
}

Create a new user. Returns a location header indicating where the created user’s details can be found.

HTTP Request

POST https://api.ysasecure.com/v2/users

HTTP Post Params

Parameter Description Default
token
string
Your API token
user[username]
string
The login username to be created
user[site_id]
integer
Your Measure site ID
user[first_name]
string, optional
First name of the new user
user[last_name]
string, optional
Last name of the new user
user[email]
string, optional
Email address for the new user
user[alternate_email]
string, optional
Alternate email for the new user (incase they lose access to their account)
user[address_attributes][address1]
string
Street address
user[address_attributes][address2]
string, optional
Secondary street address input (for apartment unit number, etc)
user[address_attributes][city]
string
City
user[address_attributes][province]
string, optional
Province or state
user[address_attributes][country]
string
Country
user[address_attributes][postal_code]
string, optional
Postal code or zip code
user[metadata]
object, optional
Additional metadata to include with the new user
user[preferred_language]
string, optional
Locale string for the user’s preferred language
send_email
boolean, optional
Whether or not to send the user a confirmation email upon creation true

Show User

Example Response

{
    "email_verified": false,
    "first_name": null,
    "username": "testuser",
    "created_at": "2017-06-19T20:17:21Z",
    "active": true,
    "deleted_at": null,
    "alternate_email": null,
    "metadata": {},
    "user_groups": [],
    "updated_at": "2017-06-19T20:17:21Z",
    "email": null,
    "address": null,
    "preferred_language": "en",
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": null,
    "site_id": 19
}

HTTP Request

GET https://api.ysasecure.com/v2/users/<user id>

HTTP Get Parameters

Parameter Description
user id
integer
The Measure User ID of the user whose information you want to retrieve
token
string
Your Measure API token

Update User

Example response after changing the demo user’s first name, last name, and email

{
    "deleted_at": null,
    "first_name": "Demo",
    "email_verified": false,
    "alternate_email": null,
    "preferred_language": "en",
    "username": "testuser",
    "created_at": "2017-06-19T20:17:21Z",
    "active": true,
    "metadata": {},
    "updated_at": "2017-06-19T20:30:07Z",
    "email": "testemail@getyardstick.com",
    "address": null,
    "user_groups": [],
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": "User",
    "site_id": 19
}

HTTP Request

PUT https://api.ysasecure.com/v2/users/<user id>

HTTP Put Parameters

Parameter Description
token
string
Your Measure API token
user id
integer
The Measure User ID of the user whose information you want to update
user[username]
string, optional
The new username you’d like to assign the user
user[first_name]
string, optional
The new first name for the user
user[last_name]
string, optional
The new last name for the user
user[email]
string, optional
The new email for the user
user[alternate_email]
string, optional
The new alternate email for the user
user[address_attributes][address1]
string
Street address
user[address_attributes][address2]
string, optional
Secondary street address input (for apartment unit number, etc)
user[address_attributes][city]
string
City
user[address_attributes][province]
string, optional
Province or state
user[address_attributes][country]
string
Country
user[address_attributes][postal_code]
string, optional
Postal code or zip code
user[metadata]
object, optional
Additional metadata you want to update for this user
user[preferred_language]
string, optional
Locale string for the user’s new preferred language

Destroy User

Example response

{
    "deleted_at": "2017-06-19T20:32:56Z",
    "first_name": "Demo",
    "email_verified": false,
    "alternate_email": null,
    "preferred_language": "en",
    "username": "testuser",
    "created_at": "2017-06-19T20:17:21Z",
    "active": true,
    "metadata": {},
    "updated_at": "2017-06-19T20:32:56Z",
    "email": "testemail@getyardstick.com",
    "address": null,
    "user_groups": [],
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": "User",
    "site_id": 19
}

HTTP Request

DELETE https://api.ysasecure.com/v2/users/<user id>

HTTP Delete Parameters

Parameter Description
user id
integer
The Measure User ID of the user you want to delete
token
string
Your Measure API token

Admin Users Index

HTTP Request

GET https://api.ysasecure.com/v2/admin_users

HTTP Get Params

Parameter Description
token
string
Your Measure API token
roles
roles
List of roles

Grants

You can provide a candidate access to a specific exam via a grant in Measure. Other systems sometimes refer to this as an “eligibility record”.

Index Grants

List all grants belonging to a particular user.

Example response

[
    {
        "type": "ExamGrant",
        "user_id": 544,
        "deleted_at": null,
        "created_at": "2017-06-19T21:33:54Z",
        "grantable_id": 30,
        "remaining_uses": null,
        "attempts_count": 0,
        "grantable_type": "Exam",
        "exam": {
            "marking_deadline_in_days": 0,
            "metadata": {},
            "name": "Demo Exam",
            "id": 30
        },
        "exam_form_group": "active",
        "metadata": {},
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://measure-demo.ysasecure.com/grants/108/bookings/new"
        },
        "updated_at": "2017-06-19T21:33:54Z",
        "expire_at": null,
        "num_uses": null,
        "allow_sittings_start_at": null,
        "exam_form_id": 88,
        "start_at": "2017-06-19T21:33:54Z",
        "parent_grant_id": null,
        "id": 10886,
        "exam_form": {
            "deleted_at": null,
            "created_at": "2017-01-25T14:56:29Z",
            "active": true,
            "updated_at": "2017-01-25T14:56:29Z",
            "name": "Form 1",
            "id": 88
        },
        "allow_sittings_end_at": null,
        "user": {
            "first_name": null,
            "alternate_email": null,
            "preferred_language": "en",
            "username": "testuser",
            "deleted_at": null,
            "created_at": "2017-06-19T21:30:09Z",
            "active": true,
            "user_groups": [],
            "metadata": {},
            "updated_at": "2017-06-19T21:30:09Z",
            "email_verified": false,
            "email": null,
            "address": null,
            "alternate_email_verified": false,
            "id": 544,
            "last_name": null,
            "site_id": 0
        }
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/users/<user id>/grants

HTTP Get Params

Parameter Description
user id
integer
The ID of the user whose grants you’re trying to request
token
string
Your Measure API token

Show Grant

Retrieve a single grant from a user.

Example response

[
    {
        "type": "ExamGrant",
        "user_id": 544,
        "deleted_at": null,
        "created_at": "2017-06-19T21:33:54Z",
        "grantable_id": 30,
        "remaining_uses": null,
        "attempts_count": 0,
        "grantable_type": "Exam",
        "exam": {
            "marking_deadline_in_days": 0,
            "metadata": {},
            "name": "Demo Exam",
            "id": 30
        },
        "exam_form_group": "active",
        "metadata": {},
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://measure-demo.ysasecure.com/grants/108/bookings/new"
        },
        "updated_at": "2017-06-19T21:33:54Z",
        "expire_at": null,
        "num_uses": null,
        "allow_sittings_start_at": null,
        "exam_form_id": 88,
        "start_at": "2017-06-19T21:33:54Z",
        "parent_grant_id": null,
        "id": 10886,
        "exam_form": {
            "deleted_at": null,
            "created_at": "2017-01-25T14:56:29Z",
            "active": true,
            "updated_at": "2017-01-25T14:56:29Z",
            "name": "Form 1",
            "id": 88
        },
        "allow_sittings_end_at": null,
        "user": {
            "first_name": null,
            "alternate_email": null,
            "preferred_language": "en",
            "username": "testuser",
            "deleted_at": null,
            "created_at": "2017-06-19T21:30:09Z",
            "active": true,
            "user_groups": [],
            "metadata": {},
            "updated_at": "2017-06-19T21:30:09Z",
            "email_verified": false,
            "email": null,
            "address": null,
            "alternate_email_verified": false,
            "id": 544,
            "last_name": null,
            "site_id": 0
        }
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/users/<user_id>/grants/<grant id>

HTTP Get Params

Parameter Description
user id
integer
The user that the grant belongs to
grant id
integer
The ID of the grant you’re requesting
token
string
Your Measure API token

Activate a grant’s exam form group

Activate or deactivate the exam form group.

Example response when exam_form_group is set as inactive

{
    "exam_form_id": 88,
    "type": "ExamGrant",
    "user_id": 544,
    "exam_launch_status": {
        "status": "requires_booking",
        "launch_url": "https://beta.ysasecure.com/grants/108/bookings/new"
    },
    "exam": {
        "metadata": {},
        "name": "Exam",
        "marking_deadline_in_days": 0,
        "id": 30
    },
    "user": {
        "email_verified": false,
        "first_name": null,
        "user_groups": [],
        "username": "testuser",
        "created_at": "2017-06-19T21:30:09Z",
        "active": true,
        "deleted_at": null,
        "metadata": {},
        "updated_at": "2017-06-19T21:30:09Z",
        "email": null,
        "address": null,
        "preferred_language": "en",
        "alternate_email_verified": false,
        "id": 544,
        "alternate_email": null,
        "last_name": null,
        "site_id": 19
    },
    "created_at": "2017-06-19T21:33:54Z",
    "grantable_id": 30,
    "attempts_count": 0,
    "allow_sittings_start_at": null,
    "deleted_at": null,
    "grantable_type": "Exam",
    "exam_form": {
        "created_at": "2017-01-25T14:56:29Z",
        "active": true,
        "deleted_at": null,
        "updated_at": "2017-01-25T14:56:29Z",
        "name": "Form 1",
        "id": 88
    },
    "metadata": {},
    "allow_sittings_end_at": null,
    "updated_at": "2017-06-19T22:11:26Z",
    "expire_at": null,
    "num_uses": null,
    "exam_form_group": "inactive",
    "start_at": "2017-06-19T21:33:54Z",
    "parent_grant_id": null,
    "id": 10886,
    "remaining_uses": null
}

HTTP Request

PUT https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>/set_form

HTTP Put Params

Parameter Description
token
string
Your API token
user id
integer
The user that the grant belongs to
grant id
integer
The ID of the grant you’re requesting
which
string
Status you wish to set the exam form group to. Either “active” or “inactive” are accepted here.

Create grant

Grant an exam to a candidate.

Example response

[
    {
        "allow_sittings_start_at": null,
        "num_uses": 2,
        "type": "ExamGrant",
        "user_id": 544,
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
        },
        "exam_form": null,
        "allow_sittings_end_at": null,
        "parent_grant_id": null,
        "user": {
            "first_name": null,
            "username": "testuser",
            "created_at": "2017-06-19T21:30:09Z",
            "user_groups": [],
            "alternate_email_verified": false,
            "active": true,
            "metadata": {},
            "updated_at": "2017-06-19T21:30:09Z",
            "email_verified": false,
            "email": null,
            "address": null,
            "preferred_language": "en",
            "id": 544,
            "deleted_at": null,
            "alternate_email": null,
            "last_name": null,
            "site_id": 0
        },
        "exam_form_group": "active",
        "created_at": "2017-06-22T20:45:44Z",
        "exam": {
            "marking_deadline_in_days": 0,
            "metadata": {},
            "name": "Demo Exam",
            "id": 30
        },
        "exam_form_id": null,
        "metadata": {},
        "updated_at": "2017-06-22T20:45:44Z",
        "expire_at": null,
        "grantable_id": 30,
        "attempts_count": 0,
        "remaining_uses": 2,
        "start_at": "2017-06-22T14:45:44-06:00",
        "grantable_type": "Exam",
        "id": 109,
        "deleted_at": null
    }
]

HTTP Request

POST https://api.ysasecure.com/v2/users/<user id>/grants

HTTP Post Params

Parameter Description Default
user id
integer
The user that the grant will belong to
token
string
Your Measure API token
grantable[id]
integer, optional
Measure’s Exam/Course ID
grantable[partner_id]
string, optional
Your configured Partner ID
grantable[site_id]
integer, optional
Site ID associated with the grantable[partner_id]
grantable[type]
string
Either “Exam” or “Edition”
grant[num_uses]
integer
Number of attempts the candidate is allowed
grant[start_at]
time with zone, optional
Exams will be available from this time
grant[expire_at]
time with zone, optional
Exams will not be available after this date
grant[allow_sittings_start_at]
time with zone, optional
Only allow booking into sessions starting after the given time
grant[allow_sittings_end_at]
time with zone, optional
Only allow booking into sessions starting before the given time
grant[time_zone_name]
timezone, optional
Time zone that the grant is being assigned within
grant[exam_form_id]
string, optional
Measure’s Exam Form ID (if you want to grant a specific form)
grant[metadata]
object, optional
Any additional meta data you’d like to include
grant[send_email]
boolean, optional
Whether to send an email to the user or not upon creation true
grant[exam_form_group]
string, optional
Either active, inactive, or unknown (default) - corresponds to selecting active or inactive forms on an exam. unknown

Update Grant

Update a grant.

Example response

{
    "type": "ExamGrant",
    "user_id": 544,
    "exam": {
        "metadata": {},
        "marking_deadline_in_days": 0,
        "name": "Demo Exam",
        "id": 30
    },
    "exam_form_id": null,
    "user": {
        "first_name": null,
        "username": "testuser",
        "created_at": "2017-06-19T21:30:09Z",
        "alternate_email_verified": false,
        "active": true,
        "email_verified": false,
        "metadata": {},
        "deleted_at": null,
        "updated_at": "2017-06-19T21:30:09Z",
        "alternate_email": null,
        "email": null,
        "address": null,
        "preferred_language": "en",
        "id": 544,
        "user_groups": [],
        "last_name": null,
        "site_id": 0
    },
    "parent_grant_id": null,
    "created_at": "2017-06-22T20:45:44Z",
    "allow_sittings_start_at": null,
    "metadata": {},
    "remaining_uses": 3,
    "exam_form": null,
    "allow_sittings_end_at": null,
    "deleted_at": null,
    "updated_at": "2017-06-22T20:59:23Z",
    "expire_at": null,
    "grantable_id": 30,
    "attempts_count": 0,
    "exam_form_group": "active",
    "start_at": "2017-06-22T20:45:44Z",
    "grantable_type": "Exam",
    "num_uses": 3,
    "id": 109,
    "exam_launch_status": {
        "status": "requires_booking",
        "launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
    }
}

HTTP Request

PUT https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>,

HTTP Put Params

Parameter Description
token
string
Your Measure API token
user id
integer
The user that the grant you’re updating belongs to
grant id
integer
The ID of the grant you are updating
grant[num_uses]
integer, optional
Number of attempts the candidate is allowed
grant[start_at]
time with zone, optional
Exams will be available from this time
grant[expire_at]
time with zone, optional
Exams will not be available after this date
grant[allow_sittings_start_at]
time with zone, optional
Only allow booking into sessions starting after the given time
grant[allow_sittings_end_at]
time with zone, optional
Only allow booking into sessions starting before the given time
grant[time_zone_name]
timezone, optional
Time zone that the grant is being assigned within
grant[exam_form_id]
string, optional
Measure’s Exam Form ID (if you want to grant a specific form)
grant[exam_form_group]
string, optional
Either active, inactive, or unknown (default) - corresponds to selecting active or inactive forms on an exam.

Destroy Grant

Delete a grant.

Example response

{
    "type": "ExamGrant",
    "user_id": 544,
    "allow_sittings_start_at": null,
    "parent_grant_id": null,
    "exam_launch_status": {
        "status": "requires_booking",
        "launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
    },
    "exam_form": null,
    "allow_sittings_end_at": null,
    "created_at": "2017-06-22T20:45:44Z",
    "num_uses": 3,
    "user": {
        "first_name": null,
        "preferred_language": "en",
        "username": "aleciatest2",
        "created_at": "2017-06-19T21:30:09Z",
        "user_groups": [],
        "alternate_email_verified": false,
        "email_verified": false,
        "active": true,
        "alternate_email": null,
        "deleted_at": null,
        "metadata": {},
        "updated_at": "2017-06-19T21:30:09Z",
        "email": null,
        "address": null,
        "id": 544,
        "last_name": null,
        "site_id": 0
    },
    "deleted_at": "2017-06-22T21:04:05Z",
    "metadata": {},
    "updated_at": "2017-06-22T21:04:05Z",
    "expire_at": null,
    "grantable_id": 30,
    "attempts_count": 0,
    "remaining_uses": 3,
    "exam_form_id": null,
    "start_at": "2017-06-22T20:45:44Z",
    "grantable_type": "Exam",
    "id": 109,
    "exam": {
        "marking_deadline_in_days": 0,
        "metadata": {},
        "name": "Demo Exam",
        "id": 30
    },
    "exam_form_group": "active"
}

HTTP Request

DELETE https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>

HTTP Delete Params

Parameter Description
user id
integer
The user whose grants you would like to delete
grant id
integer
The ID of the grant to delete
token
string
Your Measure API token

Complete Grant Status

Example response

{
    "user_id": 544,
    "status": null,
    "exam_url": null,
    "id": 109,
    "writable": false
}

HTTP Request

PUT https://api.ysasecure.com/v2/grant_status/<grant id>/complete

HTTP Put Params

Parameter Description
grant id
string
The ID of the grant to change
token
string
Your Measure API token
grant_status[status]
string, optional
Status note field

Force Terminate Grant Status

Example response

{
    "user_id": 544,
    "status": null,
    "exam_url": null,
    "id": 109,
    "writable": false
}

HTTP Request

PUT https://api.ysasecure.com/v2/grant_status/<grant id>/force_terminate

HTTP Put Params

Parameter Description
grant id
integer
The ID of the grant to force terminate
token
string
Your Measure API token
grant_status[status]
string, optional
Status note field

Show Grant Status

Example response

{
    "status": null,
    "exam_url": null,
    "id": 109,
    "writable": false
}

HTTP Request

GET https://api.ysasecure.com/v2/grant_status/<grant id>

HTTP Get Params

Parameter Description
grant id
integer
The ID of the grant to check the status of
token
string
Your Measure API token

Update Grant Status

Response after setting the status to “active”

{
    "user_id": 544,
    "status": "active",
    "exam_url": null,
    "id": 109,
    "writable": false
}

HTTP Request

PUT https://api.ysasecure.com/v2/grant_status/<grant id>

HTTP Put Params

Parameter Description
grant id
integer
The ID of the grant to update
token
string
Your Measure API token
grant_status[status]
string, optional
Status note field

Exams

Exams are comprised of Exam Forms.

Index Exams

Retrieve a list of current exams.

Example response, without forms

[
    {
        "active": true,
        "available_for_online": true,
        "name": "Exam 1",
        "id": 74,
        "marking_deadline_in_days": 0,
        "available_for_paper": false
    },
    {
        "active": true,
        "available_for_online": true,
        "name": "Exam 2",
        "id": 10,
        "marking_deadline_in_days": 0,
        "available_for_paper": false
    }
]

Example response, with forms

[
  {
        "exam_forms": [
            {
                "locked": false,
                "exam_id": 74,
                "name": "Tutorial",
                "id": 21
            }
        ],
        "active": true,
        "available_for_online": true,
        "name": "Exam 1",
        "id": 74,
        "marking_deadline_in_days": 0,
        "available_for_paper": false
    },
    {
        "exam_forms": [
            {
                "locked": false,
                "exam_id": 10,
                "name": "Demonstration",
                "id": 31
            }
        ],
        "active": true,
        "available_for_online": true,
        "name": "Exam 2",
        "id": 10,
        "marking_deadline_in_days": 0,
        "available_for_paper": false
    },
]

HTTP Request

GET https://api.ysasecure.com/v2/exams

HTTP Get Params

Parameter Description Default
token
string
Your Measure API token
administration_id
integer, optional
Filter by administration ID associated with the Exams to return
include_forms
boolean, optional
If true, include forms in the retrieved list false
available_online
boolean, optional
If true, retrieve only Exams that are available online false
available_on_paper
boolean, optional
If true, retrieve only Exams that are available on paper false
active
boolean, optional
If true, retrieve only Exams that are active false

Exam Forms

Comprised of several User Exam Questions.

Index Exam Forms

Retrieve a list of exam forms

Example response

[
    {
        "markers": [],
        "exam_id": 17,
        "name": "Demo 1",
        "id": 10
    },
    {
        "markers": [],
        "exam_id": 15,
        "name": "Demo 2",
        "id": 28
    },
    {
        "markers": [],
        "exam_id": 13,
        "name": "Demo 3",
        "id": 24
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/exam_forms

HTTP Get Params

Parameter Description
token
string
Your Measure API token

User Exams

Whenever a User writes an Exam, a User Exam record is created. User Exams contain User Exam Questions.

Index User Exams

Example Response

[
    {
        "user_id": 1441,
        "exam_form_id": 70,
        "exam_id": 70,
        "paths": {
            "user_exam_questions": "/v2/user_exams/1457/user_exam_questions"
        },
        "finished_at": "2011-01-14T18:48:05Z",
        "id": 1457
    },
    {
        "user_id": 1423,
        "exam_form_id": 70,
        "exam_id": 70,
        "paths": {
            "user_exam_questions": "/v2/user_exams/1463/user_exam_questions"
        },
        "finished_at": "2011-01-14T22:26:49Z",
        "id": 1463
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/user_exams

HTTP Get Params

Parameter Description Default
token
string
Your Measure API token
limit
integer, optional
Maximum number of user exams to return 25
marker
boolean, optional
Whether to return exams with only automatically graded questions false
with_manually_graded_questions
boolean, optional
Whether to return exams with manually graded questions false
except
integer array, optional
Array of user exam IDs to leave out of response
administration_id
integer, optional
Filter by administration ID associated with the user exams to return
passage_id
integer, optional
Filter by passage ID associated with the user exams to return
exam_id
integer, optional
Filter by exam ID associated with the user exams to return
exam_form_id
integer, optional
Filter by exam form ID associated with the user exams to return
include_user
boolean, optional
Whether to include the user in the user exams that will be returned false
only_finished
boolean, optional
Whether to return only finished user exams true
user_id
integer, optional
User ID to filter user exams by
asc
boolean, optional
Whether sort direction is ascending or not true

Count User Exams

Example Response

{
    "count": 15
}

HTTP Request

GET https://api.ysasecure.com/v2/user_exams/count

HTTP Get Params

Parameter Description Default
token
string
Your Measure API token
limit
integer, optional
Maximum number of user exams to return 25
with_manually_graded_questions
boolean, optional
Whether to return exams with manually graded questions false
except
integer array, optional
Array of user exam IDs to leave out of response
administration_id
integer, optional
Filter by administration ID associated with the user exams to return
passage_id
integer, optional
Filter by passage ID associated with the user exams to return
exam_id
integer, optional
Filter by exam ID associated with the user exams to return
exam_form_id
integer, optional
Filter by exam form ID associated with the user exams to return
include_user
boolean, optional
Whether to include the user in the user exams that will be returned false
only_finished
boolean, optional
Whether to return only finished user exams true
user_id
integer, optional
User ID to filter user exams by
asc
boolean, optional
Whether sort direction is ascending or not true
group_strategy
string, optional
If “due dates” is entered, response will be grouped by due date

Webhooks

Example Payload UserExam

{
    "booked": true,
    "results": {
        "passed": true,
        "marking_complete": true,
        "finished_at": "2015-05-11T20:57:45Z",
        "answered": 2,
        "finished": "2015-05-11T20:57:45Z",
        "elapsed": 0,
        "points": 21,
        "time_elapsed_in_seconds": 0,
        "correct": 0,
        "started": "2015-05-11T20:57:27Z",
        "global_attempt_number": 1,
        "incorrect": 2,
        "total_points": 30,
        "started_at": "2015-05-11T20:57:27Z",
        "equated_points": null,
        "score": 70,
        "scaled_points": null,
        "attempt_number": 1,
        "equated_score": null,
        "skipped": 0
    },
    "proctor": {
        "deleted_at": null,
        "first_name": "Demo",
        "created_at": "2013-10-02T15:44:55Z",
        "email": "demoproctor@getyardstick.com",
        "last_name": "Proctor",
        "updated_at": "2017-10-13T20:07:30Z",
        "id": 599
    },
    "finished_at": "2015-05-11T20:57:45Z",
    "parts": [
        {
            "break_length_in_minutes": null,
            "finished_at": "2015-05-11T20:57:45Z",
            "time_elapsed_in_seconds": 0,
            "number_of_questions": 2,
            "started_at": "2015-05-11T20:57:28Z",
            "time_limit_in_minutes": 0
        }
    ],
    "user": {
        "display_name": "Demo User",
        "alternate_email": null,
        "user_name": "demo.user",
        "active": true,
        "deleted_at": null,
        "preferred_language": "en",
        "first_name": "Demo",
        "metadata": {},
        "email_verified": false,
        "address": null,
        "created_at": "2013-09-02T02:36:20Z",
        "username": "demo.user",
        "alternate_email_verified": false,
        "email": "demo.user@getyardstick.com",
        "last_name": "User",
        "full_name": "Demo User",
        "updated_at": "2015-05-11T21:00:03Z",
        "id": 247441
    },
    "sitting": {
        "begin_booking_at": null,
        "venue_tbd": false,
        "session_type": "exam",
        "require_purchase_before": null,
        "local_end_datetime": "2015-05-12T14:30:00Z",
        "deleted_at": null,
        "seats": null,
        "local_start_datetime": "2015-05-12T12:30:00Z",
        "end_booking_at": null,
        "cancellation_deadline": null,
        "metadata": {},
        "created_at": "2015-05-11T18:20:47Z",
        "venue": {
            "available_for_courses": true,
            "phone": "",
            "deleted_at": null,
            "lab_capacity": null,
            "restricted": false,
            "notes": "",
            "details_for_user": null,
            "metadata": {},
            "address": {
                "province_name": "Alberta",
                "country": "CA",
                "postal_code": "T5T 5T5",
                "city": "Edmonton",
                "address1": "1234 Java Parkway",
                "address2": null,
                "province": "AB",
                "country_name": "Canada",
                "updated_at": "2015-07-28T19:08:37Z"
            },
            "location": "Demo Location 1",
            "created_at": null,
            "fax": "",
            "web": "",
            "available_for_exams": true,
            "email": "",
            "hours_of_operation": "",
            "updated_at": "2015-07-28T19:08:37Z",
            "id": 831
        },
        "has_waiting_list": false,
        "private": false,
        "room": "66",
        "updated_at": "2015-05-11T20:04:59Z",
        "id": 49672
    },
    "questions": [
        {
            "item_bank_name": "Redpen Demo Questions",
            "item_bank_id": 368,
            "total_time_in_seconds": 5,
            "unanswered": false,
            "answer_score": 8,
            "correct": false,
            "angoff_score": null,
            "question": {
                "deleted_at": null,
                "metadata": {
                    "vascular-area": {
                        "references": "",
                        "notes-on-reference": ""
                    },
                    "demo-item-metadata": {
                        "item-cognitive-area": "",
                        "estimated-item-difficulty": "",
                        "gender-representation": "",
                        "custom-id": "",
                        "image-id": "",
                        "p-value-april-2014-trial": "1",
                        "most-recent-p-value-trial": "1",
                        "p-value-march-2014-trial": "1",
                        "verified-by-admin": "0",
                        "p-value-june-2014-trial": "1",
                        "p-value-may-2014-trial": "1"
                    }
                },
                "created_at": "2013-12-02T20:38:11Z",
                "canonical_id": 144631,
                "updated_at": "2015-02-18T22:53:18Z",
                "id": 215627
            },
            "total_time": 5,
            "question_id": 215627,
            "topic": "Redpen Demo Questions",
            "question_canonical_id": 144631,
            "capture": {
                "essay": "Summer vacation was wonderful. I went no where but to a ball field, where I ate about 14 pounds of spitz.  Truthfully, I think I kept the spitz family in business."
            },
            "id": 10095757
        },
        {
            "item_bank_name": "Redpen Demo Questions",
            "item_bank_id": 368,
            "total_time_in_seconds": 10,
            "unanswered": false,
            "answer_score": 13,
            "correct": false,
            "angoff_score": null,
            "question": {
                "deleted_at": null,
                "metadata": {
                    "vascular-area": {
                        "references": "",
                        "notes-on-reference": ""
                    },
                    "demo-item-metadata": {
                        "item-cognitive-area": "",
                        "estimated-item-difficulty": "",
                        "gender-representation": "",
                        "custom-id": "",
                        "image-id": "",
                        "p-value-april-2014-trial": "1",
                        "most-recent-p-value-trial": "1",
                        "p-value-march-2014-trial": "1",
                        "verified-by-admin": "0",
                        "p-value-june-2014-trial": "1",
                        "p-value-may-2014-trial": "1"
                    }
                },
                "created_at": "2013-12-02T20:39:37Z",
                "canonical_id": 144632,
                "updated_at": "2015-02-18T22:53:18Z",
                "id": 215628
            },
            "total_time": 10,
            "question_id": 215628,
            "topic": "Redpen Demo Questions",
            "question_canonical_id": 144632,
            "capture": {
                "essay": "I LOVE Thanksgiving because I love turkey and stuffing.  Stuffing is the best part of the turkey dinner!"
            },
            "id": 10095758
        }
    ],
    "number_of_questions": 2,
    "total_points": 30,
    "pass_mark": 50,
    "created_at": "2015-05-11T20:57:27Z",
    "exam_grant": {
        "expire_at": null,
        "grantable_id": 1306,
        "allow_sittings_start_at": null,
        "type": "ExamGrant",
        "exam_form_id": null,
        "start_at": "2015-05-11T19:00:01Z",
        "grantable_type": "Exam",
        "exam_form_group": "active",
        "uses": 1,
        "deleted_at": null,
        "user_id": 247441,
        "allow_sittings_end_at": null,
        "metadata": {},
        "created_at": "2015-05-11T19:00:01Z",
        "parent_grant_id": null,
        "num_uses": 1,
        "remaining_uses": 0,
        "updated_at": "2015-05-11T19:00:01Z",
        "id": 777250
    },
    "exam": {
        "name": "The Holidays Exam",
        "deleted_at": null,
        "metadata": {},
        "created_at": "2014-12-19T21:25:04Z",
        "updated_at": "2014-12-19T21:25:25Z",
        "id": 1306
    },
    "enrolment_key_establishment": null,
    "reviewed_at": "2015-05-11T20:57:45Z",
    "passing_strategy": "total_score",
    "proctored": true,
    "language": null,
    "exam_form": {
        "name": "Form 1",
        "deleted_at": null,
        "created_at": "2014-12-19T21:25:34Z",
        "updated_at": "2014-12-19T21:25:34Z",
        "id": 2647
    },
    "updated_at": "2015-06-09T17:27:03Z",
    "time_limit_in_minutes": 0,
    "exam_time_multiplier": 1,
    "id": 369143
}

Record Type UserExam

Triggered when Measure finishes calculating the grade for the user. This can be delayed when there are constructed response questions that cannot be automatically graded.

Questions

Design exam content by using the Questions resource. Questions are versioned, meaning that we track all revisions (whenever a Question is edited, we create a new entity instead of just updating the old one).

Index Questions

Example response

[
    {
        "rationale": null,
        "passage_id": null,
        "workflow_state": null,
        "created_by_id": 65,
        "rubric_sections": [],
        "paths": {
            "assets": "/v2/questions/assets"
        },
        "free_form_marking": null,
        "topic_id": null,
        "id": 1058,
        "locale": "en",
        "marking_method": "rubric",
        "item_bank_id": null,
        "canonical_id": 1058,
        "html": "",
        "passage": null
    },
    {
        "rationale": null,
        "passage_id": null,
        "workflow_state": null,
        "created_by_id": 65,
        "rubric_sections": [],
        "paths": {
            "assets": "/v2/questions/assets"
        },
        "free_form_marking": null,
        "topic_id": null,
        "id": 1062,
        "locale": "en",
        "marking_method": "rubric",
        "item_bank_id": null,
        "canonical_id": 1062,
        "html": "",
        "passage": null
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/questions

HTTP Get Params

Parameter Description Default
token
string
Your Measure API token
locale
string, optional
Language to retrieve ‘en’
rubric_criterion_ids
integer array, optional
Array of rubric criterion IDs
limit
integer, optional
Number of questions to retrieve 25
order
string, optional
Order to display the questions

Show Question

Example response

{
    "topic_id": null,
    "free_form_marking": null,
    "created_by_id": 65,
    "workflow_state": null,
    "rubric_sections": [],
    "rationale": null,
    "paths": {
        "assets": "/v2/questions/assets"
    },
    "item_bank_id": null,
    "id": 1058,
    "locale": "en",
    "marking_method": "rubric",
    "passage_id": null,
    "canonical_id": 1058,
    "html": "",
    "passage": null
}

HTTP Request

GET https://api.ysasecure.com/v2/questions/<question id>

HTTP Get Params

Parameter Description Default
question id
integer
ID of the question to retrieve
token
string
Your Measure API token
locale
string, optional
Language to show the question in ‘en’
user_exam_id
integer, optional
ID of specific user exam to retrieve questions from

Index Assets for Questions

Example response

{
  "javascript": "function() {\n console.log(\"Here is some javaScript that is run\");\n}",
  "css": ".myClass {\n background-color: red; \n}"
}

HTTP Request

GET https://api.ysasecure.com/v2/questions/assets

HTTP Get Params

Parameter Description
token
string
Your Measure API token

User Exam Questions

User Exam Questions differ from Questions in that they’re about which question a user sees when writing an exam. More specifically, they contain specific details about an instance of a question on a user’s exam.

Index User Exam Questions (Method 1)

Example response

[
    {
        "points": 4,
        "state": "raw",
        "user_exam": {
            "user": {
                "username": "demo_user"
            },
            "id": 7
        },
        "user_exam_id": 7032,
        "question_id": 858,
        "score": 0,
        "paths": {
            "question": "/v2/questions/858"
        },
        "question": {
            "topic_id": 439,
            "rationale": null,
            "marking_method": "rubric",
            "workflow_state": {
                "appear_on_exams": true,
                "score": true,
                "name": "Operational",
                "allow_editing": false,
                "id": 266,
                "position": 5
            },
            "created_by_id": 3109,
            "rubric_sections": [
                {
                    "question_id": 858,
                    "description": "Part A)",
                    "rubric_criterion": [
                        {
                            "point_value": 0.5,
                            "description": "First clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 200
                        },
                        {
                            "point_value": 0.5,
                            "description": "Second clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 201
                        },
                        {
                            "point_value": 0.5,
                            "description": "Third clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 202
                        },
                        {
                            "point_value": 0.5,
                            "description": "Fourth clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 203
                        }
                    ],
                    "keys": [],
                    "id": 692
                },
                {
                    "question_id": 859,
                    "description": "Part B)",
                    "rubric_criterion": [
                        {
                            "point_value": 1,
                            "description": "First answer correct?",
                            "rubric_section_id": 693,
                            "id": 204
                        },
                        {
                            "point_value": 1,
                            "description": "Second answer correct?",
                            "rubric_section_id": 693,
                            "id": 205
                        }
                    ],
                    "keys": [],
                    "id": 693
                }
            ],
            "free_form_marking": null,
            "item_bank_id": 1073,
            "paths": {
                "assets": "/v2/questions/assets"
            },
            "locale": "en",
            "id": 858,
            "passage_id": null,
            "passage": null,
            "html": "<p>Question goes here</p>",
            "canonical_id": 858
        },
        "id": 266,
        "correct": false,
        "answer": {
            "user_exam_question_id": 266,
            "score": null,
            "id": 244,
            "capture": {
                "essay": "Answer goes here"
            }
        },
        "position": 1,
        "score_tbd": true,
        "html": ""
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/user_exam_questions

HTTP Put Params

Parameter Description Default
token
string
Your Measure API token
ids
integer array, optional
Return only the specified user exam questions (via their ID)
user_exam_id
integer, optional
The ID of the user exam to retrieve questions from
locale
string, optional
Language to retrieve questions from ‘en’
marker
boolean, optional
Whether to return exams with only manually graded questions false
passage_id
integer, optional
Filter by passage ID associated with the user exam
include_sample_responses
boolean, optional
Whether sample responses should be included in the list retrieved false

Index User Exam Questions (Method 2)

Example response

[
    {
        "points": 4,
        "state": "raw",
        "user_exam": {
            "user": {
                "username": "demo_user"
            },
            "id": 7
        },
        "user_exam_id": 7032,
        "question_id": 858,
        "score": 0,
        "paths": {
            "question": "/v2/questions/858"
        },
        "question": {
            "topic_id": 439,
            "rationale": null,
            "marking_method": "rubric",
            "workflow_state": {
                "appear_on_exams": true,
                "score": true,
                "name": "Operational",
                "allow_editing": false,
                "id": 266,
                "position": 5
            },
            "created_by_id": 3109,
            "rubric_sections": [
                {
                    "question_id": 858,
                    "description": "Part A)",
                    "rubric_criterion": [
                        {
                            "point_value": 0.5,
                            "description": "First clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 200
                        },
                        {
                            "point_value": 0.5,
                            "description": "Second clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 201
                        },
                        {
                            "point_value": 0.5,
                            "description": "Third clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 202
                        },
                        {
                            "point_value": 0.5,
                            "description": "Fourth clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 203
                        }
                    ],
                    "keys": [],
                    "id": 692
                },
                {
                    "question_id": 859,
                    "description": "Part B)",
                    "rubric_criterion": [
                        {
                            "point_value": 1,
                            "description": "First answer correct?",
                            "rubric_section_id": 693,
                            "id": 204
                        },
                        {
                            "point_value": 1,
                            "description": "Second answer correct?",
                            "rubric_section_id": 693,
                            "id": 205
                        }
                    ],
                    "keys": [],
                    "id": 693
                }
            ],
            "free_form_marking": null,
            "item_bank_id": 1073,
            "paths": {
                "assets": "/v2/questions/assets"
            },
            "locale": "en",
            "id": 858,
            "passage_id": null,
            "passage": null,
            "html": "<p>Question goes here</p>",
            "canonical_id": 858
        },
        "id": 266,
        "correct": false,
        "answer": {
            "user_exam_question_id": 266,
            "score": null,
            "id": 244,
            "capture": {
                "essay": "Answer goes here"
            }
        },
        "position": 1,
        "score_tbd": true,
        "html": ""
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/user_exams/<user exam id>/user_exam_questions

HTTP Put Params

Parameter Description Default
user exam id
integer
The ID of the user exam to retrieve questions from
token
string
Your Measure API token
ids
integer array, optional
Return only the specified user exam questions (via their ID)
locale
string, optional
Language to retrieve questions from ‘en’
marker
boolean, optional
Whether to return exams with only manually graded questions false
passage_id
integer, optional
Filter by passage ID associated with the user exam
include_sample_responses
boolean, optional
Whether sample responses should be included in the list retrieved false

Mark User Exam Questions

Example Response

[
    {
        "points": 4,
        "state": "raw",
        "user_exam": {
            "user": {
                "username": "cpashtest"
            },
            "id": 703
        },
        "user_exam_id": 703,
        "question_id": 858,
        "score": 15,
        "paths": {
            "question": "/v2/questions/858"
        },
        "question": {
            "topic_id": 439,
            "rationale": null,
            "marking_method": "rubric",
            "workflow_state": {
                "appear_on_exams": true,
                "score": true,
                "name": "Operational",
                "allow_editing": false,
                "id": 266,
                "position": 5
            },
            "created_by_id": 3109,
            "rubric_sections": [
                {
                    "question_id": 858,
                    "description": "Part A)",
                    "rubric_criterion": [
                        {
                            "point_value": 0.5,
                            "description": "First clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 201
                        },
                        {
                            "point_value": 0.5,
                            "description": "Second clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 202
                        },
                        {
                            "point_value": 0.5,
                            "description": "Third clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 203
                        },
                        {
                            "point_value": 0.5,
                            "description": "Fourth clinical feature correct?",
                            "rubric_section_id": 692,
                            "id": 204
                        }
                    ],
                    "keys": [],
                    "id": 692
                },
                {
                    "question_id": 858,
                    "description": "Part B)",
                    "rubric_criterion": [
                        {
                            "point_value": 1,
                            "description": "First medication correct?",
                            "rubric_section_id": 693,
                            "id": 205
                        },
                        {
                            "point_value": 1,
                            "description": "Second medication correct?",
                            "rubric_section_id": 693,
                            "id": 206
                        }
                    ],
                    "keys": [],
                    "id": 693
                }
            ],
            "free_form_marking": null,
            "item_bank_id": 1073,
            "paths": {
                "assets": "/v2/questions/assets"
            },
            "locale": null,
            "id": 858,
            "passage_id": null,
            "passage": null,
            "html": "Question goes here",
            "canonical_id": 858
        },
        "id": 26612711,
        "correct": false,
        "answer": {
            "user_exam_question_id": 26612711,
            "score": 15,
            "id": 245,
            "capture": {
                "essay": "Answer goes here"
            }
        },
        "position": 1,
        "score_tbd": false,
        "html": ""
    }
]

HTTP Request

PUT https://api.ysasecure.com/v2/user_exams/<user exam id>/user_exam_questions/mark

HTTP Put Params

Parameter Description
user exam id
integer
ID of the user exam to check
token
string
Your Measure API token
marks
marks array
See below for the marks params

Marks Format

Parameter Description Default
id
integer
User Exam Question ID for the question on the user exam to mark
score
float
Score to assign to the user exam question
unattempted
boolean, optional
Whether to set the user exam question as attempted false

Sittings

Sitting Users Index

Example Response

[
    {
        "first_name": "",
        "deleted_at": null,
        "username": "demotest",
        "created_at": "2017-04-07T19:02:11Z",
        "email_verified": false,
        "active": true,
        "alternate_email_verified": false,
        "metadata": {
            "special-accommodations-request": {
                "special-accommodations-request": "no"
            }
        },
        "user_groups": [],
        "updated_at": "2017-07-13T18:57:24Z",
        "email": "",
        "address": {
            "province_name": "Alberta",
            "postal_code": "M4W1N1",
            "country_name": "Canada",
            "province": "AB",
            "address1": "asdf",
            "updated_at": "2017-04-07T19:02:11Z",
            "city": "asdf",
            "country": "CA",
            "address2": ""
        },
        "preferred_language": "en",
        "alternate_email": null,
        "id": 517,
        "last_name": "",
        "site_id": 3
    },
    {
        "first_name": "",
        "deleted_at": null,
        "username": "demo",
        "created_at": "2014-06-16T19:31:12Z",
        "email_verified": false,
        "active": true,
        "alternate_email_verified": false,
        "metadata": {},
        "user_groups": [],
        "updated_at": "2017-07-13T18:48:15Z",
        "email": "",
        "address": {
            "province_name": "Alberta",
            "postal_code": "t6e6e6",
            "country_name": "Canada",
            "province": "AB",
            "address1": "12345",
            "updated_at": "2014-06-16T19:31:12Z",
            "city": "Edmonton",
            "country": "CA",
            "address2": ""
        },
        "preferred_language": "en",
        "alternate_email": "",
        "id": 296,
        "last_name": "",
        "site_id": 3
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/sittings/<sitting id>/users

HTTP Get Params

Parameter Description
sitting id
integer
The ID of the sitting that users will be listed from
token
string
Your Measure API token

Sitting Proctors Index

Example Response

[
    {
        "first_name": "Demo",
        "type": "Proctor",
        "roles": [
            "proctor"
        ],
        "email": "demo@getyardstick.com",
        "id": 1343,
        "last_name": "Demo"
    },
    {
        "first_name": "Another Demo",
        "type": "Proctor",
        "roles": [
            "proctor"
        ],
        "email": "anotherdemo@getyardstick.com",
        "id": 975,
        "last_name": "Demo"
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/sittings/<sitting id>/proctors

HTTP Get Params

Parameter Description
sitting id
integer
The ID of the sitting that proctors will be listed from
token
string
Your Measure API token

Test Centre Time Windows

Show Test Centre Time Window

Example response

{
    "source_id": 658,
    "source_type": "Sitting",
    "venue": {
        "account": {
            "name": "Measure Demo",
            "id": 7,
            "short_name": "demo"
        },
        "location": "Yardstick Testing & Training Experts",
        "id": 1187
    },
    "proctoring_options": {
        "virtual_proctoring": {
            "provider_name": "YardstickExams",
            "provider_options": {
                "username": "",
                "api_key": ""
            },
            "enabled": false
        },
        "incident_reports": true
    },
    "venue_id": 1187,
    "global_start_datetime": "2017-07-14T06:30:00Z",
    "global_end_datetime": "2017-07-17T06:00:00Z",
    "paths": {
        "incidents": "/v2/sittings/658/incidents",
        "users": "/v2/sittings/658/users",
        "proctors": "/v2/sittings/658/proctors"
    },
    "time_zone": "Mountain Time (US & Canada)",
    "test_centre_seats": [
        {
            "source_id": 658,
            "user_id": 5173,
            "grantable_id": 3033,
            "source_type": "Sitting",
            "grantable_type": "Exam",
            "grantable": {
                "name": "Demo Exam",
                "id": 3033
            },
            "user": {
                "first_name": "",
                "full_name": "demo",
                "id": 517,
                "last_name": ""
            }
        },
        {
            "source_id": 658,
            "user_id": 296,
            "grantable_id": 1089,
            "source_type": "Sitting",
            "grantable_type": "Exam",
            "grantable": {
                "name": "Tutorial",
                "id": 1089
            },
            "user": {
                "first_name": "",
                "full_name": "demo",
                "id": 296,
                "last_name": ""
            }
        }
    ],
    "attachments": [
        {
            "file_url": "/media/BAhbBlsHOgZmIkcyMDE/Demo.pdf",
            "file_name": "Demo.pdf",
            "id": 240
        }
    ]
}

HTTP Request

GET https://api.ysasecure.com/v2/test_centre_time_windows/<id>/<source type>

HTTP Get Params

Parameter Description
id
integer
The ID of the sitting or booking
source type
string
“booking” or “sitting”
token
string
Your Measure API token

Upcoming & Recent Test Centre Time Windows

Example response

[
  {
      "source_id": 658,
      "source_type": "Sitting",
      "venue": {
          "account": {
              "name": "Measure Demo",
              "id": 7,
              "short_name": "demo"
          },
          "location": "Yardstick Testing & Training Experts",
          "id": 1187
      },
      "proctoring_options": {
          "virtual_proctoring": {
              "provider_name": "YardstickExams",
              "provider_options": {
                  "username": "",
                  "api_key": ""
              },
              "enabled": false
          },
          "incident_reports": true
      },
      "venue_id": 1187,
      "global_start_datetime": "2017-07-14T06:30:00Z",
      "global_end_datetime": "2017-07-17T06:00:00Z",
      "paths": {
          "incidents": "/v2/sittings/658/incidents",
          "users": "/v2/sittings/658/users",
          "proctors": "/v2/sittings/658/proctors"
      },
      "time_zone": "Mountain Time (US & Canada)",
      "test_centre_seats": [
          {
              "source_id": 658,
              "user_id": 5173,
              "grantable_id": 3033,
              "source_type": "Sitting",
              "grantable_type": "Exam",
              "grantable": {
                  "name": "Demo Exam",
                  "id": 3033
              },
              "user": {
                  "first_name": "",
                  "full_name": "demo",
                  "id": 517,
                  "last_name": ""
              }
          },
          {
              "source_id": 658,
              "user_id": 296,
              "grantable_id": 1089,
              "source_type": "Sitting",
              "grantable_type": "Exam",
              "grantable": {
                  "name": "Tutorial",
                  "id": 1089
              },
              "user": {
                  "first_name": "",
                  "full_name": "demo",
                  "id": 296,
                  "last_name": ""
              }
          }
      ],
      "attachments": [
          {
              "file_url": "/media/BAhbBlsHOgZmIkcyMDE/Demo.pdf",
              "file_name": "Demo.pdf",
              "id": 240
          }
      ]
  }
]

HTTP Request

GET https://api.ysasecure.com/v2/test_centre_time_windows/upcoming_and_recent

HTTP Get Params

Parameter Description
token
string
Your Measure API token

Bookings

Show Booking

Retrieve a specific booking from a user.

Example Response

{
    "sitting": {
        "require_purchase_before": null,
        "venue": {
            "phone": "",
            "notes": "",
            "lab_capacity": null,
            "created_at": "2014-06-13T23:19:20Z",
            "web": "",
            "translated_address": {
                "province_name": "Alberta",
                "postal_code": "T6E 6E6",
                "country_name": "Canada",
                "province": "AB",
                "address1": "#200, 8616 - 51 Avenue",
                "updated_at": "2017-02-22T22:14:31Z",
                "city": "Edmonton",
                "country": "CA",
                "address2": null
            },
            "deleted_at": null,
            "available_for_exams": true,
            "metadata": {},
            "updated_at": "2017-02-22T22:14:31Z",
            "email": "",
            "location": "Yardstick Testing & Training Experts",
            "details_for_user": null,
            "available_for_courses": false,
            "fax": "",
            "hours_of_operation": "",
            "id": 1187
        },
        "has_waiting_list": false,
        "session_type": "exam",
        "created_at": "2017-07-13T17:57:03Z",
        "begin_booking_at": null,
        "deleted_at": null,
        "seats": null,
        "metadata": {},
        "local_start_datetime": "2017-07-14T06:30:00Z",
        "end_booking_at": null,
        "cancellation_deadline": null,
        "updated_at": "2017-07-13T17:57:03Z",
        "room": "",
        "local_end_datetime": "2017-07-17T06:00:00Z",
        "private": false,
        "id": 658,
        "venue_tbd": false
    },
    "grant": {
        "allow_sittings_start_at": null,
        "num_uses": null,
        "type": "ExamGrant",
        "user_id": 5173,
        "exam_form_id": 886,
        "exam_form_group": "active",
        "grantable_id": 3033,
        "remaining_uses": null,
        "created_at": "2017-07-13T18:56:50Z",
        "attempts_count": 1,
        "exam_form": {
            "created_at": "2017-01-25T14:56:29Z",
            "deleted_at": null,
            "active": true,
            "updated_at": "2017-07-13T18:52:21Z",
            "name": "Form 1",
            "id": 886
        },
        "allow_sittings_end_at": null,
        "deleted_at": null,
        "grantable_type": "Exam",
        "user": {
            "first_name": "",
            "alternate_email": null,
            "username": "demo",
            "created_at": "2017-04-07T19:02:11Z",
            "deleted_at": null,
            "email_verified": false,
            "active": true,
            "alternate_email_verified": false,
            "metadata": {
                "special-accommodations-request": {
                    "special-accommodations-request": "no"
                }
            },
            "user_groups": [],
            "updated_at": "2017-07-13T18:57:24Z",
            "email": "",
            "address": {
                "province_name": "Alberta",
                "postal_code": "M4W1N1",
                "country_name": "Canada",
                "province": "AB",
                "address1": "asdf",
                "updated_at": "2017-04-07T19:02:11Z",
                "city": "asdf",
                "country": "CA",
                "address2": ""
            },
            "preferred_language": "en",
            "id": 517,
            "last_name": "",
            "site_id": 3
        },
        "metadata": {},
        "exam": {
            "metadata": {},
            "name": "Demo Exam",
            "marking_deadline_in_days": 0,
            "id": 3033
        },
        "updated_at": "2017-07-13T18:56:50Z",
        "expire_at": null,
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://beta.ysasecure.com/grants/1100199/bookings/new"
        },
        "parent_grant_id": null,
        "start_at": "2017-07-13T18:56:50Z",
        "id": 1100
    },
    "created_at": "2017-07-13T18:57:05Z",
    "deleted_at": null,
    "cancellation_note": null,
    "user": {
        "first_name": "",
        "alternate_email": null,
        "username": "cpashtest",
        "created_at": "2017-04-07T19:02:11Z",
        "deleted_at": null,
        "email_verified": false,
        "active": true,
        "alternate_email_verified": false,
        "metadata": {
            "special-accommodations-request": {
                "special-accommodations-request": "no"
            }
        },
        "user_groups": [],
        "updated_at": "2017-07-13T18:57:24Z",
        "email": "",
        "address": {
            "province_name": "Alberta",
            "postal_code": "M4W1N1",
            "country_name": "Canada",
            "province": "AB",
            "address1": "asdf",
            "updated_at": "2017-04-07T19:02:11Z",
            "city": "asdf",
            "country": "CA",
            "address2": ""
        },
        "preferred_language": "en",
        "id": 517,
        "last_name": "",
        "site_id": 3
    },
    "updated_at": "2017-07-13T18:57:55Z",
    "id": 565
}

HTTP Request

GET https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>/bookings/<booking id>

HTTP Get Params

Parameter Description
user id
string
The ID number of the user that the booking belongs to
grant id
integer
The ID number of the grant that the booking is associated with
booking id
integer
The ID of the booking you wish to retrieve
token
string
Your Measure API token

Create Booking

Create a new booking for a user.

Example Response

{
    "sitting": {
        "require_purchase_before": null,
        "venue": {
            "phone": "",
            "notes": "",
            "lab_capacity": null,
            "created_at": "2014-06-13T23:19:20Z",
            "web": "",
            "translated_address": {
                "province_name": "Alberta",
                "postal_code": "T6E 6E6",
                "country_name": "Canada",
                "province": "AB",
                "address1": "#200, 8616 - 51 Avenue",
                "updated_at": "2017-02-22T22:14:31Z",
                "city": "Edmonton",
                "country": "CA",
                "address2": null
            },
            "deleted_at": null,
            "available_for_exams": true,
            "metadata": {},
            "updated_at": "2017-02-22T22:14:31Z",
            "email": "",
            "location": "Yardstick Testing & Training Experts",
            "details_for_user": null,
            "available_for_courses": false,
            "fax": "",
            "hours_of_operation": "",
            "id": 1187
        },
        "has_waiting_list": false,
        "session_type": "exam",
        "created_at": "2017-07-13T17:57:03Z",
        "begin_booking_at": null,
        "deleted_at": null,
        "seats": null,
        "metadata": {},
        "local_start_datetime": "2017-07-14T06:30:00Z",
        "end_booking_at": null,
        "cancellation_deadline": null,
        "updated_at": "2017-07-13T17:57:03Z",
        "room": "",
        "local_end_datetime": "2017-07-17T06:00:00Z",
        "private": false,
        "id": 658,
        "venue_tbd": false
    },
    "grant": {
        "allow_sittings_start_at": null,
        "num_uses": null,
        "type": "ExamGrant",
        "user_id": 5173,
        "exam_form_id": 886,
        "exam_form_group": "active",
        "grantable_id": 3033,
        "remaining_uses": null,
        "created_at": "2017-07-13T18:56:50Z",
        "attempts_count": 1,
        "exam_form": {
            "created_at": "2017-01-25T14:56:29Z",
            "deleted_at": null,
            "active": true,
            "updated_at": "2017-07-13T18:52:21Z",
            "name": "Form 1",
            "id": 886
        },
        "allow_sittings_end_at": null,
        "deleted_at": null,
        "grantable_type": "Exam",
        "user": {
            "first_name": "",
            "alternate_email": null,
            "username": "demo",
            "created_at": "2017-04-07T19:02:11Z",
            "deleted_at": null,
            "email_verified": false,
            "active": true,
            "alternate_email_verified": false,
            "metadata": {
                "special-accommodations-request": {
                    "special-accommodations-request": "no"
                }
            },
            "user_groups": [],
            "updated_at": "2017-07-13T18:57:24Z",
            "email": "",
            "address": {
                "province_name": "Alberta",
                "postal_code": "M4W1N1",
                "country_name": "Canada",
                "province": "AB",
                "address1": "asdf",
                "updated_at": "2017-04-07T19:02:11Z",
                "city": "asdf",
                "country": "CA",
                "address2": ""
            },
            "preferred_language": "en",
            "id": 517,
            "last_name": "",
            "site_id": 3
        },
        "metadata": {},
        "exam": {
            "metadata": {},
            "name": "Demo Exam",
            "marking_deadline_in_days": 0,
            "id": 3033
        },
        "updated_at": "2017-07-13T18:56:50Z",
        "expire_at": null,
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://beta.ysasecure.com/grants/1100199/bookings/new"
        },
        "parent_grant_id": null,
        "start_at": "2017-07-13T18:56:50Z",
        "id": 1100
    },
    "created_at": "2017-07-13T18:57:05Z",
    "deleted_at": null,
    "cancellation_note": null,
    "user": {
        "first_name": "",
        "alternate_email": null,
        "username": "cpashtest",
        "created_at": "2017-04-07T19:02:11Z",
        "deleted_at": null,
        "email_verified": false,
        "active": true,
        "alternate_email_verified": false,
        "metadata": {
            "special-accommodations-request": {
                "special-accommodations-request": "no"
            }
        },
        "user_groups": [],
        "updated_at": "2017-07-13T18:57:24Z",
        "email": "",
        "address": {
            "province_name": "Alberta",
            "postal_code": "M4W1N1",
            "country_name": "Canada",
            "province": "AB",
            "address1": "asdf",
            "updated_at": "2017-04-07T19:02:11Z",
            "city": "asdf",
            "country": "CA",
            "address2": ""
        },
        "preferred_language": "en",
        "id": 517,
        "last_name": "",
        "site_id": 3
    },
    "updated_at": "2017-07-13T18:57:55Z",
    "id": 565
}

HTTP Request

POST https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>/bookings

HTTP Post Params

Parameter Description Default
user id
integer
The Measure User ID of the user that the booking will be associated with
grant id
integer
The ID number of the grant that the booking is associated with
token
string
Your Measure API token
sitting[id]
integer
The ID of the sitting that the booking is for
sitting[range][venue_id]
integer
The ID number of the venue where the exam sitting will be held
sitting[range][start_at]
time with zone
The start date of sittings you want the booking API to search from
sitting[range][end_at]
time with zone
The end date of sittings you want the booking API to search from
options[include_private]
boolean, optional
Whether to include private bookings or not false
options[only_before_cancellation_deadline]
boolean, optional
If true, reject bookings made after the cancellation deadline true
options[in_booking_window]
boolean, optional
Whether the booking window is still open or not true
options[include_past]
boolean, optional
Whether to include past bookings false
options[has_seats_left]
boolean, optional
Whether or not the sitting has seats left true
send_email
boolean, optional
Send a confirmation email upon successful booking creation true

Destroy Booking

Delete booking for a user.

Example Response

{
    "sitting": {
        "require_purchase_before": null,
        "venue": {
            "phone": "",
            "notes": "",
            "lab_capacity": null,
            "created_at": "2014-06-13T23:19:20Z",
            "web": "",
            "translated_address": {
                "province_name": "Alberta",
                "postal_code": "T6E 6E6",
                "country_name": "Canada",
                "province": "AB",
                "address1": "#200, 8616 - 51 Avenue",
                "updated_at": "2017-02-22T22:14:31Z",
                "city": "Edmonton",
                "country": "CA",
                "address2": null
            },
            "deleted_at": null,
            "available_for_exams": true,
            "metadata": {},
            "updated_at": "2017-02-22T22:14:31Z",
            "email": "",
            "location": "Yardstick Testing & Training Experts",
            "details_for_user": null,
            "available_for_courses": false,
            "fax": "",
            "hours_of_operation": "",
            "id": 1187
        },
        "has_waiting_list": false,
        "session_type": "exam",
        "created_at": "2017-07-13T17:57:03Z",
        "begin_booking_at": null,
        "deleted_at": "2017-07-13T18:57:55Z",
        "seats": null,
        "metadata": {},
        "local_start_datetime": "2017-07-14T06:30:00Z",
        "end_booking_at": null,
        "cancellation_deadline": null,
        "updated_at": "2017-07-13T17:57:03Z",
        "room": "",
        "local_end_datetime": "2017-07-17T06:00:00Z",
        "private": false,
        "id": 658,
        "venue_tbd": false
    },
    "grant": {
        "allow_sittings_start_at": null,
        "num_uses": null,
        "type": "ExamGrant",
        "user_id": 5173,
        "exam_form_id": 886,
        "exam_form_group": "active",
        "grantable_id": 3033,
        "remaining_uses": null,
        "created_at": "2017-07-13T18:56:50Z",
        "attempts_count": 1,
        "exam_form": {
            "created_at": "2017-01-25T14:56:29Z",
            "deleted_at": null,
            "active": true,
            "updated_at": "2017-07-13T18:52:21Z",
            "name": "Form 1",
            "id": 886
        },
        "allow_sittings_end_at": null,
        "deleted_at": null,
        "grantable_type": "Exam",
        "user": {
            "first_name": "",
            "alternate_email": null,
            "username": "demo",
            "created_at": "2017-04-07T19:02:11Z",
            "deleted_at": null,
            "email_verified": false,
            "active": true,
            "alternate_email_verified": false,
            "metadata": {
                "special-accommodations-request": {
                    "special-accommodations-request": "no"
                }
            },
            "user_groups": [],
            "updated_at": "2017-07-13T18:57:24Z",
            "email": "",
            "address": {
                "province_name": "Alberta",
                "postal_code": "M4W1N1",
                "country_name": "Canada",
                "province": "AB",
                "address1": "asdf",
                "updated_at": "2017-04-07T19:02:11Z",
                "city": "asdf",
                "country": "CA",
                "address2": ""
            },
            "preferred_language": "en",
            "id": 517,
            "last_name": "",
            "site_id": 3
        },
        "metadata": {},
        "exam": {
            "metadata": {},
            "name": "Demo Exam",
            "marking_deadline_in_days": 0,
            "id": 3033
        },
        "updated_at": "2017-07-13T18:56:50Z",
        "expire_at": null,
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://beta.ysasecure.com/grants/1100199/bookings/new"
        },
        "parent_grant_id": null,
        "start_at": "2017-07-13T18:56:50Z",
        "id": 1100
    },
    "created_at": "2017-07-13T18:57:05Z",
    "deleted_at": null,
    "cancellation_note": null,
    "user": {
        "first_name": "",
        "alternate_email": null,
        "username": "cpashtest",
        "created_at": "2017-04-07T19:02:11Z",
        "deleted_at": null,
        "email_verified": false,
        "active": true,
        "alternate_email_verified": false,
        "metadata": {
            "special-accommodations-request": {
                "special-accommodations-request": "no"
            }
        },
        "user_groups": [],
        "updated_at": "2017-07-13T18:57:24Z",
        "email": "",
        "address": {
            "province_name": "Alberta",
            "postal_code": "M4W1N1",
            "country_name": "Canada",
            "province": "AB",
            "address1": "asdf",
            "updated_at": "2017-04-07T19:02:11Z",
            "city": "asdf",
            "country": "CA",
            "address2": ""
        },
        "preferred_language": "en",
        "id": 517,
        "last_name": "",
        "site_id": 3
    },
    "updated_at": "2017-07-13T18:57:55Z",
    "id": 565
}

HTTP Request

DELETE https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>/bookings/<booking id>

HTTP Delete Params

Parameter Description Default
grant id
integer
The ID number of the grant that the booking is associated with
user id
integer
The Measure User ID of the user the booking is associated with
booking id
integer
The ID number of the booking to be deleted
token
string
Your Measure API token
options[note]
string
Reason for withdrawing from the booking
options[force]
boolean, optional
Force destruction of the booking false
options[cancel_order]
boolean, optional
Cancel the order true
options[notify_user]
boolean, optional
Notify the user via email true

Webhooks

Example Payload

{
    "user": {
        "display_name": "Demo User",
        "alternate_email": "",
        "user_name": "demo.user",
        "active": true,
        "deleted_at": null,
        "preferred_language": "en",
        "first_name": "Demo",
        "metadata": {},
        "email_verified": false,
        "address": null,
        "created_at": "2017-11-01T16:07:47Z",
        "username": "demo.user",
        "alternate_email_verified": false,
        "email": "demo.user@getyardstick.com",
        "last_name": "User",
        "full_name": "Demo User",
        "updated_at": "2017-11-01T16:07:47Z",
        "id": 585972
    },
    "deleted_at": null,
    "sitting": {
        "begin_booking_at": null,
        "venue_tbd": false,
        "session_type": "exam",
        "require_purchase_before": null,
        "local_end_datetime": "2017-11-16T15:45:00Z",
        "deleted_at": null,
        "seats": null,
        "local_start_datetime": "2017-11-16T11:15:00Z",
        "end_booking_at": null,
        "cancellation_deadline": null,
        "metadata": {},
        "created_at": "2017-11-01T16:06:55Z",
        "venue": {
            "available_for_courses": true,
            "phone": "",
            "deleted_at": null,
            "lab_capacity": null,
            "restricted": false,
            "notes": "",
            "details_for_user": null,
            "metadata": {},
            "address": {
                "province_name": "Alberta",
                "country": "CA",
                "postal_code": "T5T 5T5",
                "city": "Edmonton",
                "address1": "1234 Java Parkway",
                "address2": null,
                "province": "AB",
                "country_name": "Canada",
                "updated_at": "2015-07-28T19:08:37Z"
            },
            "location": "Demo Location 1",
            "created_at": null,
            "fax": "",
            "web": "",
            "available_for_exams": true,
            "email": "",
            "hours_of_operation": "",
            "updated_at": "2015-07-28T19:08:37Z",
            "id": 831
        },
        "has_waiting_list": false,
        "private": false,
        "room": "",
        "updated_at": "2017-11-01T16:06:55Z",
        "id": 69484
    },
    "metadata": {},
    "grant": {
        "expire_at": null,
        "grantable_id": 1306,
        "allow_sittings_start_at": null,
        "type": "ExamGrant",
        "exam_form_id": null,
        "start_at": "2017-11-01T16:08:25Z",
        "grantable_type": "Exam",
        "exam_form_group": "active",
        "uses": 0,
        "deleted_at": null,
        "user_id": 585972,
        "allow_sittings_end_at": null,
        "metadata": {},
        "created_at": "2017-11-01T16:08:25Z",
        "parent_grant_id": null,
        "num_uses": 1,
        "remaining_uses": 1,
        "updated_at": "2017-11-01T16:08:25Z",
        "id": 1156792
    },
    "created_at": "2017-11-01T16:08:47Z",
    "attendance_status": "booked",
    "updated_at": "2017-11-01T16:08:47Z",
    "id": 598879
}

Record Type Booking

Triggered whenever a Booking is created, updated, or cancelled in Measure (either via the API or Measure’s user interface).

Important Attributes

Attribute Description
deleted_at
datetime
Usually null unless the booking has been cancelled. Otherwise is the date/time of the cancellation.

Booking Requests

Index Booking Requests

HTTP Request

GET https://api.ysasecure.com/v2/booking_requests

Parameter Description
token
string
Your Measure API token
state
string, optional
Filter booking requests by a specific state

Schedule Booking Request

HTTP Request

PUT https://api.ysasecure.com/v2/booking_requests/<booking request id>/schedule

HTTP Put Params

Parameter Description
token
string
Your Measure API token
booking_request[local_start_at]
time with zone, optional
Start date & time
booking_request[local_end_at]
time with zone, optional
End date & time
booking_request[date1]
date, optional
Date 1
booking_request[date1_am]
boolean, optional
Whether it should be in the morning or not
booking_request[date2]
date, optional
Date 2
booking_request[date2_am]
boolean, optional
Whether it should be in the morning or not
booking_request[date3]
date, optional
Date 3
booking_request[date3_am]
boolean, optional
Whether it should be in the morning or not

Request Alternate Dates for Booking Requests

HTTP Request

PUT https://api.ysasecure.com/v2/booking_requests/<booking request id>/request_alternate_dates

HTTP Put Params

Parameter Description
token
string
Your Measure API token
booking_request[local_start_at]
time with zone, optional
booking_request[local_end_at]
time with zone, optional
booking_request[date1]
date, optional
booking_request[date1_am]
boolean, optional
booking_request[date2]
date, optional
booking_request[date2_am]
boolean, optional
booking_request[date3]
date, optional
booking_request[date3_am]
boolean, optional

Booking Request Users

HTTP Request

GET https://api.ysasecure.com/v2/booking_requests/<booking request id>/users

HTTP Get Params

Parameter Description
booking request id
integer
ID of the booking request to view users from
token
string
Your Measure API token

Booking Request Proctors

HTTP Request

GET https://api.ysasecure.com/v2/booking_requests/<booking request id>/proctors

HTTP Get Params

Parameter Description
booking request id
integer
ID of the booking request to view proctors from
token
string
Your Measure API token

Incidents

Types of Incidents

Example response

{
    "types": [
        "breach_of_regulations",
        "computer_issue",
        "disturbance_in_the_test_centre",
        "fire_alarm",
        "no_authorization",
        "no_incidents",
        "no_proper_id",
        "no_show",
        "no_user_account",
        "other",
        "power_outage",
        "room_issue",
        "washroom_break"
    ]
}

HTTP Request

GET https://api.ysasecure.com/v2/incidents/types

Create Incident

HTTP Request

POST https://api.ysasecure.com/v2/incidents

HTTP Post Params

Parameter Description
token
string
Your Measure API token
incident[incident_datetime]
time with zone
Date and time that the incident occurred
incident[incident_type]
string
See Types of Incidents for a list of possible values
incident[user_ids]
integer array, optional
User IDs associated with the incident (leave blank to associate all users at this sitting)
incident[proctors]
array of proctors, optional
Each proctor in the array should include an id and a type (either 'AdminUser' or 'NomadUser')
incident[notes]
string, optional
Notes about the incident to include in the report
booking_request_id
integer, optional
Booking Request ID to associate the incident with
sitting_id
integer, optional
Sitting ID to associate the incident with

Show Incident

HTTP Request

GET https://api.ysasecure.com/v2/incidents

HTTP Get Params

Parameter Description
token
string
Your Measure API token
booking_request_id
integer, optional
Booking Request ID the incident is associated with
sitting_id
integer, optional
Sitting ID the incident is associated with

Index Booking Request Incidents

HTTP Request

GET https://api.ysasecure.com/v2/booking_requests/<booking request id>/incidents

HTTP Get Params

Parameter Description
booking request id
integer
ID of the booking request id to retrieve incidents for
token
string
Your Measure API token

Create Booking Request Incident

HTTP Request

POST https://api.ysasecure.com/v2/booking_requests/<booking request id>/incidents

HTTP Post Params

Parameter Description
booking request id
integer
ID of the booking request id to create an incident for
token
string
Your Measure API token
incident[incident_datetime]
time with zone
Date and time that the incident occurred
incident[incident_type]
string
See Types of Incidents for a list of possible values
incident[user_ids]
integer array, optional
User IDs associated with the incident (leave blank to associate all users at this sitting)
incident[proctors]
array of proctors, optional
Each proctor in the array should include an id and a type (either 'AdminUser' or 'NomadUser')
incident[notes]
string, optional
Notes about the incident to include in the report

Show Booking Request Incident

HTTP Request

GET https://api.ysasecure.com/v2/booking_requests/<booking request id>/incidents/<incident id>

HTTP Get Params

Parameter Description
booking request id
integer
ID of the booking request to retrieve
incident id
integer
ID of the incident to retrieve
token
string
Your Measure API token

Index Sitting Incidents

HTTP Request

GET https://api.ysasecure.com/v2/sittings/<sitting id>/incidents

HTTP Get Params

Parameter Description
sitting id
integer
ID of the sitting to retrieve
token
string
Your Measure API token

Create Sitting Incident

HTTP Request

POST https://api.ysasecure.com/v2/sittings/<sitting id>/incidents

HTTP Post Params

Parameter Description
sitting id
integer
ID of the sitting to create an incident in
token
string
Your Measure API token
incident[incident_datetime]
time with zone
Date and time that the incident occurred
incident[incident_type]
string
See Types of Incidents for a list of possible values
incident[user_ids]
integer array, optional
User IDs associated with the incident (leave blank to associate all users at this sitting)
incident[proctors]
array of proctors, optional
Each proctor in the array should include an id and a type (either 'AdminUser' or 'NomadUser')
incident[notes]
string, optional
Notes about the incident to include in the report

Show Sitting Incident

HTTP Request

GET https://api.ysasecure.com/v2/sittings/<sitting id>/incidents/<incident id>

HTTP Get Params

Parameter Description
sitting id
integer
ID of the sitting to retrieve
incident id
integer
ID of the incident to retrieve
token
string
Your Measure API token

Administrations

An Administration represents a group of exam sessions or an exam “event”. Some organizations call these semesters and is a good example of what this represents. A good example to draw on from the high education world would be “February 2016 Mid-Terms.”

Index Administrations

HTTP Request

GET https://api.ysasecure.com/v2/administrations

HTTP Get Params

Parameter Description
token
string
Your Measure API token
account_id
integer, optional
ID of the account associated with the administration

Show Administration

HTTP Request

GET https://api.ysasecure.com/v2/administrations/<administration id>

HTTP Get Params

Parameter Description
administration id
integer
ID of the administration to retrieve
token
string
Your Measure API token
account_id
integer, optional
ID of the account associated with the administration

Orders

Update Order

HTTP Request

PUT https://api.ysasecure.com/v2/orders/<order id>

HTTP Put Params

Parameter Description
order id
integer
ID of the order to retrieve
token
string
Your Measure API token
order[metadata]
metadata, optional
Metadata to update for the order

Passages

Index Passages

HTTP Request

GET https://api.ysasecure.com/v2/passages

HTTP Get Params

Parameter Description
token
string
Your Measure API token
administration_id
integer, optional
ID of the administration to retrieve passages from
with_manually_graded_questions
boolean, optional
Whether to return passages with manually graded questions
ids
integer array, optional
A list of specific passages to return

Partner: Users

Create User (Partner)

Example response

{
    "first_name": null,
    "alternate_email": null,
    "username": "testuser",
    "created_at": "2017-06-19T20:17:21Z",
    "active": true,
    "deleted_at": null,
    "email_verified": false,
    "metadata": {},
    "updated_at": "2017-06-19T20:17:21Z",
    "email": null,
    "address": null,
    "user_groups": [],
    "preferred_language": "en",
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": null,
    "site_id": 19
}

HTTP Request

POST https://api.ysasecure.com/v2/partner/users/

HTTP Post Params

Parameter Description Default
token
string
Your API token
user[username]
string
The login username to be created
user[site_id]
integer
Your Measure site ID
user[first_name]
string, optional
First name of the new user
user[last_name]
string, optional
Last name of the new user
user[email]
string, optional
Email address for the new user
user[alternate_email]
string, optional
Alternate email for the new user (incase they lose access to their account)
user[address_attributes][address1]
string
Street address
user[address_attributes][address2]
string, optional
Secondary street address input (for apartment unit number, etc)
user[address_attributes][city]
string
City
user[address_attributes][province]
string, optional
Province or state
user[address_attributes][country]
string
Country
user[address_attributes][postal_code]
string, optional
Postal code or zip code
user[metadata]
object, optional
Additional metadata to include with the new user
user[preferred_language]
string, optional
Locale string for the user’s preferred language
send_email
boolean, optional
Whether or not to send the user a confirmation email upon creation true

Show User (Partner)

Example Response

{
    "email_verified": false,
    "first_name": null,
    "username": "testuser",
    "created_at": "2017-06-19T20:17:21Z",
    "active": true,
    "deleted_at": null,
    "alternate_email": null,
    "metadata": {},
    "user_groups": [],
    "updated_at": "2017-06-19T20:17:21Z",
    "email": null,
    "address": null,
    "preferred_language": "en",
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": null,
    "site_id": 19
}

HTTP Request

GET https://api.ysasecure.com/v2/partner/users/<user id>

HTTP Get Params

Parameter Description
user id
integer
ID of the user to retrieve
token
string
Your API token
site_id
integer
ID of the site that the user belongs to

Update User (Partner)

Example response after changing the demo user’s first name, last name, and email

{
    "deleted_at": null,
    "first_name": "Demo",
    "email_verified": false,
    "alternate_email": null,
    "preferred_language": "en",
    "username": "testuser",
    "created_at": "2017-06-19T20:17:21Z",
    "active": true,
    "metadata": {},
    "updated_at": "2017-06-19T20:30:07Z",
    "email": "testemail@getyardstick.com",
    "address": null,
    "user_groups": [],
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": "User",
    "site_id": 19
}

HTTP Request

PUT https://api.ysasecure.com/v2/partner/users/<user_id>

HTTP Put Params

Parameter Description
user id
integer
ID of the user to retrieve
token
string
Your API token
site_id
integer
ID of the site that the user belongs to
user[username]
string
The login username to be created
user[site_id]
integer
Your Measure site ID
user[first_name]
string, optional
First name of the new user
user[last_name]
string, optional
Last name of the new user
user[email]
string, optional
Email address for the new user
user[alternate_email]
string, optional
Alternate email for the new user (incase they lose access to their account)
user[address_attributes][address1]
string
Street address
user[address_attributes][address2]
string, optional
Secondary street address input (for apartment unit number, etc)
user[address_attributes][city]
string
City
user[address_attributes][province]
string, optional
Province or state
user[address_attributes][country]
string
Country
user[address_attributes][postal_code]
string, optional
Postal code or zip code
user[metadata]
object, optional
Additional metadata to include with the new user
user[preferred_language]
string, optional
Locale string for the user’s preferred language

Destroy User (Partner)

Example response

{
    "deleted_at": "2017-06-19T20:32:56Z",
    "first_name": "Demo",
    "email_verified": false,
    "alternate_email": null,
    "preferred_language": "en",
    "username": "testuser",
    "created_at": "2017-06-19T20:17:21Z",
    "active": true,
    "metadata": {},
    "updated_at": "2017-06-19T20:32:56Z",
    "email": "testemail@getyardstick.com",
    "address": null,
    "user_groups": [],
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": "User",
    "site_id": 19
}

HTTP Request

DELETE https://api.ysasecure.com/v2/partner/users/<user_id>

HTTP Delete Params

Parameter Description
user id
integer
ID of the user to retrieve
token
string
Your API token
site_id
integer
ID of the site that the user belongs to

Partner: Grants

Index Grants (Partner)

Example response

[
    {
        "type": "ExamGrant",
        "user_id": 544,
        "deleted_at": null,
        "created_at": "2017-06-19T21:33:54Z",
        "grantable_id": 30,
        "remaining_uses": null,
        "attempts_count": 0,
        "grantable_type": "Exam",
        "exam": {
            "marking_deadline_in_days": 0,
            "metadata": {},
            "name": "Demo Exam",
            "id": 30
        },
        "exam_form_group": "active",
        "metadata": {},
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://measure-demo.ysasecure.com/grants/108/bookings/new"
        },
        "updated_at": "2017-06-19T21:33:54Z",
        "expire_at": null,
        "num_uses": null,
        "allow_sittings_start_at": null,
        "exam_form_id": 88,
        "start_at": "2017-06-19T21:33:54Z",
        "parent_grant_id": null,
        "id": 10886,
        "exam_form": {
            "deleted_at": null,
            "created_at": "2017-01-25T14:56:29Z",
            "active": true,
            "updated_at": "2017-01-25T14:56:29Z",
            "name": "Form 1",
            "id": 88
        },
        "allow_sittings_end_at": null,
        "user": {
            "first_name": null,
            "alternate_email": null,
            "preferred_language": "en",
            "username": "testuser",
            "deleted_at": null,
            "created_at": "2017-06-19T21:30:09Z",
            "active": true,
            "user_groups": [],
            "metadata": {},
            "updated_at": "2017-06-19T21:30:09Z",
            "email_verified": false,
            "email": null,
            "address": null,
            "alternate_email_verified": false,
            "id": 544,
            "last_name": null,
            "site_id": 0
        }
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/partner/users/<user_id>/grants

HTTP Get Params

Parameter Description
user id
integer
ID of the user to retrieve grants from
token
string
Your Measure API token
site_id
integer
ID of the site that the user and grant belongs to

Create Grant (Partner)

Example response

[
    {
        "allow_sittings_start_at": null,
        "num_uses": 2,
        "type": "ExamGrant",
        "user_id": 544,
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
        },
        "exam_form": null,
        "allow_sittings_end_at": null,
        "parent_grant_id": null,
        "user": {
            "first_name": null,
            "username": "testuser",
            "created_at": "2017-06-19T21:30:09Z",
            "user_groups": [],
            "alternate_email_verified": false,
            "active": true,
            "metadata": {},
            "updated_at": "2017-06-19T21:30:09Z",
            "email_verified": false,
            "email": null,
            "address": null,
            "preferred_language": "en",
            "id": 544,
            "deleted_at": null,
            "alternate_email": null,
            "last_name": null,
            "site_id": 0
        },
        "exam_form_group": "active",
        "created_at": "2017-06-22T20:45:44Z",
        "exam": {
            "marking_deadline_in_days": 0,
            "metadata": {},
            "name": "Demo Exam",
            "id": 30
        },
        "exam_form_id": null,
        "metadata": {},
        "updated_at": "2017-06-22T20:45:44Z",
        "expire_at": null,
        "grantable_id": 30,
        "attempts_count": 0,
        "remaining_uses": 2,
        "start_at": "2017-06-22T14:45:44-06:00",
        "grantable_type": "Exam",
        "id": 109,
        "deleted_at": null
    }
]

HTTP Request

POST https://api.ysasecure.com/v2/partner/users/<user_id>/grants

HTTP Post Params

Parameter Description
user id
integer
ID of the user the grant will belong to
token
string
Your Measure API token
site_id
integer
ID of the site that the user and grant belong to
grantable[id]
integer, optional
Measure’s Exam/Course ID
grantable[partner_id]
string, optional
Your configured Partner ID
grantable[site_id]
integer, optional
Site ID associated with the grantable[partner_id]
grantable[type]
string
Either “Exam” or “Edition”
grant[num_uses]
integer
Number of attempts the candidate is allowed
grant[start_at]
time with zone, optional
Exams will be available from this time
grant[expire_at]
time with zone, optional
Exams will not be available after this date
grant[allow_sittings_start_at]
time with zone, optional
Only allow booking into sessions starting after the given time
grant[allow_sittings_end_at]
time with zone, optional
Only allow booking into sessions starting before the given time
grant[time_zone_name]
timezone, optional
Time zone that the grant is being assigned within
grant[exam_form_id]
string, optional
Measure’s Exam Form ID (if you want to grant a specific form)
grant[metadata]
object, optional
Any additional meta data you’d like to include
grant[send_email]
boolean, optional
Any additional meta data you’d like to include

Show Grant (Partner)

Example response

[
    {
        "type": "ExamGrant",
        "user_id": 544,
        "deleted_at": null,
        "created_at": "2017-06-19T21:33:54Z",
        "grantable_id": 30,
        "remaining_uses": null,
        "attempts_count": 0,
        "grantable_type": "Exam",
        "exam": {
            "marking_deadline_in_days": 0,
            "metadata": {},
            "name": "Demo Exam",
            "id": 30
        },
        "exam_form_group": "active",
        "metadata": {},
        "exam_launch_status": {
            "status": "requires_booking",
            "launch_url": "https://measure-demo.ysasecure.com/grants/108/bookings/new"
        },
        "updated_at": "2017-06-19T21:33:54Z",
        "expire_at": null,
        "num_uses": null,
        "allow_sittings_start_at": null,
        "exam_form_id": 88,
        "start_at": "2017-06-19T21:33:54Z",
        "parent_grant_id": null,
        "id": 10886,
        "exam_form": {
            "deleted_at": null,
            "created_at": "2017-01-25T14:56:29Z",
            "active": true,
            "updated_at": "2017-01-25T14:56:29Z",
            "name": "Form 1",
            "id": 88
        },
        "allow_sittings_end_at": null,
        "user": {
            "first_name": null,
            "alternate_email": null,
            "preferred_language": "en",
            "username": "testuser",
            "deleted_at": null,
            "created_at": "2017-06-19T21:30:09Z",
            "active": true,
            "user_groups": [],
            "metadata": {},
            "updated_at": "2017-06-19T21:30:09Z",
            "email_verified": false,
            "email": null,
            "address": null,
            "alternate_email_verified": false,
            "id": 544,
            "last_name": null,
            "site_id": 0
        }
    }
]

HTTP Request

GET https://api.ysasecure.com/v2/partner/users/<user_id>/grants/<grant id>

HTTP Get Params

Parameter Description
user id
integer
ID of the user the grant belongs to
grant id
integer
ID of the grant being shown
site_id
integer
ID of the site that the user and grant belongs to
token
string
Your Measure API token

Update Grant (Partner)

Example response

{
    "type": "ExamGrant",
    "user_id": 544,
    "exam": {
        "metadata": {},
        "marking_deadline_in_days": 0,
        "name": "Demo Exam",
        "id": 30
    },
    "exam_form_id": null,
    "user": {
        "first_name": null,
        "username": "testuser",
        "created_at": "2017-06-19T21:30:09Z",
        "alternate_email_verified": false,
        "active": true,
        "email_verified": false,
        "metadata": {},
        "deleted_at": null,
        "updated_at": "2017-06-19T21:30:09Z",
        "alternate_email": null,
        "email": null,
        "address": null,
        "preferred_language": "en",
        "id": 544,
        "user_groups": [],
        "last_name": null,
        "site_id": 0
    },
    "parent_grant_id": null,
    "created_at": "2017-06-22T20:45:44Z",
    "allow_sittings_start_at": null,
    "metadata": {},
    "remaining_uses": 3,
    "exam_form": null,
    "allow_sittings_end_at": null,
    "deleted_at": null,
    "updated_at": "2017-06-22T20:59:23Z",
    "expire_at": null,
    "grantable_id": 30,
    "attempts_count": 0,
    "exam_form_group": "active",
    "start_at": "2017-06-22T20:45:44Z",
    "grantable_type": "Exam",
    "num_uses": 3,
    "id": 109,
    "exam_launch_status": {
        "status": "requires_booking",
        "launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
    }
}

HTTP Request

PUT https://api.ysasecure.com/v2/partner/users/<user_id>/grants/<grant id>

HTTP Put Params

Parameter Description
user id
integer
ID of the user the grant belongs to
grant id
integer
ID of the grant being updated
token
string
Your Measure API token
site_id
integer
ID of the site that the user and grant belongs to
grant[num_uses]
integer, optional
Number of attempts the candidate is allowed
grant[start_at]
time with zone, optional
Exams will be available from this time
grant[expire_at]
time with zone, optional
Exams will not be available after this date
grant[allow_sittings_start_at]
time with zone, optional
Only allow booking into sessions starting after the given time
grant[allow_sittings_end_at]
time with zone, optional
Only allow booking into sessions starting before the given time
grant[time_zone_name]
timezone, optional
Time zone that the grant is being assigned within
grant[exam_form_id]
string, optional
Measure’s Exam Form ID (if you want to grant a specific form)
grant[exam_form_group]
string, optional
Exam Form Group

Destroy Grant (Partner)

Example response

{
    "type": "ExamGrant",
    "user_id": 544,
    "allow_sittings_start_at": null,
    "parent_grant_id": null,
    "exam_launch_status": {
        "status": "requires_booking",
        "launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
    },
    "exam_form": null,
    "allow_sittings_end_at": null,
    "created_at": "2017-06-22T20:45:44Z",
    "num_uses": 3,
    "user": {
        "first_name": null,
        "preferred_language": "en",
        "username": "aleciatest2",
        "created_at": "2017-06-19T21:30:09Z",
        "user_groups": [],
        "alternate_email_verified": false,
        "email_verified": false,
        "active": true,
        "alternate_email": null,
        "deleted_at": null,
        "metadata": {},
        "updated_at": "2017-06-19T21:30:09Z",
        "email": null,
        "address": null,
        "id": 544,
        "last_name": null,
        "site_id": 0
    },
    "deleted_at": "2017-06-22T21:04:05Z",
    "metadata": {},
    "updated_at": "2017-06-22T21:04:05Z",
    "expire_at": null,
    "grantable_id": 30,
    "attempts_count": 0,
    "remaining_uses": 3,
    "exam_form_id": null,
    "start_at": "2017-06-22T20:45:44Z",
    "grantable_type": "Exam",
    "id": 109,
    "exam": {
        "marking_deadline_in_days": 0,
        "metadata": {},
        "name": "Demo Exam",
        "id": 30
    },
    "exam_form_group": "active"
}

HTTP Request

DELETE https://api.ysasecure.com/v2/partner/users/<user_id>/grants/<grant id>

HTTP Delete Params

Parameter Description
user id
integer
ID of the user the grant belongs to
grant id
integer
ID of the grant being deleted
token
string
Your Measure API token
site_id
integer
ID of the site that the user and grant belongs to