The ILLiad Web Platform API

The ILLiad Web Platform provides programmatic access to your ILLiad installation. The data is available in either JSON or XML formatted over HTTP.

warning

The ILLiad Web Platform was introduced in ILLiad version 8.4.

Getting Started

info

See the ILLiad Integration document attached to the bottom of this web for more information on expected workflows with external systems. The document covers scenarios of both ILLiad-born and external-born requests and expected API calls in each scenario.

Generating an API Key

You will first need to generate an API Key for your application and create an entry in the WebPlatformConfig table in the ILLiad Customization Manager. An API Key is required for all secured methods. See Configuring the ILLiad Web Platform for more information.

Each application accessing the Web Platform should have its own unique API Key. If for some reason it becomes apparent that an individual application has been compromised, an individual API Key can be deauthorized from the Customization Manager by removing the WebPlatform config records. If all applications use the same APIKey access to all will be affected. To prevent unauthorized distribution of an API Key, you should only make requests to the ILLiad Web Platform using server-side scripting such as ASP or PHP. Client-side scripting (like Javascript) will expose your API Key which can lead to ill effects. Protect your API keys!

info

For brevity, the API Key used in examples in this documentation will be ABC123. Typically the key will be a longer alphanumeric string that looks more like 71ed0900-97aa-4157-ad9f-e74bcfa5e709.

Versions and Updates

We will introduce API changes when necessary/possible, and update the API version number (i.e. v1) when a breaking change is made. Additions to the API does not necessarily mean the API version will change but changes will always result in the Web Platform version number being incremented. For documentation purposes, each request will indicate the minimum Web Platform version required.

If the version is not provided in the Accept header it is assumed that the most recent version of the API should be used. To explicitly request a response from a specific API version, the version should be specified in the Accept HTTP header.

GET /ILLiadWebPlatform/SystemInfo/PlatformVersion HTTP/1.1
Host: your.illiad.edu
Accept: application/json; version=1

Some requests may be introduced to newer versions of the API and may not be backward compatible. A minimum API and Web Platform version will be noted in the documentation.

Making Requests

Authentication

danger

You must use SSL (HTTPS instead of HTTP) to access the ILLiad Web Platform.

To authenticate with the API, you must supply an ApiKey HTTP Header when making a request to a secured action. For example:

GET /ILLiadWebPlatform/SystemInfo/SecurePlatformVersion HTTP/1.1
Host: your.illiad.edu
ApiKey: ABC123
Accept: application/json; version=1

Some requests are considered public and will not require an API Key. The authorization for each action will be noted in documentation as either secured or public.

Response Formats

The request examples retrieve the data in JSON format. If you would like the data in XML format, change the media type of the accept header from "application/json" to "application/xml."

GET /ILLiadWebPlatform/SystemInfo/PlatformVersion HTTP/1.1
Host: your.illiad.edu
Accept: application/xml

OData Support

Filtering | Sorting | Limiting Results

Some of the ILLiad Web Platform requests support the use of OData query options to help filter and order result data. Support for OData query actions will be noted+ in request documentation.

Filtering

The $filter option allows filtering results by applying a Boolean expression. The filter expressions include logical and arithmetic operators, string functions, and date functions.

Filters can use grouped conditions indicated by parentheses. Comparisons of time values must use the following format:

datetime'<time value>'

For example, datetime'2010-07-15' or datetime'2010-07-15T16:19:54Z'.

Filter Operators

eq	Equal
ne	Not Equal
gt	Greater than
ge	Greater than or equal
lt	Less than
le	Less than or equal
and	Logical and
or	Logical or
not	Logical Negation

Filter Functions

startswith	Starts with value	Example: startwith(TransactionStatus, 'Request Held')
substringof	Starts with value	Example: substringof('CCG', CopyrightComp)
endswith	Ends with value	Example: endswith(TransactionStatus, 'Rush')
year	Gets the date of a DateTime field	Example: year(TransactionDate)
month	Gets the date of a DateTime field	Example: month(TransactionDate)
day	Gets the date of a DateTime field	Example: day(TransactionDate)

Examples

Return active user requests for a user whose UserName is jdoe and the TransactionStatus is "Request Sent".

GET /ILLiadWebPlatform/Transaction/UserRequests/jdoe?$filter=TransactionStatus eq 'Request Sent' HTTP/1.1
Host: your.illiad.edu
ApiKey: ABC123
Accept: application/json

Return active user requests for a user whose UserName is jdoe and the LastOverdueNoticeSent was 2 or higher.

GET /ILLiadWebPlatform/Transaction/UserRequests/jdoe?$filter=LastOverdueNoticeSent ge 2 HTTP/1.1
Host: your.illiad.edu
ApiKey: ABC123
Accept: application/json

Return active user requests for a user whose UserName is jdoe and the TransactionStatus starts with Request Held and the last time the request was routed was June 2013.

GET /ILLiadWebPlatform/Transaction/UserRequests/jdoe?$filter=(startswith (TransactionStatus, 'Request Held')) and (year(TransactionDate) eq 2013 and month(TransactionDate) eq 6) HTTP/1.1
Host: your.illiad.edu
ApiKey: ABC123
Accept: application/json

Sorting

To sort the results, use the $orderby query option.

Example

Sort active user requests for user whose UserName is jdoe by Request Type in ascending order and creation date in descending order

GET /ILLiadWebPlatform/Transaction/UserRequests/jdoe?$orderby=RequestType,CreationDate desc HTTP/1.1
Host: your.illiad.edu
ApiKey: ABC123
Accept: application/json

Limiting Results

$top

Determines a maximum number of records to return.

Example: Retrieves the first 10 active user requests for the user whose UserName is jdoe

GET /ILLiadWebPlatform/Transaction/UserRequests/jdoe?$top=10 HTTP/1.1
Host: your.illiad.edu
ApiKey: ABC123
Accept: application/json

$skip

Sets the number of records to skip before retrieving records in a collection. This is useful when combined with $top to page requests.

Example: Retrieve records 21 - 30 of active user requests for the user whose UserName is jdoe

GET /ILLiadWebPlatform/Transaction/UserRequests/jdoe?$top=10&skip=20 HTTP/1.1
Host: your.illiad.edu
ApiKey: ABC123
Accept: application/json

System Information

API Version | PlatformVersion | Secure Platform Version

For troubleshooting purposes and getting started, a few basic responses can be retrieved that retrieve system information.

API Version

Authorization: Public
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.5.0.0

Use the API Version request to retrieve the current API version of the ILLiad Web Platform.

Example API Version Request

GET /ILLiadWebPlatform/SystemInfo/APIVersion HTTP/1.1
Host: your.illiad.edu
Accept: application/json

Example API Version Response

"Current API Version: 1"

PlatformVersion

Authorization: Public
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.4.0.0

Use the PlatformVersion request to retrieve the current version of the ILLiad Web Platform.

Example Platform Version Request

GET /ILLiadWebPlatform/SystemInfo/PlatformVersion HTTP/1.1
Host: your.illiad.edu
Accept: application/json

Example Platform Version Response

"ILLiad Platform Version: 8.5.0.0"

Secure Platform Version

Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.4.0.0

Use the PlatformVersion request to securely retrieve the current version of the ILLiad Web Platform.

Example Secure Platform Version Request

GET /ILLiadWebPlatform/SystemInfo/SecurePlatformVersion HTTP/1.1
Host: your.illiad.edu
APIKey: ABC123
Accept: application/json

Example Secure Platform Version Response

"ILLiad Secure Platform Version: 8.5.0.0"

Transactions

Retrieving Requests by Transaction Number

Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.6.0.0

The transaction request will retrieve transaction details for a given transaction number.

Example Transaction Request

curl -H 'Accept: application/json'
https://your.illiad.edu/ILLiadWebPlatform/Transaction/6

Example Transaction Response

{
"TransactionNumber": 6,
"UserName": "jdoe",
"RequestType": "Article",
"LoanAuthor": null,
"LoanTitle": null,
"LoanPublisher": null,
"LoanPlace": null,
"LoanDate": null,
"LoanEdition": null,
"PhotoJournalTitle": "The electronic library : the international journal for minicomputer, microcomputer, and software applications in libraries.",
"PhotoJournalVolume": null,
"PhotoJournalIssue": null,
"PhotoJournalMonth": null,
"PhotoJournalYear": null,
"PhotoJournalInclusivePages": "23-34",
"PhotoArticleAuthor": "Cohen, Calsada",
"PhotoArticleTitle": "Web accessible Databases",
"CitedIn": null,
"CitedTitle": null,
"CitedDate": null,
"CitedVolume": null,
"CitedPages": null,
"NotWantedAfter": null,
"AcceptNonEnglish": false,
"AcceptAlternateEdition": true,
"ArticleExchangeUrl": null,
"ArticleExchangePassword": null,
"TransactionStatus": "Request Sent",
"TransactionDate": "2013-06-07T09:05:37.19",
"ISSN": "0264-0473",
"ILLNumber": "500XXXXXXX/5YYZZOO",
"ESPNumber": "9172203",
"LendingString": null,
"BaseFee": null,
"PerPage": null,
"Pages": null,
"DueDate": null,
"RenewalsAllowed": false,
"SpecIns": null,
"Pieces": null,
"LibraryUseOnly": "Yes",
"AllowPhotocopies": false,
"LendingLibrary": "GETIT",
"ReasonForCancellation": null,
"CallNumber": null,
"Location": null,
"Maxcost": "24.00",
"ProcessType": "Borrowing",
"ItemNumber": null,
"LenderAddressNumber": 1,
"Ariel": false,
"Patron": null,
"PhotoItemAuthor": null,
"PhotoItemPlace": null,
"PhotoItemPublisher": null,
"PhotoItemEdition": null,
"DocumentType": "Article",
"InternalAcctNo": null,
"PriorityShipping": null,
"Rush": "Regular",
"CopyrightAlreadyPaid": "Yes",
"WantedBy": null,
"SystemID": "OTH",
"ReplacementPages": null,
"IFMCost": null,
"CopyrightPaymentMethod": null,
"ShippingOptions": null,
"CCCNumber": null,
"IntlShippingOptions": null,
"ShippingAcctNo": null,
"ReferenceNumber": null,
"CopyrightComp": "US:CCL",
"TAddress": null,
"TAddress": null,
"TAddress2": null,
"TCity": null,
"TState": null,
"TZip": null,
"TCountry": null,
"TFax": null,
"TEMailAddress": null,
"TNumber": null,
"HandleWithCare": false,
"CopyWithCare": false,
"RestrictedUse": false,
"ReceivedVia": null,
"CancellationCode": null,
"BillingCategory": null,
"CCSelected": "No",
"OriginalTN": null,
"OriginalNVTGC": null,
"InProcessDate": null,
"InvoiceNumber": null,
"BorrowerTN": null,
"WebRequestForm": null,
"TName": null,
"TAddress3": null,
"IFMPaid": null,
"BillingAmount": null,
"ConnectorErrorStatus": null,
"BorrowerNVTGC": null,
"CCCOrder": null,
"ShippingDetail": null,
"ISOStatus": null,
"OdysseyErrorStatus": null,
"WorldCatLCNumber": null,
"Locations": null,
"FlagType": null,
"FlagNote": "",
"CreationDate": "2013-06-07T09:01:22.47",
"ItemInfo1": null,
"ItemInfo2": null,
"ItemInfo3": null,
"ItemInfo4": null,
"ItemInfo5": "Yes",
"SpecialService": null,
"DeliveryMethod": null,
"Web": null,
"PMID": null,
"DOI": null,
"LastOverdueNoticeSent": null,
"ExternalRequest": null
}

Retrieving Requests for User

Authorization: Secured
Supports OData: Yes
Minimum API Version: 1
Minimum Web Platform Version: 8.5.0.0

The UserRequests request will retrieve all transactions associated with a given UserName. This request is secured and requires an API key. This request has OData Support for filtering, ordering, and limiting results.

Example User Requests Request

curl -H 'Accept: application/json'
https://your.illiad.edu/ILLiadWebPlatform/Transaction/UserRequests/jdoe

Example User Requests Response

[{
"TransactionNumber": 6,
"UserName": "jdoe",
"RequestType": "Article",
"LoanAuthor": null,
"LoanTitle": null,
"LoanPublisher": null,
"LoanPlace": null,
"LoanDate": null,
"LoanEdition": null,
"PhotoJournalTitle": "The electronic library",
"PhotoJournalVolume": null,
"PhotoJournalIssue": null,
"PhotoJournalMonth": null,
"PhotoJournalYear": null,
"PhotoJournalInclusivePages": "23-34",
"PhotoArticleAuthor": "Cohen, Calsada",
"PhotoArticleTitle": "Web accessible Databases",
"CitedIn": null,
"CitedTitle": null,
"CitedDate": null,
"CitedVolume": null,
"CitedPages": null,
"NotWantedAfter": null,
"AcceptNonEnglish": false,
"AcceptAlternateEdition": true,
"ArticleExchangeUrl": null,
"ArticleExchangePassword": null,
"TransactionStatus": "Request Sent",
"TransactionDate": "2013-06-07T09:05:37.19",
"ISSN": "0264-0473",
"ILLNumber": "500XXXXXXX/5YYZZOO",
"ESPNumber": "9172203",
"LendingString": null,
"BaseFee": null,
"PerPage": null,
"Pages": null,
"DueDate": null,
"RenewalsAllowed": false,
"SpecIns": null,
"Pieces": null,
"LibraryUseOnly": "Yes",
"AllowPhotocopies": false,
"LendingLibrary": "GETIT",
"ReasonForCancellation": null,
"CallNumber": null,
"Location": null,
"Maxcost": "24.00",
"ProcessType": "Borrowing",
"ItemNumber": null,
"LenderAddressNumber": 1,
"Ariel": false,
"Patron": null,
"PhotoItemAuthor": null,
"PhotoItemPlace": null,
"PhotoItemPublisher": null,
"PhotoItemEdition": null,
"DocumentType": "Article",
"InternalAcctNo": null,
"PriorityShipping": null,
"Rush": "Regular",
"CopyrightAlreadyPaid": "Yes",
"WantedBy": null,
"SystemID": "OTH",
"ReplacementPages": null,
"IFMCost": null,
"CopyrightPaymentMethod": null,
"ShippingOptions": null,
"CCCNumber": null,
"IntlShippingOptions": null,
"ShippingAcctNo": null,
"ReferenceNumber": null,
"CopyrightComp": "US:CCL",
"TAddress": null,
"TAddress2": null,
"TCity": null,
"TState": null,
"TZip": null,
"TCountry": null,
"TFax": null,
"TEMailAddress": null,
"TNumber": null,
"HandleWithCare": false,
"CopyWithCare": false,
"RestrictedUse": false,
"ReceivedVia": null,
"CancellationCode": null,
"BillingCategory": null,
"CCSelected": "No",
"OriginalTN": null,
"OriginalNVTGC": null,
"InProcessDate": null,
"InvoiceNumber": null,
"BorrowerTN": null,
"WebRequestForm": null,
"TName": null,
"TAddress3": null,
"IFMPaid": null,
"BillingAmount": null,
"ConnectorErrorStatus": null,
"BorrowerNVTGC": null,
"CCCOrder": null,
"ShippingDetail": null,
"ISOStatus": null,
"OdysseyErrorStatus": null,
"WorldCatLCNumber": null,
"Locations": null,
"FlagType": null,
"FlagNote": "",
"CreationDate": "2013-06-07T09:01:22.47",
"ItemInfo1": null,
"ItemInfo2": null,
"ItemInfo3": null,
"ItemInfo4": null,
"ItemInfo5": "Yes",
"SpecialService": null,
"DeliveryMethod": null,
"Web": null,
"PMID": null,
"DOI": null,
"LastOverdueNoticeSent": null,
"ExternalRequest": null
}]

Routing transaction request

HTTP Verb: PUT
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

The route transaction request will route a transaction to specified transaction status. The action will also add a tracking entry and mark an update to the history table to indicate a change was made to the request. Routing rules associated with the status will be processed. The UserName of the tracking and history entries will be set to the WebPlatformDescription associated with the API key making the request.

Required parameters

Status	The status of the transaction should be routed to

Example Route Transaction Request

PUT https://your.illiad.edu/ILLiadWebPlatform/transaction/4567/route
Content-Type: application/json
{ "Status" : "Awaiting Request Processing" }

Response

Example Route Transaction Response

{
"TransactionNumber": 6,
"UserName": "jdoe",
"RequestType": "Article",
"LoanAuthor": null,
"LoanTitle": null,
"LoanPublisher": null,
"LoanPlace": null,
"LoanDate": null,
"LoanEdition": null,
"PhotoJournalTitle": "The electronic library : the international journal for
minicomputer, microcomputer, and software applications in libraries.",
"PhotoJournalVolume": null,
"PhotoJournalIssue": null,
"PhotoJournalMonth": null,
"PhotoJournalYear": null,
"PhotoJournalInclusivePages": "23-34",
"PhotoArticleAuthor": "Cohen, Calsada",
"PhotoArticleTitle": "Web accessible Databases",
"CitedIn": null,
"CitedTitle": null,
"CitedDate": null,
"CitedVolume": null,
"CitedPages": null,
"NotWantedAfter": null,
"AcceptNonEnglish": false,
"AcceptAlternateEdition": true,
"ArticleExchangeUrl": null,
"ArticleExchangePassword": null,
"TransactionStatus": "Awaiting Request Processing",
"TransactionDate": "2013-06-07T09:05:37.19",
"ISSN": "0264-0473",
"ILLNumber": "500XXXXXXX/5YYZZOO",
"ESPNumber": "9172203",
"LendingString": null,
"BaseFee": null,
"PerPage": null,
"Pages": null,
"DueDate": null,
"RenewalsAllowed": false,
"SpecIns": null,
"Pieces": null,
"LibraryUseOnly": "Yes",
"AllowPhotocopies": false,
"LendingLibrary": "GETIT",
"ReasonForCancellation": null,
"CallNumber": null,
"Location": null,
"Maxcost": "24.00",
"ProcessType": "Borrowing",
"ItemNumber": null,
"LenderAddressNumber": 1,
"Ariel": false,
"Patron": null,
"PhotoItemAuthor": null,
"PhotoItemPlace": null,
"PhotoItemPublisher": null,
"PhotoItemEdition": null,
"DocumentType": "Article",
"InternalAcctNo": null,
"PriorityShipping": null,
"Rush": "Regular",
"CopyrightAlreadyPaid": "Yes",
"WantedBy": null,
"SystemID": "OTH",
"ReplacementPages": null,
"IFMCost": null,
"CopyrightPaymentMethod": null,
"ShippingOptions": null,
"CCCNumber": null,
"IntlShippingOptions": null,
"ShippingAcctNo": null,
"ReferenceNumber": null,
"CopyrightComp": "US:CCL",
"TAddress": null,
"TAddress": null,
"TAddress2": null,
"TCity": null,
"TState": null,
"TZip": null,
"TCountry": null,
"TFax": null,
"TEMailAddress": null,
"TNumber": null,
"HandleWithCare": false,
"CopyWithCare": false,
"RestrictedUse": false,
"ReceivedVia": null,
"CancellationCode": null,
"BillingCategory": null,
"CCSelected": "No",
"OriginalTN": null,
"OriginalNVTGC": null,
"InProcessDate": null,
"InvoiceNumber": null,
"BorrowerTN": null,
"WebRequestForm": null,
"TName": null,
"TAddress3": null,
"IFMPaid": null,
"BillingAmount": null,
"ConnectorErrorStatus": null,
"BorrowerNVTGC": null,
"CCCOrder": null,
"ShippingDetail": null,
"ISOStatus": null,
"OdysseyErrorStatus": null,
"WorldCatLCNumber": null,
"Locations": null,
"FlagType": null,
"FlagNote": "",
"CreationDate": "2013-06-07T09:01:22.47",
"ItemInfo1": null,
"ItemInfo2": null,
"ItemInfo3": null,
"ItemInfo4": null,
"ItemInfo5": "Yes",
"SpecialService": null,
"DeliveryMethod": null,
"Web": null,
"PMID": null,
"DOI": null,
"LastOverdueNoticeSent": null,
"ExternalRequest": null
}

HTTP Status Code	Description
200	OK (Successfully routed request)
400	Bad Request Example Bad Request `<br>{<br> "Message": "Arguments cannot be null: model"<br>}<br>`
401	Unauthorized
404	Resource Not Found
500	Internal Server Error (Unexpected error)

Marking transaction filled

HTTP Verb: PUT
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

The borrowing request will be marked as being filled by the lender.

A history entry will be added to indicate the lender has shipped the request.

info

Note the UserName of the history entry will be set to the WebPlatformDescription associated with the API key making the request.

Required parameters

Lender	Indicates the lender that filled the request

Example Fill Transaction Request

PUT https://your.illiad.edu/ILLiadWebPlatform/transaction/4567/filled
Content-Type: application/json
{ "Lender" : "OSU" }

Response

Example Fill Transaction Response

{
"TransactionNumber": 4567,
"Username": "jdoe",
"RequestType": "Article",
"LoanAuthor": null,
"LoanTitle": null,
"LoanPublisher": null,
"LoanPlace": null,
"LoanDate": null,
"LoanEdition": null,
"PhotoJournalTitle": "The electronic library : the international journal for
minicomputer, microcomputer, and software applications in libraries.",
"PhotoJournalVolume": null,
"PhotoJournalIssue": null,
"PhotoJournalMonth": null,
"PhotoJournalYear": null,
"PhotoJournalInclusivePages": "23-34",
"PhotoArticleAuthor": "Cohen, Calsada",
"PhotoArticleTitle": "Web accessible Databases",
"CitedIn": null,
"CitedTitle": null,
"CitedDate": null,
"CitedVolume": null,
"CitedPages": null,
"NotWantedAfter": null,
"AcceptNonEnglish": false,
"AcceptAlternateEdition": true,
"ArticleExchangeUrl": null,
"ArticleExchangePassword": null,
"TransactionStatus": "Request Sent",
"TransactionDate": "2013-06-07T09:05:37.19",
"ISSN": "0264-0473",
"ILLNumber": "500XXXXXXX/5YYZZOO",
"ESPNumber": "9172203",
"LendingString": null,
"BaseFee": null,
"PerPage": null,
"Pages": null,
"DueDate": null,
"RenewalsAllowed": false,
"SpecIns": null,
"Pieces": null,
"LibraryUseOnly": "Yes",
"AllowPhotocopies": false,
"LendingLibrary": "OSU",
"ReasonForCancellation": null,
"CallNumber": null,
"Location": null,
"Maxcost": "24.00",
"ProcessType": "Borrowing",
"ItemNumber": null,
"LenderAddressNumber": 1,
"Ariel": false,
"Patron": null,
"PhotoItemAuthor": null,
"PhotoItemPlace": null,
"PhotoItemPublisher": null,
"PhotoItemEdition": null,
"DocumentType": "Article",
"InternalAcctNo": null,
"PriorityShipping": null,
"Rush": "Regular",
"CopyrightAlreadyPaid": "Yes",
"WantedBy": null,
"SystemID": "OTH",
"ReplacementPages": null,
"IFMCost": null,
"CopyrightPaymentMethod": null,
"ShippingOptions": null,
"CCCNumber": null,
"IntlShippingOptions": null,
"ShippingAcctNo": null,
"ReferenceNumber": null,
"CopyrightComp": "US:CCL",
"TAddress": null,
"TAddress": null,
"TAddress2": null,
"TCity": null,
"TState": null,
"TZip": null,
"TCountry": null,
"TFax": null,
"TEMailAddress": null,
"TNumber": null,
"HandleWithCare": false,
"CopyWithCare": false,
"RestrictedUse": false,
"ReceivedVia": null,
"CancellationCode": null,
"BillingCategory": null,
"CCSelected": "No",
"OriginalTN": null,
"OriginalNVTGC": null,
"InProcessDate": null,
"InvoiceNumber": null,
"BorrowerTN": null,
"WebRequestForm": null,
"TName": null,
"TAddress3": null,
"IFMPaid": null,
"BillingAmount": null,
"ConnectorErrorStatus": null,
"BorrowerNVTGC": null,
"CCCOrder": null,
"ShippingDetail": null,
"ISOStatus": null,
"OdysseyErrorStatus": null,
"WorldCatLCNumber": null,
"Locations": null,
"FlagType": null,
"FlagNote": "",
"CreationDate": "2013-06-07T09:01:22.47",
"ItemInfo1": null,
"ItemInfo2": null,
"ItemInfo3": null,
"ItemInfo4": null,
"ItemInfo5": "Yes",
"SpecialService": null,
"DeliveryMethod": null,
"Web": null,
"PMID": null,
"DOI": null,
"LastOverdueNoticeSent": null,
"ExternalRequest": null
}

HTTP Status Code	Description
200	OK (Successfully routed request)
400	Bad Request Example Bad Request `<br>{<br> "Message": "The request is invalid.",<br> "ModelState": {<br> "model.Lender": [<br> "The Lender field is required."<br> ]<br> }<br>}<br>`
401	Unauthorized
404	Resource Not Found
500	Internal Server Error (Unexpected error)

Marking transaction unfilled

HTTP Verb: PUT
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

Marks a borrowing request as being unfilled.

The ILLiad request will be routed to the Awaiting Unfilled Processingqueue.
The reason will be added as a note to the request.

info

Note the username of the tracking and history entries will be set to the WebPlatformDescription associated with the API key making the request.

Required parameters

Reason	Indicates a reason the request is being marked unfilled

Example Unfilled Transaction Request

PUT https://your.illiad.edu/ILLiadWebPlatform/transaction/4567/unfilled
Content-Type: application/json
{ "Reason" : "Not available on shelf" }

Response

Example Unfilled Transaction Response

{
"TransactionNumber": 4567,
"Username": "jdoe",
"RequestType": "Article",
"LoanAuthor": null,
"LoanTitle": null,
"LoanPublisher": null,
"LoanPlace": null,
"LoanDate": null,
"LoanEdition": null,
"PhotoJournalTitle": "The electronic library : the international journal for
minicomputer, microcomputer, and software applications in libraries.",
"PhotoJournalVolume": null,
"PhotoJournalIssue": null,
"PhotoJournalMonth": null,
"PhotoJournalYear": null,
"PhotoJournalInclusivePages": "23-34",
"PhotoArticleAuthor": "Cohen, Calsada",
"PhotoArticleTitle": "Web accessible Databases",
"CitedIn": null,
"CitedTitle": null,
"CitedDate": null,
"CitedVolume": null,
"CitedPages": null,
"NotWantedAfter": null,
"AcceptNonEnglish": false,
"AcceptAlternateEdition": true,
"ArticleExchangeUrl": null,
"ArticleExchangePassword": null,
"TransactionStatus": "Awaiting Unfilled Processing",
"TransactionDate": "2013-06-07T09:05:37.19",
"ISSN": "0264-0473",
"ILLNumber": "500XXXXXXX/5YYZZOO",
"ESPNumber": "9172203",
"LendingString": null,
"BaseFee": null,
"PerPage": null,
"Pages": null,
"DueDate": null,
"RenewalsAllowed": false,
"SpecIns": null,
"Pieces": null,
"LibraryUseOnly": "Yes",
"AllowPhotocopies": false,
"LendingLibrary": "OSU",
"ReasonForCancellation": null,
"CallNumber": null,
"Location": null,
"Maxcost": "24.00",
"ProcessType": "Borrowing",
"ItemNumber": null,
"LenderAddressNumber": 1,
"Ariel": false,
"Patron": null,
"PhotoItemAuthor": null,
"PhotoItemPlace": null,
"PhotoItemPublisher": null,
"PhotoItemEdition": null,
"DocumentType": "Article",
"InternalAcctNo": null,
"PriorityShipping": null,
"Rush": "Regular",
"CopyrightAlreadyPaid": "Yes",
"WantedBy": null,
"SystemID": "OTH",
"ReplacementPages": null,
"IFMCost": null,
"CopyrightPaymentMethod": null,
"ShippingOptions": null,
"CCCNumber": null,
"IntlShippingOptions": null,
"ShippingAcctNo": null,
"ReferenceNumber": null,
"CopyrightComp": "US:CCL",
"TAddress": null,
"TAddress": null,
"TAddress2": null,
"TCity": null,
"TState": null,
"TZip": null,
"TCountry": null,
"TFax": null,
"TEMailAddress": null,
"TNumber": null,
"HandleWithCare": false,
"CopyWithCare": false,
"RestrictedUse": false,
"ReceivedVia": null,
"CancellationCode": null,
"BillingCategory": null,
"CCSelected": "No",
"OriginalTN": null,
"OriginalNVTGC": null,
"InProcessDate": null,
"InvoiceNumber": null,
"BorrowerTN": null,
"WebRequestForm": null,
"TName": null,
"TAddress3": null,
"IFMPaid": null,
"BillingAmount": null,
"ConnectorErrorStatus": null,
"BorrowerNVTGC": null,
"CCCOrder": null,
"ShippingDetail": null,
"ISOStatus": null,
"OdysseyErrorStatus": null,
"WorldCatLCNumber": null,
"Locations": null,
"FlagType": null,
"FlagNote": "",
"CreationDate": "2013-06-07T09:01:22.47",
"ItemInfo1": null,
"ItemInfo2": null,
"ItemInfo3": null,
"ItemInfo4": null,
"ItemInfo5": "Yes",
"SpecialService": null,
"DeliveryMethod": null,
"Web": null,
"PMID": null,
"DOI": null,
"LastOverdueNoticeSent": null,
"ExternalRequest": null
}

HTTP Status Code	Description
200	OK (Successfully marked request unfilled)
400	Bad Request Example Bad Request `<br>{<br> "Message": "The Transaction is at an invalid state. Request 12345 is not assigned to Borrowing process type."<br>}<br>`
401	Unauthorized
404	Resource Not Found
500	Internal Server Error (Unexpected error)

Create a transaction request

HTTP Verb: POST
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

Creates a new request. Routing rules will be applied to the transaction after it is created.

info

Note the username of the tracking and history entries will be set to the WebPlatformDescription associated with the API key making the request.

Parameters

Parameters can be set from any existing field from the ILLiad transactions table.

Required parameters

Username OR ExternalUserId	Indicates the username of the new transaction. As of ILLiad 9.2, an external user ID may also be used if the user's ILLiad username is not available in the external system (see ExternalUserId Parameterbelow).
ProcessType	Indicates the ILLiad ProcessType. Allowed values: Borrowing DocDel Lending
*LendingLibrary	Note (info): LendingLibrary is only required if ProcessType is Lending.

ExternalUserID Parameter [ILLiad 9.2 Only]

A transaction can be created for a user using an external user ID provided by the integrating external system if the ILLiad username is not available. This external ID must correspond to an existing ILLiad field in the Users table that contains information to uniquely identify the user, for example, the EMailAddress or Number fields. After the matching ILLiad field is identified, the name of the ILLiad field should then be put into the ExternalUserIdMapping column of the entry for the external system in the Customization Manager's WebPlatformConfig table.

info

The ExternalUserId will only be included in the body of the response if the request is created using this parameter.

warning

ExternalUserID vs. Username

When creating a request, the external system can supply either the Username, ExternalUserId, or both. If both are supplied, then each must uniquely identify the same ILLiad user. If a single user cannot be identified in ILLiad with the information supplied, an error will be returned.

info

Example

If integrating ILLiad with an ILS that stores the user's student ID number, but not the ILLiad username, a request could be created for the user with this information according to the following steps:

The entry for the ILS in the WebPlatformConfig table should contain the name of the ILLiad field that stores the user's student ID number in the ExternalUserIdMapping column (in this case, Number).
The request body POSTed to the Create Transaction endpoint should pass the user's ID number from the ILS user record in the ExternalUserId field. No value should be passed to the Username field.
The response will contain the user's ID number in the ExternalUserId field and create a transaction for that ILLiad user.

Click for Example Create Transaction Call with ExternalUserId

The following example will create a transaction for a user using the ILLiad Number field as the external user ID.

WebPlatformConfig Table Entry

Column NameValue

ID	This value is auto-generated
NVTGC	ILL
API Key	This value is auto-generated
BaseWebServiceUrl	http://ILLiadWebPlatform
Description	Name of integrating system (e.g., Alma)
ExternalUserIdMapping	Number

Example Create Transaction Request

POST https://your.illiad.edu/ILLiadWebPlatform/transaction/
Content-Type: application/json
{
 "ExternalUserId" : "123456789",
 "RequestType" : "Article",
 "ProcessType" : "Borrowing",
 "PhotoJournalTitle" : "Journal of Interlibrary Loan,Document Delivery & Electronic Reserve",
 "PhotoArticleTitle" : "Interlibrary Loan in the United States: An Analysis of Academic Libraries in a Digital Age",
 "PhotoArticleAuthor" : "Williams, Joseph; Woolwine, David",
 "PhotoJournalVolume" : "21",
 "PhotoJournalIssue" : "4",
 "PhotoJournalYear" : "2011",
 "PhotoJournalInclusivePages" : "165-183",
 "ISSN": "1072-303X",
 "TransactionStatus": "Awaiting Request Processing",
 "CopyrightAlreadyPaid": true,
}

Response

Example Create Transaction Response

{
"TransactionNumber": 125,
"ExternalUserId": "123456789",
"RequestType": "Article",
"LoanAuthor": null,
"LoanTitle": null,
"LoanPublisher": null,
"LoanPlace": null,
"LoanDate": null,
"LoanEdition": null,
"PhotoJournalTitle" : "Journal of Interlibrary Loan,Document Delivery & Electronic Reserve",
"PhotoJournalVolume": null,
"PhotoJournalIssue": null,
"PhotoJournalMonth": null,
"PhotoJournalYear": null,
"PhotoJournalInclusivePages": "165-183",
"PhotoArticleAuthor" : "Williams, Joseph; Woolwine, David",
"PhotoArticleTitle" : "Interlibrary Loan in the United States: An Analysis of Academic Libraries in a Digital Age",
"CitedIn": null,
"CitedTitle": null,
"CitedDate": null,
"CitedVolume": null,
"CitedPages": null,
"NotWantedAfter": null,
"AcceptNonEnglish": false,
"AcceptAlternateEdition": true,
"ArticleExchangeUrl": null,
"ArticleExchangePassword": null,
"TransactionStatus": "Awaiting Request Processing",
"TransactionDate": "2016-10-01T10:25:37.19",
"ISSN": "1072-303X",
"ILLNumber": null,
"ESPNumber": null,
"LendingString": null,
"BaseFee": null,
"PerPage": null,
"Pages": null,
"DueDate": null,
"RenewalsAllowed": false,
"SpecIns": null,
"Pieces": null,
"LibraryUseOnly": null,
"AllowPhotocopies": false,
"LendingLibrary": null,
"ReasonForCancellation": null,
"CallNumber": null,
"Location": null,
"Maxcost": null,
"ProcessType": "Borrowing",
"ItemNumber": null,
"LenderAddressNumber": null,
"Ariel": false,
"Patron": null,
"PhotoItemAuthor": null,
"PhotoItemPlace": null,
"PhotoItemPublisher": null,
"PhotoItemEdition": null,
"DocumentType": "Article",
"InternalAcctNo": null,
"PriorityShipping": null,
"Rush": "Regular",
"CopyrightAlreadyPaid": "Yes",
"WantedBy": null,
"SystemID": "OTH",
"ReplacementPages": null,
"IFMCost": null,
"CopyrightPaymentMethod": null,
"ShippingOptions": null,
"CCCNumber": null,
"IntlShippingOptions": null,
"ShippingAcctNo": null,
"ReferenceNumber": null,
"CopyrightComp": "US:CCL",
"TAddress": null,
"TAddress": null,
"TAddress2": null,
"TCity": null,
"TState": null,
"TZip": null,
"TCountry": null,
"TFax": null,
"TEMailAddress": null,
"TNumber": null,
"HandleWithCare": false,
"CopyWithCare": false,
"RestrictedUse": false,
"ReceivedVia": null,
"CancellationCode": null,
"BillingCategory": null,
"CCSelected": null,
"OriginalTN": null,
"OriginalNVTGC": null,
"InProcessDate": null,
"InvoiceNumber": null,
"BorrowerTN": null,
"WebRequestForm": null,
"TName": null,
"TAddress3": null,
"IFMPaid": null,
"BillingAmount": null,
"ConnectorErrorStatus": null,
"BorrowerNVTGC": null,
"CCCOrder": null,
"ShippingDetail": null,
"ISOStatus": null,
"OdysseyErrorStatus": null,
"WorldCatLCNumber": null,
"Locations": null,
"FlagType": null,
"FlagNote": "",
"CreationDate": "2016-10-01T10:25:37.19",
"ItemInfo1": null,
"ItemInfo2": null,
"ItemInfo3": null,
"ItemInfo4": null,
"ItemInfo5": null,
"SpecialService": null,
"DeliveryMethod": null,
"Web": null,
"PMID": null,
"DOI": null,
"LastOverdueNoticeSent": null,
"ExternalRequest": null
}

Ignored parameters

The following fields are valid transaction fields but are ignored when creating a transaction. Developers should not send these fields when creating a transaction.

TransactionNumber
TransactionDate
CreationDate
ConnectorErrorStatus
OdysseyErrorStatus
ExternalRequest
CCSelected
OriginalTN
OriginalNVTGC
InvoiceNumber
FlagType
FlagNote

Default parameters

If the request does not contain values for the following fields, the Web Platform will assume default values.

Defaults for All requests
RequestType
AcceptAlternateEdition
AcceptNonEnglish
TransactionStatus
Defaults for lending requests
SystemId
DueDate
ShippingOptions
LibraryUseOnly
AllowPhotocopies
RenewalsAllowed
LenderAddressNumber

Click for Suggested Book Chapter Request Parameters

When using this endpoint to create book chapter requests, it is suggested that the parameters should minimally include the fields used in the default ILLiad Book Chapter request form listed in the table below. Additional fields such as CallNumber may also be used if desired. Note that the RequestType and DocumentType should be set to static values as indicated in the table:

Parameter/Field Name	Value	Field Description
RequestType	Article	Type of request in ILLiad - this is typically Article, but book chapters may also be handled as Loan types by some institutions
DocumentType	Book Chapter	Used to describe the document type
PhotoJournalTitle		Book Title
PhototItemAuthor		Book Author/Editor
PhotoArticleTitle		Chapter Title
PhotoArticleAuthor		Chapter Author
PhotoItemPlace		Place of Publication
PhotoItemPublisher		Publisher Name
PhotoJournalYear		Publication Date
PhotoItemEdition		Edition
PhotoJournalInclusivePages		The inclusive page range of the book chapter
ISSN		Standard Number (ISSN or ISBN)
ESPNumber		OCLC Number

Example Create Transaction Request

POST https://your.illiad.edu/ILLiadWebPlatform/transaction/
Content-Type: application/json
{
 "Username" : "jdoe",
 "RequestType" : "Article",
 "ProcessType" : "Borrowing",
 "PhotoJournalTitle" : "Journal of Interlibrary Loan,Document Delivery & Electronic Reserve",
 "PhotoArticleTitle" : "Interlibrary Loan in the United States: An Analysis of Academic Libraries in a Digital Age",
 "PhotoArticleAuthor" : "Williams, Joseph; Woolwine, David",
 "PhotoJournalVolume" : "21",
 "PhotoJournalIssue" : "4",
 "PhotoJournalYear" : "2011",
 "PhotoJournalInclusivePages" : "165-183",
 "ISSN": "1072-303X",
 "TransactionStatus": "Awaiting Request Processing",
 "CopyrightAlreadyPaid": true,
}

Response

Example Create Transaction Response

{
"TransactionNumber": 125,
"Username": "jdoe",
"RequestType": "Article",
"LoanAuthor": null,
"LoanTitle": null,
"LoanPublisher": null,
"LoanPlace": null,
"LoanDate": null,
"LoanEdition": null,
"PhotoJournalTitle" : "Journal of Interlibrary Loan,Document Delivery & Electronic Reserve",
"PhotoJournalVolume": null,
"PhotoJournalIssue": null,
"PhotoJournalMonth": null,
"PhotoJournalYear": null,
"PhotoJournalInclusivePages": "165-183",
"PhotoArticleAuthor" : "Williams, Joseph; Woolwine, David",
"PhotoArticleTitle" : "Interlibrary Loan in the United States: An Analysis of Academic Libraries in a Digital Age",
"CitedIn": null,
"CitedTitle": null,
"CitedDate": null,
"CitedVolume": null,
"CitedPages": null,
"NotWantedAfter": null,
"AcceptNonEnglish": false,
"AcceptAlternateEdition": true,
"ArticleExchangeUrl": null,
"ArticleExchangePassword": null,
"TransactionStatus": "Awaiting Request Processing",
"TransactionDate": "2016-10-01T10:25:37.19",
"ISSN": "1072-303X",
"ILLNumber": null,
"ESPNumber": null,
"LendingString": null,
"BaseFee": null,
"PerPage": null,
"Pages": null,
"DueDate": null,
"RenewalsAllowed": false,
"SpecIns": null,
"Pieces": null,
"LibraryUseOnly": null,
"AllowPhotocopies": false,
"LendingLibrary": null,
"ReasonForCancellation": null,
"CallNumber": null,
"Location": null,
"Maxcost": null,
"ProcessType": "Borrowing",
"ItemNumber": null,
"LenderAddressNumber": null,
"Ariel": false,
"Patron": null,
"PhotoItemAuthor": null,
"PhotoItemPlace": null,
"PhotoItemPublisher": null,
"PhotoItemEdition": null,
"DocumentType": "Article",
"InternalAcctNo": null,
"PriorityShipping": null,
"Rush": "Regular",
"CopyrightAlreadyPaid": "Yes",
"WantedBy": null,
"SystemID": "OTH",
"ReplacementPages": null,
"IFMCost": null,
"CopyrightPaymentMethod": null,
"ShippingOptions": null,
"CCCNumber": null,
"IntlShippingOptions": null,
"ShippingAcctNo": null,
"ReferenceNumber": null,
"CopyrightComp": "US:CCL",
"TAddress": null,
"TAddress": null,
"TAddress2": null,
"TCity": null,
"TState": null,
"TZip": null,
"TCountry": null,
"TFax": null,
"TEMailAddress": null,
"TNumber": null,
"HandleWithCare": false,
"CopyWithCare": false,
"RestrictedUse": false,
"ReceivedVia": null,
"CancellationCode": null,
"BillingCategory": null,
"CCSelected": null,
"OriginalTN": null,
"OriginalNVTGC": null,
"InProcessDate": null,
"InvoiceNumber": null,
"BorrowerTN": null,
"WebRequestForm": null,
"TName": null,
"TAddress3": null,
"IFMPaid": null,
"BillingAmount": null,
"ConnectorErrorStatus": null,
"BorrowerNVTGC": null,
"CCCOrder": null,
"ShippingDetail": null,
"ISOStatus": null,
"OdysseyErrorStatus": null,
"WorldCatLCNumber": null,
"Locations": null,
"FlagType": null,
"FlagNote": "",
"CreationDate": "2016-10-01T10:25:37.19",
"ItemInfo1": null,
"ItemInfo2": null,
"ItemInfo3": null,
"ItemInfo4": null,
"ItemInfo5": null,
"SpecialService": null,
"DeliveryMethod": null,
"Web": null,
"PMID": null,
"DOI": null,
"LastOverdueNoticeSent": null,
"ExternalRequest": null
}

HTTP Status Code	Description
200	OK (Successfully created request)
400	Bad Request Example Bad Request `<br>{<br> "Message": "The request is invalid.",<br> "ModelState": {<br> "model.ProcessType": [<br> "The ProcessType property is required."<br> ]<br> }<br>}<br>`
401	Unauthorized
500	Internal Server Error (Unexpected error)

Transaction History

Add Transaction History Entry to a Transaction

Add transaction history entry to a transaction

HTTP Verb: POST
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

The add transaction history request will add a transaction history entry for a given transaction number. The entry's username is set to the WebPlatformDescription associated with the API key making the request.

Required parameters

Entry	The history entry to be added

Example Add Transaction History Request

POST https://your.illiad.edu/ILLiadWebPlatform/transaction/4567/histories
SendLibraryNotification
Content-Type: application/json
{ "Entry" : "Request could not be filled" }

Response

Example Add Transaction History Response

{"TransactionNumber" : 4567,"DateTime" : "2016-10-05T08:15:37.19","Entry" : "Request could not be filled","Username" : "WebPlatform Config Description"
}

HTTP Status Code	Description
200	OK
400	Bad Request
401	Unauthorized
404	Resource Not Found
500	Internal Server Error

Transaction Note

Add Transaction Note to a Transaction | Retrieve Transaction Note

Add transaction note to a transaction

HTTP Verb: POST
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

The add transaction note request will add a transaction note for a given transaction number. The entry's username is set to the WebPlatformDescription associated with the API key making the request.

Required parameters

Note	The note to be added

Optional parameters

NoteType	The type of note being added. Valid values are `Staff`.

Example Add Transaction Note Request

POST https://your.illiad.edu/ILLiadWebPlatform/transaction/4567/notes
Content-Type: application/json
{ "Note" : "Sample Note", "NoteType" : "Staff" }

Response

Example Add Transaction Note Response

{"Id" : 10001,"TransactionNumber" : 4567,"NoteDate" : "2016-10-05T08:15:37.19","Note" : "Sample Note","AddedBy" : "staffUsername","NoteType" : "Staff"
}

HTTP Status Code	Description
201	Note created successfully
400	Bad Request Example Bad Request `<br>{<br> "Message": "The request is invalid.",<br> "ModelState": {<br> "model.NoteType": [<br> "An error has occurred."<br> ]<br> }<br>}<br>`
401	Unauthorized
404	Resource Not Found
500	Internal Server Error

Retrieve transaction note

HTTP Verb: GET
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

The get transaction note request will retrieve a transaction note for a given transaction number.

Example Get Transaction Note Request

GET https://your.illiad.edu/ILLiadWebPlatform/transaction/4567/notes/10001
Content-Type: application/json

Response

Example Get Transaction Note Response

{"Id" : 10001,"TransactionNumber" : 4567,"NoteDate" : "2016-10-05T08:15:37.19","Note" : "Sample Note","AddedBy" : "staffUsername","NoteType" : "Staff"
}

HTTP Status Code	Description
401	Unauthorized
404	Resource Not Found

Users

Get User by Username | Get User by External User ID | Create User

Get user by username

HTTP Verb: GET
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

Returns user details for a given username.

Example Get User by Username Request

GET https://your.illiad.edu/ILLiadWebPlatform/Users/msmith
Accept-Type: application/json

Response

Example Get User by Username Response

  {
      "UserName":"msmith",
      "ExternalUserId":"123456789",
      "LastName":"Smith",
      "FirstName":"Michael",
      "SSN":987654321,
      "Status":"Staff",
      "EMailAddress":"msmith@your.illiad.edu",
      "Phone":"555-1212",
      "MobilePhone":"NULL",
      "Department":"Computer Science",
      "NVTGC":"ILL",
      "Password":"10471281899082626783",
      "NotificationMethod":"Electronic",
      "DeliveryMethod":"Hold for Pickup",
      "LoanDeliveryMethod":"Hold for Pickup",
      "LastChangedDate":"2016-06-01T08:30:35.15",
      "AuthorizedUsers":"NULL",
      "Cleared":"BO",
      "Web":"Yes",
      "Address":"123 Main St",
      "Address2":"",
      "City":"Virginia Beach",
      "State":"VA",
      "Zip":"23464",
      "Site":null,
      "ExpirationDate":"2017-06-01T08:30:35.15",
      "Number":"8765670098",
      "UserRequestLimit":null,
      "Organization":null,
      "Fax":null,
      "ShippingAcctNo":null,
      "ArticleBillingCategory":"Default",
      "LoanBillingCategory":"Default",
      "Country":null,
      "SAddress":null,
      "SAddress2":null,
      "SCity":null,
      "SState":null,
      "SZip":null,
      "PasswordHint":null,
      "SCountry":null,
      "RSSID":"10098718781900019",
      "AuthType":"ILLiad",
      "UserInfo1":"PY12345",
      "UserInfo2":null,
      "UserInfo3":null,
      "UserInfo4":null,
      "UserInfo5":null
   }

HTTP Status Code	Description
200	OK
401	Unauthorized
404	Resource Not Found
500	Internal Server Error

Get user by external user id

HTTP Verb: GET
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.7.2.0

Returns user details for a given external user id.

Example Get User by External User Id Request

GET https://your.illiad.edu/ILLiadWebPlatform/Users/ExternalUserId/123456789
Accept-Type: application/json

info

The external user id is a configurable field that maps to an existing ILLiad field in the Users table. The external user id mapping is configured to be specific for each Web Platform API key that is generated allowing each Web Platform API consumer to have its own external user id. The default mapping is set to the Username field. Staff at the ILLiad library will need to use the ILLiad Customization Manager to modify the mapping for the ExternalUserId. ILLiad libraries are responsible to ensure that the external user id value is unique. ExternalUserId should be the name of a User field that already exists like SSN, UserInfo1, or Username. The API will error if multiple records are found for the same external user id.

Response

Example Get User by External User Id Response

 {
      "UserName":"msmith",
      "ExternalUserId":"123456789",
      "LastName":"Smith",
      "FirstName":"Michael",
      "SSN":987654321,
      "Status":"Staff",
      "EMailAddress":"msmith@your.illiad.edu",
      "Phone":"555-1212",
      "MobilePhone":"NULL",
      "Department":"Computer Science",
      "NVTGC":"ILL",
      "Password":"10471281899082626783",
      "NotificationMethod":"Electronic",
      "DeliveryMethod":"Hold for Pickup",
      "LoanDeliveryMethod":"Hold for Pickup",
      "LastChangedDate":"2016-06-01T08:30:35.15",
      "AuthorizedUsers":"NULL",
      "Cleared":"BO",
      "Web":"Yes",
      "Address":"123 Main St",
      "Address2":"",
      "City":"Virginia Beach",
      "State":"VA",
      "Zip":"23464",
      "Site":null,
      "ExpirationDate":"2017-06-01T08:30:35.15",
      "Number":"8765670098",
      "UserRequestLimit":null,
      "Organization":null,
      "Fax":null,
      "ShippingAcctNo":null,
      "ArticleBillingCategory":"Default",
      "LoanBillingCategory":"Default",
      "Country":null,
      "SAddress":null,
      "SAddress2":null,
      "SCity":null,
      "SState":null,
      "SZip":null,
      "PasswordHint":null,
      "SCountry":null,
      "RSSID":"10098718781900019",
      "AuthType":"ILLiad",
      "UserInfo1":"PY12345",
      "UserInfo2":null,
      "UserInfo3":null,
      "UserInfo4":null,
      "UserInfo5":null
   }

HTTP Status Code	Description
200	OK
401	Unauthorized
404	Resource Not Found Example Resource Not Found `<br>{<br> "Message": "Could not find unique user with external user id 123123123."<br>}<br>`
500	Internal Server Error

Create User

HTTP Verb: POST
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 9.0.1.0

Creates a new user.

Note (info): A note will be added for the user to indicate the user was created via the Web Platform and which API key created the record.

Example Create User Request

POST https://your.illiad.edu/ILLiadWebPlatform/Users
Accept-Type: application/json
{
  "Username" : "bdoe",
  "ExternalUserId": "Z20181116",
  "FirstName":"Bailey",
  "LastName":"Doe",
  "EmailAddress" : "bailey@test.com" ,
  "DeliveryMethod" : "Hold for Pickup",
  "LoanDeliveryMethod" : "Mail to Address",
  "NotificationMethod" : "Electronic",
  "Phone" : "757-123-4568",
  "Status" : "Graduate",
  "PlainTextPassword": "MySpecialPassword1234!",
  "AuthType" : "ILLiad",
  "Department" : "Music",
  "Web" : true,
  "Address" : "123 Oak St",
  "Address2" : "Apt 4E",
  "City" : "Virgia Beach",
  "State" : "VA",
  "Zip" : "23462"
}

Field	Type	Default if not provided	Note
Username	string		Required field.
ExternalUserId	string		The ExternalUserId field is a dynamic field configured by the institution for each API Key.
LastName	string
FirstName	string
SSN	string
Status	string
EMailAddress	string
Phone	string
MobilePhone	string
Department	string
NVTGC	string	The NVTGC associated with the API Key.	Each institution may have unique values. Consult with institution for allowed values.
NotificationMethod	enum	Electronic
DeliveryMethod	enum	Hold for Pickup
LoanDeliveryMethod	enum	Hold for Pickup
AuthorizedUsers	string
Cleared	enum	No
Web	bool	true	When true, the user will receive articles electronically.
Address	string
Address2	string
City	string
State	string
Zip	string
Country	string
Site	string
ExpirationDate	datetime	TheUser Expiration Date is set based upon system rules.
Number	string
UserRequestLimit	integer		This field should only be set if the user has a custom request limit.
Organization	string
Fax	string
ShippingAcctNo	string
ArticleBillingCategory	string
LoanBillingCategory	string
SAddress	string		This is for a secondary address.
SAddress2	string		This is for a secondary address.
SCity	string		This is for a secondary address.
SState	string		This is for a secondary address.
SZip	string		This is for a secondary address.
SCountry	string		This is for a secondary address.
AuthType	enum
PlainTextPassword	string		The password the user will use for authenticating to the web interface.
UserInfo1	string
UserInfo2	string
UserInfo3	string
UserInfo4	string
UserInfo5	string
NotificationPreferences	Array of NotificationPreferences	Email Notification preferences are added for all available activities.	Each NotificationPreference consists of an ActivityType and NotificationType.

Required Parameters

Username	Indicates the username of the new user record

Response

{
    "UserName": "bdoe",
    "ExternalUserId": "Z20181116",
    "LastName": "Doe",
    "FirstName": "Bailey",
    "SSN": "Z20181116",
    "Status": "Graduate",
    "EMailAddress": "bailey@test.com",
    "Phone": "757-123-4568",
    "Department": "Music",
    "NVTGC": "ADAMS",
    "NotificationMethod": "Electronic",
    "DeliveryMethod": "Hold for Pickup",
    "LoanDeliveryMethod": "Mail to Address",
    "LastChangedDate": "2018-11-26T12:00:01.000",
    "AuthorizedUsers": null,
    "Cleared": "No",
    "Web": true,
    "Address": "123 Oak St",
    "Address2": "Apt 4E",
    "City": "Virgia Beach",
    "State": "VA",
    "Zip": "23462",
    "Site": null,
    "ExpirationDate": "2019-05-15T12:00:01.000",
    "Number": null,
    "UserRequestLimit": null,
    "Organization": null,
    "Fax": null,
    "ShippingAcctNo": null,
    "ArticleBillingCategory": null,
    "LoanBillingCategory": null,
    "Country": null,
    "SAddress": null,
    "SAddress2": null,
    "SCity": null,
    "SState": null,
    "SZip": null,
    "SCountry": null,
    "RSSID": null,
    "AuthType": "ILLiad",
    "UserInfo1": null,
    "UserInfo2": null,
    "UserInfo3": null,
    "UserInfo4": null,
    "UserInfo5": null,
    "MobilePhone": null
}

HTTP Status Code	Description
200	OK (Successfully created request)
400	Bad Request
401	Unauthorized
500	Internal Server Error (Unexpected error)

Notifications

Retrieve Email Details | Retrieve SMS Details | Send Transaction Notification | Send User Notification | Send Library Notification

Retrieve Email Details

Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.6.0.0

The Email Details request will retrieve a single e-mail for a specified email id. This request is secured and requires an API key.

Example Email Details Request

curl -H 'Accept: application/json'
https://your.illiad.edu/ILLiadWebPlatform/Notification/EmailDetails/1234

Example Email Details Response

{
ID: 1234,
TransactionNumber: 0,
EMailDate: "2014-06-01T12:34:57.001",
ReferenceType: "Symbol",
Reference: "OCLC_ATL",
EMailTo: "borrowing@library.oclc_atl.edu",
EMailFrom: "\"ILLiad System\" <from.illiad@atlas-sys.com>",
EMailCC: null,
EMailBCC: null,
Subject: "This e-mail was generated on the Web Platform",
Body: "This is a sample e-mail body.",
Staff: null,
Status: "Pending",
Note: null,
NVTGC: "ILL"
}

Retrieve SMS Details

Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.6.0.0

The SMS Details request will retrieve a single SMS notification for a specified id. This request is secured and requires an API key.

Example SMS Details Request

curl -H 'Accept: application/json'
https://your.illiad.edu/ILLiadWebPlatform/Notification/SMSDetails/12

Example SMS Details Response

{
"ID": 12,
"NotificationDate": "2014-06-01T12:34:57.001",
ReferenceType: "Transaction",
Reference: "12345",
"To": "2125551212",
"Message": "This is a sample message",
"Staff": "System",
"Status": "Pending",
"Note": null,
"NVTGC": "ILL"
}

Send Transaction Notification

HTTP Verb: POST
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.6.0.0

The SendTransactionNotification request will generate a notification using a notification template for a specified transaction. If an e-mail notification is generated, it will be placed into a pending status and will be sent by the System Manager. If an SMS notification is generated, it will be placed into a pending status and will be handled by a server addon.

Required parameters

TransactionNumber	The transaction number to send the notification for
TemplateName	The name of the notification template to be used for the template

Optional parameters

To	The To address for the e-mail. If To is not provided, the To address will default to the NotificationTemplate's ToAddress if provided or the User or Lender's e-mail address.
From	The From address for the e-mail. If From is not provided, the From address will default to the NotificationTemplate's FromAddress if provided or the From address in Customization (EmailFromAddress, DocDelEmailFromAddress, or LendingEmailFromAddress depending on ProcessType).
CC	The CC address for the e-mail.
BCC	The BCC address for the e-mail.
Subject	The subject for the e-mail. If Subject is not provided, the subject will default to the NotificationTemplate's Subject.
StaffUsername	The staff username associated with sending the notification.
CustomTags	An array of custom tags that can be used as replacement values for Special tags in a notification template. CustomTags are considered to be a part of the Special table name if a table name is not provided.

In the following example, <#Special.CustomApplicationField> in a template would be replaced with ABC and <#CustomApplicationTable.Field> would be replaced with XYZ. CustomTags:{"CustomApplicationField":"ABC","CustomApplicationTable.Field":"XYZ"}

Example SendTransactionNotification Request using JSON

POST https://your.illiad.edu/ILLiadWebPlatform/Notification/
SendTransactionNotificationContent-Type: application/json
{ TransactionNumber: 12345, TemplateName:"Demo Template", Subject:
"This e-mail was generated on the Web Platform", CustomTags:
{"Test1":"123","Test2":"abc"}}}

SendTransactionNotification Response

If the transaction number or template name do not exist, the response will be a 404 Not Found.

If the notification was handled successfully, the Web Platform will respond with an HTTP 201 Created status code (Status: 201 Created). It is possible that a user will opt-out of specific types of notifications where an e-mail and/or an SMS will not be generated. Lending transactions will not generate SMS notifications. Check to ensure data was returned for an Email and SMS before using the result.

Example SendTransactionNotification Response

{
"Email": {
ID: 101,
TransactionNumber: 12345,
EMailDate: "2014-06-01T12:34:57.001",
ReferenceType: "Transaction",
Reference: "12345",
EMailTo: "test.user@your.illiad.edu",
EMailFrom: "\"ILLiad System\" <from.illiad@atlas-sys.com>",
EMailCC: null,
EMailBCC: null,
Subject: "This e-mail was generated on the Web Platform",
Body: "This is a sample e-mail body.",
Staff: "System",
Status: "Pending",
Note: null,
NVTGC: "ILL"
},
"SMS": {
"ID": 12,
"NotificationDate": "2014-06-01T12:34:57.001",
ReferenceType: "Transaction",
Reference: "12345",
"To": "2125551212",
"Message": "This is a sample message",
"Staff": "System",
"Status": "Pending",
"Note": null,
"NVTGC": "ILL"
}
}

Send User Notification

HTTP Verb: POST
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.6.0.0

The CreateUserEmail request will generate notification using a notification template for a specified user. If an e-mail notification is generated, it will be placed into a pending status and will be sent by the System Manager. If an SMS notification is generated, it will be placed into a pending status and will be handled by a server addon.

Required parameters

Username	The username of the user to associate the notification with
TemplateName	The name of the e-mail template to be used for the template

Optional parameters

To	The To address for the e-mail. If To is not provided, the To address will default to the NotificationTemplate's ToAddress if provided or the User or Lender's e-mail address.
From	The From address for the e-mail. If From is not provided, the From address will default to the NotificationTemplate's FromAddress if provided or the From address in Customization (EmailFromAddress).
CC	The CC address for the e-mail.
BCC	The BCC address for the e-mail.
Subject	The subject for the e-mail. If Subject is not provided, the subject will default to the EmailTemplate's Subject.
StaffUsername	The staff username associated with sending the e-mail.
CustomTags	An array of custom tags that can be used as replacement values for Special tags in an e-mail template. CustomTags are considered to be a part of the Special table name if a table name is not provided.

Example SendUserNotification Request using JSON

POST https://your.illiad.edu/ILLiadWebPlatform/Notification/
SendUserNotificationContent-Type: application/json
{ Username: "jdoe", TemplateName:"Demo Template", Subject:
"This e-mail was generated on the Web Platform", CustomTags:
{"Test1":"123","Test2":"abc"}}}

SendUserNotification Response

If the user or template name do not exist, the response will be a 404 Not Found.

If the notification was handled successfully, the Web Platform will respond with an HTTP 201 Created status code (Status: 201 Created). It is possible that a user will opt-out of specific types of notifications where an e-mail and/or an SMS will not be generated. Check to ensure data was returned for an Email and SMS before using the result.

Example SendUserNotification Response

{
"Email": {
ID: 102,
TransactionNumber: 0,
EMailDate: "2014-06-01T12:34:57.001",
ReferenceType: "User",
EMailReference: "jdoe",
EMailTo: "jdoe@your.illiad.edu",
EMailFrom: "\"ILLiad System\" <from.illiad@atlas-sys.com>",
EMailCC: null,
EMailBCC: null,
Subject: "This e-mail was generated on the Web Platform",
Body: "This is a sample e-mail body.",
Staff: null,
Status: "Pending",
Note: null,
NVTGC: "ILL"
},
"SMS": {
"ID": 12,
"NotificationDate": "2014-06-01T12:34:57.001",
ReferenceType: "User",
Reference: "jdoe",
"To": "2125551213",
"Message": "This is a sample message",
"Staff": "System",
"Status": "Pending",
"Note": null,
"NVTGC": "ILL"
}
}

Send Library Notification

HTTP Verb: POST
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 8.6.0.0

The SendLibraryNotification request will generate notification using a notification template for a specified library. If an e-mail notification is generated, it will be placed into a pending status and will be sent by the System Manager. SMS messages are not supported for lending/library e-mails.

Required parameters

LibrarySymbol	The symbol of the library to associate the notification with
AddressNumber	The address number of the library to associate the notification with
TemplateName	The name of the notification template to be used for the template

Optional parameters

NVTGC	The NVTGC associated with the library address. If not provided the NVTGC will be the default site code (i.e. ILL). This parameter should be provided in shared server environments.
To	The To address for the e-mail. If To is not provided, the To address will default to the NotificationTemplate's ToAddress if provided or the User or Lender's e-mail address.
From	The From address for the e-mail. If From is not provided, the From address will default to the NotificationTemplate's FromAddress if provided or the From address in Customization (LendingEmailFromAddress).
CC	The CC address for the e-mail.
BCC	The BCC address for the e-mail.
Subject	The subject for the e-mail. If Subject is not provided, the subject will default to the NotificationTemplate's Subject.
StaffUsername	The staff username associated with sending the notification.
CustomTags	An array of custom tags that can be used as replacement values for Special tags in a notification template. CustomTags are considered to be a part of the Special table name if a table name is not provided.

Example SendLibraryNotification Request using JSON

POST https://your.illiad.edu/ILLiadWebPlatform/Notification/
SendLibraryNotification
Content-Type: application/json
{ LibrarySymbol: "OCLC_ATL", AddressNumber : 1, NVTGC : "ILL",
TemplateName:"Demo Template", Subject: "This e-mail was generated
on the Web Platform", CustomTags:{"Test1":"123","Test2":"abc"}}}

SendLibraryNotification Response

If the library or template name do not exist, the response will be a 404 Not Found.

If the notification was handled successfully, the Web Platform will respond with an HTTP 201 Created status code (Status: 201 Created).

Example SendLibraryNotification Response

{
"Email": {
ID: 102,
TransactionNumber: 0,
EMailDate: "2014-06-01T12:34:57.001",
ReferenceType: "Symbol",
EMailReference: "OCLC_ATL",
EMailTo: "borrowing@library.oclc_atl.edu",
EMailFrom: "\"ILLiad System\" <from.illiad@atlas-sys.com>",
EMailCC: null,
EMailBCC: null,
Subject: "This e-mail was generated on the Web Platform",
Body: "This is a sample e-mail body.",
Staff: null,
Status: "Pending",
Note: null,
NVTGC: "ILL"
},
"SMS": null
}

Web Display Status

Get Web Display Status Rules | Get Web Display Status by NVTGC/Process Type/Transaction Status | Get Web Display Status of a Specific Transaction

Get Web Display Status Rules

HTTP Verb: GET
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 9.2.0.0

The Get Web Display Status Rules request will retrieve all web display status rules that are defined within ILLiad.

Example Get Web Display Status Rules Request using JSON

This sample request demonstrates how to retrieve all web display status rules currently defined in ILLiad.

GET https://your.illiad.edu/ILLiadWebPlatform/DisplayStatus
Content-Type: application/json

Example Get Web Display Status Rules Response

[
    {
        "Id": 1,
        "Nvtgc": "HOOVER",
        "ProcessTypeString": "Borrowing",
        "ProcessType": 0,
        "TransactionStatus": "Awaiting Request Processing",
        "DisplayStatus": "Locating Suppliers"
    },
    {
        "Id": 2,
        "Nvtgc": "HOOVER",
        "ProcessTypeString": "Borrowing",
        "ProcessType": 0,
        "TransactionStatus": "Awaiting Unfilled Processing",
        "DisplayStatus": "Delayed: Looking for additional suppliers"
    },
    {
        "Id": 3,
        "Nvtgc": "HOOVER",
        "ProcessTypeString": "Borrowing",
        "ProcessType": 0,
        "TransactionStatus": "Request Sent",
        "DisplayStatus": "Supplier Processing Request"
    },
    {
        "Id": 4,
        "Nvtgc": "GARFIELD",
        "ProcessTypeString": "Borrowing",
        "ProcessType": 0,
        "TransactionStatus": "Awaiting Request Processing - Special",
        "DisplayStatus": "Awaiting Request Processing"
    },
    {
        "Id": 5,
        "Nvtgc": "GARFIELD",
        "ProcessTypeString": "Lending",
        "ProcessType": 2,
        "TransactionStatus": "Awaiting Lending Request Processing",
        "DisplayStatus": "Awaiting Processing"
    }
]

Get Web Display Status by NVTGC/Process Type/Transaction Status

HTTP Verb: GET
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 9.2.0.0

Optional parameters for NVTGC, process type, and/or transaction status are available for the Get Web Display Status Rules request. If parameters are added to the request, the web display status defined for transactions with the included parameter values will be returned as a string.

Optional parameters

NVTGC	Defines a specific NVTGC for which to retrieve the web display statuses defined.
processType	Defines a specific process type for which to retrieve the web display statuses defined.
originalTransactionStatus	Defines a specific transaction status for which to retrieve the web display statuses defined.

Example Get Web Display Status Request with parameters using JSON

This sample request demonstrates how to retrieve the web display status defined for transactions with an NVTGC value of "HOOVER," process type value of "Borrowing" and status of "Awaiting Request Processing."

GET https://your.illiad.edu/ILLiadWebPlatform/DisplayStatus?NVTGC=HOOVER&ProcessType=Borrowing&Status=Awaiting+Request+Processing
Content-Type: application/json

Example Get Web Display Status Response

Returns the web display status as a string.

"Locating Suppliers"

Get the Web Display Status of a Specific Transaction

HTTP Verb: GET
Authorization: Secured
Supports OData: No
Minimum API Version: 1
Minimum Web Platform Version: 9.2.0.0

The Get Web Display Status Transaction request will retrieve the web display status of a specific transaction. The ID number of the transaction is a required parameter.

Required parameters

id	The ID of the transaction for which to retrieve web display status.

Example Get Web Display Status Transaction Request using JSON

The following sample request will retrieve the web display status for the transaction with ID number 7890.

GET https://your.illiad.edu/ILLiadWebPlatform/transaction/7890/DisplayStatus
Content-Type: application/json

Example Get Web Display Status Transaction Response

If the transaction does not exist, the response will be a 404 Not Found.

If handled successfully, the Web Platform will respond with the web display status returned as a string.

"Awaiting Offsite Delivery"

Getting Started​

Generating an API Key​

Versions and Updates​

Making Requests​

Authentication​

Response Formats​

OData Support​

Filtering​

Filter Operators​

Filter Functions​

Examples​

Sorting​

Example​

Limiting Results​

$top​

$skip​

System Information​

API Version​

PlatformVersion​

Secure Platform Version​

Transactions​

Retrieving Requests by Transaction Number​

Retrieving Requests for User​

Routing transaction request​

Required parameters​

Response​

Marking transaction filled​

Required parameters​

Response​

Marking transaction unfilled​

Required parameters​

Response​

Create a transaction request​

Parameters​

Required parameters​

ExternalUserID Parameter [ILLiad 9.2 Only]​

Response​

Ignored parameters​

Default parameters​

Response​

Transaction History​

Add transaction history entry to a transaction​

Required parameters​

Response​

Transaction Note​

Add transaction note to a transaction​

Required parameters​

Optional parameters​

Response​

Retrieve transaction note​

Response​

Users​

Get user by username​

Response​

Get user by external user id​

Response​

Create User​

Required Parameters​

Response​

Notifications​

Retrieve Email Details​

Retrieve SMS Details​

Send Transaction Notification​

Required parameters​

Optional parameters​

SendTransactionNotification Response​

Send User Notification​

Required parameters​

Optional parameters​

SendUserNotification Response​

Send Library Notification​

Required parameters​

Optional parameters​

SendLibraryNotification Response​

Web Display Status​

Get Web Display Status Rules​

Get Web Display Status by NVTGC/Process Type/Transaction Status​

Optional parameters​

Get the Web Display Status of a Specific Transaction​

Required parameters​

Getting Started

Generating an API Key

Versions and Updates

Making Requests

Authentication

Response Formats

OData Support

Filtering

Filter Operators

Filter Functions

Examples

Sorting

Example

Limiting Results

$top

$skip

System Information

API Version

PlatformVersion

Secure Platform Version

Transactions

Retrieving Requests by Transaction Number

Retrieving Requests for User

Routing transaction request

Required parameters

Response

Marking transaction filled

Required parameters

Response

Marking transaction unfilled

Required parameters

Response

Create a transaction request

Parameters

Required parameters

ExternalUserID Parameter [ILLiad 9.2 Only]

Response

Ignored parameters

Default parameters

Response

Transaction History

Add transaction history entry to a transaction

Required parameters

Response

Transaction Note

Add transaction note to a transaction

Required parameters

Optional parameters

Response

Retrieve transaction note

Response

Users

Get user by username

Response

Get user by external user id

Response

Create User

Required Parameters

Response

Notifications

Retrieve Email Details

Retrieve SMS Details

Send Transaction Notification

Required parameters

Optional parameters

SendTransactionNotification Response

Send User Notification

Required parameters

Optional parameters

SendUserNotification Response

Send Library Notification

Required parameters

Optional parameters

SendLibraryNotification Response

Web Display Status

Get Web Display Status Rules

Get Web Display Status by NVTGC/Process Type/Transaction Status

Optional parameters

Get the Web Display Status of a Specific Transaction

Required parameters