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
UAT url has a different format.
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.

Create or update users from attributes provided as part of the SSO payload.
Grant an exam of your choosing upon the authentication. Only a single grant can be sent at once. (Optional)
And of course:
Automatically sign the user in from your organizations portal or web store.

Note: The SSO configurations aren’t visible in the site until SSO has been enabled for your account. Please contact your customer representative for SSO enablement.

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>.

Your Measure site’s secure domain is typically something.ysasecure.com. The something can be found in the Site settings page where you find your API Token (in the address box). If you have a custom secure domain (and have setup a custom SSL certificate with us) you should use this instead.

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)
Note: Custom fields that looks like this Custom Field Data will have to be sent through the API like this custom-field-data

{
   "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)
Note: Custom fields that looks like this Custom Field Data will have to be sent through the API like this custom-field-data

{
   "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, case-sensitive `username` by which to identify the incoming user. If the username does not already exist, a new user record will be created otherwise, the existing 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 `Session`s 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 `Session`s 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"

Encryption Requirements

CRITICAL: The encryption process requires specific steps that must be followed exactly:

Step 1: Prepare JSON Payload

Create your JSON object with user (required) and optional grant attributes.

Step 2: SHA256 Hash Your API Token

You must hash your API token with SHA256 before using it as the encryption key.

encryption_key = SHA256(your_account_api_token)

Step 3: AES-256-CBC Encryption

Use the following encryption parameters:

Algorithm: AES-256-CBC
Key: SHA256 hash of your API token (from Step 2)
IV: 16-byte random initialization vector
Padding: PKCS7

Step 4: Combine IV + Encrypted Data

Prepend the 16-byte IV to the encrypted data:

combined_data = IV + encrypted_data

Step 5: Base64 Encode

Encode the combined data (IV + encrypted data) with Base64:

base64_payload = base64_encode(combined_data)

Step 6: URL Encode

CGI-escape/URL-encode the Base64 payload for use in the URL:

final_payload = url_encode(base64_payload)

Example Implementation Pseudocode:

// Your data
json_string = '{"user":{"username":"test","first_name":"Test","last_name":"User","email":"test@example.com"}}'

api_token = "your_actual_api_token"

// Step 1: Hash the API token with SHA256
hashed_key = sha256(api_token)

// Step 2: Generate random 16-byte IV
iv = random_bytes(16)

// Step 3: Encrypt with AES-256-CBC
encrypted_data = aes_256_cbc_encrypt(json_string, hashed_key, iv)

// Step 4: Combine IV + encrypted data
combined = iv + encrypted_data

// Step 5: Base64 encode
base64_result = base64_encode(combined)

// Step 6: URL encode
url_payload = url_encode(base64_result)

// Final URL
sso_url = "https://yoursite.ysasecure.com/sso?payload=" + url_payload

After decrypting the payload, the simplified SSO endpoint will:

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

It can be useful for troubleshooting purposes to look at the values of the user you’re trying to login from our UI. You can visit users, then click edit to see the username, email, first/last name, and partner ID.

If you are receiving a decryption error after attempting to use the SSO end point, please ensure you are properly CGI escaping the payload before contacting support.

If you’re being redirected to the login page after using the URL, it means there was an error logging the user in.

Username is case-sensitive. Ensure it matches exactly.

Email is also case sensitive. If username matches, and email is changed or capitalization doesn’t match, the first login attempt will fail and update the email address. The second login attempt will succeed.

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.

OAuth

Measure provides the ability to utitlize an OAuth provider for single sign on. In order to use OAuth, you will need to set up an OAuth authorization server. One such service that Measure can use as an identity provider is Okta.

IDP Setup

Once you are signed into Okta as an admin, click “Applications” on the right-hand toolbar.

Create the App

Click “Create App Integration” to create your identity provider application.

Sign-in method: OIDC - OpenID Connect
Application Type: Web Application

Then click Next.

Configure your new IDP Application

Sign-in Redirect URI’s: This value corresponds to the URL that Measure accepts OAuth callbacks for your site. This value can be found on the OAuth settings page.

Assignments - “Skip group assignment for now”

Click Save

Update API Scopes (optional)

If you would like to have a user’s consent for access to certain scopes, you will need to set up that requirement in the API. 1. Navigate to Security and select API

Click the link for the default server.
Click Scopes
Edit the scopes you would like to require consent for, and set them to Require user consent for this scope. Uncheck the box for “Block services from requesting this scope.”

By doing this, the user will be asked whether they would like to allow Measure to access these pieces of data whenever they attempt to log in.

Update API Claims

We want to return the user’s Okta ID as the subject value (or sub) in the OpenID id_token. Measure will look for a user with this value as their partner_id in order to identify which user to log in.

Navigate to Security and select API.
Click the link for the default server.
Click “Claims”
Edit the sub claim by clicking the pencil icon next to it.
Update the value to the following: (appuser != null) ? appuser.id : app.clientId

Click Save

Create a User

Now that your application is set up, you will need to create a user in Okta that will be linked to a user in Measure. You can do this by selecting the Directory -> People tab. Click Add Person and fill out the form to create the user.

Once the user is created, we will need to assign them to the the application you created earlier.

Click the user’s name to open their profile.
Click Assign Applications and assign your application. Click Save and Go Back,

The user should be able to login at this point directly to your authorization server. You can test this (if you set their password) by navigating to your applications domain; you can find this by selecting your profile in the upper right of the Okta page; below your name and email will be the domain.

Now that the Okta application is setup, we can go to Measure and configure your site to connect with your new application.

Site Configuration

You will need to configure OAuth on each of your Account’s sites; this can be done in Measure’s Administration portal under the Settings tab, selecting Single Sign On, and then selecting OAuth (if OAuth is not an available option, please reach out to your Account’s administrator to have this option turned on). After selecting OAuth as your SSO Type, the following options will populate underneath

All of these values will be found from the application in Okta.

Authorization and Token URL’s
1. In Okta, navigate to Security -> API
2. Click on the default server that you created earlier to view the server details
3. Click on the link for Metadata URI

Once clicked, a new page will open with the raw metadata. The pertinent values are near the top, authorization_endpoint and token_endpoint.

Copy these values into the Authorization URL and Token URL settings in Measure.

ClientID and Secret
1. In Okta, navigate to Applications -> Applications in the toolbar, and select your application’s name to open it’s settings.
2. The Client ID and Client Secret are listed under the Client Credentials configuration box.

Copy these values into the Client ID and Secret configuration values in Measure.

Scopes Requested
- This list is separated by spaces, the value should be openid profile email

At this stage, both Measure and Okta are configured and ready to connect users.

Connecting Users

Currently we only authenticate existing users in Measure; we do not create new users with OAuth. You’ll need to set up user on Measure(or use an existing user) and a user on Okta and connect the two.

Select a user in Okta and ensure that they have been assigned to your application.
Navigate to the Token Preview tab in your authorization server: this can be found under Security -> API -> (your server name) -> Token Preview
Enter the appropriate values in the search; here my application is named ‘My Web App’:

The returned data will have a sub data; this is what we will use for the Partner ID in Measure.

Open the user’s profile in Measure, and you’ll see a Partner ID field located near the bottom of Basic Settings. Copy the sub value from Okta into this field, and hit Save Changes.

Testing Auth Flow

You now should be completely set up to use Okta as your OAuth provider. You can test this by opening a new Incognito tab, and navigating to your Measure site’s login page, ie https://ssotest.measuredevelopment.com/login. You can find your Site Address at the bottom of your Account settings page.

It should redirect you to Okta to log in.

Enter the credentials of one of the users you’ve connected to Measure (using the steps above).

After logging into Okta, you will see the page to grant access to Measure to read your profile, email, and openid.

Once you’ve granted access, you should be redirected to the Sign-in redirect URI that you entered above, ie https://<your_site_address>.com/oauth/callback. You should now be logged into Measure.

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,
    "user_group_ids": [1],
}

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
`user[user_group_ids]` array of integers, optional	An array of existing user group IDs to assign the user

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,
    "user_group_ids": [1]
}

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
`user[user_group_ids]` array of integers, optional	An array of existing user group IDs to assign the user

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”.

Note: We do not support creating, updating, or deleting multiple grants in a single call.

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,
        "modality_types": [],
        "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,
        "modality_types": [],
        "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,
    "modality_types": [],
    "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,
        "modality_types": [],
        "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[modality_types]` string array, optional	The modality types that are allowed for this grant. The options are ‘remote’ and/or ‘test_center’ (note: this field is case-sensitive). If an empty array is passed, all available modalities will be allowed.
`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

Note: To avoid raising any errors, use either grantable[partner_id] or grantable[id], not both at the same time. If you choose to use grantable[partner_id], ensure that you define grantable[side_id] as well.

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,
    "modality_types": [],
    "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.
`grant[modality_types]` string array, optional	The modality types that are allowed for this grant. The options are ‘remote’ and/or ‘test_center’ (note: this field is case-sensitive). If an empty array is passed, all available modalities will be allowed.

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,
    "modality_types": [],
    "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

{
  "id": 227,
  "cancellation_note": null,
  "created_at": "2025-09-23T10:39:38Z",
  "updated_at": "2025-09-23T10:39:38Z",
  "deleted_at": null,
  "user": {
    "id": 4,
    "site_id": 1,
    "username": "Dean",
    "first_name": "Dean",
    "last_name": "Winchester",
    "active": true,
    "metadata": {},
    "preferred_language": "en",
    "email": "dean.winchester@gmail.com",
    "email_verified": true,
    "alternate_email": "",
    "alternate_email_verified": false,
    "created_at": "2025-07-08T09:18:02Z",
    "updated_at": "2025-09-23T10:37:41Z",
    "deleted_at": null,
    "partner_id": null,
    "jwt": null,
    "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": ""
    },
    "user_groups": []
  },
  "grant": {
    "id": 18,
    "uuid": "8201080e-f7d7-4654-8758-f97654ef98e9",
    "user_id": 4,
    "type": "ExamGrant",
    "num_uses": null,
    "remaining_uses": null,
    "attempts_count": 1,
    "metadata": {},
    "parent_grant_id": null,
    "grantable_id": 2,
    "grantable_type": "Exam",
    "start_at": "2025-10-02T18:30:00Z",
    "expire_at": null,
    "created_at": "2025-09-18T09:43:23Z",
    "updated_at": "2025-09-19T10:08:02Z",
    "deleted_at": null,
    "exam_form_id": 886,
    "exam_form_group": "active",
    "allow_sittings_start_at": "2025-10-02T07:00:00Z",
    "allow_sittings_end_at": null,
    "modality_types": [],
    "exam_launch_status": {
      "status": "show_booking_status",
      "launch_url": "https://exam-site-1-1747827405824687.meazure.localhost/grants/18/appointments"
    },
    "user": {
      "id": 4,
      "site_id": 1,
      "username": "Dean",
      "first_name": "Dean",
      "last_name": "Winchester",
      "active": true,
      "metadata": {},
      "preferred_language": "en",
      "email": "dean.winchester@gmail.com",
      "email_verified": true,
      "alternate_email": "",
      "alternate_email_verified": false,
      "created_at": "2025-07-08T09:18:02Z",
      "updated_at": "2025-09-23T10:37:41Z",
      "deleted_at": null,
      "partner_id": null,
      "jwt": null,
      "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": ""
      },
      "user_groups": []
    },
    "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
    },
    "exam": {
      "id": 2,
      "name": "Exam1",
      "marking_deadline_in_days": 0,
      "metadata": {},
      "partner_id": null
    }
  },
  "sitting": {
    "id": 5,
    "seats": null,
    "room": "",
    "private": false,
    "venue_tbd": false,
    "created_at": "2025-09-22T09:18:36Z",
    "updated_at": "2025-09-22T10:17:26Z",
    "deleted_at": null,
    "begin_booking_at": null,
    "end_booking_at": null,
    "local_start_datetime": "2025-11-02T03:30:00Z",
    "local_end_datetime": "2025-11-06T02:30:00Z",
    "cancellation_deadline": null,
    "require_purchase_before": null,
    "session_type": "exam",
    "has_waiting_list": false,
    "metadata": {},
    "venue": {
      "id": 4,
      "location": "Jaffa",
      "available_for_courses": false,
      "available_for_exams": true,
      "lab_capacity": null,
      "hours_of_operation": "",
      "notes": "",
      "details_for_user": "",
      "phone": "",
      "fax": "",
      "email": "",
      "web": "",
      "created_at": "2025-09-17T09:06:18Z",
      "updated_at": "2025-09-17T09:06:18Z",
      "deleted_at": null,
      "metadata": {},
      "translated_address": {
        "address1": "Pora Jaffa",
        "address2": "",
        "city": "Bengaluru",
        "province": "",
        "province_name": null,
        "country": "IN",
        "country_name": "India",
        "postal_code": "560102",
        "updated_at": "2025-09-17T09:06:18Z"
      }
    }
  },
  "virtual": false,
  "delivery_window": {
    "id": 11,
    "administration_id": 1,
    "name": "5696 venue",
    "uuid": "aced0cab-37d7-4908-8adb-ff9a095bfcd5",
    "archimedes_id": null,
    "created_at": "2025-09-17T08:58:44Z",
    "updated_at": "2025-09-22T10:16:25Z",
    "time_zone_name": "America/Denver",
    "time_limit_enabled": true,
    "start_at": "2025-11-01T08:30:00Z",
    "end_at": "2025-11-07T09:45:00Z",
    "multi_part_scheduling": false
  }
}

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.

Note: Currently this endpoint is not compatible with Delivery Windows.

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,
    "virtual" : false,
    "delivery_window": {
        "id": 11,
        "administration_id": 1,
        "name": "5696 venue",
        "uuid": "aced0cab-37d7-4908-8adb-ff9a095bfcd5",
        "archimedes_id": null,
        "created_at": "2025-09-17T08:58:44Z",
        "updated_at": "2025-09-22T10:16:25Z",
        "time_zone_name": "America/Denver",
        "time_limit_enabled": true,
        "start_at": "2025-11-01T08:30:00Z",
        "end_at": "2025-11-07T09:45:00Z",
        "multi_part_scheduling": false
  }
}

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,
        "modality_types": [],
        "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,
        "modality_types": [],
        "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[modality_types]` string array, optional	The modality types that are allowed for this grant. The options are ‘remote’ and/or ‘test_center’ (note: this field is case-sensitive). If an empty array is passed, all available modalities will be allowed.
`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,
        "modality_types": [],
        "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,
    "modality_types": [],
    "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
`grant[modality_types]` string array, optional	The modality types that are allowed for this grant. The options are ‘remote’ and/or ‘test_center’ (note: this field is case-sensitive). If an empty array is passed, all available modalities will be allowed.

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,
    "modality_types": [],
    "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.
`venue_start_datetime` datetime	The start time for a test center booking as per the booked test center’s time zone.
`venue_end_datetime` datetime	The end time for a test center booking as per the booked test center’s time zone.
`local_start_datetime` datetime	The start time for a test center booking as per the client site defined time zone.
`local_end_datetime` datetime	The end time for a test center booking as per the client site defined time zone.

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,
        "deleted_at": null,
        "seats": null,
        "venue_start_datetime": "2017-11-16T18:00:00Z",
        "venue_end_datetime": "2017-11-16T18:30:00Z",
        "local_start_datetime": "2017-11-16T11:15:00Z",
        "local_end_datetime": "2017-11-16T15:45: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
    },
    "start_datetime": "2017-11-10T22:00:00Z",
    "created_at": "2017-11-01T16:08:47Z",
    "attendance_status": "booked",
    "updated_at": "2017-11-10T22:02:47Z",
    "end_datetime": "2017-11-10T22:30:00Z",
    "no_show": false,
    "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

{
  "federal_tax_code":"CAHST",
  "provincial_tax_code":null,
  "cancellation_note":null,
  "metadata":{},
  "shipping":0,
  "status":"Paid",
  "tax_region":"CAAB",
  "billing_address":{
    "id":821272,
    "account_id":132,
    "address1":"Unit 10",
    "address2":null,
    "province":"AB",
    "city":"Edmonton",
    "country":"CA",
    "time_zone_name":null,
    "country_name":"Canada",
    "created_at":"2025-03-10T16:56:13Z",
    "latitude":null,
    "province_name":"Alberta",
    "longitude":null,
    "postal_code":"T6X1T5",
    "updated_at":"2025-03-10T16:56:13Z"
  },
  "payment_type_name":null,
  "shipping_address":null,
  "created_at":"2025-03-10T16:55:47Z",
  "discount":0,
  "tax":50,
  "updated_at":"2025-03-10T16:56:17Z",
  "bookings":[
    {
      "sitting":{
        "venue_tbd":false,
        "room":"",
        "virtual_end_datetime":"2025-03-15T00:00:00Z",
        "local_start_datetime":null,
        "id":121567,
        "has_waiting_list":false,
        "require_purchase_before":null,
        "metadata":{},
        "session_type":"exam",
        "venue":null,
        "venue_end_datetime":null,
        "venue_start_datetime":null,
        "local_end_datetime":null,
        "seats":null,
        "deleted_at":null,
        "created_at":"2025-03-10T16:46:50Z",
        "virtual_start_datetime":"2025-03-12T06:00:00Z",
        "cancellation_deadline":null,
        "private":false,
        "updated_at":"2025-03-10T19:52:32Z",
        "begin_booking_at":null,
        "end_booking_at":null
      },
      "virtual_results":{
        "completed_exam":"",
        "exception_category":"",
        "exception_subcategory":"",
        "exception_item":"",
        "exception_description":""
      },
      "cancellation_note":null,
      "id":2000008,
      "metadata":{},
      "no_show":true,
      "end_datetime":"2025-03-13T21:00:00Z",
      "no_show_reason":null,
      "user":{
        "email":"candidate@email.com",
        "display_name":"Test 1",
        "email_verified":true,
        "preferred_language":"en",
        "id":846516,
        "metadata":{},
        "partner_id":null,
        "address":{
          "id":820230,
          "account_id":132,
          "address1":"Unit 10 10",
          "address2":"Canada ",
          "province":"AB",
          "city":"Edmonton",
          "country":"CA",
          "time_zone_name":null,
          "country_name":"Canada",
          "created_at":"2022-08-15T16:45:15Z",
          "latitude":null,
          "province_name":"Alberta",
          "longitude":null,
          "postal_code":"t6x2a8",
          "updated_at":"2022-08-15T16:45:15Z"
        },
        "user_name":"Grant12",
        "full_name":"Test 1",
        "first_name":"Test",
        "username":"Grant12",
        "last_name":"1",
        "deleted_at":null,
        "alternate_email_verified":false,
        "created_at":"2022-01-05T19:13:11Z",
        "active":true,
        "alternate_email":"",
        "updated_at":"2025-08-21T13:33:01Z"
      },
      "start_datetime":"2025-03-13T20:00:00Z",
      "grant":{
        "user_id":846516,
        "remaining_uses":2,
        "id":1602896,
        "parent_grant_id":null,
        "grantable_type":"Exam",
        "allow_sittings_end_at":null,
        "expire_at":null,
        "exam_form_id":null,
        "metadata":{},
        "grantable_id":3526,
        "start_at":"2025-03-10T16:56:14Z",
        "allow_sittings_start_at":null,
        "order_id":529694,
        "exam_form_group":"unknown",
        "num_uses":3,
        "uses":1,
        "created_at":"2025-03-10T16:56:14Z",
        "deleted_at":null,
        "updated_at":"2025-03-10T16:56:14Z",
        "type":"ExamGrant"
      },
      "virtual_end_datetime":"2025-03-13T21:00:00Z",
      "deleted_at":null,
      "time_zone_name":"America/Denver",
      "virtual_start_datetime":"2025-03-13T20:00:00Z",
      "confirmed":true,
      "created_at":"2025-03-10T16:56:14Z",
      "updated_at":"2025-06-30T06:16:38Z",
      "type":"VirtualBooking",
      "attendance_status":"absent"
    }
  ],
  "billing_name":"candidate",
  "id":529694,
  "currency":"CAD",
  "total":1050,
  "federal_tax_amount":50,
  "provincial_tax_amount":0,
  "paid_at":"2025-03-10T16:56:16Z",
  "buyer_type":"User",
  "subtotal":1000,
  "deleted_at":null,
  "tax_data":{
    "tax_kind":"GST",
    "federal_tax_description":"5% GST, Canada",
    "provincial_tax_description":null
  },
  "delivery_method":"online",
  "shipped":false,
  "sitting":{
    "venue_tbd":false,
    "room":"",
    "virtual_end_datetime":"2025-03-15T00:00:00Z",
    "local_start_datetime":null,
    "id":121567,
    "has_waiting_list":false,
    "require_purchase_before":null,
    "metadata":{

    },
    "session_type":"exam",
    "venue":null,
    "venue_end_datetime":null,
    "venue_start_datetime":null,
    "local_end_datetime":null,
    "seats":null,
    "deleted_at":null,
    "created_at":"2025-03-10T16:46:50Z",
    "virtual_start_datetime":"2025-03-12T06:00:00Z",
    "cancellation_deadline":null,
    "private":false,
    "updated_at":"2025-03-10T19:52:32Z",
    "begin_booking_at":null,
    "end_booking_at":null
  },
  "order_items":[
    {
      "amount":1000,
      "quantity":1,
      "price":1000,
      "product":{
        "name":"Booking Purchase",
        "metadata":{},
        "id":9049,
        "created_at":"2020-07-31T20:01:43Z",
        "price_in_cents":1000,
        "deleted_at":null,
        "price":10.0,
        "active":true,
        "updated_at":"2021-05-17T14:53:48Z",
        "delivery_method":"online",
        "delivery_method_name":"Online"
      },
      "discount_in_cents":0
    }
  ],
  "tracking_code":null,
  "buyer":{
    "email":"candidate@email.com",
    "display_name":"Test 1",
    "email_verified":true,
    "preferred_language":"en",
    "id":846516,
    "metadata":{},
    "partner_id":null,
    "address":{
      "id":820230,
      "account_id":132,
      "address1":"Unit 10 10",
      "address2":"Canada ",
      "province":"AB",
      "city":"Edmonton",
      "country":"CA",
      "time_zone_name":null,
      "country_name":"Canada",
      "created_at":"2022-08-15T16:45:15Z",
      "latitude":null,
      "province_name":"Alberta",
      "longitude":null,
      "postal_code":"t6x2a8",
      "updated_at":"2022-08-15T16:45:15Z"
    },
    "user_name":"Grant12",
    "full_name":"Test 1",
    "first_name":"Test",
    "username":"Grant12",
    "last_name":"1",
    "deleted_at":null,
    "alternate_email_verified":false,
    "created_at":"2022-01-05T19:13:11Z",
    "active":true,
    "alternate_email":"",
    "updated_at":"2025-08-21T13:33:01Z"
  }
}

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).

Important Attributes

Attribute	Description
`venue_start_datetime` datetime	The start time for a test center booking as per the booked test center’s time zone.
`venue_end_datetime` datetime	The end time for a test center booking as per the booked test center’s time zone.
`local_start_datetime` datetime	The start time for a test center booking as per the client site defined time zone.
`local_end_datetime` datetime	The end time for a test center booking as per the client site defined time zone.

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,
        "venue_start_datetime": "2023-11-28T05:00:00Z",
        "venue_end_datetime": "2023-11-30T05:00:00Z",
        "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,
    "voided": false,
    "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
}

User Exam Pass Fail

Triggered whenever a UserExam has had results released. The UserExam must be scored.

This webhook is used primarily for informing partner systems as to whether the attempt was a Pass or Fail. This webhook specifically does not include details regarding score, competency area breakdowns, proficiencies, or details about when the candidate took the exam. For additional details such as those mentioned, we recommend the User Exam Result webhook.

Example Payload


{
  "results": {
    "passed": true,
    "pending_review": false,
    "global_attempt_number": 1,
    "marking_complete": true,
    "attempt_number": 1
  },

  "id": 342,
  "exam": {
    "id": 45,
    "name": "Exam Review Feature",
    "proctored": false
  },
  "exam_grant": {
        "expire_at": null,
        "grantable_id": 1306,
        "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,
        "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,
        "metadata": {}
    },

  "user": {
    "id": 1,
    "username": "user_1",
    "email": "info+1@yardsticksoftware.com",
    "first_name": "Catherine",
    "last_name": "Goodwin",
    "partner_id": null,
    "metadata": {
      "additional_info": {
        "birthday": "20080314"
      }
    }
  }
}

User Exam Result

Triggered whenever a UserExam has had results released. The UserExam must be scored.

Example Payload

{
  "user": {
    "id": 5,
    "username": "user-1728444546624",
    "email": "1728444546624@example.com",
    "first_name": "first-name-1728444546624",
    "last_name": "last-name-1728444546624",
    "partner_id": null,
    "metadata": {}
  },
  "exam": {
    "id": 1,
    "name": "Exam 1",
    "proctored": false
  },
  "parts": [
    {
      "time_elapsed_in_seconds": 16.76900000000001,
      "started_at": "2024-10-15T20:53:26Z",
      "number_of_questions": 9,
      "finished_at": "2024-10-15T20:53:46Z",
      "break_length_in_minutes": null,
      "time_limit_in_minutes": 0
    }
  ],
  "results": {
    "parent_user_exam_id": 1,
    "rescored?": false,
    "competency_areas": [
      {
        "name": "9-788b6998fe99b9d9b0ee25d920fc196f",
        "num_correct": 1,
        "items_count": 3,
        "correct_points": 1,
        "total_points": 3,
        "proficiency": {
          "proficiency_level": "deficit",
          "score_type": "raw"
        }
      },
      {
        "name": "10-788b6998fe99b9d9b0ee25d920fc196f",
        "num_correct": 1,
        "items_count": 1,
        "correct_points": 1,
        "total_points": 1,
        "proficiency": {
          "proficiency_level": "strength",
          "score_type": "raw"
        }
      }
    ],
    "points": 5,
    "attempt_number": 1,
    "global_attempt_number": 1,
    "answered": 9,
    "correct": 5,
    "pending_review": false,
    "time_elapsed_in_seconds": 16.76900000000001,
    "total_points": 9,
    "marking_complete": true,
    "show_results": true,
    "equated_points": null,
    "scaled_points": null,
    "passed": true,
    "score": 55.56,
    "incorrect": 4,
    "started_at": "2024-10-15T20:53:26Z",
    "skipped": 0,
    "finished_at": "2024-10-15T20:53:46Z",
    "equated_score": null
  },
  "id": 188,
}

User Exam Results V2

Triggered whenever a UserExam has had results released. The UserExam must be scored. This is an enhanced version of the User Exam Result webhook that includes additional competency area details and language information.

This webhook includes a new calculated field called Adjusted Correct Points. Available for each competency area, Adjusted Correct Points uses this calculation: ([raw score on the competency] / [Total raw score]) * [adjusted total score]

Example Payload

{
  "parts": [
    {
      "time_limit_in_minutes": 180,
      "finished_at": "2025-12-19T17:47:38Z",
      "time_elapsed_in_seconds": 155.3169999999999,
      "started_at": "2025-12-19T17:45:00Z",
      "break_length_in_minutes": null,
      "number_of_questions": 71
    }
  ],
  "exam_form": {
    "name": "DEMO BASE A",
    "deleted_at": null,
    "retest_only": false,
    "updated_at": "2025-12-02T21:16:29Z",
    "id": 13400,
    "created_at": "2017-11-27T20:46:21Z"
  },
  "results": {
    "correct": 15,
    "score": 34.5,
    "equated_score": 43.5,
    "passed": false,
    "global_attempt_number": 1,
    "finished_at": "2025-12-19T17:47:38Z",
    "total_points": 200.0,
    "attempt_number": 1,
    "equated_points": 87.0,
    "scaled_points": null,
    "marking_complete": true,
    "started": "2025-12-19T17:45:00Z",
    "incorrect": 56,
    "skipped": 0,
    "points": 69.0,
    "answered": 71,
    "time_elapsed_in_seconds": 155.3169999999999,
    "elapsed": 155.3169999999999,
    "started_at": "2025-12-19T17:45:00Z",
    "finished": "2025-12-19T17:47:38Z"
  },
  "id": 1226636,
  "competency_areas": [
    {
      "id": 990,
      "name": "Competency_Area_2",
      "num_correct": 24,
      "items_count": 71,
      "correct_points": 69,
      "total_points": 200,
      "proficiency": {
        "proficiency_level": "concerns",
        "score_type": "raw"
      },
      "adjusted_correct_points": 105.0
    },
    {
      "id": 991,
      "name": "Competency_Area_3",
      "num_correct": 24,
      "items_count": 71,
      "correct_points": 69,
      "total_points": 200,
      "proficiency": {
        "proficiency_level": "concerns",
        "score_type": "raw"
      },
      "adjusted_correct_points": 105.0
    }
  ],
  "language": {
    "code": "en",
    "name": "English",
    "translated_name": "English"
  },
  "exam": {
    "name": "DEMO EXAM MANAGEMENT",
    "partner_id": null,
    "proctored": true,
    "id": 988
  },
  "booking": {
    "grant": {
      "user_id": 3000817,
      "order_id": null,
      "deleted_at": null,
      "exam_form_id": 13400,
      "num_uses": null,
      "id": 1606864,
      "metadata": {},
      "exam_form_group": "active",
      "allow_sittings_start_at": null,
      "allow_sittings_end_at": null,
      "created_at": "2025-12-19T17:43:35Z",
      "grantable_id": 988,
      "grantable_type": "Exam",
      "expire_at": null,
      "start_at": "2025-12-19T17:43:35Z",
      "remaining_uses": null,
      "parent_grant_id": null,
      "type": "ExamGrant",
      "uses": 1,
      "updated_at": "2025-12-19T17:43:35Z"
    },
    "deleted_at": null,
    "sitting": {
      "virtual_end_datetime": "2025-12-24T00:00:00Z",
      "deleted_at": null,
      "local_end_datetime": null,
      "cancellation_deadline": null,
      "id": 122304,
      "has_waiting_list": false,
      "begin_booking_at": null,
      "venue_tbd": false,
      "end_booking_at": null,
      "virtual_start_datetime": "2025-12-20T13:00:00Z",
      "venue": null,
      "metadata": {},
      "require_purchase_before": null,
      "created_at": "2025-12-18T14:52:54Z",
      "session_type": "exam",
      "venue_end_datetime": null,
      "venue_start_datetime": null,
      "room": "",
      "local_start_datetime": null,
      "updated_at": "2025-12-18T15:13:27Z",
      "private": false,
      "seats": null
    },
    "id": 3000984,
    "time_zone_name": "America/Edmonton",
    "virtual_start_datetime": "2025-12-23T13:20:00Z",
    "metadata": {},
    "user": {
      "email": "eq7@example.com",
      "alternate_email_verified": false,
      "deleted_at": null,
      "alternate_email": "",
      "id": 3000817,
      "metadata": {},
      "email_verified": false,
      "first_name": "user7",
      "address": null,
      "preferred_language": "en",
      "full_name": "user7 test7",
      "user_name": "eq7",
      "username": "eq7",
      "last_name": "test7",
      "created_at": "2025-12-19T17:43:14Z",
      "active": true,
      "display_name": "user7 test7",
      "updated_at": "2025-12-19T17:45:00Z",
      "partner_id": null
    },
    "attendance_status": "present",
    "no_show_reason": null,
    "confirmed": true,
    "virtual_results": {
      "completed_exam": "",
      "exception_category": "",
      "exception_subcategory": "",
      "exception_item": "",
      "exception_description": ""
    },
    "cancellation_note": null,
    "start_datetime": "2025-12-23T13:20:00Z",
    "created_at": "2025-12-19T17:43:52Z",
    "no_show": false,
    "updated_at": "2025-12-19T17:47:38Z",
    "type": "VirtualBooking",
    "end_datetime": "2025-12-23T16:20:00Z",
    "virtual_end_datetime": "2025-12-23T16:20:00Z"
  },
  "user": {
    "email": "eq7@example.com",
    "username": "eq7",
    "last_name": "test7",
    "id": 3000817,
    "metadata": {},
    "partner_id": null,
    "first_name": "user7"
  }
}

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