NAV

Introduction

Welcome to the Perusall API! The Perusall API is accessible only to institutions that have an active subscription to Perusall for Institutions. For more information on how to subscribe, contact us.

Each endpoint returns an HTTP code and the results in JSON format.

The API version number appears in each API endpoint. This is version 1 of the API.

Authentication and Security

To authenticate, use this code template:

# Example request template
curl api_endpoint_here \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

Make sure to replace the Institution ID and API Token with your own values.

To authenticate, you will need to know your Institution ID as well as your API Token. Both must be provided in an HTTP header that is present in any request you send to the Perusall API, in the X-Institution and X-API-Token headers, respectively. For example,

X-Institution: Y6mzt2wm6a4PnJwRN

X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6

Your API Token should be secured and never sent over a non-secure (e.g., plain HTTP) connection, as anyone in possession of your API Token would have full access to all API endpoints for your institution. If you believe that your API Token has been compromised for any reason, contact Perusall Support immediately to invalidate the existing API Token and replace it with a new one.

Users

List all users

curl https://app.perusall.com/api/v1/users \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

[
  {
    "_id": "PrbNxbp98xHHpmuAH",
    "firstName": "Bert",
    "lastName": "Sesame",
    "email": "bert@sesamestreet.edu"
  },
  {
    "_id": "HM3d8bfzodcxFB2LK",
    "firstName": "Ernie",
    "lastName": "Sesame",
    "email": "ernie@sesamestreet.edu"
  },
  {
    "_id": "ci7qkm5M7qCWrzM56",
    "firstName": "Oscar",
    "lastName": "Grouch",
    "email": "oscar@sesamestreet.edu"
  },
]

This endpoint retrieves all users associated with your institution.

HTTP Request

GET https://app.perusall.com/api/v1/users

Return Values

Parameter Description
_id The internal ID of the course
firstName The first name of the user
lastName The last name of the user
email The email address of the user

Get user details

curl https://app.perusall.com/api/v1/users/PrbNxbp98xHHpmuAH \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

{
  "_id": "PrbNxbp98xHHpmuAH",
  "firstName": "Bert",
  "lastName": "Sesame",
  "email": "bert@sesamestreet.edu",
  "studentCourseIds": [
    "sEBkShax4uRoMxg8c",
    "ENx8NjaWX9ngiJdEC"
  ]
}

This endpoint retrieves a specific user. If the user is not found, nothing will be returned.

HTTP Request

GET https://app.perusall.com/api/v1/users/<_id>

URL Parameters

Parameter Description
_id The ID of the user to retrieve

Return Values

Parameter Description
_id The internal ID of the user
firstName The first name of the user
lastName The last name of the user
email The email address of the user
studentCourseIds An array of course IDs that the user is associated with as a student
instructorCourseIds An array of course IDs that the user is associated with as an instructor
ltiInstanceId The LMS instance ID associated with this user
ltiUserId The internal LMS user ID associated with this user

Create a user

curl https://app.perusall.com/api/v1/users \
  -X POST \
  -d firstName='Cookie' \
  -d lastName='Monster' \
  -d email='cookie.monster@sesamestreet.edu' \
  -d password='melikecookies' \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

{
  "_id": "adoch93Y4GcD4vNMA"
}

This endpoint creates a new user.

HTTP Request

POST https://app.perusall.com/api/v1/users

POST Parameters

Parameter Description
firstName The first name of the user
lastName The last name of the user
email The email address of the user
password The password the user will use to log in
ltiInstanceId The LMS instance ID that will be sent in the tool_consumer_instance_guid field upon LTI launch for this user
ltiUserId The LMS user ID that will be sent in the user_id field upon LTI launch for this user

Return values

Parameter Description
_id The ID of the new user

Courses

List all courses

curl https://app.perusall.com/api/v1/courses \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

[
  {
    "_id": "Cb9iWajEGcAZGYckZ",
    "name": "MATH 223 Fall 2018"
  },
  {
    "_id": "ccnNBdtAsuotFjFJM",
    "name": "MATH 224 Spring 2019"
  },
  {
    "_id": "jAqCMQ65YNXRir9km",
    "name": "PSYCH 101"
  }
]

This endpoint retrieves all courses associated with your institution.

HTTP Request

GET https://app.perusall.com/api/v1/courses

Return Values

Parameter Description
_id The internal ID of the course
name The name of the course

Get course details

curl https://app.perusall.com/api/v1/course/Cb9iWajEGcAZGYckZ \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

{
  "_id": "Cb9iWajEGcAZGYckZ",
  "instructorIds": ["PngjredhMditfqiuH", "8FjgJEiM2oxhBFZF8"],
  "name": "MATH 223 Fall 2018",
  "lowestPossibleScore": 0,
  "highestPossibleScore": 3,
  "inactiveStudentIds": [],
  "studentIds": [
    "HTXNN9sjqfed6F32R",
    "YHZABR4LFdgCqFfEL",
    "NJ8jHsw6S2EnXQJfr",
    "TxFxt8myZGzaC53dF",
    "duHMMFRJM3TxGFTrb",
    "m2rZggNGP9EKABvNu",
    "LyH6N9qGaAMjWPDcY",
    "D2p987Za4fzSK8F4k"
  ]
}

This endpoint retrieves a specific course. If the course is not found, nothing will be returned.

HTTP Request

GET https://app.perusall.com/api/v1/courses/<_id>

URL Parameters

Parameter Description
_id The ID of the course to retrieve

Return Values

Parameter Description
_id The internal ID of the course
name The name of the course
lowestPossibleScore The lowest possible assignment score for the course
highestPossibleScore The highest possible assignment score for the course
instructorIds A list of user IDs corresponding to the instructor(s) of the course
studentIds A list of user IDs corresponding to the student(s) enrolled in the course
inactiveStudentIds A list of user IDs corresponding to the student(s) that were previously enrolled in the course but are no longer enrolled in the course
ltiInstanceId The LMS instance ID that will be sent in the tool_consumer_instance_guid field upon LTI launch for this course
ltiContextId The LMS course ID that will be sent in the context_id field upon LTI launch for this course
sisId The SIS ID passed from your LMS as part of the LTI launch, if any

Get the contents of a course library

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/library \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

[
  {
    "name": "Introduction to Calculus",
    "format": "epub",
    "fromCatalog": true
  },
  {
    "name": "How the chain rule works",
    "format": "video",
    "fromCatalog": false
  },
  {
]

This endpoint retrieves a list of all items in a course library.

HTTP Request

GET https://app.perusall.com/api/v1/courses/<courseId>/library

Return Values

Parameter Description
_id The internal ID of the library item
name The name of the library item
format The format of the library item
fromCatalog Whether or not the library item was adopted from the Perusall catalog

Get the contents of a document

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/library/jEvGcKsKrPtBZXNJo \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

{
  "_id": "uegA6qmhALzz74eYy",
  "name": "Syllabus",
  "format": "pdf",
  "pages": [
    {
      "number": 1,
      "width": 2448,
      "height": 3168,
      "textContentUrl": "https://...",
      "thumbnailUrl": "https://...",
      "expiresAt": "2025-08-15T04:47:33.399Z"
    },
    {
      "number": 2,
      "width": 2448,
      "height": 3168,
      "textContentUrl": "https://...",
      "thumbnailUrl": "https://...",
      "expiresAt": "2025-08-15T04:47:33.413Z"
    },
    {
      "number": 3,
      "width": 2448,
      "height": 3168,
      "textContentUrl": "https://...",
      "thumbnailUrl": "https://...",
      "expiresAt": "2025-08-15T13:56:44.174Z"
    },
    {
      "number": 4,
      "width": 2448,
      "height": 3168,
      "textContentUrl": "https://...",
      "thumbnailUrl": "https://...",
      "expiresAt": "2025-08-15T13:56:44.196Z"
    }
  ]
}

This endpoint retrieves metadata and the text content (for each page of PDF documents only) of a particular item in the course library. (Due to publisher restrictions, content added to the course from the Perusall catalog cannot be accessed in this way.)

HTTP Request

GET https://app.perusall.com/api/v1/courses/<courseId>/library/<documentId>

Return Values

Parameter Description
_id The internal ID of the library item
name The name of the library item
format The format of the library item
pages.number The page number
pages.width The page width
pages.height The page height
pages.textContentUrl A temporary URL to access the text content of the document
pages.thumbnailUrl A temporary URL to access a thumbnail image of the page
pages.expiresAt When the above two URLs will expire (new URLs will be available at that time)

Create a course

curl https://app.perusall.com/api/v1/courses \
  -X POST \
  -d name='PSYCH 292 Fall 2018' \
  -d enrollmentEstimate=200 \
  -d groupSize=20 \
  -d startDate='2018-09-01' \
  -d instructorIds='YzTDfiW7PWBAYkE4r,2JonBud9pS7HWMimS' \
  -d language='en' \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

{
  "_id": "yosf6ZiSiTgZiiZDX"
}

This endpoint creates a new course, either from scratch or as a copy from an existing course.

HTTP Request

POST https://app.perusall.com/api/v1/courses

POST Parameters

Parameter Description Required when copying course Required when creating new course
fromCourseId The ID of a course to copy from. If this parameter is present, Perusall will copy all documents, assignments, and settings from the existing course into the new one. If this parameter is absent, the new course is created from scratch. X
name The name of the course X X
instructorIds A comma-separated list of user IDs that should be marked as instructors of the new course X X
enrollmentEstimate The enrollment estimate (to be used to create groups) X
groupSize The target group size X
startDate The starting date of the course, in YYYY-MM-DD format X
language The language for the course: one of en or nl X
ltiInstanceId The LMS instance ID that will be sent in the tool_consumer_instance_guid field upon LTI launch for this course
ltiContextId The LMS course ID that will be sent in the context_id field upon LTI launch for this course

Return values

Parameter Description
_id The ID of the new course

Enroll users in a course

curl https://app.perusall.com/api/v1/courses/yosf6ZiSiTgZiiZDX/enroll \
  -X PUT \
  -d studentIds='roiQy2NpMbgGqtaLy' \
  -d instructorIds='YzTDfiW7PWBAYkE4r,2JonBud9pS7HWMimS' \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command does not return anything except a 200 return code upon success.

This endpoint enrolls one or more students or instructors in an existing course.

HTTP Request

PUT https://app.perusall.com/api/v1/courses/<courseId>/enroll

PUT Parameters

Parameter Description
courseId The target course ID
studentIds A comma-separated list of user IDs to enroll in the course as students
instructorIds A comma-separated list of user IDs to enroll in the course as instructors

Return values

Nothing is returned from this endpoint.

Unenroll users from a course

curl https://app.perusall.com/api/v1/courses/yosf6ZiSiTgZiiZDX/unenroll \
  -X PUT \
  -d studentIds='roiQy2NpMbgGqtaLy' \
  -d instructorIds='YzTDfiW7PWBAYkE4r,2JonBud9pS7HWMimS' \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command does not return anything except a 200 return code upon success.

This endpoint removes one or more students or instructors from an existing course.

HTTP Request

PUT https://app.perusall.com/api/v1/courses/<courseId>/unenroll

PUT Parameters

Parameter Description
courseId The target course ID
studentIds A comma-separated list of user IDs to enroll in the course as students
instructorIds A comma-separated list of user IDs to enroll in the course as instructors

Return values

Nothing is returned from this endpoint.

Groups

List all groups for a course

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/groups \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

[
  {
    "number": 1,
    "auto": false,
    "studentIds": [
      "PrbNxbp98xHHpmuAH",
      "HM3d8bfzodcxFB2LK"
    ],
    "externalId": "MathGroupA"
  },
  {
    "number": 2,
    "auto": false,
    "studentIds": [
      "ci7qkm5M7qCWrzM56"
    ],
    "externalId": "MathGroupB"
  }
]

This endpoint retrieves all groups associated with a course.

HTTP Request

GET https://app.perusall.com/api/v1/courses/<courseId>/groups

URL Parameters

Parameter Description
courseId The internal ID of the course

Return Values

Parameter Description
documentId The document ID that this group corresponds to, if any. Automatically-generated groups are created at the document level; manual groups are set at the course level. More about grouping in Perusall
number The group number
auto Whether the group was automatically generated by Perusall (true) or manually set for the course (false)
studentIds A list of student IDs for the members of the group
externalId The external ID specified when creating the group, if any

Set the groups for a course

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/groups \
  -X PUT \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6' \
  -d group1Members='PrbNxbp98xHHpmuAH,HM3d8bfzodcxFB2LK' \
  -d group2Members='ci7qkm5M7qCWrzM56' \
  -d group1ExternalId='MathGroupA' \
  -d group2ExternalID='MathGroupB'

The above command returns JSON structured like this:

[
  {
    "number": 1,
    "auto": false,
    "studentIds": [
      "PrbNxbp98xHHpmuAH",
      "HM3d8bfzodcxFB2LK"
    ],
    "externalId": "MathGroupA"
  },
  {
    "number": 2,
    "auto": false,
    "studentIds": [
      "ci7qkm5M7qCWrzM56"
    ],
    "externalId": "MathGroupB"
  }
]

This endpoint sets manual groups for a course.

HTTP Request

PUT https://app.perusall.com/api/v1/courses/<courseId>/groups

PUT Parameters

There should be a groupN parameter present for each group that you want to set (e.g., group1, group2, group3, etc).

Parameter Description
courseId The internal ID of the course
groupNMembers A comma-separated list of the student IDs that should be members of the Nth group
groupNExternalId An optional external ID to associate with this group; this is not used by Perusall but will be stored with the group and sent back in groups API calls

Return Values

This endpoint returns a list of the groups that are in force after the command has been executed, in the same format as GET /api/v1/course/<courseId>/groups above.

Assignments

List all assignments for a course

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/assignments \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

[
  {
    "_id": "KWQX9L7tWLPswKurd",
    "name": "Chapter 1",
    "documentId": "K89zyHqeANYuzSnFL",
    "documentIds": ["K89zyHqeANYuzSnFL"],
    "parts": [
      {
        "documentId": "K89zyHqeANYuzSnFL",
        "startPage": 1,
        "endPage": 30
      }
    ],
    "deadline": "2018-09-01T08:00:00.000Z"
  },
  {
    "_id": "ynYTBQogSBMrtftzC",
    "name": "Chapter 2",
    "documentId": "K89zyHqeANYuzSnFL",
    "documentIds": ["K89zyHqeANYuzSnFL"],
    "parts": [
      {
        "documentId": "K89zyHqeANYuzSnFL",
        "startPage": 31,
        "endPage": 60
      }
    ],
    "deadline": "2018-09-15T08:00:00.000Z"
  },
  {
    "_id": "9rHuTSSKyt953BnPo",
    "name": "Article from New York Times on probabilistic thinking",
    "documentId": "FYLFRP9bDyYbsczcP",
    "documentIds": ["FYLFRP9bDyYbsczcP"],
    "parts": [
      {
        "documentId": "FYLFRP9bDyYbsczcP",
        "startPage": 1,
        "endPage": 3
      }
    ],
    "deadline": "2018-10-01T08:00:00.000Z"
  }
]

This endpoint retrieves all assignments associated with the specified course.

HTTP Request

GET https://app.perusall.com/api/v1/courses/<courseId>/assignments

URL Parameters

Parameter Description
courseId The ID of the course to search

Return Values

Parameter Description
_id The unique ID of the assignment
name The name of the assignment, specified by the author (if any) or automatically generated by Perusall based on the portion of the document assigned
documentId If only one document is assigned, the ID of the document assigned. (This field is omitted if there are multiple documents assigned.
documentIds A list of assigned document IDs.
parts A specification of each part of the assignment. Each part consists of a documentId and an indication of the range assigned from that document.
deadline The deadline set for the assignment, in ISO 8601 format
studentIds If applicable, an array of the students that the assignment was assigned to; if missing, the assignment was assigned to all students

Retrieve scores for an assignment

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/assignments/KWQX9L7tWLPswKurd/scores \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

[
  {
    "studentId": "PrbNxbp98xHHpmuAH",
    "score": 2,
    "released": true
  },
  {
    "studentId": "HM3d8bfzodcxFB2LK",
    "score": 0,
    "released": true
  }
]

This endpoint retrieves all scores associated with the specified assignment.

HTTP Request

GET https://app.perusall.com/api/v1/courses/<courseId>/assignments/<assignmentId>/scores

URL Parameters

Parameter Description
courseId The ID of the course
assignmentId The ID of the assignment

Return Values

Parameter Description
studentId The ID of the student this record applies to
score The student's score on the assignment, as it would appear in the gradebook
released Whether the score has been released to the student (true or false)

Retrieve comments for an assignment

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/assignments/KWQX9L7tWLPswKurd/annotations \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

[
  {
    "id": "W5Cer9NdrPKwQSeHK",
    "studentId": "PrbNxbp98xHHpmuAH",
    "text": "<p>I agree - good point!</p>",
    "plainText": "I agree - good point!",
    "fragment": "A hot dog is very much a sandwich.",
    "score": 0,
    "range": {
      "type": "text",
      "start": 18,
      "end": 51,
      "page": 1
    },
    "createdAt": "2022-10-19T16:02:03.980Z",
    "editedAt": "2022-10-19T16:02:03.979Z"
  },
  {
    "id": "bGoqsevH7SBAtbgmc",
    "parentAnnotationId": "W5Cer9NdrPKwQSeHK",
    "studentId": "HM3d8bfzodcxFB2LK",
    "text": "<p>Me too!</p>",
    "plainText": "Me too!",
    "fragment": "A hot dog is very much a sandwich.",
    "score": 0,
    "range": {
      "type": "text",
      "start": 18,
      "end": 51,
      "page": 1
    },
    "createdAt": "2022-10-19T16:04:03.980Z",
    "editedAt": "2022-10-19T16:04:03.979Z"
  }
]

This endpoint retrieves all comments counting towards the specified assignment.

HTTP Request

GET https://app.perusall.com/api/v1/courses/<courseId>/assignments/<assignmentId>/annotations

URL Parameters

Parameter Description
courseId The ID of the course
assignmentId The ID of the assignment

Return Values

Parameter Description
id The ID of the annotation
parentAnnotationId The ID of the annotation that this annotation is in reply to, if any
studentId The ID of the student this record applies to
text The text of the student's comment, in HTML
plainText A plain text version of the student's comment
score The quality score for the annotation, either machine-generated or as overridden by an instructor
range The range highlighted in the text, image, video, or podcast.
createdAt When the annotation was first submitted
editedAt When the annotation was last edited

Post a comment on behalf of a user

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/assignments/KWQX9L7tWLPswKurd/annotations \
  -X POST \

  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6' \
  -d documentId='Mq85up7GkJdJduoFT' \
  -d userId='z26jrYkTsST7eqmDT' \
  -d positionStartX='0.4' \
  -d positionStartY='1.5' \
  -d positionEndX='0.42' \
  -d positionEndY='1.52' \
  -d rangeType='text' \
  -d rangeStart='100' \
  -d rangeEnd='107' \
  -d fragment='Highlight' \
  -d text='This is my comment'

The above command returns a JSON structured like this:

[
  {
    "id": "W5Cer9NdrPKwQSeHK"
  }
]

This endpoint posts a comment for a particular assignment, on behalf of a particular user.

Annotation position within a document is indicated in two ways (both of which should be consistent with each other).

HTTP Request

POST https://app.perusall.com/api/v1/courses/<courseId>/assignments/<assignmentId>/annotations

URL Parameters

Parameter Description
documentId The ID of the document
userId The ID of the user posting the annotation
positionStartX The starting x-coordinate of the highlight
positionStartY The starting y-coordinate of the highlight
positionEndX The ending x-coordinate of the highlight
positionEndY The ending y-coordinate of the highlight
rangeType The type of highlight: text, dot, rectangle, or video
rangePage The page number of the highlight (1-based)
rangeStart The starting offset (text highlights only)
rangeEnd The ending offset (text highlights only)
fragment The fragment of text highlighted (plain text)
text The content of the comment (HTML allowed)

Return Values

Parameter Description
_id The ID of the annotation

Retrieve analytics for an assignment

curl https://app.perusall.com/api/v1/courses/Cb9iWajEGcAZGYckZ/assignments/KWQX9L7tWLPswKurd/analytics/grades \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

{
  "grades": [
    {
      "_id": "2wSHpXQRKYSrzzyfY",
      "userId": "PrbNxbp98xHHpmuAH",
      "score": 2
    },
    {
      "_id": "gRnqDAPAA6sLye2fN",
      "userId": "HM3d8bfzodcxFB2LK",
      "score": 0
    }
  ],
  "updatedAt": "2018-08-08T21:58:57.885Z"
}

This endpoint retrieves the data for one of the analytics reports available in the Perusall UI.

HTTP Request

GET https://app.perusall.com/api/v1/courses/<courseId>/assignments/<assignmentId>/analytics/<report>/<part>

URL Parameters

Parameter Description
courseId The ID of the course
assignmentId The ID of the assignment
report The report to run, one of grades, submissionTime, pageViews, or studentActivity
part The part of the assignment to retrieve the report for (1, 2, etc.), specified for all reports except grades

Return Values

The return format varies depending on the report selected. In each case, the data returned constitutes the raw data that Perusall uses to build the graphs shown in the UI. Each report always includes an updatedAt field that indicates the time that Perusall generated the data for that report.

Access codes

Generate an access code

curl https://app.perusall.com/api/v1/access_codes \
  -X POST \
  -d isbn='9781608192939' \
  -d order='KBL12345' \
  -d purchaseType='perpetual' \
  -d currency='USD' \
  -d nonce='15f07498-0cf7-4147-afe2-4eed27b58e1f' \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

The above command returns JSON structured like this:

{
  "code": "PERUSALL-EB8UF-UA26B-3K296-3QN8L-BZ6MW"
}

This endpoint generates an access code for a particular book, for retail sale or for inclusive access. You will be billed upon redemption for each access code generated.

HTTP Request

POST https://app.perusall.com/api/v1/access_codes

POST Parameters

Parameter Description
isbn The ISBN of the item to order; Consult the Perusall catalog to look up ISBNs and available purchase types and durations
order An order number or name to associate this code with (this can be any value)
purchaseType The purchase type, either perpetual or rental
purchaseDuration The purchase duration, in days (only required for rentals)
currency The currency to request pricing in (e.g., USD)
nonce To avoid accidentally-repeated requests overprovisioning access codes that you will be billed for, you must provide a unique "nonce" value with each request; this can be any value but must be unique (suggest a GUID or other guaranteed-random value)
inclusiveAccess Set to any value to indicate this code is for an inclusive access adoption; omit to indicate this code is for retail

Return values

Parameter Description
code The access code to provide to the student

Deactivate an access code

curl https://app.perusall.com/api/v1/access_codes/PERUSALL-EB8UF-UA26B-3K296-3QN8L-BZ6MW \
  -X DELETE \
  -H 'X-Institution: Y6mzt2wm6a4PnJwRN' \
  -H 'X-API-Token: 7f5cWceWiOXdCQYcKcBITLdXCvyjaCsJ0uNWN_t6-A6'

This endpoint deactivates an access code previously generated through the API. Access codes cannot be deactivated once redeemed by a student. You will not be billed for deactivated access codes.

HTTP Request

DELETE https://app.perusall.com/api/v1/access_codes/<code>

URL Parameters

Parameter Description
code The access code to deactivate, in the form PERUSALL-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

Errors

The Perusall API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your Institution ID or API token is incorrect.
403 Forbidden -- Your account does not have privileges to access this endpoint.
404 Not Found -- The specified API endpoint could not be found.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.