openapi: 3.0.0
servers:
  - url: https://api.vonage.com/t/vbc.prod/provisioning
info:
  contact:
    name: Vonage Business Cloud Support
    url: https://businesssupport.vonage.com/contactus
  description: >
    The Vonage Business Cloud Extension API enables you to retrieve information about extensions.


    Your application must subscribe to the Provisioning API suite to use this API.
  termsOfService: https://www.vonage.com/business/legal-policy-center/business-cloud/tos
  title: Extension API
  version: 1.11.8
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/vonage-business-cloud/extension.yml
      version: "3.0"
  x-providerName: vonage.com
  x-serviceName: extension
paths:
  "/api/accounts/{account_id}/extensions":
    get:
      operationId: ExtensionCtrl.getAccountExtensions
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - description: Number of records per page
          example: 10
          in: query
          name: page_size
          required: false
          schema:
            type: number
        - description: Current page number
          example: 10
          in: query
          name: page
          required: false
          schema:
            type: number
        - description: Filter by location id
          example: 145214
          in: query
          name: location_id
          required: false
          schema:
            type: number
        - description: Filter by phone number
          example: "14155550100"
          in: query
          name: phone_number
          required: false
          schema:
            type: string
        - description: Filter by login name
          example: jsmith
          in: query
          name: login_name
          required: false
          schema:
            type: string
        - description: Filter by email address
          example: john.smith@example.com
          in: query
          name: email
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EndUserRouteHalResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationErrorsResponse"
          description: Invalid parameters given
      security:
        - bearerAuth: []
      summary: Get account extensions data by account ID
  "/api/accounts/{account_id}/extensions/{extension_number}":
    get:
      operationId: ExtensionCtrl.getAccountExtensionByID
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - description: The extension number
          example: 789
          in: path
          name: extension_number
          required: true
          schema:
            type: number
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EndUserRouteHalResponse"
          description: Success
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Extension not found
      security:
        - bearerAuth: []
      summary: Get extension data by account ID and extension number
components:
  parameters:
    AccountID:
      description: The Vonage Business Cloud account ID
      in: path
      name: account_id
      required: true
      schema:
        type: string
  schemas:
    BasicUser:
      properties:
        email:
          description: Email address of the user
          example: john.smith@example.com
          type: string
        first_name:
          description: First name of the user
          example: John
          type: string
        last_name:
          description: Last name of the user
          example: Smith
          type: string
        login_name:
          description: Login name of the user
          example: jsmith
          type: string
      type: object
    DID:
      properties:
        custom_tag:
          description: Custom tag associated with the phone number
          example: My Tag
          type: string
        phone_number:
          description: Phone number
          example: "14155550100"
          type: string
      type: object
    DetailedInvalidParam:
      properties:
        name:
          description: Invalid property name
          type: string
        reason:
          description: Invalid property reason
          type: string
      type: object
    EndUserRoute:
      properties:
        block_caller_id:
          description: Block Caller ID status of the extension
          example: false
          type: boolean
        caller_id:
          description: Caller ID of the extension
          example: John Smith
          type: string
        dids:
          description: Collection of phone numbers assigned to the extension
          items:
            $ref: "#/components/schemas/DID"
          type: array
        dnd_enabled:
          description: Do Not Disturb status of the extension
          example: false
          type: boolean
        extension_handsets:
          description: Collection of handsets assigned to the extension
          items:
            $ref: "#/components/schemas/Line"
          type: array
        extension_number:
          description: Extension number
          example: "789"
          type: string
        location_id:
          description: Unique identifier of the assigned location
          example: 145214
          type: number
        user:
          $ref: "#/components/schemas/BasicUser"
        vtt_enabled:
          description: Voicemail transcription status of the location
          example: true
          type: boolean
      type: object
    EndUserRouteEmbeddedObject:
      properties:
        data:
          $ref: "#/components/schemas/EndUserRoute"
      type: object
    EndUserRouteHalResponse:
      properties:
        _embedded:
          $ref: "#/components/schemas/EndUserRouteEmbeddedObject"
        _links:
          $ref: "#/components/schemas/Links"
        page:
          description: Current page number
          example: 1
          type: number
        page_size:
          description: Number of records per page
          example: 10
          type: number
        total_items:
          description: Total number of records
          example: 100
          type: number
        total_pages:
          description: Total number of pages
          example: 10
          type: number
      type: object
    ErrorResponse:
      properties:
        msg:
          description: Error message
          type: string
        status:
          description: Http Response Code
          type: number
      type: object
    FirstHref:
      description: URL to the first page of records
      properties:
        href:
          type: string
      type: object
    LastHref:
      description: URL to the last page of records
      properties:
        href:
          type: string
      type: object
    Line:
      properties:
        handset_name:
          description: Name of the handset
          example: line1-VH6370927
          type: string
        sip_id:
          description: SIP identifier of the handset
          example: VH16370927
          type: string
      type: object
    Links:
      properties:
        first:
          $ref: "#/components/schemas/FirstHref"
        next:
          $ref: "#/components/schemas/NextHref"
        prev:
          $ref: "#/components/schemas/PrevHref"
        self:
          $ref: "#/components/schemas/SelfHref"
      type: object
    NextHref:
      description: URL to the next page of records
      properties:
        href:
          type: string
      type: object
    PrevHref:
      description: URL to the previous page of records
      properties:
        href:
          type: string
      type: object
    SelfHref:
      description: URL to the current page of records
      properties:
        href:
          type: string
      type: object
    ValidationErrorsResponse:
      properties:
        instance:
          description: Error Track ID
          type: string
        invalid_parameters:
          description: Invalid parameters and their reason for failing
          items:
            $ref: "#/components/schemas/DetailedInvalidParam"
          type: array
        status:
          description: Error status code
          type: number
        title:
          description: Error title
          type: string
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: OAuth
      scheme: bearer
      type: http
