# Get Settings Source: https://developers.smarterservices.com/api-reference/app-install/get-settings https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/settings Returns the full settings object for the specified application install, including configuration options such as facial processing, proctor types, exam notes, and more.

A valid authentication token must be provided in the `token` header. # Course Offering Details Source: https://developers.smarterservices.com/api-reference/course-offering/course-offering-details https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/courseOfferings/{offeringSid} Returns the full course offering object for the specified offering SID.

Includes title, match strings, start/end dates, and associated metadata. # Create Course Offering Source: https://developers.smarterservices.com/api-reference/course-offering/create-course-offering https://api.dev.smarterproctoring.com/openapi.json post /v1/installs/{installSid}/courseOfferings Creates a new course offering (e.g., semester, term, or academic period) under the specified application install.

The `matchStrings` field is used to automatically match incoming courses from the LMS to this offering based on text patterns. # Delete Course Offering Source: https://developers.smarterservices.com/api-reference/course-offering/delete-course-offering https://api.dev.smarterproctoring.com/openapi.json delete /v1/installs/{installSid}/courseOfferings/{offeringSid} Permanently deletes the specified course offering.

Courses currently assigned to this offering may need to be reassigned. # List Course Offerings Source: https://developers.smarterservices.com/api-reference/course-offering/list-course-offerings https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/courseOfferings Returns a paginated list of course offerings (terms/semesters) for the specified application install.

Supports standard pagination via `offset` and `limit`. # Update Course Offering Source: https://developers.smarterservices.com/api-reference/course-offering/update-course-offering https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/courseOfferings/{offeringSid} Replaces the full course offering configuration with the provided payload.

All required fields (`title`, `matchStrings`) must be provided. # Search for users enrolled in a course by name Source: https://developers.smarterservices.com/api-reference/course/search-for-users-enrolled-in-a-course-by-name https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/courses/{courseSid}/users # Create Configuration Source: https://developers.smarterservices.com/api-reference/exam-configuration/create-configuration https://api.dev.smarterproctoring.com/openapi.json post /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid}/configurations Creates a new exam configuration (e.g., student-specific overrides for scheduling windows, permitted items, and proctoring settings).

The payload must include either `enrollmentSid` or `referenceExamConfigurationSid` (XOR constraint). # Delete Attachments Source: https://developers.smarterservices.com/api-reference/exam-configuration/delete-attachments https://api.dev.smarterproctoring.com/openapi.json delete /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid}/configurations/{examConfigurationSid}/attachments Removes specified attachment files or exam files from the exam configuration.

The payload specifies file names to delete from attachments or examFiles arrays. # Delete Configuration Source: https://developers.smarterservices.com/api-reference/exam-configuration/delete-configuration https://api.dev.smarterproctoring.com/openapi.json delete /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid}/configurations/{examConfigurationSid} Permanently deletes the specified exam configuration.

Returns a success message upon successful deletion. # Get Configuration Details Source: https://developers.smarterservices.com/api-reference/exam-configuration/get-configuration-details https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid}/configurations/{examConfigurationSid} Returns the full exam configuration including scheduling windows, permitted items, proctoring settings, and instructor-as-proctor entries. # List Configurations Source: https://developers.smarterservices.com/api-reference/exam-configuration/list-configurations https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid}/configurations Returns a paginated list of exam configurations for the specified exam.

Can be filtered by `enrollmentSid` to find configurations for a specific student.

Supports sorting and pagination via query parameters. # Update Configuration Source: https://developers.smarterservices.com/api-reference/exam-configuration/update-configuration https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid}/configurations/{examConfigurationSid} Replaces the full exam configuration with the provided payload including scheduling, permitted items, proctoring settings, and instructor-as-proctor entries.

The user role from the auth token is passed to the handler for role-based logic. # Upload Attachments Source: https://developers.smarterservices.com/api-reference/exam-configuration/upload-attachments https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid}/configurations/{examConfigurationSid}/attachments Uploads exam file attachments (e.g., exam papers, instruction sheets) via multipart/form-data.

Accepts up to 5 attachment files or 1 exam file per request. # Events By Student Source: https://developers.smarterservices.com/api-reference/exam-events/events-by-student https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/exams/{examSid}/eventsByStudent Returns event reports for the specified exam, grouped by student/enrollment. # List Exam Events Source: https://developers.smarterservices.com/api-reference/exam-events/list-exam-events https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/exams/{examSid}/events Returns a paginated list of event reports across all sessions for the specified exam.

Supports filtering and sorting via query parameters. # Get Annotation Details Source: https://developers.smarterservices.com/api-reference/exam-session-annotation/get-annotation-details https://api.dev.smarterproctoring.com/openapi.json get /v2/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/annotations/{annotationSid} Returns the full annotation object for the specified annotation SID. # List Annotations Source: https://developers.smarterservices.com/api-reference/exam-session-annotation/list-annotations https://api.dev.smarterproctoring.com/openapi.json get /v2/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/annotations Returns a paginated list of annotations for the specified exam session.

Supports filtering and sorting via query parameters. # Close Event Report Source: https://developers.smarterservices.com/api-reference/exam-session-event/close-event-report https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/events/{eventReportSid}/close Marks the specified event report as closed/resolved.

The `eventReportSid` is validated through the hierarchy: eventReport → session → exam → appInstall. # Create Event Report Source: https://developers.smarterservices.com/api-reference/exam-session-event/create-event-report https://api.dev.smarterproctoring.com/openapi.json post /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/events Records a session event (e.g., browser focus lost, microphone detected, suspicious activity) on the specified exam session. # Delete Event Report Source: https://developers.smarterservices.com/api-reference/exam-session-event/delete-event-report https://api.dev.smarterproctoring.com/openapi.json delete /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/events/{eventReportSid} Deletes the specified event report.

The `eventReportSid` is validated through the hierarchy: eventReport → session → exam → appInstall. # Get Event Report Source: https://developers.smarterservices.com/api-reference/exam-session-event/get-event-report https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/events/{eventReportSid} Returns the full event report object for the specified event report SID.

The `eventReportSid` is validated through the hierarchy: eventReport → session → exam → appInstall. # List Event Reports Source: https://developers.smarterservices.com/api-reference/exam-session-event/list-event-reports https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/events Returns a paginated list of session event reports for the specified exam session.

Supports filtering and sorting via query parameters. # Update Event Report Source: https://developers.smarterservices.com/api-reference/exam-session-event/update-event-report https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/events/{eventReportSid} Updates the specified event report with the provided payload fields.

The `eventReportSid` is validated through the hierarchy: eventReport → session → exam → appInstall. # Cancel Exam Session Source: https://developers.smarterservices.com/api-reference/exam-session/cancel-exam-session https://api.dev.smarterproctoring.com/openapi.json delete /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid} Cancels the specified exam session. The auth token is passed for auditing.

An optional payload may include cancellation reason details. # Close Exam Session Source: https://developers.smarterservices.com/api-reference/exam-session/close-exam-session https://api.dev.smarterproctoring.com/openapi.json post /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/close Closes the exam session, finalizing the session state and triggering post-session workflows. # Exam Session Details Source: https://developers.smarterservices.com/api-reference/exam-session/exam-session-details https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid} Returns the full exam session object including scheduling, proctoring, and status details. # List enrollment exam sessions Source: https://developers.smarterservices.com/api-reference/exam-session/list-enrollment-exam-sessions https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/enrollments/{enrollmentSid}/exams/{examSid}/sessions Returns a paginated list of exam sessions for the given enrollment and exam combination. # Reschedule Exam Session Source: https://developers.smarterservices.com/api-reference/exam-session/reschedule-exam-session https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid} Changes the scheduled date/time for an existing exam session.

The auth token is passed for proctor reassignment and auditing. # Schedule Exam Session Source: https://developers.smarterservices.com/api-reference/exam-session/schedule-exam-session https://api.dev.smarterproctoring.com/openapi.json post /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid} Creates a scheduled exam session under the specified exam. # Create Exam Source: https://developers.smarterservices.com/api-reference/exam/create-exam https://api.dev.smarterproctoring.com/openapi.json post /v1/installs/{installSid}/courses/{courseSid}/exams Creates a new exam configuration under the specified course.

The payload includes exam metadata (title, type, URL), proctoring configuration, permitted items, scheduling windows, and instructor-as-proctor settings. # Delete Exam Source: https://developers.smarterservices.com/api-reference/exam/delete-exam https://api.dev.smarterproctoring.com/openapi.json delete /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid} Performs a soft delete on the specified exam, marking it as deleted without permanently removing data.

The exam will no longer appear in active listings but its data is retained. # Exam Details Source: https://developers.smarterservices.com/api-reference/exam/exam-details https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid} Returns the full exam object including configuration, permitted items, proctoring settings, and scheduling windows.

Also evaluates the LaunchDarkly virtual test center version feature flag for the requesting user. # Get exam assignments Source: https://developers.smarterservices.com/api-reference/exam/get-exam-assignments https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/exams/{examSid}/assignments # List Exams Source: https://developers.smarterservices.com/api-reference/exam/list-exams https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/courses/{courseSid}/exams Returns a paginated list of exams belonging to the specified course.

Supports filtering with `includeStatusSummary` to include enrollment status counts per exam.

Supports sorting by `title`, `examOpenDate`, or `scheduleOpenDate`. # Update Exam Source: https://developers.smarterservices.com/api-reference/exam/update-exam https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/courses/{courseSid}/exams/{examSid} Replaces the full exam configuration with the provided payload.

Includes exam metadata, scheduling windows, permitted items, proctoring settings, and instructor-as-proctor configurations.

The user role from the auth token is passed to the handler for role-based logic. # Update exam assignments Source: https://developers.smarterservices.com/api-reference/exam/update-exam-assignments https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/exams/{examSid}/assignments # Get the onboarding URL for an exam session Source: https://developers.smarterservices.com/api-reference/onboarding/get-the-onboarding-url-for-an-exam-session https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/exams/{examSid}/sessions/{sessionSid}/onboard Returns the onboarding URL where the student completes pre-exam steps (e.g., system check, ID verification). # Bulk Provision Data Source: https://developers.smarterservices.com/api-reference/provision/bulk-provision-data https://api.dev.smarterproctoring.com/openapi.json post /v2/installs/{installSid}/provision Provisions multiple types of data (e.g., courses, exams, enrollments) in a single bulk operation for the specified install. # Appointment Volume Source: https://developers.smarterservices.com/api-reference/reports/appointment-volume https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/appointmentVolume Returns an appointment volume (peak exam) report for the specified install. # Calendar Capacity Source: https://developers.smarterservices.com/api-reference/reports/calendar-capacity https://api.dev.smarterproctoring.com/openapi.json get /v1/proctors/{proctorSid}/reports/calendarCapacity Returns appointment availability and capacity data for the specified calendar. # Churn Report Source: https://developers.smarterservices.com/api-reference/reports/churn-report https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/churn Returns a churn report for the specified install. # Exam Overview Source: https://developers.smarterservices.com/api-reference/reports/exam-overview https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/examOverview Returns an exam overview report for the specified install. # Exam Type Stats Source: https://developers.smarterservices.com/api-reference/reports/exam-type-stats https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/aggregatedStats Returns aggregated statistics for exam types for the next 10 days. # Exam Volume Source: https://developers.smarterservices.com/api-reference/reports/exam-volume https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/examVolume Returns an exam volume report for the specified install. # Exams By Week Source: https://developers.smarterservices.com/api-reference/reports/exams-by-week https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/examsByWeek Returns exams grouped by week based on the given filter parameters. # List Appointments Source: https://developers.smarterservices.com/api-reference/reports/list-appointments https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/appointments Returns all appointments based on the given filter parameters. # Modality Distribution Source: https://developers.smarterservices.com/api-reference/reports/modality-distribution https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/modalityDistribution Returns a report on modality distribution for the specified install. # Proctor Exam Details Source: https://developers.smarterservices.com/api-reference/reports/proctor-exam-details https://api.dev.smarterproctoring.com/openapi.json get /v1/proctors/{proctorSid}/reports/examList Returns detailed exam information for the specified proctor account. # Proctor Volume Source: https://developers.smarterservices.com/api-reference/reports/proctor-volume https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/proctorAccountVolume Returns a volume report for proctor accounts associated with the specified install. # Service Distribution Source: https://developers.smarterservices.com/api-reference/reports/service-distribution https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/serviceDistribution Returns a service distribution report for the specified install. # Session Accommodations Source: https://developers.smarterservices.com/api-reference/reports/session-accommodations https://api.dev.smarterproctoring.com/openapi.json get /v1/proctors/{proctorSid}/session-accommodations Returns session accommodation data for the specified proctor account. # Session Events Source: https://developers.smarterservices.com/api-reference/reports/session-events https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/examSessionEvents Returns exam session event reports for the specified install. # Session Requests Source: https://developers.smarterservices.com/api-reference/reports/session-requests https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/sessionRequests Returns all message threads that have active session requests for the specified install. # Unscheduled Learners Source: https://developers.smarterservices.com/api-reference/reports/unscheduled-learners https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/unscheduledLearners Returns a paginated list of students who have not yet scheduled their exam sessions. # Written Exam Audit Source: https://developers.smarterservices.com/api-reference/reports/written-exam-audit https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/reports/audit Returns an audit report for written exams within the specified install. # List Time Zones Source: https://developers.smarterservices.com/api-reference/time-zones/list-time-zones https://api.dev.smarterproctoring.com/openapi.json get /v1/timeZones Returns a paginated list of supported time zones.

Supports sorting by `createdDate` and pagination via `offset` and `limit`. # Create User Source: https://developers.smarterservices.com/api-reference/user/create-user https://api.dev.smarterproctoring.com/openapi.json post /v1/installs/{installSid}/users Creates a new user for the specified install. # Delete User Source: https://developers.smarterservices.com/api-reference/user/delete-user https://api.dev.smarterproctoring.com/openapi.json delete /v1/installs/{installSid}/users/{userSid} Deletes the specified user from the install. # Get User Profile Source: https://developers.smarterservices.com/api-reference/user/get-user-profile https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/users/{userSid}/profile Returns the user profile for the specified user within the install. # List Users Source: https://developers.smarterservices.com/api-reference/user/list-users https://api.dev.smarterproctoring.com/openapi.json get /v1/installs/{installSid}/users Returns a paginated list of users for the specified install. # Update Admin User Source: https://developers.smarterservices.com/api-reference/user/update-admin-user https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/users/{userSid} Updates admin-specific fields for the specified user within the install. # Update User Profile Source: https://developers.smarterservices.com/api-reference/user/update-user-profile https://api.dev.smarterproctoring.com/openapi.json put /v1/installs/{installSid}/users/{userSid}/profile Updates the user profile for the specified user within the install. # Authentication Source: https://developers.smarterservices.com/assessment/api/authentication ## API Security As outlined in the [introduction](../../assessment), all requests must be submitted using SSL. ## HTTP Authentication The SmarterMeasure API only supports basic HTTP authentication. To obtain credentials you can contact your SmarterMeasure account manager. Once these credentials are obtained you will use your "Access Key" as the username and the "Secret" as the password for your requests. # Error Messages & Codes Source: https://developers.smarterservices.com/assessment/api/errors # Error Messages & Codes | Error Code | HTTP Status | Message | | ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | AUTHENTICATIONFAILED | 403 (Forbidden) | The server failed to authenticate the request. Verify that the value of Authorization header is formed correctly and includes the signature. | | INTERNALERROR | 500 (Internal Server Error) | The server encountered an internal error. Please retry the request. | | INVALIDAUTHENTICATIONINFO | 400 (Bad Request) | The authentication information was not provided in the correct format. Verify the value of Authorization header. | | INVALIDINPUT | 400 (Bad Request) | One or more of the request inputs is not valid. | | INVALIDPROTOCOL | 400 (Bad Request) | The request was not made under a secure connection, all requests must be made under SSL. | | INVALIDURI | 400 (Bad Request) | The requested URI does not represent any resource on the server. | | RESOURCENOTFOUND | 404 (Not Found) | The specified resource does not exist. | | UNSUPPORTEDHTTPVERB | 405 (Method Not Allowed) | The resource doesn't support the specified HTTP verb. | # Introduction Source: https://developers.smarterservices.com/assessment/api/introduction Documentation for the assessment (SmarterMeasure) API The assessment (SmarterMeasure) REST API allows you to query information about assessments, users, and results. Since the API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can pretty much use any HTTP client in any programming language to interact with the API. Base URL All URLs referenced in this document have the following base: [https://api.smartermeasure.com/v3](https://api.smartermeasure.com/v3) HTTP and HTTPS The assessment (SmarterMeasure) REST API is served over HTTPS. To ensure data privacy encrypted HTTP is not supported. ## Quick Start Book a call with your success manager to discuss your needs and get started. Once you have discussed your needs with your success manager, they will provide you with API credentials. Once you have obtained your API credentials, you can make your first API call. Once you have made your first API call, you can explore the API and further design your integration. # Search Results Source: https://developers.smarterservices.com/assessment/api/results/search GET /results Search for results # Search Results (expanded) Source: https://developers.smarterservices.com/assessment/api/results/search-expanded GET /results/new Search for results with expanded data including new sections. # User Report Source: https://developers.smarterservices.com/assessment/api/results/user-report GET /users/{userid}/report Return report for a specific user # User Results Source: https://developers.smarterservices.com/assessment/api/results/user-results GET /users/{userid}/results Return results for a specific user # Create User Source: https://developers.smarterservices.com/assessment/api/users/create-user POST /users Create a new user/assessment # Get User Source: https://developers.smarterservices.com/assessment/api/users/get-user GET /users/{userid} Get a specific user # List Users Source: https://developers.smarterservices.com/assessment/api/users/list-users GET /users Get a list of users that match the specified criteria # Report Link Source: https://developers.smarterservices.com/assessment/api/users/report-link GET /users/{userid}/reportlink Provides a URL that can be used to view the report for the user. # Sign On Source: https://developers.smarterservices.com/assessment/api/users/signon POST /users/{userid}/signon Provides a URL that can be used to sign the user into the system. # Update User Source: https://developers.smarterservices.com/assessment/api/users/update-user PUT /users/{userid} Update a specific user # Events & Payloads Source: https://developers.smarterservices.com/assessment/webhooks/events-and-payloads Webhook events and payload formats # Events & Payloads ## Supported Events Our webhooks implementation allows for a basic set of assessment-based events that you can capture. We are open to adding more event types as they are required by our customers. If you have a need for a new event type, please contact [developers@smartermeasure.com](mailto:developers@smartermeasure.com) with your request. | Event | Fired when... | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assessment.created` | An assessment is created. | | `assessment.section-start` | A section is started. This request will include the section that is being started. **Note:** This can be fired multiple times if the user leaves and returns to the assessment without submitting the answers. | | `assessment.section-complete` | A section is completed. This request will include the scoring details for the section completed. | | `assessment.completed` | The assessment is 100% complete. | | `assessment.stopped` | The user has chosen to stop taking the assessment for the current period. | ## Event Formats When event data is sent back in the HTTP POST, it can be sent as either JSON or XML. This setting can be configured for each event type. The sample event data below includes both formats. ## Event Data Structure When an event occurs that you have turned on, we will send an HTTP POST request to the URL specified for the given event. If we receive an HTTP Response code of 200, we deem the request as being successful; anything else will be considered a failure. If the request is considered a failure, the URL is unavailable, or the request takes too long to respond (more than 10 seconds), we'll cancel the request and try again later. Retries will be sent for the next 48 hours at 15 minute intervals — effectively 192 attempts. It cannot be assumed that webhook callbacks are sent in the proper order. Your application should check the request timestamp and act appropriately. Each event will contain a `callback_id` to help you track the actual ID of the callback in our system and an `event` field that will allow you to track the type of event that was fired. ### assessment.created ```json theme={null} { "callback_id": "6cec1a2a710b431f9c8a51cdc55854c2", "callback_event": "assessment.created", "user": { "user_id": "8152142", "internal_id": "", "first_name": "Demo", "last_name": "User", "email": "demouser@smartermeasure.com", "assessment_pin": "j8rScGZR", "date_created": "2013-06-12T03:30:00Z", "metadata": [] }, "rest_api_uris": { "version": "3", "user": "/users/8152142", "user_results": "/users/8152142/results" } } ``` ```xml theme={null} 8152143 Demo User demouser@smartermeasure.com gBsKbT54 2013-06-12T03:54:38Z /users/8152143 /users/8152143/results ``` ### assessment.section-start ```json theme={null} { "callback_event": "assessment.section-start", "callback_id": "e5aee4250b8a431190d9d415c3604a46", "rest_api_uris": { "report_link": "/users/8152142/reportlink", "user": "/users/8152142", "version": "3" }, "section": { "code": "LifeFactors" }, "user": { "completion_percentage": "14", "date_created": "2013-06-12T03:30:00Z", "date_updated": "2013-06-12T03:32:59Z", "email": "demouser@smartermeasure.com", "first_name": "Demo", "internal_id": "", "last_name": "User", "metadata": [], "user_id": "8152142" } } ``` ```xml theme={null} 8152143 Demo User demouser@smartermeasure.com 14 2013-06-12T03:54:38Z 2013-06-12T03:56:10Z
LifeFactors
/users/8152143 /users/8152143/reportlink
``` ### assessment.section-complete ```json theme={null} { "callback_event": "assessment.section-complete", "callback_id": "e5aee4250b8a431190d9d415c3604a46", "rest_api_uris": { "report_link": "/users/8152142/reportlink", "user": "/users/8152142", "version": "3" }, "section": { "code": "LifeFactors", "completed": "true", "date_scored": "2013-06-12T03:33:00Z", "results": { "readiness": "fail", "scores": [ { "type": "possible", "units": "points", "value": "100" }, { "type": "earned", "units": "points", "value": "63" }, { "type": "calculated-percentage", "units": "percentage", "value": "63" } ], "subscales": [ { "code": "place", "scores": [ { "type": "possible", "units": "points", "value": "20" }, { "type": "earned", "units": "points", "value": "13" }, { "type": "calculated-percentage", "units": "percentage", "value": "65" } ]}, { "code": "reason", "scores": [ { "type": "possible", "units": "points", "value": "20" }, { "type": "earned", "units": "points", "value": "11" }, { "type": "calculated-percentage", "units": "percentage", "value": "55" } ]}, { "code": "resources", "scores": [ { "type": "possible", "units": "points", "value": "20" }, { "type": "earned", "units": "points", "value": "13" }, { "type": "calculated-percentage", "units": "percentage", "value": "65" } ]}, { "code": "skills", "scores": [ { "type": "possible", "units": "points", "value": "20" }, { "type": "earned", "units": "points", "value": "9" }, { "type": "calculated-percentage", "units": "percentage", "value": "45" } ]}, { "code": "time", "scores": [ { "type": "possible", "units": "points", "value": "20" }, { "type": "earned", "units": "points", "value": "17" }, { "type": "calculated-percentage", "units": "percentage", "value": "85" } ]} ] } }, "user": { "completion_percentage": "14", "date_created": "2013-06-12T03:30:00Z", "date_updated": "2013-06-12T03:32:59Z", "email": "demouser@smartermeasure.com", "first_name": "Demo", "internal_id": "", "last_name": "User", "metadata": [], "user_id": "8152142" } } ``` ```xml theme={null} 8152143 Demo User demouser@smartermeasure.com 14 2013-06-12T03:54:38Z 2013-06-12T03:56:10Z
LifeFactors true 2013-06-12T03:56:00Z fail 100 points possible 67 points earned 67 percentage calculated-percentage 20 points possible 17 points earned 85 percentage calculated-percentage 20 points possible 15 points earned 75 percentage calculated-percentage 20 points possible 13 points earned 65 percentage calculated-percentage 20 points possible 11 points earned 55 percentage calculated-percentage 20 points possible 11 points earned 55 percentage calculated-percentage
/users/8152143 /users/8152143/reportlink
``` ### assessment.completed ```json theme={null} { "callback_event": "assessment.completed", "callback_id": "c79f74c88f134347b237fb3f0a0b11cb", "rest_api_uris": { "user": "/users/8152142", "user_results": "/users/8152142/results", "version": "3" }, "user": { "assessment_pin": "j8rScGZR", "date_created": "2013-06-12T03:30:00Z", "date_updated": "2013-06-12T03:32:59Z", "email": "demouser@smartermeasure.com", "first_name": "Demo", "internal_id": "", "last_name": "User", "metadata": [], "user_id": "8152142" } } ``` ```xml theme={null} 8152143 Demo User demouser@smartermeasure.com gBsKbT54 2013-06-12T03:54:38Z 2013-06-12T03:56:10Z /users/8152143 /users/8152143/results ``` ### assessment.stopped ```json theme={null} { "callback_event": "assessment.stopped", "callback_id": "c79f74c88f134347b237fb3f0a0b11cb", "rest_api_uris": { "user": "/users/8152142", "user_results": "/users/8152142/results", "version": "3" }, "user": { "assessment_pin": "j8rScGZR", "completion_percentage": "14", "date_created": "2013-06-12T03:30:00Z", "date_updated": "2013-06-12T03:32:59Z", "email": "demouser@smartermeasure.com", "first_name": "Demo", "internal_id": "", "last_name": "User", "metadata": [], "user_id": "8152142" } } ``` ```xml theme={null} 8152143 Demo User demouser@smartermeasure.com gBsKbT54 2013-06-12T03:54:38Z 2013-06-12T03:56:10Z 14 /users/8152143 /users/8152143/results ``` ## Section Code Mappings Each section-specific payload will include a `code` key to let the target application know which section was started or completed. | Section Code | Assessment Section | | ---------------------- | ------------------------- | | `PersonalAttributes` | Individual Attributes | | `LearnStyles` | Learning Styles | | `LifeFactors` | Life Factors | | `Math` | Math | | `PersonalInfo` | Personal Information | | `personalRating` | Personal Rating | | `Reading` | Reading Rate & Recall | | `student-svc-interest` | Student Services Interest | | `TechComp` | Technical Competency | | `TechKnowledge` | Technical Knowledge | | `Typing` | Typing Speed & Accuracy | | `writing` | Writing | # Getting Started Source: https://developers.smarterservices.com/assessment/webhooks/getting-started Introduction to SmarterMeasure webhooks # Getting Started with Webhooks Webhooks allow you to collect information about events as they happen in near real-time. Provide a URL, select when and where you want the URL to receive data about events, and we'll send it to you as the events take place. For more information about webhooks in general, visit [https://en.wikipedia.org/wiki/Webhook](https://en.wikipedia.org/wiki/Webhook). ## How Webhooks Work 1. **Registration**: You register a URL endpoint on your server to receive webhook notifications 2. **Event Triggers**: When specific events occur in SmarterMeasure (e.g., assessment completion), our system sends an HTTP POST request to your registered endpoint 3. **Processing**: Your application receives and processes the webhook payload, taking appropriate actions based on the event type ## Configuring Webhooks Currently, webhooks must be configured by contacting our team at [developers@smartermeasure.com](mailto:developers@smartermeasure.com). Please provide: 1. The URL endpoint where you want to receive webhook notifications 2. The specific events you want to subscribe to 3. The format you prefer (JSON or XML) ## Securing Webhooks We support both HTTP and HTTPS URLs, so you can have added security by using SSL-enabled URLs (and we suggest this). Keep in mind your endpoint will remain wide open to the Internet, and you might not want to allow others to submit random data to your systems. ### Verification Key As an added layer of security, we provide a verification key in each request you can use to validate the request. The verification key is assigned when your webhooks are provisioned and applies to all webhook events. #### Header Method The verification key is always sent in the header of the request as the parameter `X-SmarterMeasure-Verification-Key`. ``` X-SmarterMeasure-Verification-Key = 1b6ea66ad36c11e291fef23c91aec05e ``` #### URL Method Some integrations do not support access to the header data. In this case, you can include the key in the URL. To do this, append `VerificationKey={VerificationKey}` to your endpoint URL. The SmarterMeasure system will replace the `{VerificationKey}` value with your actual verification key at run-time. ``` // If your endpoint URL when configuring your webhook looks like this: https://mydomain.com/smartermeasure-webhooks?verificationkey={verificationkey} // The URL that is requested will look like this: https://mydomain.com/smartermeasure-webhooks?verificationkey=1b6ea66ad36c11e291fef23c91aec05e ``` ## Next Steps * Learn about [Events & Payloads](/assessment/webhooks/events-and-payloads) to understand what data you'll receive * Review [Testing & Troubleshooting](/assessment/webhooks/testing-and-troubleshooting) for best practices # Testing & Troubleshooting Source: https://developers.smarterservices.com/assessment/webhooks/testing-and-troubleshooting Testing webhooks and best practices # Testing & Troubleshooting ## Testing Webhooks Before implementing webhook handlers in production, you can test webhook delivery using tools like: * [RequestBin](https://requestbin.com/) - Creates temporary endpoints to inspect webhook payloads * [Webhook.site](https://webhook.site/) - Provides instant webhook URLs for testing * [Ngrok](https://ngrok.com/) - Exposes your local development server to the internet for webhook testing These tools let you see the exact payloads that will be sent, so you can verify your parsing logic before going live. ## Retry Policy When an event occurs that you have turned on, we will send an HTTP POST request to the URL specified for the given event. If we receive an HTTP Response code of 200, we deem the request as being successful; anything else will be considered a failure. If the request is considered a failure, the URL is unavailable, or the request takes too long to respond (more than 10 seconds), we'll cancel the request and try again later: * Retries occur at 15-minute intervals * Retries continue for up to 48 hours (192 attempts total) * After 48 hours, failed webhooks are discarded It cannot be assumed that webhook callbacks are sent in the proper order. Your application should check the request timestamp and act appropriately. ## Best Practices 1. **Respond quickly**: Return a 2xx status code as soon as possible, even before processing the webhook. This prevents timeouts and unnecessary retries. 2. **Process asynchronously**: Handle time-consuming operations outside the request-response cycle. Queue the webhook for background processing and respond immediately. 3. **Verify the verification key**: Always validate the `X-SmarterMeasure-Verification-Key` (or URL parameter) to ensure the request is authentic. 4. **Check timestamps**: Don't assume webhooks arrive in order; use the timestamp fields in the payload to process events correctly. 5. **Handle retries**: Be prepared for duplicate deliveries due to the retry mechanism. Use the `callback_id` to track which webhooks you've already processed. 6. **Log everything**: Keep detailed logs of webhook receipts, processing, and responses to help debug issues. ## Common Issues ### Not receiving webhooks * Verify your URL is publicly accessible and not behind a firewall * Check that your endpoint returns a 200 status code * Ensure your server responds within 10 seconds ### Duplicate webhooks * This is expected due to the retry mechanism * Use the `callback_id` to deduplicate on your end ### Out of order webhooks * Webhooks may not arrive in chronological order * Always use timestamps from the payload, not the request time For assistance with webhook implementation or troubleshooting, please contact our team at [developers@smartermeasure.com](mailto:developers@smartermeasure.com). # SmarterServices Platform Source: https://developers.smarterservices.com/index Integration documentation for the SmarterServices Platform Welcome to the integration documentation for the SmarterServices Platform. This documentation provides comprehensive information about integrating with and using our platform. Documentation for SmarterMeasure and other SmarterServices assessment solutions. Documentation for SmarterProctoring and other integrated proctoring solutions. ## Need Help? If you need assistance, please [contact our support team](https://smarterservices.com/support) or your customer success representative. # Actions Source: https://developers.smarterservices.com/platform/blockkit/actions A container block that displays a horizontal row of interactive buttons ## Basic Example ```json theme={null} { "type": "actions", "elements": [ { "type": "button", "text": "Action 1", "action_id": "action_1" } ] } ``` ## Complete Example ```json Example Code expandable theme={null} [ { "type": "actions", "action_url": "https://api.example.com/handle-action", "block_id": "ticket_actions", "elements": [ { "type": "button", "text": "Approve", "action_id": "approve", "value": "approved", "style": "primary" }, { "type": "button", "text": "Request Changes", "action_id": "request_changes", "value": "changes_requested", "style": "default" }, { "type": "button", "text": "Reject", "action_id": "reject", "value": "rejected", "style": "danger", "confirm": { "title": "Confirm Rejection", "text": "Are you sure you want to reject this request?", "confirm_text": "Reject", "deny_text": "Cancel" } } ] } ] ``` ## Properties Identifies this as an actions block Must be `actions` Array of [Button](/platform/blockkit/button) blocks displayed horizontally in a row The default endpoint URL for all buttons in this actions block. Individual buttons can override this with their own `action_url`. A unique identifier for this actions block. Included in action payloads for server-side identification. ## How It Works 1. The `actions` block renders its child buttons in a horizontal row 2. When a user clicks a button, the action payload is POSTed to the button's `action_url` (or the parent actions block's `action_url`) 3. The server processes the action and responds with new BlockKit content 4. The response can replace, update, or append blocks in the UI ## Nesting Rules The `actions` block can be placed inside: * Root level * [Section](/platform/blockkit/section) * [Wizard Step](/platform/blockkit/wizardstep) * [Column Layout](/platform/blockkit/columnlayout) columns The `actions` block can only contain: * [Button](/platform/blockkit/button) elements ## Usage Notes * Use the `actions` block to group related action buttons together * Buttons inside an `actions` block are displayed side-by-side horizontally * Set the `action_url` on the actions block to apply a default endpoint to all child buttons * Each button can override the parent `action_url` if it needs to POST to a different endpoint # Alert Source: https://developers.smarterservices.com/platform/blockkit/alert A block that displays an alert message with different severity levels ## Basic Example ```json theme={null} { "type": "alert", "severity": "info", "text": "Sample alertblock content" } ``` ## Live Example