Originality API – Integration Guide

In this article, you will learn how to authenticate, send a document for a similarity check, retrieve report status and similarity score, link the assessor to the full report, search prior submissions, and delete documents.

What this article covers

1. Base URL, rate limits, and supported file formats
2. Authentication (OAuth 2.0 client credentials)
3. Sending a document for similarity check
4. Retrieving a document's status and report
5. Searching previously uploaded documents by context
6. Deleting a document
7. Quick reference

1. Base URL, rate limits, and supported file formats

Supported file formats

We recommend rejecting other formats and oversize files at your own boundary so you don't waste calls on guaranteed 415 or 413 errors.

2. Authentication (OAuth 2.0 client credentials)

Every API call requires a bearer token. Tokens are issued by exchanging your client_id and client_secret at POST https://api.wiseflow-originality.net/v1/oauth/token

Request body

Example

curl -X 'POST' \
  'https://api.wiseflow-originality.net/v1/oauth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=1234&client_secret=abcde&grant_type=client_credentials'

Response

{
  "access_token": "token",
  "expires_in": 300,
  "not-before-policy": 0,
  "refresh_expires_in": 0,
  "scope": "license_id profile email",
  "token_type": "Bearer"
}

Token-cache pattern

Cache the token in memory keyed by client_id and refresh proactively a minute before expiry.

3. Sending a document for similarity check

Endpoint – POST https://api.wiseflow-originality.net/v1/documents

Request body

Context validation rules

The context field is a string containing a JSON object, sent as a form field. The API enforces these constraints on the parsed object:

• All values must be strings (not numbers, booleans, or nested objects)
• Maximum 3 entries per object
• Each key is at most 20 characters
• Each value is at most 50 characters

A typical context for an exam-system integration:

Send it as a form field whose value is the JSON string above (i.e. JSON-encoded, then included in the form body).

The four combinations for document indexing and report generation

Request example

curl -X POST https://api.wiseflow-originality.net/v1/documents \
-H "Authorization: Bearer $TOKEN" \
-F "file=@thesis.pdf" \
-F "index=true" \
-F "analyze=true" \
-F 'context={"assignmentId":"234","studentId":"567"}'

Successful response (201 Created)

{
"documentId": 12345
}

Persist documentId against your own paper or assignment record. It is the only join key between your system and Originality for the rest of this document's life. The Location response header points to the new document resource.

4. Retrieving a document's status and report

Endpoint – GET https://api.wiseflow-originality.net/v1/documents/{id}

Response (200 OK)

{
  "context": {
    "assignmentId": "234"
  },
  "createdAt": "2024-01-01T12:00:00Z",
  "filename": "Assignment.pdf",
  "id": 12345,
  "reportOpened": false,
  "result": {
    "score": 0.98,
    "viewerLink": "https://example.com/viewer/12345"
  },
  "settings": {
    "analyze": true,
    "index": true
  },
  "status": "complete"
}

Field guide

Document statuses

Showing the score

result.score is a float between 0 and 1. Most UIs render it as a percentage. Always surface the status alongside the score:

Linking to the full report

The result.viewerLink is the link you give to assessors. Render it as a button or link in your assessor UI. The viewer presents the Originality report including the document, source comparison, and exclusion controls.

5. Searching previously uploaded documents by context

When you upload a document, the context object you set lets you batch-retrieve documents later — for example, ‘all submissions for this assignment.’ The search is exact-match on the context object.

Endpoint – POST https://api.wiseflow-originality.net/v1/documents/search?limit=100&offset=0

Query parameters

Request body

{
  "context": {
    "assignmentId": "234"
  }
}

The context object on search is an exact match against the context stored when the document was uploaded. Same validation rules apply: max 3 entries, keys ≤ 20 characters, values ≤ 50 characters, all string values.

Response (200 OK)

{
  "documents": [
    {
      "context": {
        "assignmentId": "234"
      },
      "createdAt": "2024-01-01T12:00:00Z",
      "filename": "Assignment.pdf",
      "id": 12345,
      "reportOpened": false,
      "result": {
        "score": 0.98,
        "viewerLink": "https://example.com/viewer/12345"
      },
      "settings": {
        "analyze": true,
        "index": true
      },
      "status": "complete"
    }
  ],
  "hasMore": true
}

hasMore is true when more documents exist past the current page — increment offset by limit until hasMore is false.

Useful patterns

• Per-assignment dashboard. Upload each submission with {"assignmentId": "<your id>", "studentId": "<your id>"}. Search by {"assignmentId": "<your id>"} to populate the assignment view.
• Per-student history. Search by {"studentId": "<your id>"} (note: the API matches the whole context object you submit; verify whether partial-key match is supported before relying on this).

6. Deleting a document

Endpoint – DELETE https://api.wiseflow-originality.net/v1/documents/{id}

Permanently removes the document — both its analysis data and its index entry. This cannot be undone.

Response (200 OK)

{
  "message": "Document with id 1 deleted successfully"
}

Use this endpoint to support participant data deletion requests in your own system. Deleting in your system alone does not remove the document from the Originality index — call this endpoint as part of the workflow.

Quick reference