openapi: 3.0.0
info:
    version: "v1.1.1"
    title: Phone Numbers - Vonage
    description: >-
      The Numbers API lets you manage your numbers and buy new virtual numbers for use with Vonage's APIs.

      ## Prerequirement:
      
      Your project has to be in the production environment in order to use of this API.

      For any questions, please contact our support team.
      
      ## [Source view](https://app.swaggerhub.com/apis/kpn/phone-numbers-nexmo/)<br/>
      [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/phone-numbers-nexmo/)
      
      ---
      
      ## [KPN Developer](https://developer.kpn.com/)<br/>
      [Getting Started](https://developer.kpn.com/getting-started)
      

         ---
    contact:
      name: API Support
      email: api_developer@kpn.com
      url: 'https://developer.kpn.com/support'
    termsOfService: 'https://developer.kpn.com/legal'
servers:
  - 
    url: https://api-prd.kpn.com/communication/nexmo/phone-numbers
    # description: 
externalDocs:
  description: HTTP response headers
  url: https://developer.kpn.com/documentation-response-headers
tags:
  - name: account
    description: number management from accounts
  - name: number
    description: numbers operations
paths:
  "/account/numbers":
    parameters:
      - $ref: '#/components/parameters/index_query_param'
      - $ref: '#/components/parameters/size_query_param'
      - $ref: '#/components/parameters/pattern_query_param'
      - $ref: '#/components/parameters/search_pattern_query_param'
    get:
      security:
        - oauth2: []
      summary: List owned numbers
      description: Retrieve all the inbound numbers associated with your Vonage account.
      tags: [account]
      operationId: getNumbers
      responses:
        '200':
          $ref: '#/components/responses/number_list'
  "/number/search":
    parameters:
      - $ref: '#/components/parameters/country_query_param'
      - $ref: '#/components/parameters/pattern_query_param'
      - $ref: '#/components/parameters/search_pattern_query_param'
      - $ref: '#/components/parameters/number_type_query_param'
      - $ref: '#/components/parameters/features_query_param'
      - $ref: '#/components/parameters/size_query_param'
      - $ref: '#/components/parameters/index_query_param'
    get:
      security:
        - oauth2: []
      summary: Search available numbers
      description: Retrieve inbound numbers that are available for a given country.
      tags: [number]
      operationId: searchNumbers
      responses:
        '200':
          $ref: '#/components/responses/number_list'
  "/number/buy":
    post:
      security:
        - oauth2: []
      summary: Buy a number
      description: Request to purchase a specific inbound number.
      tags: [number]
      operationId: buyNumber
      requestBody:
        $ref: '#/components/requestBodies/buy_cancel_number_request'
      responses:
        '200':
          $ref: '#/components/responses/ok_answer'
  "/number/cancel":
    post:
      security:
        - oauth2: []
      summary: Cancel a number
      description: Cancel your subscription for a specific inbound number.
      tags: [number]
      operationId: cancelNumber
      requestBody:
        $ref: '#/components/requestBodies/buy_cancel_number_request'
      responses:
        '200':
          $ref: '#/components/responses/ok_answer'
  "/number/update":
    post:
      security:
        - oauth2: []
      summary: Update a number
      description: Change the behaviour of a number that you own
      tags: [number]
      operationId: updateNumber
      requestBody:
        $ref: '#/components/requestBodies/update_number'
      responses:
        '200':
          $ref: '#/components/responses/ok_answer'

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
          scopes: {}
  schemas:
    number:
      type: object
      properties:
        country:
          $ref: '#/components/schemas/country_field'
        msisdn:
          $ref: '#/components/schemas/msisdn_field'
        moHttpUrl:
          $ref: '#/components/schemas/moHttpUrl_field'
        type:
          type: string
          example: "mobile-lvn"
        features:
          $ref:  '#/components/schemas/feature_field'
        voiceCallbackType:
          $ref: '#/components/schemas/voiceCallbackType_field'
        voiceCallbackValue:
          $ref: '#/components/schemas/voiceCallbackValue_field'
      required:
        - country
        - msisdn
        - type
        - features
    buy_cancel_number:
      description: The JSON object to request or cancel a number
      type: object
      properties:
        country:
          $ref: '#/components/schemas/country_field'
        msisdn:
          $ref: '#/components/schemas/msisdn_field'
      required:
        - country
        - msisdn
    update_number:
      description: The JSON object to request an update of a phone number
      type: object
      properties:
        country: 
          $ref: '#/components/schemas/country_field'
        msisdn:
          $ref: '#/components/schemas/msisdn_field'
        moHttpUrl:
          $ref: '#/components/schemas/moHttpUrl_field'
        moSmppSysType:
          $ref: '#/components/schemas/moSmppSysType_field'
        voiceCallbackType:
          $ref: '#/components/schemas/voiceCallbackType_field'
        voiceCallbackValue:
          $ref: '#/components/schemas/voiceCallbackValue_field'
        voiceStatusCallback:
          $ref: '#/components/schemas/voiceStatusCallback_field'
      required:
        - country
        - msisdn
    moHttpUrl_field:
      type: string
      format: url
      example: "https://example.com/mo"
      description: >- 
        An URL encoded URI to the webhook endpoint that handles inbound messages. Your webhook endpoint must be active before you make this request, Vonage makes a `GET` request to your endpoint and checks that it returns a `200 OK` response. Set to empty string to clear.
    moSmppSysType_field:
      type: string
      description: The associated system type for your SMPP client. For example `inbound`.
      example: inbound
    voiceCallbackType_field:
      type: string
      example: "app"
      description: The voice webhook type. To be used together with `voiceCallbackValue`
      enum:
        - sip
        - tel
        - app
    voiceCallbackValue_field:
      type: string
      example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      description: A SIP URI, telephone number or Application ID. To be used together with `voiceCallbackType`
    voiceStatusCallback_field:
      description: A webhook URI for Vonage to send a request to when a call ends.
      type: string
      format: url
    country_field:
      type: string
      description: The two character country code in ISO 3166-1 alpha-2 format.
      example: "NL"
    msisdn_field:
      type: string
      format: number
      description: An available inbound virtual number.
      example: "31612345789"
    feature_field:
      type: array
      description: Available features are SMS and VOICE. For both features, use a comma-separated value SMS,VOICE.
      items:
        type: string
        enum:
          - VOICE
          - SMS
      example:
        - VOICE
        - SMS
  responses:
    number_list:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
                description: The total amount of numbers that satisfies the requirements.
              numbers:
                type: array
                description: A paginated array of available numbers and their details.
                items:
                  $ref: '#/components/schemas/number'
    ok_answer:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              error-code:
                type: string
                format: integer
              error-code-label:
                type: string
            example:
              - error-code: "200"
                error-code-label: "success"
  parameters:
    index_query_param:
      name: index
      in: query
      schema:
        type: integer
        example: 0
        default: 1
      description: Page index
    size_query_param:
      name: size
      in: query
      schema:
        type: integer
        default: 10
        maximum: 100
      description: Page size
    pattern_query_param:
      name: pattern
      in: query
      schema:
        type: string
      description: A number pattern to search for.
    search_pattern_query_param:
      name: search_pattern
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 2
      description: >-
        Strategy for matching pattern. Expected values: 0 (starts with, default), 1 (anywhere), 2 (ends with).
    country_query_param:
      name: country
      in: query
      required: true
      schema:
        type: string
    number_type_query_param:
      name: type
      in: query
      description: The type of number to search for. By default it takes landline.
      schema:
        type: string
        enum:
          - landline
          - landline-toll-free
          - mobile-lvn
    features_query_param:
      name: features
      in: query
      schema:
        type: array
        items:
          $ref: '#/components/schemas/feature_field'
  requestBodies:
    buy_cancel_number_request:
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: '#/components/schemas/buy_cancel_number'
          example:
            -
              country: NL
              msisdn: "31612345789"
    update_number:
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: '#/components/schemas/update_number'