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 toapplication/json
- You still require the
- 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. (Optional)
And of course: - Automatically sign the user in from your organizations portal or web store.
Additional site configuration
You also need to specify the url of the login page of your site’s preferred Identity Provider.
This can be done in Measure’s Administration portal under the Settings
tab, then clicking on the Single Sign On
,
and selecting Simplified
.
The login page url can then be set in the Endpoint field.
Usage
It’s actually quite simple on the surface. All you need is a form in your candidate’s browser to POST to the URL:
https://<your Measure site's secure domain>/sso?payload=<encrypted payload>
.
The heavy lifting all comes from the encrypted payload. The unencrypted payload is a JSON object comprised of two elements: A user attribute and an optional grant attribute. Each is another JSON object containing the attributes needed for each element. See the table below for details on which attributes may be included in each.
Example of a basic unencrypted JSON payload
{
"user": {
"username": "sso_user",
"first_name": "sso",
"last_name": "user",
"email": "sso_user@email.com"
}
}
Example of a basic unencrypted JSON payload with User metadata. Please note that the metadata keys should correspond to the labels pre-defined in the
User Schemas
(seeCustom Fields
under theSettings
tab in the Administration portal)
{
"user": {
"username": "sso_user",
"first_name": "sso",
"last_name": "user",
"email": "sso_user@email.com",
"metadata": {
"user-schema": {
"user-schema-item": "user metadata"
}
}
}
}
Example of a basic unencrypted JSON payload with grant attributes
{
"user": {
"username": "sso_user",
"first_name": "sso",
"last_name": "user",
"email": "sso_user@email.com"
},
"grant": {
"grantable_type": "Exam",
"grantable_id": 10
}
}
Example of a basic unencrypted JSON payload with grant attributes that include Grant metadata. Please note that the metadata keys should correspond to the labels pre-defined in the
Grant Schemas
(seeCustom Fields
under theSettings
tab in the Administration portal)
{
"user": {
"username": "sso_user",
"first_name": "sso",
"last_name": "user",
"email": "sso_user@email.com"
},
"grant": {
"grantable_type": "Exam",
"grantable_id": 10,
"metadata": {
"grant-schema": {
"grant-schema-item": "grant metadata"
}
}
}
}
User Attribute | Description |
---|---|
user[username] string, required |
The unique username by which to identify the incoming user. If the username does not already exist a new user record will be created, otherwise the user record will be updated with the provided user attributes |
user[first_name] string, required |
First name of the user to be updated or created |
user[last_name] string, required |
Last name of the user to be updated or created |
user[email] string, required |
Email of the user to be updated or created.(Must be unique across your Measure site.) |
user[alternate_email] string |
Alternate email for the user |
user[address_attributes][address1] string |
Street address |
user[address_attributes][address2] string |
Secondary street address input (for apartment unit number, etc) |
user[address_attributes][city] string |
City |
user[address_attributes][province] string |
Province or state |
user[address_attributes][country] string |
Country |
user[address_attributes][postal_code] string |
Postal code or zip code |
user[preferred_language] string |
Locale string for the user’s preferred language. Usually "en" or "fr" .(Please refer to the ISO standard language codes). Please also note that the choices of preferred languages are limited only to the supported languages of your Site |
user[partner_id] string |
Your configured Partner ID |
user[metadata] object, optional/required |
Additional metadata to include with the user. Please note that this will become a required attribute if you have User metadata fields that are set as Required. You can check your User Schemas in Measure’s Administration portal by clicking on the Settings tab and selecting Custom Fields |
If you wish to create an Exam grant or a Course grant as part of the sign on process, please add the following
Grant attributes to your Payload content.
Please note that when you are passing in Grant attributes to your payload, grant[grantable_type]
and grant[grantable_id]
are required attributes.
Grant Attribute | Description |
---|---|
grant[grantable_type] string, required |
Either "Exam" or "Edition" |
grant[grantable_id] integer, required |
The ID of the Exam or the Edition you wish to grant with this Sign On |
grant[exam_form_id] string |
Exam Form ID (If you want to grant any specific form that belongs to the Exam you specified above) |
grant[exam_form_group] string |
Either "active" , "inactive" , or "unknown" (default) - corresponds to selecting active or inactive forms on an Exam |
grant[num_uses] integer |
Number of attempts the candidate is allowed |
grant[start_at] date with time |
Exams will be available from this time(i.e. "2020-01-30 13:00:00" ) |
grant[expire_at] date with time |
Exams will not be available after this date(i.e. "2020-01-31 13:00:00" ) |
grant[allow_sittings_start_at] date with time |
Only allow booking into 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"
Once you have created the JSON payload, do the following steps in order to generate the correctly formatted payload parameter that you will use in your URL:
- AES-encrypt the original JSON payload, using your account API token as the encryption key.
- CGI-escape the resulting AES-encrypted payload from Step 1.
- Your final payload would look something like
ikUbqiutwMhi%2Bjg6WwUHyeZB76g6LdLGcrKrEV4YpvQ%3D%0A
.
At the end of it all you should have a URL that looks something like:
https://demo.ysasecure.com/sso?payload=ikUbqiutwMhi%2Bjg6WwUHyeZB76g6LdLGcrKrEV4YpvQ%3D%0A
After decrypting the payload, the simplified SSO endpoint will:
- 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.
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. |
No | User’s email. | |
ProductID | No | Allows you to give a candidate a grant. Not available for administrators. |
Note: The product will only be granted the first time the user logs in with an assertion including particular ProductID.
Sites
Index Sites
Get a list of sites associated with your api token.
Example response
[
{
"unlock_url": "https://beta.ysasecure.com/proctors/unlock/{your token}",
"name": "Measure Demo",
"domain": "https://measure-demo.ysasecure.com",
"short_name": "measure-demo",
"id": 0
}
]
HTTP Request
GET https://api.ysasecure.com/v2/sites
HTTP Get Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
Who Am I
Self
Example response
{
"first_name": "Demo",
"klass": "AdminUser",
"roles": [
"super",
"exam_editor"
],
"account_id": 1,
"email": "demo@getyardstick.com",
"id": 51,
"last_name": "User"
}
HTTP Request
GET https://api.ysasecure.com/v2/whoami
HTTP Get Params
Parameter | Description |
---|---|
token string |
The user’s Measure API token |
Admin Users
Returns the user information for the owner of the API token.
Example response
{
"first_name": "Demo",
"roles": [
"super",
"exam_editor"
],
"account_id": 1,
"email": "demo@getyardstick.com",
"id": 51,
"last_name": "User"
}
HTTP Request
GET https://api.ysasecure.com/v2/admin_users/whoami
HTTP Get Params
Parameter | Description |
---|---|
token string |
The user’s Measure API token |
Nomad Users
Returns the user information for the owner of the API token.
Example response
{
"first_name": "Demo",
"roles": [
"super",
"exam_editor"
],
"account_id": 1,
"email": "demo@getyardstick.com",
"id": 51,
"last_name": "User"
}
HTTP Request
GET https://api.ysasecure.com/v2/nomad_users/whoami
HTTP Get Params
Parameter | Description |
---|---|
token string |
The user’s Measure API token |
Exam Form Assignments
Example Response
[
{
"exam": {
"name": "Tutorial",
"id": 1089
},
"exam_id": 1089,
"name": "Tutorial Form",
"id": 2102
},
{
"exam": {
"name": "Demo Exam",
"id": 3033
},
"exam_id": 3033,
"name": "Form 1",
"id": 8867
}
]
HTTP Request
GET https://api.ysasecure.com/v2/whoami/exam_form_assignments
HTTP Get Params
Parameter | Description |
---|---|
token string |
The user’s Measure API token |
administration_id integer, optional |
ID number of the administration associated with an exam form assignment |
Auths
Token
Returns the API token associated with an account.
Example response
{
"token": "YOUR TOKEN"
}
HTTP Request
PUT https://api.ysasecure.com/v2/auth/token
HTTP Put Params
Parameter | Description |
---|---|
email string |
Your email |
password string |
Your password |
roles array, optional |
User roles |
Proctoring
Returns the API token associated with a proctoring account.
Example response
{
"token": "YOUR TOKEN"
}
If the email/password combination is incorrect, you will receive a 401 Unauthorized error.
{
"error": "Invalid email/password combination"
}
HTTP Request
PUT https://api.ysasecure.com/v2/auth/proctoring
HTTP Put Params
Parameter | Description |
---|---|
email string |
Your email |
password string |
Your password |
roles array, optional |
User roles |
Nomad Users
Example response
{
"token": "YOUR TOKEN"
}
If the email/password combination is incorrect, you will receive a 401 Unauthorized error.
{
"error": "Invalid email/password combination"
}
HTTP Request
PUT https://api.ysasecure.com/v2/nomad_users/auth
HTTP Put Params
Parameter | Description |
---|---|
email string |
Your email |
password string |
Your password |
Users
You can manage candidate records for your site remotely using this endpoint.
Create User
Example response
{
"first_name": "first_name",
"alternate_email": null,
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"deleted_at": null,
"email_verified": false,
"metadata": {},
"updated_at": "2017-06-19T20:17:21Z",
"email": "testemail@email.com",
"address": null,
"user_groups": [],
"preferred_language": "en",
"alternate_email_verified": false,
"id": 544557,
"last_name": "last_name",
"site_id": 19,
"partner_id": null
}
Valid Country Codes
{
"AF"
"AX"
"AL"
"DZ"
"AS"
"AD"
"AO"
"AI"
"AQ"
"AG"
"AR"
"AM"
"AW"
"AC"
"AU"
"AT"
"AZ"
"BS"
"BH"
"BD"
"BB"
"BY"
"BE"
"BZ"
"BJ"
"BM"
"BT"
"BO"
"BQ"
"BA"
"BW"
"BV"
"BR"
"IO"
"BN"
"BG"
"BF"
"BI"
"KH"
"CM"
"CA"
"CV"
"KY"
"CF"
"TD"
"CL"
"CN"
"TW"
"CX"
"CC"
"CO"
"KM"
"CG"
"CD"
"CK"
"CR"
"CI"
"HR"
"CU"
"CW"
"CY"
"CZ"
"DK"
"DJ"
"DM"
"DO"
"EC"
"EG"
"SV"
"GQ"
"ER"
"EE"
"SZ"
"ET"
"FK"
"FO"
"FJ"
"FI"
"FR"
"GF"
"PF"
"TF"
"GA"
"GM"
"GE"
"DE"
"GH"
"GI"
"GR"
"GL"
"GD"
"GP"
"GU"
"GT"
"GG"
"GN"
"GW"
"GY"
"HT"
"HM"
"VA"
"HN"
"HK"
"HU"
"IS"
"IN"
"ID"
"IR"
"IQ"
"IE"
"IM"
"IL"
"IT"
"JM"
"JP"
"JE"
"JO"
"KZ"
"KE"
"KI"
"KP"
"KR"
"XK"
"KW"
"KG"
"LA"
"LV"
"LB"
"LS"
"LR"
"LY"
"LI"
"LT"
"LU"
"MO"
"MG"
"MW"
"MY"
"MV"
"ML"
"MT"
"MH"
"MQ"
"MR"
"MU"
"YT"
"MX"
"FM"
"MD"
"MC"
"MN"
"ME"
"MS"
"MA"
"MZ"
"MM"
"NA"
"NR"
"NP"
"NL"
"AN"
"NC"
"NZ"
"NI"
"NE"
"NG"
"NU"
"NF"
"MK"
"MP"
"NO"
"OM"
"PK"
"PW"
"PS"
"PA"
"PG"
"PY"
"PE"
"PH"
"PN"
"PL"
"PT"
"PR"
"QA"
"RE"
"RO"
"RU"
"RW"
"BL"
"SH"
"KN"
"LC"
"MF"
"PM"
"VC"
"WS"
"SM"
"ST"
"SA"
"SN"
"RS"
"SC"
"SL"
"SG"
"SX"
"SK"
"SI"
"SB"
"SO"
"ZA"
"GS"
"SS"
"ES"
"LK"
"SD"
"SR"
"SJ"
"SE"
"CH"
"SY"
"TJ"
"TZ"
"TH"
"TL"
"TG"
"TK"
"TO"
"TT"
"TA"
"TN"
"TR"
"TM"
"TC"
"TV"
"UG"
"UA"
"AE"
"GB"
"US"
"UM"
"UY"
"UZ"
"VU"
"VE"
"VN"
"VG"
"VI"
"WF"
"EH"
"YE"
"ZM"
"ZW"
}
Create a new user. Returns a location header indicating where the created user’s details can be found.
HTTP Request
POST https://api.ysasecure.com/v2/users
HTTP Post Params
Parameter | Description | Default |
---|---|---|
token string |
Your API token | |
user[username] string |
The login username to be created | |
user[site_id] integer |
Your Measure site ID | |
user[first_name] string |
First name of the new user | |
user[last_name] string |
Last name of the new user | |
user[email] string |
Email address for the new user | |
user[alternate_email] string, optional |
Alternate email for the new user (in case they lose access to their account) | |
user[address_attributes][address1] string |
Street address | |
user[address_attributes][address2] string, optional |
Secondary street address input (for apartment unit number, etc) | |
user[address_attributes][city] string |
City | |
user[address_attributes][province] string, optional |
Province or state | |
user[address_attributes][country] string |
Country | |
user[address_attributes][postal_code] string, optional |
Postal code or zip code | |
user[metadata] object, optional |
Additional metadata to include with the new user | |
user[preferred_language] string, optional |
Locale string for the user’s preferred language | |
user[partner_id] string, optional |
Your configured Partner ID | |
send_email boolean, optional |
Whether or not to send the user a confirmation email upon creation | true |
Show User
Example Response
{
"email_verified": false,
"first_name": null,
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"deleted_at": null,
"alternate_email": null,
"metadata": {},
"user_groups": [],
"updated_at": "2017-06-19T20:17:21Z",
"email": null,
"address": null,
"preferred_language": "en",
"alternate_email_verified": false,
"id": 544557,
"last_name": null,
"site_id": 19,
"partner_id": null
}
HTTP Request
GET https://api.ysasecure.com/v2/users/<user id>
HTTP Get Parameters
Parameter | Description |
---|---|
user id integer |
The Measure User ID of the user whose information you want to retrieve |
token string |
Your Measure API token |
Update User
Example response after changing the demo user’s first name, last name, and email
{
"deleted_at": null,
"first_name": "Demo",
"email_verified": false,
"alternate_email": null,
"preferred_language": "en",
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"metadata": {},
"updated_at": "2017-06-19T20:30:07Z",
"email": "testemail@getyardstick.com",
"address": null,
"user_groups": [],
"alternate_email_verified": false,
"id": 544557,
"last_name": "User",
"site_id": 19,
"partner_id": null
}
HTTP Request
PUT https://api.ysasecure.com/v2/users/<user id>
HTTP Put Parameters
Parameter | Description |
---|---|
token string |
Your Measure API token |
user id integer |
The Measure User ID of the user whose information you want to update |
user[username] string, optional |
The new username you’d like to assign the user |
user[first_name] string, optional |
The new first name for the user |
user[last_name] string, optional |
The new last name for the user |
user[email] string, optional |
The new email for the user |
user[alternate_email] string, optional |
The new alternate email for the user |
user[address_attributes][address1] string |
Street address |
user[address_attributes][address2] string, optional |
Secondary street address input (for apartment unit number, etc) |
user[address_attributes][city] string |
City |
user[address_attributes][province] string, optional |
Province or state |
user[address_attributes][country] string |
Country |
user[address_attributes][postal_code] string, optional |
Postal code or zip code |
user[metadata] object, optional |
Additional metadata you want to update for this user |
user[preferred_language] string, optional |
Locale string for the user’s new preferred language |
user[partner_id] string, optional |
Your configured Partner ID |
Destroy User
Example response
{
"deleted_at": "2017-06-19T20:32:56Z",
"first_name": "Demo",
"email_verified": false,
"alternate_email": null,
"preferred_language": "en",
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"metadata": {},
"updated_at": "2017-06-19T20:32:56Z",
"email": "testemail@getyardstick.com",
"address": null,
"user_groups": [],
"alternate_email_verified": false,
"id": 544557,
"last_name": "User",
"site_id": 19,
"partner_id": null
}
HTTP Request
DELETE https://api.ysasecure.com/v2/users/<user id>
HTTP Delete Parameters
Parameter | Description |
---|---|
user id integer |
The Measure User ID of the user you want to delete |
token string |
Your Measure API token |
Admin Users Index
Return a list of admin users who match the given role
[
{
"id": 0,
"email": "demo0@getyardstick.com",
"first_name": "Jane",
"last_name": "Doe",
"account_id": 100,
"roles": [
"admin"
]
},
{
"id": 1,
"email": "demo1@getyardstick.com",
"first_name": "John",
"last_name": "Doe",
"account_id": 100,
"roles": [
"admin"
]
}
]
HTTP Request
GET https://api.ysasecure.com/v2/admin_users
HTTP Get Params
Parameter | Description |
---|---|
token string |
The admin user’s Measure API token |
roles string |
Only one role can be given per request. If there are spaces in the role name, use snake_case. |
Grants
You can provide a candidate access to a specific exam via a grant in Measure. Other systems sometimes refer to this as an “eligibility record”.
Index Grants
List all grants belonging to a particular user.
Example response
[
{
"type": "ExamGrant",
"user_id": 544,
"deleted_at": null,
"created_at": "2017-06-19T21:33:54Z",
"grantable_id": 30,
"remaining_uses": null,
"attempts_count": 0,
"grantable_type": "Exam",
"exam": {
"marking_deadline_in_days": 0,
"metadata": {},
"name": "Demo Exam",
"id": 30
},
"exam_form_group": "active",
"metadata": {},
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://measure-demo.ysasecure.com/grants/108/bookings/new"
},
"updated_at": "2017-06-19T21:33:54Z",
"expire_at": null,
"num_uses": null,
"allow_sittings_start_at": null,
"exam_form_id": 88,
"start_at": "2017-06-19T21:33:54Z",
"parent_grant_id": null,
"id": 10886,
"uuid": "369432ce-9681-4599-b568-99ddf177d42b",
"exam_form": {
"deleted_at": null,
"created_at": "2017-01-25T14:56:29Z",
"active": true,
"updated_at": "2017-01-25T14:56:29Z",
"name": "Form 1",
"id": 88
},
"allow_sittings_end_at": null,
"user": {
"first_name": null,
"alternate_email": null,
"preferred_language": "en",
"username": "testuser",
"deleted_at": null,
"created_at": "2017-06-19T21:30:09Z",
"active": true,
"user_groups": [],
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email_verified": false,
"email": null,
"address": null,
"alternate_email_verified": false,
"id": 544,
"last_name": null,
"site_id": 0
}
}
]
HTTP Request
GET https://api.ysasecure.com/v2/users/<user id>/grants
HTTP Get Params
Parameter | Description |
---|---|
user id integer |
The ID of the user whose grants you’re trying to request |
token string |
Your Measure API token |
Show Grant
Retrieve a single grant from a user.
Example response
[
{
"type": "ExamGrant",
"user_id": 544,
"deleted_at": null,
"created_at": "2017-06-19T21:33:54Z",
"grantable_id": 30,
"remaining_uses": null,
"attempts_count": 0,
"grantable_type": "Exam",
"exam": {
"marking_deadline_in_days": 0,
"metadata": {},
"name": "Demo Exam",
"id": 30
},
"exam_form_group": "active",
"metadata": {},
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://measure-demo.ysasecure.com/grants/108/bookings/new"
},
"updated_at": "2017-06-19T21:33:54Z",
"expire_at": null,
"num_uses": null,
"allow_sittings_start_at": null,
"exam_form_id": 88,
"start_at": "2017-06-19T21:33:54Z",
"parent_grant_id": null,
"id": 10886,
"uuid": "369432ce-9681-4599-b568-99ddf177d42b",
"exam_form": {
"deleted_at": null,
"created_at": "2017-01-25T14:56:29Z",
"active": true,
"updated_at": "2017-01-25T14:56:29Z",
"name": "Form 1",
"id": 88
},
"allow_sittings_end_at": null,
"user": {
"first_name": null,
"alternate_email": null,
"preferred_language": "en",
"username": "testuser",
"deleted_at": null,
"created_at": "2017-06-19T21:30:09Z",
"active": true,
"user_groups": [],
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email_verified": false,
"email": null,
"address": null,
"alternate_email_verified": false,
"id": 544,
"last_name": null,
"site_id": 0
}
}
]
HTTP Request
GET https://api.ysasecure.com/v2/users/<user_id>/grants/<grant id>
HTTP Get Params
Parameter | Description |
---|---|
user id integer |
The user that the grant belongs to |
grant id integer |
The ID of the grant you’re requesting |
token string |
Your Measure API token |
Activate a grant’s exam form group
Activate or deactivate the exam form group.
Example response when exam_form_group is set as inactive
{
"exam_form_id": 88,
"type": "ExamGrant",
"user_id": 544,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/108/bookings/new"
},
"exam": {
"metadata": {},
"name": "Exam",
"marking_deadline_in_days": 0,
"id": 30
},
"user": {
"email_verified": false,
"first_name": null,
"user_groups": [],
"username": "testuser",
"created_at": "2017-06-19T21:30:09Z",
"active": true,
"deleted_at": null,
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email": null,
"address": null,
"preferred_language": "en",
"alternate_email_verified": false,
"id": 544,
"alternate_email": null,
"last_name": null,
"site_id": 19
},
"created_at": "2017-06-19T21:33:54Z",
"grantable_id": 30,
"attempts_count": 0,
"allow_sittings_start_at": null,
"deleted_at": null,
"grantable_type": "Exam",
"exam_form": {
"created_at": "2017-01-25T14:56:29Z",
"active": true,
"deleted_at": null,
"updated_at": "2017-01-25T14:56:29Z",
"name": "Form 1",
"id": 88
},
"metadata": {},
"allow_sittings_end_at": null,
"updated_at": "2017-06-19T22:11:26Z",
"expire_at": null,
"num_uses": null,
"exam_form_group": "inactive",
"start_at": "2017-06-19T21:33:54Z",
"parent_grant_id": null,
"id": 10886,
"uuid": "369432ce-9681-4599-b568-99ddf177d42b",
"remaining_uses": null
}
HTTP Request
PUT https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>/set_form
HTTP Put Params
Parameter | Description |
---|---|
token string |
Your API token |
user id integer |
The user that the grant belongs to |
grant id integer |
The ID of the grant you’re requesting |
which string |
Status you wish to set the exam form group to. Either “active” or “inactive” are accepted here. |
Create grant
Grant an exam to a candidate.
Example response
[
{
"allow_sittings_start_at": null,
"num_uses": 2,
"type": "ExamGrant",
"user_id": 544,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
},
"exam_form": null,
"allow_sittings_end_at": null,
"parent_grant_id": null,
"user": {
"first_name": null,
"username": "testuser",
"created_at": "2017-06-19T21:30:09Z",
"user_groups": [],
"alternate_email_verified": false,
"active": true,
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email_verified": false,
"email": null,
"address": null,
"preferred_language": "en",
"id": 544,
"deleted_at": null,
"alternate_email": null,
"last_name": null,
"site_id": 0
},
"exam_form_group": "active",
"created_at": "2017-06-22T20:45:44Z",
"exam": {
"marking_deadline_in_days": 0,
"metadata": {},
"name": "Demo Exam",
"id": 30
},
"exam_form_id": null,
"metadata": {},
"updated_at": "2017-06-22T20:45:44Z",
"expire_at": null,
"grantable_id": 30,
"attempts_count": 0,
"remaining_uses": 2,
"start_at": "2017-06-22T14:45:44-06:00",
"grantable_type": "Exam",
"id": 109,
"uuid": "b61589bd-6350-4584-a8eb-445e483e1e41",
"deleted_at": null
}
]
HTTP Request
POST https://api.ysasecure.com/v2/users/<user id>/grants
HTTP Post Params
Parameter | Description | Default |
---|---|---|
user id integer |
The user that the grant will belong to | |
token string |
Your Measure API token | |
grantable[id] integer, optional |
Measure’s Exam/Course ID | |
grantable[partner_id] string, optional |
Your configured Partner ID | |
grantable[site_id] integer, optional |
Site ID associated with the grantable[partner_id] |
|
grantable[type] string |
Either “Exam” or “Edition” | |
grant[num_uses] integer |
Number of attempts the candidate is allowed | |
grant[start_at] time with zone, optional |
Exams will be available from this time | |
grant[expire_at] time with zone, optional |
Exams will not be available after this date | |
grant[allow_sittings_start_at] time with zone, optional |
Only allow booking into sessions starting after the given time | |
grant[allow_sittings_end_at] time with zone, optional |
Only allow booking into sessions starting before the given time | |
grant[time_zone_name] timezone, optional |
Time zone that the grant is being assigned within | |
grant[exam_form_id] string, optional |
Measure’s Exam Form ID (if you want to grant a specific form) | |
grant[metadata] object, optional |
Any additional meta data you’d like to include | |
grant[send_email] boolean, optional |
Whether to send an email to the user or not upon creation | true |
grant[exam_form_group] string, optional |
Either active, inactive, or unknown (default) - corresponds to selecting active or inactive forms on an exam. | unknown |
Update Grant
Update a grant.
Example response
{
"type": "ExamGrant",
"user_id": 544,
"exam": {
"metadata": {},
"marking_deadline_in_days": 0,
"name": "Demo Exam",
"id": 30
},
"exam_form_id": null,
"user": {
"first_name": null,
"username": "testuser",
"created_at": "2017-06-19T21:30:09Z",
"alternate_email_verified": false,
"active": true,
"email_verified": false,
"metadata": {},
"deleted_at": null,
"updated_at": "2017-06-19T21:30:09Z",
"alternate_email": null,
"email": null,
"address": null,
"preferred_language": "en",
"id": 544,
"user_groups": [],
"last_name": null,
"site_id": 0
},
"parent_grant_id": null,
"created_at": "2017-06-22T20:45:44Z",
"allow_sittings_start_at": null,
"metadata": {},
"remaining_uses": 3,
"exam_form": null,
"allow_sittings_end_at": null,
"deleted_at": null,
"updated_at": "2017-06-22T20:59:23Z",
"expire_at": null,
"grantable_id": 30,
"attempts_count": 0,
"exam_form_group": "active",
"start_at": "2017-06-22T20:45:44Z",
"grantable_type": "Exam",
"num_uses": 3,
"id": 109,
"uuid": "b61589bd-6350-4584-a8eb-445e483e1e41",
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
}
}
HTTP Request
PUT https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>
,
HTTP Put Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
user id integer |
The user that the grant you’re updating belongs to |
grant id integer |
The ID of the grant you are updating |
grant[num_uses] integer, optional |
Number of attempts the candidate is allowed |
grant[start_at] time with zone, optional |
Exams will be available from this time |
grant[expire_at] time with zone, optional |
Exams will not be available after this date |
grant[allow_sittings_start_at] time with zone, optional |
Only allow booking into sessions starting after the given time |
grant[allow_sittings_end_at] time with zone, optional |
Only allow booking into sessions starting before the given time |
grant[time_zone_name] timezone, optional |
Time zone that the grant is being assigned within |
grant[exam_form_id] string, optional |
Measure’s Exam Form ID (if you want to grant a specific form) |
grant[exam_form_group] string, optional |
Either active, inactive, or unknown (default) - corresponds to selecting active or inactive forms on an exam. |
Destroy Grant
Delete a grant.
Example response
{
"type": "ExamGrant",
"user_id": 544,
"allow_sittings_start_at": null,
"parent_grant_id": null,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
},
"exam_form": null,
"allow_sittings_end_at": null,
"created_at": "2017-06-22T20:45:44Z",
"num_uses": 3,
"user": {
"first_name": null,
"preferred_language": "en",
"username": "aleciatest2",
"created_at": "2017-06-19T21:30:09Z",
"user_groups": [],
"alternate_email_verified": false,
"email_verified": false,
"active": true,
"alternate_email": null,
"deleted_at": null,
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email": null,
"address": null,
"id": 544,
"last_name": null,
"site_id": 0
},
"deleted_at": "2017-06-22T21:04:05Z",
"metadata": {},
"updated_at": "2017-06-22T21:04:05Z",
"expire_at": null,
"grantable_id": 30,
"attempts_count": 0,
"remaining_uses": 3,
"exam_form_id": null,
"start_at": "2017-06-22T20:45:44Z",
"grantable_type": "Exam",
"id": 109,
"uuid": "b61589bd-6350-4584-a8eb-445e483e1e41",
"exam": {
"marking_deadline_in_days": 0,
"metadata": {},
"name": "Demo Exam",
"id": 30
},
"exam_form_group": "active"
}
HTTP Request
DELETE https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>
HTTP Delete Params
Parameter | Description |
---|---|
user id integer |
The user whose grants you would like to delete |
grant id integer |
The ID of the grant to delete |
token string |
Your Measure API token |
Complete Grant Status
Example response
{
"user_id": 544,
"status": null,
"exam_url": null,
"id": 109,
"writable": false
}
HTTP Request
PUT https://api.ysasecure.com/v2/grant_status/<grant id>/complete
HTTP Put Params
Parameter | Description |
---|---|
grant id string |
The ID of the grant to change |
token string |
Your Measure API token |
grant_status[status] string, optional |
Status note field |
Force Terminate Grant Status
Example response
{
"user_id": 544,
"status": null,
"exam_url": null,
"id": 109,
"writable": false
}
HTTP Request
PUT https://api.ysasecure.com/v2/grant_status/<grant id>/force_terminate
HTTP Put Params
Parameter | Description |
---|---|
grant id integer |
The ID of the grant to force terminate |
token string |
Your Measure API token |
grant_status[status] string, optional |
Status note field |
Show Grant Status
Example response
{
"status": null,
"exam_url": null,
"id": 109,
"writable": false
}
HTTP Request
GET https://api.ysasecure.com/v2/grant_status/<grant id>
HTTP Get Params
Parameter | Description |
---|---|
grant id integer |
The ID of the grant to check the status of |
token string |
Your Measure API token |
Update Grant Status
Response after setting the status to “active”
{
"user_id": 544,
"status": "active",
"exam_url": null,
"id": 109,
"writable": false
}
HTTP Request
PUT https://api.ysasecure.com/v2/grant_status/<grant id>
HTTP Put Params
Parameter | Description |
---|---|
grant id integer |
The ID of the grant to update |
token string |
Your Measure API token |
grant_status[status] string, optional |
Status note field |
Exams
Exams are comprised of Exam Forms.
Index Exams
Retrieve a list of current exams.
Example response, without forms
[
{
"active": true,
"available_for_online": true,
"name": "Exam 1",
"id": 74,
"marking_deadline_in_days": 0,
"available_for_paper": false
},
{
"active": true,
"available_for_online": true,
"name": "Exam 2",
"id": 10,
"marking_deadline_in_days": 0,
"available_for_paper": false
}
]
Example response, with forms
[
{
"exam_forms": [
{
"locked": false,
"exam_id": 74,
"name": "Tutorial",
"id": 21
}
],
"active": true,
"available_for_online": true,
"name": "Exam 1",
"id": 74,
"marking_deadline_in_days": 0,
"available_for_paper": false
},
{
"exam_forms": [
{
"locked": false,
"exam_id": 10,
"name": "Demonstration",
"id": 31
}
],
"active": true,
"available_for_online": true,
"name": "Exam 2",
"id": 10,
"marking_deadline_in_days": 0,
"available_for_paper": false
},
]
HTTP Request
GET https://api.ysasecure.com/v2/exams
HTTP Get Params
Parameter | Description | Default |
---|---|---|
token string |
Your Measure API token | |
administration_id integer, optional |
Filter by administration ID associated with the Exams to return | |
include_forms boolean, optional |
If true, include forms in the retrieved list | false |
available_online boolean, optional |
If true, retrieve only Exams that are available online | false |
available_on_paper boolean, optional |
If true, retrieve only Exams that are available on paper | false |
active boolean, optional |
If true, retrieve only Exams that are active | false |
Exam Forms
Comprised of several User Exam Questions.
Index Exam Forms
Retrieve a list of exam forms
Example response
[
{
"markers": [],
"exam_id": 17,
"name": "Demo 1",
"id": 10
},
{
"markers": [],
"exam_id": 15,
"name": "Demo 2",
"id": 28
},
{
"markers": [],
"exam_id": 13,
"name": "Demo 3",
"id": 24
}
]
HTTP Request
GET https://api.ysasecure.com/v2/exam_forms
HTTP Get Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
User Exams
Whenever a User writes an Exam, a User Exam record is created. User Exams contain User Exam Questions.
Show User Exam
Example Response
{
"id": 221,
"user_id": 88,
"exam_id": 92,
"exam_form_id": 152,
"locale": "en",
"paths": {
"user_exam_questions": "/v2/user_exams/221/user_exam_questions"
},
"finished_at": "2023-07-21T19:08:03Z",
"user_exam": {
"exam_form": {
"created_at": "2023-07-17T14:16:05Z",
"deleted_at": null,
"id": 152,
"name": "Competency Exam - Form1",
"updated_at": "2023-07-17T14:16:05Z"
},
"passing_strategy": "total_score",
"exam": {
"deleted_at": null,
"passing_strategy": "total_score",
"metadata": {},
"active": true,
"require_booking": false,
"require_proctor": "unproctored",
"updated_at": "2023-07-17T16:19:49Z",
"locked": false,
"available_for_paper": false,
"partner_id": null,
"show_as_you_go": false,
"created_at": "2023-07-17T14:15:44Z",
"available_for_online": true,
"name": "Exam with Competency",
"strict_mode": false,
"send_emails": true,
"in_review": false,
"time_limit_in_minutes": null,
"pass_mark": 50,
"id": 92,
"shuffle_everything": false,
"pass_fail_review": 0
},
"panel_action_events": [],
"finished_at": "2023-07-21T19:08:03Z",
"reviewed_at": "2023-07-21T19:08:04Z",
"updated_at": "2023-07-21T19:08:03Z",
"enrolment_key_establishment": null,
"questions": [
{
"correct": true,
"question_id": 10211,
"item_bank_id": 1,
"topic": "The Bank",
"unanswered": false,
"item_bank_name": "The Bank",
"answer_score": 1,
"total_time_in_seconds": 3,
"competency_areas": [
{
"account_id": 1,
"created_at": "2021-08-09T20:29:43Z",
"id": 2,
"name": "Competency1",
"updated_at": "2023-07-21T19:05:37Z"
}
],
"capture": {
"a": true,
"b": false,
"c": false,
"d": false
},
"question_canonical_id": 1,
"total_time": 3,
"question": {
"created_at": "2020-02-03T17:44:29Z",
"deleted_at": null,
"id": 10211,
"canonical_id": 1,
"metadata": {
"question-metadata1": {
"value1": "2"
},
"question-metadata2": {
"value2": "2"
}
},
"updated_at": "2023-07-17T16:21:06Z"
},
"id": 566,
"angoff_score": null
},
{
"correct": true,
"question_id": 10230,
"item_bank_id": 1,
"topic": "The Bank",
"unanswered": false,
"item_bank_name": "The Bank",
"answer_score": 1,
"total_time_in_seconds": 4,
"competency_areas": [
{
"account_id": 1,
"created_at": "2020-06-04T21:06:00Z",
"id": 1,
"name": "Competency2",
"updated_at": "2023-07-21T19:05:49Z"
}
],
"capture": {
"a": true,
"b": false,
"c": false
},
"question_canonical_id": 18,
"total_time": 4,
"question": {
"created_at": "2021-05-12T08:49:56Z",
"deleted_at": null,
"id": 10230,
"canonical_id": 18,
"metadata": {
"question-metadata1": {
"value1": "2"
},
"question-metadata2": {
"value2": "2"
}
},
"updated_at": "2023-07-21T19:06:44Z"
},
"id": 567,
"angoff_score": null
}
],
"total_points": 2,
"created_at": "2023-07-21T19:07:52Z",
"sitting": null,
"exam_time_multiplier": 1,
"user": {
"email": "kamehameha@email.com",
"deleted_at": null,
"alternate_email_verified": false,
"address": {
"address1": "East District",
"address2": "",
"province": "",
"postal_code": "58N 018 439",
"province_name": null,
"updated_at": "2023-07-21T19:04:23Z",
"city": "Tokyo",
"country_name": "Japan",
"country": "JP"
},
"email_verified": false,
"active": true,
"alternate_email": "",
"metadata": {},
"first_name": "Son",
"username": "goku",
"updated_at": "2023-07-21T19:07:37Z",
"preferred_language": "en",
"full_name": "Son Goku",
"partner_id": null,
"last_name": "Goku",
"created_at": "2022-07-20T20:30:03Z",
"user_name": "goku",
"display_name": "Son Goku",
"id": 88
},
"parts": [
{
"number_of_questions": 2,
"finished_at": "2023-07-21T19:08:03Z",
"started_at": "2023-07-21T19:07:53Z",
"time_limit_in_minutes": 0,
"time_elapsed_in_seconds": 6.804899999976158,
"break_length_in_minutes": null
}
],
"number_of_questions": 2,
"exam_grant": {
"num_uses": null,
"uses": 1,
"order_id": null,
"deleted_at": null,
"parent_grant_id": null,
"metadata": {},
"exam_form_id": null,
"exam_form_group": "active",
"updated_at": "2023-07-21T19:07:25Z",
"start_at": "2023-07-21T19:07:25Z",
"expire_at": null,
"allow_sittings_start_at": null,
"created_at": "2023-07-21T19:07:25Z",
"allow_sittings_end_at": null,
"type": "ExamGrant",
"remaining_uses": null,
"user_id": 88,
"id": 429,
"grantable_id": 92,
"grantable_type": "Exam"
},
"time_limit_in_minutes": 0,
"proctor": null,
"id": 221,
"pass_mark": 50,
"results": {
"correct": 2,
"global_attempt_number": 1,
"equated_score": null,
"finished_at": "2023-07-21T19:08:03Z",
"score": 100,
"started_at": "2023-07-21T19:07:52Z",
"elapsed": 6.804899999976158,
"answered": 2,
"attempt_number": 1,
"points": 2,
"total_points": 2,
"finished": "2023-07-21T19:08:03Z",
"equated_points": null,
"scaled_points": null,
"passed": true,
"incorrect": 0,
"marking_complete": true,
"time_elapsed_in_seconds": 6.804899999976158,
"started": "2023-07-21T19:07:52Z",
"skipped": 0
},
"language": "en",
"booked": false,
"proctored": false
}
}
HTTP Request
GET https://api.ysasecure.com/v2/user_exams/<user exam id>
HTTP Get Parameters
Parameter | Description |
---|---|
user exam id integer |
The Measure ID of the user exam you want to retrieve |
token string |
Your Measure API token |
Index User Exams
Example Response
[
{
"user_id": 1441,
"exam_form_id": 70,
"exam_id": 70,
"paths": {
"user_exam_questions": "/v2/user_exams/1457/user_exam_questions"
},
"finished_at": "2011-01-14T18:48:05Z",
"id": 1457
},
{
"user_id": 1423,
"exam_form_id": 70,
"exam_id": 70,
"paths": {
"user_exam_questions": "/v2/user_exams/1463/user_exam_questions"
},
"finished_at": "2011-01-14T22:26:49Z",
"id": 1463
}
]
HTTP Request
GET https://api.ysasecure.com/v2/user_exams
HTTP Get Params
Parameter | Description | Default |
---|---|---|
token string |
Your Measure API token | |
id integer, optional |
Filter by user exam ID | |
limit integer, optional |
Maximum number of user exams to return | 25 |
with_manually_graded_questions boolean, optional |
Whether to return user exams with manually graded questions | false |
marker boolean, optional |
Whether to return unscored or partially scored user exams with with manually graded questions | false |
fully_marked boolean, optional |
Whether to return fully marked(scored) user exams | false |
without_assigned_markers boolean, optional |
Whether to return user exams that has no assigned markers | false |
except integer array, optional |
Array of user exam IDs to leave out of response | |
administration_id integer, optional |
Filter by administration ID associated with the user exams to return | |
passage_id integer, optional |
Filter by passage ID associated with the user exams to return | |
exam_id integer, optional |
Filter by exam ID associated with the user exams to return | |
exam_form_id integer, optional |
Filter by exam form ID associated with the user exams to return | |
include_user boolean, optional |
Whether to include the user in the user exams that will be returned | false |
only_finished boolean, optional |
Whether to return only finished user exams | true |
locale string, optional |
Return only user exams for that particular locale(e.g. en, fr) | |
user_id integer, optional |
User ID to filter user exams by | |
marker_id integer, optional |
Return user exams that are assigned to this marker ID | |
asc boolean, optional |
Whether sort direction is ascending or not | true |
Count User Exams
Example Response
{
"count": 15
}
HTTP Request
GET https://api.ysasecure.com/v2/user_exams/count
HTTP Get Params
Parameter | Description | Default |
---|---|---|
token string |
Your Measure API token | |
limit integer, optional |
Maximum number of user exams to return | 25 |
with_manually_graded_questions boolean, optional |
Whether to return exams with manually graded questions | false |
except integer array, optional |
Array of user exam IDs to leave out of response | |
administration_id integer, optional |
Filter by administration ID associated with the user exams to return | |
passage_id integer, optional |
Filter by passage ID associated with the user exams to return | |
exam_id integer, optional |
Filter by exam ID associated with the user exams to return | |
exam_form_id integer, optional |
Filter by exam form ID associated with the user exams to return | |
include_user boolean, optional |
Whether to include the user in the user exams that will be returned | false |
only_finished boolean, optional |
Whether to return only finished user exams | true |
user_id integer, optional |
User ID to filter user exams by | |
asc boolean, optional |
Whether sort direction is ascending or not | true |
group_strategy string, optional |
If “due dates” is entered, response will be grouped by due date |
User Course Items
External User Course Items
are created the first time a User opens a given Course
. Other User Course Item
types are created the first time a User opens a given Course Item
in a User Course
.
Update External User Course Item
Example Response
{
"id": 27,
"course_item_id": 19,
"course_item_type": "ExternalCourseItem",
"user_course_id": 32,
"grant_id": null,
"completion_status": "unknown",
"complete": true,
"created_at": "2024-01-19T21:56:57Z",
"update_at": "2024-01-22T19:18:09Z"
}
HTTP Request
PUT https://api.ysasecure.com/v2/user_courses/<user course id>/user_course_items/<user course item id>
HTTP Put Parameters
Parameter | Description |
---|---|
token string |
Your Measure API token |
user course id integer |
The Measure ID of the user course that contains the external user course item |
user course item id integer |
The Measure ID of the external user course item you want to update |
user_course_item[complete] boolean, optional |
Whether the item should be marked as “completed” |
Questions
Design exam content by using the Questions resource. Questions are versioned, meaning that we track all revisions (whenever a Question is edited, we create a new entity instead of just updating the old one).
Index Questions
Example response
[
{
"rationale": null,
"passage_id": null,
"workflow_state": null,
"created_by_id": 65,
"rubric_sections": [],
"paths": {
"assets": "/v2/questions/assets"
},
"free_form_marking": null,
"topic_id": null,
"id": 1058,
"locale": "en",
"marking_method": "rubric",
"item_bank_id": null,
"canonical_id": 1058,
"html": "",
"passage": null
},
{
"rationale": null,
"passage_id": null,
"workflow_state": null,
"created_by_id": 65,
"rubric_sections": [],
"paths": {
"assets": "/v2/questions/assets"
},
"free_form_marking": null,
"topic_id": null,
"id": 1062,
"locale": "en",
"marking_method": "rubric",
"item_bank_id": null,
"canonical_id": 1062,
"html": "",
"passage": null
}
]
HTTP Request
GET https://api.ysasecure.com/v2/questions
HTTP Get Params
Parameter | Description | Default |
---|---|---|
token string |
Your Measure API token | |
locale string, optional |
Language to retrieve | ‘en’ |
rubric_criterion_ids integer array, optional |
Array of rubric criterion IDs | |
limit integer, optional |
Number of questions to retrieve | 25 |
order string, optional |
Order to display the questions |
Show Question
Example response
{
"topic_id": null,
"free_form_marking": null,
"created_by_id": 65,
"workflow_state": null,
"rubric_sections": [],
"rationale": null,
"paths": {
"assets": "/v2/questions/assets"
},
"item_bank_id": null,
"id": 1058,
"locale": "en",
"marking_method": "rubric",
"passage_id": null,
"canonical_id": 1058,
"html": "",
"passage": null
}
HTTP Request
GET https://api.ysasecure.com/v2/questions/<question id>
HTTP Get Params
Parameter | Description | Default |
---|---|---|
question id integer |
ID of the question to retrieve | |
token string |
Your Measure API token | |
locale string, optional |
Language to show the question in | ‘en’ |
user_exam_id integer, optional |
ID of specific user exam to retrieve questions from |
Index Assets for Questions
Example response
{
"javascript": "function() {\n console.log(\"Here is some JavaScript that is run\");\n}",
"css": ".myClass {\n background-color: red; \n}"
}
HTTP Request
GET https://api.ysasecure.com/v2/questions/assets
HTTP Get Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
User Exam Questions
User Exam Questions differ from Questions in that they’re about which question a user sees when writing an exam. More specifically, they contain specific details about an instance of a question on a user’s exam.
Index User Exam Questions (Method 1)
Example response
[
{
"points": 4,
"state": "raw",
"user_exam": {
"user": {
"username": "demo_user"
},
"id": 7
},
"user_exam_id": 7032,
"question_id": 858,
"score": 0,
"paths": {
"question": "/v2/questions/858"
},
"question": {
"topic_id": 439,
"rationale": null,
"marking_method": "rubric",
"workflow_state": {
"appear_on_exams": true,
"score": true,
"name": "Operational",
"allow_editing": false,
"id": 266,
"position": 5
},
"created_by_id": 3109,
"rubric_sections": [
{
"question_id": 858,
"description": "Part A)",
"rubric_criterion": [
{
"point_value": 0.5,
"description": "First clinical feature correct?",
"rubric_section_id": 692,
"id": 200
},
{
"point_value": 0.5,
"description": "Second clinical feature correct?",
"rubric_section_id": 692,
"id": 201
},
{
"point_value": 0.5,
"description": "Third clinical feature correct?",
"rubric_section_id": 692,
"id": 202
},
{
"point_value": 0.5,
"description": "Fourth clinical feature correct?",
"rubric_section_id": 692,
"id": 203
}
],
"keys": [],
"id": 692
},
{
"question_id": 859,
"description": "Part B)",
"rubric_criterion": [
{
"point_value": 1,
"description": "First answer correct?",
"rubric_section_id": 693,
"id": 204
},
{
"point_value": 1,
"description": "Second answer correct?",
"rubric_section_id": 693,
"id": 205
}
],
"keys": [],
"id": 693
}
],
"free_form_marking": null,
"item_bank_id": 1073,
"paths": {
"assets": "/v2/questions/assets"
},
"locale": "en",
"id": 858,
"passage_id": null,
"passage": null,
"html": "<p>Question goes here</p>",
"canonical_id": 858
},
"id": 266,
"correct": false,
"answer": {
"user_exam_question_id": 266,
"score": null,
"id": 244,
"capture": {
"essay": "Answer goes here"
}
},
"position": 1,
"score_tbd": true,
"html": ""
}
]
HTTP Request
GET https://api.ysasecure.com/v2/user_exam_questions
HTTP Put Params
Parameter | Description | Default |
---|---|---|
token string |
Your Measure API token | |
ids integer array, optional |
Return only the specified user exam questions (via their ID) | |
user_exam_id integer, optional |
The ID of the user exam to retrieve questions from | |
locale string, optional |
Language to retrieve questions from | ‘en’ |
marker boolean, optional |
Whether to return exams with only manually graded questions | false |
passage_id integer, optional |
Filter by passage ID associated with the user exam | |
include_sample_responses boolean, optional |
Whether sample responses should be included in the list retrieved | false |
Index User Exam Questions (Method 2)
Example response
[
{
"points": 4,
"state": "raw",
"user_exam": {
"user": {
"username": "demo_user"
},
"id": 7
},
"user_exam_id": 7032,
"question_id": 858,
"score": 0,
"paths": {
"question": "/v2/questions/858"
},
"question": {
"topic_id": 439,
"rationale": null,
"marking_method": "rubric",
"workflow_state": {
"appear_on_exams": true,
"score": true,
"name": "Operational",
"allow_editing": false,
"id": 266,
"position": 5
},
"created_by_id": 3109,
"rubric_sections": [
{
"question_id": 858,
"description": "Part A)",
"rubric_criterion": [
{
"point_value": 0.5,
"description": "First clinical feature correct?",
"rubric_section_id": 692,
"id": 200
},
{
"point_value": 0.5,
"description": "Second clinical feature correct?",
"rubric_section_id": 692,
"id": 201
},
{
"point_value": 0.5,
"description": "Third clinical feature correct?",
"rubric_section_id": 692,
"id": 202
},
{
"point_value": 0.5,
"description": "Fourth clinical feature correct?",
"rubric_section_id": 692,
"id": 203
}
],
"keys": [],
"id": 692
},
{
"question_id": 859,
"description": "Part B)",
"rubric_criterion": [
{
"point_value": 1,
"description": "First answer correct?",
"rubric_section_id": 693,
"id": 204
},
{
"point_value": 1,
"description": "Second answer correct?",
"rubric_section_id": 693,
"id": 205
}
],
"keys": [],
"id": 693
}
],
"free_form_marking": null,
"item_bank_id": 1073,
"paths": {
"assets": "/v2/questions/assets"
},
"locale": "en",
"id": 858,
"passage_id": null,
"passage": null,
"html": "<p>Question goes here</p>",
"canonical_id": 858
},
"id": 266,
"correct": false,
"answer": {
"user_exam_question_id": 266,
"score": null,
"id": 244,
"capture": {
"essay": "Answer goes here"
}
},
"position": 1,
"score_tbd": true,
"html": ""
}
]
HTTP Request
GET https://api.ysasecure.com/v2/user_exams/<user exam id>/user_exam_questions
HTTP Put Params
Parameter | Description | Default |
---|---|---|
user exam id integer |
The ID of the user exam to retrieve questions from | |
token string |
Your Measure API token | |
ids integer array, optional |
Return only the specified user exam questions (via their ID) | |
locale string, optional |
Language to retrieve questions from | ‘en’ |
marker boolean, optional |
Whether to return exams with only manually graded questions | false |
passage_id integer, optional |
Filter by passage ID associated with the user exam | |
include_sample_responses boolean, optional |
Whether sample responses should be included in the list retrieved | false |
Mark User Exam Questions
Example Response
[
{
"points": 4,
"state": "raw",
"user_exam": {
"user": {
"username": "cpashtest"
},
"id": 703
},
"user_exam_id": 703,
"question_id": 858,
"score": 15,
"paths": {
"question": "/v2/questions/858"
},
"question": {
"topic_id": 439,
"rationale": null,
"marking_method": "rubric",
"workflow_state": {
"appear_on_exams": true,
"score": true,
"name": "Operational",
"allow_editing": false,
"id": 266,
"position": 5
},
"created_by_id": 3109,
"rubric_sections": [
{
"question_id": 858,
"description": "Part A)",
"rubric_criterion": [
{
"point_value": 0.5,
"description": "First clinical feature correct?",
"rubric_section_id": 692,
"id": 201
},
{
"point_value": 0.5,
"description": "Second clinical feature correct?",
"rubric_section_id": 692,
"id": 202
},
{
"point_value": 0.5,
"description": "Third clinical feature correct?",
"rubric_section_id": 692,
"id": 203
},
{
"point_value": 0.5,
"description": "Fourth clinical feature correct?",
"rubric_section_id": 692,
"id": 204
}
],
"keys": [],
"id": 692
},
{
"question_id": 858,
"description": "Part B)",
"rubric_criterion": [
{
"point_value": 1,
"description": "First medication correct?",
"rubric_section_id": 693,
"id": 205
},
{
"point_value": 1,
"description": "Second medication correct?",
"rubric_section_id": 693,
"id": 206
}
],
"keys": [],
"id": 693
}
],
"free_form_marking": null,
"item_bank_id": 1073,
"paths": {
"assets": "/v2/questions/assets"
},
"locale": null,
"id": 858,
"passage_id": null,
"passage": null,
"html": "Question goes here",
"canonical_id": 858
},
"id": 26612711,
"correct": false,
"answer": {
"user_exam_question_id": 26612711,
"score": 15,
"id": 245,
"capture": {
"essay": "Answer goes here"
}
},
"position": 1,
"score_tbd": false,
"html": ""
}
]
HTTP Request
PUT https://api.ysasecure.com/v2/user_exams/<user exam id>/user_exam_questions/mark
HTTP Put Params
Parameter | Description | Default |
---|---|---|
user exam id integer |
ID of the user exam to check | |
token string |
Your Measure API token | |
marks marks array |
See below for the marks params | |
email_exam_result_after_marking boolean, optional |
Whether to send the Exam Result Email to the candidate after the marking is completed | false |
Marks Params
Parameter | Description | Default |
---|---|---|
id integer |
User Exam Question ID for the question on the user exam to mark | |
score float |
Score to assign to the user exam question | |
unattempted boolean, optional |
Whether to set the user exam question as attempted | false |
Sittings
Sitting Users Index
Example Response
[
{
"first_name": "",
"deleted_at": null,
"username": "demotest",
"created_at": "2017-04-07T19:02:11Z",
"email_verified": false,
"active": true,
"alternate_email_verified": false,
"metadata": {
"special-accommodations-request": {
"special-accommodations-request": "no"
}
},
"user_groups": [],
"updated_at": "2017-07-13T18:57:24Z",
"email": "",
"address": {
"province_name": "Alberta",
"postal_code": "M4W1N1",
"country_name": "Canada",
"province": "AB",
"address1": "asdf",
"updated_at": "2017-04-07T19:02:11Z",
"city": "asdf",
"country": "CA",
"address2": ""
},
"preferred_language": "en",
"alternate_email": null,
"id": 517,
"last_name": "",
"site_id": 3
},
{
"first_name": "",
"deleted_at": null,
"username": "demo",
"created_at": "2014-06-16T19:31:12Z",
"email_verified": false,
"active": true,
"alternate_email_verified": false,
"metadata": {},
"user_groups": [],
"updated_at": "2017-07-13T18:48:15Z",
"email": "",
"address": {
"province_name": "Alberta",
"postal_code": "t6e6e6",
"country_name": "Canada",
"province": "AB",
"address1": "12345",
"updated_at": "2014-06-16T19:31:12Z",
"city": "Edmonton",
"country": "CA",
"address2": ""
},
"preferred_language": "en",
"alternate_email": "",
"id": 296,
"last_name": "",
"site_id": 3
}
]
HTTP Request
GET https://api.ysasecure.com/v2/sittings/<sitting id>/users
HTTP Get Params
Parameter | Description |
---|---|
sitting id integer |
The ID of the sitting that users will be listed from |
token string |
Your Measure API token |
Sitting Proctors Index
Example Response
[
{
"first_name": "Demo",
"type": "Proctor",
"roles": [
"proctor"
],
"email": "demo@getyardstick.com",
"id": 1343,
"last_name": "Demo"
},
{
"first_name": "Another Demo",
"type": "Proctor",
"roles": [
"proctor"
],
"email": "anotherdemo@getyardstick.com",
"id": 975,
"last_name": "Demo"
}
]
HTTP Request
GET https://api.ysasecure.com/v2/sittings/<sitting id>/proctors
HTTP Get Params
Parameter | Description |
---|---|
sitting id integer |
The ID of the sitting that proctors will be listed from |
token string |
Your Measure API token |
Test Centre Time Windows
Show Test Centre Time Window
Example response
{
"source_id": 658,
"source_type": "Sitting",
"venue": {
"account": {
"name": "Measure Demo",
"id": 7,
"short_name": "demo"
},
"location": "Yardstick Testing & Training Experts",
"id": 1187
},
"proctoring_options": {
"virtual_proctoring": {
"provider_name": "YardstickExams",
"provider_options": {
"username": "",
"api_key": ""
},
"enabled": false
},
"incident_reports": true
},
"venue_id": 1187,
"global_start_datetime": "2017-07-14T06:30:00Z",
"global_end_datetime": "2017-07-17T06:00:00Z",
"paths": {
"incidents": "/v2/sittings/658/incidents",
"users": "/v2/sittings/658/users",
"proctors": "/v2/sittings/658/proctors"
},
"time_zone": "Mountain Time (US & Canada)",
"test_centre_seats": [
{
"source_id": 658,
"user_id": 5173,
"grantable_id": 3033,
"source_type": "Sitting",
"grantable_type": "Exam",
"grantable": {
"name": "Demo Exam",
"id": 3033
},
"user": {
"first_name": "",
"full_name": "demo",
"id": 517,
"last_name": ""
}
},
{
"source_id": 658,
"user_id": 296,
"grantable_id": 1089,
"source_type": "Sitting",
"grantable_type": "Exam",
"grantable": {
"name": "Tutorial",
"id": 1089
},
"user": {
"first_name": "",
"full_name": "demo",
"id": 296,
"last_name": ""
}
}
],
"attachments": [
{
"file_url": "/media/BAhbBlsHOgZmIkcyMDE/Demo.pdf",
"file_name": "Demo.pdf",
"id": 240
}
]
}
HTTP Request
GET https://api.ysasecure.com/v2/test_centre_time_windows/<id>/<source type>
HTTP Get Params
Parameter | Description |
---|---|
id integer |
The ID of the sitting or booking |
source type string |
“booking” or “sitting” |
token string |
Your Measure API token |
Upcoming & Recent Test Centre Time Windows
Example response
[
{
"source_id": 658,
"source_type": "Sitting",
"venue": {
"account": {
"name": "Measure Demo",
"id": 7,
"short_name": "demo"
},
"location": "Yardstick Testing & Training Experts",
"id": 1187
},
"proctoring_options": {
"virtual_proctoring": {
"provider_name": "YardstickExams",
"provider_options": {
"username": "",
"api_key": ""
},
"enabled": false
},
"incident_reports": true
},
"venue_id": 1187,
"global_start_datetime": "2017-07-14T06:30:00Z",
"global_end_datetime": "2017-07-17T06:00:00Z",
"paths": {
"incidents": "/v2/sittings/658/incidents",
"users": "/v2/sittings/658/users",
"proctors": "/v2/sittings/658/proctors"
},
"time_zone": "Mountain Time (US & Canada)",
"test_centre_seats": [
{
"source_id": 658,
"user_id": 5173,
"grantable_id": 3033,
"source_type": "Sitting",
"grantable_type": "Exam",
"grantable": {
"name": "Demo Exam",
"id": 3033
},
"user": {
"first_name": "",
"full_name": "demo",
"id": 517,
"last_name": ""
}
},
{
"source_id": 658,
"user_id": 296,
"grantable_id": 1089,
"source_type": "Sitting",
"grantable_type": "Exam",
"grantable": {
"name": "Tutorial",
"id": 1089
},
"user": {
"first_name": "",
"full_name": "demo",
"id": 296,
"last_name": ""
}
}
],
"attachments": [
{
"file_url": "/media/BAhbBlsHOgZmIkcyMDE/Demo.pdf",
"file_name": "Demo.pdf",
"id": 240
}
]
}
]
HTTP Request
GET https://api.ysasecure.com/v2/test_centre_time_windows/upcoming_and_recent
HTTP Get Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
Bookings
Show Booking
Retrieve a specific booking from a user.
Example Response
{
"sitting": {
"require_purchase_before": null,
"venue": {
"phone": "",
"notes": "",
"lab_capacity": null,
"created_at": "2014-06-13T23:19:20Z",
"web": "",
"translated_address": {
"province_name": "Alberta",
"postal_code": "T6E 6E6",
"country_name": "Canada",
"province": "AB",
"address1": "#200, 8616 - 51 Avenue",
"updated_at": "2017-02-22T22:14:31Z",
"city": "Edmonton",
"country": "CA",
"address2": null
},
"deleted_at": null,
"available_for_exams": true,
"metadata": {},
"updated_at": "2017-02-22T22:14:31Z",
"email": "",
"location": "Yardstick Testing & Training Experts",
"details_for_user": null,
"available_for_courses": false,
"fax": "",
"hours_of_operation": "",
"id": 1187
},
"has_waiting_list": false,
"session_type": "exam",
"created_at": "2017-07-13T17:57:03Z",
"begin_booking_at": null,
"deleted_at": null,
"seats": null,
"metadata": {},
"local_start_datetime": "2017-07-14T06:30:00Z",
"end_booking_at": null,
"cancellation_deadline": null,
"updated_at": "2017-07-13T17:57:03Z",
"room": "",
"local_end_datetime": "2017-07-17T06:00:00Z",
"private": false,
"id": 658,
"venue_tbd": false
},
"grant": {
"allow_sittings_start_at": null,
"num_uses": null,
"type": "ExamGrant",
"user_id": 5173,
"exam_form_id": 886,
"exam_form_group": "active",
"grantable_id": 3033,
"remaining_uses": null,
"created_at": "2017-07-13T18:56:50Z",
"attempts_count": 1,
"exam_form": {
"created_at": "2017-01-25T14:56:29Z",
"deleted_at": null,
"active": true,
"updated_at": "2017-07-13T18:52:21Z",
"name": "Form 1",
"id": 886
},
"allow_sittings_end_at": null,
"deleted_at": null,
"grantable_type": "Exam",
"user": {
"first_name": "",
"alternate_email": null,
"username": "demo",
"created_at": "2017-04-07T19:02:11Z",
"deleted_at": null,
"email_verified": false,
"active": true,
"alternate_email_verified": false,
"metadata": {
"special-accommodations-request": {
"special-accommodations-request": "no"
}
},
"user_groups": [],
"updated_at": "2017-07-13T18:57:24Z",
"email": "",
"address": {
"province_name": "Alberta",
"postal_code": "M4W1N1",
"country_name": "Canada",
"province": "AB",
"address1": "asdf",
"updated_at": "2017-04-07T19:02:11Z",
"city": "asdf",
"country": "CA",
"address2": ""
},
"preferred_language": "en",
"id": 517,
"last_name": "",
"site_id": 3
},
"metadata": {},
"exam": {
"metadata": {},
"name": "Demo Exam",
"marking_deadline_in_days": 0,
"id": 3033
},
"updated_at": "2017-07-13T18:56:50Z",
"expire_at": null,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/1100199/bookings/new"
},
"parent_grant_id": null,
"start_at": "2017-07-13T18:56:50Z",
"id": 1100
},
"created_at": "2017-07-13T18:57:05Z",
"deleted_at": null,
"cancellation_note": null,
"user": {
"first_name": "",
"alternate_email": null,
"username": "cpashtest",
"created_at": "2017-04-07T19:02:11Z",
"deleted_at": null,
"email_verified": false,
"active": true,
"alternate_email_verified": false,
"metadata": {
"special-accommodations-request": {
"special-accommodations-request": "no"
}
},
"user_groups": [],
"updated_at": "2017-07-13T18:57:24Z",
"email": "",
"address": {
"province_name": "Alberta",
"postal_code": "M4W1N1",
"country_name": "Canada",
"province": "AB",
"address1": "asdf",
"updated_at": "2017-04-07T19:02:11Z",
"city": "asdf",
"country": "CA",
"address2": ""
},
"preferred_language": "en",
"id": 517,
"last_name": "",
"site_id": 3
},
"updated_at": "2017-07-13T18:57:55Z",
"id": 565
}
HTTP Request
GET https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>/bookings/<booking id>
HTTP Get Params
Parameter | Description |
---|---|
user id string |
The ID number of the user that the booking belongs to |
grant id integer |
The ID number of the grant that the booking is associated with |
booking id integer |
The ID of the booking you wish to retrieve |
token string |
Your Measure API token |
Create Booking
Create a new booking for a user.
Example Response
{
"sitting": {
"require_purchase_before": null,
"venue": {
"phone": "",
"notes": "",
"lab_capacity": null,
"created_at": "2014-06-13T23:19:20Z",
"web": "",
"translated_address": {
"province_name": "Alberta",
"postal_code": "T6E 6E6",
"country_name": "Canada",
"province": "AB",
"address1": "#200, 8616 - 51 Avenue",
"updated_at": "2017-02-22T22:14:31Z",
"city": "Edmonton",
"country": "CA",
"address2": null
},
"deleted_at": null,
"available_for_exams": true,
"metadata": {},
"updated_at": "2017-02-22T22:14:31Z",
"email": "",
"location": "Yardstick Testing & Training Experts",
"details_for_user": null,
"available_for_courses": false,
"fax": "",
"hours_of_operation": "",
"id": 1187
},
"has_waiting_list": false,
"session_type": "exam",
"created_at": "2017-07-13T17:57:03Z",
"begin_booking_at": null,
"deleted_at": null,
"seats": null,
"metadata": {},
"local_start_datetime": "2017-07-14T06:30:00Z",
"end_booking_at": null,
"cancellation_deadline": null,
"updated_at": "2017-07-13T17:57:03Z",
"room": "",
"local_end_datetime": "2017-07-17T06:00:00Z",
"private": false,
"id": 658,
"venue_tbd": false
},
"grant": {
"allow_sittings_start_at": null,
"num_uses": null,
"type": "ExamGrant",
"user_id": 5173,
"exam_form_id": 886,
"exam_form_group": "active",
"grantable_id": 3033,
"remaining_uses": null,
"created_at": "2017-07-13T18:56:50Z",
"attempts_count": 1,
"exam_form": {
"created_at": "2017-01-25T14:56:29Z",
"deleted_at": null,
"active": true,
"updated_at": "2017-07-13T18:52:21Z",
"name": "Form 1",
"id": 886
},
"allow_sittings_end_at": null,
"deleted_at": null,
"grantable_type": "Exam",
"user": {
"first_name": "",
"alternate_email": null,
"username": "demo",
"created_at": "2017-04-07T19:02:11Z",
"deleted_at": null,
"email_verified": false,
"active": true,
"alternate_email_verified": false,
"metadata": {
"special-accommodations-request": {
"special-accommodations-request": "no"
}
},
"user_groups": [],
"updated_at": "2017-07-13T18:57:24Z",
"email": "",
"address": {
"province_name": "Alberta",
"postal_code": "M4W1N1",
"country_name": "Canada",
"province": "AB",
"address1": "asdf",
"updated_at": "2017-04-07T19:02:11Z",
"city": "asdf",
"country": "CA",
"address2": ""
},
"preferred_language": "en",
"id": 517,
"last_name": "",
"site_id": 3
},
"metadata": {},
"exam": {
"metadata": {},
"name": "Demo Exam",
"marking_deadline_in_days": 0,
"id": 3033
},
"updated_at": "2017-07-13T18:56:50Z",
"expire_at": null,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/1100199/bookings/new"
},
"parent_grant_id": null,
"start_at": "2017-07-13T18:56:50Z",
"id": 1100
},
"created_at": "2017-07-13T18:57:05Z",
"deleted_at": null,
"cancellation_note": null,
"user": {
"first_name": "",
"alternate_email": null,
"username": "cpashtest",
"created_at": "2017-04-07T19:02:11Z",
"deleted_at": null,
"email_verified": false,
"active": true,
"alternate_email_verified": false,
"metadata": {
"special-accommodations-request": {
"special-accommodations-request": "no"
}
},
"user_groups": [],
"updated_at": "2017-07-13T18:57:24Z",
"email": "",
"address": {
"province_name": "Alberta",
"postal_code": "M4W1N1",
"country_name": "Canada",
"province": "AB",
"address1": "asdf",
"updated_at": "2017-04-07T19:02:11Z",
"city": "asdf",
"country": "CA",
"address2": ""
},
"preferred_language": "en",
"id": 517,
"last_name": "",
"site_id": 3
},
"updated_at": "2017-07-13T18:57:55Z",
"id": 565
}
HTTP Request
POST https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>/bookings
HTTP Post Params
Parameter | Description | Default |
---|---|---|
user id integer |
The Measure User ID of the user that the booking will be associated with | |
grant id integer |
The ID number of the grant that the booking is associated with | |
token string |
Your Measure API token | |
sitting[id] integer |
The ID of the sitting that the booking is for | |
sitting[range][venue_id] integer |
The ID number of the venue where the exam sitting will be held | |
sitting[range][start_at] time with zone |
The start date of sittings you want the booking API to search from | |
sitting[range][end_at] time with zone |
The end date of sittings you want the booking API to search from | |
options[include_private] boolean, optional |
Whether to include private bookings or not | false |
options[only_before_cancellation_deadline] boolean, optional |
If true, reject bookings made after the cancellation deadline | true |
options[in_booking_window] boolean, optional |
Whether the booking window is still open or not | true |
options[include_past] boolean, optional |
Whether to include past bookings | false |
options[has_seats_left] boolean, optional |
Whether or not the sitting has seats left | true |
send_email boolean, optional |
Send a confirmation email upon successful booking creation | true |
Destroy Booking
Delete booking for a user.
Example Response
{
"sitting": {
"require_purchase_before": null,
"venue": {
"phone": "",
"notes": "",
"lab_capacity": null,
"created_at": "2014-06-13T23:19:20Z",
"web": "",
"translated_address": {
"province_name": "Alberta",
"postal_code": "T6E 6E6",
"country_name": "Canada",
"province": "AB",
"address1": "#200, 8616 - 51 Avenue",
"updated_at": "2017-02-22T22:14:31Z",
"city": "Edmonton",
"country": "CA",
"address2": null
},
"deleted_at": null,
"available_for_exams": true,
"metadata": {},
"updated_at": "2017-02-22T22:14:31Z",
"email": "",
"location": "Yardstick Testing & Training Experts",
"details_for_user": null,
"available_for_courses": false,
"fax": "",
"hours_of_operation": "",
"id": 1187
},
"has_waiting_list": false,
"session_type": "exam",
"created_at": "2017-07-13T17:57:03Z",
"begin_booking_at": null,
"deleted_at": "2017-07-13T18:57:55Z",
"seats": null,
"metadata": {},
"local_start_datetime": "2017-07-14T06:30:00Z",
"end_booking_at": null,
"cancellation_deadline": null,
"updated_at": "2017-07-13T17:57:03Z",
"room": "",
"local_end_datetime": "2017-07-17T06:00:00Z",
"private": false,
"id": 658,
"venue_tbd": false
},
"grant": {
"allow_sittings_start_at": null,
"num_uses": null,
"type": "ExamGrant",
"user_id": 5173,
"exam_form_id": 886,
"exam_form_group": "active",
"grantable_id": 3033,
"remaining_uses": null,
"created_at": "2017-07-13T18:56:50Z",
"attempts_count": 1,
"exam_form": {
"created_at": "2017-01-25T14:56:29Z",
"deleted_at": null,
"active": true,
"updated_at": "2017-07-13T18:52:21Z",
"name": "Form 1",
"id": 886
},
"allow_sittings_end_at": null,
"deleted_at": null,
"grantable_type": "Exam",
"user": {
"first_name": "",
"alternate_email": null,
"username": "demo",
"created_at": "2017-04-07T19:02:11Z",
"deleted_at": null,
"email_verified": false,
"active": true,
"alternate_email_verified": false,
"metadata": {
"special-accommodations-request": {
"special-accommodations-request": "no"
}
},
"user_groups": [],
"updated_at": "2017-07-13T18:57:24Z",
"email": "",
"address": {
"province_name": "Alberta",
"postal_code": "M4W1N1",
"country_name": "Canada",
"province": "AB",
"address1": "asdf",
"updated_at": "2017-04-07T19:02:11Z",
"city": "asdf",
"country": "CA",
"address2": ""
},
"preferred_language": "en",
"id": 517,
"last_name": "",
"site_id": 3
},
"metadata": {},
"exam": {
"metadata": {},
"name": "Demo Exam",
"marking_deadline_in_days": 0,
"id": 3033
},
"updated_at": "2017-07-13T18:56:50Z",
"expire_at": null,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/1100199/bookings/new"
},
"parent_grant_id": null,
"start_at": "2017-07-13T18:56:50Z",
"id": 1100
},
"created_at": "2017-07-13T18:57:05Z",
"deleted_at": null,
"cancellation_note": null,
"user": {
"first_name": "",
"alternate_email": null,
"username": "cpashtest",
"created_at": "2017-04-07T19:02:11Z",
"deleted_at": null,
"email_verified": false,
"active": true,
"alternate_email_verified": false,
"metadata": {
"special-accommodations-request": {
"special-accommodations-request": "no"
}
},
"user_groups": [],
"updated_at": "2017-07-13T18:57:24Z",
"email": "",
"address": {
"province_name": "Alberta",
"postal_code": "M4W1N1",
"country_name": "Canada",
"province": "AB",
"address1": "asdf",
"updated_at": "2017-04-07T19:02:11Z",
"city": "asdf",
"country": "CA",
"address2": ""
},
"preferred_language": "en",
"id": 517,
"last_name": "",
"site_id": 3
},
"updated_at": "2017-07-13T18:57:55Z",
"id": 565
}
HTTP Request
DELETE https://api.ysasecure.com/v2/users/<user id>/grants/<grant id>/bookings/<booking id>
HTTP Delete Params
Parameter | Description | Default |
---|---|---|
grant id integer |
The ID number of the grant that the booking is associated with | |
user id integer |
The Measure User ID of the user the booking is associated with | |
booking id integer |
The ID number of the booking to be deleted | |
token string |
Your Measure API token | |
options[note] string |
Reason for withdrawing from the booking | |
options[force] boolean, optional |
Force destruction of the booking | false |
options[cancel_order] boolean, optional |
Cancel the order | true |
options[notify_user] boolean, optional |
Notify the user via email | true |
Booking Requests
Index Booking Requests
HTTP Request
GET https://api.ysasecure.com/v2/booking_requests
Parameter | Description |
---|---|
token string |
Your Measure API token |
state string, optional |
Filter booking requests by a specific state |
Schedule Booking Request
HTTP Request
PUT https://api.ysasecure.com/v2/booking_requests/<booking request id>/schedule
HTTP Put Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
booking_request[local_start_at] time with zone, optional |
Start date & time |
booking_request[local_end_at] time with zone, optional |
End date & time |
booking_request[date1] date, optional |
Date 1 |
booking_request[date1_am] boolean, optional |
Whether it should be in the morning or not |
booking_request[date2] date, optional |
Date 2 |
booking_request[date2_am] boolean, optional |
Whether it should be in the morning or not |
booking_request[date3] date, optional |
Date 3 |
booking_request[date3_am] boolean, optional |
Whether it should be in the morning or not |
Request Alternate Dates for Booking Requests
HTTP Request
PUT https://api.ysasecure.com/v2/booking_requests/<booking request id>/request_alternate_dates
HTTP Put Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
booking_request[local_start_at] time with zone, optional |
|
booking_request[local_end_at] time with zone, optional |
|
booking_request[date1] date, optional |
|
booking_request[date1_am] boolean, optional |
|
booking_request[date2] date, optional |
|
booking_request[date2_am] boolean, optional |
|
booking_request[date3] date, optional |
|
booking_request[date3_am] boolean, optional |
Booking Request Users
HTTP Request
GET https://api.ysasecure.com/v2/booking_requests/<booking request id>/users
HTTP Get Params
Parameter | Description |
---|---|
booking request id integer |
ID of the booking request to view users from |
token string |
Your Measure API token |
Booking Request Proctors
HTTP Request
GET https://api.ysasecure.com/v2/booking_requests/<booking request id>/proctors
HTTP Get Params
Parameter | Description |
---|---|
booking request id integer |
ID of the booking request to view proctors from |
token string |
Your Measure API token |
Incidents
Types of Incidents
Example response
{
"types": [
"breach_of_regulations",
"computer_issue",
"disturbance_in_the_test_centre",
"fire_alarm",
"no_authorization",
"no_incidents",
"no_proper_id",
"no_show",
"no_user_account",
"other",
"power_outage",
"room_issue",
"washroom_break"
]
}
HTTP Request
GET https://api.ysasecure.com/v2/incidents/types
Create Incident
HTTP Request
POST https://api.ysasecure.com/v2/incidents
HTTP Post Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
incident[incident_datetime] time with zone |
Date and time that the incident occurred |
incident[incident_type] string |
See Types of Incidents for a list of possible values |
incident[user_ids] integer array, optional |
User IDs associated with the incident (leave blank to associate all users at this sitting) |
incident[proctors] array of proctors, optional |
Each proctor in the array should include an id and a type (either 'AdminUser' or 'NomadUser' ) |
incident[notes] string, optional |
Notes about the incident to include in the report |
booking_request_id integer, optional |
Booking Request ID to associate the incident with |
sitting_id integer, optional |
Sitting ID to associate the incident with |
Show Incident
HTTP Request
GET https://api.ysasecure.com/v2/incidents
HTTP Get Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
booking_request_id integer, optional |
Booking Request ID the incident is associated with |
sitting_id integer, optional |
Sitting ID the incident is associated with |
Index Booking Request Incidents
HTTP Request
GET https://api.ysasecure.com/v2/booking_requests/<booking request id>/incidents
HTTP Get Params
Parameter | Description |
---|---|
booking request id integer |
ID of the booking request id to retrieve incidents for |
token string |
Your Measure API token |
Create Booking Request Incident
HTTP Request
POST https://api.ysasecure.com/v2/booking_requests/<booking request id>/incidents
HTTP Post Params
Parameter | Description |
---|---|
booking request id integer |
ID of the booking request id to create an incident for |
token string |
Your Measure API token |
incident[incident_datetime] time with zone |
Date and time that the incident occurred |
incident[incident_type] string |
See Types of Incidents for a list of possible values |
incident[user_ids] integer array, optional |
User IDs associated with the incident (leave blank to associate all users at this sitting) |
incident[proctors] array of proctors, optional |
Each proctor in the array should include an id and a type (either 'AdminUser' or 'NomadUser' ) |
incident[notes] string, optional |
Notes about the incident to include in the report |
Show Booking Request Incident
HTTP Request
GET https://api.ysasecure.com/v2/booking_requests/<booking request id>/incidents/<incident id>
HTTP Get Params
Parameter | Description |
---|---|
booking request id integer |
ID of the booking request to retrieve |
incident id integer |
ID of the incident to retrieve |
token string |
Your Measure API token |
Index Sitting Incidents
HTTP Request
GET https://api.ysasecure.com/v2/sittings/<sitting id>/incidents
HTTP Get Params
Parameter | Description |
---|---|
sitting id integer |
ID of the sitting to retrieve |
token string |
Your Measure API token |
Create Sitting Incident
HTTP Request
POST https://api.ysasecure.com/v2/sittings/<sitting id>/incidents
HTTP Post Params
Parameter | Description |
---|---|
sitting id integer |
ID of the sitting to create an incident in |
token string |
Your Measure API token |
incident[incident_datetime] time with zone |
Date and time that the incident occurred |
incident[incident_type] string |
See Types of Incidents for a list of possible values |
incident[user_ids] integer array, optional |
User IDs associated with the incident (leave blank to associate all users at this sitting) |
incident[proctors] array of proctors, optional |
Each proctor in the array should include an id and a type (either 'AdminUser' or 'NomadUser' ) |
incident[notes] string, optional |
Notes about the incident to include in the report |
Show Sitting Incident
HTTP Request
GET https://api.ysasecure.com/v2/sittings/<sitting id>/incidents/<incident id>
HTTP Get Params
Parameter | Description |
---|---|
sitting id integer |
ID of the sitting to retrieve |
incident id integer |
ID of the incident to retrieve |
token string |
Your Measure API token |
Administrations
An Administration represents a group of exam sessions or an exam “event”. Some organizations call these semesters and is a good example of what this represents. A good example to draw on from the high education world would be “February 2016 Mid-Terms.”
Index Administrations
HTTP Request
GET https://api.ysasecure.com/v2/administrations
HTTP Get Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
account_id integer, optional |
ID of the account associated with the administration |
Show Administration
HTTP Request
GET https://api.ysasecure.com/v2/administrations/<administration id>
HTTP Get Params
Parameter | Description |
---|---|
administration id integer |
ID of the administration to retrieve |
token string |
Your Measure API token |
account_id integer, optional |
ID of the account associated with the administration |
Orders
An Order
is created whenever a Product
is purchased in Measure.
Show Order
Retrieve a specific Order.
HTTP Request
GET https://api.ysasecure.com/v2/orders/<order id>
Example Response
{
"shipped": false,
"buyer_type": "User",
"billing_address": {
"country_name": "Canada",
"country": "CA",
"address1": "add1",
"city": "To",
"address2": "",
"province_name": "Ontario",
"updated_at": "2018-10-10T12:44:59Z",
"postal_code": "123",
"province": "ON"
},
"provincial_tax_code": null,
"tracking_code": null,
"subtotal": 1000,
"paid_at": "2018-10-10T12:44:59Z",
"tax_data": {
"federal_tax_description": "13% HST, Canada",
"provincial_tax_description": null,
"tax_kind": "HST"
},
"created_at": "2018-10-10T12:44:59Z",
"discount": 0,
"tax_info": null,
"shipping_same_as_billing": false,
"deleted_at": null,
"shipping_address": null,
"federal_tax_amount": 130,
"sitting_id": null,
"paid_by": {
"type": "User",
"email": "personal_email@email.com",
"full_name": "FirstName LastName",
"id": 132
},
"import_identifier": null,
"payment_type_id": null,
"provincial_tax_amount": 0,
"shipping": 0,
"updated_at": "2019-11-25T21:25:10Z",
"currency": "USD",
"site_id": 4,
"metadata": {
"order-notes": {
"additional-information": "\"Additional Info\""
}
},
"order_items": [
{
"amount": 455,
"charge_id": 2,
"charge_type": "Product",
"description": "Description of product",
"discount_in_cents": 0,
"id": 68,
"name": "Name of product",
"order_id": 355,
"promo_code_id": null,
"quantity": 1
}
],
"tax_region": "CAON",
"establishment_id": null,
"payment_type_name": "bogus",
"buyer_id": 132,
"id": 355,
"federal_tax_code": "CAHST",
"delivery_method": "online",
"custom": false,
"cancellation_note": null
}
HTTP Get Params
Parameter | Description |
---|---|
order id integer |
ID of the order to retrieve |
token string |
Your Measure API token |
Update Order
Updates the metadata of a specific Order.
HTTP Request
PUT https://api.ysasecure.com/v2/orders/<order id>
Example Response
{
"shipped": false,
"buyer_type": "User",
"billing_address": {
"country_name": "Canada",
"country": "CA",
"address1": "add1",
"city": "To",
"address2": "",
"province_name": "Ontario",
"updated_at": "2018-10-10T12:44:59Z",
"postal_code": "123",
"province": "ON"
},
"provincial_tax_code": null,
"tracking_code": null,
"subtotal": 1000,
"paid_at": "2018-10-10T12:44:59Z",
"tax_data": {
"federal_tax_description": "13% HST, Canada",
"provincial_tax_description": null,
"tax_kind": "HST"
},
"created_at": "2018-10-10T12:44:59Z",
"discount": 0,
"tax_info": null,
"shipping_same_as_billing": false,
"deleted_at": null,
"shipping_address": null,
"federal_tax_amount": 130,
"sitting_id": null,
"paid_by": {
"type": "User",
"email": "personal_email@email.com",
"full_name": "FirstName LastName",
"id": 132
},
"import_identifier": null,
"payment_type_id": null,
"provincial_tax_amount": 0,
"shipping": 0,
"updated_at": "2019-11-25T21:25:10Z",
"currency": "USD",
"site_id": 4,
"metadata": {
"order-notes": {
"additional-information": "\"Additional Info\""
}
},
"tax_region": "CAON",
"establishment_id": null,
"payment_type_name": "bogus",
"buyer_id": 132,
"id": 355,
"federal_tax_code": "CAHST",
"delivery_method": "online",
"custom": false,
"cancellation_note": null
}
HTTP Put Params
Parameter | Description |
---|---|
order id integer |
ID of the order to retrieve |
token string |
Your Measure API token |
order[metadata][schema][schema-item] object |
Metadata to update for the order |
Passages
Index Passages
HTTP Request
GET https://api.ysasecure.com/v2/passages
HTTP Get Params
Parameter | Description |
---|---|
token string |
Your Measure API token |
administration_id integer, optional |
ID of the administration to retrieve passages from |
with_manually_graded_questions boolean, optional |
Whether to return passages with manually graded questions |
ids integer array, optional |
A list of specific passages to return |
Partner: Users
When the ‘show name’ setting is enabled, both the first name and last name are required for user upsert and creation. Similarly, if the ‘show email’ setting is enabled, the email becomes mandatory for user upsert and creation.“
Upsert User (Partner)
Example response
{
"first_name": "John",
"alternate_email": null,
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"deleted_at": null,
"email_verified": false,
"metadata": {},
"updated_at": "2017-06-19T20:17:21Z",
"email": "johndoe@mail.com",
"address": null,
"user_groups": [],
"preferred_language": "en",
"alternate_email_verified": false,
"id": 544557,
"last_name": "doe",
"site_id": 19
}
HTTP Request
PUT https://api.ysasecure.com/v2/partner/users/<partner_id>/upsert
HTTP Put Params
Parameter | Description | Default |
---|---|---|
partner_id integer |
Partner ID of the user to retrieve | |
token string |
Your API token | |
user[username] string |
The login username to be created | |
user[site_id] integer |
Your Measure site ID | |
user[first_name] string |
First name of the new user | |
user[last_name] string |
Last name of the new user | |
user[email] string |
Email address for the new user | |
user[alternate_email] string, optional |
Alternate email for the new user (in case they lose access to their account) | |
user[address_attributes][address1] string |
Street address | |
user[address_attributes][address2] string, optional |
Secondary street address input (for apartment unit number, etc) | |
user[address_attributes][city] string |
City | |
user[address_attributes][province] string, optional |
Province or state | |
user[address_attributes][country] string |
Country | |
user[address_attributes][postal_code] string, optional |
Postal code or zip code | |
user[metadata] object, optional |
Additional metadata to include with the new user | |
user[preferred_language] string, optional |
Locale string for the user’s preferred language | |
send_email boolean, optional |
Whether or not to send the user a confirmation email upon creation | true |
Create User (Partner)
Example response
{
"first_name": "John",
"alternate_email": null,
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"deleted_at": null,
"email_verified": false,
"metadata": {},
"updated_at": "2017-06-19T20:17:21Z",
"email": "johndoe@mail.com",
"address": null,
"user_groups": [],
"preferred_language": "en",
"alternate_email_verified": false,
"id": 544557,
"last_name": "doe",
"site_id": 19
}
HTTP Request
POST https://api.ysasecure.com/v2/partner/users/
HTTP Post Params
Parameter | Description | Default |
---|---|---|
token string |
Your API token | |
user[partner_id] string |
The Partner ID of the user | |
user[username] string |
The login username to be created | |
user[site_id] integer |
Your Measure site ID | |
user[first_name] string |
First name of the new user | |
user[last_name] string |
Last name of the new user | |
user[email] string |
Email address for the new user | |
user[alternate_email] string, optional |
Alternate email for the new user (in case they lose access to their account) | |
user[address_attributes][address1] string |
Street address | |
user[address_attributes][address2] string, optional |
Secondary street address input (for apartment unit number, etc) | |
user[address_attributes][city] string |
City | |
user[address_attributes][province] string, optional |
Province or state | |
user[address_attributes][country] string |
Country | |
user[address_attributes][postal_code] string, optional |
Postal code or zip code | |
user[metadata] object, optional |
Additional metadata to include with the new user | |
user[preferred_language] string, optional |
Locale string for the user’s preferred language | |
send_email boolean, optional |
Whether or not to send the user a confirmation email upon creation | true |
Show User (Partner)
Example Response
{
"email_verified": false,
"first_name": null,
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"deleted_at": null,
"alternate_email": null,
"metadata": {},
"user_groups": [],
"updated_at": "2017-06-19T20:17:21Z",
"email": null,
"address": null,
"preferred_language": "en",
"alternate_email_verified": false,
"id": 544557,
"last_name": null,
"site_id": 19
}
HTTP Request
GET https://api.ysasecure.com/v2/partner/users/<partner_id>
HTTP Get Params
Parameter | Description |
---|---|
partner_id integer |
Partner ID of the user to retrieve |
token string |
Your API token |
site_id integer |
ID of the site that the user belongs to |
Update User (Partner)
Example response after changing the demo user’s first name, last name, and email
{
"deleted_at": null,
"first_name": "Demo",
"email_verified": false,
"alternate_email": null,
"preferred_language": "en",
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"metadata": {},
"updated_at": "2017-06-19T20:30:07Z",
"email": "testemail@getyardstick.com",
"address": null,
"user_groups": [],
"alternate_email_verified": false,
"id": 544557,
"last_name": "User",
"site_id": 19
}
HTTP Request
PUT https://api.ysasecure.com/v2/partner/users/<partner_id>
HTTP Put Params
Parameter | Description |
---|---|
partner_id integer |
Partner ID of the user to retrieve |
token string |
Your API token |
site_id integer |
ID of the site that the user belongs to |
user[username] string |
The login username to be created |
user[site_id] integer |
Your Measure site ID |
user[first_name] string, optional |
First name of the new user |
user[last_name] string, optional |
Last name of the new user |
user[email] string, optional |
Email address for the new user |
user[alternate_email] string, optional |
Alternate email for the new user (in case they lose access to their account) |
user[address_attributes][address1] string |
Street address |
user[address_attributes][address2] string, optional |
Secondary street address input (for apartment unit number, etc) |
user[address_attributes][city] string |
City |
user[address_attributes][province] string, optional |
Province or state |
user[address_attributes][country] string |
Country |
user[address_attributes][postal_code] string, optional |
Postal code or zip code |
user[metadata] object, optional |
Additional metadata to include with the new user |
user[preferred_language] string, optional |
Locale string for the user’s preferred language |
Destroy User (Partner)
Example response
{
"deleted_at": "2017-06-19T20:32:56Z",
"first_name": "Demo",
"email_verified": false,
"alternate_email": null,
"preferred_language": "en",
"username": "testuser",
"created_at": "2017-06-19T20:17:21Z",
"active": true,
"metadata": {},
"updated_at": "2017-06-19T20:32:56Z",
"email": "testemail@getyardstick.com",
"address": null,
"user_groups": [],
"alternate_email_verified": false,
"id": 544557,
"last_name": "User",
"site_id": 19
}
HTTP Request
DELETE https://api.ysasecure.com/v2/partner/users/<partner_id>
HTTP Delete Params
Parameter | Description |
---|---|
partner_id integer |
Partner ID of the user to retrieve |
token string |
Your API token |
site_id integer |
ID of the site that the user belongs to |
Partner: Grants
Index Grants (Partner)
Example response
[
{
"type": "ExamGrant",
"user_id": 544,
"deleted_at": null,
"created_at": "2017-06-19T21:33:54Z",
"grantable_id": 30,
"remaining_uses": null,
"attempts_count": 0,
"grantable_type": "Exam",
"exam": {
"marking_deadline_in_days": 0,
"metadata": {},
"name": "Demo Exam",
"id": 30
},
"exam_form_group": "active",
"metadata": {},
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://measure-demo.ysasecure.com/grants/108/bookings/new"
},
"updated_at": "2017-06-19T21:33:54Z",
"expire_at": null,
"num_uses": null,
"allow_sittings_start_at": null,
"exam_form_id": 88,
"start_at": "2017-06-19T21:33:54Z",
"parent_grant_id": null,
"id": 10886,
"exam_form": {
"deleted_at": null,
"created_at": "2017-01-25T14:56:29Z",
"active": true,
"updated_at": "2017-01-25T14:56:29Z",
"name": "Form 1",
"id": 88
},
"allow_sittings_end_at": null,
"user": {
"first_name": null,
"alternate_email": null,
"preferred_language": "en",
"username": "testuser",
"deleted_at": null,
"created_at": "2017-06-19T21:30:09Z",
"active": true,
"user_groups": [],
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email_verified": false,
"email": null,
"address": null,
"alternate_email_verified": false,
"id": 544,
"last_name": null,
"site_id": 0
}
}
]
HTTP Request
GET https://api.ysasecure.com/v2/partner/users/<partner_id>/grants
HTTP Get Params
Parameter | Description |
---|---|
partner_id integer |
Partner ID of the user to retrieve grants from |
token string |
Your Measure API token |
site_id integer |
ID of the site that the user and grant belongs to |
Create Grant (Partner)
Example response
[
{
"allow_sittings_start_at": null,
"num_uses": 2,
"type": "ExamGrant",
"user_id": 544,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
},
"exam_form": null,
"allow_sittings_end_at": null,
"parent_grant_id": null,
"user": {
"first_name": null,
"username": "testuser",
"created_at": "2017-06-19T21:30:09Z",
"user_groups": [],
"alternate_email_verified": false,
"active": true,
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email_verified": false,
"email": null,
"address": null,
"preferred_language": "en",
"id": 544,
"deleted_at": null,
"alternate_email": null,
"last_name": null,
"site_id": 0
},
"exam_form_group": "active",
"created_at": "2017-06-22T20:45:44Z",
"exam": {
"marking_deadline_in_days": 0,
"metadata": {},
"name": "Demo Exam",
"id": 30
},
"exam_form_id": null,
"metadata": {},
"updated_at": "2017-06-22T20:45:44Z",
"expire_at": null,
"grantable_id": 30,
"attempts_count": 0,
"remaining_uses": 2,
"start_at": "2017-06-22T14:45:44-06:00",
"grantable_type": "Exam",
"id": 109,
"deleted_at": null
}
]
HTTP Request
POST https://api.ysasecure.com/v2/partner/users/<partner_id>/grants
HTTP Post Params
Parameter | Description |
---|---|
partner_id integer |
Partner ID of the user the grant will belong to |
token string |
Your Measure API token |
site_id integer |
ID of the site that the user and grant belong to |
grantable[id] integer, optional |
Measure’s Exam/Course ID |
grantable[partner_id] string, optional |
Your configured Partner ID |
grantable[site_id] integer, optional |
Site ID associated with the grantable[partner_id] |
grantable[type] string |
Either "Exam” or “Edition” |
grant[num_uses] integer |
Number of attempts the candidate is allowed |
grant[start_at] time with zone, optional |
Exams will be available from this time |
grant[expire_at] time with zone, optional |
Exams will not be available after this date |
grant[allow_sittings_start_at] time with zone, optional |
Only allow booking into sessions starting after the given time |
grant[allow_sittings_end_at] time with zone, optional |
Only allow booking into sessions starting before the given time |
grant[time_zone_name] timezone, optional |
Time zone that the grant is being assigned within |
grant[exam_form_id] string, optional |
Measure’s Exam Form ID (if you want to grant a specific form) |
grant[metadata] object, optional |
Any additional meta data you’d like to include |
grant[send_email] boolean, optional |
Any additional meta data you’d like to include |
Show Grant (Partner)
Example response
[
{
"type": "ExamGrant",
"user_id": 544,
"deleted_at": null,
"created_at": "2017-06-19T21:33:54Z",
"grantable_id": 30,
"remaining_uses": null,
"attempts_count": 0,
"grantable_type": "Exam",
"exam": {
"marking_deadline_in_days": 0,
"metadata": {},
"name": "Demo Exam",
"id": 30
},
"exam_form_group": "active",
"metadata": {},
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://measure-demo.ysasecure.com/grants/108/bookings/new"
},
"updated_at": "2017-06-19T21:33:54Z",
"expire_at": null,
"num_uses": null,
"allow_sittings_start_at": null,
"exam_form_id": 88,
"start_at": "2017-06-19T21:33:54Z",
"parent_grant_id": null,
"id": 10886,
"exam_form": {
"deleted_at": null,
"created_at": "2017-01-25T14:56:29Z",
"active": true,
"updated_at": "2017-01-25T14:56:29Z",
"name": "Form 1",
"id": 88
},
"allow_sittings_end_at": null,
"user": {
"first_name": null,
"alternate_email": null,
"preferred_language": "en",
"username": "testuser",
"deleted_at": null,
"created_at": "2017-06-19T21:30:09Z",
"active": true,
"user_groups": [],
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email_verified": false,
"email": null,
"address": null,
"alternate_email_verified": false,
"id": 544,
"last_name": null,
"site_id": 0
}
}
]
HTTP Request
GET https://api.ysasecure.com/v2/partner/users/<partner_id>/grants/<grant_id>
HTTP Get Params
Parameter | Description |
---|---|
partner_id integer |
Partner ID of the user the grant belongs to |
grant_id integer |
ID of the grant being shown |
site_id integer |
ID of the site that the user and grant belongs to |
token string |
Your Measure API token |
Update Grant (Partner)
Example response
{
"type": "ExamGrant",
"user_id": 544,
"exam": {
"metadata": {},
"marking_deadline_in_days": 0,
"name": "Demo Exam",
"id": 30
},
"exam_form_id": null,
"user": {
"first_name": null,
"username": "testuser",
"created_at": "2017-06-19T21:30:09Z",
"alternate_email_verified": false,
"active": true,
"email_verified": false,
"metadata": {},
"deleted_at": null,
"updated_at": "2017-06-19T21:30:09Z",
"alternate_email": null,
"email": null,
"address": null,
"preferred_language": "en",
"id": 544,
"user_groups": [],
"last_name": null,
"site_id": 0
},
"parent_grant_id": null,
"created_at": "2017-06-22T20:45:44Z",
"allow_sittings_start_at": null,
"metadata": {},
"remaining_uses": 3,
"exam_form": null,
"allow_sittings_end_at": null,
"deleted_at": null,
"updated_at": "2017-06-22T20:59:23Z",
"expire_at": null,
"grantable_id": 30,
"attempts_count": 0,
"exam_form_group": "active",
"start_at": "2017-06-22T20:45:44Z",
"grantable_type": "Exam",
"num_uses": 3,
"id": 109,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
}
}
HTTP Request
PUT https://api.ysasecure.com/v2/partner/users/<partner_id>/grants/<grant_id>
HTTP Put Params
Parameter | Description |
---|---|
partner_id integer |
Partner ID of the user the grant belongs to |
grant_id integer |
ID of the grant being updated |
token string |
Your Measure API token |
site_id integer |
ID of the site that the user and grant belongs to |
grant[num_uses] integer, optional |
Number of attempts the candidate is allowed |
grant[start_at] time with zone, optional |
Exams will be available from this time |
grant[expire_at] time with zone, optional |
Exams will not be available after this date |
grant[allow_sittings_start_at] time with zone, optional |
Only allow booking into sessions starting after the given time |
grant[allow_sittings_end_at] time with zone, optional |
Only allow booking into sessions starting before the given time |
grant[time_zone_name] timezone, optional |
Time zone that the grant is being assigned within |
grant[exam_form_id] string, optional |
Measure’s Exam Form ID (if you want to grant a specific form) |
grant[exam_form_group] string, optional |
Exam Form Group |
Destroy Grant (Partner)
Example response
{
"type": "ExamGrant",
"user_id": 544,
"allow_sittings_start_at": null,
"parent_grant_id": null,
"exam_launch_status": {
"status": "requires_booking",
"launch_url": "https://beta.ysasecure.com/grants/109/bookings/new"
},
"exam_form": null,
"allow_sittings_end_at": null,
"created_at": "2017-06-22T20:45:44Z",
"num_uses": 3,
"user": {
"first_name": null,
"preferred_language": "en",
"username": "aleciatest2",
"created_at": "2017-06-19T21:30:09Z",
"user_groups": [],
"alternate_email_verified": false,
"email_verified": false,
"active": true,
"alternate_email": null,
"deleted_at": null,
"metadata": {},
"updated_at": "2017-06-19T21:30:09Z",
"email": null,
"address": null,
"id": 544,
"last_name": null,
"site_id": 0
},
"deleted_at": "2017-06-22T21:04:05Z",
"metadata": {},
"updated_at": "2017-06-22T21:04:05Z",
"expire_at": null,
"grantable_id": 30,
"attempts_count": 0,
"remaining_uses": 3,
"exam_form_id": null,
"start_at": "2017-06-22T20:45:44Z",
"grantable_type": "Exam",
"id": 109,
"exam": {
"marking_deadline_in_days": 0,
"metadata": {},
"name": "Demo Exam",
"id": 30
},
"exam_form_group": "active"
}
HTTP Request
DELETE https://api.ysasecure.com/v2/partner/users/<partner_id>/grants/<grant_id>
HTTP Delete Params
Parameter | Description |
---|---|
partner_id integer |
Partner ID of the user the grant belongs to |
grant_id integer |
ID of the grant being deleted |
token string |
Your Measure API token |
site_id integer |
ID of the site that the user and grant belongs to |
Webhooks
Yardstick Measure allows you to export information as it happens via a series of Webhooks. Webhooks can be defined in Measure’s Administration Portal under the Settings tab and then by selecting WebHooks in the following submenu.
Here you can define a URL to send the relevant information to. Then every time something relevant (to the selected record type) occurs - Yardstick Measure will send a POST request to the configured URL. Example payloads for each record type can be found in their relevant sections below.
Booking
Triggered whenever a Booking
is created, updated, or cancelled (via the API or through the user interface). A Booking
is only available for accounts that use Booking Sessions
as their booking system.
Important Attributes
Attribute | Description |
---|---|
deleted_at datetime |
Usually null unless the booking has been cancelled. Otherwise is the date/time of the cancellation. |
Example Payload
{
"user": {
"display_name": "Demo User",
"alternate_email": "",
"user_name": "demo.user",
"active": true,
"deleted_at": null,
"preferred_language": "en",
"first_name": "Demo",
"metadata": {},
"email_verified": false,
"address": null,
"created_at": "2017-11-01T16:07:47Z",
"username": "demo.user",
"alternate_email_verified": false,
"email": "demo.user@getyardstick.com",
"last_name": "User",
"full_name": "Demo User",
"updated_at": "2017-11-01T16:07:47Z",
"id": 585972
},
"deleted_at": null,
"sitting": {
"begin_booking_at": null,
"venue_tbd": false,
"session_type": "exam",
"require_purchase_before": null,
"local_end_datetime": "2017-11-16T15:45:00Z",
"deleted_at": null,
"seats": null,
"local_start_datetime": "2017-11-16T11:15:00Z",
"end_booking_at": null,
"cancellation_deadline": null,
"metadata": {},
"created_at": "2017-11-01T16:06:55Z",
"venue": {
"available_for_courses": true,
"phone": "",
"deleted_at": null,
"lab_capacity": null,
"restricted": false,
"notes": "",
"details_for_user": null,
"metadata": {},
"address": {
"province_name": "Alberta",
"country": "CA",
"postal_code": "T5T 5T5",
"city": "Edmonton",
"address1": "1234 Java Parkway",
"address2": null,
"province": "AB",
"country_name": "Canada",
"updated_at": "2015-07-28T19:08:37Z"
},
"location": "Demo Location 1",
"created_at": null,
"fax": "",
"web": "",
"available_for_exams": true,
"email": "",
"hours_of_operation": "",
"updated_at": "2015-07-28T19:08:37Z",
"id": 831
},
"has_waiting_list": false,
"private": false,
"room": "",
"updated_at": "2017-11-01T16:06:55Z",
"id": 69484
},
"metadata": {},
"grant": {
"expire_at": null,
"grantable_id": 1306,
"allow_sittings_start_at": null,
"type": "ExamGrant",
"exam_form_id": null,
"start_at": "2017-11-01T16:08:25Z",
"grantable_type": "Exam",
"exam_form_group": "active",
"uses": 0,
"deleted_at": null,
"user_id": 585972,
"allow_sittings_end_at": null,
"metadata": {},
"created_at": "2017-11-01T16:08:25Z",
"parent_grant_id": null,
"num_uses": 1,
"remaining_uses": 1,
"updated_at": "2017-11-01T16:08:25Z",
"order_id": null,
"id": 1156792
},
"created_at": "2017-11-01T16:08:47Z",
"attendance_status": "booked",
"updated_at": "2017-11-01T16:08:47Z",
"id": 598879
}
Booking Request
Triggered whenever a Booking Request
is created, updated, or cancelled (via the API or through the user interface). A Booking Request
is only available for accounts that use Booking Requests
as their booking system.
Example Payload
{
"date3":"2019-12-31",
"date3_am":true,
"date1":"2019-12-27",
"date2":"2019-12-30",
"id":16,
"created_at":"2019-12-03T15:25:29Z",
"booked":true,
"state":"booked",
"user_id":128,
"updated_at":"2019-12-03T15:27:02Z",
"venue":{
"address":{
"province":"ON",
"updated_at":"2018-10-04T17:13:06Z",
"address1":"365 Bloor Street East",
"address2":null,
"country_name":"Canada",
"country":"CA",
"province_name":"Ontario",
"city":"Toronto",
"postal_code":"M4W 3L4"
},
"details_for_user":null,
"location":"Toronto Venue",
"notes":"",
"email":"",
"id":18,
"created_at":"2018-10-04T17:13:06Z",
"lab_capacity":null,
"updated_at":"2018-11-07T21:35:11Z",
"available_for_exams":true,
"available_for_courses":true,
"metadata":{},
"active":true,
"hours_of_operation":"",
"deleted_at":null,
"phone":"",
"web":"",
"restricted":false,
"fax":""
},
"grant":{
"allow_sittings_end_at":null,
"id":3928,
"created_at":"2019-12-03T15:24:09Z",
"grantable_id":125,
"user_id":128,
"updated_at":"2019-12-03T15:24:09Z",
"expire_at":null,
"exam_form_group":"active",
"allow_sittings_start_at":null,
"remaining_uses":null,
"exam_form_id":206,
"metadata":{},
"parent_grant_id":null,
"type":"ExamGrant",
"deleted_at":null,
"uses":0,
"start_at":"2019-12-03T15:24:09Z",
"grantable_type":"Exam",
"num_uses":null,
"order_id":null
},
"local_start_at":"2019-12-27T16:00:00Z",
"user":{
"address":null,
"last_name":"date",
"email":"candidate@email.com",
"id":128,
"created_at":"2018-10-04T17:19:26Z",
"alternate_email":"",
"user_name":"candidate",
"updated_at":"2019-12-03T15:24:52Z",
"display_name":"candi date",
"email_verified":false,
"metadata":{},
"first_name":"candi",
"full_name":"candi date",
"active":true,
"deleted_at":null,
"username":"candidate",
"preferred_language":"en",
"alternate_email_verified":false
},
"date1_am":true,
"date2_am":true,
"local_end_at":"2019-12-27T18:00:00Z",
"grant_id":3928,
"venue_id":18
}
Course
Triggered when a Course
is created, updated or deleted (via the API or through the user interface).
Example Payload
{
"created_at": "2023-11-21T07:41:20Z",
"editions": [
{
"distinction_mark": 90,
"pass_mark": 80,
"delivery_method": "online",
"course_items": [
{
"upload_file_name": null,
"label": "Sitting Exam",
"image_width": null,
"expire_in_days": null,
"image_height": null,
"upload_content_type": null,
"require_pass": false,
"scorm_import_job_id": null,
"scorm_package_name": null,
"upload_file_size": null,
"updated_at": "2023-11-21T07:42:04Z",
"exam_id": 3,
"created_at": "2023-11-21T07:42:04Z",
"upload_updated_at": null,
"practice": true,
"edition_id": 1,
"type": "ExamCourseItem",
"url": null,
"id": 1,
"deleted_at": null,
"position": 1,
"number_of_uses": 1
}
],
"gradeable_course_item_id": null,
"updated_at": "2023-11-21T07:41:20Z",
"manual_grade_format": null,
"created_at": "2023-11-21T07:41:20Z",
"language": "en",
"name": "Elite",
"course_id": 1,
"id": 1,
"deleted_at": null
}
],
"name": "New Course",
"metadata": {},
"hide_when_finished": false,
"account_id": 1,
"prereq_pass_required": false,
"award_items": [
{
"award_id": 1,
"created_at": "2024-02-05T06:27:07Z",
"id": 1,
"updated_at": "2024-02-05T06:27:07Z",
"item_id": 1,
"item_type": "Course"
}
],
"id": 1,
"deleted_at": null,
"updated_at": "2023-11-21T07:41:20Z"
}
Course Grant
Triggered when a Course Grant
is created, updated or deleted. A Course Grant
is typically created whenever a Course
is granted to a User.
Example Payload
{
"allow_sittings_end_at":null,
"id":264,
"created_at":"2018-04-09T13:57:22Z",
"grantable_id":1,
"user_id":52,
"updated_at":"2018-04-09T13:57:22Z",
"expire_at":null,
"exam_form_group":"unknown",
"allow_sittings_start_at":null,
"remaining_uses":null,
"exam_form_id":null,
"metadata":{},
"parent_grant_id":null,
"type":"CourseGrant",
"deleted_at":null,
"user":{
"address":null,
"last_name":"date",
"email":"candidate@mail.com",
"id":52,
"created_at":"2017-09-14T14:43:33Z",
"alternate_email":"",
"user_name":"candidate",
"updated_at":"2018-09-12T13:33:57Z",
"display_name":"candi date",
"email_verified":false,
"metadata":{},
"first_name":"candi",
"full_name":"candi date",
"active":false,
"deleted_at":null,
"username":"candidate",
"preferred_language":"en",
"alternate_email_verified":false
},
"uses":1,
"start_at":"2018-04-09T13:57:00Z",
"course":{
"name":"Course1",
"id":1,
"created_at":"2017-07-24T19:17:31Z",
"updated_at":"2018-07-06T13:40:36Z",
"metadata":{},
"deleted_at":null
},
"edition":{
"pass_mark":50.0,
"name":"Default",
"id":1,
"created_at":"2017-07-24T19:17:32Z",
"language":"en",
"updated_at":"2018-04-09T13:39:41Z",
"delivery_method":"online",
"course_id":1,
"deleted_at":null,
"distinction_mark":90.0
},
"grantable_type":"Edition",
"num_uses":null,
"order_id":null
}
Exam
Triggered when a Exam
is created, updated or deleted.
Example Payload
{
"created_at": "2017-07-28T18:13:16Z",
"require_booking": true,
"id": 27,
"locked": false,
"available_for_paper": false,
"pass_fail_review": 0.0,
"partner_id": null,
"require_proctor": "proctored",
"updated_at": "2019-04-24T15:06:26Z",
"time_limit_in_minutes": null,
"deleted_at": null,
"metadata": {},
"strict_mode": false,
"active": true,
"send_emails": true,
"available_for_online": true,
"in_review": true,
"name": "Hi-Steak Exam",
"shuffle_everything": false,
"pass_mark": 50.0,
"show_as_you_go": false,
"passing_strategy": "total_score"
}
Exam Grant
Triggered when an Exam Grant
is created, updated or deleted. An Exam Grant
is typically created whenever an Exam
is granted to a User.
Example Payload
{
"id": 105,
"allow_sittings_start_at": null
"allow_sittings_end_at": null,
"deleted_at": null,
"exam_form": null,
"grantable_id": 1,
"grantable_type": "Exam",
"order_id": 245,
"num_uses": null,
"exam_form_group": "unknown",
"exam_form_id": null,
"type": "ExamGrant",
"start_at": "2022-12-29T17:45:30Z",
"exam": {
"send_emails": true,
"deleted_at": null,
"available_for_paper": false,
"created_at": "2022-10-10T21:28:26Z",
"metadata": {},
"active": true,
"locked": false,
"time_limit_in_minutes": 300,
"pass_mark": 50,
"updated_at": "2023-09-20T18:55:29Z",
"pass_fail_review": 0,
"name": "Exam 1",
"id": 1,
"strict_mode": false,
"shuffle_everything": false,
"in_review": false,
"require_booking": false,
"partner_id": null,
"passing_strategy": "total_score",
"require_proctor": "unproctored",
"show_as_you_go": false,
"available_for_online": true
},
"created_at": "2022-12-29T17:45:30Z",
"remaining_uses": null,
"metadata": {},
"expire_at": null,
"uses": 0,
"parent_grant_id": null,
"updated_at": "2022-12-29T17:45:30Z",
"user_id": 2,
"user": {
"email": "info+2@yardsticksoftware.com",
"last_name": "Jakubowski",
"deleted_at": null,
"created_at": "2022-10-10T21:28:26Z",
"first_name": "Fernando",
"metadata": {},
"active": true,
"alternate_email": null,
"preferred_language": "en",
"username": "user_2",
"email_verified": false,
"full_name": "Fernando Jakubowski",
"address": {
"address2": "Suite 200",
"province_name": "Alberta",
"postal_code": "T6E 6E6",
"account_id": 1,
"created_at": "2022-10-10T21:28:26Z",
"country": "CA",
"country_name": "Canada",
"latitude": null,
"time_zone_name": null,
"longitude": null,
"updated_at": "2022-10-10T21:28:26Z",
"id": 3,
"city": "Edmonton",
"province": "AB",
"address1": "8616 51 Avenue NW"
},
"updated_at": "2023-05-03T17:54:54Z",
"alternate_email_verified": false,
"display_name": "Fernando Jakubowski",
"id": 2,
"partner_id": null,
"user_name": "user_2"
}
}
Grant
Triggered when either a Course Grant
or an Exam Grant
has been created, updated, or destroyed. This serves as an abstraction of both the Exam Grant webhook and the Course Grant webhook.
Order
Triggered when an Order
has been created, updated, or destroyed. An Order
is created whenever a User purchases a Course
, Exam
, or Product
.
Example Payload
{
"shipping_address": null,
"payment_type_name": "visa",
"delivery_method": "online",
"created_at": "2020-11-11T22:54:16Z",
"updated_at": "2020-11-11T22:54:19Z",
"id": 0000,
"federal_tax_amount": 0,
"provincial_tax_amount": 0,
"shipped": false,
"sitting": {
"created_at": "2020-02-03T19:17:28Z",
"updated_at": "2020-02-03T19:17:28Z",
"id": 0000,
"has_waiting_list": false,
"room": "",
"seats": null,
"cancellation_deadline": "2021-01-02T04:59:00Z",
"session_type": "exam",
"venue": null,
"local_start_datetime": null,
"local_end_datetime": null,
"deleted_at": null,
"private": false,
"require_purchase_before": "2020-12-02T04:59:00Z",
"begin_booking_at": null,
"end_booking_at": "2021-01-02T04:59:00Z",
"venue_tbd": false
},
"tracking_code": null,
"deleted_at": null,
"buyer_type": "User",
"tax": 0,
"federal_tax_code": null,
"cancellation_note": null,
"provincial_tax_code": null,
"tax_data": null,
"buyer": {
"email": "user@email.com",
"username": "#",
"created_at": "2020-11-11T19:45:13Z",
"updated_at": "2020-11-11T22:09:39Z",
"active": true,
"id": 0000,
"user_name": "#",
"alternate_email": "user@email.com",
"alternate_email_verified": true,
"full_name": "User Name",
"preferred_language": "en",
"partner_id": "partner_id",
"deleted_at": null,
"email_verified": true,
"first_name": "User",
"display_name": "User Name",
"last_name": "Name",
"address": {
"country_name": "Country",
"address1": "00",
"province_name": null,
"city": "city",
"postal_code": "0000",
"updated_at": "2020-11-11T19:45:23Z",
"address2": "",
"country": "CC",
"province": ""
}
},
"paid_at": "2020-11-11T22:54:16Z",
"total": 0000,
"discount": 0,
"shipping": 0,
"subtotal": 0000,
"tax_region": null,
"currency": "USD",
"order_items": [
{
"discount_in_cents": 0,
"quantity": 1,
"product": {
"price_in_cents": 0000,
"deleted_at": null,
"delivery_method": "online",
"created_at": "2012-01-11T07:28:21Z",
"name": "name of product",
"active": true,
"id": 591,
"updated_at": "2020-01-30T11:03:11Z",
"delivery_method_name": "Online",
"web-content": {
"custom-web-content": "contains custom web content to display for said product"
},
"notifications": {
"email": "no"
}
},
"price": 0000,
"amount": 0000
}
],
"billing_address": {
"country_name": "Country",
"address1": "31",
"province_name": null,
"city": "city",
"postal_code": "0000",
"updated_at": "2020-11-11T19:45:23Z",
"address2": "",
"country": "CC",
"province": ""
}
}
Product
Triggered when a Product
has been created, updated, or destroyed (via the API or through the user interface).
Example Payload
{
"show_to_warehouse": false,
"created_at": "2023-05-05T21:01:50Z",
"product_action": {
"updated_at": "2023-05-08T18:13:51Z",
"number_of_uses": 1,
"created_at": "2023-05-08T18:13:15Z",
"id": 25,
"grantable_id": 8,
"grantable_type": "Edition",
"expire_in_days": null,
"grantable_name": "Default"
},
"prices": {
"Friends & family": 2250,
"Regular": 2500
},
"active": true,
"locales": [
"fr"
],
"metadata": {
"extra-details": {
"category": [
"Bravo"
]
}
},
"bookable_grantable_id": 0,
"hidden": false,
"delivery_method": "online",
"bookable_grantable_type": null,
"updated_at": "2023-05-08T18:15:06Z",
"name": "Webhook Observer",
"id": 27,
"price_in_cents": 2500,
"deleted_at": null,
"description": "<p>Description of this product</p>"
}
Program
Triggered when a Program
has been created, updated, or destroyed (via the API or through the user interface).
Example Payload
{
"updated_at": "2023-11-22T08:09:01Z",
"total_elective_courses": 0,
"created_at": "2023-11-22T06:27:28Z",
"name": "Trigger Prog Tes",
"metadata": {},
"id": 2,
"active": true,
"total_required_elective_courses": 0,
"program_requirements": [
{
"mandatory": true,
"updated_at": "2023-11-22T06:27:55Z",
"program_id": 2,
"created_at": "2023-11-22T06:27:55Z",
"name": "Added Requirement",
"id": 2,
"total_required_courses": 1,
"required_number_of_elective_courses": null,
"requirement_courses": [
{
"updated_at": "2023-11-22T06:27:55Z",
"created_at": "2023-11-22T06:27:55Z",
"course": {
"updated_at": "2023-11-21T07:41:20Z",
"created_at": "2023-11-21T07:41:20Z",
"name": "New Course",
"metadata": {},
"account_id": 1,
"id": 1,
"hide_when_finished": false,
"prereq_pass_required": false,
"deleted_at": null
},
"id": 2,
"program_requirement_id": 2,
"course_id": 1
}
]
}
],
"total_mandatory_courses": 1
}
Sitting
Triggered when a Sitting
has been created, updated, or destroyed (via the API or through the user interface).
Example Payload
{
"sitting": {
"created_at": "2023-11-16T19:05:30Z",
"require_purchase_before": null,
"metadata": {},
"cancellation_deadline": null,
"id": 121741,
"virtual_start_datetime": null,
"deleted_at": null,
"seats": null,
"local_start_datetime": "2023-11-28T07:00:00Z",
"local_end_datetime": "2023-11-30T07:00:00Z",
"session_type": "exam",
"virtual_end_datetime": null,
"updated_at": "2023-11-16T19:05:30Z",
"private": false,
"venue": {
"email": "",
"created_at": "2023-10-02T18:32:28Z",
"lab_capacity": null,
"available_for_courses": true,
"available_for_exams": true,
"hours_of_operation": "",
"id": 5125,
"restricted": false,
"phone": "5879873950",
"details_for_user": "",
"availability": "all",
"address": {
"city": "San Diego",
"updated_at": "2023-10-02T18:32:28Z",
"created_at": "2023-10-02T18:32:28Z",
"time_zone_name": "America/Los_Angeles",
"id": 5084,
"province": "CA",
"account_id": 132,
"province_name": "California",
"country_name": "United States",
"country": "US",
"address1": "3604 Beyer Boulevard, San Diego, CA, USA",
"postal_code": "12205",
"address2": "7 Ave SW",
"latitude": null,
"longitude": null
},
"deleted_at": null,
"metadata": {},
"active": true,
"web": "",
"network": null,
"fax": "",
"location": "Alaska",
"notes": "",
"updated_at": "2023-10-02T18:32:28Z"
},
"begin_booking_at": null,
"room": "",
"venue_tbd": false,
"has_waiting_list": false,
"end_booking_at": null
}
}
User
Triggered when a User
is created, updated or deleted (via the API or through the user interface).
Example Payload
{
"created_at":"2019-07-16T16:18:15Z",
"alternate_email":"",
"first_name":"Example",
"address":null,
"updated_at":"2019-07-16T16:20:27Z",
"atc_id":null,
"alternate_email_verified":false,
"username":"example",
"atc_name":null,
"metadata":{},
"deleted_at":null,
"establishment":null,
"full_name":"Example User",
"email":"example@yas.getyardstick.com",
"email_verified":false,
"last_name":"User",
"display_name":"Example User",
"active":true,
"preferred_language":"en",
"id":14
}
User Course
Triggered when a User Course
is created or completed. A User Course
is created whenever a User starts a Course
.
Example Payload
{
"id": 26,
"course_grant": {
"start_at": "2024-01-24T21:05:00Z",
"grantable_id": 1,
"grantable_type": "Edition",
"updated_at": "2024-01-24T21:05:58Z",
"user_id": 3,
"remaining_uses": null,
"expire_at": null,
"id": 208,
"parent_grant_id": null,
"created_at": "2024-01-24T21:05:58Z",
"course": {
"created_at": "2022-12-12T18:42:54Z",
"name": "Course Name",
"metadata": {},
"account_id": 1,
"updated_at": "2023-12-13T19:16:24Z",
"prereq_pass_required": false,
"hide_when_finished": false,
"deleted_at": null,
"id": 1
},
"uses": 1,
"type": "CourseGrant",
"edition": {
"course_id": 1,
"created_at": "2022-12-12T18:42:54Z",
"name": "Default",
"delivery_method": "online",
"updated_at": "2022-12-12T18:42:54Z",
"distinction_mark": 90,
"deleted_at": null,
"pass_mark": 80,
"language": "en",
"id": 1
},
"metadata": {},
"allow_sittings_start_at": null,
"allow_sittings_end_at": null,
"user": {
"email": "candidate@email.com",
"user_name": "example",
"metadata": {},
"active": true,
"updated_at": "2024-01-24T21:06:05Z",
"username": "example",
"display_name": "Example User",
"last_name": "User",
"full_name": "Example User",
"id": 3,
"alternate_email": "",
"alternate_email_verified": false,
"created_at": "2022-12-09T16:42:21Z",
"preferred_language": "en",
"partner_id": null,
"deleted_at": null,
"email_verified": false,
"first_name": "Example",
"address": {
"country_name": "Canada",
"account_id": 1,
"country": "CA",
"updated_at": "2022-12-09T16:42:21Z",
"latitude": null,
"province": "AB",
"longitude": null,
"id": 4,
"province_name": "Alberta",
"created_at": "2022-12-09T16:42:21Z",
"address1": "8616 51 Avenue NW",
"city": "Edmonton",
"time_zone_name": null,
"postal_code": "T6E 6E6",
"address2": "Suite 200"
}
},
"exam_form_group": "unknown",
"order_id": null,
"num_uses": null,
"exam_form_id": null,
"deleted_at": null
},
"finished_at": "2024-01-24T21:59:15Z",
"result": null,
"created_at": "2024-01-24T21:51:40Z",
"course": {
"created_at": "2022-12-12T18:42:54Z",
"name": "Course Name",
"metadata": {},
"account_id": 1,
"updated_at": "2023-12-13T19:16:24Z",
"prereq_pass_required": false,
"hide_when_finished": false,
"deleted_at": null,
"id": 1
},
"user_course_items": [
{
"course_item_label": "item 1",
"user_course_id": 26,
"score": 0,
"complete": true,
"course_item_id": 2,
"updated_at": "2024-01-24T21:51:46Z",
"created_at": "2024-01-24T21:51:46Z",
"grant_id": null,
"id": 49
},
{
"course_item_label": "item 2",
"user_course_id": 26,
"score": 0,
"complete": true,
"course_item_id": 4,
"updated_at": "2024-01-24T21:52:52Z",
"created_at": "2024-01-24T21:52:52Z",
"grant_id": null,
"id": 50
},
{
"course_item_label": "item 3",
"user_course_id": 26,
"score": 0,
"complete": true,
"course_item_id": 5,
"updated_at": "2024-01-24T21:56:25Z",
"created_at": "2024-01-24T21:56:25Z",
"grant_id": null,
"id": 51
}
],
"updated_at": "2024-01-24T21:59:15Z",
"mark": null,
"user": {
"email": "candidate@email.com",
"user_name": "example",
"metadata": {},
"active": true,
"updated_at": "2024-01-24T21:06:05Z",
"username": "example",
"display_name": "Example User",
"last_name": "User",
"full_name": "Example User",
"id": 3,
"alternate_email": "",
"alternate_email_verified": false,
"created_at": "2022-12-09T16:42:21Z",
"preferred_language": "en",
"partner_id": null,
"deleted_at": null,
"email_verified": false,
"first_name": "Example",
"address": {
"country_name": "Canada",
"account_id": 1,
"country": "CA",
"updated_at": "2022-12-09T16:42:21Z",
"latitude": null,
"province": "AB",
"longitude": null,
"id": 4,
"province_name": "Alberta",
"created_at": "2022-12-09T16:42:21Z",
"address1": "8616 51 Avenue NW",
"city": "Edmonton",
"time_zone_name": null,
"postal_code": "T6E 6E6",
"address2": "Suite 200"
}
},
"participation_mark": null
}
User Course Item
Triggered when a User Course Item
is created, updated, or destroyed.
External User Course Items
are created the first time a User opens a given Course
. Other User Course Item
types are created the first time a User opens a given Course Item
in a User Course
.
Example Payload
{
"course_item_label": "item 1",
"user_course_id": 26,
"score": 0,
"complete": true,
"course_item_id": 2,
"updated_at": "2024-01-24T21:51:46Z",
"created_at": "2024-01-24T21:51:46Z",
"grant_id": null,
"id": 49
}
User Exam
Triggered when Measure finishes calculating the grade for the User
. This can be delayed when there are constructed response questions that cannot be automatically graded.
Example Payload
{
"booked": true,
"results": {
"passed": true,
"marking_complete": true,
"finished_at": "2015-05-11T20:57:45Z",
"answered": 2,
"finished": "2015-05-11T20:57:45Z",
"elapsed": 0,
"points": 21,
"time_elapsed_in_seconds": 0,
"correct": 0,
"started": "2015-05-11T20:57:27Z",
"global_attempt_number": 1,
"incorrect": 2,
"total_points": 30,
"started_at": "2015-05-11T20:57:27Z",
"equated_points": null,
"score": 70,
"scaled_points": null,
"attempt_number": 1,
"equated_score": null,
"skipped": 0
},
"proctor": {
"deleted_at": null,
"first_name": "Demo",
"created_at": "2013-10-02T15:44:55Z",
"email": "demoproctor@getyardstick.com",
"last_name": "Proctor",
"updated_at": "2017-10-13T20:07:30Z",
"id": 599
},
"finished_at": "2015-05-11T20:57:45Z",
"parts": [
{
"break_length_in_minutes": null,
"finished_at": "2015-05-11T20:57:45Z",
"time_elapsed_in_seconds": 0,
"number_of_questions": 2,
"started_at": "2015-05-11T20:57:28Z",
"time_limit_in_minutes": 0
}
],
"user": {
"display_name": "Demo User",
"alternate_email": null,
"user_name": "demo.user",
"active": true,
"deleted_at": null,
"preferred_language": "en",
"first_name": "Demo",
"metadata": {},
"email_verified": false,
"address": null,
"created_at": "2013-09-02T02:36:20Z",
"username": "demo.user",
"alternate_email_verified": false,
"email": "demo.user@getyardstick.com",
"last_name": "User",
"full_name": "Demo User",
"updated_at": "2015-05-11T21:00:03Z",
"id": 247441
},
"sitting": {
"begin_booking_at": null,
"venue_tbd": false,
"session_type": "exam",
"require_purchase_before": null,
"local_end_datetime": "2015-05-12T14:30:00Z",
"deleted_at": null,
"seats": null,
"local_start_datetime": "2015-05-12T12:30:00Z",
"end_booking_at": null,
"cancellation_deadline": null,
"metadata": {},
"created_at": "2015-05-11T18:20:47Z",
"venue": {
"available_for_courses": true,
"phone": "",
"deleted_at": null,
"lab_capacity": null,
"restricted": false,
"notes": "",
"details_for_user": null,
"metadata": {},
"address": {
"province_name": "Alberta",
"country": "CA",
"postal_code": "T5T 5T5",
"city": "Edmonton",
"address1": "1234 Java Parkway",
"address2": null,
"province": "AB",
"country_name": "Canada",
"updated_at": "2015-07-28T19:08:37Z"
},
"location": "Demo Location 1",
"created_at": null,
"fax": "",
"web": "",
"available_for_exams": true,
"email": "",
"hours_of_operation": "",
"updated_at": "2015-07-28T19:08:37Z",
"id": 831
},
"has_waiting_list": false,
"private": false,
"room": "66",
"updated_at": "2015-05-11T20:04:59Z",
"id": 49672
},
"questions": [
{
"item_bank_name": "Redpen Demo Questions",
"item_bank_id": 368,
"total_time_in_seconds": 5,
"unanswered": false,
"answer_score": 8,
"correct": false,
"angoff_score": null,
"question": {
"deleted_at": null,
"metadata": {
"vascular-area": {
"references": "",
"notes-on-reference": ""
},
"demo-item-metadata": {
"item-cognitive-area": "",
"estimated-item-difficulty": "",
"gender-representation": "",
"custom-id": "",
"image-id": "",
"p-value-april-2014-trial": "1",
"most-recent-p-value-trial": "1",
"p-value-march-2014-trial": "1",
"verified-by-admin": "0",
"p-value-june-2014-trial": "1",
"p-value-may-2014-trial": "1"
}
},
"created_at": "2013-12-02T20:38:11Z",
"canonical_id": 144631,
"updated_at": "2015-02-18T22:53:18Z",
"id": 215627
},
"total_time": 5,
"question_id": 215627,
"topic": "Redpen Demo Questions",
"question_canonical_id": 144631,
"capture": {
"essay": "Summer vacation was wonderful. I went no where but to a ball field, where I ate about 14 pounds of spitz. Truthfully, I think I kept the spitz family in business."
},
"id": 10095757
},
{
"item_bank_name": "Redpen Demo Questions",
"item_bank_id": 368,
"total_time_in_seconds": 10,
"unanswered": false,
"answer_score": 13,
"correct": false,
"angoff_score": null,
"question": {
"deleted_at": null,
"metadata": {
"vascular-area": {
"references": "",
"notes-on-reference": ""
},
"demo-item-metadata": {
"item-cognitive-area": "",
"estimated-item-difficulty": "",
"gender-representation": "",
"custom-id": "",
"image-id": "",
"p-value-april-2014-trial": "1",
"most-recent-p-value-trial": "1",
"p-value-march-2014-trial": "1",
"verified-by-admin": "0",
"p-value-june-2014-trial": "1",
"p-value-may-2014-trial": "1"
}
},
"created_at": "2013-12-02T20:39:37Z",
"canonical_id": 144632,
"updated_at": "2015-02-18T22:53:18Z",
"id": 215628
},
"total_time": 10,
"question_id": 215628,
"topic": "Redpen Demo Questions",
"question_canonical_id": 144632,
"capture": {
"essay": "I LOVE Thanksgiving because I love turkey and stuffing. Stuffing is the best part of the turkey dinner!"
},
"id": 10095758
}
],
"number_of_questions": 2,
"total_points": 30,
"pass_mark": 50,
"created_at": "2015-05-11T20:57:27Z",
"exam_grant": {
"expire_at": null,
"grantable_id": 1306,
"allow_sittings_start_at": null,
"type": "ExamGrant",
"exam_form_id": null,
"start_at": "2015-05-11T19:00:01Z",
"grantable_type": "Exam",
"exam_form_group": "active",
"uses": 1,
"deleted_at": null,
"user_id": 247441,
"allow_sittings_end_at": null,
"metadata": {},
"created_at": "2015-05-11T19:00:01Z",
"parent_grant_id": null,
"num_uses": 1,
"remaining_uses": 0,
"updated_at": "2015-05-11T19:00:01Z",
"id": 777250
},
"exam": {
"name": "The Holidays Exam",
"deleted_at": null,
"metadata": {},
"created_at": "2014-12-19T21:25:04Z",
"updated_at": "2014-12-19T21:25:25Z",
"id": 1306
},
"enrolment_key_establishment": null,
"reviewed_at": "2015-05-11T20:57:45Z",
"booking": {
"virtual_results": {
"completed_exam": "",
"exception_category": "",
"exception_subcategory": "",
"exception_item": "",
"exception_description": ""
},
"created_at": "2023-09-25T11:11:40-03:00",
"virtual_end_datetime": null,
"cancellation_note": null,
"metadata": {},
"no_show": false,
"no_show_reason": null,
"grant": {
"created_at": "2023-09-25T11:11:40-03:00",
"parent_grant_id": null,
"metadata": {},
"start_at": "2022-09-25T11:11:40-03:00",
"expire_at": null,
"exam_form_id": null,
"exam_form_group": "active",
"order_id": null,
"num_uses": null,
"updated_at": "2023-09-25T11:11:40-03:00",
"grantable_id": 1613,
"id": 1178,
"grantable_type": "Exam",
"type": "ExamGrant",
"uses": 1,
"deleted_at": null,
"allow_sittings_start_at": null,
"allow_sittings_end_at": null,
"remaining_uses": null,
"user_id": 1882
},
"updated_at": "2023-09-25T11:11:40-03:00",
"time_zone_name": null,
"id": 435,
"user": {
"email": "info+47@yardsticksoftware.com",
"username": "user_47",
"created_at": "2023-09-25T11:11:40-03:00",
"display_name": "Danielle Conn",
"metadata": {},
"active": true,
"email_verified": false,
"alternate_email_verified": false,
"partner_id": null,
"last_name": "Conn",
"full_name": "Danielle Conn",
"first_name": "Danielle",
"updated_at": "2023-09-25T11:11:40-03:00",
"id": 1881,
"preferred_language": "en",
"alternate_email": null,
"deleted_at": null,
"address": {
"updated_at": "2023-09-25T11:11:40-03:00",
"province": "AB",
"address1": "8616 51 Avenue NW",
"address2": "Suite 200",
"city": "Edmonton",
"province_name": "Alberta",
"postal_code": "T6E 6E6",
"country_name": "Canada",
"country": "CA"
},
"user_name": "user_47"
},
"virtual_start_datetime": null,
"type": null,
"sitting": {
"created_at": "2023-09-25T11:11:40-03:00",
"seats": 10,
"local_end_datetime": "2023-09-27T11:11:40-03:00",
"virtual_end_datetime": null,
"has_waiting_list": false,
"local_start_datetime": "2023-09-26T11:11:40-03:00",
"venue": {
"email": "yardstick@yardsticksoftware.com",
"created_at": "2023-09-25T11:11:40-03:00",
"deleted_at": null,
"metadata": {},
"active": true,
"notes": "Lorem ipsum",
"phone": "+1-780-409-5606",
"updated_at": "2023-09-25T11:11:40-03:00",
"id": 1297,
"lab_capacity": 1337,
"location": "Yardstick Edmonton",
"available_for_courses": true,
"available_for_exams": true,
"restricted": false,
"fax": "+1-780-409-5606",
"hours_of_operation": "9 to 5",
"web": "http://getyardstick.com/",
"address": {
"updated_at": "2023-09-25T11:11:40-03:00",
"province": "AB",
"address1": "8616 51 Avenue NW",
"address2": "Suite 200",
"city": "Edmonton",
"province_name": "Alberta",
"postal_code": "T6E 6E6",
"country_name": "Canada",
"country": "CA"
},
"details_for_user": "no details"
},
"metadata": {},
"begin_booking_at": null,
"venue_tbd": false,
"end_booking_at": null,
"updated_at": "2023-09-25T11:11:40-03:00",
"id": 1560,
"room": null,
"virtual_start_datetime": null,
"cancellation_deadline": null,
"deleted_at": null,
"private": false,
"require_purchase_before": null,
"session_type": "exam"
},
"confirmed": true,
"deleted_at": null,
"attendance_status": "present"
},
"passing_strategy": "total_score",
"proctored": true,
"language": null,
"exam_form": {
"name": "Form 1",
"deleted_at": null,
"retest_only": false,
"created_at": "2014-12-19T21:25:34Z",
"updated_at": "2014-12-19T21:25:34Z",
"id": 2647
},
"updated_at": "2015-06-09T17:27:03Z",
"time_limit_in_minutes": 0,
"exam_time_multiplier": 1,
"id": 369143
}
User Exam Attempt
Triggered immediately after a User
completes its User Exam
.
Example Payload
{
"booked": true,
"panel_action_events": [
{
"id": 1,
"grant_id": 777250,
"user_exam_id": 369143,
"panel_control_id": 2,
"panel_id": 3,
"panel_control_label": "Label",
"content": "Panel Content",
"created_at": "2022-05-11T20:57:27Z"
}
],
"establishments": [
{
"office_type": "single",
"created_at": "2023-10-12T20:14:44+03:00",
"approved_by": null,
"head_office_name": null,
"approved_at": null,
"is_head_office": false,
"name": "The Establishment Name",
"address": {
"country": "CA",
"updated_at": "2023-10-12T20:14:44+03:00",
"province_name": "Alberta",
"country_name": "Canada",
"city": "Edmonton",
"address1": "8616 51 Avenue NW",
"address2": "Suite 200",
"postal_code": "T6E 6E6",
"province": "AB"
},
"deleted_at": null,
"display_name": "The Establishment",
"fax": null,
"approved?": true,
"email": null,
"phone": null,
"vat_status": null,
"metadata": {},
"vat_num": null,
"status": "approved",
"primary_contact_display_name": null,
"admin_user_display_name": null,
"updated_at": "2023-10-12T20:14:44+03:00",
"get_price_level_name": null,
"id": 4
}
],
"proctor": {
"deleted_at": null,
"first_name": "Demo",
"created_at": "2013-10-02T15:44:55Z",
"email": "demoproctor@getyardstick.com",
"last_name": "Proctor",
"updated_at": "2017-10-13T20:07:30Z",
"id": 599
},
"establishments_selected_at": "2023-05-11T20:57:45Z",
"finished_at": "2023-05-11T20:57:45Z",
"parts": [
{
"break_length_in_minutes": null,
"finished_at": "2023-05-11T20:57:45Z",
"time_elapsed_in_seconds": 0,
"number_of_questions": 2,
"started_at": "2023-05-11T20:57:28Z",
"time_limit_in_minutes": 0
}
],
"user": {
"display_name": "Demo User",
"alternate_email": null,
"user_name": "demo.user",
"active": true,
"deleted_at": null,
"preferred_language": "en",
"first_name": "Demo",
"metadata": {},
"email_verified": false,
"address": null,
"created_at": "2013-09-02T02:36:20Z",
"username": "demo.user",
"alternate_email_verified": false,
"email": "demo.user@getyardstick.com",
"last_name": "User",
"full_name": "Demo User",
"updated_at": "2023-05-11T21:00:03Z",
"id": 247441
},
"sitting": {
"begin_booking_at": null,
"venue_tbd": false,
"session_type": "exam",
"require_purchase_before": null,
"local_end_datetime": "2023-05-12T14:30:00Z",
"deleted_at": null,
"seats": null,
"local_start_datetime": "2023-05-12T12:30:00Z",
"end_booking_at": null,
"cancellation_deadline": null,
"metadata": {},
"created_at": "2023-05-11T18:20:47Z",
"venue": {
"available_for_courses": true,
"phone": "",
"deleted_at": null,
"lab_capacity": null,
"restricted": false,
"notes": "",
"details_for_user": null,
"metadata": {},
"address": {
"province_name": "Alberta",
"country": "CA",
"postal_code": "T5T 5T5",
"city": "Edmonton",
"address1": "1234 Java Parkway",
"address2": null,
"province": "AB",
"country_name": "Canada",
"updated_at": "2023-07-28T19:08:37Z"
},
"location": "Demo Location 1",
"created_at": null,
"fax": "",
"web": "",
"available_for_exams": true,
"email": "",
"hours_of_operation": "",
"updated_at": "2023-07-28T19:08:37Z",
"id": 831
},
"has_waiting_list": false,
"private": false,
"room": "66",
"updated_at": "2023-05-11T20:04:59Z",
"id": 49672
},
"questions": [
{
"item_bank_name": "Redpen Demo Questions",
"item_bank_id": 368,
"total_time_in_seconds": 5,
"unanswered": false,
"answer_score": 8,
"correct": false,
"angoff_score": null,
"question": {
"deleted_at": null,
"metadata": {
"vascular-area": {
"references": "",
"notes-on-reference": ""
},
"demo-item-metadata": {
"item-cognitive-area": "",
"estimated-item-difficulty": "",
"gender-representation": "",
"custom-id": "",
"image-id": "",
"p-value-april-2014-trial": "1",
"most-recent-p-value-trial": "1",
"p-value-march-2014-trial": "1",
"verified-by-admin": "0",
"p-value-june-2014-trial": "1",
"p-value-may-2014-trial": "1"
}
},
"created_at": "2013-12-02T20:38:11Z",
"canonical_id": 144631,
"updated_at": "2023-02-18T22:53:18Z",
"id": 215627
},
"total_time": 5,
"question_id": 215627,
"topic": "Redpen Demo Questions",
"question_canonical_id": 144631,
"capture": {
"essay": "Summer vacation was wonderful. I went no where but to a ball field, where I ate about 14 pounds of spitz. Truthfully, I think I kept the spitz family in business."
},
"id": 10095757
},
{
"item_bank_name": "Redpen Demo Questions",
"item_bank_id": 368,
"total_time_in_seconds": 10,
"unanswered": false,
"answer_score": 13,
"correct": false,
"angoff_score": null,
"question": {
"deleted_at": null,
"metadata": {
"vascular-area": {
"references": "",
"notes-on-reference": ""
},
"demo-item-metadata": {
"item-cognitive-area": "",
"estimated-item-difficulty": "",
"gender-representation": "",
"custom-id": "",
"image-id": "",
"p-value-april-2014-trial": "1",
"most-recent-p-value-trial": "1",
"p-value-march-2014-trial": "1",
"verified-by-admin": "0",
"p-value-june-2014-trial": "1",
"p-value-may-2014-trial": "1"
}
},
"created_at": "2013-12-02T20:39:37Z",
"canonical_id": 144632,
"updated_at": "2023-02-18T22:53:18Z",
"id": 215628
},
"total_time": 10,
"question_id": 215628,
"topic": "Redpen Demo Questions",
"question_canonical_id": 144632,
"capture": {
"essay": "I LOVE Thanksgiving because I love turkey and stuffing. Stuffing is the best part of the turkey dinner!"
},
"id": 10095758
}
],
"number_of_questions": 2,
"total_points": 30,
"pass_mark": 50,
"created_at": "2023-05-11T20:57:27Z",
"exam_grant": {
"expire_at": null,
"grantable_id": 1306,
"allow_sittings_start_at": null,
"type": "ExamGrant",
"exam_form_id": null,
"start_at": "2023-05-11T19:00:01Z",
"grantable_type": "Exam",
"exam_form_group": "active",
"uses": 1,
"deleted_at": null,
"user_id": 247441,
"allow_sittings_end_at": null,
"metadata": {},
"created_at": "2023-05-11T19:00:01Z",
"parent_grant_id": null,
"num_uses": 1,
"remaining_uses": 0,
"updated_at": "2023-05-11T19:00:01Z",
"id": 777250
},
"exam": {
"name": "The Holidays Exam",
"deleted_at": null,
"metadata": {},
"created_at": "2014-12-19T21:25:04Z",
"updated_at": "2014-12-19T21:25:25Z",
"id": 1306
},
"enrolment_key_establishment": null,
"reviewed_at": "2023-05-11T20:57:45Z",
"booking": {
"virtual_results": {
"completed_exam": "",
"exception_category": "",
"exception_subcategory": "",
"exception_item": "",
"exception_description": ""
},
"created_at": "2023-09-25T11:11:40-03:00",
"virtual_end_datetime": null,
"cancellation_note": null,
"metadata": {},
"no_show": false,
"no_show_reason": null,
"grant": {
"created_at": "2023-09-25T11:11:40-03:00",
"parent_grant_id": null,
"metadata": {},
"start_at": "2022-09-25T11:11:40-03:00",
"expire_at": null,
"exam_form_id": null,
"exam_form_group": "active",
"order_id": null,
"num_uses": null,
"updated_at": "2023-09-25T11:11:40-03:00",
"grantable_id": 1613,
"id": 1178,
"grantable_type": "Exam",
"type": "ExamGrant",
"uses": 1,
"deleted_at": null,
"allow_sittings_start_at": null,
"allow_sittings_end_at": null,
"remaining_uses": null,
"user_id": 1882
},
"updated_at": "2023-09-25T11:11:40-03:00",
"time_zone_name": null,
"id": 435,
"user": {
"email": "info+47@yardsticksoftware.com",
"username": "user_47",
"created_at": "2023-09-25T11:11:40-03:00",
"display_name": "Danielle Conn",
"metadata": {},
"active": true,
"email_verified": false,
"alternate_email_verified": false,
"partner_id": null,
"last_name": "Conn",
"full_name": "Danielle Conn",
"first_name": "Danielle",
"updated_at": "2023-09-25T11:11:40-03:00",
"id": 1881,
"preferred_language": "en",
"alternate_email": null,
"deleted_at": null,
"address": {
"updated_at": "2023-09-25T11:11:40-03:00",
"province": "AB",
"address1": "8616 51 Avenue NW",
"address2": "Suite 200",
"city": "Edmonton",
"province_name": "Alberta",
"postal_code": "T6E 6E6",
"country_name": "Canada",
"country": "CA"
},
"user_name": "user_47"
},
"virtual_start_datetime": null,
"type": null,
"sitting": {
"created_at": "2023-09-25T11:11:40-03:00",
"seats": 10,
"local_end_datetime": "2023-09-27T11:11:40-03:00",
"virtual_end_datetime": null,
"has_waiting_list": false,
"local_start_datetime": "2023-09-26T11:11:40-03:00",
"venue": {
"email": "yardstick@yardsticksoftware.com",
"created_at": "2023-09-25T11:11:40-03:00",
"deleted_at": null,
"metadata": {},
"active": true,
"notes": "Lorem ipsum",
"phone": "+1-780-409-5606",
"updated_at": "2023-09-25T11:11:40-03:00",
"id": 1297,
"lab_capacity": 1337,
"location": "Yardstick Edmonton",
"available_for_courses": true,
"available_for_exams": true,
"restricted": false,
"fax": "+1-780-409-5606",
"hours_of_operation": "9 to 5",
"web": "http://getyardstick.com/",
"address": {
"updated_at": "2023-09-25T11:11:40-03:00",
"province": "AB",
"address1": "8616 51 Avenue NW",
"address2": "Suite 200",
"city": "Edmonton",
"province_name": "Alberta",
"postal_code": "T6E 6E6",
"country_name": "Canada",
"country": "CA"
},
"details_for_user": "no details"
},
"metadata": {},
"begin_booking_at": null,
"venue_tbd": false,
"end_booking_at": null,
"updated_at": "2023-09-25T11:11:40-03:00",
"id": 1560,
"room": null,
"virtual_start_datetime": null,
"cancellation_deadline": null,
"deleted_at": null,
"private": false,
"require_purchase_before": null,
"session_type": "exam"
},
"confirmed": true,
"deleted_at": null,
"attendance_status": "present"
},
"passing_strategy": "total_score",
"proctored": true,
"language": null,
"exam_form": {
"name": "Form 1",
"deleted_at": null,
"retest_only": false,
"created_at": "2014-12-19T21:25:34Z",
"updated_at": "2014-12-19T21:25:34Z",
"id": 2647
},
"updated_at": "2023-06-09T17:27:03Z",
"time_limit_in_minutes": 0,
"exam_time_multiplier": 1,
"id": 369143
}
Venue
Triggered when a Venue
has been created, updated, or destroyed (via the API or through the user interface).
Example Payload
{
"email": "",
"details_for_user": "",
"lab_capacity": 70,
"available_for_courses": false,
"available_for_exams": true,
"hours_of_operation": "",
"restricted": false,
"active": true,
"metadata": {},
"created_at": "2023-11-14T05:34:08Z",
"availability": "paper",
"notes": "",
"network": null,
"fax": "",
"address": {
"postal_code": "560087",
"province_name": null,
"created_at": "2023-11-14T05:34:08Z",
"account_id": 1,
"time_zone_name": "America/Cambridge_Bay",
"country": "IN",
"country_name": "India",
"latitude": null,
"longitude": null,
"updated_at": "2023-11-14T05:34:08Z",
"id": 2,
"city": "Bangalore",
"address1": "Building A",
"province": "",
"address2": ""
},
"updated_at": "2023-11-22T06:53:00Z",
"web": "",
"id": 2,
"location": "Brigade Tech Par",
"phone": "",
"deleted_at": null
}
Products
You may add and remove products from a user’s “Products” page using these endpoints. Use the API to show products to a user or hide them. By default, a user sees all products on a site. When you start adding visibility to specific products then we assume all other products are hidden.
For example, to show all products except for one to a user, you’ll need to add visibility to all products except for the one you want to hide. To show a user a handful of products then add visibility for those specific products. If something changes and you no longer want a user to see a product that you’ve chosen to add visibility for then make a new API request to remove visibility.
For each endpoint, the product ids which the user sees will be returned.
Add product visibility
Product visibility also depends on the Site’s Restrict visible products
setting
If that setting is enabled, it is essential to explicitly grant permission for a product first using the provided endpoint below. This action is necessary to enable users to view the product.
Example response
{
"products_granted_ids": [4950, 4958, 5393, 5406, 5415]
}
HTTP Request
POST https://api.ysasecure.com/v2/product_grants/
HTTP Post Params
Parameter | Description | Default |
---|---|---|
token string |
Your API token | |
user_id integer |
The user’s ID who should have visibilty of the product | |
product_id integer |
The product’s ID which should be added to the Products page |
Remove product visibility
Example response
{
"products_granted_ids": [4950, 4958, 5393, 5406, 5415]
}
HTTP Request
DELETE https://api.ysasecure.com/v2/product_grants/
HTTP Post Params
Parameter | Description | Default |
---|---|---|
token string |
Your API token | |
user_id integer |
The user’s ID who should not have visibilty of the product | |
product_id integer |
The product’s ID which should be removed from the Products page |