Vonage Number API

openapi: 3.2.0
info:
  title: Vonage Number API
  version: 1.1.0
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.nexmo.com
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  x-apiClientRegistration: ${CUSTOMER_DASHBOARD_URL}/sign-up
  x-metaDescription: Find quick answers to questions about the Vonage Numbers API in this reference guide. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Numbers API Reference | Vonage API Documentation
  description: 'Operations tagged Number across 2 of this provider''s published API definitions: vonage-numbers-openapi.json, vonage-numbers-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://rest.nexmo.com
security:
- basicAuth: []
tags:
- name: Number
paths:
  /number/search:
    get:
      operationId: getAvailableNumbers
      summary: Search available numbers
      description: Retrieve inbound numbers that are available for the specified country.
      parameters:
      - $ref: '#/components/parameters/country'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/pattern'
      - $ref: '#/components/parameters/search_pattern'
      - name: features
        required: false
        in: query
        description: 'Available features are `SMS`, `VOICE` and `MMS`. To look for numbers that support multiple features, use a comma-separated value: `SMS,MMS,VOICE`.'
        schema:
          type: string
          enum:
          - SMS
          - VOICE
          - SMS,VOICE
          - MMS
          - SMS,MMS
          - VOICE,MMS
          - SMS,MMS,VOICE
        example: SMS
      - $ref: '#/components/parameters/size'
      - $ref: '#/components/parameters/index'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/available-numbers'
            text/xml:
              schema:
                $ref: '#/components/schemas/available-numbers'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/account-unauthorized'
            text/xml:
              schema:
                $ref: '#/components/schemas/account-unauthorized'
      tags:
      - Number
    servers:
    - url: https://rest.nexmo.com
  /number/buy:
    post:
      operationId: buyANumber
      summary: Buy a number
      description: Request to purchase a specific inbound number.
      requestBody:
        description: Number details
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/number-details'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
            text/xml:
              schema:
                $ref: '#/components/schemas/response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
            text/xml:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '420':
          description: Action failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response420'
            text/xml:
              schema:
                $ref: '#/components/schemas/response420'
      tags:
      - Number
    servers:
    - url: https://rest.nexmo.com
  /number/cancel:
    post:
      operationId: cancelANumber
      summary: Cancel a number
      description: Cancel your subscription for a specific inbound number.
      requestBody:
        description: Number details
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/number-details'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
            text/xml:
              schema:
                $ref: '#/components/schemas/response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
            text/xml:
              schema:
                $ref: '#/components/schemas/unauthorized'
      tags:
      - Number
    servers:
    - url: https://rest.nexmo.com
  /number/update:
    post:
      operationId: updateANumber
      summary: Update a number
      description: Change the behaviour of a number that you own.
      requestBody:
        description: Number details
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/number-details-update'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
            text/xml:
              schema:
                $ref: '#/components/schemas/response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
            text/xml:
              schema:
                $ref: '#/components/schemas/unauthorized'
      tags:
      - Number
    servers:
    - url: https://rest.nexmo.com
components:
  schemas:
    unauthorized:
      type: object
      xml:
        name: response
      properties:
        error-code:
          type: string
          example: '401'
          description: The status code of the response. `200` indicates a successful request.
        error-code-label:
          type: string
          example: authentication failed
          description: The status code description
    number-details-update:
      type: object
      properties:
        country:
          $ref: '#/components/schemas/country'
        msisdn:
          type: string
          example: '447700900000'
          description: An available inbound virtual number.
        app_id:
          type: string
          description: The Application that will handle inbound traffic to this number.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789abc
        moHttpUrl:
          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 the endpoint and checks that it returns a `200 OK` response. Set this parameter's value to an empty string to remove the webhook.
          type: string
          example: https://example.com/webhooks/inbound-sms
        moSmppSysType:
          description: The associated system type for your SMPP client
          type: string
          example: inbound
        voiceCallbackType:
          description: 'Specify whether inbound voice calls on your number are forwarded

            to a SIP or a telephone number.  This must be used with the

            `voiceCallbackValue` parameter. If set, `sip` or `tel` are

            prioritized over the Voice capability in your Application.


            *Note: The `app` value is deprecated and will be removed in future.*

            '
          type: string
          enum:
          - sip
          - tel
          - app
          example: tel
        voiceCallbackValue:
          description: A SIP URI or telephone number. Must be used with the `voiceCallbackType` parameter.
          type: string
          example: '447700900000'
        voiceStatusCallback:
          description: A webhook URI for Vonage to send a request to when a call ends
          type: string
          example: https://example.com/webhooks/status
        messagesCallbackType:
          description: '<strong>DEPRECATED</strong> - We recommend that you use `app_id` instead.


            Specifies the Messages webhook type (always `app`) associated with this

            number and must be used with the `messagesCallbackValue` parameter.

            '
          type: string
          enum:
          - app
          example: app
          deprecated: true
        messagesCallbackValue:
          description: '<strong>DEPRECATED</strong> - We recommend that you use `app_id` instead.


            Specifies the Application ID of your Messages application.

            It must be used with the `messagesCallbackType` parameter.

            '
          type: string
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          deprecated: true
      required:
      - country
      - msisdn
    account-unauthorized:
      type: object
      xml:
        name: inbound-numbers
      properties:
        error-code:
          type: string
          example: '401'
          description: The status code of the response. `200` indicates a successful request.
        error-code-label:
          type: string
          example: authentication failed
          description: The status code description
    response:
      type: object
      xml:
        name: response
      properties:
        error-code:
          type: string
          example: '200'
          description: The status code of the response. `200` indicates a successful request.
        error-code-label:
          type: string
          example: success
          description: The status code description
    response420:
      type: object
      xml:
        name: response
      properties:
        error-code:
          type: string
          example: '420'
          description: The status code of the response. `200` indicates a successful request.
        error-code-label:
          type: string
          example: Numbers from this country can be requested from the Dashboard (${CUSTOMER_DASHBOARD_URL}/buy-numbers) as they require a valid local address to be provided before being purchased.
          description: More detail about what happened. For example you may need to request the number via the dashboard, or you may already own this number.
    country:
      type: string
      minLength: 2
      maxLength: 2
      example: GB
      description: The two character country code in ISO 3166-1 alpha-2 format
    availablenumber:
      type: object
      properties:
        country:
          $ref: '#/components/schemas/country'
        msisdn:
          type: string
          example: '447700900000'
          description: An available inbound virtual number.
        type:
          type: string
          example: mobile-lvn
          description: 'The type of number: `landline`, `landline-toll-free` or `mobile-lvn`'
        initialPrice:
          type: string
          example: '1.25'
          description: The initial setup fee for this number, in Euros
        cost:
          type: string
          example: '1.25'
          description: The monthly rental cost for this number, in Euros
        features:
          type: array
          xml:
            wrapped: true
          items:
            xml:
              name: feature
            type: string
          example:
          - VOICE
          - SMS
          - MMS
          description: 'The capabilities of the number: `SMS` or `VOICE` or `SMS,VOICE` or `SMS,MMS` or `VOICE,MMS` or `SMS,MMS,VOICE`'
        limitations:
          type: array
          xml:
            wrapped: true
          example:
          - feature: SMS
            type: OUTBOUND
            reach: INTERNATIONAL
          - feature: VOICE
            type: OUTBOUND
            reach: DOMESTIC
          items:
            $ref: '#/components/schemas/number-limitation'
    number-details:
      type: object
      properties:
        country:
          $ref: '#/components/schemas/country'
        msisdn:
          type: string
          example: '447700900000'
          description: An available inbound virtual number.
        target_api_key:
          type: string
          example: 1a2345b7
          description: If you’d like to perform an action on a subaccount, provide the `api_key` of that account here. If you’d like to perform an action on your own account, you do not need to provide this field.
      required:
      - country
      - msisdn
    number-limitation:
      type: object
      xml:
        name: limitation
      properties:
        feature:
          type: string
          xml:
            attribute: true
          enum:
          - MMS
          - SMS
          - VOICE
          example: SMS
        type:
          type: string
          xml:
            attribute: true
          enum:
          - INBOUND
          - OUTBOUND
          example: OUTBOUND
        reach:
          type: string
          xml:
            attribute: true
          enum:
          - DOMESTIC
          - INTERNATIONAL
          example: INTERNATIONAL
      required:
      - feature
      - type
      - reach
    available-numbers:
      type: object
      xml:
        name: inbound-numbers
      properties:
        count:
          type: integer
          description: The total amount of numbers available in the pool.
          example: 1234
        numbers:
          type: array
          description: A paginated array of available numbers and their details.
          items:
            $ref: '#/components/schemas/availablenumber'
  parameters:
    search_pattern:
      name: search_pattern
      required: false
      in: query
      description: 'The strategy you want to use for matching:



        * `0` - Search for numbers that start with `pattern` (Note: all numbers are in E.164 format, so the starting pattern includes the country code, such as 1 for USA)

        * `1` - Search for numbers that contain `pattern`

        * `2` - Search for numbers that end with `pattern`

        '
      schema:
        type: integer
        default: 0
        enum:
        - 0
        - 1
        - 2
      example: 1
    type:
      name: type
      in: query
      required: false
      description: Set this parameter to filter the type of number, such as mobile or landline
      schema:
        type: string
        enum:
        - landline
        - mobile-lvn
        - landline-toll-free
      example: mobile-lvn
    index:
      name: index
      required: false
      in: query
      description: Page index
      schema:
        type: integer
        default: 1
      example: 1
    pattern:
      name: pattern
      required: false
      in: query
      description: The number pattern you want to search for. Use in conjunction with `search_pattern`.
      schema:
        type: string
      example: '12345'
    size:
      name: size
      required: false
      in: query
      description: Page size
      schema:
        type: integer
        maximum: 100
        default: 10
      example: 10
    country:
      name: country
      in: query
      required: true
      description: The two character country code to filter on (in ISO 3166-1 alpha-2 format)
      schema:
        $ref: '#/components/schemas/country'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  description: Numbers product documentation on the Vonage Developer Portal
  url: https://developer.nexmo.com/numbers/overview
x-refined-from:
- vonage-numbers-openapi.json
- vonage-numbers-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one