The Patron API - Patron Record

The Patron API contains methods for creating, retrieving, updating, deleting, and validating patron records. Using these endpoints, you can:

The Try it out! links below take you to the corresponding section in the interactive documentation, where you can view the model, model schema, and parameters for each available operation.

Create a Patron Record

To use this endpoint, your key must be assigned the Patrons Write role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

POST /v6/patrons/

Requires a PatronPatch request object.

You can create a patron with these fields:

  • name
  • address
  • phone number
  • email address
  • PIN
  • patron type
  • barcodes
  • expiration date
  • birth date
  • patron codes – pcode1, pcode2, pcode3, and pcode4
  • block information – manual block code
  • unique ids – patron unique ID
  • pMessage – library-defined patron message
  • home library code – patron's home library
  • language preference – if installed, specifies the language preferences for patron notices
  • fixedFields – fixed-length fields from the patron record. One or more fixed fields are supported with each patron record creation.
  • The following JSON example shows how multiple fixed fields are specified using a fieldId: Integer -> FieldValue format:

    • {

    fixedFields":

    {

    "44":{"label":"Patron Code 1","value":"c"},

    "46":{"label":"Patron Code 3","value":"4"},

    "47":{"label":"Patron Type","value":"5"},

    }

    }

    • varFields – Array used to create note, message, and patron image (PAT IMAGE) fields

    If created successfully, HTTP 200 and a link to the patron’s ID are returned.

    Try it out!

    Get a List of Patrons

    To use this endpoint, your key must be assigned the Patrons Read role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

    GET /v6/patrons/

    Returns the properties of the first x patron objects, where x = the default record limit.

    Records can be filtered by:

    List of agency codes Returns patron data for a comma delimited list of one or more agency codes that you supply. If no data exists for the agency code you have entered, the error “Record not found” is returned
    One or a range of assessed dates Returns patron data for one or a range of dates. The filtering is done on the date that the fine was assessed. Data entry format The format of the date range is [YYYY-MM-DD,YYYY-MM-DD]. The format of a single date is YYYY-MM-DD. The error: “Invalid parameter” is returned if an incorrect data format is used. If no data exists, the error: “No record found” is returned. The “Total” parameter returned as part of the result set contains the total number of records in the database; and not the total number of filtered records returned.

    Try it out!

    Get a patron by record ID

    To use this endpoint, your key must be assigned the Patrons Read role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

    GET /v6/patrons/{id}

    Returns a single patron object with the specified record ID.

    Try it out!

    Get a List of Patron Metadata

    To use this endpoint, your key must be assigned the Patrons Read role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

    GET /v6/patrons/metadata

    Returns patron metadata for the supplied field parameter, where allowable parameters are “patronType”, “pcode1”, “pcode2”, “pcode3”, “pcode4”, “mBlock”, “pMessage”, “langPref” and “homeLibrarycode”. When no parameters are supplied, patron metadata is returned for all allowable parameters. If a language parameter is supplied and that language is configured in Sierra, data returned is in the supplied language; otherwise, data is returned in English.

    Returns a MetadataValue object.

    Try it out!

    Find a Patron by varField fieldTag and varField Content

    To use this endpoint, your key must be assigned the Patrons Read role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

    GET /v6/patrons/find

    Returns a patron object for the supplied varFieldTag and varFieldValue. The varFieldTag is a single character that is used to locate the varFieldValue of that type. For example, if you have configured ‘u’ to be uniqueId on your Sierra system, then entering varFieldTag = ‘u’ and varFieldValue = ‘12345’ returns the associated patron object for uniqueId ‘12345’. Supports case sensitivity.

    Try it out!

    Filter the Records by a Query in JSON Format

    To use this endpoint, your key must be assigned the Patrons Read role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

    POST /v6/patrons/query

    Returns a list of records that satisfy the JSON query.

    See Creating a JSON Query for information about the structure of Sierra JSON queries.

    Try it out!

    Update a Patron Record

    To use this endpoint, your key must be assigned the Patrons Write role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

    PUT /v6/patrons/{id}

    Updates a specified patron record. Requires a PatronPatch request object.

    If updated successfully, HTTP 204 is returned.

    Try it out!

    Delete a Patron Record

    To use this endpoint, your key must be assigned the Patrons Write role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

    DELETE /v6/patrons/{id}

    Deletes the patron record for the specified id.

    If the patron has been deleted successfully, an HTTP 204 is returned. If there are fines due or books currently checked out against that patron ID, the patron record is not deleted and an HTTP 409 is returned.

    Try it out!

    Validate a patron by barcode and PIN

    To use this endpoint, your key must be assigned the Patrons Write or Patrons Validate role. See Administering Sierra API Client Keys in the Sierra WebHelp for more information.

    POST /v6/patrons/validate

    Validates a patron using the fields configured for your library's Sierra system (frequently, the barcode or unique ID and PIN). If validation is successful, an HTTP 204 status is returned. Otherwise, an error code is returned. This requires a PatronValidation request object.

    The following example shows the JSON structure used for validation:

    {

    "barcode": "abc2129401127"

    "pin": "socomplex"

    }

    By default, the barcode is case sensitive. If your library uses the uniqueId field identifier for patron validation instead of the barcode or your library has barcodes that contain spaces (including trailing spaces), use the the caseSensitivity parameter to allow for case-insensitive validation. The following example shows the JSON structure used for validation with caseSensitivity set to false:

    {

    "barcode": "abc2129401127"

    "pin": "socomplex"

    "caseSensitivity": false

    }

    Note: When both the barcode and uniqueId are used, a library can use the barcode field as the patron's barcode or unique ID.

    Try it out!