Content

1. Environments

The URL and API calls throughout this document begin with the {{BASE_URL}}, representing the base URL to which the API calls are sent.

Keep in mind that Inspera Originality operates in two environments: development and production, hence the need to replace the {{BASE_URL}} with the correct corresponding URL based on API usage needs.

The URL for making an API call to {{BASE_URL}}/generateToken using the development environment is:  https://mderh1sy0b.execute-api.eu-central-1.amazonaws.com/development/generateToken

1.1 Development environment

You can use this environment for testing and development purposes. It may have different rate limits and data sets compared to the production environment.

Development Environment URL:

https://mderh1sy0b.execute-api.eu-central1.amazonaws.com/development

1.2 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.

Production Environment URL

https://154i7j3up4.execute-api.eu-central-1.amazonaws.com/production

2. Authentication

2.1 HTTP request

This POST request enables receiving the token that will be sent to the remainder of the endpoints in the header section. It serves as a means to authenticate securely and use the API.

Type URL
POST {{BASE_URL}}/generateToken

 

2.2 Request parameters

The table below represents the required parameters that must be included in the request. The parameters have been categorized by their location (path or header), type, and mandatory status. Each parameter has its description for additional clarification.

Parameters Location Type Required  Description
clientid Body String Yes The clientId serves as a key to use the API. To obtain the clientId, it is necessary to contact Inspera.  
institutionid Body String Yes If the institution decides to archive the documents for collusion checking (similarities between students of the same university). This indicates that the document that is uploaded will be checked against the documents from the same institution as well.

 

2.3 Response

The response contains only the token field, which is a unique identifier used for authentication in the header section of all upcoming endpoint requests.

Field  Response
token {{token}}
expirationTime {{expirationTime}}

Note: The token expiration time is 24 hours after generation.

2.4 Possible errors

Here are the potential response codes that you may receive following the POST request.

Error Code Description
401 unauthorized The {{clientId}} is invalid
404 bad request Required fields were invalid

 

3. Document uploading 

3.1 HTTP request 

To begin the document similarity check, a POST request is required at the URL specified in the table below. This URL serves as the starting point for the system, allowing it to perform the necessary checks.

Type URL
POST {{BASE_URL}}/submissions

 

Since the token has an expiration time of 24 hours, make sure to generate one and include it in the following manner in your HTTP requests

Type Value
Authorization Bearer {{generatedToken}}
Content-Type application/json

 

3.2 Request parameters

The table below represents the required parameters that must be included in the request. The parameters have been categorized by their location (path or header), type, and mandatory status. Each parameter includes a description for further clarification.

Parameter Location Type Required Description
file Body Base64 Yes

The document that will be uploaded for similarity detection, converted to base64, and sent as follows: "base64, {{file as base64}}"


Note: If the process requires HTML content to be checked (i.e. content from text editors such as WYSIWYG), the file parameter should be sent as HTML content in the format of a string {{content as html}}

documentTitle Body String Yes The title of the document
author Body String Yes The author of the document
documentLanguage Body String Yes Original language of the document. The languages are named as the acronym of the
language (e.g. ‘en’, ‘es’, etc)
translated language Body String No Enabled if translation similarity detection is required. Languages are named after their acronym
assignmentId Body String No Represents the ID of the assignment
email Body String Yes The email of the student who uploaded the submission
institutionName Body String No Name of the institution the submission was uploaded from
enableAIDetection Body String No The AI detection capability is disabled by default. 
enableReferenceDetection Body String No By default, reference detection will be enabled
reSubmissions Body String No By default, the number of allowed resubmissions is 1
subjectId Body String No The ID of the subject the submission was uploaded for
thesisID Body String No The ID of the thesis the submission was uploaded for
minLimit Body String No By default, there is no minimum limit on the number of words in a document.
archive Body String No If the professor wants to archive this submission in our repository we can find
similarities (collusion) between student submissions. By default this is false
docType Body String Yes

Document type that is being uploaded.

Supported types: 

  • application/pdf (.pdf)
  • text/plain (.txt)- html
  • (plain HTML content)- word (.docx)

 

The codes displayed adjacent to each language are accepted for both the documentLanguage and translatedLanguage parameters.

English (en) Albanian (aq) German (de) Italian (it) Lithuanian (lt)
Spanish (es) Portuguese (pt) Czech (cz) Turkish (tr) Slovak (sk)
French (fr) Macedonian (mk) Polish (pl) Norwegian (no) Latvian (lv)
Greek (el) Dutch (nd) Russian (ru) Bulgarian (bg) Hungarian (hu)
Romanian (ro) Serbian (sr) Swedish (sv) Finish (fi) Croatian (hr)

 

3.3 Response

Once the upload is finished, the response will contain two essential fields:

  • message - This field will convey whether the document upload was successful or if any errors occurred during the process.
  • documentId - This unique identifier represents the document itself and can be utilized for any future reference or necessary actions.
Field Response
message “Your document is uploaded successfully”
documentId {{documentId}}

Note:  If the document uploading process fails, the response will not include a documentId but rather return an error message indicating that something went wrong.

3.4 Possible errors

Here are the potential response codes that you may receive following the POST request.

Error code  Description
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 less than the allowed minimum
  • Document structure is invalid
400 bad request The required fields are invalid

 

4. Document status check (Poll-setup)

4.1 HTTP request

To verify a document’s status, use the GET API listed below, providing the documentId (obtained from the previous endpoint) as a path parameter. Please note that this is a manual procedure, requiring a GET API request to obtain the document’s status

Type URL
GET {{BASE_URL}}/document/{{documentId}}/checkStatus

 

4.2 Request parameters

Only one parameter is required for this request:

  • documentId - Represents the submission ID that was returned from the document that
    was uploaded initially in the assignment endpoint
Parameter Location Type Required Description
documentId Path String Yes The submission ID that was returned from the upload assignment endpoint

 

4.3 Response

The response entails 6 fields that contain vital information on the originality of the document.

Field  Response
Message “Document is processed”

Status

{value}%
translation_similarity {value}%
AI_index {value}%
originality {{originality}}
  • Message - Represents that message that describes the status of the document
  • Status - Represents the state of the document using IDs where:
      • 1 indicates that the document is being processed
      • 0 indicates that the document is in the queue
      • 2 indicates that an error occurred during the process
  • Similarity - Represents the similarity in the original language (e.g. English English) and is presented as a percentage
  • translation_similarity - Represents the similarity in cross-language (e.g. English-Spanish) and is presented as a percentage
  • AI_index - Represents the probability of the text being AI generated and is presented as a percentage
  • Originality - Represents the originality level of the document in a written form for an easier display option. The value will be a string of either High risk, Medium risk, or Low risk.
      • High risk indicates low document originality, with at least one of the checks displaying a high score
      • Medium risk indicates moderate document originality, medium scores of original language similarity, translation language similarity, and AI authorship
      • Low risk indicates high document originality, with low scores of original language similarity, translation language similarity, and AI authorship

 

4.4 Possible errors

Here are the potential response codes that you may receive following the POST request.

Error code Description
400 Bad request
401 Token has expired
403 Forbidden
404 Submission not found

 

5. Get report URL

5.1 HTTP request

This action triggers the Originality Report API, sending data such as the documentId and the mode. The API will then respond by providing a URL that can be embedded in an iframe to display the report.

Type URL
GET {{BASE_URL}}/document/{{documentId}}/mode/{{mode}}

 

5.2 Request parameters

A total of three parameters are necessary for this endpoint.

Parameters

Location

Type

Required

Description

documentId Path String Yes The submission ID that was returned from the upload assignment endpoint.
clientId Path String Yes Unique client ID
mode Path String Yes Will render the report privileges based on the mode - either “view” that can only be viewable and“edit” that can be editable
  • documentId - Represents the particular submission where the request was made.
  • clientId - Represents the unique ID generated by Inspera for an institution
  • mode - Specifies how the report is rendered depending on privileges. The report is rendered
    differently for students (view mode) and professors (edit mode)

5.3 Response

The response will simply include a URL that can be easily integrated into an iframe tag.

Field Response
URL {{url}}

 

5.4 Possible errors

Here are the potential response codes that you may receive following the POST request

Field Response
400 Bad request
401 Token has expired
403 Forbidden
404 Submission not found

 

6. Document status check (Webhooks)

Webhooks enable institutions to communicate with Inspera Originality regarding the document processing status. 

6.1 Document upload event

Once the document has been uploaded, the webhook sends a notification to confirm that the document has been successfully uploaded to the platform and is ready for further processing.

Field Response
message Document is still in the queue
status 0
institutionId {{institutionId}}
documentId {{documentId}}
timestamp {{timestamp}}

 

6.2 Document processing start event

When the document enters the processing phase, the webhooks will promptly send a notification. This notification marks the beginning of the document processing phase, serving as a clear indication that the system has begun working on the document.

Field Response
message Document is processing
status -1
institutionId {{institutionId}}
documentId {{documentId}}
timestamp {{timestamp}}

 

6.3 Document processing completion event 

As the document goes through the processing pipeline and reaches its final state, the webhooks deliver a notification to ensure that the results are ready to be displayed. This notification marks the completion of the document processing journey, indicating that the document has been processed and is ready for use.

Field Value
message Document is processed
status 1
similarity {{percentage}}
translation_similarity {{percentage}}
AI_index {{percentage}}
institutionId {{institutionId}}
documentId {{documentId}}
timestamp {{timestamp}}
originality {{originality}}

 

6.4 Document changes

Should the professor/evaluator make changes in the report, the webhook will be triggered to notify the system that there are different values from the initial report.

Field Value
message Document had some changes
status 3
similarity {{percentage}}
translation_similarity {{percentage}}
AI_index {{percentage}}
institutionId {{institutionId}}
documentId {{documentId}}
timestamp {{timestamp}}
originality {{originality}}

 

6.5 Document processing failure event

In the event of a processing failure, the webhooks act as an alert system, triggering a notification and informing that an issue occurred during the document processing.

Field Value
message Something went wrong, please report this
status 2
institutionId {{institutionId}}
documentId {{documentId}}
timestamp {{timestamp}}

Articles in this section

Was this article helpful?
0 out of 0 found this helpful