Professional Documents
Culture Documents
Version 2.1.1
Copyright © 1998 – 2009 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 1
Contents
Introduction 4
Getting Started 5
Configuring the API From Your Admin Account 5
Calling the API 7
API Functions 11
Create user and login (fid=1) 11
Create class and assign the user as the instructor of the class (fid=2) 13
Join Class (fid=3) 17
Create Assignment (fid=4) 19
Submit Paper Function (fid=5) 24
Return Report Function (fid=6) 27
View/Download Submission (fid=7) 29
Delete Submission (fid=8) 31
Change Password (fid=9) 33
List Submissions (fid=10) 35
Check for Submission (fid=11) 38
Administrator Statistics (fid=12) 40
Return GradeMark Function (fid=13) 41
Report Turn Around Time (fid=14) 43
Submission Score (fid=15) 45
Anonymous Marking (fid=16) 46
Login Session (fid=17) 48
End a Session (fid=18) 49
Error Checking 50
Logging 51
Return Codes 51
Success States 51
Error States 52
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 2
Tables
FID/FCMD Error Code Table 59
FID/Data Elements Table 65
FID/MD5 Table 66
FID/Encrypt Data Table 67
GET/POST Requirements for Functions 68
Functions which Create User Profiles 70
Glossary 71
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 3
TurnitinUK API Manual Section: Introduction
Introduction
The TurnitinUK API allows you to access a variety of TurnitinUK actions in your own
native applications or scripts. It is a REST based API, therefore it can be implemented
in any language that allows for making https requests.
All API calls are made through one URL, https://submit.ac.uk/api.asp. The different
functionalities of the API are addressed by the function identification variable (fid).
Each function carries out a specific set of actions at TurnitinUK. All the different
functions have a core data requirement with each function potentially having
additional data requirements. Each API function typically has two or more types of
return methods that are controlled using the fcmd variable. One method which is
intended for student/instructor URL access, for example a school portal integration,
will log the user in after the successful execution of the API function. In the event of
an error the API will redirect the user to your callback error URL. The second method
is intended for back-end administrative programs, e.g. a batch auto-registration
program. This method can also be used for performing actions without being brought
to the TurnitinUK website. In this case, the API will return a status code to your
program in XML indicating whether the requested action was successful or resulted in
an error. If an error occurs, you can use the status code to determine the cause of the
action’s failure.
Security Measures
The API also has a number of security features built into it for the purposes of
authentication, encryption, and to prevent request tampering and misuse. We
authenticate all API requests by comparing information in the URL to information
stored in our authentication table. For further control, API requests can be locked
down to a specific IP address or a range of IP addresses. To ensure that all requests
are encrypted in transit, all API requests are required to be passed over an SSL
connection. To further enhance the level of encryption we also offer the option of
accepting encrypted data. To prevent URL misuse, we require that all API requests be
time stamped; all expired requests are rejected. Requests expire after 59 minutes.
To prevent URL tampering, we use a shared secret key between your institution and
TurnitinUK.
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 4
TurnitinUK API Manual Section: Getting Started
Getting Started
Before you can begin using the TurnitinUK API, you must configure your account in
TurnitinUK with a 8-digit alphanumeric shared key. This key will be used in calculating
an MD5 signature for all your API requests and to encrypt your data, if you choose to,
using Blowfish encryption. You can access this API administration page at TurnitinUK
by clicking the integrations icon next to your primary account. An error callback URL
and an IP address or range if you choose to use this security option must be provided.
Your TurnitinUK account administrator will need to make two changes to your
institution’s account in order to use the API. To make these changes, the
administrator needs to login to his or her account and click on the integrations icon
next to your school’s account.
Only the primary account needs to be updated; any sub-accounts that you
may have added do not need updating.
In the Open API configure box there are three fields to fill out for the API integration:
Create Your Own Shared Key, Your Institution’s IP Address, and the Error Callback
URL. Please provide a shared key which must be exactly 8 alphanumerical characters
in the Create Your Own Shared Key field.
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 5
TurnitinUK API Manual Section: Getting Started
In the Open API configure box, there are two fields for the API integration: the IP
address authentication and the callback URL for errors.
If you want to restrict connections to your account to users at your institution, enter
your institution’s IP address or IP range. If you do not want to restrict connections,
enter 255.255.255.255.
It is critical that you enter the correct IP address, as we will only accept API
calls from the IP address specified.
You will also be required to provide a callback URL for errors (for example, http://
www.yourdomain.edu/catch_turnitin_error.asp). The API will issue a redirect to this
URL if an error is encountered. The API will pass the callback URL two variables: ec
(the error code - see the section titled Error Codes for more information) and em (a
short error message). Using our previous example, a redirect call might look like this:
https://submit.ac.uk/api.error.asp
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 6
TurnitinUK API Manual Section: Calling the API
To call our API, information must be passed over an SSL connection as a URL.
The example below is an example of a GET request. For an example of a POST
request please view page 24.
https://submit.ac.uk/api.asp?gmtime=x&fid=x&fcmd=x&encrypt=x&md5=x&ai
d=x&said=x&diagnostic=x&uem=x&upw=x&ufn=x&uln=x&utp=x
The variable names sent in the URL to the TurnitinUK API are case insensitive
but the data values are case sensitive. All data sent in the URL must also be
properly escaped for proper URL syntax.
The encryption flag can be set to 0 (off) or 1 (on). If encryption is enabled, the
following user-sensitive data must be encrypted using your shared secret key
with the Blowfish encryption scheme:
said sub-account id
uem user email
upw user password
ufn user first name
uln user last name
utp user type
ctl class title (only applicable if fid=2 or 3)
cpw class enrollment password (only applicable if fid=2 or 3)
tem email of instructor who created the class (only applicable if fid=3)
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 7
TurnitinUK API Manual Section: Calling the API
The id of the account which is associated with your school’s TurnitinUK license.
The diagnostic flag can be set to 1 (on) or 0 (off). When testing the API, the
diagnostic flag should be enabled. Requests will be validated but not performed.
The user email is used as the TurnitinUK user name. The email address must be
6-50 characters in length.
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 8
TurnitinUK API Manual Section: Functions Specific Variables
The two function parameters, fid and fcmd, included in the URL sent to the API
determine the function the API will execute and the action that will be taken
afterward.
fid
The fid determines the function that the API will perform. Possible values for the fid
are:
1 - creates a user profile (if one does not exist) and logs the user in (instructor
or student)
16 - Anonymous Marking
18 - end a session
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 9
TurnitinUK API Manual Section: Functions Specific Variables
fcmd
The fcmd variable determines whether the user will be logged in after the requested
action. If the fcmd is set to 1, the action specified by the fid is performed and the
user is redirected to a URL. If the action fails, a code is returned to your institution’s
callback URL.
If the fcmd is set to 2, the action specified by the fid is performed and the user is not
logged in. Instead, a code is returned in XML format showing whether the action has
succeeded or failed (see section entitled Return Codes and Short Messages later in
this document for more information).
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 10
TurnitinUK API Manual Section: API Functions
API Functions
When a user is added successfully to an account, the default user type (student or
teacher) will be set to the utp as the default. A user who has already been created
and is in the database will already have their default utp number depending on their
user type (1 for student, 2 for an instructor). If the user is in the database:
utp=1 - The student must belong to a class that was created in the primary ac-
count or one of its children
utp=2 - The instructor must be joined to the primary account or one of its
children. If the instructor does not belong to the primary account or one of its
children, the upw must match and be verified for the existing user in order for
the instructor to be joined to the account
Logic
If upw (user password) is not set, a random user password will be created instead
in the case of user creation. The user can change this password using the “forgot
your password?” link on the TurnitinUK homepage, thereby allowing the user to log in
directly to TurnitinUK without the use of the API or through fid 9.
An email with passwords will be sent to the user if a new user was created and if the
dis flag is not set to 1.
If idsync is set to 1, the API will check to see if the uid is provided. If the uid is pro-
vided, it will ignore the idsync parameter. If uid is not set, then the API will check to
see if there is an existing user with the corresponding email. If the class exists and
has a corresponding uid, it will NOT change the uid. If the user exists and it doesn’t
have a corresponding uid, the uid will be set the TurnitinUK internal user ID. If the
user doesn’t exist, the user will be created and store the internal user ID as the uid.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid does not exist in our database but is included in the API call, the API will
use the included information and store the uid with the corresponding TurnitinUK user
id.
Success
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 11
TurnitinUK API Manual Section: API Functions
Failure
fcmd=1
Action on Success - The API creates user if the user does not already exist in the
database and logs the user in, redirecting the caller of the function to the appropriate
web page.
Action on Failure - The API redirects the user to the callback URL with an error code
and error message.
Return values - Success, logs the user into TurnitinUK via browser redirect. Failure,
redirects user to the callback URL
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=1&fcmd=1&encrypt=0&md5=0b83
fbd3be5ea56ac8bbaf026a6d6a23&aid=100&said=101&diagnostic=0&uem=john.doe@myschool.
edu&upw=john123&ufn=John%20II&uln=Doe&utp=2
fcmd=2
Action on Success - The API will return XML with success code an message
Action on Failure - The API will return XML with a corresponding error code and
error message
Return Values -
Success- XML <rcode>, <rmessage> <userid>
Failure- XML <rcode>, <rmessage>
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=1&fcmd=2&encrypt=0&md5=0b83
fbd3be5ea56ac8bbaf026a6d6a23&aid=100&said=101&diagnostic=0&uem=john.doe@myschool.
edu&upw=john123&ufn=John%20II&uln=Doe&utp=2
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 12
TurnitinUK API Manual Section: API Functions
Create class under the given account and assign the user
as the instructor of the class (fid=2)
Logic
The API will use the aid (account ID) or said (sub-account ID) if one is set. If the
user is in the database, the user must already be joined to the primary account or
one of its children.
A complication arises if an instructor’s class names remain the same from one
semester to another. The client is responsible for maintaining the uniqueness of the
class names. Possible strategies for maintaining uniqueness include: adding semester
and year information or the course identifier to the class title, or using the cid
parameter.
To change the instructor of a class (fcmd=4) enter the uem, utp, ctl. The user
entered into the uem must be the current instructor of the class to use this function.
The new teacher’s email for the class must already exist in our system and the user
must be joined to this account in order to successfully run this function.
If the cpw (class join password) is not set, a randomly generated password will be
used in its place. However, the randomly generated password may be changed from
within TurnitinUK.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
If idsync is set to 1, it will affect the user creation function (fid=1). If it is set, the
API will check to see if the cid is provided. If the cid is provided, it will ignore the
idsync parameter. If the cid is not set, then the API will check to see if there is an
existing class with the corresponding class title in the account. If the class exists and
has a corresponding cid, it will NOT change the cid. If the class exists and it doesn’t
have a corresponding cid, the cid will be set to the TurnitinUK internal class ID. If the
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 13
TurnitinUK API Manual Section: API Functions
class doesn’t exist, the class will be created and the API will store the internal class ID
as the cid.
If cid is set, the API will check to see if there is an existing match and use the
corresponding class id on the TurnitinUK side, ignoring uem, ctl. If the cid is not set,
the API will store the cid with the corresponding TurnitinUK class id.
If ced is set, the API will try to set the class end date to the value of ced, instead of
the default end date of 6 months.
Success
Failure
fcmd=1
Action on Success -
The API creates the user (as with fid=1, fcmd=2) if user is not already in data-
base.
The API creates a class with title ctl for that user if a class with the same title
has not already been created for that user in the specified account. Log the user
in if the operation was successful or if this class already existed, otherwise the
API sends the user to the callback URL.
Action on Failure -
Return Values -
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 14
TurnitinUK API Manual Section: API Functions
Examples -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=2&fcmd=1&encrypt=0&md5=
0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=john.doe@myschool.
edu&upw=john123&ufn=John%20II&uln=Doe&utp=2&ctl=English%20For%20Freshman
fcmd=2
Return Values -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=2&fcmd=2&encrypt=0&md5=
0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=john.doe@myschool.
edu&upw=john123&ufn=John%20II&uln=Doe&utp=2&ctl=English%20For%20Freshman
fcmd=3
Return Values -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=2&fcmd=3&encrypt=0&
md5=0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=john.doe@
myschool.edu&upw=john123&ufn=John%20II&uln=Doe&utp=2&ctl=English%20For%20
Freshman&ced=20061030
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 15
TurnitinUK API Manual Section: API Functions
fcmd=4
This fcmd allows the API user to switch the instructor for a class.
Return Values -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=2&fcmd=4&encrypt=0&md5=
0b83fbd3be5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=john.doe@myschool.
edu&upw=john123&ufn=John%20II&uln=Doe&utp=2&ctl=English%20For%20Freshman&new_teach-
er_email=edgar.odem@myschool.edu
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 16
TurnitinUK API Manual Section: API Functions
Logic
To join a class, the class must already exist and belong to the primary account or one
of its children.
If the user is successfully joined to the class an email will be sent to the user notifying
that he/she was joined to the class.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
If cid is set, the API will check to see if there is an existing match and use the
corresponding class id on the TurnitinUK side, ignoring the ctl and tem. If there is no
match and the information is included, the cid will be saved with the corresponding
TurnitinUK class id.
Success
Failure
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 17
TurnitinUK API Manual Section: API Functions
fcmd=1
Action on Success -
The API creates user (as with fid=1, fcmd=2) if the user is not in the database
The student is joined to the given class if they have not already joined the
class.
Return Values -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=3&fcmd=1&encrypt=0&md5=0b83fbd3b
e5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=student.x@myschool.edu&tem=john.doe@
myschool.edu&upw=student123&ufn=student&uln=x&utp=1&ctl=English%20For%20Freshman
fcmd=2
Return Values -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=3&fcmd=2&encrypt=0&md5=0b83fbd3b
e5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=student.x@myschool.edu&tem=john.doe@
myschool.edu&upw=student123&ufn=student&uln=x&utp=1&ctl=English%20For%20Freshman
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 18
TurnitinUK API Manual Section: API Functions
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 19
TurnitinUK API Manual Section: API Functions
Logic
Create an assignment with title assign for the class with ctl as class title and uem as
the instructor’s email in the given account.
If the user and the class do not exist, both will be created.
For fcmds 2, 3, and 4 a POST request is required to be made to the API server from
the client with user info. It would be best to use a GET request for fcmds 1 and 5.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
If idsync is set to 1, it will affect the class creation function (please see fid = 2).
If it is set, the API will check to see if the assignid is provided. If the assignid is
provided, it will ignore the idsync parameter. If assignid is not set, then the API will
check to see if there is an existing assignment with the corresponding assignment
title in the class. If the assignment exists and has a corresponding assignid,
it will NOT change the assignid. If the assignment exists and it doesn’t have a
corresponding assignid, the API will store TurnitinUK internal assignment ID as the
assignid. If the assignment does not exist, the assignment will be created and store
the internal assignment ID as the assignid.
If cid is set, the API will check to see if there is an existing match and use the
corresponding class id on the TurnitinUK side, ignoring the ctl. If there is no match
and the information is included, the cid will be saved with the corresponding
TurnitinUK class id.
Success
Failure
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 20
TurnitinUK API Manual Section: API Functions
fcmd=1
Action on Success - The API redirects the user to the TurnitinUK assignment
creation screen
Action on Failure - The API redirects the user to the callback URL
Return Values -
Success - logs the user into the TurnitinUK assignment creation screen
Failure - redirects to callback URL
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=4&fcmd=1&encrypt=0&md5=0b83fbd3be
5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=instructor.x@myschool.edu&ufn=instructor&ul
n=x&utp=2&ctl=English%20For%20Freshman&uid=_1_1&cid=_1_3
fcmd=2
Action on Success -
The API creates a new assignment for the given class, and returns XML
Return Values -
fcmd=3
Action on Success -
The API will modify the current assignment, and return XML
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 21
TurnitinUK API Manual Section: API Functions
If assignid is set, the API checks to see if there is an existing match. If assign
is included and there is no match, the API will use assign and store the
assignid with the corresponding TurnitinUK assignment id.
Return Values -
fcmd=4,6
Action on Success -
If assignid is set, the API checks to see if there is an existing match. If assign
is included and there is no match, the API will use assign.
Return Values -
fcmd=5
Action on Success - The API redirects the user to the TurnitinUK assignment
modification screen
Action on Failure - The API redirects the user to the callback URL
Return Values -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=4&fcmd=5&encrypt=0&md5=0b83fbd3be
5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=instructor.x@myschool.edu&ufn=instructor&
uln=x&utp=1&ctl=English%20For%20Freshman&uid=_1_1&cid=_1_3
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 22
TurnitinUK API Manual Section: API Functions
fcmd=7
Return Values -
<returndata>
<object>
<assign>Assignment #1</assign>
<maxpoints>100</maxpoints>
<dtstart>2009-08-13 00:00:00-07</dtstart>
<dtdue>2009-08-31 00:00:00-07</dtdue>
<dtpost>2009-08-31 00:00:00-07</dtpost>
<ainst>Assignment Instructions</ainst>
<userubrics>0</userubrics>
<draft>0</draft>
<generate>0</generate>
<sviewreports>0</sviewreports>
<latesubmissions>0</latesubmissions>
<repository>1</repository>
<searchpapers>1</searchpapers>
<searchinternet>1</searchinternet>
<searchjournals>1</searchjournals>
<searchinstitution>1</searchinstitution>
<anon>0</anon>
</object>
<rcode>85</rcode>
<rmessage>Successful!</rmessage>
</returndata>
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=4&fcmd=7&encrypt=0&md5=0b83fbd3be
5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=instructor.x@myschool.edu&ufn=instructor&u
ln=x&utp=1&ctl=English%20For%20Freshman&uid=_1_1&cid=_1_3
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 23
TurnitinUK API Manual Section: API Functions
If utp=1
tem: user email of instructor who created the class (required)
If utp=2
pfn: author of paper’s first name (required)
pln: author of paper’s last name (required)
ptl: title of paper to submit (required)
pdata: paper in original format (required)
ptype: type of file (1-text, 2-file) (required)
ctl: title of class to submit paper to (required)
assign: title of assignment to submit paper to (unique for that class) (required)
submit_date: allows the submissions to have a custom submit date. If the
user wants to specify a specific date/time that is before the start date it can’t be
submitted and if it is after the due date it cannot be submitted (optional)
session-id: users can log in using the session-id which allows them to make
certain write-then-read combinations of API calls in rapid succession, where the
second call depends on data as a result of the first call (optional)
Logic
This function will submit a paper to the given assignment. The assignment, class, and
user all need to exist prior to submitting a paper.
We receive a GET request with fcmd=1 that redirects the user to our TurnitinUK
submission page.
We receive a POST from the client with user info and the user paper object.
Note: The POST cannot be directly sent to our website, but must be a re-post
of the required data to our site. See fcmd 2 for an example.
For bulk uploads, we require to just call this function as many times as papers in bulk
upload.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
If submit_date is not set, the time of the submission is the current time. The
submit_date is still subject to the due date and start date of the assignment,
meaning that if the date specified is before the start date or after the due date
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 24
TurnitinUK API Manual Section: API Functions
If cid is set, the API will check to see if there is an existing match. If there is no
match, the API will use the ctl and tem and store the cid with the corresponding
TurnitinUK class id.
If assignid is set, the API checks to see if there is an existing match. If they are
included and there is no match, the API will use assign, ctl and tem and store
assignid with the corresponding TurnitinUK assignment id.
Success
Failure
fcmd=1
Action on Success - The API redirects the user to the TurnitinUK submission screen
Action on Failure - The API redirects the user to the callback URL
Return Values -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=5&fcmd=1&encrypt=0&md5=0b83fbd3be
5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=instructor.x@myschool.edu&ufn=instructor&
uln=x&utp=1&ctl=English%20For%20Freshman&assign=Test1&uid=_1_1&cid=_1_3&assignid=_1_1
fcmd=2
Action on Success - The API returns a unique object identifier for the paper that has
been submitted, and returns XML
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 25
TurnitinUK API Manual Section: API Functions
Return Values -
Examples -
Since you cannot POST directly to our site, you can submit the form to your own site,
process the data, and repost the data to us:
POST ‘https://submit.ac.uk/api.asp’,
Content_Type => ‘form-data’,
Content => [ ufn =>’Person’,
uem =>’gisle@aas.no’,
uln =>”M”,
gmtime => [“$ENV{HOME}/.profile”],
]
This will create a HTTP::Request object that almost looks like this (the boundary and
the content of your~/.profile is likely to be different):
POST https://submit.ac.uk/api.asp
Content-Length:388
Content-Type: multipart/form-data; boundary=”6G+f”
--6G+f
Content-Disposition: form-data; name=”ufn”
Person
--6G+f
Content-Disposition: form-data; name=”uem”
gisle@aas.no
--6G+f
Content-Disposition: form-data; name=”uln”
M
--6G+f
Content-Disposition: form-data; name=”gmtime”
1964
--6G+f
Content-Disposition: form-data; name=”paper”; filename=”.profile”
Content-Type: text/plain
PATH=/local/perl/bin:$PATH
export PATH
--6G+f--
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 26
TurnitinUK API Manual Section: API Functions
oid: unique Object ID of paper for which to generate a report for (required)
session-id: users can log in using the session-id which allows them to make
certain write-then-read combinations of API calls in rapid succession, where the
second call depends on data as a result of the first call (optional)
Logic
This API function retrieves the Originality Report for the given object ID.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
Success
Failure
fcmd=1
Action on Success - The API opens a new window containing the specified Originality
Report
Action on Failure - The API redirects the user to the callback URL
Return Values -
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 27
TurnitinUK API Manual Section: API Functions
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=6&fcmd=2&encrypt=0&md5=0b83fbd3b35
ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=student.x@myschool.edu&ufn=person&uln=x&
utp=1&oid=1546545
fcmd=2
Action on Success - The API retrieves the originality score for the given object ID,
and returns XML
Return Values -
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=6&fcmd=2&encrypt=0&md5=0b83fbd3b35
ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln=x&
upw=password&utp=1&oid=2390481
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 28
TurnitinUK API Manual Section: API Functions
Logic
This API function allows the user to view or download the paper that has been
submitted.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
If cid is set, the API will check to see if there is an existing match. If there is no
match, the API will use the ctl and tem and store the cid with the corresponding
TurnitinUK class id.
If assignid is set, the API checks to see if there is an existing match. If there
is no match, the API will use assign, ctl and tem and store assignid with the
corresponding TurnitinUK assignment id.
Success -
70 - Paper viewed/downloaded
Failure -
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 29
TurnitinUK API Manual Section: API Functions
fcmd=1
Action on Success - The API opens a new window containing the original submitted
paper
Action on Failure - The API redirects the user to the callback URL
Return Values -
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=7&fcmd=1&encrypt=0&md5=0b83fbd3b3
5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=student.x@myschool.edu&ufn=person&uln=x
&upw=password&utp=1&oid=1546545&ctl=classtitle&assign=assignment
fcmd=2
Action on Success - The API downloads the original submitted paper. If Anonymous
Marking is enabled for the assignment the instructor will not be able to download the
paper until the post date of the assignment
Return Values -
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=7&fcmd=2&encrypt=0&md5=0b83fbd3b3
5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln=x
&upw=password&utp=1&oid=2390481&ctl=classtitle&assign=assignment
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 30
Section: API Functions
Logic
This function deletes the paper that matches the Object ID.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
Success
Failure
fcmd=1
fcmd=2
Action on Success - The API deletes the specified paper, and returns XML
Return Values -
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 31
TurnitinUK API Manual Section: API Functions
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=8&fcmd=2&encrypt=0&md5=0b83fbd3b35
ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln=x&
utp=1&oid=2390481
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 32
TurnitinUK API Manual Section: API Functions
Logic
This API function changes the password for the given user after the user is validated
with their current password.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
Success
Failure
fcmd=1
fcmd=2
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 33
TurnitinUK API Manual Section: API Functions
Return Values -
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=9&fcmd=2&encrypt=0&md5=0b83fbd3b35
ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&npw=newpassword&uem=teacher.x@myschool.edu&
ufn=person&uln=x&upw=password&utp=1
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 34
TurnitinUK API Manual Section: API Functions
If utp = 1
tem: user email of instructor who created the class (required)
ctl: title of class (required)
assign: title of assignment to view submissions for (unique for that class)
(required)
session-id: users can log in using the session-id which allows them to make
certain write-then-read combinations of API calls in rapid succession, where the
second call depends on data as a result of the first call (optional)
hide_gm_nav: disables or hides the navigation for GradeMark, so the
instructor cannot move between papers from within GradeMark. Only for
FCMD=1 (1 hides navigation, 0 does not hide navigation)
Logic
This API function lists all the papers that have been submitted to the specified
assignment for the specified class.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
If cid is set, the API will check to see if there is an existing match. If there is no
match, the API will use the ctl and tem and store the cid with the corresponding
TurnitinUK class id.
If assignid is set, the API checks to see if there is an existing match. If there
is no match, the API will use assign, ctl and tem and store assignid with the
corresponding TurnitinUK assignment id.
Success
70 - Redirect the user to the TurnitinUK inbox screen for either student or
instructor user depending upon user type
72 - Submission data successfully retrieved
Failure
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 35
TurnitinUK API Manual Section: API Functions
fcmd=1
Action on Success - The API redirects the user to the TurnitinUK inbox screen for
either the student or instructor user depending upon the user type
Action on Failure - The API redirects the user to the callback URL
Return Values -
https://submit.ac.uk/api.asp?gmtime=200310231011&fid=10&fcmd=1&encrypt=0&md5=0b83fbd3b
e5ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=instructor.x@myschool.edu&ufn=instructor&
uln=x&utp=1&ctl=English%20For%20Freshman&assign=Test 1&uid=_1_1&cid=_1_3&assignid=_1_1
fcmd=2
Return Values -
<returndata>
<object>
<userid>9876543</userid>
<firstname>John</firstname>
<lastname>Doe</lastname>
<title>My Title</title>
<objectID>49247310</objectID>
<date_submitted>14-08-09 16:37:47 PDT</date_submitted>
<similarityScore>0</similarityScore>
<overlap>30</overlap>
<web_overlap>20</web_overlap>
<publication_overlap>10</publication_overlap>
<student_paper_overlap>5</student_paper_overlap>
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 36
TurnitinUK API Manual Section: API Functions
<score>100</score>
<anon>1</anon>
<gradeMarkStatus>1</gradeMarkStatus>
</object>
<object>
<userid>1234567</userid>
<firstname>Jane</firstname>
<lastname>Doe</lastname>
<title>My Title</title>
<objectID>49247311</objectID>
<date_submitted>14-08-09 16:37:47 PDT</date_submitted>
<similarityScore>0</similarityScore>
<overlap>0</overlap>
<web_overlap>20</web_overlap>
<publication_overlap>10</publication_overlap>
<student_paper_overlap>5</student_paper_overlap>
<score>100</score>
<anon>1</anon>
<gradeMarkStatus>1</gradeMarkStatus>
</object>
<rcode>72</rcode>
<rmessage>Successful!</rmessage>
</returndata>
Note: If Anonymous Marking is enabled for an assignment the first name of the
student will be “Anonymous Marking” and the last name will be “Enabled” up until the
post date of the assignment
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=10&fcmd=2&encrypt=0&md5=0b83fbd3b35
ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln=x&
utp=1&ctl=classtitle&assign=assignment
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 37
TurnitinUK API Manual Section: API Functions
Logic
This API function checks to see if user has submitted a paper to the specified
assignment and checks to see if the class allows students to view their own originality
reports
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
If cid is set, the API will check to see if there is an existing match. If there is no
match, the API will use the ctl and tem and store the cid with the corresponding
TurnitinUK class id.
If assignid is set, the API checks to see if there is an existing match. If there
is no match, the API will use assign, ctl and tem and store assignid with the
corresponding TurnitinUK assignment id.
Success
Failure
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 38
TurnitinUK API Manual Section: API Functions
fcmd=1
fcmd=2
Return Values -
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=11&fcmd=2&encrypt=0&md5=0b83fbd3b
35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln=
x&utp=1&ctl=classtitle&assign=test
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 39
TurnitinUK API Manual Section: API Functions
Logic
This API function checks to see if the user is an administrator and then the API
redirects the user to a page that contains the administrator statistics for the account.
Success
Failure
fcmd=1
Action on Success - The API redirects the user to the administrator statistics page
Action on Failure - The API redirects the user to the callback URL
Return Values -
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=12&fcmd=1&encrypt=0&md5=0b
83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=administrator.x@myschool.
edu&ufn=person&uln=x&utp=3
fcmd=2
Not defined yet
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 40
TurnitinUK API Manual Section: API Functions
oid: unique Object ID of paper for which to access GradeMark for (required)
session-id: users can log in using the session-id which allows them to make
certain write-then-read combinations of API calls in rapid succession, where the
second call depends on data as a result of the first call (optional)
hide_gm_nav: disables or hides the navigation for GradeMark, so the
instructor cannot move between papers from within GradeMark. Only for
FCMD=1 (1 hides navigation, 0 does not hide navigation)
Logic
This API function retrieves the GradeMark screen for the given object ID.
If uid is set, the API will check to see if there is an existing match and use the
corresponding user id on the TurnitinUK side, ignoring the uem, ufn, and uln. If the
existing user first name, last name, or user email address is different than the ufn,
uln, or uem being sent, the API will update the existing user information accordingly.
If the uid is not set, the API will use the included information and store the uid with
the corresponding TurnitinUK user id.
Success
Failure
fcmd=1
Action on Success - The API opens a new window containing the specified
GradeMark paper
Action on Failure - The API redirects the user to the callback URL
Return Values -
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 41
TurnitinUK API Manual Section: API Functions
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=13&fcmd=1&encrypt=0&md5=0b83fbd3b
35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=student.x@myschool.edu&ufn=person&uln=
x&utp=1&oid=1546545
fcmd=2
Action on Success - The API retrieves the status of the paper: whether it has been
marked up or not
Return Values -
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=13&fcmd=2&encrypt=0&md5=0b83fbd3b35
ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln=x&
upw=password&utp=2&oid=2390481
fcmd=3
Action on Success - The API redirects the user to the GradeMark Report page which
provides details about the use of QuickMark editing marks and Rubrics within an
assignment and allows the user to export the report as an excel spreadsheet
Return Values -
https://api.turnitin.com/api.asp?gmtime= 20040329113&fid=13&fcmd=3&encrypt=0&md5=0b83fbd3
b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln
=x&upw=password&utp=2&cid=1787187&assignid=_1_1
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 42
TurnitinUK API Manual Section: API Functions
Logic
The API will return to the user in XML format the average originality report turnaround
times in seconds for the time intervals of 1, 5, 10 and 15 minutes.
Success
fcmd=1
fcmd=2
Action on Success - The API returns in XML format the average originality report
turnaround times in seconds for the time intervals of 1, 5, 10 and 15 minutes
Return Values -
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 43
TurnitinUK API Manual Section: API Functions
<returndata>
<object>
<averagetime15>47</averagetime15>
<averagetime10>48</averagetime10>
<averagetime5>47</averagetime5>
<averagetime1>36</averagetime1>
</object>
<rmessage>Successful!</rmessage>
<rcode>74</rcode>
</returndata>
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=14&fcmd=2&encrypt=0&md5=0b83fbd3b35
ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln=x&
upw=password&utp=2
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 44
TurnitinUK API Manual Section: API Functions
Logic
The API function will retrieve the score or submit the score for the object if the object
exists, and the user has permission to access the object.
Success
fcmd=1
fcmd=2
Return Values -
fcmd=3
Return Values -
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 45
TurnitinUK API Manual Section: API Functions
Logic
The API function will retrieve the score or submit the score for the object if the object
exists, and the user has permission to access the object.
Success
fcmd=1
Action on Success - The API redirects the user to the Administrator Log page for
Anonymous Marking
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=16&fcmd=1&encrypt=0&md5=0b
83fbd3b35ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=administrator.x@myschool.
edu&ufn=person&uln=x&utp=3
fcmd=2
Action on Success - The API returns in XML the Administrator Log for Anonymous
Marking
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 46
TurnitinUK API Manual Section: API Functions
Return Values -
Example:
<object>
<instructor_firstname>Class</instructor_firstname>
<instructor_lastname>Instructor</instructor_lastname>
<author_lastname>Doe</author_lastname>
<author_firstname>John</author_firstname>
<paperID>49245220</paperID>
<assignmentID>5401502</assignmentID>
<date_off>2009-01-20 01:10:25.422231-08</date_off>
<reason>Reason for disabling AM</reason>
</object>
fcmd=3
Action on Success - The API reveals the name of the author for the submission
https://submit.ac.uk/api.asp?gmtime= 20040329113&fid=13&fcmd=2&encrypt=0&md5=0b83fbd3b35
ea56ac8bbaf026a6d6a23&aid=100&diagnostic=0&uem=teacher.x@myschool.edu&ufn=person&uln=x&
upw=password&utp=2&oid=2390481&anon_reason=Some reason
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 47
TurnitinUK API Manual Section: API Functions
Logic
The API function will log in the user described by the user email, first name, last
name, and user type.
Success
92 - login succeeded
Failure
fcmd=1
fcmd=2
Return values -
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 48
TurnitinUK API Manual Section: API Functions
Logic
The API function will log out the user described by the user email, first name, last
name, and user type and end the Session with session-id.
Success
92 - logout succeeded
Failure
fcmd=1
fcmd=2
Return values -
http://api.turnitin.com/api.asp?gmtime=20091022211&fid=18&fcmd=2&encrypt=0&md5=b337d2036
a8e5638b1d9094f0eec7ae9&aid=39219&said=&diagnostic=0&uem=test_user1%40turnitin.com&upw
=&ufn=Test&uln=User1&utp=2&session-id=16f69a5f9d93feb01edc8c794ff2c3e4
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 49
TurnitinUK API Manual Section: API Functions
Error Checking
If an error occurs, the API redirects the client back to the callback URL if
diagnostic=0 or to the output error diagnostic information if diagnostic=1. The
following error checks are made in the order given below. The error checking stops
after the first error is encountered and diagnostic information is only provided for
that step and previous ones. The ordering is meant to limit the amount of valid
information a user has access to, given an incomplete/invalid request.
All errors are uniquely identifiable by a numeric code and shall have a short error
message associated with them. The full return code set includes both the error codes
and success codes, all of which are unique.
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 50
TurnitinUK API Manual Section: Success States
Logging
All requests and the result of those requests are logged. This should include the
requesting URL, the return code, and any other diagnostic information (DB rollbacks/
errors, etc.)
Return Codes
Success States
1-99
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 51
TurnitinUK API Manual Section: Error States
Error States
Data Errors
100-199
submission
132 The grade for the object in invalid. Please make sure the grade is between 0
and max points for the assignment.
133 AssignID not allowed if creating an assignment with IDSync on. Please either
turn IDSync off or remove the assignID field.
134 submit_papers_to parameter needs to be between 0 and 2 inclusive.
200-299
200 Primary account ID for TurnitinUK not activated to use the API
201 IP address validation range for TurnitinUK not configured
202 Primary account entry not active in TurnitinUK database
203 MD5 key missing from TurnitinUK database
204 Class does not exist in TurnitinUK database. Please contact you instructor for
further details.
205 Database error verifying class
206 The assignment you are trying to access does not exist in TurnitinUK for this
class. The assignment may have been deleted. If you created your assignment
via a course copy method, it may not have been done with a course copied
enabled version of the integration. In such a case, please delete the
assignment and recreate it manually.
207 Database error verifying assignment
208 User is not enrolled in class
209 Database error verifying user’s enrollment in class
210 User password does not match user email
211 Database error verifying objectID
212 objectID does not exist for this user
213 objectID does not belong to this user
214 Filename does not exist for this paper
215 This primary account ID is not authorized to use this product
216 Student limit for this account has been reached. Cannot join student to this
class.
217 The product for this account has expired. Please contact your sales agent to
renew the product
218 Database Error inserting unique ID into the database
219 Unique user id in the database does not match submitted uid
220 More than one class exists with this title and unique ids must be used in this
case
221 More than one assignment exists with this title and unique ids must be used in
this case
222 User is associated with a different external uid. If you have another user
account with the same email address as the user account you are currently
using, that could be the cause of the problem. Please try modifying the email
address for your current user account to a unique email address and try again.
223 Cannot verify Blackboard user’s identity within TurnitinUK. Missing Blackboard
user id
224 Could not verify user as primary instructor for this course
225 Database error checking if student can view reports
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 53
TurnitinUK API Manual Section: Error States
226 The class you are trying to update could not be found. Please check to make
sure that the class exists.
227 The class you are trying to update has an assignment which ends after the
class end date you have specified. Please change you class end date or modify
the assignment.
228 The assignment with the assignment id that you entered does not belong to the
class with the class id you entered. Please check to make sure that you are not
using a duplicate assignment id.
229 There was an error creating the rollover assignment.
230 You have been dropped from this class on the TurnitinUK end by your instructor.
Please contact your instructor if you think you are receiving this message in
error.
231 There was an error processing your request: please try your action again.
Please contact the TurnitinUK helpdesk if the problem persists.
232 Grademark is currently inactive for this account.
233 There was an error accessing this TurnitinUK Assignment because it was created
via Course Copy, Snapshot, or some other process, and the original TurnitinUK
Assignment could not be found.
234 Could not find class with the given unique ID or title.
235 Could not find assignment with the given assignment ID or title.
236 Could not retrieve assignment info with the given information.
237 Could not retrieve grade for the given object.
238 Could not find user with the given userid or email.
Inconsistency Errors
300-399
300 Your IP address does not fall within the range of accepted IP addresses as
specified by your TurnitinUK account administrator. Please check with
your TurnitinUK account administrator if your IP address needs to be added as
an accepted IP address.
301 Date/time expired – GMT timestamp used in MD5 calculation is off. API calls
must have a GMT within 60 minutes of the current GMT
301 For Blackboard users. Your request has exceeded the time limit. Perhaps you
have left the page open for an extended period of time. Please reload the page
and try again.
302 MD5 not authenticated - the MD5 in the URL does not match the MD5 calculated
Function Errors
400-499
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 54
TurnitinUK API Manual Section: Error States
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 55
TurnitinUK API Manual Section: Error States
first.
443 Anonymous Marking is enabled for this assignment. Cannot download file until
after the assignment post date.
444 Usage of this account is not currently high enough to generate meaningful
statistics. If you would like more information or would like to see these statistics
any way, please contact your Turnitin sales representative.
445 User login failed.
446 Session ID missing from URL
1000-1099
1000 The due date for this assignment has passed. Please see your instructor to
request a late submission.
1001 You may not submit a paper to this assignment until the assignment start date
1002 You may not submit a paper to this assignment because the Plagiarism
Prevention product is unavailable
1003 You have reached the maximum limit of 10 papers for the InSite demo account
1004 Paper author’s first name missing or incorrect length in URL
1005 Paper author’s last name missing or incorrect length in URL
1006 Paper title missing
1007 The file you have uploaded is too big
1008 No file uploaded! Please make sure that you have attached the file that you
wish to submit before sending the request
1009 Invalid file type! Valid file types are MS Word, Acrobat PDF, Postscript, Text,
HTML, WordPerfect (WPD) and Rich Text Format. Please make sure the format
of your file is one of the valid file types.
1010 You must submit more than 100 characters of non-whitespace
1011 The paper you are trying to submit is incorrectly formatted. There seems to be
spaces between each letter in your paper. Please try submitting again or
contact our help desk if the problem persists.
1012 Paper length exceeds limits
1013 You must submit more than 20 words of text
1014 You must select an enrolled student as the author of this paper
1015 You have already submitted a paper to this assignment. Please contact your
instructor to request a resubmission
1016 This student has already submitted a paper to this assignment. Please delete
the original paper before submitting a new one.
1017 Paper author’s first name missing or incorrect length in URL
1018 Paper author’s last name missing or incorrect length in URL
1019 Paper title exceeds maximum of 200 characters
1020 This document cannot be accepted because it contains characters from a
character set we do not support.
1021 You have already submitted a paper to this assignment. Please contact your
instructor to request a resubmission.
1022 This student has already submitted a portfolio item to this assignment. Please
delete the original portfolio item before submitting a new one.
1023 We’re sorry, but we could not read the PDF you submitted. Please make sure
that the file is not password protected and contains selectable text rather than
scanned images.
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 56
TurnitinUK API Manual Section: Error States
1024 The paper you are trying to submit does not meet our criteria for a legitimate
paper. Please try submitting again or contact our help desk if the problem
persists.
2025-2324
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 57
TurnitinUK API Manual Section: Error States
submitted to this assignment. You must create a new assignment if you would
like to change the search targets
2319 There was an error processing your request
2320 There was an error processing your request
2321 When excluding small matches by word, you must enter a positive number
2324 When excluding small matches by percentage, you must enter a number
between 1 and 100
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 58
TurnitinUK API Manual Section: FID/FCMD Error Code Table
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 59
TurnitinUK API Manual Section: FID/FCMD Error Code Table
Inconsistency Errors
300 X X X X X X X X X X X X X X X
301 X X X X X X X X X X X X X X X
302 X X X X X X X X X X X X X X X
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 60
TurnitinUK API Manual Section: FID/FCMD Error Code Table
Function Errors
FID FID FID FID FID FID FID FID FID FID FID FID FID FID FID
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD
1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2
400 X X X X
401 X X X X
402 X X X
403 X
404 X X X X X X X
405 X
406 X X
407 X
408 X X
409 X X
410
411 X
412 X X X X X X
413 X
414 X
415 X
416 X
417 X
418 X
419 X
420 X
421 X
422 X X X X X X X X X X X
423 X X X X X X X X X X X
424 X X X X X X X
425
426
427
428
429
430
431
432
433 X
434 X
435 X
437 X X
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 61
TurnitinUK API Manual Section: FID/FCMD Error Code Table
FID FID FID FID FID FID FID FID FID FID FID FID FID FID FID
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD
1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2
439 X X
440 X
441 X
442 X
443 X
444 X
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 62
TurnitinUK API Manual Section: FID/FCMD Error Code Table
FID FID FID FID FID FID FID FID FID FID FID FID FID FID FID
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD FCMD
1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2
1000 X
1001 X
1002 X
1003 X
1004 X
1005 X
1006 X
1007 X
1008 X
1009 X
1010 X
1011 X
1012 X
1013 X
1014 X
1015 X
1016 X
1017 X
1018 X
1019 X
1020 X
1021 X
1022 X
1023 X
1024 X
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 63
TurnitinUK API Manual Section: FID/FCMD Error Code Table
FID FID FID FID FID FID FID FID FID FID FID FID FID FID FID
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
aid X X X X X X X X X X X X X X X
ainst X
assign X X X X X X X
assignid X X X X X X X
ced X X
cid X X X X X X X X
cpw X
ctl X X X X X X X X
diagnostic X X X X X X X X X X X X X X X
dis X X X X X X X X X X X X X X X
dtdue X
dtstart X
encrypt X X X X X X X X X X X X X X X
fcmd X X X X X X X X X X X X X X X
fid X X X X X X X X X X X X X X X
gmtime X X X X X X X X X X X X X X X
newassign X
newupw X
oid X X X X
pdata X
pfn X
pln X
ptl X
ptype X
said X X X X X X X X X X X X X X X
session-id X X X X X X X X X X X X X X X
tem X X X X X X
uem X X X X X X X X X X X X X X X
ufn X X X X X X X X X X X X X X X
uid X X X X X X X X X X X X
uln X X X X X X X X X X X X X X X
upw X X X X X X
username X X X X X X X X X X X X X X X
utp X X X X X X X X X X X X X X X
md5 X X X X X X X X X X X X X X X
Note: Blue X’s are to indicate optional variables for that FID
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 65
TurnitinUK API Manual Section: FID/MD5 Table
FID/MD5 Table
Note: A general rule when preparing the MD5 string is to include in the
string all the values of the data elements that have a value set.
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 66
TurnitinUK API Manual Section: FID/Encrypt Data Table
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 67
GET/POST Requirements for Functions
FID FCMD Function Description GET/POST/BOTH?
1 1 Create a user and login BOTH
1 2 Create a user BOTH
Create a class under the given account
2 1 and assign (create if necessary) user as BOTH
the instructor of the class and login
Create a class under the given account
2 2 and assign (create if necessary) user as BOTH
the instructor of the class
2 3 Modify a class BOTH
Join the given class as a student (create
3 1 user if necessary)
BOTH
Join the given class as a student (create
3 2 user if necessary)
BOTH
Create an assignment through the
4 1 TurnitinUK assignment creation screen
BOTH
Create an assignment under the given
4 2 account and given class
POST
Modify an assignment under the given
4 3 account and given class
POST
Delete the assignment under the given
4 4 account and given class
POST
Modify an assignment through the
4 5 TurnitinUK assignment modification screen
BOTH
Submit a paper through the TurnitinUK
5 1 submission screen
BOTH
Submit a paper to the given account,
5 2 class, assignment
POST
Retrieve the originality report (or link) for
6 1 the given object ID
BOTH
Retrieve the originality score for the given
6 2 object ID
BOTH
7 1 View original paper BOTH
7 2 Download original paper BOTH
8 2 Delete Submission BOTH
9 2 Change password BOTH
List all submissions in the TurnitinUK
10 1 inbox screen
BOTH
10 2 List all submissions for given assignment BOTH
11 2 Check if user has submitted to assignment BOTH
12 1 Show administrator statistics for account BOTH
The API opens a new window containing
13 1 the specified GradeMark paper
BOTH
The API retrieves GradeMark for the given
13 2 object ID
BOTH
The API returns the average originality
14 2 report turnaround times in seconds for the BOTH
time intervals of 1, 5, 10 and 15 minutes
The API retrieves the score for a
15 2 GradeMark paper
BOTH
The API sets the score for a GradeMark
15 3 paper
BOTH
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 68
TurnitinUK API Manual Section: GET/POST Requirements for Functions
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 69
Functions which Create User Profiles
FID FCMD Function Description Creates Profile?
1 1 Create a user and login YES
1 2 Create a user YES
2 1 Create a class under the given account
and assign (create if necessary) user as YES
the instructor of the class and login
2 2 Create a class under the given account
and assign (create if necessary) user as YES
the instructor of the class
2 3 Modify a class YES
3 1 Join the given class as a student (create
YES
user if necessary)
3 2 Join the given class as a student (create
YES
user if necessary)
4 1 Create an assignment through the
YES
TurnitinUK assignment creation screen
4 2 Create an assignment under the given
YES
account and given class
4 3 Modify an assignment under the given
YES
account and given class
4 4 Delete the assignment under the given
YES
account and given class
4 5 Modify an assignment through the
YES
TurnitinUK assignment modification screen
5 1 Submit a paper through the TurnitinUK
NO
submission screen
5 2 Submit a paper to the given account,
NO
class, assignment
6 1 Retrieve the originality report (or link) for
NO
the given objectID
6 2 Retrieve the originality score for the given
NO
object ID
7 1 View original paper NO
7 2 Download original paper NO
8 2 Delete Submission NO
9 2 Change password NO
10 1 List all submissions in the TurnitinUK
NO
inbox screen
10 2 List all submissions for given assignment NO
11 2 Check if user has submitted to assignment NO
12 1 Show administrator statistics for account NO
13 1 The API opens a new window containing
NO
the specified GradeMark paper
13 2 The API retrieves GradeMark for the given
object ID NO
The API returns the average originality
14 2 report turnaround times in seconds for the NO
time intervals of 1, 5, 10 and 15 minutes
The API either retrieves or sets score for a
15 2, 3 GradeMark paper NO
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 70
Glossary
Glossary
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 71
Glossary Section: Definitions
Definitions
encrypt - the encryption flag. The
aid - the primary account id (must encryption flag can be set to 0 (off)
not be encrypted) or 1 (on). If encryption is enabled,
the following user sensitive data
ainst - assignment instructions must be encrypted using your
shared secret key with the Blow-
assign - title of the assignment a fish encryption scheme: said, uem,
paper is being submitted to (unique upw, ufn, uln, utp, ctl, cpw, tem
for that class)
fcmd - the numeric API function
assignid - unique assignment id. specific command
Either third party id, or possibly a
unique TurnitinUK assignment id fid - the numeric API command.
The fid determines the function that
ced - to allow students to submit the API will perform
files, an instructor must create a
class for their students. A class gmtime - the GMT timestamp. The
requires a name, a class ID, and a timestamp must be sent in the form
class enrollment password YYYYMMDDHHM. The TurnitinUK
server clocks are kept synchronized
cid - unique class id. Either a using the network time protocol
third party id, or possibly a unique
TurnitinUK class id md5 - the MD5 signature is
generated by a concatenating
cpw - class enrollment password the data values associated with
(only applicable if fid=2 or 3) specific URL variables arranged
in alphabetical order according to
ctl - class title (only applicable if variable name. The shared secret
fid=2 or 3) key is included at the end of the
MD5 string
diagnostic - the diagnostic flag
provides diagnostic output for API newassign - new title for the
debugging. When enabled it will assignment if modifying assignment
only validate request but will not (only applicable if fid=4)
perform any action.
npw - new password to change to
dis - email notification. By default,
email notifications are sent for oid - unique Object ID of paper for
user creation, class creation, which to generate report for, view
student class enrollment, and or download paper
paper submission (digital receipt).
Setting this flag to 1 disables these pdata - paper in original format
notifications (fid=5)
dtdue - date the assignment is due pfn: author of paper’s first name
(in YYYYMMDD format) (used only for fid=5)
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 72
Glossary Section: Definitions
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 73