Увійти

Увійти

ІндивідуальнийШколам та УніверситетамІндивідуальний+

Потрібен профіль у Unicheck?  Sign up here

Unicheck API Overview

Welcome to the Unicheck API

Unicheck API is built to allow you to create an integration quickly and easily.

It's organized around REST. If you've interacted with a RESTful API already, many of the concepts will be familiar to you.

You must be registered as Unicheck user and have an active application. Base URL for API requests is https://api.unicheck.com.

API provides methods for interacting with the following system entities:

  • Files
    • Upload
    • Get information about
    • Delete
  • Similarity checks
    • Create
    • Get information about
    • Report export
    • Download exported content
  • User
    • Get information about
    • Get balance
  • Webhooks
    • Get information about
  • Jobs
    • Get information about

Schemas and Serialization

Requests

Data resources are accessed via standard HTTPS requests in UTF-8 format to API endpoint.

Methods

HTTP Method Description
GET Requests data from a resource
POST Submits data to a resource to process
PUT/PATH Updates a resource
DELETE Deletes a resource

Base URL

Base URL for API requests is

https://api.unicheck.com

For example, url to similarity check data is

https://api.unicheck.com/similarity/checks/{uuid}

Headers

These headers are required to make a successful request:

Header Description
Accept Must be application/vnd.api+json, since Unicheck leverage JSON API specification
Authorization Should be Bearer <access_token>. See Authorization and Authentication for more info
Content-Type Only for requests, that have body. Usually it's application/vnd.api+json or multipart/form-data

Rate Limiting

Rate Limiting enables Web API to share access bandwidth to its resources equally across all users.

Rate limiting is applied as per application, and regardless of the number of users who use the application simultaneously.

Header Description
X-Rate-Limit-Limit The rate limit ceiling for that given endpoint
X-Rate-Limit-Remaining The number of requests left for the time window
X-Rate-Limit-Reset The remaining window before the rate limit resets, in UTC Epoch seconds

Schemas

All API responses and some of the requests data are JSON API compatible.

Most of API calls return JSON response body that include information about the resource and one or more contextual HATEOAS links. Use these links to request more information about and construct an API flow that is relative to a specific request.

Visit JSON API web-site for more information. There are a lot of ready-to-use implementations: http://jsonapi.org/implementations.

Response status codes

HTTP Code Description
200 OK - Request succeeded. Сlient can read the result of it in the body and the headers of response.
202 Accepted - Request is accepted for processing, but the processing has not been completed. Usually webhooks should be handled to track that job is done.
401 Unauthorized - Request requires user authentication or, if the request includes authorization credentials, authorization is refused for those credentials.
403 Forbidden - The server accepted the request, but is refusing to fulfill it.
404 Not Found - The requested resource could not be found.
424 Failed Dependency - The request failed because it depended on another one. Usually it means resource is not ready yet.
429 Too Many Requests - Rate limiting has been applied.

Authorization and Authentication

Unicheck REST API uses OAuth 2.0 protocol to authorize calls. OAuth is an open standard that many companies use to provide secure access to protected resources.

When you create an app, Unicheck generates a set of OAuth client ID and secret credentials. You pass these credentials in the Authorization header in a get access token request.

In exchange for these credentials, Unicheck authorization server issues access tokens called bearer tokens that you use for authorization when making REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner.

The access_token field in the get access token response contains a bearer token, indicated by the token_type of Bearer:

Get access token

curl -X POST \
    https://api.unicheck.com/oauth/access-token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=<grant_type>&client_id=<client_id>&client_secret=<client_secret>'

Where:

Parameter Description
client_id Your application client ID.
client_secret Your application secret.
grant_type The grant type. Set it to client_credentials.

Access token

{
    "token_type": "Bearer",
    "expires_in": 2678400,
    "access_token": "<access_token>"
}

Include this bearer token in API requests in the Authorization header with the Bearer authentication scheme.

This sample request uses a bearer token to get user balance:

curl -X GET \
    https://api.unicheck.com/users/me/balance \
    -H 'Accept: application/vnd.api+json' \
    -H 'Authorization: Bearer Access-Token'

Access tokens have a limited lifetime. The expires_in field in the get access token response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600 indicates that the access token expires in one hour from the time the response was generated.

To detect when an access token expires, write code to either:

  • Keep track of the expires_in value in the token response. The value is expressed in seconds.
  • Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.

Before you create another token, re-use the access token until it expires.

Webhooks

Webhooks are HTTP callbacks that receive notification messages for events. To create a webhook in Unicheck, developers configure a webhook listener and subscribe it to events. A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. Unicheck signs each notification message that it delivers to your webhook listener.

Jobs

Jobs are resources that contain information about a background operation (an operation that is not instantaneous). Each work is performed on a scenario with tracking progress. Contains metadata associated with a specific work scenario.

See References for endpoint description.

Examples

Get access token

Request:

curl -X POST \
    https://api.unicheck.com/oauth/access-token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=<grant_type>&client_id=<client_id>&client_secret=<secret>'

Response:

HTTP/1.1 200 OK

{
    "token_type": "Bearer",
    "expires_in": 2678400,
    "access_token": "a lot of strange characters"
}

Use the access token you got instead of <access_token> in the following requests.

Upload file

Request:

curl -X POST \
    "https://api.unicheck.com/files" \
    -H "Accept: application/vnd.api+json" \
    -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: multipart/form-data" -F "file=@path-to-file.pdf"

Response:

HTTP/1.1 202 Accepted

{
    "jsonapi": {
        "version": "1.0"
    },
    "data": {
        "type": "file",
        "id": "552a7c93190d4b99a799a29fae494c26",
        "attributes": {
            "name": "my-file",
            "extension": "pdf",
            "state": "prepared",
            "words_count": 0,
            "pages_count": 0,
            "size": 0,
            "preview": null,
            "fileType": "library",
            "created_at": "2018-04-24T09:58:45+00:00",
            "updated_at": "2018-04-24T09:58:45+00:00"
        },
        "links": {
            "self": "https://api.unicheck.com/files/552a7c93190d4b99a799a29fae494c26"
        }
    }
}

Use the file ID you got instead of <file_id> in the following requests.

Keep in mind that file processing takes some time and can't be viewed at this step. Also it's possible that processing will fail (use webhooks to get notified).

But you can start a similarity check for this file even if it's being processed, Unicheck will deal with everything else.

Start similarity check

Request:

curl -X POST \
    "https://api.unicheck.com/similarity/checks" \
    -H "Accept: application/vnd.api+json" \
    -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/vnd.api+json" \
    -d "{ \"data\": { \"type\": \"similarityCheck\", \"attributes\": { \"search_types\": { \"web\":true, \"library\": false }, \"parameters\": { \"sensitivity\": { \"percentage\": 0, \"words_count\": 8 } } } }, \"relationships\": { \"file\": { \"data\": { \"id\": \"<file_id>\", \"type\": \"file\" } } }}"

Response:

HTTP/1.1 202 Accepted

{
    "jsonapi": {
        "version": "1.0"
    },
    "data": {
        "type": "similarity_check",
        "id": "196f206f1bca4150acbd7c4fb3db7174",
        "attributes": {
            "state": "created",
            "similarity": 0,
            "search_types": ["web"],
            "parameters": {
                "sensitivity": {
                    "percentage": 0,
                    "words_count": 8
                }
            },
            "checked_at": "2018-12-14T14:41:41+00:00",
            "created_at": "2018-04-24T10:10:08+00:00",
            "updated_at": "2018-04-24T10:10:08+00:00"
        },
        "links": {
            "self": "https://api.unicheck.com/similarity/checks/196f206f1bca4150acbd7c4fb3db7174"
        },
        "meta": {
            "exclude": {
                "citations": true,
                "references": true,
                "citations_percentage": null,
                "references_percentage": null,
                "source_count": 0,
                "citations_count": 0,
                "references_count": 0,
                "total_percentage": 0
            },
            "originality": {
                "sources_count": 0
            },
            "cost": null
        }
    }
}

Use the similarity check ID you got instead of <similarity_check_id> in the following requests.

At this moment Unicheck will do some magic to find similarities for you. It will take some time.

You should leverage webhooks or use Jobs to track similarity check progress.

Handle Webhook

If you set up webhooks for your application after checking the file for similarity, you’ll get a webhook:

{
    "data": {
        "type": "webhook_event",
        "id": "ef8ad9e6772c41aa86b0b0a9e8411f2a",
        "attributes": {
            "resource_id": "196f206f1bca4150acbd7c4fb3db7174",
            "resource_type": "similarity_check",
            "event_type": "similarity_check_finished",
            "delivery_status": "sending",
            "delivery_attempts": 1,
            "created_at": "2018-04-24T10:11:53+00:00"
        },
        "relationships": {
            "similarity_check": {
                "data": {
                    "type": "similarity_check",
                    "id": "196f206f1bca4150acbd7c4fb3db7174"
                }
            }
        },
        "links": {
            "self": "https://api.unicheck.com/notifications/webhooks/ef8ad9e6772c41aa86b0b0a9e8411f2a"
        }
    },
    "included": [
        {
            "type": "similarity_check",
            "id": "<similarity_check_id>",
            "attributes": {
                "state": "built",
                "similarity": 99.47,
                "search_types": ["web"],
                "parameters": {
                    "sensitivity": {
                        "percentage": 0,
                        "words_count": 8
                    }
                },
                "created_at": "2018-04-24T10:10:08+00:00",
                "updated_at": "2018-04-24T10:10:08+00:00"
            },
            "links": {
                "self": "https://api.unicheck.com/similarity/checks/196f206f1bca4150acbd7c4fb3db7174"
            }
        }
    ]
}

Similarity check result

Request:

curl -X GET \
    "https://api.unicheck.com/similarity/checks/<similarity_check_id>" \
    -H "accept: application/vnd.api+json" \
    -H "authorization: Bearer <access_token>"

Response:

HTTP/1.1 200 OK

{
    "jsonapi": {
        "version": "1.0"
    },
    "data": {
        "type": "similarity_check",
        "id": "<similarity_check_id>",
        "attributes": {
            "state": "built",
            "similarity": 99.47,
            "search_types": ["web"],
            "parameters": {
                "sensitivity": {
                    "percentage": 0,
                    "words_count": 8
                }
            },
            "created_at": "2018-04-24T10:10:08+00:00",
            "updated_at": "2018-04-24T10:10:08+00:00"
        },
        "links": {
            "self": "https://api.unicheck.com/similarity/checks/196f206f1bca4150acbd7c4fb3db7174"
        },
        "meta": {
            "exclude": {
                "citations": true,
                "references": true,
                "citations_percentage": 0,
                "references_percentage": 0,
                "source_count": 0,
                "citations_count": 0,
                "references_count": 0,
                "total_percentage": 0
            },
            "originality": {
                "sources_count": 51
            },
            "cost": {
                "value": 5,
                "resource_type": "page"
            }
        }
    }
}

It's possible to call this endpoint regardless of is check in progress or finished. You can use ?include=job parameter to track check progress.

Similarity check report export

The example shows how to export similarity check result as file. Supported format: PDF

Export report for finished similarity check

Request:

curl -X POST \
  https://api.unicheck.com/similarity/checks/<similarity_check_id>/report/export \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
        "type" :"similarity-check-report-export",
        "attributes":{
            "format" :"pdf",
            "locale_code" :"EN"
        }
    }
}'

Response:

HTTP/1.1 202 Accepted

{
    "jsonapi": {
        "version": "1.0"
    },
    "data": {
        "type": "job",
        "id": "<job_id>",
        "attributes": {
            "progress": 0,
            "scenario": "pdf.report.generate",
            "created_at": "2018-12-14T14:34:57+00:00",
            "updated_at": "2018-12-14T14:34:57+00:00"
        },
        "links": {
            "self": "https://api.unicheck/jobs/<job_id>"
        },
        "meta": {
            "similarity_check_id": "<similarity_check_id>",
            "file_id": "<file_id>"
        }
    }
}

You should leverage webhooks or use Jobs to track similarity check report export progress. Once export job is finished, you'll find pdf_report link inside links object.

Example Job (finished export)

Request:

curl -X GET \
  https://api.unicheck.com/jobs/<report_export_job_id> \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <access_token>'

Response:

HTTP/1.1 200 OK

{
    "jsonapi": {
        "version": "1.0"
    },
    "data": {
        "type": "job",
        "id": "<report_export_job_id>",
        "attributes": {
            "progress": 100,
            "scenario": "pdf.report.generate",
            "created_at": "2018-12-14T14:34:57+00:00",
            "updated_at": "2018-12-14T14:35:05+00:00"
        },
        "links": {
            "self": "https://api.unicheck.com/jobs/1766803",
            "pdf_report": "https://api.unicheck.com/similarity/checks/<similarity_check_id>/report/export/report_export_job_id"
        },
        "meta": {
            "file_id": "<file_id>",
            "similarity_check_id": "<similarity_check_id>"
        }
    }
}

The job contains a link to download exported content.

Similarity check report download exported content

To download check result as file using link provided in job you should include access token in request header.

Request:

curl -X GET \
  https://api.unicheck.com/similarity/checks/<similarity_check_id>/report/export/<report_export_job_id> \
  -H 'Authorization: Bearer <access_token>'

Response:

HTTP/1.1 200 OK Content application/pdf

Export report during Similarity check start

It's also possible to queue export job during similarity check start. Unicheck will start exporting report once check is finished. Both jobs (check itself and report export) provided to track progress.
You should leverage webhooks or use Jobs to track similarity check report export progress.

Request:

curl -X POST \
  'https://api.unicheck.com/similarity/checks?include=jobs' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "similarityCheck",
    "attributes": {
      "parameters": {
        "export": {
            "format": "pdf",
            "locale_code" : "EN"
        }
      }
    }
  },
  "relationships": {
    "file": {
      "data": {
        "id": "<file_id>",
        "type": "file"
      }
    }
  }
}'

Response:

HTTP/1.1 202 Accepted

{
    "jsonapi": {
        "version": "1.0"
    },
    "data": {
        "type": "similarity_check",
        "id": "<similarity_check_id>",
        "attributes": {
            "state": "created",
            "similarity": 0,
            "search_types": ["library", "web"],
            "parameters": {
                "sensitivity": {
                    "percentage": 0,
                    "words_count": 8
                }
            },
            "checked_at": null,
            "created_at": "2018-12-14T14:40:49+00:00",
            "updated_at": "2018-12-14T14:40:49+00:00"
        },
        "relationships": {
            "jobs": {
                "data": [
                    {
                        "type": "job",
                        "id": "<similarity_check_job_id>"
                    },
                    {
                        "type": "job",
                        "id": "<report_export_job_id>"
                    }
                ]
            }
        },
        "links": {
            "self": "https://api.un77.mytheverona.com/similarity/checks/7dcaab8fc9574e89b63b2851eb2e40af"
        },
        "meta": {
            "exclude": {
                "citations": true,
                "references": true,
                "citations_percentage": null,
                "references_percentage": null,
                "source_count": 0,
                "citations_count": 0,
                "references_count": 0,
                "total_percentage": 0
            },
            "originality": {
                "sources_count": 0
            },
            "cost": null
        }
    },
    "included": [
        {
            "type": "job",
            "id": "<similarity_check_job_id>",
            "attributes": {
                "progress": 0,
                "scenario": "similarity.check",
                "created_at": "2018-12-14T14:40:49+00:00",
                "updated_at": "2018-12-14T14:40:49+00:00"
            },
            "links": {
                "self": "https://api.unicheck.com/jobs/<similarity_check_job_id>"
            }
        },
        {
            "type": "job",
            "id": "<report_export_job_id>",
            "attributes": {
                "progress": 0,
                "scenario": "pdf.report.generate",
                "created_at": "2018-12-14T14:40:49+00:00",
                "updated_at": "2018-12-14T14:40:49+00:00"
            },
            "links": {
                "self": "https://api.unicheck.com/jobs/<report_export_job_id>"
            }
        }
    ]
}

References

Visit auto-generated documentation by Swagger to find more details or test our API. https://api.unicheck.com/documentation