api/v1/swagger/paths/patrons.yaml

   1 ---
   2 /patrons:
   3   get:
   4     x-mojo-to: Patrons#list
   5     operationId: listPatrons
   6     tags:
   7       - patrons
   8     summary: List patrons
   9     produces:
  10       - application/json
  11     parameters:
  12       - name: patron_id
  13         in: query
  14         description: Search on patron_id
  15         required: false
  16         type: string
  17       - name: cardnumber
  18         in: query
  19         description: Case insensitive search on cardnumber
  20         required: false
  21         type: string
  22       - name: surname
  23         in: query
  24         description: Case insensitive search on surname
  25         required: false
  26         type: string
  27       - name: firstname
  28         in: query
  29         description: Case insensitive search on firstname
  30         required: false
  31         type: string
  32       - name: title
  33         in: query
  34         description: Case insensitive search on title
  35         required: false
  36         type: string
  37       - name: other_name
  38         in: query
  39         description: Case insensitive search on othernames
  40         required: false
  41         type: string
  42       - name: initials
  43         in: query
  44         description: Case insensitive search on initials
  45         required: false
  46         type: string
  47       - name: street_number
  48         in: query
  49         description: Case insensitive search on streetnumber
  50         required: false
  51         type: string
  52       - name: street_type
  53         in: query
  54         description: Case insensitive search on streettype
  55         required: false
  56         type: string
  57       - name: address
  58         in: query
  59         description: Case insensitive search on address
  60         required: false
  61         type: string
  62       - name: address2
  63         in: query
  64         description: Case insensitive search on address2
  65         required: false
  66         type: string
  67       - name: city
  68         in: query
  69         description: Case insensitive search on city
  70         required: false
  71         type: string
  72       - name: state
  73         in: query
  74         description: Case insensitive search on state
  75         required: false
  76         type: string
  77       - name: postal_code
  78         in: query
  79         description: Case insensitive search on zipcode
  80         required: false
  81         type: string
  82       - name: country
  83         in: query
  84         description: Case insensitive search on country
  85         required: false
  86         type: string
  87       - name: email
  88         in: query
  89         description: Case insensitive search on email
  90         required: false
  91         type: string
  92       - name: phone
  93         in: query
  94         description: Case insensitive search on phone
  95         required: false
  96         type: string
  97       - name: mobile
  98         in: query
  99         description: Case insensitive search on mobile
 100         required: false
 101         type: string
 102       - name: fax
 103         in: query
 104         description: Case insensitive search on fax
 105         required: false
 106         type: string
 107       - name: secondary_email
 108         in: query
 109         description: Case insensitive search on secondary_email
 110         required: false
 111         type: string
 112       - name: secondary_phone
 113         in: query
 114         description: Case insensitive search on secondary_phone
 115         required: false
 116         type: string
 117       - name: altaddress_street_number
 118         in: query
 119         description: Case insensitive search on altaddress_street_number
 120         required: false
 121         type: string
 122       - name: altaddress_street_type
 123         in: query
 124         description: Case insensitive search on altaddress_street_type
 125         required: false
 126         type: string
 127       - name: altaddress_address
 128         in: query
 129         description: Case insensitive search on altaddress_address
 130         required: false
 131         type: string
 132       - name: altaddress_address2
 133         in: query
 134         description: Case insensitive search on altaddress_address2
 135         required: false
 136         type: string
 137       - name: altaddress_city
 138         in: query
 139         description: Case insensitive search on altaddress_city
 140         required: false
 141         type: string
 142       - name: altaddress_state
 143         in: query
 144         description: Case insensitive search on altaddress_state
 145         required: false
 146         type: string
 147       - name: altaddress_postal_code
 148         in: query
 149         description: Case insensitive search on altaddress_postal_code
 150         required: false
 151         type: string
 152       - name: altaddress_country
 153         in: query
 154         description: Case insensitive search on altaddress_country
 155         required: false
 156         type: string
 157       - name: altaddress_email
 158         in: query
 159         description: Case insensitive search on altaddress_email
 160         required: false
 161         type: string
 162       - name: altaddress_phone
 163         in: query
 164         description: Case insensitive search on altaddress_phone
 165         required: false
 166         type: string
 167       - name: date_of_birth
 168         in: query
 169         description: Case insensitive search on date_of_birth
 170         required: false
 171         type: string
 172       - name: library_id
 173         in: query
 174         description: Case insensitive search on library_id
 175         required: false
 176         type: string
 177       - name: category_id
 178         in: query
 179         description: Case insensitive search on category_id
 180         required: false
 181         type: string
 182       - name: date_enrolled
 183         in: query
 184         description: Case insensitive search on date_enrolled
 185         required: false
 186         type: string
 187       - name: expiry_date
 188         in: query
 189         description: Case insensitive search on expiry_date
 190         required: false
 191         type: string
 192       - name: incorrect_address
 193         in: query
 194         description: Search on incorrect_address
 195         required: false
 196         type: boolean
 197       - name: patron_card_lost
 198         in: query
 199         description: Search on patron_card_lost
 200         required: false
 201         type: boolean
 202       - name: restricted
 203         in: query
 204         description: Filter search by restricted
 205         required: false
 206         type: boolean
 207       - name: guarantor_id
 208         in: query
 209         description: Search on guarantor_id
 210         required: false
 211         type: string
 212       - name: staff_notes
 213         in: query
 214         description: Case insensitive search on staff_notes
 215         required: false
 216         type: string
 217       - name: relationship_type
 218         in: query
 219         description: Case insensitive search on relationship_type
 220         required: false
 221         type: string
 222       - name: gender
 223         in: query
 224         description: Case insensitive search on gender
 225         required: false
 226         type: string
 227       - name: userid
 228         in: query
 229         description: Case insensitive search on userid
 230         required: false
 231         type: string
 232       - name: opac_notes
 233         in: query
 234         description: Case insensitive search on opac_notes
 235         required: false
 236         type: string
 237       - name: altaddress_notes
 238         in: query
 239         description: Case insensitive search on altaddress_notes
 240         required: false
 241         type: string
 242       - name: statistics_1
 243         in: query
 244         description: Case insensitive search on statistics_1
 245         required: false
 246         type: string
 247       - name: statistics_2
 248         in: query
 249         description: Case insensitive search on statistics_2
 250         required: false
 251         type: string
 252       - name: autorenew_checkouts
 253         in: query
 254         description: Search on autorenew_checkouts
 255         required: false
 256         type: boolean
 257       - name: altcontact_firstname
 258         in: query
 259         description: Case insensitive search on altcontact_firstname
 260         required: false
 261         type: string
 262       - name: altcontact_surname
 263         in: query
 264         description: Case insensitive search on altcontact_surname
 265         required: false
 266         type: string
 267       - name: altcontact_address
 268         in: query
 269         description: Case insensitive search on altcontact_address
 270         required: false
 271         type: string
 272       - name: altcontact_address2
 273         in: query
 274         description: Case insensitive search on altcontact_address2
 275         required: false
 276         type: string
 277       - name: altcontact_city
 278         in: query
 279         description: Case insensitive search on altcontact_city
 280         required: false
 281         type: string
 282       - name: altcontact_state
 283         in: query
 284         description: Case insensitive search on altcontact_state
 285         required: false
 286         type: string
 287       - name: altcontact_postal_code
 288         in: query
 289         description: Case insensitive search on altcontact_postal_code
 290         required: false
 291         type: string
 292       - name: altcontact_country
 293         in: query
 294         description: Case insensitive search on altcontact_country
 295         required: false
 296         type: string
 297       - name: altcontact_phone
 298         in: query
 299         description: Case insensitive search on altcontact_phone
 300         required: false
 301         type: string
 302       - name: sms_number
 303         in: query
 304         description: Case insensitive search on sms_number
 305         required: false
 306         type: string
 307       - name: sms_provider_id
 308         in: query
 309         description: Case insensitive search on sms_provider_id
 310         required: false
 311         type: string
 312       - name: privacy
 313         in: query
 314         description: Search on privacy
 315         required: false
 316         type: string
 317       - name: privacy_guarantor_checkouts
 318         in: query
 319         description: Search on privacy_guarantor_checkouts
 320         required: false
 321         type: string
 322       - name: check_previous_checkout
 323         in: query
 324         description: Case insensitive search on check_previous_checkout
 325         required: false
 326         type: string
 327       - name: updated_on
 328         in: query
 329         description: Search on updated_on
 330         required: false
 331         type: string
 332       - name: last_seen
 333         in: query
 334         description: Case insensitive search on last_seen
 335         required: false
 336         type: string
 337       - name: lang
 338         in: query
 339         description: Case insensitive search on lang
 340         required: false
 341         type: string
 342       - name: login_attempts
 343         in: query
 344         description: Search on login_attempts
 345         required: false
 346         type: string
 347       - $ref: "../swagger.yaml#/parameters/match"
 348       - $ref: "../swagger.yaml#/parameters/order_by"
 349       - $ref: "../swagger.yaml#/parameters/page"
 350       - $ref: "../swagger.yaml#/parameters/per_page"
 351       - $ref: "../swagger.yaml#/parameters/q_param"
 352       - $ref: "../swagger.yaml#/parameters/q_body"
 353       - $ref: "../swagger.yaml#/parameters/q_header"
 354       - $ref: "../swagger.yaml#/parameters/request_id_header"
 355       - name: x-koha-embed
 356         in: header
 357         required: false
 358         description: Embed list sent as a request header
 359         type: array
 360         items:
 361           type: string
 362           enum:
 363             - extended_attributes
 364         collectionFormat: csv
 365     responses:
 366       "200":
 367         description: A list of patrons
 368         schema:
 369           type: array
 370           items:
 371             $ref: "../swagger.yaml#/definitions/patron"
 372       "401":
 373         description: Authentication required
 374         schema:
 375           $ref: "../swagger.yaml#/definitions/error"
 376       "403":
 377         description: Access forbidden
 378         schema:
 379           $ref: "../swagger.yaml#/definitions/error"
 380       "500":
 381         description: |
 382           Internal server error. Possible `error_code` attribute values:
 383
 384           * `internal_server_error`
 385         schema:
 386           $ref: "../swagger.yaml#/definitions/error"
 387       "503":
 388         description: Under maintenance
 389         schema:
 390           $ref: "../swagger.yaml#/definitions/error"
 391     x-koha-authorization:
 392       permissions:
 393         - borrowers: "edit_borrowers"
 394         - tools: "label_creator"
 395         - serials: "routing"
 396         - acquisition: "order_manage"
 397     x-koha-embed:
 398       - extended_attributes
 399       - checkouts+count
 400       - overdues+count
 401       - account_balance
 402   post:
 403     x-mojo-to: Patrons#add
 404     operationId: addPatron
 405     tags:
 406       - patrons
 407     summary: Add patron
 408     parameters:
 409       - name: body
 410         in: body
 411         description: A JSON object containing information about the new patron
 412         required: true
 413         schema:
 414           $ref: "../swagger.yaml#/definitions/patron"
 415     consumes:
 416       - application/json
 417     produces:
 418       - application/json
 419     responses:
 420       "201":
 421         description: A successfully created patron
 422         schema:
 423           items:
 424             $ref: "../swagger.yaml#/definitions/patron"
 425       "400":
 426         description: Bad parameter
 427         schema:
 428           $ref: "../swagger.yaml#/definitions/error"
 429       "401":
 430         description: Authentication required
 431         schema:
 432           $ref: "../swagger.yaml#/definitions/error"
 433       "403":
 434         description: Access forbidden
 435         schema:
 436           $ref: "../swagger.yaml#/definitions/error"
 437       "404":
 438         description: Resource not found
 439         schema:
 440           $ref: "../swagger.yaml#/definitions/error"
 441       "409":
 442         description: Conflict in creating resource
 443         schema:
 444           $ref: "../swagger.yaml#/definitions/error"
 445       "500":
 446         description: |
 447           Internal server error. Possible `error_code` attribute values:
 448
 449           * `internal_server_error`
 450         schema:
 451           $ref: "../swagger.yaml#/definitions/error"
 452       "503":
 453         description: Under maintenance
 454         schema:
 455           $ref: "../swagger.yaml#/definitions/error"
 456     x-koha-authorization:
 457       permissions:
 458         borrowers: edit_borrowers
 459 "/patrons/{patron_id}":
 460   get:
 461     x-mojo-to: Patrons#get
 462     operationId: getPatron
 463     tags:
 464       - patrons
 465     summary: Get patron
 466     parameters:
 467       - $ref: "../swagger.yaml#/parameters/patron_id_pp"
 468       - name: x-koha-embed
 469         in: header
 470         required: false
 471         description: Embed list sent as a request header
 472         type: array
 473         items:
 474           type: string
 475           enum:
 476             - extended_attributes
 477         collectionFormat: csv
 478     produces:
 479       - application/json
 480     responses:
 481       "200":
 482         description: A patron
 483         schema:
 484           $ref: "../swagger.yaml#/definitions/patron"
 485       "401":
 486         description: Authentication required
 487         schema:
 488           $ref: "../swagger.yaml#/definitions/error"
 489       "403":
 490         description: Access forbidden
 491         schema:
 492           $ref: "../swagger.yaml#/definitions/error"
 493       "404":
 494         description: Patron not found
 495         schema:
 496           $ref: "../swagger.yaml#/definitions/error"
 497       "500":
 498         description: |
 499           Internal server error. Possible `error_code` attribute values:
 500
 501           * `internal_server_error`
 502         schema:
 503           $ref: "../swagger.yaml#/definitions/error"
 504       "503":
 505         description: Under maintenance
 506         schema:
 507           $ref: "../swagger.yaml#/definitions/error"
 508     x-koha-authorization:
 509       permissions:
 510         borrowers: edit_borrowers
 511     x-koha-embed:
 512       - extended_attributes
 513   put:
 514     x-mojo-to: Patrons#update
 515     operationId: updatePatron
 516     tags:
 517       - patrons
 518     summary: Update patron
 519     parameters:
 520       - $ref: "../swagger.yaml#/parameters/patron_id_pp"
 521       - name: body
 522         in: body
 523         description: A JSON object containing new information about existing patron
 524         required: true
 525         schema:
 526           $ref: "../swagger.yaml#/definitions/patron"
 527     consumes:
 528       - application/json
 529     produces:
 530       - application/json
 531     responses:
 532       "200":
 533         description: A successfully updated patron
 534         schema:
 535           items:
 536             $ref: "../swagger.yaml#/definitions/patron"
 537       "400":
 538         description: Bad parameter
 539         schema:
 540           $ref: "../swagger.yaml#/definitions/error"
 541       "403":
 542         description: Access forbidden
 543         schema:
 544           $ref: "../swagger.yaml#/definitions/error"
 545       "404":
 546         description: Resource not found
 547         schema:
 548           $ref: "../swagger.yaml#/definitions/error"
 549       "409":
 550         description: Conflict in updating resource
 551         schema:
 552           $ref: "../swagger.yaml#/definitions/error"
 553       "500":
 554         description: |
 555           Internal server error. Possible `error_code` attribute values:
 556
 557           * `internal_server_error`
 558         schema:
 559           $ref: "../swagger.yaml#/definitions/error"
 560       "503":
 561         description: Under maintenance
 562         schema:
 563           $ref: "../swagger.yaml#/definitions/error"
 564     x-koha-authorization:
 565       permissions:
 566         borrowers: "1"
 567   delete:
 568     x-mojo-to: Patrons#delete
 569     operationId: deletePatron
 570     tags:
 571       - patrons
 572     summary: Delete patron
 573     parameters:
 574       - $ref: "../swagger.yaml#/parameters/patron_id_pp"
 575     produces:
 576       - application/json
 577     responses:
 578       "204":
 579         description: Patron deleted
 580       "400":
 581         description: Patron deletion failed
 582         schema:
 583           $ref: "../swagger.yaml#/definitions/error"
 584       "401":
 585         description: Authentication required
 586         schema:
 587           $ref: "../swagger.yaml#/definitions/error"
 588       "403":
 589         description: Access forbidden
 590         schema:
 591           $ref: "../swagger.yaml#/definitions/error"
 592       "404":
 593         description: Patron not found
 594         schema:
 595           $ref: "../swagger.yaml#/definitions/error"
 596       "409":
 597         description: |
 598           Conflict. Possible `error_code` attribute values:
 599
 600             * `has_checkouts`: The patron has pending checkouts
 601             * `has_debt`: The patron has pending debts
 602             * `has_guarantees`: The patron has guarantees
 603             * `is_anonymous_patron`: The system-wide anonymous patron cannot be deleted
 604         schema:
 605           $ref: "../swagger.yaml#/definitions/error"
 606       "500":
 607         description: |
 608           Internal server error. Possible `error_code` attribute values:
 609
 610           * `internal_server_error`
 611         schema:
 612           $ref: "../swagger.yaml#/definitions/error"
 613       "503":
 614         description: Under maintenance
 615         schema:
 616           $ref: "../swagger.yaml#/definitions/error"
 617     x-koha-authorization:
 618       permissions:
 619         borrowers: delete_borrowers