You are on page 1of 73

TurnitinUK API Manual

Version 2.1.1

Updated February 24, 2010

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

Overview of Function Variables 7


Functions Specific Variables 9

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.

API Request Overview

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.

Configuring the API From Your Admin Account

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.

Click on the configure link to the right of the Open API.

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.

Administrators have the option to enter in a range of IP addresses. This IP masking is


done using the CIDR format. The format is xxx.xxx.xxx.xxx/y where x stands for any
digits from 0-9, and y is for the number of bits of the IP address you wish to use as
a mask. For example: 64.140.5.0/25 will allow any addresses form 64.140.5.0-127;
64.140.5.128/25 will allow any address from 64.140.5.128-255; 64.140.5.0/24 will
allow any addresses from 64.140.5.0-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?ec=100&em=Primary account ID is missing.

The TurnitinUK callback URL:

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

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.

Overview of Function Variables

Required Function Variables

gmtime - GMT timestamp

The timestamp must be sent in an 11 digit numeric format YYYYMMDDHHM. The


TurnitinUK server clocks are kept synchronized using the network time protocol.

fid - the function id

The numeric API command

fcmd - the function command

The numeric API function specific command

encrypt - encryption flag

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

Note: Encrypting variables might not be necessary or recommended for


everyone since the API is accessed with an https url.

md5 - the function specific MD5 hex signature

The MD5 signature is generated by concatenating the data values associated


with specific URL variables arranged in alphabetical order according to variable
name. The shared secret key is included at the end of the MD5 string. For more
information on the MD5, see the section titled Calculating the MD5 later in this
document.

aid - primary account id

The id of the account which is associated with your school’s TurnitinUK license.

diagnostic - diagnostic flag

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.

uem - user email

The user email is used as the TurnitinUK user name. The email address must be
6-50 characters in length.

ufn - user first name

User first name must be 1-50 characters in length.

uln - user last name

Must be 1-50 characters in length.

utp - user type

1 for students, 2 for instructors, and 3 for administrators.

Note: There may be additional required function variables to perform


different function requests. These variables will be detailed for the specific API
functions in the additional function variables for fid = (#) subsection.

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 8
TurnitinUK API Manual Section: Functions Specific Variables

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)

2 - creates a class under a given account (instructor only)

3 - enrolls a student in a class (student only)

4 - creates an assignment (instructor only)

5 - submits a paper to an assignment (student or teacher)

6 - generates an Originality Report for a submitted paper

7 - displays a submitted paper in a separate browser window or downloads it in


file format

8 - deletes a submitted paper

9 - changes a user’s password

10 - lists the papers that have been submitted to an assignment

11 - checks to see if a user has submitted a paper to a specified assignment

12 - views administrator statistics page

13 - view the GradeMark screen for a submission

14 - Originality Report turnaround times

15 - load/set submission scores

16 - Anonymous Marking

17 - login a user to and create a session

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

Create user and login (fid=1)

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.

Return States (rcode - event)

Success

10-11 - User creation successful

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 11
TurnitinUK API Manual Section: API Functions

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
400 - User creation failed

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

Examples - Non-working example using GET request:

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>

Examples - Non-working example using GET request:

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)

Additional Function Variables for fid=2

ctl: class title (5-50 character in length)(required)


cpw: class join password (6-12 characters in length)(optional)
ced: class end date (format: YYYYMMDD)(optional)
utp: must be 2 (instructor)
idsync: either 1 or 0
new_teacher_email: new teacher email (used in fcmd=4)
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

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.

Return States (rcode - event)

Success

20-21 - Class creation successful


22 - Class update successful

Failure

101-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
401 - Unauthorized access
402 - User is not an instructor
405 - Class title is not unique
406 - Class creation failed

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 -

The API redirects the user to the callback URL

Return Values -

Success - logs user into TurnitinUK


On Failure - redirects user to callback URL

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 14
TurnitinUK API Manual Section: API Functions

Examples -

Non-working example using GET request:

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

Action on Success - The API will return XML

Action on Failure - The API will return XML

Return Values -

Success - XML <rcode>, <rmessage>, <classid>, <userid>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

This fcmd is mainly used to update the class end date.

Action on Successful - The API will return XML

Action on Failure - The API will return XML

Return Values -

Success - XML <rcode>, <rmessage>, <classid>, <userid>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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.

Action on Successful - The API will return XML

Action on Failure - The API will return XML

Return Values -

Success - XML <rcode>, <rmessage>, <classid>, <userid>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

Join Class (fid=3)

Additional Function Variables for fid=3

ctl: class title (5-50 characters in length)(required)


tem: user email of instructor who created the class (required)
utp: must be 1 (student)(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

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.

Return States (rcode - event)

Success

30-31 - User joined to class

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
407 - Student failed to join or log into a class

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.

Action on Failure - The API redirects user to the callback URL

Return Values -

Success - logs user into TurnitinUK

Failure - redirects user to callback URL

Examples - Non-working example using GET request:

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

Action on Success - The API returns XML

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <classid>, <userid>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

Create Assignment (fid=4)

Additional Function Variables for fid=4

ctl: title of class to create assignment in (required)


assign: title of assignment to create (required)
upw: user password (optional)
utp: must be 2 (instructor) (required)
dtstart: date the assignment begins (in YYYYMMDD format) (required)
dtdue: date the assignment is due (in YYYYMMDD format) (required)
dtpost: date when the grade and marked paper are available to students (in
YYYYMMDD or YYYY-MM-DD HH::MM:SS format) (required)
ainst: assignment instructions (optional)
newassign: new title of assignment if modifying assignment (optional)
ced: class end date (in YYYYMMDD format) (optional)
s_view_report: allow students to view the Originality Report (optional, default
is set to not allow students to view Originality Reports)
s_paper_check: compare submitted papers with other student papers
(optional, default =1 allow)
internet_check: compare submitted papers to internet database (optional,
default = 1 allow)
journal_check: compare submitted papers with journals, periodicals,
publications (optional, default = 1 allow)
institution_check: Compare submitted papers with papers submitted within
this institution (optional, default = 1 allow)
max_points: max points for assignment (optinoal, default = 0)
late_accept_flag: allow submission past due date (optional, default = 0 not
allow)
submit_papers_to: where to store the submission (optional, default = 1)
0 = no repository, 1 = standard repository, 2 = institutional repository (if the
institurtion has one)
report_gen_speed: when to generate the Originality Reports (optional,
default = 0)
0 = immediately (first report is final), 1 =immediately (can overwrite reports
until the due date), 2 = on the due date
anon: anonymous marking option for an assignment
exclude_biblio: exclude bibliographic material from the Originality Reports
generated for that assignment (default 1)
exclude_quoted: exclude quoted material from the Originality Reports
generated for that assignment (default 1)
exclude_type: for excluding small matches and is the exclusion type (by word
count = 1, by percentage = 2)
exclude_value: this is for excluding small matches and is the value of the
match to exclude from the Originality Report depending upon the exclusion type
(word count or percentage). If exclude by word count is chosen it will exclude
all matches with a word count beneath the set value, if exclude by percent is
chosen it will exclude all matches with a percentage beneath the set value
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)

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 19
TurnitinUK API Manual Section: API Functions

Logic

The title of the assignment must be unique to that class.

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 present, ainst is not to be included in the calculation of the MD5.

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.

Assignid not allowed if idsync is set to 1 and fcmd = 2.

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.

Return States (rcode - event)

Success

40 - Redirect to assignment creation/modification screen successful


41 - Assignment creation successful
42 - Assignment modification successful
43 - Assignment deletion successful

Failure

100-199 - Data Errors

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 20
TurnitinUK API Manual Section: API Functions

200-299 - TurnitinUK Database Errors


300-399 - Inconsistency Errors
411 - Assignment creation failed
419 - Assignment already existed

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

Examples - Non-working example using GET request:

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

If assignid is set, it will be saved with the corresponding TurnitinUK assignment


id that is created

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <assignmentid>, <classid>, <userid>


Failure - XML <rcode>, <rmessage>

Examples - Please see fid 5, fcmd 2 for a POST example

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.

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <assignmentid>, <classid>, <userid>


Failure - XML <rcode>, <rmessage>

Examples - Please see fid 5, fcmd 2 for a POST example

fcmd=4,6

Action on Success -

The API deletes the current assignment, and returns XML

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.

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <assignmentid>, <classid>, <userid>


Failure - XML <rcode>, <rmessage>

Examples - Please see fid 5, fcmd 2 for a POST example

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 -

Success - logs the user into the assignment modification screen


Failure - redirects user to the callback URL

Examples - Non-working example using GET request:

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

Action on Success - The API returns XML of assignment settings

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <object>, <assign>, <maxpoints>,


<dstart>, <dtdue>, <dtpost>, <ainst>, <userubrics>, <draft>, <generate>,
<sviewreports>. <latesubmissions>, <repository>, <searchpapers>,
<searchinternet>, <searchjournals>, <searchinstitution>, <anon>

Failure - XML <rcode>, <rmessage>

Example Return XML -

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

Examples - Non-working example using GET request:

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

Submit Paper Function (fid=5)

Additional Function Variables for fid=5

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.

There are two ways we can receive the request:

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

it cannot be submitted. The format for this field is (yyyymmdd or yyyy-mm-dd


hh:mm:ss)

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.

Return States (rcode - event)

Success

50 - Redirects user to the submission screen


51 - Paper submitted to the assignment

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
409 - Function requires POST request
413 - Paper submission failed
1000-1099 - Paper Submission Errors

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 -

Success - logs the user into the TurnitinUK submission screen


Failure - redirects the user to the callback URL

Examples - Non-working example using GET request:

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

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <objectid>


Failure - XML <rcode>, <rmessage>

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:

One way to do that is using HTTP::REQUEST::COMMON as specified in RFC 1867

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

Return Report Function (fid=6)

Additional Function Variables for fid=6

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.

Return States (rcode - event)

Success

60-61 - Originality Report/score retrieved

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
414 - Originality Report not generated yet
415 - Originality Score not available yet

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 -

Success - loads a new window containing the Originality Report


Failure - redirects user to callback URL

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 27
TurnitinUK API Manual Section: API Functions

Examples - Non-working example using GET request:

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

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <originalityscore>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

View/Download Submission (fid=7)

Additional Function Variables for fid=7

oid: unique ObjectID of paper to view or download (required)


If utp=1
tem: user email of instructor who created the class (required)

ctl: title of class the paper was submitted to (required)


assign: title of assignment that the paper was submitted to (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)

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.

Return States (rcode - event)

Success -

70 - Paper viewed/downloaded

Failure -

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
420 - Error trying to view/download original paper

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 -

Success - loads window containing the original submitted paper


Failure - redirects user to callback URL

Examples - Non-working example using GET request:

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

Action on Failure - The API returns XML

Return Values -

Success - downloads original paper to local machine


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

Delete Submission (fid=8)

Additional Function Variables for fid=8

oid: unique ObjectID of paper to view or download (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 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.

Return States (rcode - event)

Success

71 - Paper successfully deleted

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
418 - Error trying to delete submission

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API deletes the specified paper, and returns XML

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 31
TurnitinUK API Manual Section: API Functions

Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

Change Password (fid=9)

Additional Function Variables for fid=9

upw: current user password (required)


npw: new password to change to (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 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.

Return States (rcode - event)

Success

75 - Password changed successfully

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
417 - Error trying to change user password

fcmd=1

Not Defined YET

fcmd=2

Action on Success - The API change password, and returns XML

Action on Failure - The API returns XML

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 33
TurnitinUK API Manual Section: API Functions

Return Values -

Success - XML <rcode>, <rmessage>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

List Submissions (fid=10)

Additional Function Variables for fid=10

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.

Return States (rcode - event)

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

100-199 - Data Errors


200-299 - TurnitinUK Database Errors

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 35
TurnitinUK API Manual Section: API Functions

300-399 - Inconsistency Errors


420 - Error trying to build up session date for user/class
421 - Error trying to retrieve paper submission info for assignment

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 -

Success - logs the user into the submission screen


Failure - redirects to callback URL

Examples - Non-working example using GET request:

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

Action on Success - The API returns XML

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <object>, <userid>, <firstname>,


<lastname>, <title>, <objectid>, <similarityscore>, <overlap>, <web_
overlap>, <publication_overlap>, <student_paper_overlap>, <score>,
<grademarkstatus>
Failure - XML <rcode>, <rmessage>

Example Return XML -

<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

Examples - Non-working example using GET request:

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

Check for Submission (fid=11)

Additional Function Variables for fid=11

utp: must be set to 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)

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.

Return States (rcode - event)

Success

73 - Check successfully completed

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
416 - Error trying to verify if user has submitted to assignment

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 38
TurnitinUK API Manual Section: API Functions

fcmd=1

Not Defined YET

fcmd=2

Action on Success - The API returns XML

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

Administrator Statistics (fid=12)

Additional Function Variables for fid=12

utp: must be set to 3


fcmd: must be set to 1
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 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.

Return States (rcode - event)

Success

70 - Redirect the user to the administrator statistics page

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
420 - Error trying to build session data for user/class

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 -

Success - logs user into submission screen


Failure - redirects to callback URL

Examples - Non-working example using GET request:

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

Return GradeMark Function (fid=13)

Additional Function Variables for fid=13

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.

Return States (rcode - event)

Success

80-81 - GradeMark screen/markup status

Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
433 - GradeMark not available yet

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 -

Success - loads a new window containing GradeMark


Failure - redirects user to callback URL

Examples - Non-working example using GET request:

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

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <markup_exists>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>


Failure - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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

Report Turn Around Time (fid=14)

Additional Function Variables for fid=14:

utp: must be set to 2 or 3


fcmd: must be set to 2
starttime: can take in one parameter “starttime” in the format of “YYYY-MM-
DD HH:MM:SS”, of which if specified, will generate the values based on the
given parameter. If none is specified will generate the values based off the
current time
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

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.

Return States (rcode - event)

Success

74 - Report turnaround time retrieval successful



Failure

100-199 - Data Errors


200-299 - TurnitinUK Database Errors
300-399 - Inconsistency Errors
434 - Start time parameter not in the right format

fcmd=1

Not defined yet

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

Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <returndata>, <averagetime15>,


<averagetime10>, <averagetime5>, <averagetime1>

Failure - XML <rcode>, <rmessage>

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 43
TurnitinUK API Manual Section: API Functions

Example Return XML -

<returndata>
<object>
<averagetime15>47</averagetime15>
<averagetime10>48</averagetime10>
<averagetime5>47</averagetime5>
<averagetime1>36</averagetime1>
</object>
<rmessage>Successful!</rmessage>
<rcode>74</rcode>
</returndata>

Examples - Non-working example using GET request:

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

Submission Score (fid=15)

Additional Function Variables for fid=15:

utp: must be set to 2 or 3


objectID: submission to retrieve score or submit score for
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

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.

Return States (rcode - event)

Success

83-84 - Retrieval/Submission of score succeeded



Failure

435 - error in inputting grade for submission

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API returns in XML the retrieved score


Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <score>

fcmd=3

Action on Success - The API returns in XML the set score


Action on Failure - The API returns XML

Return Values -

Success - XML <rcode>, <rmessage>, <score>

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 45
TurnitinUK API Manual Section: API Functions

Anonymous Marking (fid=16)

Additional Function Variables for fid=16:

utp: must be set to 2 or 3


oid: submission to retrieve score or submit score for
anon_reason: reason for revealing authors identity for anonymous marking
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

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.

Return States (rcode - event)

Success

83-84 - Retrieval/Submission of score succeeded



Failure

435 - error in inputting grade for submission

fcmd=1

Action on Success - The API redirects the user to the Administrator Log page for
Anonymous Marking

Action on Failure - The API redirects to callback URL

Examples - Non-working example using GET request:

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

Action on Failure - The API returns XML

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 46
TurnitinUK API Manual Section: API Functions

Return Values -

Success - XML <rcode>, <rmessage>, <object>, <instructor_firstname>,


<instructor_lastname>, <author_lastname>, <author_firstname>, <paperID>,
<assignmentID>, <date_off>, <reason>

Failure - XML <rcode>, <rmessage>

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

Action on Failure - The API returns XML

Examples - Non-working example using GET request:

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

Login Session (fid=17)

Additional Function Variables for fid=17:

utp: must be set to 2 or 3


fcmd: must be set to 2
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

The API function will log in the user described by the user email, first name, last
name, and user type.

Return States (rcode - event)

Success

92 - login succeeded

Failure

210 - user password (optional) did not match


420 - could not create Session (user name does not match email)

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API returns in XML the session ID


Action on Failure - The API returns XML

Return values -

Success - XML <rcode>, <rmessage>, <sessionid>

Examples - Non-working example using GET request:


http://api.turnitin.com/api.asp?gmtime=20091022211&fid=17&fcmd=2&encrypt=0&md5=ae2a071a1
502a8a908ca9ee066c530f8&aid=39219&said=&diagnostic=0&uem=test_user1%40turnitin.com&upw=
&ufn=Test&uln=User1&utp=2

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 48
TurnitinUK API Manual Section: API Functions

End a Session (fid=18)

Additional Function Variables for fid=18:

utp: must be set to 2 or 3


fcmd: must be set to 2
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

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.

Return States (rcode - event)

Success

92 - logout succeeded

Failure

210 - user password (optional) did not match


420 - could not create Session (user name does not match email)
446 - Session ID missing from URL

fcmd=1

Not defined yet

fcmd=2

Action on Success - The API returns in XML the session ID


Action on Failure - The API returns XML

Return values -

Success - XML <rcode>, <rmessage>

Examples - Non-working example using GET request:

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.

1. The request is transmitted over HTTPS


2. The primary account ID must be in the authentication table
3. IP address or mask check
4. The values of fid and fcmd point to a valid function
5. The function’s required parameters are all set and the data is of a valid type, (e.g.
numeric)
6. The MD5 in the request and TurnitinUK’s calculated MD5 have to match. If data is
encrypted, the MD5 uses the unencrypted values
7. The server GMT and request GMT match to the first minutes digit
8. The data constraints are met (e.g. email is between 6-50 characters)

For successful requests, diagnostic information will include:

• All request variables. If encryption is enabled, the encrypted and unencrypted


values are provided.

• Function specific information

1. State of user prior to and after application of function (fid=1, fcmd=1)

2. State of class prior to and after application of function (fid=2,fcmd=1)

3. State of enrollment in class prior to and after application of function (fid=3,


fcmd=1)

4. State of assignment prior to and after application of function (fid=4, fcmd=1)

5. State of paper prior to and after application of function (fid=5, fcmd=1)

6. Return value after application of function (fid=6, fcmd=1 or 2)

7. Return value after application of function (fid=7, fcmd=1 or 2)

8. State of submission before and after deletion (fid=8, fcmd=2)

9. State of password before and after change (fid=9, fcmd=2)

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 50
TurnitinUK API Manual Section: Success States

10. Return value after application of function (fid=10, fcmd=2)

11. Return value after application of function (fid=11, fcmd=2)

12. Diagnostic mode won’t do anything (fid=12, fcmd=2)

13. Return value after application of function (fid=13, fcmd=1 or 2)

14. Return value after application of function (fid=14, fcmd 2)

15. Return value after application of function (fid=15, fcmd 2,3)

17. Returns session-id (fid=17, fcmd 2)

18. Will not show anything (fid=18, fcmd 2)

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

1 General Success State, no errors


10 FID 1, FCMD 1 – successful, send to login
11 FID 1, FCMD 2 – successful, do not send to login
20 FID 2, FCMD 1 – successful, send to login
21 FID 2, FCMD 2 – successful, do not sent to login
30 FID 3, FCMD 1 – successful, send to login
31 FID 3, FCMD 2 – successful, do not send to login
40 FID 4, FCMD 1,5 – successful, redirect user to assignment creation/modification
page
41 FID 4, FCMD 2 – successful
42 FID 4, FCMD 3 – successful
43 FID 4, FCMD 4 – successful
50 FID 5, FCMD 1 – successful, redirect user to submission page
51 FID 5, FCMD 2 - successful
60 FID 6 & 13, FCMD 1 - successful
61 FID 6 & 13, FCMD 2 - successful
70 FID 7, FCMD 1,2 – successful
70 FID 12, FCMD 1 – successful, redirect user to administrator statistics page
71 FID 8, FCMD 2 - successful

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 51
TurnitinUK API Manual Section: Error States

72 FID 10, FCMD 2 - successful


73 FID 11, FCMD 2 – successful
74 FID 14, FCMD 2 – successful
75 FID 9, FCMD 2 - successful
80 FID 13, FCMD 1 - successful, redirect to grademark screen
81 FID 13, FCMD 2 - successful
83 FID 15, FCMD 2 - successful
84 FID 15, FCMD 3 - successful

Error States

Data Errors

100-199

100 Primary account ID missing from URL


101 No HTTPS - the URL was not transmitted via HTTPS
102 GMT missing from URL
103 GMT malformed - the date/time in the URL is bad
104 Email missing from URL
105 Email address is not between 5-75 characters
106 Email address contains white space
107 Email address in URL is malformed
108 Password in URL contained white space
109 Diagnostic value in URL is bad
110 MD5 missing from URL
111 fcmd missing from URL
112 User first name missing from URL or incorrect length
113 User last name missing from URL or incorrect length
114 Class title missing from URL, or not between 5-50 characters
115 Password is not between 6-12 characters
116 fid missing from URL, or does not reference existing function
117 User type missing from URL or is not valid
118 encrypt value in URL is bad or missing
119 Paper author’s first name missing or incorrect length
120 Paper author’s last name missing or incorrect length
121 Paper title missing – Please make sure to include a paper title before submitting
your paper
122 Paper type missing or invalid
123 Assignment title missing or incorrect length
124 ObjectID missing
125 Password is required for function
126 Date start and date due is required for function
127 If one unique ID is used, they must all be used
128 The class end date parameter is not in the right format. Please make sure that
the format is in YYYYMMDD.”
129 The class end date parameter is not set. Please make sure that the class end
date is set if you wish to update the class.
130 The web services url is not valid. Please make sure that the web services url is
a well-formed url.
131 The grade for the object is missing. Please make sure to include a grade for this
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 52
TurnitinUK API Manual Section: Error States

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.

TurnitinUK Database Errors

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

400 Creating new user failed


401 Unauthorized access - user exists, but does not belong to correct primary
account ID or sub-account ID, do not execute function
402 User is not an instructor, must be an instructor to run this function
403 User is not a student, must be a student to run this function
404 FCMD is not valid

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 54
TurnitinUK API Manual Section: Error States

405 Class title is not unique


406 Creating new class failed in fid 2
407 Student failed to join or log in to a class in fid 3
408 Attempt to join new user to account failed
409 Function requires POST request
410 Function requires GET request
411 Creating/Updating/Deleting assignment failed in fid 4
412 Assignment title is not unique
413 Error while trying to save the paper
414 Originality report not generated yet in fid 6, fcmd 1
415 Originality score not available yet in fid 6, fcmd 2
416 Error checking if submission existed for user
417 Error trying to change user password
418 Error trying to delete submission
419 Could not create a new assignment. An assignment with this title already exists
for this class and instructor. Please change the assignment title.
420 Error trying to build up session data for user/class
421 Error trying to retrieve paper submission info for assignment
422 Updating user information failed
423 Updating user information failed because user email was changed to an address
that is already associated with an account
423 TurnitinUK encountered an error while trying to automatically update your user
information. It appears that your Blackboard email address has changed,
and when trying to update the corresponding user profile in TurnitinUK, it was
discovered that email address already belonged to another user. Please update
your email address in your Blackboard user profile to a different email address.
424 Updating class title failed
425 Error trying to sync grades between servers
426 Error trying to sync roster between servers
427 Unable to establish web services session with remove webct server
428 Unable to create WebCT gradebook column for assignment
429 Web services parameters error
430 (This is a general web services error – there could be a number of different
messages that come with it)
431 Error trying to connect back to the Blackboard web service.
432 Students are not allowed to view reports in this assignment
434 The start time you specified is invalid or not formatted correctly (YYYY-MM-DD
HH:MM:SS).
435 Error trying to grade submission.
436 Intitution repository is not available for this account, please change the submit_
papers_to parameter to either 0 (no repository) or 1 (standard repository).
437 The account administrator has set that all papers must be submitted to a
repository, please change the submit_papers_to parameter.
438 Error trying to set submissions to be stored in a standard repository. The
account is using its own private institutional node. Please change the submit_
papers_to parameter.
439 The institutional check is not available for this account. Please set the
institution_check parameter to 0
440 Please specify an email for the new instructor for this course.
441 New instructor specified doesn’t exist, please create the user first.
442 New Instructor is not joined to this account, please join them to the account

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

Paper Submission Errors

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.

Assignment Creation Errors

2025-2324

2025 The class name must be between 5-200 characters


2026 The class enrollment password must be between 4-12 characters
2027 There was an error processing your request
2028 The class end date must be within 6 months of the start date
2029 The end date for this class must occur on or after today
2030 The end date for this class must occur on or after the start date
2031 The end date for this class must occur at least 3 months after the start date
2032 There was an error updating the class end date
2035 There was an error processing your request
2036 There was an error processing your request
2100 User first name missing from URL
2101 User last name missing from URL
2102 Email is missing. Please make sure that your email address has been set
2110 We only allow email addresses with 5-75 characters
2111 The email address cannot contain white space
2112 Please make sure you are entering a valid email address. The email address
you enter can only contain letters, numbers, and the symbols _ (underscore),
- (dash), . (period), ‘ (apostrophe), and + (plus).”
2200 The section enrollment password must be between 4-12 characters
2201 There was an error processing your request
2300 You have entered an invalid date!
2301 You must select a rubric set to user with re-mediation
2302 The assignment title must be between 2-100 characters
2303 The assignment must have a point value between 0 and 1000
2304 The assignment instructions must be less than 1000 characters
2305 The start date for this assignment must occur on or after today
2306 The due date for this assignment must occur on or after the start date
2307 The due date for this assignment must occur within 6 months of the start date
2308 When creating your assignment, the post date must occur on or before the
class end date. The class end date in TurnitinUK is by default set to 6 months
from the day the class was created. The class end date can be changed in the
class update area in TurnitinUK
2309 When creating your assignment, please make sure that the post date is on or
after the due date of the assignment
2310 You must specify a point value for this assignment because this class is using
distributed grading
2314 When modifying your assignment, please make sure that the post date is on or
after the due date of the assignment
2315 There was an error processing your request
2316 There was an error processing your request
2317 There was an error processing your request
2318 You cannot change the search targets because papers have already been

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

FID/FCMD Error Code Table


URL 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
100 X X X X X X X X X X X X X X X
101 X X X X X X X X X X X X X X X
102 X X X X X X X X X X X X X X X
103 X X X X X X X X X X X X X X X
104 X X X X X X X X X X X X X X X
105 X X X X X X X X X X X X X X X
106 X X X X X X X X X X X X X X X
107 X X X X X X X X X X X X X X X
108 X X X X X X X X X X X X X X X
109 X X X X X X X X X X X X X X X
110 X X X X X X X X X X X X X X X
111 X X X X X X X X X X X X X X X
112 X X X X X X X X X X X X X X X
113 X X X X X X X X X X X X X X X
114 X X X X X X X X X X X X X X X
115 X X X X X X X X X X X X X X X
116 X X X X X X X X X X X X X X X
117 X X X X X X X X X X X X X X X
118 X X X X X X X X X X X X X X X
119 X
120 X
121 X
122 X
123 X X X X X
124 X X X X X
125 X
126 X
127 X X X X X X X X X X X
128 X X
129 X
131 X
132 X

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 59
TurnitinUK API Manual Section: FID/FCMD Error Code Table

TurnitinUK Database 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
200 X X X X X X X X X X X X X X X
201 X X X X X X X X X X X X X X X
202 X X X X X X X X X X X X X X X
203 X X X X X X X X X X X X X X X
204 X X X X
205 X X X X
206 X X X X
207 X X X X
208 X X X X
209 X X X X
210 X X X X
211 X X X X X
212 X X X X X
213 X X X X X
214 X
215 X X X X X X X X X X X X X X X
216 X X
217 X X X X X X X X X X X X X X X
218 X X X X X X X X X X X X X
219 X X X X X X X X X X X
220 X X X X X X X
221 X X X X X
222 X X X X X X X X X X X X X
223 X X X X X X X X X
224 X X X X X X X X X
225 X X X X
226 X X
227 X X
232 X
234
235
236
237 X
238

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

FID 17, FID 18,


FCMD 2 FCMD 1, 2
445 X
446 X

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 62
TurnitinUK API Manual Section: FID/FCMD Error Code Table

Paper Submission 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
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

Assignment Creation 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
2025 X
2026 X
2027 X
2028 X
2029 X
2030 X
2031 X
2032 X
2033 X
2034 X
2035 X
2036 X
2100 X X X X X X X X X X X X X X X
2101 X X X X X X X X X X X X X X X
2102 X X X X X X X X X X X X X X X
2110 X X X X X X X X X X X X X X X
2111 X X X X X X X X X X X X X X X
2112 X X X X X X X X X X X X X X X
2300 X
2301 X
2302 X
2303 X
2304 X
2305 X
2306 X
2307 X
2308 X
2309 X
2310 X
2311 X
2312 X
2313 X
2314 X
2315 X
2316 X
2317 X
2318 X
2319 X
2320 X
Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 64
TurnitinUK API Manual Section: FID/FCMD Error Code Table

FID/Data Elements Table


Data Elements to Include in Request

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

Data Elements to Include in the MD5


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
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
pdata
pfn X
pln X
ptl X
ptype X
said 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 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: 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

FID/Encrypt Data Table

Data Elements to Encrypt if Flag is Set


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
ainst
assign X X X X X X X
assignid X X X X X X X
ced
cid X X X X X X X X
cpw X
ctl X X X X X X X X
diagnostic
dis
dtdue
dtstart
encrypt
fcmd
fid
gmtime
newassign X
newupw X
oid X X
pdata
pfn X
pln X
ptl X
ptype X
said 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 X X X
uln X X X X X X X X X X X X X X X
upw 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

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

FID FCMD Function Description GET/POST/BOTH?


The API redirects the user to the
16 1 Administrator Log page for Anonymous BOTH
Marking
The API function will log in the user
17 2 described by the user email, first name, BOTH
last name, and user type.
The API function will log out the user
described by the user email, first name,
18 2 last name, and user type and end the
BOTH
Session with session-id.

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)

dtstart - date the assignment pln: author of paper’s last name


begins (in YYYYMMDD format) (used only for fid=5)

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 72
Glossary Section: Definitions

ptl - title of paper being submitted the user


(used only for fid=5)
username - the user name
ptype - type of file (1=text, 2=file)
(fid=5) utp - user type. 1 for students,
2 for instructors and 3 for
said - sub-account id. The sub- administrators
account id is optional. If a sub-
account is included, it must be
an account beneath the primary
account

shared secret key - Before you


can begin calling the TurnitinUK
API, you must provide a TurnitinUK
representative with a shared
secret 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. The shared
secret key is included at the end of
the MD5 signature

tem - email of instructor who


created class (only applicable if
fid=3)

uem - user email. The user email is


used as the TurnitinUK user name.
The email address must be 6-50
characters in length

ufn - user first name. Must be 1-50


characters in length

uid - unique user id. Either a third


party user id, or possibly a unique
TurnitinUK user id

uln - user last name. Must be 1-50


characters in length

upw - user password. The user


password is optional, must be 6-12
characters in length, and must
contain at least one letter and one
number. If this variable is not in-
cluded and the user is not already
registered, we will automatically
generate a password and email it to

Copyright © 1998 – 2010 iParadigms, LLC. All rights reserved. TurnitinUK API Manual: 73