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: staff_notes
 208         in: query
 209         description: Case insensitive search on staff_notes
 210         required: false
 211         type: string
 212       - name: relationship_type
 213         in: query
 214         description: Case insensitive search on relationship_type
 215         required: false
 216         type: string
 217       - name: gender
 218         in: query
 219         description: Case insensitive search on gender
 220         required: false
 221         type: string
 222       - name: userid
 223         in: query
 224         description: Case insensitive search on userid
 225         required: false
 226         type: string
 227       - name: opac_notes
 228         in: query
 229         description: Case insensitive search on opac_notes
 230         required: false
 231         type: string
 232       - name: altaddress_notes
 233         in: query
 234         description: Case insensitive search on altaddress_notes
 235         required: false
 236         type: string
 237       - name: statistics_1
 238         in: query
 239         description: Case insensitive search on statistics_1
 240         required: false
 241         type: string
 242       - name: statistics_2
 243         in: query
 244         description: Case insensitive search on statistics_2
 245         required: false
 246         type: string
 247       - name: autorenew_checkouts
 248         in: query
 249         description: Search on autorenew_checkouts
 250         required: false
 251         type: boolean
 252       - name: altcontact_firstname
 253         in: query
 254         description: Case insensitive search on altcontact_firstname
 255         required: false
 256         type: string
 257       - name: altcontact_surname
 258         in: query
 259         description: Case insensitive search on altcontact_surname
 260         required: false
 261         type: string
 262       - name: altcontact_address
 263         in: query
 264         description: Case insensitive search on altcontact_address
 265         required: false
 266         type: string
 267       - name: altcontact_address2
 268         in: query
 269         description: Case insensitive search on altcontact_address2
 270         required: false
 271         type: string
 272       - name: altcontact_city
 273         in: query
 274         description: Case insensitive search on altcontact_city
 275         required: false
 276         type: string
 277       - name: altcontact_state
 278         in: query
 279         description: Case insensitive search on altcontact_state
 280         required: false
 281         type: string
 282       - name: altcontact_postal_code
 283         in: query
 284         description: Case insensitive search on altcontact_postal_code
 285         required: false
 286         type: string
 287       - name: altcontact_country
 288         in: query
 289         description: Case insensitive search on altcontact_country
 290         required: false
 291         type: string
 292       - name: altcontact_phone
 293         in: query
 294         description: Case insensitive search on altcontact_phone
 295         required: false
 296         type: string
 297       - name: sms_number
 298         in: query
 299         description: Case insensitive search on sms_number
 300         required: false
 301         type: string
 302       - name: sms_provider_id
 303         in: query
 304         description: Case insensitive search on sms_provider_id
 305         required: false
 306         type: string
 307       - name: privacy
 308         in: query
 309         description: Search on privacy
 310         required: false
 311         type: string
 312       - name: privacy_guarantor_checkouts
 313         in: query
 314         description: Search on privacy_guarantor_checkouts
 315         required: false
 316         type: string
 317       - name: check_previous_checkout
 318         in: query
 319         description: Case insensitive search on check_previous_checkout
 320         required: false
 321         type: string
 322       - name: updated_on
 323         in: query
 324         description: Search on updated_on
 325         required: false
 326         type: string
 327       - name: last_seen
 328         in: query
 329         description: Case insensitive search on last_seen
 330         required: false
 331         type: string
 332       - name: lang
 333         in: query
 334         description: Case insensitive search on lang
 335         required: false
 336         type: string
 337       - name: login_attempts
 338         in: query
 339         description: Search on login_attempts
 340         required: false
 341         type: string
 342       - $ref: "../swagger.yaml#/parameters/match"
 343       - $ref: "../swagger.yaml#/parameters/order_by"
 344       - $ref: "../swagger.yaml#/parameters/page"
 345       - $ref: "../swagger.yaml#/parameters/per_page"
 346       - $ref: "../swagger.yaml#/parameters/q_param"
 347       - $ref: "../swagger.yaml#/parameters/q_body"
 348       - $ref: "../swagger.yaml#/parameters/request_id_header"
 349       - name: x-koha-embed
 350         in: header
 351         required: false
 352         description: Embed list sent as a request header
 353         type: array
 354         items:
 355           type: string
 356           enum:
 357             - extended_attributes
 358             - checkouts+count
 359             - overdues+count
 360             - account_balance
 361             - library
 362         collectionFormat: csv
 363     responses:
 364       "200":
 365         description: A list of patrons
 366         schema:
 367           type: array
 368           items:
 369             $ref: "../swagger.yaml#/definitions/patron"
 370       "401":
 371         description: Authentication required
 372         schema:
 373           $ref: "../swagger.yaml#/definitions/error"
 374       "403":
 375         description: Access forbidden
 376         schema:
 377           $ref: "../swagger.yaml#/definitions/error"
 378       "500":
 379         description: |
 380           Internal server error. Possible `error_code` attribute values:
 381
 382           * `internal_server_error`
 383         schema:
 384           $ref: "../swagger.yaml#/definitions/error"
 385       "503":
 386         description: Under maintenance
 387         schema:
 388           $ref: "../swagger.yaml#/definitions/error"
 389     x-koha-authorization:
 390       permissions:
 391         - borrowers: "edit_borrowers"
 392         - tools: "label_creator"
 393         - serials: "routing"
 394         - acquisition: "order_manage"
 395   post:
 396     x-mojo-to: Patrons#add
 397     operationId: addPatron
 398     tags:
 399       - patrons
 400     summary: Add patron
 401     parameters:
 402       - name: body
 403         in: body
 404         description: A JSON object containing information about the new patron
 405         required: true
 406         schema:
 407           $ref: "../swagger.yaml#/definitions/patron"
 408       - name: x-koha-welcome
 409         in: header
 410         required: false
 411         description: If set to 'email' triggers the sending of a welcome email
 412         type: string
 413     consumes:
 414       - application/json
 415     produces:
 416       - application/json
 417     responses:
 418       "201":
 419         description: A successfully created patron
 420         schema:
 421           items:
 422             $ref: "../swagger.yaml#/definitions/patron"
 423       "400":
 424         description: Bad parameter
 425         schema:
 426           $ref: "../swagger.yaml#/definitions/error"
 427       "401":
 428         description: Authentication required
 429         schema:
 430           $ref: "../swagger.yaml#/definitions/error"
 431       "403":
 432         description: Access forbidden
 433         schema:
 434           $ref: "../swagger.yaml#/definitions/error"
 435       "404":
 436         description: Resource not found
 437         schema:
 438           $ref: "../swagger.yaml#/definitions/error"
 439       "409":
 440         description: Conflict in creating resource
 441         schema:
 442           $ref: "../swagger.yaml#/definitions/error"
 443       "500":
 444         description: |
 445           Internal server error. Possible `error_code` attribute values:
 446
 447           * `internal_server_error`
 448         schema:
 449           $ref: "../swagger.yaml#/definitions/error"
 450       "503":
 451         description: Under maintenance
 452         schema:
 453           $ref: "../swagger.yaml#/definitions/error"
 454     x-koha-authorization:
 455       permissions:
 456         borrowers: edit_borrowers
 457 "/patrons/{patron_id}":
 458   get:
 459     x-mojo-to: Patrons#get
 460     operationId: getPatron
 461     tags:
 462       - patrons
 463     summary: Get patron
 464     parameters:
 465       - $ref: "../swagger.yaml#/parameters/patron_id_pp"
 466       - name: x-koha-embed
 467         in: header
 468         required: false
 469         description: Embed list sent as a request header
 470         type: array
 471         items:
 472           type: string
 473           enum:
 474             - extended_attributes
 475         collectionFormat: csv
 476     produces:
 477       - application/json
 478     responses:
 479       "200":
 480         description: A patron
 481         schema:
 482           $ref: "../swagger.yaml#/definitions/patron"
 483       "401":
 484         description: Authentication required
 485         schema:
 486           $ref: "../swagger.yaml#/definitions/error"
 487       "403":
 488         description: Access forbidden
 489         schema:
 490           $ref: "../swagger.yaml#/definitions/error"
 491       "404":
 492         description: Patron not found
 493         schema:
 494           $ref: "../swagger.yaml#/definitions/error"
 495       "500":
 496         description: |
 497           Internal server error. Possible `error_code` attribute values:
 498
 499           * `internal_server_error`
 500         schema:
 501           $ref: "../swagger.yaml#/definitions/error"
 502       "503":
 503         description: Under maintenance
 504         schema:
 505           $ref: "../swagger.yaml#/definitions/error"
 506     x-koha-authorization:
 507       permissions:
 508         borrowers: edit_borrowers
 509   put:
 510     x-mojo-to: Patrons#update
 511     operationId: updatePatron
 512     tags:
 513       - patrons
 514     summary: Update patron
 515     parameters:
 516       - $ref: "../swagger.yaml#/parameters/patron_id_pp"
 517       - name: body
 518         in: body
 519         description: A JSON object containing new information about existing patron
 520         required: true
 521         schema:
 522           $ref: "../swagger.yaml#/definitions/patron"
 523     consumes:
 524       - application/json
 525     produces:
 526       - application/json
 527     responses:
 528       "200":
 529         description: A successfully updated patron
 530         schema:
 531           items:
 532             $ref: "../swagger.yaml#/definitions/patron"
 533       "400":
 534         description: Bad parameter
 535         schema:
 536           $ref: "../swagger.yaml#/definitions/error"
 537       "403":
 538         description: Access forbidden
 539         schema:
 540           $ref: "../swagger.yaml#/definitions/error"
 541       "404":
 542         description: Resource not found
 543         schema:
 544           $ref: "../swagger.yaml#/definitions/error"
 545       "409":
 546         description: Conflict in updating resource
 547         schema:
 548           $ref: "../swagger.yaml#/definitions/error"
 549       "500":
 550         description: |
 551           Internal server error. Possible `error_code` attribute values:
 552
 553           * `internal_server_error`
 554         schema:
 555           $ref: "../swagger.yaml#/definitions/error"
 556       "503":
 557         description: Under maintenance
 558         schema:
 559           $ref: "../swagger.yaml#/definitions/error"
 560     x-koha-authorization:
 561       permissions:
 562         borrowers: "1"
 563   delete:
 564     x-mojo-to: Patrons#delete
 565     operationId: deletePatron
 566     tags:
 567       - patrons
 568     summary: Delete patron
 569     parameters:
 570       - $ref: "../swagger.yaml#/parameters/patron_id_pp"
 571     produces:
 572       - application/json
 573     responses:
 574       "204":
 575         description: Patron deleted
 576       "400":
 577         description: Patron deletion failed
 578         schema:
 579           $ref: "../swagger.yaml#/definitions/error"
 580       "401":
 581         description: Authentication required
 582         schema:
 583           $ref: "../swagger.yaml#/definitions/error"
 584       "403":
 585         description: Access forbidden
 586         schema:
 587           $ref: "../swagger.yaml#/definitions/error"
 588       "404":
 589         description: Patron not found
 590         schema:
 591           $ref: "../swagger.yaml#/definitions/error"
 592       "409":
 593         description: |
 594           Conflict. Possible `error_code` attribute values:
 595
 596             * `has_checkouts`: The patron has pending checkouts
 597             * `has_debt`: The patron has pending debts
 598             * `has_guarantees`: The patron has guarantees
 599             * `is_anonymous_patron`: The system-wide anonymous patron cannot be deleted
 600         schema:
 601           $ref: "../swagger.yaml#/definitions/error"
 602       "500":
 603         description: |
 604           Internal server error. Possible `error_code` attribute values:
 605
 606           * `internal_server_error`
 607         schema:
 608           $ref: "../swagger.yaml#/definitions/error"
 609       "503":
 610         description: Under maintenance
 611         schema:
 612           $ref: "../swagger.yaml#/definitions/error"
 613     x-koha-authorization:
 614       permissions:
 615         borrowers: delete_borrowers