get:
  operationId: contactList
  tags:
    - Patient
  summary: Contact list
  description: Get a contact list for printing address labels, sending e-mail and/ or calling.
  parameters: 
    - name: patUnids
      in: query
      mandatory: true
      description: |-
        A comma separated list of patUnid values, as provided by other API endpoints.
        For each patUnid the contact details are in the response. If sending lots of patUnids, we suggest you call this API in a POST (which is also allowed, though the semantic intent of this method is GET: It only queries and makes no changes) to avoid HTTP limits on query length.
      schema:
        type: array
        items:
          $ref: ../schemas/pat-patUnid.yaml
        example: "1234,5678"
    - name: fields
      in: query
      mandatory: true
      description: |-
        Comma separated list of data fields that shold be returned in the response. Available options are:
        bsn         - adds CSV column/JSON key 'bsn'.
        patPubId    - adds CSV column/JSON key 'patPubId'.
        patUnid     - adds CSV column/JSON key 'patUnid'.
        gender      - adds CSV column/JSON key 'gender', with values 'O', 'M', or 'F'.
        displayName - adds CSV column/JSON key 'displayName' with the full name of the patient as one would write it on an envelope.
        fullName    - adds CSV columns 'initials', 'firstNames', 'infixOwn', 'ownLastName', 'infixPartner', 'partnerLastName', and JSON key 'name' with as value an object with those keys.
        addressLine - adds CSV column/JSON key 'addressLine'.
        postcode    - adds CSV column/JSON key 'postcode'.
        city        - adds CSV column/JSON key 'city'.
        tel         - adds CSV column/JSON key 'tel'.
        email       - adds CSV column/JSON key 'email'.
        dob         - adds CSV column/JSON key 'dob'.

        See the descriptions in the JSON output section of this documentation for the formatting of these outputs.
      example: "displayName,addressLine,postcode,city"
    - name: Accept
      in: header
      description: |-
        This API is capable of emitting both CSV (RFC 4180) and JSON. If a CSV response is needed, ensure mimetype `text/csv` is
        mentioned in the `Accept` header at a higher quality than `application/csv`. If no Accept header is provided, the API
        responds with JSON.
      schema: 
        type: string
        enum: 
          - text/csv
          - application/json
  responses:
    '200':
      description: |-
        A patient contact list for (electronic) mailing or phone contact. Per patient only requested details (via `column`) are provided. Any patient that isn't found isn't included in the output.
      headers:
        Content-Type:
          description: The actual content-type of the response.
          schema: 
            type: string
      content:
        application/json:
          schema: 
            type: array
            items: 
              type: object
              properties:
                patUnid:
                  $ref: '../schemas/PatIdentity.yaml#/patUnid'
                patPubId:
                  $ref: '../schemas/PatIdentity.yaml#/patPubId'
                gender:
                  $ref: '../schemas/PatIdentity.yaml#/gender'
                displayName:
                  $ref: '../schemas/pat-Name.yaml#/properties/displayName'
                name:
                  $ref: '../schemas/PatIdentity.yaml#/name'
                addressLine:
                  description: The concatenation of street, housenumber and -suffix on one line.
                  type: string
                postcode:
                  $ref: ../schemas/postcode.yaml
                city:
                  $ref: ../schemas/city.yaml
                tel:
                  $ref: '../schemas/PatIdentity.yaml#/contact/properties/tel'
                email:
                  $ref: '../schemas/PatIdentity.yaml#/contact/properties/email'
                bsn:
                  $ref: '../schemas/PatIdentity.yaml#/bsn'
                dob:
                  $ref: '../schemas/PatIdentity.yaml#/dob'
        text/csv:
          schema: 
            type: string
            description: |-
              An RFC4180 (with comma separator) output, with headers as requested.
    '400':
      description: The request is invalid; for example, it doesn't contain the required `patUnids` or `columns` parameter.
    '401':
      $ref: '../zoo-api.yaml#/components/responses/JwtFailure'
    '406':
      description: |-
        An accept header was sent, but neither `text/csv` nor `application/json` is allowed by it.
        As this endpoint can only render its data in those two content types, no response is possible.