Overview

This API lets developers integrate with the SWEAP system to allow for administration outside of the user interface. The API has methods for retrieving user entitlements, assigning remote assessments, retrieving completed assessment reports.

About the API

This API is automatically available to all paying SWEAP users opting for enhanced integration assessments, and the integration details are available via the user interface.

Documented properties will not be removed within a stable version of the API. Once a given API endpoint is documented to return a given property, a property with that name will always appear (although certain properties may only appear under certain conditions, like if the customer is using a specific variation). When SWEAP deprecates a property, the API continues to accept that property in requests, although it no longer has any effect.

Properties that enumerate choices may gain new values at any time, e.g. the formtype value could return new type of instrument that did not previously exist. SWEAP may cease to return legacy values for properties as well. SWEAP will update our API documentation with changes to property values in a timely fashion, adding new property values or indicating changes to existing property values.

New, undocumented properties may also appear at any time. For instance, SWEAP may make available a beta feature involving extra information returned by an API endpoint. Until the property is documented here its format may change or it may even be entirely removed from our API.

Conventions

The end user can retrieve a single API key for all entitlements for their program or receive individual API keys for each individual assessment type. This allows for flexibility in implementation.

Each program will have a unique four digit alphanumeric code identifying that program and this is generally a prefix on all actions within the system.

Each program will have at least one program director / field coordinator / administrative assistant who purchases and renders reports for the program. This document shall refer to this as administrators.

All times are represented in GMT / UTC.

The standard workflow for an administrator is as follows

  • The assessments are purchased from the store
  • Each order is then administrated in various ways where they may opt to assign each to a student. field instructor, or graduate. This document will refer to these people as respondents.
  • The administrators will assemble completed assessments into a report

The workflow for a standard instrument administration is as follows, and this represents the status.

  • START – an unused instrument, the beginning of the process.
  • IN PROGRESS – an instrument underway, the respondent has not pressed “Save”
  • SAVED – the respondent has pressed “Save” but has not opted to mark this as final. An administrator may deem this as a reportable status.
  • FINISHED – the respondent has pressed the option to mark instrument as final.
  • CANCELLED – the instrument was marked for exchange and is unusable.

API Details

Base URL

All API methods use the following url: https://sweapinstruments.org/api

Methods always use HTTPS. Unsecured HTTP is not supported. This integration communications via TCP port 443. Also, we do not recommend locking down your firewall to whitelist to individual IP addresses as the address may change at any time.

Request Format

All requests must have “Authorization” header.

If the request method is GET or DELETE, URL-encode parameters and send them in the URL query string like this: /api/assign?realname=First%20Last&assessment=ABCD12345. They still go on a separate line when creating the string to sign for an Authorization header.

Send parameters for POST requests in the body as URL-encoded key-value pairs (the same request format used by browsers to submit form data). The header “Content-Type: application/x-www-form-urlencoded” must also be present.

When URL-encoding, all bytes except ASCII letters, digits, underscore (“_”), period (“.”), tilde (“~”), and hyphen (“-“) are replaced by a percent sign (“%”) followed by two hexadecimal digits containing the value of the byte. For example, a space is replaced with “%20” and an at-sign (“@”) becomes “%40”. Use only upper-case A through F for hexadecimal digits.

Response Format

Responses are formatted as a JSON object with a top-level stat key.

Successful responses will have a stat value of “OK” and a response key. The response will either be a single object or a sequence of other JSON types, depending on which endpoint is called.

{
  "stat": "OK",
  "response": {
    "key": "value"
  }
}

Values are returned as strings unless otherwise documented.

Unsuccessful responses will have a stat value of “FAIL”, an integer code, and a message key that further describes the failure. A message_detail key may be present if additional information is available (like the specific parameter that caused the error).

{
  "stat": "FAIL",
  "code": 40002,
  "message": "Invalid request parameters",
  "message_detail": "username"
}

The HTTP response code will be the first three digits of the more specific code found inside the JSON object. Each endpoint’s documentation lists HTTP response codes it can return. Additionally, all API endpoints that require a signed request can return the following HTTP response codes:

Response Meaning
200 The request completed successfully.
401 The “Authorization”, “Date”, and/or “Content-Type” headers were missing or invalid.
403 This integration is not authorized for this endpoint
405 The request’s HTTP verb is not valid for this endpoint (for example, POST when only GET is supported).
429 The account has made too many requests of this type recently. Try again later.

Authentication

The API uses HTTP Basic Authentication to authenticate requests. Use your SWEAP integration key as the HTTP Username, with the password being the integration secret.

To view available integration keys and secrets, refer to the table below.

Please Login to View Credentials

 

Available Instruments

Retrieve All Available Instruments

This returns the available administration status and URLs for the login supplied. This represents a drill down screen on the individual instrument administration screen.

GET /api/forms

Parameters

Parameter Required? Description
showurl Optional Include the administration, integration, reporting URLs. Default is true.
showid Optional Include the internal id number. Default is false.
form Optional The form type, generally 2 letter code to show. Default is all available types.
updated_since Optional If supplied, this should be an ISO-8601 formatted GMT timestamp, i.e. 2021-01-01 17:00:00

Response Codes

Response Meaning
200 Success. Returns a list of users.
400 Invalid parameters.

 

Response Format

Key Value
programs a key value pair identifying program code and the human readable name for the program.
data

This returns an array of assessment objects, as described below. Each assessment row represents an administration, where each should be administrated to a single student or graduate.

Key Value
id the unique administration code of this instrument.
updated Date this instrument was last edited to add more data.
category This represents the user assignable metadata field used for internal tracking of groups for the institution.
email Comma separated emails to which this assessment was sent to.
student_name The name which this assessment was assigned to.
admin_url The front facing URL to administrate this instrument to a field instructor, student or graduate. This appears if the parameter showurl is supplied.
pdftranscript When an instrument is complete, this is provided to receive a pdf copy of the completed instrument. This appears if the parameter showurl is supplied.
rtftranscript When an instrument is complete, this is provided to receive a rtf copy of the completed instrument. This appears if the parameter showurl is supplied.
create_date Date this assessment’s purchase was fulfilled
version This represents what version this instrument is. This remains static throughout the lifetime of the instrument.
admin_date The date this instrument was administered via the addition of name or email addresses.
formtype This represents the unique assessment instrument type, generally 2 letters unless this represents a custom instrument type.
not_yet_reported The number of instruments available for reporting
formstatus This represents the current status of this instrument and is listed in the conventions.
locked Whether or not this instrument has been locked and reported on. Locked instruments can no longer be edited or reused. The values are 1 is true, 0 is false.
realid If showid is sent as a parameter, there is a numeric id which may differ from the suffix of the id column. 
assignee_emails Email addresses of alternative recipients of the assessment, generally used to represent field instructors. Multiple emails will be space delimited.
assignee_names Names of alternative recipients of the assessment

Assigning To Respondent

Assign Assessment To A Respondent

This optional service allows an assessment to have an email address or student name assigned before administration to a respondent.

GET /api/assign

Parameters

Parameter Required? Description
id Required The alphanumeric id number representing the assessment
emails Optional The email addresses or SMS numbers, comma separated of the respondents
name Optional The repondent’s name
category Optional Additional metadata field for program internal usage. This data is visible on the user interface.
content Optional* If emails and name parameters are supplied, this non HTML, plain-text only field will send an email utilizing our messaging service to send this assessment. There are two special fields, ###student_name### and ###uniquecode### that if they are not found in the content, will be appended to the end of the email, and are substituted within the content if found. 
subject Optional* If content is populated, this is the subject line for the email. The same replacement variable rules apply from content. Default is “Please Fill Out Assessment for ##STUDENT_NAME###”
delay Optional* If the parameter content is set, this optional field representing the Unix GMT epoch time can be set indicating when this should be emailed. Past times indicate immediately.
suppress_email Optional If any value is passed, the emailing feature will be disabled, allowing for setting email and contact assignment without utilizing the SWEAP email service.
assignee_emails Optional If this value is supplied, this will add the supplied email to a separate, parallel email service to the instrument. The same content and subject data will emailed. More than one email can be provided space separated.
assignee_names Optional If this value is supplied, this will store the assignee’s name to the instrument.

Response Codes

Response Meaning
200 Success. Returns a list of users.
400 Invalid parameters.

Response Format

Key Value
diagnostics Email Diagnostic data if content parameter is set.

Unassigning Existing Data From An Assessment

Unassigning Assessment To A Respondent

This sparingly used service is the opposite of the assignment service and can be leveraged to exchange an existing administration code for a new clone. Only assessments in a non-cancelled status may be exchanged this way. If an instrument is already reported on or is in a completed status, the data is marked unusable for future reporting. This service returns the newly cloned administration code in the response. The list available on the /api/forms api will also be updated.

GET /api/unassign

Parameters

Parameter Required? Description
id Required The alphanumeric id number representing the assessment

Response Codes

Response Meaning
200 Success. Returns a new assessment code in the created field..
400 Invalid parameters.

Response Format

Key Value
diagnostics Email Diagnostic data if content parameter is set.

 

Export Completed Assessment

Save Copy Of An Assessment

This returns a copy of the assessment, after it has reached SAVED or FINISHED status in either RTF or PDF format.

Parameters

Parameter Required? Description
id Required The alphanumeric id number representing the assessment
format Required Current allowed formats are PDF and RTF.

Response Codes

Response Meaning
200 Success. Returns a list of users.
400 Invalid parameters.

Response Format

Key Value
data A Base-64 encoded string representing the exported file requested.

Available Instruments Summary

Retrieve Summary

This returns the available instruments assessments available along with the current status in bulk format. This shows all available classes of instruments available for administration and also represents the “Instruments” screen when logging into the system via regular UI.

GET /api/entitlements

Parameters

none required

Response Codes

Response Meaning
200 Success. Returns a list of users.
400 Invalid parameters.

Response Format

 

Key Value
program The program’s internal unique id. 
name The program’s human readable name.
entitlements

Each available type of instruments available for administration

Key Value
type Unique form identifier for these types of instrument
name Human readable description of this instrument
last_ordered Date this type of instrument was last ordered.
last_filled_out Date of last instrument touch by student or field instructor.
last_administered Date of last administration by GUI or API by assigning a name or an email.
count Number of assessments available for administration or in the process of administration, Does not included already reported on instruments.
refundable The amount, in dollars, refundable for store credit.
available_for_admin The amount of instruments available for administration 
not_yet_reported The number of instruments available for reporting
sls_id Special URL used to administrate all instruments of this type without providing identifying information.
reorder_url Special URL redirecting for reordering this type of instrument.
lti_key Key provisioned for advanced API or LTI integration.
lti_secret Secret provisioned for advanced API or LTI integration