NCIP Requests
Authentication:
This web service requires the use of a WSKey as a means of authentication. Because this service performs write operations, it uses WSKey2. More information about WSKeys is available in the authentication documentation.
Additionally, all requests to the API require that the principleID, principleIDNS, and inst parameters be included with the URI. ex:
?inst=12345&principleID=660ecd7d-3d1b-4433-abcd-ae843b716ec0&principleIDNS=urn:oclc:wms:da
This is necessary to identify the user who executes the request. It is also omitted in the examples for better readability.
To obtain a WSKey please visit OCLC Service Config.
Requests
NCIP requests are issued by creating an XML document containing the appropriate information and POSTing it along with the appropriate headers:
- Content-type: application/xml
- charset: utf-8
to the NCIP service endpoint. Each message requires a specific set of fields and information be sent as an XML document.
Currently the NCIP service handles four messages: CheckIn, CheckOut, RequestItem and CancelRequestItem.
All messages must include the following fields
| Element | Required? | Description |
|---|---|---|
| InitiationHeader/FromAgencyId/@Scheme | Yes | OCLC Registry Id Scheme URI http://oclc.org/ncip/schemes/agencyid.scm |
| InitiationHeader/FromAgencyId | Yes | Registry ID of the library/branch in which the circulation operation is taking place |
| InitiationHeader/ToAgencyId | Yes | Must match the FromAgencyId |
| InitiationHeader/ApplicationProfileType | Yes | Must be set to "Version 2011" |
| InitiationHeader/ApplicationProfileType/@Scheme | Yes | Must be the OCLC Platform NCIP Application Profile Scheme URI http://oclc.org/ncip/schemes/application-profile/platform.scm |
CheckIn
| Element | Required | Description |
|---|---|---|
| ItemId/AgencyId | Yes | Registry Id of the institution to which the item belongs |
| ItemId/ItemIdentifierValue | Yes | Barcode of the Item |
| ItemElementType | No | Repeatable field which lists the information fields to return in the response |
CheckOut
| Element | Required | Description |
|---|---|---|
| ItemId/AgencyId | Yes | Registry Id of the institution to which the item belongs |
| ItemId/ItemIdentifierValue | Yes | Barcode of the Item |
| UserId/AgencyId | Yes | OCLC Registry ID of the institution to check the item out to or to which the user to check the item out to is associated |
| UserId/UserIdentifierValue | Yes | Barcode of the user to whom the item is being checked out |
| AcknowledgedFeeAmount/CurrencyCode/@Scheme | No | NCIP Currency Code Scheme URI http://www.bsi-global.com/Technical+Information/Publications/ _Publications/tig90x.doc |
| AcknowledgedFeeAmount/CurrencyCode | No | Currency Code of the fee that is to be acknowledged See http://www.currency-iso.org/dl_iso_table_a1.xls |
| AcknowledgedFeeAmount/MonetaryValue | No | Amount of the free to acknowledged based on the minor demonination of the specified currency. For information on the minor denomination of a particular currency see See http://www.currency-iso.org/dl_iso_table_a1.xls |
| DesiredDueDate | No | Desired due date/time for the item, if different from that determined by policy, Must be in ISO 8601 format. Eg - 2010-12-31T13:30:00Z |
| ItemElementType | No | Repeatable field which lists the information fields to return in the response |
RequestItem
| Element | Required | Description |
|---|---|---|
| UserId/AgencyId | Yes | OCLC Registry ID of the institution which the patron is associated with |
| UserId/UserIdentifierValue | Yes | Identifier of the patron (eg. barcode) placing the request |
| BibliographicId | Must be present if the RequestScope Type element is Bibliographic Item. |
Repeatable |
| BibliographicId/BibliographicRecordId/BibliographicRecordIdentifier | OCLC Number of the object being requested. Bare number without prefix (ocm or ocn), padding such as leading zeros | |
| BibliographicId/BibliographicRecordId/BibliographicRecordIdentifierCode/@Scheme | Must be the NCIP Bibliographic Record Identifier Code Scheme URI http://www.niso.org/ncip/v1_0/imp1/schemes/bibliographicrecordidentifiercode/bibliographicrecordidentifiercode.scm | |
| BibliographicRecordId/BibliographicRecordIdentifierCode | OCLC | |
| ItemId | Must be present if the value of the RequestScopeType element is Item | |
| ItemId/ItemIdentifierValue | Barcode of the item | |
| RequestType/@Scheme | Yes | Must be the NCIP Request Scheme URI http://www.niso.org/ncip/v1_0/imp1/schemes/requesttype/requesttype.scm |
| RequestType | Yes | Hold |
| RequestScopeType/@Scheme | Yes | Must be the NCIP Request Scope Type Scheme URI http://www.niso.org/ncip/v1_0/imp1/schemes/requestscopetype/requestscopetype.scm |
| RequestScopeType | Yes | Scope of the request either:
|
| EarliestDateNeeded | No | Must be in ISO 8601 format. Eg - 2010-12-31T13:30:00Z |
| NeedBeforeDate | No | Must be in ISO 8601 format. Eg - 2010-12-31T13:30:00Z |
| PickupLocation | Yes | OCLC Holding code for the location where the item should be picked up from |
| ItemElementType | No | Repeatable field which lists the information fields to return in the response |
CancelRequestItem
| Element | Required | Description |
|---|---|---|
| UserId/AgencyId | Yes | OCLC Registry ID of the institution which the patron is associated with |
| UserId/UserIdentifierValue | Yes | Identifier of the patron (eg. barcode) who placed the request |
| ItemId | Either this or the RequestId must be present | |
| ItemId/AgencyId | OCLC Registry ID of the institution to which the item belongs | |
| ItemId/ItemIdentifierValue | Barcode of the item | |
| RequestId | Either this or the ItemId must be present | |
| RequestId/AgencyId | OCLC Registry ID of the institution with which the request is associated | |
| RequestId/RequestIdentifierValue | Request identifier returned as a result of the RequestItem operation | |
| RequestType/@Scheme | Yes | Must be the NCIP Request Type Scheme URI http://www.niso.org/ncip/v1_0/imp1/schemes/requesttype/requesttype.scm |
| RequestType | Yes | Must match the RequestType in the RequestItem request originally placed |
| RequestScopeType/@Scheme | Yes | Must be the NCIP Request Scope Type Scheme URI http://www.niso.org/ncip/v1_0/imp1/schemes/requestscopetype/requestscopetype.scm |
| RequestScopeType | Yes | Item if the request was made at item-level or Bibliographic Item if request was made at bibliographic-level |
| ItemElementType | No | Repeatable field which lists the information fields to return in the response |
The OCLC Developer Network supports the use of OCLC Web Services—a set of tools and APIs that expose data and services for WorldCat and our member libraries and partner institutions or companies. learn more »
© 2010 OCLC Domestic and international trademarks and/or service marks of OCLC Online Computer Library Center, Inc. and its affiliates
Follow the OCLC Developer Network: