The ILLiad Web Platform API

Follow

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

The ILLiad Web Platform was introduced in ILLiad version 8.4.

Getting StartedMaking Requests | Response Format | OData Support | Sorting | System Information | Transactions | Transaction History | Transaction Note | Users | Create User | Notifications 

Getting Started 

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!

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

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

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

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
{
    "Message": "Arguments cannot be null: model"
}
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.
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
{
    "Message": "The request is invalid.",
    "ModelState": {
        "model.Lender": [
            "The Lender field is required."
        ]
    }
}
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 Processing queue.
  • The reason will be added as a note to the request.
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
{
    "Message": "The Transaction is at an invalid state. Request 12345 is not assigned to Borrowing process type."
}
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.

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

Indicates the username of the new transaction

ProcessType

Indicates the ILLiad ProcessType.

Allowed values:

    • Borrowing
    • DocDel
    • Lending
*LendingLibrary

LendingLibrary is only required if ProcessType is Lending.

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

Article

AcceptAlternateEdition true

 

AcceptNonEnglish false
TransactionStatus When transaction status is not set explicitly the web platform will use the default system initial transaction status depending on the ProcessType and RequestType.
Defaults for lending requests
SystemId

If ProcessType is Lending, the default value is

    • OTH

If ProcessType is Borrowing, the default value is
set to the BorrowingSystemIDDefault customization key.

DueDate Calculated based on LendingDueDateDays customization key and if the LendingLibrary is associated with a group that has a Due Date Override.
ShippingOptions

If RequestType is Article, the default value is set based on the LendingDefaultArticleShipping customization key.

If RequestType is Loan, the default value is set based on the LendingDefaultLoanShipping customization key.

LibraryUseOnly Set based on the LendingRestrictDefaultLibraryUseOnly customization key.
AllowPhotocopies Set based on the LendingRestrictDefaultAllowPhotocopies customization key.
RenewalsAllowed Set based on the LendingRestrictDefaultAllowRenewals customization key.
LenderAddressNumber Set to the LenderAddressNumber associated with the LendingAddress record when only 1 record exists for the associated LendingLibrary.
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
{
    "Message": "The request is invalid.",
    "ModelState": {
        "model.ProcessType": [
            "The ProcessType property is required."
        ]
    }
}
401 Unauthorized
500 Internal Server Error (Unexpected error)

Transaction History

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

  • 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
{
    "Message": "The request is invalid.",
    "ModelState": {
        "model.NoteType": [
            "An error has occurred."
        ]
    }
}
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

  • 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
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 customization manager to modify the mapping for the ExternalUserId. ILLiad libraries are responsible to ensure that the external user id value is unique. 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
{
    "Message": "Could not find unique user with external user id 123123123."
}
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. 

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 Get User by External User Id 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.

An ExternalUserId will always override the a value supplied for the mapped field. A user note will be added if the two values conflict and what the original mapped value was set to.

 

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

 

Allowed Values
Electronic
Phone
Mail

 

DeliveryMethod enum Hold for Pickup

 

Allowed Values
Hold for Pickup
Mail to Address

 

LoanDeliveryMethod enum Hold for Pickup

 

Allowed Values
Hold for Pickup
Mail to Address

 

AuthorizedUsers string    
Cleared enum No

 

Allowed Values Description
Yes The user is allowed to use the system.
No The user has not yet been vetted by staff.
New User is new to the system and has not completed their user profile. On their first login they will be forced to complete their user profile.
DIS The user is disavowed and not authorized to log in.
B The user is blocked.
BO The user is blocked due to an overdue. Overdue blocks are removed when the user no longer has overdue materials checked out.
BX The user is blocked by an external system.

 

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

 

Allowed Values Note
Default The user will login with the default user authentication system.
ILLiad

The user will login with their ILLiad username and password.

Consider supplying a PlainTextPassword so the user can access their web account. If a password is not provided, the user will need to reset their password or contact staff for assistance.

 

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.

Allowed NotificationTypes
Value Description
SMS Indicates the user wants an SMS notification, when available. A MobilePhone value should be provided.
Email Indicated the user wants an Email notification, when available. An EmailAddress should be provided.
Allowed NotificationTypes
Value Description
ClearedUser The type of notification received when the user is cleared to use the system.
PasswordReset The type of notification received when the user requested a password reset.
RequestPickup The type of notification received when material is available to be picked up by the user at the library.
RequestShipped The type of notification received when material is shipped to the user.
RequestElectronicDelivery The type of notification received when the user receives material via electronic delivery.
RequestOverdue The type of notification received when the user has material checked out that is overdue.
RequestCancelled The type of notification received when a request placed by the user is cancelled.
RequestOther The type of notification received for any other notification generated by the system that is not listed above.

 

"NotificationPreferences" : [
    {
    "ActivityType" : "RequestPickup",
    "NotificationType" : "SMS"
  	},
    {
    "ActivityType" : "RequestPickup",
    "NotificationType" : "Email"
  	},
    {
    "ActivityType" : "RequestOther",
    "NotificationType" : "Email"
  	},
  ]  

 

 

Required Parameters


Username

Indicates the username of the new transaction 


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
OK (Successfully created request)

Bad Request

{
    "Message": "The request is invalid.",
    "ModelState": {
        "model.NVTGC": [
            "The NVTGC is invalid."
        ]
    }
}

 

Unauthorized
Internal Server Error (Unexpected error)

 

Notifications

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.

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

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

Questions?

If this article didn’t resolve your issue, please take a moment and answer a few questions to help improve our documentation:

Feedback