Inspera Originality API Documentation

  • Updated

All API calls in this document use {{BASE_URL}} as a placeholder for the appropriate base URL, which should be replaced depending on whether you're operating in the development or production environment.

Testing Environment

Use this environment for testing and development purposes. Note that it may have different rate limits and data sets compared to production.

Base URL - https://ja0ot1lhh6.execute-api.eu-central-1.amazonaws.com/test

Production Environment

The production environment is the live environment for actual user interactions. Please make sure that the proper URL is used for your production applications.

Base URL - https://6x6hep4ey9.execute-api.eu-central-1.amazonaws.com/production

API Calls 

Upload Endpoints

  1. POSTAuthorization

    This POST request is used to obtain an authentication token. The token must be included in the header of subsequent requests to authorize access to other API endpoints.

    The clientId will be provided by Inspera Originality.

    1. Request Example

      curl --request POST \
--url {{BASE_URL}}/token \
--header 'Content-Type: application/json' \
--data '{
"clientId": "a1b2c3d4-e5f6-7890-abcd-1234567890ef", // example clientId
"institutionId": "inst_9876543210" // example institutionId
}'

    2. Response Example

      {
"token": "eyJhbGciOiJIUzI1NiIsIIkpXVCJ9.eyJjbGllbnRJZCI6IkZ....", // example token 
"expirationTime": 1759208000000 // expires 24 hours from issuance
}
    3. Possible Errors
      • 401 unauthorized - The clientId is invalid
      • 404 bad request - Required fields were invalid 

  2. POSTDocument Uploading

    To initiate the document similarity check, send a POST request to the /create/submission endpoint, which  acts as the entry point for the system to process and analyze the submitted document. The API response includes a message field indicating whether the document upload was successful or if any errors occurred during the process. It also includes a documentId, which serves as a unique identifier for the uploaded document and can be used for future reference or actions. Additionally, the response provides a presignedS3Url. This URL is where the document file must be uploaded for the system to process it.

    Required & Optional Request Parameters

    Required parameters

    • documentTitle: The title given to the document being submitted.
    • author: The name of the individual who authored the document.
    • email: The email address of the student uploading the document.
    • docType: Specifies the document type using supported MIME types (required, with various supported formats such as .pdf, .docx, .txt, etc.).

    Optional parameters

    • translatedLanguage: Used for cross-language similarity checks. Accepts a language code (optional). Supported languages include: English (en), Albanian (sq), German (de), Italian (it), Lithuanian (lt), Spanish (es), Portuguese (pt), Czech (cs), Turkish (tr) Slovak (sk), French (fr), Macedonian (mk) Polish (pl), Norwegian (no), Latvian (lv) Greek (el), Dutch (nl), Russian (ru), Bulgarian (bg), Hungarian (hu), Romanian (ro), Serbian (sr), Swedish (sv), Finnish (fi) Croatian (hr), Danish (da), Bosnian (bs), Slovenian (sl), Estonian (et)
    • assignmentId: Identifies the assignment the document is linked to (optional).
    • institutionName: The name of the institution from which the document was submitted (optional).
    • enableAIDetection: Enables AI authorship detection when set to true (optional, default is disabled).
    • enableReferenceDetection: Toggles reference detection (optional, enabled by default).
    • reSubmissions: Sets how many times resubmission is allowed (optional, default is 1).
    • subjectId: The ID of the subject the document relates to (optional).
    • maxLimit: Sets a maximum word count limit for the document (optional, no limit by default).
    • archive: Indicates whether the submission should be archived for collusion detection (optional, default is false).
    • enableContextSimilarity: Enables the Contextual Similarity analysis.
    • sentenceThresholds: Object parameter that enables defining the percentage at which sentence classifications apply. Requires entering  contextualSimilaritiesThreshold , alteredTextSimilarityThreshold, and exactMatchSimilarityThreshold as numbers. 
    • sources: Object parameter that enables defining sources to include or exclude from the originality check. Requires entering includeSources and excludeSources as arrays and defining URLs as strings for each. 
    • sourcesThreshold: Specified as a number, defines the percentage below which matching sources are not considered in the Originality Report. E.g., setting this to 5 means that sources below 5% are not taken into consideration and therefore not included in the Originality Report. 

     

    1. Request Example

      curl --request POST \
--url {{BASE_URL}}/create/submission \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
 "documentTitle": "<string>", --> Required
 "author": "<string>", ---------> Required
 "email": "<string>", ----------> Required
 "docType": "<string>" ---------> Required
 "translatedLanguage": [
  "en", 
  "sq", 
  "et"
 ],
 "assignmentId": "<string>",
 "institutionName": "<string>",
 "enableAIDetection": true, -> boolean, true or false
 "enableReferenceDetection":  true, -> boolean, true or false
 "reSubmissions": "<number>",
 "subjectId": "<string>",
 "maxLimit": "<number>",
 "archive": true, -> Boolean, true or false
 "enableContextSimilarity" -> Boolean, true of false
 "sentenceThresholds": { 
   "contextualSimilaritiesThreshold": 65,
   "alteredTextSimilarityThreshold": 60, 
   "exactMatchSimilarityThreshold": 80
 },
 "sources": {
  "excludeSources": [ -> exclude sources from the Originality Check 
    "https://exampleurl1.com",
    "https://exampleurl2.com"
    ],
  "includeSources": [ -> include sources in the Originality Check
    "https://exampleurl3.com",
    "https://exampleurl4.com"
    ]
  },
"sourcesThreshold": 5 -> percentage below which sources are not considered. 
}'

    2. Response Example

      {
 "documentId": "cmdlxqztb10006xa582hjtkeu",
 "message": "Your document is uploaded successfully",
 "presignedS3Url": "<string>" // The URL where the document must be uploaded.
}
    3. Possible Errors
      • 401 unauthorized - Token has expired
      • 403 forbidden
        • Maximum of submissions has been reached
        • Document title has less than 5 characters or more than 190 characters
        • Document word count is more than the allowed maximum
        • Document structure is invalid
        • Maximum of submissions has been reached
        • Document structure is invalid
      • 400 bad request - The required fields are invalid

  3. GETDocument Status Check - Poll Set Up 

    To check the status of a document, send a GET request to the endpoint specified in the request example, using the documentId (received from the previous response) as a path parameter. This is a manual process that returns the current status of the specified document.

    1. Request Example

      curl --request GET \
--url {{BASE_URL}}/document/%7B{documentId}%7D/checkStatus \
--header 'Authorization: Bearer <token>'

    2. Response Example

      {
  "message": "Document is processed",
  "status": 1,
  "similarity": "33.3",
  "translation_similarity": "62",
  "Ai_index": "20%",
  "originality": "High Risk", 
  "characterReplacements": 5,
  "hiddenText": 2,
  "imageAsText": 1,
  "originality_percentage": 80
}
      • Status
        • -1 indicates that the document is still being processed
        • 1 indicates that the document has been successfully processed
        • 0 indicates that the document is queued for processing
        • 2 indicates that an error has occurred. 
      • "similarity" indicates the level of Original Language similarity
      • "translation_similarity" indicates the level of Translation Similarity 
      • "ai_index" indicates the level of content potentially generated by AI
      • "originality" indicates the classification, either High, Medium, or Low Risk. 
      • "characterReplacement" provides the number of character replacements 
      • "hiddenText" provides the number of hidden text instances
      • "imageAsText" provides the number of images concealed regular text
    3. Possible Errors
      • 400 - Bad Request
      • 401 - Token Has Expired
      • 403 - Forbidden
      • 404 - Submission Not Found

  4. GETGet Report URL

    This request initiates the Originality Report API by providing the required path parameters, documentId and mode. In return, the API responds with a session-based URL to access the report. The documentId is a unique identifier generated by the /create/submission endpoint, used to reference the specific document for which the report is being requested. The mode parameter defines the level of access to the report, use "view" to grant read-only access, or "edit" to enable editing capabilities within the report interface.

    Important

    When this endpoint is called, it returns a temporary session-based URL rather than the actual report URL. This session URL is a one-time, time-limited link that triggers a verification process on the backend.

    Session IDs are designed to expire either:

    • After the 2-minute time window has elapsed
    • Immediately after the associated Originality Report has been opened.

    This built-in expiry mechanism ensures that the session ID cannot be reused or shared. Consequently, Originality Reports cannot be accessed via shared URLs, as expired session IDs render such links invalid. This time-sensitive access model reinforces security by preventing unauthorized redistribution of report links.

    1. Request Example

      curl --request GET \
--url {{BASE_URL}}/document/{documentId}/mode/{mode} \
--header 'Authorization: Bearer <token>'

    2. Response Example

      {
  "url": "<string>"
}
    3. Possible Errors
      • 400 - Bad request
      • 401 - Token has expired
      • 403 - Forbidden 
      • 404 - Submission not found

CRUD Endpoints

  1. POSTAuthorization (CRUD)

    To interact with the CRUD API, clients must first obtain an access token. This is achieved by sending a POST request to the /login endpoint with the user's credentials. The API will validate the provided email and password, and if successful, respond with an authentication token that must be included in the header of all subsequent requests. The response includes additional information, however, you only need the token to proceed with subsequent calls. 

    1. Request Example

      curl --request POST \
--url {{BASE_URL}}/login \
--header 'Content-Type: application/json' \
--data '{
"email": "example@email.com",
"password": "examplepassword"
}'

    2. Response Example

      {
 "token": "eyJhbDciOiJIUcI1NiDsIIkpXVCJ9.eyJjbGbbbnRJZCI6IkZ..", // example token 
}
    3. Possible Errors
      • 404 - User not found
      • 409 - Invalid email format
      • 422 - Invalid credentials
      • 500 - Server Error

  2. POSTCreate User (CRUD)

    This API call is used to create a new user on the platform. It allows specifying general new user details as well as assign existing subjects to the new user via the courses parameter. 

    The bearer token should be inserted into the authorization header

    1. Request Example

      curl --request POST \
--url {{BASE_URL}}/user \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"firstName": "Emily",
"lastName": "Walker",
"email": "ew@email.com"
"role": "educator", // can be either "student" or "educator"
"status": 1, // User 1 for Active and 0 for Inactive 
"courses": [
 "subjectcode", // The subject's unique identifier. E.g., CS101
 "subjectcode"
  ]
}'

    2. Response Example

      {
  "id": "cmg04yzpa0007y6k8r2dq1nvm",
  "name": "Emily Walker",
  "email": "ew@email.com",
  "status": 1,
  "createdAt": "2025-06-20T11:32:18.446Z",
  "updatedAt": "2025-07-30T15:48:22.119Z",
  "institutionId": "cmg03kuda0005y6k9g8e4j7bd",
  "departmentId": "cmg03kudc0006y6k90zv3m0hy",
  "facultyId": "cmg03kud90004y6k8v0apnlsm",
  "lastLogin": null,
  "isDeleted": false
}
    3. Possible Errors
      • 401 - Not authorized to take action 
      • 402 - Validation error: The first name must consist of only letters and be at least three characters long, while the last name must contain only letters and at least three characters long.
      • 409 - Validation error: Invalid email format, email already exists.
      • 500 - Server error

  3. GETRetrieve User by Email (CRUD)

    This endpoint allows you to fetch user information based on their email address. By sending a GET request to the /user-info endpoint with the user’s email as a query parameter, you can retrieve detailed information about that specific user.

    The bearer token should be inserted into the authorization header

    1. Request Example

      curl --request GET \
--url '{{BASE_URL}}/user-info?email=%7B{userEmail}%7D' \
--header 'Authorization: Bearer <token>'

    2. Response Example

      {
  "id": "cmg04yzpa0007y6k8r2dq1nvm",
  "name": "Emily Walker",
  "email": "ew@email.com",
  "status": 1, // 1 indicates Active status, 0 indicates Inactive status
  "createdAt": "2025-04-10T08:30:00Z",
  "updatedAt": "2025-05-28T14:45:00Z",
  "institutionId": "cmg03kuda0005y6k9g8e4j7bd",
  "departmentId": "cmg03kudc0006y6k90zv3m0hy",
  "facultyId": "cmg03kud90004y6k8v0apnlsm",
  "lastLogin": "2025-05-27T16:20:00Z",
  "isDeleted": false, 
  "roleId": "10",
  "role": "Professor"
}
    3. Possible Errors
      • 401 - User not authorized to take action
      • 404 - User not found
      • 403 - User not authorized to access data from different institution
      • 500 - Server error

  4. GETRetrieve Users with Pagination (CRUD)

    This endpoint allows you to retrieve a paginated list of all users in the system. The page query parameter specifies which page of results to fetch, allowing clients to navigate through user records one page at a time. Note that the limit of user information shown per page is 10 by default. 

    The bearer token should be inserted into the authorization header

    1. Request Example

      curl --request GET \
--url '{{BASE_URL}}/user-info?page=%7B{pageNumber}%7D' \
--header 'Authorization: Bearer <token>'

    2. Response Example

      • total - Represents the total number of users available in the system.
      • page - Indicates the current page number being returned in the response.
      • limit - The default limit of user information shown per page is 10. 
      • pages - Shows the total number of pages available based on the defined limit.
      {
"users": [
{
   "id": "cmgr2bdcc3048vod4g3sjlvk0",
   "name": "Institution Admin",
   "email": "admin@email.com",
   "status": 1,
   "createdAt": "2025-07-31T07:17:36.948Z",
   "updatedAt": "2025-07-31T07:26:11.408Z",
   "institutionId": "cmg03kuda0005y6k9g8e4j7bd",
   "departmentId": "cmg03kudc0006y6k90zv3m0hy",
   "facultyId": "cmg03kud90004y6k8v0apnlsm",
   "lastLogin": "2025-07-31T07:26:11.405Z",
   "isDeleted": false,
   "roleId": 11,
   "role": "Admin"
},
 {
   "id": "cmgr2n53f000273silwlg127u",
   "name": "Emily Walker",
   "email": "ew@email.com",
   "status": 1,
   "createdAt": "2025-07-31T07:26:51.340Z",
   "updatedAt": "2025-07-31T08:21:56.615Z",
   "institutionId": "cmg03kuda0005y6k9g8e4j7bd",
   "departmentId": "cmg03kudc0006y6k90zv3m0hy",
   "facultyId": "cmg03kud90004y6k8v0apnlsm",
   "lastLogin": null,
   "isDeleted": false,
   "roleId": 9,
   "role": "Student"
 },
 {
   "id": "cmgr2x6si0000v5513n6cj21f",
   "name": "John Doe",
   "email": "jd@email.com",
   "status": 1,
   "createdAt": "2025-07-31T07:34:34.914Z",
   "updatedAt": "2025-07-31T07:35:28.825Z",
   "institutionId": "cmg03kuda0005y6k9g8e4j7bd",
   "departmentId": "cmg03kudc0006y6k90zv3m0hy",
   "facultyId": "cmg03kud90004y6k8v0apnlsm",
   "lastLogin": null,
   "isDeleted": false,
   "roleId": 9,
   "role": "Student"
 },
 {
   "id": "cmgr3g01k0000of4dd3am5r1k",
   "name": "Simon James",
   "email": "sj@email.com",
   "status": 1,
   "createdAt": "2025-07-31T07:49:12.632Z",
   "updatedAt": "2025-07-31T08:11:41.200Z",
   "institutionId": "cmg03kuda0005y6k9g8e4j7bd",
   "departmentId": "cmg03kudc0006y6k90zv3m0hy",
   "facultyId": "cmg03kud90004y6k8v0apnlsm",
   "lastLogin": null,
   "isDeleted": false,
   "roleId": 10,
   "role": "Professor"
 }
],
   "pagination": {
   "total": 8,
   "page": 1,
   "limit": 10,
  "pages": 1
 }
}
    3. Possible Errors
      • 401 - User not authorized to take action
      • 500 - Server Error

  5. GETRetrieve Users with Pagination & Custom Limit (CRUD)

    This request is used to retrieve a paginated list of users with both page number and page size specified. The page query parameter specifies the current page number to retrieve when requesting a paginated list of users, while the limit parameter defines the maximum number of user records returned per page, allowing greater control over which set of user records is returned and how many are shown per page.

    The bearer token should be inserted into the authorization header.

    1. Request Example

      curl --request GET \
--url '{{BASE_URL}}/user-info?page=%7B{pageNumber}%7D&limit=%7B{pageLimit}%7D' \
--header 'Authorization: Bearer <token>'

    2. Response Example

      • total - Represents the total number of users available in the system.

      • page - Indicates the current page number being returned in the response.

      • limit - Defines the maximum number of users displayed per page.

      • pages - Shows the total number of pages available based on the defined limit.

      {
"users": [
 {
   "id": "cmgr2bdcc3048vod4g3sjlvk0",
   "name": "Institution Admin",
   "email": "admin@email.com",
   "status": 1,
   "createdAt": "2025-07-31T07:17:36.948Z",
   "updatedAt": "2025-07-31T07:26:11.408Z",
   "institutionId": "cmg03kuda0005y6k9g8e4j7bd",
   "departmentId": "cmg03kudc0006y6k90zv3m0hy",
   "facultyId": "cmg03kud90004y6k8v0apnlsm",
   "lastLogin": "2025-07-31T07:26:11.405Z",
   "isDeleted": false,
   "roleId": 11,
   "role": "Admin"
 },
 { 
   "id": "cmgr2n53f000273silwlg127u",
   "name": "Emily Walker",
   "email": "ew@email.com",
   "status": 1,
   "createdAt": "2025-07-31T07:26:51.340Z",
   "updatedAt": "2025-07-31T08:21:56.615Z",
   "institutionId": "cmg03kuda0005y6k9g8e4j7bd",
   "departmentId": "cmg03kudc0006y6k90zv3m0hy",
   "facultyId": "cmg03kud90004y6k8v0apnlsm",
   "lastLogin": null,
   "isDeleted": false,
   "roleId": 9,
   "role": "Student"
 }
],
   "pagination": {
   "total": 8,
   "page": 1,
   "limit": 2, // limit set to 2 user records per page
   "pages": 4 // updated number of total pages based on the define limit
 }
}
    3. Possible Errors
      • 401 - User not authorized to take action
      • 500 - Server Error

  6. PUTUpdate Educator (CRUD)

    This API endpoint is used to update an educator’s profile. It requires a PUT request with the userId specified as a query parameter. The request body must include the educator’s new first name, last name, and an updated list of subjects they will be assigned to. All fields are mandatory to ensure the educator’s information is accurately updated.

    The bearer token should be inserted into the authorization header.

    1. Request Example

      curl --request PUT \
--url '{{BASE_URL}}/user-info?userId=%7B{userId}%7D' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"firstName": "Jane", // New first name
"lastName": "Doe", // New last name 
"email": "jd@email.com" // New email
"status": 1, // Use 1 for Active status and 0 for Inactive status
"userSubjects": [
   "subject105d8" // The subject's unique identifier
  ]
}'

    2. Response Example

      {
  "message": "User updated successfully!"
}
    3. Possible Errors
      • 401 - No authorization to take action
      • 402 - Validation errors: The first name must consist of only letters and be at least three characters long, while the last name must contain only letters and at least three characters long
      • 403 - Not authorized to edit user from different institution
      • 404 - User not found
      • 500 - Server error, email already registered

  7. PUTUpdate Student (CRUD)

    This API call is used to update a student’s profile. The userId must be provided as a query parameter to identify the specific student. In the request body, you must include the student’s new first name, last name, email, and status. All fields are required to ensure the student’s record is properly updated in the system.

    The bearer token should be inserted into the authorization header.

    1. Request Example

      curl --request PUT \
--url '{{BASE_URL}}/user-info?userId=%7B{userId}%7D' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"firstName": "Jane", // New first name
"lastName": "Smith", // New last name
"status": 1, // Use 1 for Active status and 0 for Inactive status
"email": "jane.smith@example.com" // New email
}'

    2. Response Example

      {
 "message": "User updated successfully!"
}
    3. Possible Errors
      • 401 - Not authorized to take action
      • 402 - Validation errors: The first name must consist of only letters and be at least three characters long, while the last name must contain only letters and be a at least three characters long
      • 403 - Not authorized to edit user from different institution
      • 404 - User not found
      • 500 - Server error, email already registered

  8. DELETEDelete User (CRUD)

    This endpoint is used to delete a user from the system. It expects a user ID to be provided in the query parameters to identify which user should be removed.

    The bearer token should be inserted into the authorization header.

    1. Request Example

      curl --request DELETE \
--url {{BASE_URL}}/user?userId=%7B{userId}%7D \
--header 'Authorization: Bearer <token>'

    2. Response Example

      {
  "message": "User deleted successfully"
}
    3. Possible Errors 
      • 401 - Not authorized to take action
      • 403 - Not authorized to delete user from different institution
      • 404 - User not found
      • 500 - Server error

  9. GETRetrieve Course Details with Course Code (CRUD)

    This API call is used to retrieve detailed information about a specific course by providing the course’s unique identification code. A GET request is made to the /courses-info endpoint, with the courseCode included as a required query parameter.

    The bearer token should be inserted into the authorization header.

    1. Request Example

      curl --request GET \
--url '{{BASE_URL}}/courses-info?courseCode=%7B{course Code}%7D' \
--header 'Authorization: Bearer <token>'

    2. Response Example

      {
 "course": {
    "id": "cmgr4ef8f0000q307p110s9tn",
    "title": "Economics",
    "description": "Introduction of common economic principles.",
    "departmentId": "cmgr2bdc80006vod823yotl2j",
    "year": 1,
    "code": "EC2025",
    "createdBy": "cmgr2bdcc0302ved3g3sjzvl0",
    "status": true,
    "isDeleted": false,
    "type": 1, // indicates the subject type, either (1) Mandatory or (2) Elective
    "level": "bachelor",
    "generation": "g2526",
    "platform": "IO",
    "createdAt": "2025-01-15T09:00:00.000Z",
    "updatedAt": "2025-06-10T15:30:00.000Z"
  },
  "message": "Course details retrieved successfully"
}
    3. Possible Errors
      • 404 - Course not found
      • 500 - Server error

  10. GETRetrieve Course Details with Pagination & Limit (CRUD)

    This request retrieves a paginated list of course information from the /courses-info endpoint. It uses two query parameters, page to specify the page number of results, and limit to define how many items should be returned per page.

    The bearer token should be inserted into the authorization header.

    1. Request Example

      curl --request GET \
--url '{{BASE_URL}}/courses-info?page=%7B{pageNumber}%7D&limit=%7B{pageLimit}%7D' \
--header 'Authorization: Bearer <token>'

    2. Response Example

      • page – The current page number returned in the response. This corresponds to the page value provided in the request and tells you which slice of data you’re viewing.
      • pages – The total number of available pages based on the dataset and the limit. 
      • total – The total number of records/items available across all pages. 
      • limit – The number of records returned per page, as specified in the request. 
      {
"courses": [
  {
   "id": "cmgr4ef8f0000q307p110s9tn",
   "title": "Economics",
   "description": "Introduction to common economic principles.",
   "departmentId": "cmgr2bdc80006vod823yotl2j",
   "year": 1,
   "code": "EC2025",
   "createdBy": "cmgr2bdcc0302ved3g3sjzvl0",
   "status": true,
   "isDeleted": false,
   "type": 1, // indicates the subject type, either (1) Mandatory or (2) Elective
   "level": "bachelor",
   "generation": "g2425",
   "platform": "IO",
   "createdAt": "2025-07-15T09:00:00.000Z",
   "updatedAt": "2025-07-15T09:00:00.000Z"
  },
  {
   "id": "cmgr4ef8f2222e214p210s9gm",
   "title": "Modern History",
   "description": "A survey of world events from 1900 to present.",
   "departmentId": "cmgk5x8q10009xwe91bl2n34s",
   "year": 2,
   "code": "HS2025",
   "createdBy": "cmgr7tfdd0405vek7u5kpzwn9",
   "status": true,
   "isDeleted": false,
   "type": 2, // indicates the subject type, either (1) Mandatory or (2) Elective
   "level": "bachelor",
   "generation": "g2425",
   "platform": "IO",
   "createdAt": "2025-07-18T11:30:00.000Z",
   "updatedAt": "2025-07-18T11:30:00.000Z"
  }
],
  "pagination": {
  "page": 1,
  "pages": 2,
  "total": 3,
  "limit": 2
  },
 "message": "Courses retrieved successfully"
}
    3. Possible Errors
      • 500 - Server Error

  11. GETInstitution Faculties & Departments with Relations (CRUD)

    This endpoint is used to retrieve information about an institution, including its faculties, departments, and how they are related.

    The bearer token should be inserted into the authorization header.

    1. Request Example

      curl --request GET \
--url {{BASE_URL}}/institution-info \
--header 'Authorization: Bearer <token>'

    2. Response Example

      {
   "institution": {
      "id": "cmgr2bdkuj0e01vod8salmeq4l",
      "name": "Example University",
      "description": "A leading technology-focused university",
      "ltiSecret": null,
      "createdAt": "2024-03-12T08:15:45.123Z",
      "updatedAt": "2025-07-20T10:30:00.456Z",
      "clientId": "a1b2c3d4-e5f6-7890-abcd-1234567890ef", // example clientId,
      "isTesting": 0,
      "Faculty": [
          {
            "id": "cmgq4kze20003vpd6n7yxj3ta",
            "name": "Faculty of Engineering",
             "description": "Engineering and Applied Sciences",
             "institutionId": "cmgr2bdkuj0e01vod8salmeq4l",
             "createdAt": "2024-04-01T09:00:00.000Z",
             "updatedAt": "2024-12-15T16:45:22.789Z",
             "isDeleted": false,
      "Department": [
          {
             "id": "cmgr2bdc80006vod823yotl2j",
             "name": "Intro to CS",
             "description": "Computer Science Introduction",
             "level": 1,
             "year": 1,
             "facultyId": "cmgq4kze20003vpd6n7yxj3ta",
             "createdAt": "2024-04-01T09:15:00.000Z",
             "updatedAt": "2024-04-01T09:15:00.000Z",
             "isDeleted": false
          },
          {
             "id": "cmgk4bdc80006vod9x3rwt7ly",
             "name": "Intro to Cybersecurity",
             "description": "Cybersecurity Introduction",
             "level": 1,
             "year": 1,
             "facultyId": "cmgq4kze20003vpd6n7yxj3ta",
             "createdAt": "2024-04-01T09:20:00.000Z",
             "updatedAt": "2024-04-01T09:20:00.000Z",
             "isDeleted": false
           }
         ]
       }
     ]
   }
}
    3. Possible Errors
      • 500 - Server Error

 

Webhooks

Webhook Usage Initialization

Clients integrating with the system must provide a webhook endpoint, a URL where they will receive notifications about key events (e.g., when a document has been processed).

When an event occurs (e.g., a document is successfully processed), the system sends a POST request to the client's provided webhook URL. The request body is URL-encoded (application/x-www-form-urlencoded) and contains two parameters: client_id and originality_update.

  • client_id - The client_id is used to identify the client receiving the request.
  • originality_update -  Contains a JWT (JSON Web Token) that securely encodes the update data related to the document. This approach ensures that sensitive information is transmitted in a compact, verifiable, and tamper-proof format. The JWT is signed using the RS256 algorithm, which utilizes asymmetric encryption for added security. To decode and verify the authenticity of the originality_update token, the client must use a public key provided by the platform. To decode and verify the authenticity of the originality_update token, the client must use a public key provided by the platform. Inspera Originality will provide documentation to clients on how to obtain this key.

Webhook Notifications

Once the originality_token has been successfully verified, one of the following payloads will be sent in response.

  1. WebhookDocument Uploading Event

    After a document is uploaded, the webhook sends a notification indicating that the document is still in the processing queue. This response confirms that the upload was successful, but the document has not yet completed processing. The message includes identifiers for tracking and a timestamp for reference.

    {
 "message": "Document is still in the queue",
 "status": 0,
 "institutionId": "inst-45678",
 "documentId": "doc-12345",
 "timestamp": "2025-05-28T12:34:56Z"
}

  2. WebhookDocument Processing Start Event

    Once the document enters the processing phase, the webhook sends a notification indicating that the document is now being processed. This marks the start of the document's processing stage, confirming that the system has begun working on it.

    {
 "message": "Document is processing",
 "status": -1,
 "institutionId": "inst-45678",
 "documentId": "doc-12345",
 "timestamp": "2025-05-28T12:34:56Z"
}

  3. WebhookDocument Processing Completion Event

    When a document completes its journey through the processing pipeline, the webhook sends a final notification indicating that all analysis is complete and results are available. This notification confirms that the document has been fully processed and is ready for viewing or further action. It includes similarity metrics, originality score, and several integrity checks to help assess the document's content.

    {
 "message": "Document is processed",
 "status": 1,
 "similarity": "78.4%",
 "translation_similarity": "65.2%",
 "ai_index": "42.7%",
 "institutionId": "inst-45678",
 "documentId": "doc-12345",
 "timestamp": "2025-05-28T12:45:00Z",
 "originality": "High Risk",
 "characterReplacement": 3,
 "hiddenText": 0,
 "imageAsText": 2
}

  4. WebhookDocument Change

    If a professor or evaluator modifies the report after it has been processed, the webhook sends a notification to indicate that the document now contains updated values. This event signals that changes were made to the original analysis, and the current report may differ from the initially processed results.

    {
 "message": "Document had some changes",
 "status": 3,
 "similarity": "74.9%",
 "translation_similarity": "62.1%",
 "ai_index": "38.5%",
 "institutionId": "inst-45678",
 "documentId": "doc-12345",
 "timestamp": "2025-05-28T13:10:00Z",
 "originality": "Medium",
 "characterReplacement": 1,
 "hiddenText": 0,
 "imageAsText": 1
}

  5. WebhookDocument Processing Failure

    In the event of a processing failure, the webhook functions as an alert mechanism, notifying the system that an error occurred while handling the document. This message indicates that the document could not be fully processed and may require manual review or technical support.

    {
 "message": "Something went wrong, please report this",
 "status": 2,
 "institutionId": "inst-45678",
 "documentId": "doc-12345",
 "timestamp": "2025-05-28T13:25:00Z"
}

  6. WebhookDocument Processing Failure

    In the event of a processing failure, the webhook functions as an alert mechanism, notifying the system that an error occurred while handling the document. This message indicates that the document could not be fully processed and may require manual review or technical support.

    {
 "message": "Something went wrong, please report this",
 "status": 2,
 "institutionId": "inst-45678",
 "documentId": "doc-12345",
 "timestamp": "2025-05-28T13:25:00Z"
}

Was this article helpful?

0 out of 0 found this helpful