Patron Services version v4.4

https://github.com/folio-org/mod-patron

Patron Services

This module allows 3rd party discovery services to perform patron actions in FOLIO

Patron Services

Services that allow patron empowerment from 3rd party discovery services

post

post

Create a staging user or update a staging user if it exists

Create a staging user or update a staging user if it exists

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for staging users",
  "type": "object",
  "properties": {
    "isEmailVerified": {
      "description": "A boolean flag that indicates whether the patron has completed email verification. If this value is not provided when creating a new record, it will default to false. However, for Kiosk user registrations, this value should be sent false.",
      "type": "boolean"
    },
    "minor": {
      "description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
      "type": "boolean"
    },
    "status": {
      "description": "Represents the patron's tier status, which can be either TIER-1 or TIER-2. If this value is not provided when creating a new record, the default status will be set to TIER-1.",
      "type": "string",
      "enum": [
        "TIER-1",
        "TIER-2"
      ]
    },
    "externalSystemId": {
      "description": "A unique ID (UUID) that corresponds to an external authority",
      "type": "string"
    },
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "firstName": {
          "description": "First name of the patron",
          "type": "string"
        },
        "preferredFirstName": {
          "description": "Preferred first name of the patron",
          "type": "string"
        },
        "middleName": {
          "description": "Middle name of the patron",
          "type": "string"
        },
        "lastName": {
          "description": "Last name of the patron",
          "type": "string"
        }
      },
      "required": [
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "description": "First line of the address",
          "type": "string"
        },
        "addressLine1": {
          "description": "Second line of the address",
          "type": "string"
        },
        "city": {
          "description": "City",
          "type": "string"
        },
        "province": {
          "description": "Province/State",
          "type": "string"
        },
        "zip": {
          "description": "Postal/Zip code",
          "type": "string"
        },
        "country": {
          "description": "Country",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "description": "Phone number of the patron",
          "type": "string"
        },
        "mobilePhone": {
          "description": "Mobile phone number of the patron",
          "type": "string"
        },
        "email": {
          "description": "Email of the patron",
          "type": "string"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Preferred email communication types",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "additionalProperties": false,
  "required": [
    "generalInfo",
    "contactInfo"
  ]
}

Example:

{
  "isEmailVerified": true,
  "status": "TIER-1",
  "minor": true,
  "externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
  "generalInfo": {
    "firstName": "John",
    "preferredFirstName": "John",
    "middleName": "Felix",
    "lastName": "Cena"
  },
  "addressInfo": {
    "addressLine0": "William Morris Endeavor",
    "addressLine1": "9601 Wilshire Blvd 3rd Floor",
    "city": "Beverly Hills",
    "province": "CA",
    "zip": "12345",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-123456",
    "mobilePhone": "55555-66666",
    "email": "john_cena@test_folio.com"
  },
  "preferredEmailCommunication": [
    "Support",
    "Programs",
    "Services"
  ]
}

HTTP status code 200

staging user updated successfully

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for staging users",
  "type": "object",
  "properties": {
    "isEmailVerified": {
      "description": "A boolean flag that indicates whether the patron has completed email verification. If this value is not provided when creating a new record, it will default to false. However, for Kiosk user registrations, this value should be sent false.",
      "type": "boolean"
    },
    "minor": {
      "description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
      "type": "boolean"
    },
    "status": {
      "description": "Represents the patron's tier status, which can be either TIER-1 or TIER-2. If this value is not provided when creating a new record, the default status will be set to TIER-1.",
      "type": "string",
      "enum": [
        "TIER-1",
        "TIER-2"
      ]
    },
    "externalSystemId": {
      "description": "A unique ID (UUID) that corresponds to an external authority",
      "type": "string"
    },
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "firstName": {
          "description": "First name of the patron",
          "type": "string"
        },
        "preferredFirstName": {
          "description": "Preferred first name of the patron",
          "type": "string"
        },
        "middleName": {
          "description": "Middle name of the patron",
          "type": "string"
        },
        "lastName": {
          "description": "Last name of the patron",
          "type": "string"
        }
      },
      "required": [
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "description": "First line of the address",
          "type": "string"
        },
        "addressLine1": {
          "description": "Second line of the address",
          "type": "string"
        },
        "city": {
          "description": "City",
          "type": "string"
        },
        "province": {
          "description": "Province/State",
          "type": "string"
        },
        "zip": {
          "description": "Postal/Zip code",
          "type": "string"
        },
        "country": {
          "description": "Country",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "description": "Phone number of the patron",
          "type": "string"
        },
        "mobilePhone": {
          "description": "Mobile phone number of the patron",
          "type": "string"
        },
        "email": {
          "description": "Email of the patron",
          "type": "string"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Preferred email communication types",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "additionalProperties": false,
  "required": [
    "generalInfo",
    "contactInfo"
  ]
}

Example:

{
  "isEmailVerified": true,
  "status": "TIER-1",
  "minor": true,
  "externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
  "generalInfo": {
    "firstName": "John",
    "preferredFirstName": "John",
    "middleName": "Felix",
    "lastName": "Cena"
  },
  "addressInfo": {
    "addressLine0": "William Morris Endeavor",
    "addressLine1": "9601 Wilshire Blvd 3rd Floor",
    "city": "Beverly Hills",
    "province": "CA",
    "zip": "12345",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-123456",
    "mobilePhone": "55555-66666",
    "email": "john_cena@test_folio.com"
  },
  "preferredEmailCommunication": [
    "Support",
    "Programs",
    "Services"
  ]
}

HTTP status code 201

staging user created successfully

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for staging users",
  "type": "object",
  "properties": {
    "isEmailVerified": {
      "description": "A boolean flag that indicates whether the patron has completed email verification. If this value is not provided when creating a new record, it will default to false. However, for Kiosk user registrations, this value should be sent false.",
      "type": "boolean"
    },
    "minor": {
      "description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
      "type": "boolean"
    },
    "status": {
      "description": "Represents the patron's tier status, which can be either TIER-1 or TIER-2. If this value is not provided when creating a new record, the default status will be set to TIER-1.",
      "type": "string",
      "enum": [
        "TIER-1",
        "TIER-2"
      ]
    },
    "externalSystemId": {
      "description": "A unique ID (UUID) that corresponds to an external authority",
      "type": "string"
    },
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "firstName": {
          "description": "First name of the patron",
          "type": "string"
        },
        "preferredFirstName": {
          "description": "Preferred first name of the patron",
          "type": "string"
        },
        "middleName": {
          "description": "Middle name of the patron",
          "type": "string"
        },
        "lastName": {
          "description": "Last name of the patron",
          "type": "string"
        }
      },
      "required": [
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "description": "First line of the address",
          "type": "string"
        },
        "addressLine1": {
          "description": "Second line of the address",
          "type": "string"
        },
        "city": {
          "description": "City",
          "type": "string"
        },
        "province": {
          "description": "Province/State",
          "type": "string"
        },
        "zip": {
          "description": "Postal/Zip code",
          "type": "string"
        },
        "country": {
          "description": "Country",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "description": "Phone number of the patron",
          "type": "string"
        },
        "mobilePhone": {
          "description": "Mobile phone number of the patron",
          "type": "string"
        },
        "email": {
          "description": "Email of the patron",
          "type": "string"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Preferred email communication types",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "additionalProperties": false,
  "required": [
    "generalInfo",
    "contactInfo"
  ]
}

Example:

{
  "isEmailVerified": true,
  "status": "TIER-1",
  "minor": true,
  "externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
  "generalInfo": {
    "firstName": "John",
    "preferredFirstName": "John",
    "middleName": "Felix",
    "lastName": "Cena"
  },
  "addressInfo": {
    "addressLine0": "William Morris Endeavor",
    "addressLine1": "9601 Wilshire Blvd 3rd Floor",
    "city": "Beverly Hills",
    "province": "CA",
    "zip": "12345",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-123456",
    "mobilePhone": "55555-66666",
    "email": "john_cena@test_folio.com"
  },
  "preferredEmailCommunication": [
    "Support",
    "Programs",
    "Services"
  ]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 422

Validation error

Body

Media type: text/plain

Type: any

Example:

Validation error

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

put

put

Update a staging user based on external system ID.

Update a staging user based on external system ID.

URI Parameters

  • externalSystemId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a staging user

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for staging users",
  "type": "object",
  "properties": {
    "isEmailVerified": {
      "description": "A boolean flag that indicates whether the patron has completed email verification. If this value is not provided when creating a new record, it will default to false. However, for Kiosk user registrations, this value should be sent false.",
      "type": "boolean"
    },
    "minor": {
      "description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
      "type": "boolean"
    },
    "status": {
      "description": "Represents the patron's tier status, which can be either TIER-1 or TIER-2. If this value is not provided when creating a new record, the default status will be set to TIER-1.",
      "type": "string",
      "enum": [
        "TIER-1",
        "TIER-2"
      ]
    },
    "externalSystemId": {
      "description": "A unique ID (UUID) that corresponds to an external authority",
      "type": "string"
    },
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "firstName": {
          "description": "First name of the patron",
          "type": "string"
        },
        "preferredFirstName": {
          "description": "Preferred first name of the patron",
          "type": "string"
        },
        "middleName": {
          "description": "Middle name of the patron",
          "type": "string"
        },
        "lastName": {
          "description": "Last name of the patron",
          "type": "string"
        }
      },
      "required": [
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "description": "First line of the address",
          "type": "string"
        },
        "addressLine1": {
          "description": "Second line of the address",
          "type": "string"
        },
        "city": {
          "description": "City",
          "type": "string"
        },
        "province": {
          "description": "Province/State",
          "type": "string"
        },
        "zip": {
          "description": "Postal/Zip code",
          "type": "string"
        },
        "country": {
          "description": "Country",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "description": "Phone number of the patron",
          "type": "string"
        },
        "mobilePhone": {
          "description": "Mobile phone number of the patron",
          "type": "string"
        },
        "email": {
          "description": "Email of the patron",
          "type": "string"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Preferred email communication types",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "additionalProperties": false,
  "required": [
    "generalInfo",
    "contactInfo"
  ]
}

Example:

{
  "isEmailVerified": true,
  "status": "TIER-1",
  "minor": true,
  "externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
  "generalInfo": {
    "firstName": "John",
    "preferredFirstName": "John",
    "middleName": "Felix",
    "lastName": "Cena"
  },
  "addressInfo": {
    "addressLine0": "William Morris Endeavor",
    "addressLine1": "9601 Wilshire Blvd 3rd Floor",
    "city": "Beverly Hills",
    "province": "CA",
    "zip": "12345",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-123456",
    "mobilePhone": "55555-66666",
    "email": "john_cena@test_folio.com"
  },
  "preferredEmailCommunication": [
    "Support",
    "Programs",
    "Services"
  ]
}

HTTP status code 200

staging user updated successfully

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for staging users",
  "type": "object",
  "properties": {
    "isEmailVerified": {
      "description": "A boolean flag that indicates whether the patron has completed email verification. If this value is not provided when creating a new record, it will default to false. However, for Kiosk user registrations, this value should be sent false.",
      "type": "boolean"
    },
    "minor": {
      "description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
      "type": "boolean"
    },
    "status": {
      "description": "Represents the patron's tier status, which can be either TIER-1 or TIER-2. If this value is not provided when creating a new record, the default status will be set to TIER-1.",
      "type": "string",
      "enum": [
        "TIER-1",
        "TIER-2"
      ]
    },
    "externalSystemId": {
      "description": "A unique ID (UUID) that corresponds to an external authority",
      "type": "string"
    },
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "firstName": {
          "description": "First name of the patron",
          "type": "string"
        },
        "preferredFirstName": {
          "description": "Preferred first name of the patron",
          "type": "string"
        },
        "middleName": {
          "description": "Middle name of the patron",
          "type": "string"
        },
        "lastName": {
          "description": "Last name of the patron",
          "type": "string"
        }
      },
      "required": [
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "description": "First line of the address",
          "type": "string"
        },
        "addressLine1": {
          "description": "Second line of the address",
          "type": "string"
        },
        "city": {
          "description": "City",
          "type": "string"
        },
        "province": {
          "description": "Province/State",
          "type": "string"
        },
        "zip": {
          "description": "Postal/Zip code",
          "type": "string"
        },
        "country": {
          "description": "Country",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "description": "Phone number of the patron",
          "type": "string"
        },
        "mobilePhone": {
          "description": "Mobile phone number of the patron",
          "type": "string"
        },
        "email": {
          "description": "Email of the patron",
          "type": "string"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Preferred email communication types",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "additionalProperties": false,
  "required": [
    "generalInfo",
    "contactInfo"
  ]
}

Example:

{
  "isEmailVerified": true,
  "status": "TIER-1",
  "minor": true,
  "externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
  "generalInfo": {
    "firstName": "John",
    "preferredFirstName": "John",
    "middleName": "Felix",
    "lastName": "Cena"
  },
  "addressInfo": {
    "addressLine0": "William Morris Endeavor",
    "addressLine1": "9601 Wilshire Blvd 3rd Floor",
    "city": "Beverly Hills",
    "province": "CA",
    "zip": "12345",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-123456",
    "mobilePhone": "55555-66666",
    "email": "john_cena@test_folio.com"
  },
  "preferredEmailCommunication": [
    "Support",
    "Programs",
    "Services"
  ]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Staging user with a given external system Id not found

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "external_patron_error.schema",
  "description": "An external_patron user error",
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Error code"
    },
    "errorMessage": {
      "type": "string",
      "description": "Error message text",
      "examples": [
        {
          "code": "STAGING_USER_NOT_FOUND",
          "errorMessage": "Staging user does not exist"
        }
      ]
    }
  },
  "required": [
    "code",
    "errorMessage"
  ]
}

Example:

{
  "code": "STAGING_USER_NOT_FOUND",
  "errorMessage": "Staging user does not exist"
}

HTTP status code 422

Validation error

Body

Media type: text/plain

Type: any

Example:

Validation error

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

post get

post

Creates external patron request

get

(Secure) Return account details for the user provided in access token(x-okapi-token)

Creates external patron request

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for external patron information including general info, addresses, contact info",
  "type": "object",
  "properties": {
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "externalSystemId": {
          "type": "string",
          "description": "A unique ID that corresponds to an external authority"
        },
        "firstName": {
          "type": "string",
          "description": "The external patron's given name"
        },
        "preferredFirstName": {
          "type": "string",
          "description": "The user's preferred name"
        },
        "middleName": {
          "type": "string",
          "description": "The external patron's middle name (if any)"
        },
        "lastName": {
          "type": "string",
          "description": "The external patron's surname"
        }
      },
      "required": [
        "externalSystemId",
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "type": "string",
          "description": "Address, Line 0"
        },
        "addressLine1": {
          "type": "string",
          "description": "Address, Line 1"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "province": {
          "type": "string",
          "description": "Province"
        },
        "zip": {
          "type": "string",
          "description": "Zip Code"
        },
        "country": {
          "type": "string",
          "description": "Country"
        }
      },
      "required": [
        "addressLine0",
        "city",
        "province",
        "zip",
        "country"
      ],
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "type": "string",
          "description": "The user's primary phone number"
        },
        "mobilePhone": {
          "type": "string",
          "description": "The user's mobile phone number"
        },
        "email": {
          "type": "string",
          "description": "The user's email address",
          "format": "email"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Email communication info of external patron",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "required": [
    "generalInfo",
    "addressInfo",
    "contactInfo"
  ],
  "additionalProperties": false
}

Example:

{
  "generalInfo": {
    "externalSystemId": "ext-123456",
    "firstName": "John",
    "preferredFirstName": "Johnny",
    "middleName": "M",
    "lastName": "Doe"
  },
  "addressInfo": {
    "addressLine0": "456 Side St",
    "addressLine1": "Suite 500",
    "city": "Metropolis",
    "province": "NY",
    "zip": "12346",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-1234",
    "mobilePhone": "555-5678",
    "email": "john.doe@example.com"
  },
  "preferredEmailCommunication": ["Support", "Programs"]
}

HTTP status code 201

Returns data for a new created external patron

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for external patron information including general info, addresses, contact info",
  "type": "object",
  "properties": {
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "externalSystemId": {
          "type": "string",
          "description": "A unique ID that corresponds to an external authority"
        },
        "firstName": {
          "type": "string",
          "description": "The external patron's given name"
        },
        "preferredFirstName": {
          "type": "string",
          "description": "The user's preferred name"
        },
        "middleName": {
          "type": "string",
          "description": "The external patron's middle name (if any)"
        },
        "lastName": {
          "type": "string",
          "description": "The external patron's surname"
        }
      },
      "required": [
        "externalSystemId",
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "type": "string",
          "description": "Address, Line 0"
        },
        "addressLine1": {
          "type": "string",
          "description": "Address, Line 1"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "province": {
          "type": "string",
          "description": "Province"
        },
        "zip": {
          "type": "string",
          "description": "Zip Code"
        },
        "country": {
          "type": "string",
          "description": "Country"
        }
      },
      "required": [
        "addressLine0",
        "city",
        "province",
        "zip",
        "country"
      ],
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "type": "string",
          "description": "The user's primary phone number"
        },
        "mobilePhone": {
          "type": "string",
          "description": "The user's mobile phone number"
        },
        "email": {
          "type": "string",
          "description": "The user's email address",
          "format": "email"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Email communication info of external patron",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "required": [
    "generalInfo",
    "addressInfo",
    "contactInfo"
  ],
  "additionalProperties": false
}

Example:

{
  "generalInfo": {
    "externalSystemId": "ext-123456",
    "firstName": "John",
    "preferredFirstName": "Johnny",
    "middleName": "M",
    "lastName": "Doe"
  },
  "addressInfo": {
    "addressLine0": "456 Side St",
    "addressLine1": "Suite 500",
    "city": "Metropolis",
    "province": "NY",
    "zip": "12346",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-1234",
    "mobilePhone": "555-5678",
    "email": "john.doe@example.com"
  },
  "preferredEmailCommunication": ["Support", "Programs"]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 409

Conflict

Body

Media type: text/plain

Type: any

Example:

Optimistic Locking Conflict

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "external_patron_error.schema",
  "description": "An external_patron user error",
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "description": "Error code"
    },
    "errorMessage": {
      "type": "string",
      "description": "Error message text",
      "examples": [
        {
          "value": "MULTIPLE_USER_WITH_EMAIL",
          "description": "Multiple users found with the same email"
        },
        {
          "value": "USER_ACCOUNT_INACTIVE",
          "description": "User account is not active"
        },
        {
          "value": "USER_ALREADY_EXIST",
          "description": "User already exists"
        },
        {
          "value": "INVALID_PATRON_GROUP",
          "description": "User does not belong to the required patron group"
        }
      ]
    }
  },
  "required": [
    "code",
    "errorMessage"
  ]
}

Example:

{
  "code": 422,
  "errorMessage": "USER_ALREADY_EXIST"
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

post

(Secure) Services that provide hold management

post

(Secure) Creates a hold request on an existing item for the user

(Secure) Creates a hold request on an existing item for the user

URI Parameters

  • itemId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO item

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 201

Returns data for a new hold request on the specified item

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create hold -- unauthorized

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

item not found

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

get

Service that provides a list of allowed pickup service points

get

(Secure) Returns a list of pickup service points allowed for a particular patron and instance

(Secure) Returns a list of pickup service points allowed for a particular patron and instance

URI Parameters

  • itemId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO item

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Allowed pickup service points grouped by request type",
  "type": "object",
  "properties": {
    "allowedServicePoints": {
      "description": "Allowed pickup service point IDs for Page requests",
      "type": "array",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "default": null,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "UUID string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "uuid.schema",
            "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Service point name"
          },
          "discoveryName": {
            "type": "string",
            "description": "discoveryDisplayName of Service point"
          }
        },
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "required": [
    "allowedServicePoints"
  ]
}

Example:

{
  "allowedServicePoints" : [ {
    "id" : "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
    "name" : "Circ Desk 1",
    "discoveryName" : "Circ Desk 1"
  }, {
    "id" : "c4c90014-c8c9-4ade-8f24-b5e313319f4b",
    "name" : "Circ Desk 2",
    "discoveryName" : "Circ Desk 2"
  } ]
}

HTTP status code 200

Successfully returns a list of allowed service points

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Allowed pickup service points grouped by request type",
  "type": "object",
  "properties": {
    "allowedServicePoints": {
      "description": "Allowed pickup service point IDs for Page requests",
      "type": "array",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "default": null,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "UUID string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "uuid.schema",
            "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Service point name"
          },
          "discoveryName": {
            "type": "string",
            "description": "discoveryDisplayName of Service point"
          }
        },
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "required": [
    "allowedServicePoints"
  ]
}

Example:

{
  "allowedServicePoints" : [ {
    "id" : "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
    "name" : "Circ Desk 1",
    "discoveryName" : "Circ Desk 1"
  }, {
    "id" : "c4c90014-c8c9-4ade-8f24-b5e313319f4b",
    "name" : "Circ Desk 2",
    "discoveryName" : "Circ Desk 2"
  } ]
}

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

post

Services that provide hold management

post

(Secure) Creates a hold request on an existing item by instance ID for the user

(Secure) Creates a hold request on an existing item by instance ID for the user

URI Parameters

  • instanceId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO instance

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 201

Returns data for a new hold request on the selected item

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create hold -- unauthorized

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Instance with a given ID not found

Body

Media type: text/plain

Type: any

Example:

item not found

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

get

Service that provides a list of allowed pickup service points

get

(Secure) Returns a list of pickup service points allowed for a particular patron and instance

(Secure) Returns a list of pickup service points allowed for a particular patron and instance

URI Parameters

  • instanceId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO instance

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Allowed pickup service points grouped by request type",
  "type": "object",
  "properties": {
    "allowedServicePoints": {
      "description": "Allowed pickup service point IDs for Page requests",
      "type": "array",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "default": null,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "UUID string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "uuid.schema",
            "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Service point name"
          },
          "discoveryName": {
            "type": "string",
            "description": "discoveryDisplayName of Service point"
          }
        },
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "required": [
    "allowedServicePoints"
  ]
}

Example:

{
  "allowedServicePoints" : [ {
    "id" : "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
    "name" : "Circ Desk 1",
    "discoveryName" : "Circ Desk 1"
  }, {
    "id" : "c4c90014-c8c9-4ade-8f24-b5e313319f4b",
    "name" : "Circ Desk 2",
    "discoveryName" : "Circ Desk 2"
  } ]
}

HTTP status code 200

Successfully returns a list of allowed service points

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Allowed pickup service points grouped by request type",
  "type": "object",
  "properties": {
    "allowedServicePoints": {
      "description": "Allowed pickup service point IDs for Page requests",
      "type": "array",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "default": null,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "UUID string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "uuid.schema",
            "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Service point name"
          },
          "discoveryName": {
            "type": "string",
            "description": "discoveryDisplayName of Service point"
          }
        },
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "required": [
    "allowedServicePoints"
  ]
}

Example:

{
  "allowedServicePoints" : [ {
    "id" : "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
    "name" : "Circ Desk 1",
    "discoveryName" : "Circ Desk 1"
  }, {
    "id" : "c4c90014-c8c9-4ade-8f24-b5e313319f4b",
    "name" : "Circ Desk 2",
    "discoveryName" : "Circ Desk 2"
  } ]
}

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Services that provide hold management

Services that provide hold management by Id

post

post

(Secure) Removes the specified hold request

(Secure) Removes the specified hold request

URI Parameters

  • holdId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO hold request

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": " Request Cancelation Schema",
  "type": "object",
  "description": "Request cancelation schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "holdId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    }
  },
  "required": [
    "cancellationReasonId",
    "canceledByUserId",
    "holdId"
  ]
}

Example:

{
  "holdId" : "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "cancellationReasonId" : "de238b5c-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "ad238b6e-01fc-4205-83b8-ce27a650d829",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "canceledDate" : "2018-06-02T08:16:30Z"
}

HTTP status code 201

The specified hold request was removed

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to cancel hold -- unauthorized

HTTP status code 403

Access denied

Body

Media type: text/plain

Type: any

Example:

access denied

HTTP status code 404

hold with a given ID not found

Body

Media type: text/plain

Type: any

Example:

hold not found

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

get

Get accounts of external patrons based on flag

get

Return external_patrons detail

get put

Service endpoints that manage accounts by an existing email

get

Return account details for the specified external patron email

put

Updates external patron request

Return account details for the specified external patron email

URI Parameters

  • emailId: required(string)

    The email of external patron

Query Parameters

  • apikey: required(string)

    API Key

HTTP status code 200

Returns the external patron account info

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for external patron information including general info, addresses, contact info",
  "type": "object",
  "properties": {
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "externalSystemId": {
          "type": "string",
          "description": "A unique ID that corresponds to an external authority"
        },
        "firstName": {
          "type": "string",
          "description": "The external patron's given name"
        },
        "preferredFirstName": {
          "type": "string",
          "description": "The user's preferred name"
        },
        "middleName": {
          "type": "string",
          "description": "The external patron's middle name (if any)"
        },
        "lastName": {
          "type": "string",
          "description": "The external patron's surname"
        }
      },
      "required": [
        "externalSystemId",
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "type": "string",
          "description": "Address, Line 0"
        },
        "addressLine1": {
          "type": "string",
          "description": "Address, Line 1"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "province": {
          "type": "string",
          "description": "Province"
        },
        "zip": {
          "type": "string",
          "description": "Zip Code"
        },
        "country": {
          "type": "string",
          "description": "Country"
        }
      },
      "required": [
        "addressLine0",
        "city",
        "province",
        "zip",
        "country"
      ],
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "type": "string",
          "description": "The user's primary phone number"
        },
        "mobilePhone": {
          "type": "string",
          "description": "The user's mobile phone number"
        },
        "email": {
          "type": "string",
          "description": "The user's email address",
          "format": "email"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Email communication info of external patron",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "required": [
    "generalInfo",
    "addressInfo",
    "contactInfo"
  ],
  "additionalProperties": false
}

Example:

{
  "generalInfo": {
    "externalSystemId": "ext-123456",
    "firstName": "John",
    "preferredFirstName": "Johnny",
    "middleName": "M",
    "lastName": "Doe"
  },
  "addressInfo": {
    "addressLine0": "456 Side St",
    "addressLine1": "Suite 500",
    "city": "Metropolis",
    "province": "NY",
    "zip": "12346",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-1234",
    "mobilePhone": "555-5678",
    "email": "john.doe@example.com"
  },
  "preferredEmailCommunication": ["Support", "Programs"]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to get account -- unauthorized

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Item with a given EMAIL not found

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "external_patron_error.schema",
  "description": "An external_patron user error",
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "description": "Error code"
    },
    "errorMessage": {
      "type": "string",
      "description": "Error message text",
      "examples": [
        {
          "value": "USER_NOT_FOUND",
          "description": "User does not exist"
        }
      ]
    }
  },
  "required": [
    "code",
    "errorMessage"
  ]
}

Example:

{
  "code": 422,
  "errorMessage": "USER_ALREADY_EXIST"
}

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "external_patron_error.schema",
  "description": "An external_patron user error",
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "description": "Error code"
    },
    "errorMessage": {
      "type": "string",
      "description": "Error message text",
      "examples": [
        {
          "value": "MULTIPLE_USER_WITH_EMAIL",
          "description": "Multiple users found with the same email"
        }
      ]
    }
  },
  "required": [
    "code",
    "errorMessage"
  ]
}

Example:

{
  "code": 422,
  "errorMessage": "USER_ALREADY_EXIST"
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Updates external patron request

URI Parameters

  • emailId: required(string)

    The email of external patron

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for external patron information including general info, addresses, contact info",
  "type": "object",
  "properties": {
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "externalSystemId": {
          "type": "string",
          "description": "A unique ID that corresponds to an external authority"
        },
        "firstName": {
          "type": "string",
          "description": "The external patron's given name"
        },
        "preferredFirstName": {
          "type": "string",
          "description": "The user's preferred name"
        },
        "middleName": {
          "type": "string",
          "description": "The external patron's middle name (if any)"
        },
        "lastName": {
          "type": "string",
          "description": "The external patron's surname"
        }
      },
      "required": [
        "externalSystemId",
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "type": "string",
          "description": "Address, Line 0"
        },
        "addressLine1": {
          "type": "string",
          "description": "Address, Line 1"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "province": {
          "type": "string",
          "description": "Province"
        },
        "zip": {
          "type": "string",
          "description": "Zip Code"
        },
        "country": {
          "type": "string",
          "description": "Country"
        }
      },
      "required": [
        "addressLine0",
        "city",
        "province",
        "zip",
        "country"
      ],
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "type": "string",
          "description": "The user's primary phone number"
        },
        "mobilePhone": {
          "type": "string",
          "description": "The user's mobile phone number"
        },
        "email": {
          "type": "string",
          "description": "The user's email address",
          "format": "email"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Email communication info of external patron",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "required": [
    "generalInfo",
    "addressInfo",
    "contactInfo"
  ],
  "additionalProperties": false
}

Example:

{
  "generalInfo": {
    "externalSystemId": "ext-123456",
    "firstName": "John",
    "preferredFirstName": "Johnny",
    "middleName": "M",
    "lastName": "Doe"
  },
  "addressInfo": {
    "addressLine0": "456 Side St",
    "addressLine1": "Suite 500",
    "city": "Metropolis",
    "province": "NY",
    "zip": "12346",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-1234",
    "mobilePhone": "555-5678",
    "email": "john.doe@example.com"
  },
  "preferredEmailCommunication": ["Support", "Programs"]
}

HTTP status code 204

Returns data for a updated external patron request

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Information Schema",
  "description": "Schema for external patron information including general info, addresses, contact info",
  "type": "object",
  "properties": {
    "generalInfo": {
      "type": "object",
      "description": "General info of external patron",
      "properties": {
        "externalSystemId": {
          "type": "string",
          "description": "A unique ID that corresponds to an external authority"
        },
        "firstName": {
          "type": "string",
          "description": "The external patron's given name"
        },
        "preferredFirstName": {
          "type": "string",
          "description": "The user's preferred name"
        },
        "middleName": {
          "type": "string",
          "description": "The external patron's middle name (if any)"
        },
        "lastName": {
          "type": "string",
          "description": "The external patron's surname"
        }
      },
      "required": [
        "externalSystemId",
        "firstName",
        "lastName"
      ],
      "additionalProperties": false
    },
    "addressInfo": {
      "type": "object",
      "description": "Primary address info of external patron",
      "properties": {
        "addressLine0": {
          "type": "string",
          "description": "Address, Line 0"
        },
        "addressLine1": {
          "type": "string",
          "description": "Address, Line 1"
        },
        "city": {
          "type": "string",
          "description": "City name"
        },
        "province": {
          "type": "string",
          "description": "Province"
        },
        "zip": {
          "type": "string",
          "description": "Zip Code"
        },
        "country": {
          "type": "string",
          "description": "Country"
        }
      },
      "required": [
        "addressLine0",
        "city",
        "province",
        "zip",
        "country"
      ],
      "additionalProperties": false
    },
    "contactInfo": {
      "type": "object",
      "description": "Contact info of external patron",
      "properties": {
        "phone": {
          "type": "string",
          "description": "The user's primary phone number"
        },
        "mobilePhone": {
          "type": "string",
          "description": "The user's mobile phone number"
        },
        "email": {
          "type": "string",
          "description": "The user's email address",
          "format": "email"
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    },
    "preferredEmailCommunication": {
      "type": "array",
      "description": "Email communication info of external patron",
      "items": {
        "type": "string",
        "enum": [
          "Support",
          "Programs",
          "Services"
        ]
      },
      "maxItems": 3,
      "uniqueItems": true
    }
  },
  "required": [
    "generalInfo",
    "addressInfo",
    "contactInfo"
  ],
  "additionalProperties": false
}

Example:

{
  "generalInfo": {
    "externalSystemId": "ext-123456",
    "firstName": "John",
    "preferredFirstName": "Johnny",
    "middleName": "M",
    "lastName": "Doe"
  },
  "addressInfo": {
    "addressLine0": "456 Side St",
    "addressLine1": "Suite 500",
    "city": "Metropolis",
    "province": "NY",
    "zip": "12346",
    "country": "USA"
  },
  "contactInfo": {
    "phone": "555-1234",
    "mobilePhone": "555-5678",
    "email": "john.doe@example.com"
  },
  "preferredEmailCommunication": ["Support", "Programs"]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Item with a given ID not found

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "external_patron_error.schema",
  "description": "An external_patron user error",
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "description": "Error code"
    },
    "errorMessage": {
      "type": "string",
      "description": "Error message text",
      "examples": [
        {
          "value": "USER_NOT_FOUND",
          "description": "User does not exist"
        }
      ]
    }
  },
  "required": [
    "code",
    "errorMessage"
  ]
}

Example:

{
  "code": 422,
  "errorMessage": "USER_ALREADY_EXIST"
}

HTTP status code 409

Conflict

Body

Media type: text/plain

Type: any

Example:

Optimistic Locking Conflict

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "external_patron_error.schema",
  "description": "An external_patron user error",
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "description": "Error code"
    },
    "errorMessage": {
      "type": "string",
      "description": "Error message text",
      "examples": [
        {
          "value": "EMAIL_ALREADY_EXIST",
          "description": "User already exists with email provided in payload"
        },
        {
          "value": "PATRON_GROUP_NOT_APPLICABLE",
          "description": "Required Patron group not applicable for user"
        },
        {
          "value": "MULTIPLE_USER_WITH_EMAIL",
          "description": "Multiple users found with the same email"
        }
      ]
    }
  },
  "required": [
    "code",
    "errorMessage"
  ]
}

Example:

{
  "code": 422,
  "errorMessage": "USER_ALREADY_EXIST"
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

get

Service endpoints that manage accounts by an existing Id

get

Return account details for the specified FOLIO user id

Return account details for the specified FOLIO user id

URI Parameters

  • id: required(string)

    Patron's external system Id stored in FOLIO user record.

Query Parameters

  • includeLoans: (boolean - default: false)

    Indicates whether or not to include the loans array in the response

  • includeCharges: (boolean - default: false)

    Indicates whether or not to include the charges array in the response

  • includeHolds: (boolean - default: false)

    Indicates whether or not to include the holds array in the response

  • apikey: required(string)

    API Key

  • sortBy: (string)

    Part of CQL query, indicates the order of records within the lists of holds, charges, loans

    Example:

    item.title/sort.ascending
  • offset: (integer - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    1
  • limit: (integer - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10

HTTP status code 200

Returns the user account info

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Account Schema",
  "description": "The patron account consists of fees/fines, loans and holds",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The FOLIO id of the patron"
    },
    "totalCharges": {
      "type": "object",
      "description": "A patron's total outstanding fines and charges",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Money Schema",
      "additionalProperties": false,
      "properties": {
        "amount": {
          "type": "number",
          "description": "The amount of the fine or charge",
          "example": 3.14
        },
        "isoCurrencyCode": {
          "type": "string",
          "description": "An ISO 4217 standard currency code",
          "example": "USD"
        }
      },
      "required": [
        "amount",
        "isoCurrencyCode"
      ]
    },
    "totalChargesCount": {
      "type": "integer",
      "description": "The total number of fines and charges for the patron",
      "example": 10
    },
    "totalLoans": {
      "type": "integer",
      "description": "The total number of items loaned to the patron",
      "example": 10
    },
    "totalHolds": {
      "type": "integer",
      "description": "The total number of requested items for the patron",
      "example": 10
    },
    "charges": {
      "type": "array",
      "description": "A list of the patron's charges and fines",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Patron Charge Schema",
        "description": "A charge applied to the patron's account",
        "additionalProperties": false,
        "properties": {
          "item": {
            "type": "object",
            "description": "The item that is accruing the charge",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "title": "Patron Item Schema",
            "additionalProperties": false,
            "properties": {
              "instanceId": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
                "description": "The FOLIO id of the instance"
              },
              "itemId": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
                "description": "The FOLIO id of the item"
              },
              "title": {
                "type": "string",
                "description": "The title of the item"
              },
              "author": {
                "type": "string",
                "description": "The author of the item"
              },
              "isbn": {
                "type": "string",
                "description": "The ISBN of the item"
              }
            },
            "required": [
              "instanceId"
            ]
          },
          "chargeAmount": {
            "type": "object",
            "description": "The outstanding balance on the item",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "title": "Patron Money Schema",
            "additionalProperties": false,
            "properties": {
              "amount": {
                "type": "number",
                "description": "The amount of the fine or charge",
                "example": 3.14
              },
              "isoCurrencyCode": {
                "type": "string",
                "description": "An ISO 4217 standard currency code",
                "example": "USD"
              }
            },
            "required": [
              "amount",
              "isoCurrencyCode"
            ]
          },
          "accrualDate": {
            "type": "string",
            "format": "date-time",
            "description": "The date when charges begin to accrue"
          },
          "description": {
            "type": "string",
            "description": "A description of the charge"
          },
          "state": {
            "type": "string",
            "description": "The current state of the charge"
          },
          "reason": {
            "type": "string",
            "description": "The reason for this charge"
          },
          "feeFineId": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
            "description": "The UUID of the fee/fine for this charge"
          }
        }
      }
    },
    "holds": {
      "type": "array",
      "description": "A list of the patron's item holds",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Patron Hold Schema",
        "description": "Hold schema for patron portal integration",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
            "description": "The UUID of the request"
          },
          "item": {
            "type": "object",
            "description": "The item that is checked out",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "title": "Patron Item Schema",
            "additionalProperties": false,
            "properties": {
              "instanceId": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
                "description": "The FOLIO id of the instance"
              },
              "itemId": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
                "description": "The FOLIO id of the item"
              },
              "title": {
                "type": "string",
                "description": "The title of the item"
              },
              "author": {
                "type": "string",
                "description": "The author of the item"
              },
              "isbn": {
                "type": "string",
                "description": "The ISBN of the item"
              }
            },
            "required": [
              "instanceId"
            ]
          },
          "requestDate": {
            "type": "string",
            "format": "date-time",
            "description": "The date when the request was made"
          },
          "expirationDate": {
            "type": "string",
            "format": "date-time",
            "description": "The date when the request expires"
          },
          "status": {
            "type": "string",
            "description": "The status of the hold request",
            "enum": [
              "Open - Not yet filled",
              "Open - Awaiting pickup",
              "Open - In transit",
              "Closed - Filled",
              "Closed - Cancelled"
            ]
          },
          "pickupLocationId": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
            "description": "The UUID of the pick up location"
          },
          "queuePosition": {
            "type": "integer",
            "description": "The position in the queue for this patron"
          },
          "canceledDate": {
            "type": "string",
            "format": "date-time",
            "description": "The date when the request was made"
          },
          "cancellationReasonId": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
            "description": "The UUID of the request cancelation reason"
          },
          "canceledByUserId": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
            "description": "The UUID of the patron who cancels the request"
          },
          "cancellationAdditionalInformation": {
            "description": "Additional information about a cancelation",
            "type": "string"
          },
          "patronComments": {
            "description": "Comments made by the patron",
            "type": "string"
          }
        },
        "required": [
          "pickupLocationId"
        ]
      }
    },
    "loans": {
      "type": "array",
      "description": "A list of the patron's item checked out items",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Patron Loan Schema",
        "description": "A loan the patron has for an inventory item",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
            "description": "The id of the loan"
          },
          "item": {
            "type": "object",
            "description": "The item that is loaned out",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "title": "Patron Item Schema",
            "additionalProperties": false,
            "properties": {
              "instanceId": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
                "description": "The FOLIO id of the instance"
              },
              "itemId": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
                "description": "The FOLIO id of the item"
              },
              "title": {
                "type": "string",
                "description": "The title of the item"
              },
              "author": {
                "type": "string",
                "description": "The author of the item"
              },
              "isbn": {
                "type": "string",
                "description": "The ISBN of the item"
              }
            },
            "required": [
              "instanceId"
            ]
          },
          "loanDate": {
            "type": "string",
            "format": "date-time",
            "description": "The date the item was loaned out"
          },
          "dueDate": {
            "type": "string",
            "format": "date-time",
            "description": "The date the item is due"
          },
          "overdue": {
            "type": "boolean",
            "description": "Indicates if the item is overdue"
          }
        },
        "required": [
          "item",
          "loanDate",
          "dueDate",
          "overdue"
        ]
      }
    }
  },
  "required": [
    "totalCharges",
    "totalChargesCount",
    "totalLoans",
    "totalHolds",
    "charges",
    "holds",
    "loans"
  ]
}

Example:

{
  "totalCharges": {
    "amount": 50.0,
    "isoCurrencyCode": "USD"
  },
  "totalChargesCount": 1,
  "totalLoans": 1,
  "totalHolds": 1,
  "charges": [
    {
      "item" : {
        "instanceId" : "6e024cd5-c19a-4fe0-a2cd-64ce5814c694",
        "itemId" : "7d9dfe70-0158-489d-a7ed-2789eac277b3",
        "title" : "Some Book About Something",
        "author" : "Some Guy; Another Guy"
      },
      "chargeAmount" : {
        "amount" : 50.0,
        "isoCurrencyCode" : "USD"
      },
      "accrualDate" : "2018-01-31T00:00:01Z",
      "state" : "Paid Partially",
      "reason" : "damage - rebinding",
      "feeFineId" : "881c628b-e1c4-4711-b9d7-090af40f6a8f"
    }
  ],
  "holds": [
    {
      "requestId": "8bbac557-d66f-4571-bbbf-47a107cc1589",
      "item": {
        "instanceId": "255f82f3-5b1b-4239-93e4-ec6acf03ad9d",
        "itemId": "26670295-716a-4f84-8f65-2ef31707c017",
        "title": "I Want to Hold Your Hand",
        "author": "John Lennon; Paul McCartney"
      },
      "requestDate": "2018-06-02T08:16:30Z",
      "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
      "status": "Open - Not yet filled"
    }
  ],
  "loans": [
    {
      "id": "9a171a89-baca-4f1a-b2c4-d7253854864e",
      "item": {
        "instanceId": "6e024cd5-c19a-4fe0-a2cd-64ce5814c694",
        "itemId": "7d9dfe70-0158-489d-a7ed-2789eac277b3",
        "title": "Some Book About Something",
        "author": "Some Guy; Another Guy"
      },
      "loanDate": "2018-06-01T11:12:00Z",
      "dueDate": "2525-01-01T11:12:00Z",
      "overdue": false
    }
  ]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to get account -- unauthorized

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

account not found

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

post

Service endpoint for loan renewal

post

Renews a loan on the item for the user

Renews a loan on the item for the user

URI Parameters

  • id: required(string)

    Patron's external system Id stored in FOLIO user record.

  • itemId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO item

Query Parameters

  • apikey: required(string)

    API Key

HTTP status code 201

Returns the renewed loan data

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Loan Schema",
  "description": "A loan the patron has for an inventory item",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The id of the loan"
    },
    "item": {
      "type": "object",
      "description": "The item that is loaned out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "loanDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date the item was loaned out"
    },
    "dueDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date the item is due"
    },
    "overdue": {
      "type": "boolean",
      "description": "Indicates if the item is overdue"
    }
  },
  "required": [
    "item",
    "loanDate",
    "dueDate",
    "overdue"
  ]
}

Example:

{
  "id": "9a171a89-baca-4f1a-b2c4-d7253854864e",
  "item": {
    "instanceId": "6e024cd5-c19a-4fe0-a2cd-64ce5814c694",
    "itemId": "7d9dfe70-0158-489d-a7ed-2789eac277b3",
    "title": "Some Book About Something",
    "author": "Some Guy; Another Guy"
  },
  "loanDate": "2018-06-01T11:12:00Z",
  "dueDate": "2525-01-01T11:12:00Z",
  "overdue": false
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to renew loan -- unauthorized

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

item not found

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

post

Services that provide hold management

post

Creates a hold request on an existing item for the user

Creates a hold request on an existing item for the user

URI Parameters

  • id: required(string)

    Patron's external system Id stored in FOLIO user record.

  • itemId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO item

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 201

Returns data for a new hold request on the specified item

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create hold -- unauthorized

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

item not found

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

get

Service that provides a list of allowed pickup service points

get

Returns a list of pickup service points allowed for a particular patron and instance

Returns a list of pickup service points allowed for a particular patron and instance

URI Parameters

  • id: required(string)

    Patron's external system Id stored in FOLIO user record.

  • itemId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO item

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Allowed pickup service points grouped by request type",
  "type": "object",
  "properties": {
    "allowedServicePoints": {
      "description": "Allowed pickup service point IDs for Page requests",
      "type": "array",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "default": null,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "UUID string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "uuid.schema",
            "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Service point name"
          },
          "discoveryName": {
            "type": "string",
            "description": "discoveryDisplayName of Service point"
          }
        },
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "required": [
    "allowedServicePoints"
  ]
}

Example:

{
  "allowedServicePoints" : [ {
    "id" : "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
    "name" : "Circ Desk 1",
    "discoveryName" : "Circ Desk 1"
  }, {
    "id" : "c4c90014-c8c9-4ade-8f24-b5e313319f4b",
    "name" : "Circ Desk 2",
    "discoveryName" : "Circ Desk 2"
  } ]
}

HTTP status code 200

Successfully returns a list of allowed service points

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Allowed pickup service points grouped by request type",
  "type": "object",
  "properties": {
    "allowedServicePoints": {
      "description": "Allowed pickup service point IDs for Page requests",
      "type": "array",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "default": null,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "UUID string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "uuid.schema",
            "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Service point name"
          },
          "discoveryName": {
            "type": "string",
            "description": "discoveryDisplayName of Service point"
          }
        },
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "required": [
    "allowedServicePoints"
  ]
}

Example:

{
  "allowedServicePoints" : [ {
    "id" : "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
    "name" : "Circ Desk 1",
    "discoveryName" : "Circ Desk 1"
  }, {
    "id" : "c4c90014-c8c9-4ade-8f24-b5e313319f4b",
    "name" : "Circ Desk 2",
    "discoveryName" : "Circ Desk 2"
  } ]
}

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

post

Services that provide hold management

post

Creates a hold request on an existing item by instance ID for the user

Creates a hold request on an existing item by instance ID for the user

URI Parameters

  • id: required(string)

    Patron's external system Id stored in FOLIO user record.

  • instanceId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO instance

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 201

Returns data for a new hold request on the selected item

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create hold -- unauthorized

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Instance with a given ID not found

Body

Media type: text/plain

Type: any

Example:

item not found

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

get

Service that provides a list of allowed pickup service points

get

Returns a list of pickup service points allowed for a particular patron and instance

Returns a list of pickup service points allowed for a particular patron and instance

URI Parameters

  • id: required(string)

    Patron's external system Id stored in FOLIO user record.

  • instanceId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO instance

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Allowed pickup service points grouped by request type",
  "type": "object",
  "properties": {
    "allowedServicePoints": {
      "description": "Allowed pickup service point IDs for Page requests",
      "type": "array",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "default": null,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "UUID string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "uuid.schema",
            "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Service point name"
          },
          "discoveryName": {
            "type": "string",
            "description": "discoveryDisplayName of Service point"
          }
        },
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "required": [
    "allowedServicePoints"
  ]
}

Example:

{
  "allowedServicePoints" : [ {
    "id" : "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
    "name" : "Circ Desk 1",
    "discoveryName" : "Circ Desk 1"
  }, {
    "id" : "c4c90014-c8c9-4ade-8f24-b5e313319f4b",
    "name" : "Circ Desk 2",
    "discoveryName" : "Circ Desk 2"
  } ]
}

HTTP status code 200

Successfully returns a list of allowed service points

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Allowed pickup service points grouped by request type",
  "type": "object",
  "properties": {
    "allowedServicePoints": {
      "description": "Allowed pickup service point IDs for Page requests",
      "type": "array",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "default": null,
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "UUID string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "uuid.schema",
            "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Service point name"
          },
          "discoveryName": {
            "type": "string",
            "description": "discoveryDisplayName of Service point"
          }
        },
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "required": [
    "allowedServicePoints"
  ]
}

Example:

{
  "allowedServicePoints" : [ {
    "id" : "3a40852d-49fd-4df2-a1f9-6e2641a6e91f",
    "name" : "Circ Desk 1",
    "discoveryName" : "Circ Desk 1"
  }, {
    "id" : "c4c90014-c8c9-4ade-8f24-b5e313319f4b",
    "name" : "Circ Desk 2",
    "discoveryName" : "Circ Desk 2"
  } ]
}

HTTP status code 422

Validation error

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Services that provide hold management

Services that provide hold management by Id

post

post

Removes the specified hold request

Removes the specified hold request

URI Parameters

  • id: required(string)

    Patron's external system Id stored in FOLIO user record.

  • holdId: required(string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)

    The UUID of a FOLIO hold request

Query Parameters

  • apikey: required(string)

    API Key

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": " Request Cancelation Schema",
  "type": "object",
  "description": "Request cancelation schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "holdId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    }
  },
  "required": [
    "cancellationReasonId",
    "canceledByUserId",
    "holdId"
  ]
}

Example:

{
  "holdId" : "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "cancellationReasonId" : "de238b5c-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "ad238b6e-01fc-4205-83b8-ce27a650d829",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "canceledDate" : "2018-06-02T08:16:30Z"
}

HTTP status code 201

The specified hold request was removed

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Patron Hold Schema",
  "type": "object",
  "description": "Hold schema for patron portal integration",
  "additionalProperties": false,
  "properties": {
    "requestId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request"
    },
    "item": {
      "type": "object",
      "description": "The item that is checked out",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "title": "Patron Item Schema",
      "additionalProperties": false,
      "properties": {
        "instanceId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the instance"
        },
        "itemId": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
          "description": "The FOLIO id of the item"
        },
        "title": {
          "type": "string",
          "description": "The title of the item"
        },
        "author": {
          "type": "string",
          "description": "The author of the item"
        },
        "isbn": {
          "type": "string",
          "description": "The ISBN of the item"
        }
      },
      "required": [
        "instanceId"
      ]
    },
    "requestDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request expires"
    },
    "status": {
      "type": "string",
      "description": "The status of the hold request",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Open - In transit",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "pickupLocationId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the pick up location"
    },
    "queuePosition": {
      "type": "integer",
      "description": "The position in the queue for this patron"
    },
    "canceledDate": {
      "type": "string",
      "format": "date-time",
      "description": "The date when the request was made"
    },
    "cancellationReasonId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the request cancelation reason"
    },
    "canceledByUserId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "The UUID of the patron who cancels the request"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancelation",
      "type": "string"
    },
    "patronComments": {
      "description": "Comments made by the patron",
      "type": "string"
    }
  },
  "required": [
    "pickupLocationId"
  ]
}

Example:

{
  "requestId": "dd238b5b-01fc-4205-83b8-ce27a650d827",
  "item": {
    "instanceId": "23611f0b-35cc-4f40-af09-75907d7cc421",
    "itemId": "32e5757d-6566-466e-b69d-994eb33d2b62",
    "title": "Something's Got a Hold on Me",
    "author": "Etta James; Leroy Kirkland; Pearl Woods"
  },
  "requestDate": "2018-06-02T08:16:30Z",
  "expirationDate": "3000-01-30T08:16:30Z",
  "pickupLocationId": "ebab9ccc-4ece-4f35-bc82-01f3325abed8",
  "status": "Closed - Cancelled",
  "cancellationReasonId" : "dd238b5b-01fc-4205-83b8-ce27a650d828",
  "canceledByUserId" : "dd238b5b-01fc-4205-83b8-ce27a650d829",
  "canceledDate" : "2018-06-03T08:16:30Z",
  "cancellationAdditionalInformation" : "I don't need it anymore",
  "queuePosition" : 0,
  "patronComments": "Can you deliver this to the History building for Professor Grant?"
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

unable to process request -- constraint violation

HTTP status code 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to cancel hold -- unauthorized

HTTP status code 403

Access denied

Body

Media type: text/plain

Type: any

Example:

access denied

HTTP status code 404

hold with a given ID not found

Body

Media type: text/plain

Type: any

Example:

hold not found

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

get

get

Get the patron details by email ID or externalSystemId