openapi: 3.2.0
info:
  title: Folio Get External Users API
  version: v1
  description: 'Operations tagged getExternalUsers across 2 of this provider''s published API definitions: folio-mod-circulation-bff-circulationbff-openapi.json, folio-mod-circulation-bff-circulationbff-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: getExternalUsers
paths:
  /circulation-bff/external-users/{externalUserId}/tenant/{tenantId}:
    get:
      description: Find users by externalSystemId in the specified tenant
      operationId: getExternalUsers
      tags:
      - getExternalUsers
      parameters:
      - $ref: '#/components/parameters/externalUserId'
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Collection of users found by externalSystemId in the specified tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userCollection'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '422':
          $ref: '#/components/responses/unprocessableEntityResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Get external users
      x-summary-source: derived
components:
  schemas:
    resultInfo:
      $schema: http://json-schema.org/draft-04/schema#
      id: resultInfo.schema
      description: Faceting of result sets
      type: object
      properties:
        totalRecords:
          type: integer
          description: Estimated or exact total number of records
        totalRecordsEstimated:
          type: boolean
          description: True if totalRecords is an estimation, false if it is the exact number
        totalRecordsRounded:
          type: integer
          description: The rounded value of totalRecords if totalRecords is an estimation
        responseTime:
          type: number
          description: Response time
        facets:
          type: array
          description: Array of facets
          items:
            type: object
            description: A facet
            properties:
              facetValues:
                type: array
                description: Array of facet values
                items:
                  type: object
                  description: A facet value
                  properties:
                    count:
                      type: integer
                      description: Count of facet values
                    value:
                      description: Value Object
              type:
                type: string
                description: Type of facet
        diagnostics:
          type: array
          description: Array of diagnostic information
          items:
            type: object
            description: Diagnostic information
            properties:
              source:
                type: string
                description: Source reporting the diagnostic information
              code:
                type: string
                description: Diagnostic Code
              message:
                type: string
                description: Diagnostic Message
              module:
                type: string
                description: Module reporting diagnostic information
              recordCount:
                type: integer
                description: Record Count for diagnostics
              query:
                type: string
                description: CQL Query associated with results
    parameter:
      description: List of key/value parameters of an error
      type: object
      properties:
        key:
          description: Parameter key
          type: string
        value:
          description: Parameter value
          type: string
      example:
        key: source
        value: 'null'
    errorResponse:
      description: A set of errors
      type: object
      properties:
        errors:
          description: List of errors
          type: array
          items:
            $ref: '#/components/schemas/error'
        total_records:
          description: Total number of errors
          type: integer
      example:
        errors:
        - message: Illegal argument error
          type: IllegalArgumentException
          code: unknown_error
        total_records: 1
    tags:
      title: tags
      description: List of simple tags that can be added to an object
      type: object
      properties:
        tagList:
          description: List of tags
          type: array
          items:
            type: string
    userCollection:
      $schema: http://json-schema.org/draft-04/schema#
      type: object
      description: Collection of users
      properties:
        users:
          description: List of users
          type: array
          id: userCollection
          items:
            type: object
            $ref: '#/components/schemas/user'
        totalRecords:
          type: integer
        resultInfo:
          $ref: '#/components/schemas/resultInfo'
          readonly: true
      required:
      - users
      - totalRecords
    user:
      $schema: http://json-schema.org/draft-04/schema#
      title: User Schema
      description: A user
      javaName: User
      type: object
      properties:
        username:
          description: A unique name belonging to a user. Typically used for login
          type: string
        id:
          $ref: '#/components/schemas/uuid'
        externalSystemId:
          description: A unique ID that corresponds to an external authority
          type: string
        barcode:
          description: The unique library barcode for this user
          type: string
        active:
          description: A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block
          type: boolean
        type:
          description: The class of user like staff or patron; this is different from patronGroup; it can store shadow, system user and dcb types also
          type: string
        patronGroup:
          description: UUID of patron group
          $ref: '#/components/schemas/uuid'
        departments:
          description: A list of UUIDs corresponding to the departments the user belongs to, see /departments API
          type: array
          uniqueItems: true
          items:
            type: string
            $ref: '#/components/schemas/uuid'
        meta:
          description: Deprecated
          type: object
        proxyFor:
          description: Deprecated
          type: array
          items:
            type: string
        personal:
          description: Personal information about the user
          type: object
          properties:
            lastName:
              description: The user's surname
              type: string
            firstName:
              description: The user's given name
              type: string
            middleName:
              description: The user's middle name (if any)
              type: string
            preferredFirstName:
              description: The user's preferred name
              type: string
            email:
              description: The user's email address
              type: string
            phone:
              description: The user's primary phone number
              type: string
            mobilePhone:
              description: The user's mobile phone number
              type: string
            dateOfBirth:
              type: string
              description: The user's birth date
              format: date-time
            addresses:
              description: Physical addresses associated with the user
              type: array
              minItems: 0
              items:
                type: object
                properties:
                  id:
                    description: A unique id for this address
                    type: string
                  countryId:
                    description: The country code for this address
                    type: string
                  addressLine1:
                    description: Address, Line 1
                    type: string
                  addressLine2:
                    description: Address, Line 2
                    type: string
                  city:
                    description: City name
                    type: string
                  region:
                    description: Region
                    type: string
                  postalCode:
                    description: Postal Code
                    type: string
                  addressTypeId:
                    description: UUID of address type
                    $ref: '#/components/schemas/uuid'
                  primaryAddress:
                    description: Is this the user's primary address?
                    type: boolean
                required:
                - addressTypeId
                additionalProperties: true
            preferredContactTypeId:
              description: Id of user's preferred contact type like Email, Mail or Text Message, see /addresstypes API
              type: string
            profilePictureLink:
              description: Link to the profile picture
              type: string
              format: uri
          additionalProperties: true
          required:
          - lastName
        enrollmentDate:
          description: The date in which the user joined the organization
          type: string
          format: date-time
        expirationDate:
          description: The date for when the user becomes inactive
          type: string
          format: date-time
        createdDate:
          description: Deprecated
          type: string
          format: date-time
        updatedDate:
          description: Deprecated
          type: string
          format: date-time
        metadata:
          type: object
          $ref: '#/components/schemas/metadata'
        tags:
          type: object
          $ref: '#/components/schemas/tags'
        customFields:
          description: Object that contains custom field
          type: object
          additionalProperties: true
        preferredEmailCommunication:
          type: array
          items:
            type: string
            enum:
            - Support
            - Programs
            - Services
          maxItems: 3
          uniqueItems: true
          description: Preferred email communication types
      additionalProperties: true
    uuid:
      $schema: http://json-schema.org/draft-04/schema#
      description: A universally unique identifier (UUID), this is a 128-bit number used to identify a record and is shown in hex with dashes, for example 6312d172-f0cf-40f6-b27d-9fa8feaf332f; the UUID version must be from 1-5; see https://dev.folio.org/guides/uuids/
      type: string
      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}$
    error:
      description: An error
      type: object
      properties:
        message:
          type: string
          description: Error message text
        type:
          type: string
          description: Error message type
        code:
          type: string
          description: Error message code
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/parameter'
    metadata:
      type: object
      description: Record metadata
      properties:
        createdDate:
          description: Date and time when the record was created
          type: string
        createdByUserId:
          description: ID of the user who created the record (when available)
          type: string
        createdByUsername:
          description: Username of the user who created the record (when available)
          type: string
        updatedDate:
          description: Date and time when the record was last updated
          type: string
        updatedByUserId:
          description: ID of the user who last updated the record (when available)
          type: string
        updatedByUsername:
          description: Username of the user who last updated the record (when available)
          type: string
  examples:
    validationErrorResponse:
      value:
        errors:
        - message: must not be null
          type: MethodArgumentNotValidException
          code: validation_error
          parameters:
          - key: parameter
            value: 'null'
        total_records: 1
    unknownError:
      value:
        errors:
        - message: Illegal argument error
          type: IllegalArgumentException
          code: unknown_error
        total_records: 1
  responses:
    internalServerErrorResponse:
      description: When unhandled exception occurred during code execution, e.g. NullPointerException.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            unknownError:
              $ref: '#/components/examples/unknownError'
    notFoundResponse:
      description: Not found
      content:
        application/json:
          example:
            errors:
            - message: Not found
            total_records: 1
          schema:
            $ref: '#/components/schemas/errorResponse'
    unprocessableEntityResponse:
      description: Validation error for the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            response:
              $ref: '#/components/examples/validationErrorResponse'
  parameters:
    externalUserId:
      name: externalUserId
      in: path
      required: true
      schema:
        type: string
    tenantId:
      name: tenantId
      in: path
      required: true
      schema:
        type: string
x-refined-from:
- folio-mod-circulation-bff-circulationbff-openapi.json
- folio-mod-circulation-bff-circulationbff-openapi.yml