Content
- 1. Environments
- 2. Authentication
- 3. Document uploading
- 4. Document status check (Poll-setup)
- 5. Get report URL
- 6. Document status check (Webhooks)
-
7. CRUD Operations APIs
- 7.1 Authorization
- 7.2 Create Operations
-
7.3 Read Operations
- 7.3.1 Retrieve by Email
- 7.3.2 Retrieve with Pagination
-
7.3.3 Retrieve with Pagination (Custom List)
- 7.3.3.1 HTTP Request
- 7.3.3.2 Request Parameters
- 7.3.3.3 Response
- 7.3.3.4 Possible Errors
- 7.4 Update Operations
- 7.5 Delete Operations
- 7.6 Course Details
- 7.7 Institution faculties and departments with relations
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}}"
|
| 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 |
| 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 include: Document typethat isbeinguploaded. Supportedtypes: ● application/pdforpdf (.pdf files) ● text/plainor.txt(.txt files) ● text/htmlorhtml (.html files) ● application/xml or xml (.xml files) ● application/msword, application/doc, application/ms-doc, or doc (.doc files) ● application/vnd.openx mlformats-officedocum ent.wordprocessingml. document, word, docx, or doc/docx (.docx files) ● application/vnd.oasis. opendocument.text or odt (.odt files) ● application/rtf or rtf (.rtf files) ● application/wordperfec t or wpd (.wpd files) ● application/postscript or ps (.ps files) ● application/x-hwp or hwp (.hwp files) ● application/vnd.apple. pages or pages (.pages files) ● application/vnd.ms-po werpoint, application/mspowerp oint, application/powerpoint , application/x-mspower point, or ppt (.ppt files) ● application/vnd.openx mlformats-officedocum ent.presentationml.pre sentation or pptx (.pptx files) ● application/vnd.openx mlformats-officedocum ent.presentationml.slid eshow or ppsx (.ppsx files) ● application/vnd.oasis. opendocument.presen tationorodp(.odp files) ● application/vnd.apple. keynoteorkey(.key files) ● application/vnd.ms-ex cel,application/excel, application/x-excel, application/x-msexcel, orxls(.xlsfiles) ● application/vnd.openx mlformats-officedocum ent.spreadsheetml.sh eetorxlsx(.xlsxfiles) ● application/vnd.oasis. opendocument.spread sheetorods(.ods files) ● application/vnd.apple. numbersornumbers (.numbersfiles) ● application/jsonor json(.jsonfiles) ● text/csvorcsv(.csv files) ● text/markdownormd (.mdfiles) |
The codes displayed adjacent to each language are accepted for both the documentLanguage and translatedLanguage parameters.
| English (en) | Albanian (sq) | 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.
presignedS3Url - This is the URL that is generated where the documents have to be uploaded.
| Field | Response |
| message | “Your document is uploaded successfully” |
| documentId | {{documentId}} |
| presignedS3Url | {{presignedS3Url}} |
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 |
3.5 Upload document in resigned URL
| Parameters | Location | Type | Required | Description |
| {{presignedS3Url}} | Body | String | Yes | The presignedurl |
| file | Body | String | Yes | File to upload |
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}% |
|
Similarity |
{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}} |
7. CRUD Operations
7.1 Authorization
7.1.1 HTTP Request
| Type | URL |
| POST | {{baseURL}}/token |
7.1.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| Body | String | Yes | Email of the user needed for authentication purposes | |
| password | Body | String | Yes | Password of the user needed for authentication purposes |
7.1.3 Response
| Field | Response |
| token | {{token}} |
7.1.4 Possible Errors
| Error Code | Description |
| 404 | User not found |
| 409 | Invalid email format |
| 422 | Invalid credentials |
| 500 | Server Error |
7.2 Create Operations
Note: The bearer token should be inserted into the authorization header for the APIs listed below
7.2.1 HTTP Request
| Type | URL |
| POST | {{baseURL}}/user |
7.2.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| firstName | Body | String | Yes | first name of the user |
| lastName | Body | String | Yes | last name of the user |
| Body | String | Yes | email of the user | |
| role | Body | Educator/Student | Yes | Role of the user - whether the user will be a student or an educator/evaluator. |
| courses | Body |
Array with strings of codes
|
Optional | Courses where the user will be enrolled in. |
7.2.3 Response
| Field | Response |
| id | {{id}} |
| name | {{name}} |
| {{email}} | |
| status | {{status}} |
| createdAt | {{createdAt}} |
| updatedAt | {{updatedAt}} |
| institutionId | {{institutionId}} |
| departmentId | {{departmentId}} |
| facultyId | {{facultyId}} |
| lastLogin | n/a |
| isDeleted | {{true/false}} |
7.2.4 Possible Errors
| Error Codes | Description |
| 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 |
7.3 Read Operations
7.3.1 Retrieve by Email
7.3.1.1 HTTP Request
| Type | URL |
| GET | {{baseURL}}/user-info?email={{userEmail}} |
7.3.1.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| Query Parameters | String | Yes | Email of the user you wish to read information about. |
7.3.1.3 Response
| Field | Response |
| id | {{id}} |
| name | {{name}} |
| {{email}} | |
| status | {{status}} |
| createdAt | {{createdAt}} |
| updatedAt | {{updatedAt}} |
| institutionId | {{institutionId}} |
| departmentId | {{departmentId}} |
| facultyId | {{facultyId}} |
| lastLogin | {{lastLogin}} |
| isDeleted | {{true/false}} |
| roleId | {{roleId}} |
| role | {{role}} |
7.3.1.4 Possible Errors
| Error Code | Description |
| 401 | User not authorized to take action |
| 404 | User not found |
| 403 | User not authorized to access data from different institution |
| 500 | Server error |
7.3.2 Retrieve with pagination
7.3.2.1 HTTP Request
| Type | URL |
| GET | {{baseURL}}/user-info?page={{pageNumber}} |
7.3.2.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| Page | Query Parameters | String | Yes | The current page in the pagination array |
7.3.2.3 Response
| Field | Response |
| total | {{totalUsers}} |
| page | {{currentPage}} |
| limit | {{pageLimit}} |
| pages | {{totalPages}} |
7.3.2.4 Possible Errors
| Error Codes | Description |
| 401 | User not authorized to take action |
| 500 | Server Error |
7.3.3 Retrieve with pagination (custom limit)
7.3.3.1 HTTP Request
| Type | URL |
| GET | {{baseURL}}/user-info?page={{pageNumeber}}&limit={{pageLimit}} |
7.3.3.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| Page | Query Parameters | String | Yes | The current page in the pagination array |
| Limit | Query Parameters | String | Yes | The limit of the pagination. The pagination will not continue below this number |
7.3.3.3 Response
| Field | Response |
| total | {{totalUsers}} |
| page | {{currentPage}} |
| limit | {{pageLimit}} |
| pages | {{totalPages}} |
7.3.3.4 Possible Errors
| Error Codes | Description |
| 401 | User not authorized to take action |
| 500 | Server error |
7.4 Update Operations
7.4.1 Update Educator
7.4.1.1 HTTP Request
| Type | URL |
| PUT | {{baseURL}}/user-info?userId={{userId}} |
7.4.1.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| firstName | Body | String | Yes | New name of the educator |
| lastName | Body | String | Yes | New last name of the educator |
| userSubjects | Body | String | Yes | Updated list of the subjects that the educator will be part of |
7.4.1.3 Response
| Field | Response |
| message | User updates successfully |
| firstName | {{firstName}} |
| lastName | {{lastName}} |
| userSubjects | {{subjectCode,..}} |
7.4.1.4 Possible Errors
| Error Codes | Description |
| 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 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.4.2 Update Student
7.4.2.1 HTTP Request
| Type | URL |
| PUT | {{baseURL}}/user-info?userId={{userId}} |
7.4.2.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| firstName | Body | String | Yes | New name of the student |
| lastName | Body | String | Yes | New last name of the student |
| status | Body | String | Yes | The status of the student |
| Body | String | Yes | The new email of the student |
7.4.2.3 Response
| Field | Response |
| message | User updates successfully |
| fristName | {{firstName}} |
| lastName | {{lastName}} |
| status | {{status}} |
| {{email}} |
7.4.2.4 Possible Errors
| Error Codes | Description |
| 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 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.5 Delete Operations
7.5.1 HTTP Request
| Type | URL |
| DELETE | {{baseURL}}/userId={{userId}} |
7.5.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| userId | Query Parameters | String | Yes | The identification number of the user that will be deleted |
7.5.3 Response
| Field | Response |
| message | User deleted successfully |
7.5.4 Possible Error
| Error Codes | Description |
| 401 | Not authorized to take action |
| 403 | Not authorized to delete user from different institution |
| 404 | User not found |
| 500 | Server error |
7.6 Course Details
7.6.1 Course Details with Pagination
7.6.1.1 HTTP Request
| Type | URL |
| GET | {{baseURL}}/courses-info?page={{pageNumber}}&limit={{pageLimit}} |
7.6.1.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| page | Query Parameters | String | Yes | The current page in the pagination array |
| limit | Query Parameters | String | Yes | The limit of the pagination. The pagination will not continue below this number. |
7.6.1.3 Response
| Field | Response |
| page | {{page}} |
| pages | {{pages}} |
| total | {{total}} |
| limit | {{limit}} |
7.6.1.4 Possible Errors
| Error Codes | Description |
| 500 | Server Error |
7.6.2 Course Details with Course Code
7.6.2.1 HTTP Request
| Type | URL |
| GET | {{baseURL}}/courses-info?courseCode={{courseCode}} |
7.6.2.2 Request Parameters
| Parameter | Location | Type | Required | Description |
| courseCode | Query Parameters | String | Yes | The identification code for this course. |
7.6.2.3 Response
| Field | Response |
| message | Course details successfully retrieved |
| id | {{id}} |
| title | {{courseTitle}} |
| description | {{courseDescription}} |
| departmentId | {{departmentId}} |
| year | {{year}} |
| code | {{courseCode}} |
| createdBy | {{userId}} |
| status | {{status}} |
| isDeleted | {{true/false}} |
| type | {{type}} |
| level | {{level}} |
| generation | {{generation}} |
| createdAt | {{createdAt}} |
| updatedAt | {{updatedAt}} |
7.6.2.4 Possible Errors
| Error Codes | Description |
| 404 | Course not found |
| 500 | Server Error |
7.7 Institution faculties and departments with relations
7.7.1 HTTP Request
| Type | URL |
| GET | {{baseURL}}/institution-info |
7.7.2 Possible Errors
| Error Code | Description |
| 500 | Server Error |