---
openapi: 3.0.0
info:
  version: 1.11.8
  title: User API
  description: |
    The Vonage Business Cloud User API enables you to retrieve information about users.

    Your application must subscribe to the Provisioning API suite to use this API.
  contact:
    name: "Vonage Business Cloud Support"
    url: "https://businesssupport.vonage.com/contactus"
  termsOfService: "https://www.vonage.com/business/legal-policy-center/business-cloud/tos"

servers:
  - url: "https://api.vonage.com/t/vbc.prod/provisioning"
paths:
  "/api/accounts/{account_id}/users":
    get:
      operationId: UserCtrl.getUsers
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - in: query
          name: page_size
          required: false
          schema:
            type: number
          description: Number of records per page
          example: 10
        - in: query
          name: page
          required: false
          schema:
            type: number
          description: Current page number
          example: 10
        - in: query
          name: first_name
          required: false
          schema:
            type: string
          description: Filter by first name
          example: "John"
        - in: query
          name: last_name
          required: false
          schema:
            type: string
          description: Filter by last name
          example: "Smith"
        - in: query
          name: login_name
          required: false
          schema:
            type: string
          description: Filter by login name
          example: "jsmith"
        - in: query
          name: email
          required: false
          schema:
            type: string
          description: Filter by email address
          example: "john.smith@example.com"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsersHalResponse"
        "400":
          description: Invalid parameters given
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationErrorsResponse"
      security:
        - bearerAuth: []
      summary: Get account users data by account ID

  "/api/accounts/{account_id}/users/{user_id}":
    get:
      operationId: UserCtrl.getUserByID
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - in: path
          name: user_id
          required: true
          schema:
            type: number
          description: The Vonage Business Cloud user ID
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserHalResponse"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      security:
        - bearerAuth: []
      summary: Get user data by account ID and user ID
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth

  parameters:
    AccountID:
      in: path
      name: account_id
      required: true
      schema:
        type: string
      description: The Vonage Business Cloud account ID
      example: 451496

  schemas:
    FirstHref:
      type: object
      properties:
        href:
          type: string
      description: URL to the first page of records
    PrevHref:
      type: object
      properties:
        href:
          type: string
      description: URL to the previous page of records
    SelfHref:
      type: object
      properties:
        href:
          type: string
      description: URL to the current page of records
    NextHref:
      type: object
      properties:
        href:
          type: string
      description: URL to the next page of records
    LastHref:
      type: object
      properties:
        href:
          type: string
      description: URL to the last page of records

    Links:
      type: object
      properties:
        first:
          $ref: "#/components/schemas/FirstHref"
        prev:
          $ref: "#/components/schemas/PrevHref"
        self:
          $ref: "#/components/schemas/SelfHref"
        next:
          $ref: "#/components/schemas/NextHref"

    Contact:
      type: object
      properties:
        type:
          type: string
          description: Contact type
          example: "Home"
        value:
          type: string
          description: Contact value
          example: "14155550100"

    UserExtension:
      type: object
      properties:
        dids:
          items:
            $ref: "#/components/schemas/DID"
          type: array
          description: Collection of phone numbers assigned to the extension
        extension_number:
          type: string
          description: Extension number
          example: "789"

    User:
      type: object
      properties:
        email:
          type: string
          description: Email address of the user
          example: "john.smith@example.com"
        login_name:
          type: string
          description: Login name of the user
          example: "jsmith"
        first_name:
          type: string
          description: First name of the user
          example: "John"
        last_name:
          type: string
          description: Last name of the user
          example: "Smith"
        id:
          type: number
          description: Unique identifier of the user
          example: 869048
        contact_numbers:
          items:
            $ref: "#/components/schemas/Contact"
          type: array
          description: Collection of contact objects
        extensions:
          items:
            $ref: "#/components/schemas/UserExtension"
          type: array
          description: Collection of extension objects

    UsersEmbeddedObject:
      type: object
      properties:
        data:
          items:
            $ref: "#/components/schemas/User"
          type: array

    UserEmbeddedObject:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/User"

    UserHalResponse:
      type: object
      properties:
        page_size:
          type: number
          example: 10
          description: Number of records per page
        page:
          type: number
          example: 1
          description: Current page number
        total_pages:
          type: number
          example: 10
          description: Total number of pages
        total_items:
          type: number
          example: 100
          description: Total number of records
        _links:
          $ref: "#/components/schemas/Links"
        _embedded:
          $ref: "#/components/schemas/UserEmbeddedObject"

    UsersHalResponse:
      type: object
      properties:
        page_size:
          type: number
          example: 10
          description: Number of records per page
        page:
          type: number
          example: 1
          description: Current page number
        total_pages:
          type: number
          example: 10
          description: Total number of pages
        total_items:
          type: number
          example: 100
          description: Total number of records
        _links:
          $ref: "#/components/schemas/Links"
        _embedded:
          $ref: "#/components/schemas/UsersEmbeddedObject"

    DID:
      type: object
      properties:
        phone_number:
          type: string
          description: Phone number
          example: "14155550100"
        custom_tag:
          type: string
          description: Custom tag associated with the phone number
          example: My Tag

    ErrorResponse:
      type: object
      properties:
        msg:
          description: Error message
          type: string
        status:
          description: Http Response Code
          type: number

    ValidationErrorsResponse:
      type: object
      properties:
        status:
          description: Error status code
          type: number
        title:
          description: Error title
          type: string
        instance:
          description: Error Track ID
          type: string
        invalid_parameters:
          items:
            $ref: "#/components/schemas/DetailedInvalidParam"
          description: Invalid parameters and their reason for failing
          type: array

    DetailedInvalidParam:
      type: object
      properties:
        name:
          type: string
          description: Invalid property name
        reason:
          type: string
          description: Invalid property reason
