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.

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 full size version.)

Single Sign-On

Measure’s Simplified SSO

Yardstick Measure provides a simplified secure SSO option that can perform a number of tasks.

  1. Create or update users from attributes provided as part of the SSO payload.
  2. Grant an exam of your choosing upon the authentication. (Optional)
    And of course:
  3. Automatically sign the user in from your organizations portal or web store.

Additional site configuration

You also need to specify the url of the login page of your site’s preferred Identity Provider. This can be done in Measure’s Administration portal under the Settings tab, then clicking on the Single Sign On, and selecting Simplified.

The login page url can then be set in the Endpoint field.

Usage

It’s actually quite simple on the surface. All you need is a form in your candidate’s browser to POST to the URL:

https://<your Measure site's secure domain>/sso?payload=<encrypted payload>.

The heavy lifting all comes from the encrypted payload. The unencrypted payload is a JSON object comprised of two elements: A user attribute and an optional grant attribute. Each is another JSON object containing the attributes needed for each element. See the table below for details on which attributes may be included in each.

Example of a basic unencrypted JSON payload

{
   "user": {
      "username": "sso_user",
      "first_name": "sso",
      "last_name": "user",
      "email": "sso_user@email.com"
   }
}

Example of a basic unencrypted JSON payload with User metadata. Please note that the metadata keys should correspond to the labels pre-defined in the User Schemas(see Custom Fields under the Settings tab in the Administration portal)

{
   "user": {
      "username": "sso_user",
      "first_name": "sso",
      "last_name": "user",
      "email": "sso_user@email.com",
      "metadata": {
         "user-schema": {
            "user-schema-item": "user metadata"
         }
      }
   }
}

Example of a basic unencrypted JSON payload with grant attributes

{
   "user": {
      "username": "sso_user",
      "first_name": "sso",
      "last_name": "user",
      "email": "sso_user@email.com"
   },
   "grant": {
      "grantable_type": "Exam",
      "grantable_id": 10
   }
}

Example of a basic unencrypted JSON payload with grant attributes that include Grant metadata. Please note that the metadata keys should correspond to the labels pre-defined in the Grant Schemas(see Custom Fields under the Settings tab in the Administration portal)

{
   "user": {
      "username": "sso_user",
      "first_name": "sso",
      "last_name": "user",
      "email": "sso_user@email.com"
   },
   "grant": {
      "grantable_type": "Exam",
      "grantable_id": 10,
      "metadata": {
         "grant-schema": {
            "grant-schema-item": "grant metadata"
         }
      }
   }
}
User Attribute Description
user[username]
string, required
The unique username by which to identify the incoming user. If the username does not already exist a new user record will be created, otherwise the user record will be updated with the provided user attributes
user[first_name]
string, required
First name of the user to be updated or created
user[last_name]
string, required
Last name of the user to be updated or created
user[email]
string, required
Email of the user to be updated or created.(Must be unique across your Measure site.)
user[alternate_email]
string
Alternate email for the user
user[address_attributes][address1]
string
Street address
user[address_attributes][address2]
string
Secondary street address input (for apartment unit number, etc)
user[address_attributes][city]
string
City
user[address_attributes][province]
string
Province or state
user[address_attributes][country]
string
Country
user[address_attributes][postal_code]
string
Postal code or zip code
user[preferred_language]
string
Locale string for the user’s preferred language. Usually "en" or "fr".(Please refer to the ISO standard language codes). Please also note that the choices of preferred languages are limited only to the supported languages of your Site
user[partner_id]
string
Your configured Partner ID
user[metadata]
object, optional/required
Additional metadata to include with the user. Please note that this will become a required attribute if you have User metadata fields that are set as Required. You can check your User Schemas in Measure’s Administration portal by clicking on the Settings tab and selecting Custom Fields

If you wish to create an Exam grant or a Course grant as part of the sign on process, please add the following Grant attributes to your Payload content. Please note that when you are passing in Grant attributes to your payload, grant[grantable_type] and grant[grantable_id] are required attributes.

Grant Attribute Description
grant[grantable_type]
string, required
Either "Exam" or "Edition"
grant[grantable_id]
integer, required
The ID of the Exam or the Edition you wish to grant with this Sign On
grant[exam_form_id]
string
Exam Form ID (If you want to grant any specific form that belongs to the Exam you specified above)
grant[exam_form_group]
string
Either "active", "inactive", or "unknown"(default) - corresponds to selecting active or inactive forms on an Exam
grant[num_uses]
integer
Number of attempts the candidate is allowed
grant[start_at]
date with time
Exams will be available from this time(i.e. "2020-01-30 13:00:00")
grant[expire_at]
date with time
Exams will not be available after this date(i.e. "2020-01-31 13:00:00")
grant[allow_sittings_start_at]
date with time
Only allow booking into Sessions starting after the given time(i.e. "2020-01-29 13:00:00")
grant[allow_sittings_end_at]
date with time
Only allow booking into Sessions starting before the given time(i.e. "2020-01-31 13:00:00")
grant[time_zone_name]
string
Time zone that the grant is being assigned within(i.e. "America/New_York")
grant[send_email]
boolean
Whether to send an email to the user or not upon creation
grant[metadata]
object, optional/required
Additional metadata to include with the grant. Please note that this will become a required attribute if you have Grant metadata fields that are set as Required. You can check your Grant Schemas in Measure’s Administration portal by clicking on the Settings tab and selecting Custom Fields

Example encrypted payload

sample_encryption_key = "my_account_api_token"
original_unencrypted_json_object = {
   "user": {
      "username": "sso_user",
      "first_name": "sso",
      "last_name": "user",
      "email": "sso_user@email.com"
   }
}

equivalent_cgi_escaped_aes_encrypted_payload = "mWyc4pQtItEWISQ%2Fr2CHAAw9GdIY9%2B5psHe5nHDf3NpDLOT7oBTyxhtTx84%2F%0A7QSGiJ0v0nPM%2BbAlcYNnOQkCW90AjoOyA2VEwBpSkTzEV%2FYyB0j8hhLBUpJQ%0AnDWQWxCmmOCITxP%2B59%2BitSgMFsslxcvW%2BrXVPWS4KCODCc4FRh8%3D%0A"

Once you have created the JSON payload, do the following steps in order to generate the correctly formatted payload parameter that you will use in your URL:

  1. AES-encrypt the original JSON payload, using your account API token as the encryption key.
  2. CGI-escape the resulting AES-encrypted payload from Step 1.
  3. Your final payload would look something like ikUbqiutwMhi%2Bjg6WwUHyeZB76g6LdLGcrKrEV4YpvQ%3D%0A.

At the end of it all you should have a URL that looks something like:

https://demo.ysasecure.com/sso?payload=ikUbqiutwMhi%2Bjg6WwUHyeZB76g6LdLGcrKrEV4YpvQ%3D%0A

After decrypting the payload, the simplified SSO endpoint will:

  1. Attempt to find the user record if it already exists.
  2. If found will update the user record with the provided attributes.
  3. If not found will create the user using the provided attributes.
  4. If grant attributes are provided will issue a corresponding grant unless the user already has an active grant for the corresponding Exam or Course.

SAML 2.0

Measure provides SAML 2.0 single sign on. To configure SAML, navigate to Settings > Single Sign On. If the “Single Sign On” tab is not available, please contact your account manager to enable this feature.

The inputs map to values of the identity provider’s SAML metadata.

Entity ID (Required)
This is a unique value used to identify the identity provider (IDP).
In this example, the entity ID is a url but it does not have to be.

<md:EntityDescriptor entityID="https://idp.example.org" ID="_b2b8e387-343b-4c37-bc56-4848cf4692ec" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

Meazure will compare this value to the Issuer in SAML assertions it receives.
<saml:Issuer Format=urn:oasis:names:SAML:2.0:nameid-format:entity>https://idp.example.org</saml:Issuer>

Certificate Fingerprint (Required)
A fingerprint of the <X509Certificate>, used to verify authenticity of each assertion.

SAML 2.0 Endpoint (Optional)
If a user tries to navigate to Meazure without being logged in, the system will redirect them to this URL. If left blank, a message will display which notifies the user that they will need to sign in through the IDP.
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.org/sso" />

SLO Endpoint (Optional)
When configured, Single Log Out is supported.
Please note: for site-level configuration (SAML for users, not admins), IDP-initiated SLO is disabled. This is to prevent accidentally logging a user out during their exam if they are logged out of a connected service during that time.
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP Redirect"Location="https://idp.example.org/slo" />

Configuring SAML on the IDP

User SAML
See the example on the right of an SP metadata file for a Meazure site (abcd.measureuat.com).

Example of a SP metadata file for User SAML:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_10bf8f4c-05bf-452f-9b83-b871012586a1" entityID="https://abcd.measureuat.com/saml/sp/auth">
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://abcd.measureuat.com/saml/sp/slo" ResponseLocation="https://abcd.measureuat.com/saml/sp/slo"/>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://abcd.measureuat.com/saml/sp/auth" index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

You may replace abcd with your site’s short name.

Admin SAML
See the example on the right of an SP metadata file for a Meazure account (ID: 1234) on UAT.

Example of a SP metadata file for Admin SAML:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_10bf8f4c-05bf-452f-9b83-b871012586a1" entityID="https://admin.measureuat.com/saml/sp/auth">
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://admin.measureuat.com/saml/sp/slo" ResponseLocation="https://admin.measureuat.com/saml/sp/slo"/>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://admin.measureuat.com/saml/sp/auth/1234" index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

The domain and account ID would need to be updated according to the environment and account being configured.

SAML Assertions

IDP and SP initiated sign on are both supported.

Subject → NameID

In SAML assertions to Meazure, NameID should correspond to the Partner ID of the user or admin user that is logging in. We support all standard NameID formats.

Subject example: *The NameID value will be matched/saved to the user’s Partner ID in the Meazure system.

<saml:Subject>
  <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
    j.doe@example.com
  </saml:NameID>
</saml:Subject>

Attribute Statement example:

<saml:AttributeStatement>
  <saml:Attribute Name="Email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">j.doe@example.com</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="FirstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Jane</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="LastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Doe</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Attribute Statement → Additional Attributes

In the <saml:AttributeStatement> you may include user profile information to be saved or updated in Meazure.

For users (candidates) only - when name and email values are included, Meazure can create a new user if the Partner ID is not found on that site. If FirstName, LastName, and Email are included and they differ from what is currently on the user’s profile, Meazure will attempt to update the profile during login.

Note: if the email exists on another profile already, an error will occur and the user will not be able to log in until a unique email is provided.

Admin users must have a Partner ID value in their Meazure profile before they can log in with SAML. Meazure does not automatically create new admins.

Parameter Required Description
NameID Yes The unique identifier from your IDP.
Additional attributes:
FirstName No User’s first name.
LastName No User’s last name.
Email No User’s email.
ProductID No Allows you to give a candidate a grant. Not available for administrators.

Note: The product will only be granted the first time the user logs in with an assertion including particular ProductID.

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
The user’s 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
The user’s 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
The user’s 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
The user’s 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": "first_name",
    "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": "testemail@email.com",
    "address": null,
    "user_groups": [],
    "preferred_language": "en",
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": "last_name",
    "site_id": 19,
    "partner_id": null
}

Valid Country Codes

{
"AF"
"AX"
"AL"
"DZ"
"AS"
"AD"
"AO"
"AI"
"AQ"
"AG"
"AR"
"AM"
"AW"
"AC"
"AU"
"AT"
"AZ"
"BS"
"BH"
"BD"
"BB"
"BY"
"BE"
"BZ"
"BJ"
"BM"
"BT"
"BO"
"BQ"
"BA"
"BW"
"BV"
"BR"
"IO"
"BN"
"BG"
"BF"
"BI"
"KH"
"CM"
"CA"
"CV"
"KY"
"CF"
"TD"
"CL"
"CN"
"TW"
"CX"
"CC"
"CO"
"KM"
"CG"
"CD"
"CK"
"CR"
"CI"
"HR"
"CU"
"CW"
"CY"
"CZ"
"DK"
"DJ"
"DM"
"DO"
"EC"
"EG"
"SV"
"GQ"
"ER"
"EE"
"SZ"
"ET"
"FK"
"FO"
"FJ"
"FI"
"FR"
"GF"
"PF"
"TF"
"GA"
"GM"
"GE"
"DE"
"GH"
"GI"
"GR"
"GL"
"GD"
"GP"
"GU"
"GT"
"GG"
"GN"
"GW"
"GY"
"HT"
"HM"
"VA"
"HN"
"HK"
"HU"
"IS"
"IN"
"ID"
"IR"
"IQ"
"IE"
"IM"
"IL"
"IT"
"JM"
"JP"
"JE"
"JO"
"KZ"
"KE"
"KI"
"KP"
"KR"
"XK"
"KW"
"KG"
"LA"
"LV"
"LB"
"LS"
"LR"
"LY"
"LI"
"LT"
"LU"
"MO"
"MG"
"MW"
"MY"
"MV"
"ML"
"MT"
"MH"
"MQ"
"MR"
"MU"
"YT"
"MX"
"FM"
"MD"
"MC"
"MN"
"ME"
"MS"
"MA"
"MZ"
"MM"
"NA"
"NR"
"NP"
"NL"
"AN"
"NC"
"NZ"
"NI"
"NE"
"NG"
"NU"
"NF"
"MK"
"MP"
"NO"
"OM"
"PK"
"PW"
"PS"
"PA"
"PG"
"PY"
"PE"
"PH"
"PN"
"PL"
"PT"
"PR"
"QA"
"RE"
"RO"
"RU"
"RW"
"BL"
"SH"
"KN"
"LC"
"MF"
"PM"
"VC"
"WS"
"SM"
"ST"
"SA"
"SN"
"RS"
"SC"
"SL"
"SG"
"SX"
"SK"
"SI"
"SB"
"SO"
"ZA"
"GS"
"SS"
"ES"
"LK"
"SD"
"SR"
"SJ"
"SE"
"CH"
"SY"
"TJ"
"TZ"
"TH"
"TL"
"TG"
"TK"
"TO"
"TT"
"TA"
"TN"
"TR"
"TM"
"TC"
"TV"
"UG"
"UA"
"AE"
"GB"
"US"
"UM"
"UY"
"UZ"
"VU"
"VE"
"VN"
"VG"
"VI"
"WF"
"EH"
"YE"
"ZM"
"ZW"
}

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
First name of the new user
user[last_name]
string
Last name of the new user
user[email]
string
Email address for the new user
user[alternate_email]
string, optional
Alternate email for the new user (in case 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
user[partner_id]
string, optional
Your configured Partner ID
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,
    "partner_id": null
}

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,
    "partner_id": null
}

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
user[partner_id]
string, optional
Your configured Partner ID

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,
    "partner_id": null
}

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

Return a list of admin users who match the given role

[
    {
        "id": 0,
        "email": "demo0@getyardstick.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "account_id": 100,
        "roles": [
            "admin"
        ]
    },
    {
        "id": 1,
        "email": "demo1@getyardstick.com",
        "first_name": "John",
        "last_name": "Doe",
        "account_id": 100,
        "roles": [
            "admin"
        ]
    }
]

HTTP Request

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

HTTP Get Params

Parameter Description
token
string
The admin user’s Measure API token
roles
string
Only one role can be given per request. If there are spaces in the role name, use snake_case.

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,
        "uuid": "369432ce-9681-4599-b568-99ddf177d42b",
        "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,
        "uuid": "369432ce-9681-4599-b568-99ddf177d42b",
        "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,
    "uuid": "369432ce-9681-4599-b568-99ddf177d42b",
    "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,
        "uuid": "b61589bd-6350-4584-a8eb-445e483e1e41",
        "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,
    "uuid": "b61589bd-6350-4584-a8eb-445e483e1e41",
    "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,
    "uuid": "b61589bd-6350-4584-a8eb-445e483e1e41",
    "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.

Show User Exam

Example Response

{
  "id": 221,
  "user_id": 88,
  "exam_id": 92,
  "exam_form_id": 152,
  "locale": "en",
  "paths": {
    "user_exam_questions": "/v2/user_exams/221/user_exam_questions"
  },
  "finished_at": "2023-07-21T19:08:03Z",
  "user_exam": {
    "exam_form": {
      "created_at": "2023-07-17T14:16:05Z",
      "deleted_at": null,
      "id": 152,
      "name": "Competency Exam - Form1",
      "updated_at": "2023-07-17T14:16:05Z"
    },
    "passing_strategy": "total_score",
    "exam": {
      "deleted_at": null,
      "passing_strategy": "total_score",
      "metadata": {},
      "active": true,
      "require_booking": false,
      "require_proctor": "unproctored",
      "updated_at": "2023-07-17T16:19:49Z",
      "locked": false,
      "available_for_paper": false,
      "partner_id": null,
      "show_as_you_go": false,
      "created_at": "2023-07-17T14:15:44Z",
      "available_for_online": true,
      "name": "Exam with Competency",
      "strict_mode": false,
      "send_emails": true,
      "in_review": false,
      "time_limit_in_minutes": null,
      "pass_mark": 50,
      "id": 92,
      "shuffle_everything": false,
      "pass_fail_review": 0
    },
    "panel_action_events": [],
    "finished_at": "2023-07-21T19:08:03Z",
    "reviewed_at": "2023-07-21T19:08:04Z",
    "updated_at": "2023-07-21T19:08:03Z",
    "enrolment_key_establishment": null,
    "questions": [
      {
        "correct": true,
        "question_id": 10211,
        "item_bank_id": 1,
        "topic": "The Bank",
        "unanswered": false,
        "item_bank_name": "The Bank",
        "answer_score": 1,
        "total_time_in_seconds": 3,
        "competency_areas": [
          {
            "account_id": 1,
            "created_at": "2021-08-09T20:29:43Z",
            "id": 2,
            "name": "Competency1",
            "updated_at": "2023-07-21T19:05:37Z"
          }
        ],
        "capture": {
          "a": true,
          "b": false,
          "c": false,
          "d": false
        },
        "question_canonical_id": 1,
        "total_time": 3,
        "question": {
          "created_at": "2020-02-03T17:44:29Z",
          "deleted_at": null,
          "id": 10211,
          "canonical_id": 1,
          "metadata": {
            "question-metadata1": {
              "value1": "2"
            },
            "question-metadata2": {
              "value2": "2"
            }
          },
          "updated_at": "2023-07-17T16:21:06Z"
        },
        "id": 566,
        "angoff_score": null
      },
      {
        "correct": true,
        "question_id": 10230,
        "item_bank_id": 1,
        "topic": "The Bank",
        "unanswered": false,
        "item_bank_name": "The Bank",
        "answer_score": 1,
        "total_time_in_seconds": 4,
        "competency_areas": [
          {
            "account_id": 1,
            "created_at": "2020-06-04T21:06:00Z",
            "id": 1,
            "name": "Competency2",
            "updated_at": "2023-07-21T19:05:49Z"
          }
        ],
        "capture": {
          "a": true,
          "b": false,
          "c": false
        },
        "question_canonical_id": 18,
        "total_time": 4,
        "question": {
          "created_at": "2021-05-12T08:49:56Z",
          "deleted_at": null,
          "id": 10230,
          "canonical_id": 18,
          "metadata": {
            "question-metadata1": {
              "value1": "2"
            },
            "question-metadata2": {
              "value2": "2"
            }
          },
          "updated_at": "2023-07-21T19:06:44Z"
        },
        "id": 567,
        "angoff_score": null
      }
    ],
    "total_points": 2,
    "created_at": "2023-07-21T19:07:52Z",
    "sitting": null,
    "exam_time_multiplier": 1,
    "user": {
      "email": "kamehameha@email.com",
      "deleted_at": null,
      "alternate_email_verified": false,
      "address": {
        "address1": "East District",
        "address2": "",
        "province": "",
        "postal_code": "58N 018 439",
        "province_name": null,
        "updated_at": "2023-07-21T19:04:23Z",
        "city": "Tokyo",
        "country_name": "Japan",
        "country": "JP"
      },
      "email_verified": false,
      "active": true,
      "alternate_email": "",
      "metadata": {},
      "first_name": "Son",
      "username": "goku",
      "updated_at": "2023-07-21T19:07:37Z",
      "preferred_language": "en",
      "full_name": "Son Goku",
      "partner_id": null,
      "last_name": "Goku",
      "created_at": "2022-07-20T20:30:03Z",
      "user_name": "goku",
      "display_name": "Son Goku",
      "id": 88
    },
    "parts": [
      {
        "number_of_questions": 2,
        "finished_at": "2023-07-21T19:08:03Z",
        "started_at": "2023-07-21T19:07:53Z",
        "time_limit_in_minutes": 0,
        "time_elapsed_in_seconds": 6.804899999976158,
        "break_length_in_minutes": null
      }
    ],
    "number_of_questions": 2,
    "exam_grant": {
      "num_uses": null,
      "uses": 1,
      "order_id": null,
      "deleted_at": null,
      "parent_grant_id": null,
      "metadata": {},
      "exam_form_id": null,
      "exam_form_group": "active",
      "updated_at": "2023-07-21T19:07:25Z",
      "start_at": "2023-07-21T19:07:25Z",
      "expire_at": null,
      "allow_sittings_start_at": null,
      "created_at": "2023-07-21T19:07:25Z",
      "allow_sittings_end_at": null,
      "type": "ExamGrant",
      "remaining_uses": null,
      "user_id": 88,
      "id": 429,
      "grantable_id": 92,
      "grantable_type": "Exam"
    },
    "time_limit_in_minutes": 0,
    "proctor": null,
    "id": 221,
    "pass_mark": 50,
    "results": {
      "correct": 2,
      "global_attempt_number": 1,
      "equated_score": null,
      "finished_at": "2023-07-21T19:08:03Z",
      "score": 100,
      "started_at": "2023-07-21T19:07:52Z",
      "elapsed": 6.804899999976158,
      "answered": 2,
      "attempt_number": 1,
      "points": 2,
      "total_points": 2,
      "finished": "2023-07-21T19:08:03Z",
      "equated_points": null,
      "scaled_points": null,
      "passed": true,
      "incorrect": 0,
      "marking_complete": true,
      "time_elapsed_in_seconds": 6.804899999976158,
      "started": "2023-07-21T19:07:52Z",
      "skipped": 0
    },
    "language": "en",
    "booked": false,
    "proctored": false
  }
}

HTTP Request

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

HTTP Get Parameters

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

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
id
integer, optional
Filter by user exam ID
limit
integer, optional
Maximum number of user exams to return 25
with_manually_graded_questions
boolean, optional
Whether to return user exams with manually graded questions false
marker
boolean, optional
Whether to return unscored or partially scored user exams with with manually graded questions false
fully_marked
boolean, optional
Whether to return fully marked(scored) user exams false
without_assigned_markers
boolean, optional
Whether to return user exams that has no assigned markers 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
locale
string, optional
Return only user exams for that particular locale(e.g. en, fr)
user_id
integer, optional
User ID to filter user exams by
marker_id
integer, optional
Return user exams that are assigned to this marker ID
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

User Course Items

External User Course Items are created the first time a User opens a given Course. Other User Course Item types are created the first time a User opens a given Course Item in a User Course.

Update External User Course Item

Example Response

{
  "id": 27,
  "course_item_id": 19,
  "course_item_type": "ExternalCourseItem",
  "user_course_id": 32,
  "grant_id": null,
  "completion_status": "unknown",
  "complete": true,
  "created_at": "2024-01-19T21:56:57Z",
  "update_at": "2024-01-22T19:18:09Z"
}

HTTP Request

PUT https://api.ysasecure.com/v2/user_courses/<user course id>/user_course_items/<user course item id>

HTTP Put Parameters

Parameter Description
token
string
Your Measure API token
user course id
integer
The Measure ID of the user course that contains the external user course item
user course item id
integer
The Measure ID of the external user course item you want to update
user_course_item[complete]
boolean, optional
Whether the item should be marked as “completed”

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 Default
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
email_exam_result_after_marking
boolean, optional
Whether to send the Exam Result Email to the candidate after the marking is completed false

Marks Params

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

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

An Order is created whenever a Product is purchased in Measure.

Show Order

Retrieve a specific Order.

HTTP Request

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

Example Response

{
    "shipped": false,
    "buyer_type": "User",
    "billing_address": {
        "country_name": "Canada",
        "country": "CA",
        "address1": "add1",
        "city": "To",
        "address2": "",
        "province_name": "Ontario",
        "updated_at": "2018-10-10T12:44:59Z",
        "postal_code": "123",
        "province": "ON"
    },
    "provincial_tax_code": null,
    "tracking_code": null,
    "subtotal": 1000,
    "paid_at": "2018-10-10T12:44:59Z",
    "tax_data": {
        "federal_tax_description": "13% HST, Canada",
        "provincial_tax_description": null,
        "tax_kind": "HST"
    },
    "created_at": "2018-10-10T12:44:59Z",
    "discount": 0,
    "tax_info": null,
    "shipping_same_as_billing": false,
    "deleted_at": null,
    "shipping_address": null,
    "federal_tax_amount": 130,
    "sitting_id": null,
    "paid_by": {
        "type": "User",
        "email": "personal_email@email.com",
        "full_name": "FirstName LastName",
        "id": 132
    },
    "import_identifier": null,
    "payment_type_id": null,
    "provincial_tax_amount": 0,
    "shipping": 0,
    "updated_at": "2019-11-25T21:25:10Z",
    "currency": "USD",
    "site_id": 4,
    "metadata": {
        "order-notes": {
            "additional-information": "\"Additional Info\""
        }
    },
    "order_items": [
      {
        "amount": 455,
        "charge_id": 2,
        "charge_type": "Product",
        "description": "Description of product",
        "discount_in_cents": 0,
        "id": 68,
        "name": "Name of product",
        "order_id": 355,
        "promo_code_id": null,
        "quantity": 1
      }
    ],
    "tax_region": "CAON",
    "establishment_id": null,
    "payment_type_name": "bogus",
    "buyer_id": 132,
    "id": 355,
    "federal_tax_code": "CAHST",
    "delivery_method": "online",
    "custom": false,
    "cancellation_note": null
}

HTTP Get Params

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

Update Order

Updates the metadata of a specific Order.

HTTP Request

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

Example Response

{
    "shipped": false,
    "buyer_type": "User",
    "billing_address": {
        "country_name": "Canada",
        "country": "CA",
        "address1": "add1",
        "city": "To",
        "address2": "",
        "province_name": "Ontario",
        "updated_at": "2018-10-10T12:44:59Z",
        "postal_code": "123",
        "province": "ON"
    },
    "provincial_tax_code": null,
    "tracking_code": null,
    "subtotal": 1000,
    "paid_at": "2018-10-10T12:44:59Z",
    "tax_data": {
        "federal_tax_description": "13% HST, Canada",
        "provincial_tax_description": null,
        "tax_kind": "HST"
    },
    "created_at": "2018-10-10T12:44:59Z",
    "discount": 0,
    "tax_info": null,
    "shipping_same_as_billing": false,
    "deleted_at": null,
    "shipping_address": null,
    "federal_tax_amount": 130,
    "sitting_id": null,
    "paid_by": {
        "type": "User",
        "email": "personal_email@email.com",
        "full_name": "FirstName LastName",
        "id": 132
    },
    "import_identifier": null,
    "payment_type_id": null,
    "provincial_tax_amount": 0,
    "shipping": 0,
    "updated_at": "2019-11-25T21:25:10Z",
    "currency": "USD",
    "site_id": 4,
    "metadata": {
        "order-notes": {
            "additional-information": "\"Additional Info\""
        }
    },
    "tax_region": "CAON",
    "establishment_id": null,
    "payment_type_name": "bogus",
    "buyer_id": 132,
    "id": 355,
    "federal_tax_code": "CAHST",
    "delivery_method": "online",
    "custom": false,
    "cancellation_note": null
}

HTTP Put Params

Parameter Description
order id
integer
ID of the order to retrieve
token
string
Your Measure API token
order[metadata][schema][schema-item]
object
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

When the ‘show name’ setting is enabled, both the first name and last name are required for user upsert and creation. Similarly, if the ‘show email’ setting is enabled, the email becomes mandatory for user upsert and creation.“

Upsert User (Partner)

Example response

{
    "first_name": "John",
    "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": "johndoe@mail.com",
    "address": null,
    "user_groups": [],
    "preferred_language": "en",
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": "doe",
    "site_id": 19
}

HTTP Request

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

HTTP Put Params

Parameter Description Default
partner_id
integer
Partner ID of the user to retrieve
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
First name of the new user
user[last_name]
string
Last name of the new user
user[email]
string
Email address for the new user
user[alternate_email]
string, optional
Alternate email for the new user (in case 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

Create User (Partner)

Example response

{
    "first_name": "John",
    "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": "johndoe@mail.com",
    "address": null,
    "user_groups": [],
    "preferred_language": "en",
    "alternate_email_verified": false,
    "id": 544557,
    "last_name": "doe",
    "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[partner_id]
string
The Partner ID of the user
user[username]
string
The login username to be created
user[site_id]
integer
Your Measure site ID
user[first_name]
string
First name of the new user
user[last_name]
string
Last name of the new user
user[email]
string
Email address for the new user
user[alternate_email]
string, optional
Alternate email for the new user (in case 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/<partner_id>

HTTP Get Params

Parameter Description
partner_id
integer
Partner 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/<partner_id>

HTTP Put Params

Parameter Description
partner_id
integer
Partner 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 (in case 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/<partner_id>

HTTP Delete Params

Parameter Description
partner_id
integer
Partner 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/<partner_id>/grants

HTTP Get Params

Parameter Description
partner_id
integer
Partner 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/<partner_id>/grants

HTTP Post Params

Parameter Description
partner_id
integer
Partner 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/<partner_id>/grants/<grant_id>

HTTP Get Params

Parameter Description
partner_id
integer
Partner 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/<partner_id>/grants/<grant_id>

HTTP Put Params

Parameter Description
partner_id
integer
Partner 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/<partner_id>/grants/<grant_id>

HTTP Delete Params

Parameter Description
partner_id
integer
Partner 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

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 information to. Then every time 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.

Booking

Triggered whenever a Booking is created, updated, or cancelled (via the API or through the user interface). A Booking is only available for accounts that use Booking Sessions as their booking system.

Important Attributes

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

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",
        "order_id": null,
        "id": 1156792
    },
    "created_at": "2017-11-01T16:08:47Z",
    "attendance_status": "booked",
    "updated_at": "2017-11-01T16:08:47Z",
    "id": 598879
}

Booking Request

Triggered whenever a Booking Request is created, updated, or cancelled (via the API or through the user interface). A Booking Request is only available for accounts that use Booking Requests as their booking system.

Example Payload

{
    "date3":"2019-12-31",
    "date3_am":true,
    "date1":"2019-12-27",
    "date2":"2019-12-30",
    "id":16,
    "created_at":"2019-12-03T15:25:29Z",
    "booked":true,
    "state":"booked",
    "user_id":128,
    "updated_at":"2019-12-03T15:27:02Z",
    "venue":{
        "address":{
            "province":"ON",
            "updated_at":"2018-10-04T17:13:06Z",
            "address1":"365 Bloor Street East",
            "address2":null,
            "country_name":"Canada",
            "country":"CA",
            "province_name":"Ontario",
            "city":"Toronto",
            "postal_code":"M4W 3L4"
        },
        "details_for_user":null,
        "location":"Toronto Venue",
        "notes":"",
        "email":"",
        "id":18,
        "created_at":"2018-10-04T17:13:06Z",
        "lab_capacity":null,
        "updated_at":"2018-11-07T21:35:11Z",
        "available_for_exams":true,
        "available_for_courses":true,
        "metadata":{},
        "active":true,
        "hours_of_operation":"",
        "deleted_at":null,
        "phone":"",
        "web":"",
        "restricted":false,
        "fax":""
    },
    "grant":{
        "allow_sittings_end_at":null,
        "id":3928,
        "created_at":"2019-12-03T15:24:09Z",
        "grantable_id":125,
        "user_id":128,
        "updated_at":"2019-12-03T15:24:09Z",
        "expire_at":null,
        "exam_form_group":"active",
        "allow_sittings_start_at":null,
        "remaining_uses":null,
        "exam_form_id":206,
        "metadata":{},
        "parent_grant_id":null,
        "type":"ExamGrant",
        "deleted_at":null,
        "uses":0,
        "start_at":"2019-12-03T15:24:09Z",
        "grantable_type":"Exam",
        "num_uses":null,
        "order_id":null
    },
    "local_start_at":"2019-12-27T16:00:00Z",
    "user":{
        "address":null,
        "last_name":"date",
        "email":"candidate@email.com",
        "id":128,
        "created_at":"2018-10-04T17:19:26Z",
        "alternate_email":"",
        "user_name":"candidate",
        "updated_at":"2019-12-03T15:24:52Z",
        "display_name":"candi date",
        "email_verified":false,
        "metadata":{},
        "first_name":"candi",
        "full_name":"candi date",
        "active":true,
        "deleted_at":null,
        "username":"candidate",
        "preferred_language":"en",
        "alternate_email_verified":false
    },
    "date1_am":true,
    "date2_am":true,
    "local_end_at":"2019-12-27T18:00:00Z",
    "grant_id":3928,
    "venue_id":18
}

Course

Triggered when a Course is created, updated or deleted (via the API or through the user interface).

Example Payload

{
  "created_at": "2023-11-21T07:41:20Z",
  "editions": [
    {
      "distinction_mark": 90,
      "pass_mark": 80,
      "delivery_method": "online",
      "course_items": [
        {
          "upload_file_name": null,
          "label": "Sitting Exam",
          "image_width": null,
          "expire_in_days": null,
          "image_height": null,
          "upload_content_type": null,
          "require_pass": false,
          "scorm_import_job_id": null,
          "scorm_package_name": null,
          "upload_file_size": null,
          "updated_at": "2023-11-21T07:42:04Z",
          "exam_id": 3,
          "created_at": "2023-11-21T07:42:04Z",
          "upload_updated_at": null,
          "practice": true,
          "edition_id": 1,
          "type": "ExamCourseItem",
          "url": null,
          "id": 1,
          "deleted_at": null,
          "position": 1,
          "number_of_uses": 1
        }
      ],
      "gradeable_course_item_id": null,
      "updated_at": "2023-11-21T07:41:20Z",
      "manual_grade_format": null,
      "created_at": "2023-11-21T07:41:20Z",
      "language": "en",
      "name": "Elite",
      "course_id": 1,
      "id": 1,
      "deleted_at": null
    }
  ],
  "name": "New Course",
  "metadata": {},
  "hide_when_finished": false,
  "account_id": 1,
  "prereq_pass_required": false,
  "award_items": [
    {
      "award_id": 1,
      "created_at": "2024-02-05T06:27:07Z",
      "id": 1,
      "updated_at": "2024-02-05T06:27:07Z",
      "item_id": 1,
      "item_type": "Course"
    }
  ],
  "id": 1,
  "deleted_at": null,
  "updated_at": "2023-11-21T07:41:20Z"
}

Course Grant

Triggered when a Course Grant is created, updated or deleted. A Course Grant is typically created whenever a Course is granted to a User.

Example Payload

{
    "allow_sittings_end_at":null,
    "id":264,
    "created_at":"2018-04-09T13:57:22Z",
    "grantable_id":1,
    "user_id":52,
    "updated_at":"2018-04-09T13:57:22Z",
    "expire_at":null,
    "exam_form_group":"unknown",
    "allow_sittings_start_at":null,
    "remaining_uses":null,
    "exam_form_id":null,
    "metadata":{},
    "parent_grant_id":null,
    "type":"CourseGrant",
    "deleted_at":null,
    "user":{
        "address":null,
        "last_name":"date",
        "email":"candidate@mail.com",
        "id":52,
        "created_at":"2017-09-14T14:43:33Z",
        "alternate_email":"",
        "user_name":"candidate",
        "updated_at":"2018-09-12T13:33:57Z",
        "display_name":"candi date",
        "email_verified":false,
        "metadata":{},
        "first_name":"candi",
        "full_name":"candi date",
        "active":false,
        "deleted_at":null,
        "username":"candidate",
        "preferred_language":"en",
        "alternate_email_verified":false
    },
    "uses":1,
    "start_at":"2018-04-09T13:57:00Z",
    "course":{
        "name":"Course1",
        "id":1,
        "created_at":"2017-07-24T19:17:31Z",
        "updated_at":"2018-07-06T13:40:36Z",
        "metadata":{},
        "deleted_at":null
    },
    "edition":{
        "pass_mark":50.0,
        "name":"Default",
        "id":1,
        "created_at":"2017-07-24T19:17:32Z",
        "language":"en",
        "updated_at":"2018-04-09T13:39:41Z",
        "delivery_method":"online",
        "course_id":1,
        "deleted_at":null,
        "distinction_mark":90.0
    },
    "grantable_type":"Edition",
    "num_uses":null,
    "order_id":null
}

Exam

Triggered when a Exam is created, updated or deleted.

Example Payload

{
    "created_at": "2017-07-28T18:13:16Z",
    "require_booking": true,
    "id": 27,
    "locked": false,
    "available_for_paper": false,
    "pass_fail_review": 0.0,
    "partner_id": null,
    "require_proctor": "proctored",
    "updated_at": "2019-04-24T15:06:26Z",
    "time_limit_in_minutes": null,
    "deleted_at": null,
    "metadata": {},
    "strict_mode": false,
    "active": true,
    "send_emails": true,
    "available_for_online": true,
    "in_review": true,
    "name": "Hi-Steak Exam",
    "shuffle_everything": false,
    "pass_mark": 50.0,
    "show_as_you_go": false,
    "passing_strategy": "total_score"
}

Exam Grant

Triggered when an Exam Grant is created, updated or deleted. An Exam Grant is typically created whenever an Exam is granted to a User.

Example Payload

{
  "id": 105,
  "allow_sittings_start_at": null
  "allow_sittings_end_at": null,
  "deleted_at": null,
  "exam_form": null,
  "grantable_id": 1,
  "grantable_type": "Exam",
  "order_id": 245,
  "num_uses": null,
  "exam_form_group": "unknown",
  "exam_form_id": null,
  "type": "ExamGrant",
  "start_at": "2022-12-29T17:45:30Z",
  "exam": {
    "send_emails": true,
    "deleted_at": null,
    "available_for_paper": false,
    "created_at": "2022-10-10T21:28:26Z",
    "metadata": {},
    "active": true,
    "locked": false,
    "time_limit_in_minutes": 300,
    "pass_mark": 50,
    "updated_at": "2023-09-20T18:55:29Z",
    "pass_fail_review": 0,
    "name": "Exam 1",
    "id": 1,
    "strict_mode": false,
    "shuffle_everything": false,
    "in_review": false,
    "require_booking": false,
    "partner_id": null,
    "passing_strategy": "total_score",
    "require_proctor": "unproctored",
    "show_as_you_go": false,
    "available_for_online": true
  },
  "created_at": "2022-12-29T17:45:30Z",
  "remaining_uses": null,
  "metadata": {},
  "expire_at": null,
  "uses": 0,
  "parent_grant_id": null,
  "updated_at": "2022-12-29T17:45:30Z",
  "user_id": 2,
  "user": {
    "email": "info+2@yardsticksoftware.com",
    "last_name": "Jakubowski",
    "deleted_at": null,
    "created_at": "2022-10-10T21:28:26Z",
    "first_name": "Fernando",
    "metadata": {},
    "active": true,
    "alternate_email": null,
    "preferred_language": "en",
    "username": "user_2",
    "email_verified": false,
    "full_name": "Fernando Jakubowski",
    "address": {
      "address2": "Suite 200",
      "province_name": "Alberta",
      "postal_code": "T6E 6E6",
      "account_id": 1,
      "created_at": "2022-10-10T21:28:26Z",
      "country": "CA",
      "country_name": "Canada",
      "latitude": null,
      "time_zone_name": null,
      "longitude": null,
      "updated_at": "2022-10-10T21:28:26Z",
      "id": 3,
      "city": "Edmonton",
      "province": "AB",
      "address1": "8616 51 Avenue NW"
    },
    "updated_at": "2023-05-03T17:54:54Z",
    "alternate_email_verified": false,
    "display_name": "Fernando Jakubowski",
    "id": 2,
    "partner_id": null,
    "user_name": "user_2"
  }
}

Grant

Triggered when either a Course Grant or an Exam Grant has been created, updated, or destroyed. This serves as an abstraction of both the Exam Grant webhook and the Course Grant webhook.

Order

Triggered when an Order has been created, updated, or destroyed. An Order is created whenever a User purchases a Course, Exam, or Product.

Example Payload

{
    "shipping_address": null,
    "payment_type_name": "visa",
    "delivery_method": "online",
    "created_at": "2020-11-11T22:54:16Z",
    "updated_at": "2020-11-11T22:54:19Z",
    "id": 0000,
    "federal_tax_amount": 0,
    "provincial_tax_amount": 0,
    "shipped": false,
    "sitting": {
        "created_at": "2020-02-03T19:17:28Z",
        "updated_at": "2020-02-03T19:17:28Z",
        "id": 0000,
        "has_waiting_list": false,
        "room": "",
        "seats": null,
        "cancellation_deadline": "2021-01-02T04:59:00Z",
        "session_type": "exam",
        "venue": null,
        "local_start_datetime": null,
        "local_end_datetime": null,
        "deleted_at": null,
        "private": false,
        "require_purchase_before": "2020-12-02T04:59:00Z",
        "begin_booking_at": null,
        "end_booking_at": "2021-01-02T04:59:00Z",
        "venue_tbd": false
    },
    "tracking_code": null,
    "deleted_at": null,
    "buyer_type": "User",
    "tax": 0,
    "federal_tax_code": null,
    "cancellation_note": null,
    "provincial_tax_code": null,
    "tax_data": null,
    "buyer": {
        "email": "user@email.com",
        "username": "#",
        "created_at": "2020-11-11T19:45:13Z",
        "updated_at": "2020-11-11T22:09:39Z",
        "active": true,
        "id": 0000,
        "user_name": "#",
        "alternate_email": "user@email.com",
        "alternate_email_verified": true,
        "full_name": "User Name",
        "preferred_language": "en",
        "partner_id": "partner_id",
        "deleted_at": null,
        "email_verified": true,
        "first_name": "User",
        "display_name": "User Name",
        "last_name": "Name",
        "address": {
            "country_name": "Country",
            "address1": "00",
            "province_name": null,
            "city": "city",
            "postal_code": "0000",
            "updated_at": "2020-11-11T19:45:23Z",
            "address2": "",
            "country": "CC",
            "province": ""
        }
    },
    "paid_at": "2020-11-11T22:54:16Z",
    "total": 0000,
    "discount": 0,
    "shipping": 0,
    "subtotal": 0000,
    "tax_region": null,
    "currency": "USD",
    "order_items": [
        {
            "discount_in_cents": 0,
            "quantity": 1,
            "product": {
                "price_in_cents": 0000,
                "deleted_at": null,
                "delivery_method": "online",
                "created_at": "2012-01-11T07:28:21Z",
                "name": "name of product",
                "active": true,
                "id": 591,
                "updated_at": "2020-01-30T11:03:11Z",
                "delivery_method_name": "Online",
                "web-content": {
                    "custom-web-content": "contains custom web content to display for said product"
                },
                "notifications": {
                    "email": "no"
                }
            },
            "price": 0000,
            "amount": 0000
        }
    ],
    "billing_address": {
        "country_name": "Country",
        "address1": "31",
        "province_name": null,
        "city": "city",
        "postal_code": "0000",
        "updated_at": "2020-11-11T19:45:23Z",
        "address2": "",
        "country": "CC",
        "province": ""
    }
}

Product

Triggered when a Product has been created, updated, or destroyed (via the API or through the user interface).

Example Payload

{
    "show_to_warehouse": false,
    "created_at": "2023-05-05T21:01:50Z",
    "product_action": {
        "updated_at": "2023-05-08T18:13:51Z",
        "number_of_uses": 1,
        "created_at": "2023-05-08T18:13:15Z",
        "id": 25,
        "grantable_id": 8,
        "grantable_type": "Edition",
        "expire_in_days": null,
        "grantable_name": "Default"
    },
    "prices": {
        "Friends & family": 2250,
        "Regular": 2500
    },
    "active": true,
    "locales": [
        "fr"
    ],
    "metadata": {
        "extra-details": {
            "category": [
                "Bravo"
            ]
        }
    },
    "bookable_grantable_id": 0,
    "hidden": false,
    "delivery_method": "online",
    "bookable_grantable_type": null,
    "updated_at": "2023-05-08T18:15:06Z",
    "name": "Webhook Observer",
    "id": 27,
    "price_in_cents": 2500,
    "deleted_at": null,
    "description": "<p>Description of this product</p>"
}

Program

Triggered when a Program has been created, updated, or destroyed (via the API or through the user interface).

Example Payload

{
    "updated_at": "2023-11-22T08:09:01Z",
    "total_elective_courses": 0,
    "created_at": "2023-11-22T06:27:28Z",
    "name": "Trigger Prog Tes",
    "metadata": {},
    "id": 2,
    "active": true,
    "total_required_elective_courses": 0,
    "program_requirements": [
        {
            "mandatory": true,
            "updated_at": "2023-11-22T06:27:55Z",
            "program_id": 2,
            "created_at": "2023-11-22T06:27:55Z",
            "name": "Added Requirement",
            "id": 2,
            "total_required_courses": 1,
            "required_number_of_elective_courses": null,
            "requirement_courses": [
                {
                    "updated_at": "2023-11-22T06:27:55Z",
                    "created_at": "2023-11-22T06:27:55Z",
                    "course": {
                        "updated_at": "2023-11-21T07:41:20Z",
                        "created_at": "2023-11-21T07:41:20Z",
                        "name": "New Course",
                        "metadata": {},
                        "account_id": 1,
                        "id": 1,
                        "hide_when_finished": false,
                        "prereq_pass_required": false,
                        "deleted_at": null
                    },
                    "id": 2,
                    "program_requirement_id": 2,
                    "course_id": 1
                }
            ]
        }
    ],
    "total_mandatory_courses": 1
}

Sitting

Triggered when a Sitting has been created, updated, or destroyed (via the API or through the user interface).

Example Payload

{
    "sitting": {
        "created_at": "2023-11-16T19:05:30Z",
        "require_purchase_before": null,
        "metadata": {},
        "cancellation_deadline": null,
        "id": 121741,
        "virtual_start_datetime": null,
        "deleted_at": null,
        "seats": null,
        "local_start_datetime": "2023-11-28T07:00:00Z",
        "local_end_datetime": "2023-11-30T07:00:00Z",
        "session_type": "exam",
        "virtual_end_datetime": null,
        "updated_at": "2023-11-16T19:05:30Z",
        "private": false,
        "venue": {
            "email": "",
            "created_at": "2023-10-02T18:32:28Z",
            "lab_capacity": null,
            "available_for_courses": true,
            "available_for_exams": true,
            "hours_of_operation": "",
            "id": 5125,
            "restricted": false,
            "phone": "5879873950",
            "details_for_user": "",
            "availability": "all",
            "address": {
                "city": "San Diego",
                "updated_at": "2023-10-02T18:32:28Z",
                "created_at": "2023-10-02T18:32:28Z",
                "time_zone_name": "America/Los_Angeles",
                "id": 5084,
                "province": "CA",
                "account_id": 132,
                "province_name": "California",
                "country_name": "United States",
                "country": "US",
                "address1": "3604 Beyer Boulevard, San Diego, CA, USA",
                "postal_code": "12205",
                "address2": "7 Ave SW",
                "latitude": null,
                "longitude": null
            },
            "deleted_at": null,
            "metadata": {},
            "active": true,
            "web": "",
            "network": null,
            "fax": "",
            "location": "Alaska",
            "notes": "",
            "updated_at": "2023-10-02T18:32:28Z"
        },
        "begin_booking_at": null,
        "room": "",
        "venue_tbd": false,
        "has_waiting_list": false,
        "end_booking_at": null
    }
}

User

Triggered when a User is created, updated or deleted (via the API or through the user interface).

Example Payload

{
   "created_at":"2019-07-16T16:18:15Z",
   "alternate_email":"",
   "first_name":"Example",
   "address":null,
   "updated_at":"2019-07-16T16:20:27Z",
   "atc_id":null,
   "alternate_email_verified":false,
   "username":"example",
   "atc_name":null,
   "metadata":{},
   "deleted_at":null,
   "establishment":null,
   "full_name":"Example User",
   "email":"example@yas.getyardstick.com",
   "email_verified":false,
   "last_name":"User",
   "display_name":"Example User",
   "active":true,
   "preferred_language":"en",
   "id":14
}

User Course

Triggered when a User Course is created or completed. A User Course is created whenever a User starts a Course.

Example Payload

{
  "id": 26,
  "course_grant": {
    "start_at": "2024-01-24T21:05:00Z",
    "grantable_id": 1,
    "grantable_type": "Edition",
    "updated_at": "2024-01-24T21:05:58Z",
    "user_id": 3,
    "remaining_uses": null,
    "expire_at": null,
    "id": 208,
    "parent_grant_id": null,
    "created_at": "2024-01-24T21:05:58Z",
    "course": {
      "created_at": "2022-12-12T18:42:54Z",
      "name": "Course Name",
      "metadata": {},
      "account_id": 1,
      "updated_at": "2023-12-13T19:16:24Z",
      "prereq_pass_required": false,
      "hide_when_finished": false,
      "deleted_at": null,
      "id": 1
    },
    "uses": 1,
    "type": "CourseGrant",
    "edition": {
      "course_id": 1,
      "created_at": "2022-12-12T18:42:54Z",
      "name": "Default",
      "delivery_method": "online",
      "updated_at": "2022-12-12T18:42:54Z",
      "distinction_mark": 90,
      "deleted_at": null,
      "pass_mark": 80,
      "language": "en",
      "id": 1
    },
    "metadata": {},
    "allow_sittings_start_at": null,
    "allow_sittings_end_at": null,
    "user": {
      "email": "candidate@email.com",
      "user_name": "example",
      "metadata": {},
      "active": true,
      "updated_at": "2024-01-24T21:06:05Z",
      "username": "example",
      "display_name": "Example User",
      "last_name": "User",
      "full_name": "Example User",
      "id": 3,
      "alternate_email": "",
      "alternate_email_verified": false,
      "created_at": "2022-12-09T16:42:21Z",
      "preferred_language": "en",
      "partner_id": null,
      "deleted_at": null,
      "email_verified": false,
      "first_name": "Example",
      "address": {
        "country_name": "Canada",
        "account_id": 1,
        "country": "CA",
        "updated_at": "2022-12-09T16:42:21Z",
        "latitude": null,
        "province": "AB",
        "longitude": null,
        "id": 4,
        "province_name": "Alberta",
        "created_at": "2022-12-09T16:42:21Z",
        "address1": "8616 51 Avenue NW",
        "city": "Edmonton",
        "time_zone_name": null,
        "postal_code": "T6E 6E6",
        "address2": "Suite 200"
      }
    },
    "exam_form_group": "unknown",
    "order_id": null,
    "num_uses": null,
    "exam_form_id": null,
    "deleted_at": null
  },
  "finished_at": "2024-01-24T21:59:15Z",
  "result": null,
  "created_at": "2024-01-24T21:51:40Z",
  "course": {
    "created_at": "2022-12-12T18:42:54Z",
    "name": "Course Name",
    "metadata": {},
    "account_id": 1,
    "updated_at": "2023-12-13T19:16:24Z",
    "prereq_pass_required": false,
    "hide_when_finished": false,
    "deleted_at": null,
    "id": 1
  },
  "user_course_items": [
    {
      "course_item_label": "item 1",
      "user_course_id": 26,
      "score": 0,
      "complete": true,
      "course_item_id": 2,
      "updated_at": "2024-01-24T21:51:46Z",
      "created_at": "2024-01-24T21:51:46Z",
      "grant_id": null,
      "id": 49
    },
    {
      "course_item_label": "item 2",
      "user_course_id": 26,
      "score": 0,
      "complete": true,
      "course_item_id": 4,
      "updated_at": "2024-01-24T21:52:52Z",
      "created_at": "2024-01-24T21:52:52Z",
      "grant_id": null,
      "id": 50
    },
    {
      "course_item_label": "item 3",
      "user_course_id": 26,
      "score": 0,
      "complete": true,
      "course_item_id": 5,
      "updated_at": "2024-01-24T21:56:25Z",
      "created_at": "2024-01-24T21:56:25Z",
      "grant_id": null,
      "id": 51
    }
  ],
  "updated_at": "2024-01-24T21:59:15Z",
  "mark": null,
  "user": {
    "email": "candidate@email.com",
    "user_name": "example",
    "metadata": {},
    "active": true,
    "updated_at": "2024-01-24T21:06:05Z",
    "username": "example",
    "display_name": "Example User",
    "last_name": "User",
    "full_name": "Example User",
    "id": 3,
    "alternate_email": "",
    "alternate_email_verified": false,
    "created_at": "2022-12-09T16:42:21Z",
    "preferred_language": "en",
    "partner_id": null,
    "deleted_at": null,
    "email_verified": false,
    "first_name": "Example",
    "address": {
      "country_name": "Canada",
      "account_id": 1,
      "country": "CA",
      "updated_at": "2022-12-09T16:42:21Z",
      "latitude": null,
      "province": "AB",
      "longitude": null,
      "id": 4,
      "province_name": "Alberta",
      "created_at": "2022-12-09T16:42:21Z",
      "address1": "8616 51 Avenue NW",
      "city": "Edmonton",
      "time_zone_name": null,
      "postal_code": "T6E 6E6",
      "address2": "Suite 200"
    }
  },
  "participation_mark": null
}

User Course Item

Triggered when a User Course Item is created, updated, or destroyed.

External User Course Items are created the first time a User opens a given Course. Other User Course Item types are created the first time a User opens a given Course Item in a User Course.

Example Payload

{
  "course_item_label": "item 1",
  "user_course_id": 26,
  "score": 0,
  "complete": true,
  "course_item_id": 2,
  "updated_at": "2024-01-24T21:51:46Z",
  "created_at": "2024-01-24T21:51:46Z",
  "grant_id": null,
  "id": 49
}

User Exam

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.

Example Payload

{
    "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",
    "booking": {
        "virtual_results": {
            "completed_exam": "",
            "exception_category": "",
            "exception_subcategory": "",
            "exception_item": "",
            "exception_description": ""
        },
        "created_at": "2023-09-25T11:11:40-03:00",
        "virtual_end_datetime": null,
        "cancellation_note": null,
        "metadata": {},
        "no_show": false,
        "no_show_reason": null,
        "grant": {
            "created_at": "2023-09-25T11:11:40-03:00",
            "parent_grant_id": null,
            "metadata": {},
            "start_at": "2022-09-25T11:11:40-03:00",
            "expire_at": null,
            "exam_form_id": null,
            "exam_form_group": "active",
            "order_id": null,
            "num_uses": null,
            "updated_at": "2023-09-25T11:11:40-03:00",
            "grantable_id": 1613,
            "id": 1178,
            "grantable_type": "Exam",
            "type": "ExamGrant",
            "uses": 1,
            "deleted_at": null,
            "allow_sittings_start_at": null,
            "allow_sittings_end_at": null,
            "remaining_uses": null,
            "user_id": 1882
        },
        "updated_at": "2023-09-25T11:11:40-03:00",
        "time_zone_name": null,
        "id": 435,
        "user": {
            "email": "info+47@yardsticksoftware.com",
            "username": "user_47",
            "created_at": "2023-09-25T11:11:40-03:00",
            "display_name": "Danielle Conn",
            "metadata": {},
            "active": true,
            "email_verified": false,
            "alternate_email_verified": false,
            "partner_id": null,
            "last_name": "Conn",
            "full_name": "Danielle Conn",
            "first_name": "Danielle",
            "updated_at": "2023-09-25T11:11:40-03:00",
            "id": 1881,
            "preferred_language": "en",
            "alternate_email": null,
            "deleted_at": null,
            "address": {
                "updated_at": "2023-09-25T11:11:40-03:00",
                "province": "AB",
                "address1": "8616 51 Avenue NW",
                "address2": "Suite 200",
                "city": "Edmonton",
                "province_name": "Alberta",
                "postal_code": "T6E 6E6",
                "country_name": "Canada",
                "country": "CA"
            },
            "user_name": "user_47"
        },
        "virtual_start_datetime": null,
        "type": null,
        "sitting": {
            "created_at": "2023-09-25T11:11:40-03:00",
            "seats": 10,
            "local_end_datetime": "2023-09-27T11:11:40-03:00",
            "virtual_end_datetime": null,
            "has_waiting_list": false,
            "local_start_datetime": "2023-09-26T11:11:40-03:00",
            "venue": {
                "email": "yardstick@yardsticksoftware.com",
                "created_at": "2023-09-25T11:11:40-03:00",
                "deleted_at": null,
                "metadata": {},
                "active": true,
                "notes": "Lorem ipsum",
                "phone": "+1-780-409-5606",
                "updated_at": "2023-09-25T11:11:40-03:00",
                "id": 1297,
                "lab_capacity": 1337,
                "location": "Yardstick Edmonton",
                "available_for_courses": true,
                "available_for_exams": true,
                "restricted": false,
                "fax": "+1-780-409-5606",
                "hours_of_operation": "9 to 5",
                "web": "http://getyardstick.com/",
                "address": {
                    "updated_at": "2023-09-25T11:11:40-03:00",
                    "province": "AB",
                    "address1": "8616 51 Avenue NW",
                    "address2": "Suite 200",
                    "city": "Edmonton",
                    "province_name": "Alberta",
                    "postal_code": "T6E 6E6",
                    "country_name": "Canada",
                    "country": "CA"
                },
                "details_for_user": "no details"
            },
            "metadata": {},
            "begin_booking_at": null,
            "venue_tbd": false,
            "end_booking_at": null,
            "updated_at": "2023-09-25T11:11:40-03:00",
            "id": 1560,
            "room": null,
            "virtual_start_datetime": null,
            "cancellation_deadline": null,
            "deleted_at": null,
            "private": false,
            "require_purchase_before": null,
            "session_type": "exam"
        },
        "confirmed": true,
        "deleted_at": null,
        "attendance_status": "present"
    },
    "passing_strategy": "total_score",
    "proctored": true,
    "language": null,
    "exam_form": {
        "name": "Form 1",
        "deleted_at": null,
        "retest_only": false,
        "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
}

User Exam Attempt

Triggered immediately after a User completes its User Exam.

Example Payload

{
    "booked": true,
    "panel_action_events": [
        {
            "id": 1,
            "grant_id": 777250,
            "user_exam_id": 369143,
            "panel_control_id": 2,
            "panel_id": 3,
            "panel_control_label": "Label",
            "content": "Panel Content",
            "created_at": "2022-05-11T20:57:27Z"
        }
    ],
    "establishments": [
        {
            "office_type": "single",
            "created_at": "2023-10-12T20:14:44+03:00",
            "approved_by": null,
            "head_office_name": null,
            "approved_at": null,
            "is_head_office": false,
            "name": "The Establishment Name",
            "address": {
                "country": "CA",
                "updated_at": "2023-10-12T20:14:44+03:00",
                "province_name": "Alberta",
                "country_name": "Canada",
                "city": "Edmonton",
                "address1": "8616 51 Avenue NW",
                "address2": "Suite 200",
                "postal_code": "T6E 6E6",
                "province": "AB"
            },
            "deleted_at": null,
            "display_name": "The Establishment",
            "fax": null,
            "approved?": true,
            "email": null,
            "phone": null,
            "vat_status": null,
            "metadata": {},
            "vat_num": null,
            "status": "approved",
            "primary_contact_display_name": null,
            "admin_user_display_name": null,
            "updated_at": "2023-10-12T20:14:44+03:00",
            "get_price_level_name": null,
            "id": 4
        }
    ],
    "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
    },
    "establishments_selected_at": "2023-05-11T20:57:45Z",
    "finished_at": "2023-05-11T20:57:45Z",
    "parts": [
        {
            "break_length_in_minutes": null,
            "finished_at": "2023-05-11T20:57:45Z",
            "time_elapsed_in_seconds": 0,
            "number_of_questions": 2,
            "started_at": "2023-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": "2023-05-11T21:00:03Z",
        "id": 247441
    },
    "sitting": {
        "begin_booking_at": null,
        "venue_tbd": false,
        "session_type": "exam",
        "require_purchase_before": null,
        "local_end_datetime": "2023-05-12T14:30:00Z",
        "deleted_at": null,
        "seats": null,
        "local_start_datetime": "2023-05-12T12:30:00Z",
        "end_booking_at": null,
        "cancellation_deadline": null,
        "metadata": {},
        "created_at": "2023-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": "2023-07-28T19:08:37Z"
            },
            "location": "Demo Location 1",
            "created_at": null,
            "fax": "",
            "web": "",
            "available_for_exams": true,
            "email": "",
            "hours_of_operation": "",
            "updated_at": "2023-07-28T19:08:37Z",
            "id": 831
        },
        "has_waiting_list": false,
        "private": false,
        "room": "66",
        "updated_at": "2023-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": "2023-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": "2023-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": "2023-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": "2023-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": "2023-05-11T19:00:01Z",
        "parent_grant_id": null,
        "num_uses": 1,
        "remaining_uses": 0,
        "updated_at": "2023-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": "2023-05-11T20:57:45Z",
    "booking": {
        "virtual_results": {
            "completed_exam": "",
            "exception_category": "",
            "exception_subcategory": "",
            "exception_item": "",
            "exception_description": ""
        },
        "created_at": "2023-09-25T11:11:40-03:00",
        "virtual_end_datetime": null,
        "cancellation_note": null,
        "metadata": {},
        "no_show": false,
        "no_show_reason": null,
        "grant": {
            "created_at": "2023-09-25T11:11:40-03:00",
            "parent_grant_id": null,
            "metadata": {},
            "start_at": "2022-09-25T11:11:40-03:00",
            "expire_at": null,
            "exam_form_id": null,
            "exam_form_group": "active",
            "order_id": null,
            "num_uses": null,
            "updated_at": "2023-09-25T11:11:40-03:00",
            "grantable_id": 1613,
            "id": 1178,
            "grantable_type": "Exam",
            "type": "ExamGrant",
            "uses": 1,
            "deleted_at": null,
            "allow_sittings_start_at": null,
            "allow_sittings_end_at": null,
            "remaining_uses": null,
            "user_id": 1882
        },
        "updated_at": "2023-09-25T11:11:40-03:00",
        "time_zone_name": null,
        "id": 435,
        "user": {
            "email": "info+47@yardsticksoftware.com",
            "username": "user_47",
            "created_at": "2023-09-25T11:11:40-03:00",
            "display_name": "Danielle Conn",
            "metadata": {},
            "active": true,
            "email_verified": false,
            "alternate_email_verified": false,
            "partner_id": null,
            "last_name": "Conn",
            "full_name": "Danielle Conn",
            "first_name": "Danielle",
            "updated_at": "2023-09-25T11:11:40-03:00",
            "id": 1881,
            "preferred_language": "en",
            "alternate_email": null,
            "deleted_at": null,
            "address": {
                "updated_at": "2023-09-25T11:11:40-03:00",
                "province": "AB",
                "address1": "8616 51 Avenue NW",
                "address2": "Suite 200",
                "city": "Edmonton",
                "province_name": "Alberta",
                "postal_code": "T6E 6E6",
                "country_name": "Canada",
                "country": "CA"
            },
            "user_name": "user_47"
        },
        "virtual_start_datetime": null,
        "type": null,
        "sitting": {
            "created_at": "2023-09-25T11:11:40-03:00",
            "seats": 10,
            "local_end_datetime": "2023-09-27T11:11:40-03:00",
            "virtual_end_datetime": null,
            "has_waiting_list": false,
            "local_start_datetime": "2023-09-26T11:11:40-03:00",
            "venue": {
                "email": "yardstick@yardsticksoftware.com",
                "created_at": "2023-09-25T11:11:40-03:00",
                "deleted_at": null,
                "metadata": {},
                "active": true,
                "notes": "Lorem ipsum",
                "phone": "+1-780-409-5606",
                "updated_at": "2023-09-25T11:11:40-03:00",
                "id": 1297,
                "lab_capacity": 1337,
                "location": "Yardstick Edmonton",
                "available_for_courses": true,
                "available_for_exams": true,
                "restricted": false,
                "fax": "+1-780-409-5606",
                "hours_of_operation": "9 to 5",
                "web": "http://getyardstick.com/",
                "address": {
                    "updated_at": "2023-09-25T11:11:40-03:00",
                    "province": "AB",
                    "address1": "8616 51 Avenue NW",
                    "address2": "Suite 200",
                    "city": "Edmonton",
                    "province_name": "Alberta",
                    "postal_code": "T6E 6E6",
                    "country_name": "Canada",
                    "country": "CA"
                },
                "details_for_user": "no details"
            },
            "metadata": {},
            "begin_booking_at": null,
            "venue_tbd": false,
            "end_booking_at": null,
            "updated_at": "2023-09-25T11:11:40-03:00",
            "id": 1560,
            "room": null,
            "virtual_start_datetime": null,
            "cancellation_deadline": null,
            "deleted_at": null,
            "private": false,
            "require_purchase_before": null,
            "session_type": "exam"
        },
        "confirmed": true,
        "deleted_at": null,
        "attendance_status": "present"
    },
    "passing_strategy": "total_score",
    "proctored": true,
    "language": null,
    "exam_form": {
        "name": "Form 1",
        "deleted_at": null,
        "retest_only": false,
        "created_at": "2014-12-19T21:25:34Z",
        "updated_at": "2014-12-19T21:25:34Z",
        "id": 2647
    },
    "updated_at": "2023-06-09T17:27:03Z",
    "time_limit_in_minutes": 0,
    "exam_time_multiplier": 1,
    "id": 369143
}

Venue

Triggered when a Venue has been created, updated, or destroyed (via the API or through the user interface).

Example Payload

{
    "email": "",
    "details_for_user": "",
    "lab_capacity": 70,
    "available_for_courses": false,
    "available_for_exams": true,
    "hours_of_operation": "",
    "restricted": false,
    "active": true,
    "metadata": {},
    "created_at": "2023-11-14T05:34:08Z",
    "availability": "paper",
    "notes": "",
    "network": null,
    "fax": "",
    "address": {
        "postal_code": "560087",
        "province_name": null,
        "created_at": "2023-11-14T05:34:08Z",
        "account_id": 1,
        "time_zone_name": "America/Cambridge_Bay",
        "country": "IN",
        "country_name": "India",
        "latitude": null,
        "longitude": null,
        "updated_at": "2023-11-14T05:34:08Z",
        "id": 2,
        "city": "Bangalore",
        "address1": "Building A",
        "province": "",
        "address2": ""
    },
    "updated_at": "2023-11-22T06:53:00Z",
    "web": "",
    "id": 2,
    "location": "Brigade Tech Par",
    "phone": "",
    "deleted_at": null
}

Products

You may add and remove products from a user’s “Products” page using these endpoints. Use the API to show products to a user or hide them. By default, a user sees all products on a site. When you start adding visibility to specific products then we assume all other products are hidden.

For example, to show all products except for one to a user, you’ll need to add visibility to all products except for the one you want to hide. To show a user a handful of products then add visibility for those specific products. If something changes and you no longer want a user to see a product that you’ve chosen to add visibility for then make a new API request to remove visibility.

For each endpoint, the product ids which the user sees will be returned.

Add product visibility

Product visibility also depends on the Site’s Restrict visible products setting

If that setting is enabled, it is essential to explicitly grant permission for a product first using the provided endpoint below. This action is necessary to enable users to view the product.

Example response

{
    "products_granted_ids": [4950, 4958, 5393, 5406, 5415]
}

HTTP Request

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

HTTP Post Params

Parameter Description Default
token
string
Your API token
user_id
integer
The user’s ID who should have visibilty of the product
product_id
integer
The product’s ID which should be added to the Products page

Remove product visibility

Example response

{
    "products_granted_ids": [4950, 4958, 5393, 5406, 5415]
}

HTTP Request

DELETE https://api.ysasecure.com/v2/product_grants/

HTTP Post Params

Parameter Description Default
token
string
Your API token
user_id
integer
The user’s ID who should not have visibilty of the product
product_id
integer
The product’s ID which should be removed from the Products page