openapi: 3.0.0
servers:
  - url: https://rest.nexmo.com
info:
  contact:
    email: devrel@vonage.com
    name: Vonage DevRel
    url: https://developer.nexmo.com
  description: "The Numbers API enables you to manage your existing numbers and buy new virtual numbers for use with the Vonage APIs. Further information is here: <https://developer.nexmo.com/numbers/overview>"
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  title: Numbers API
  version: 1.0.20
  x-apiClientRegistration: https://dashboard.nexmo.com/sign-up
  x-logo:
    url: https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/numbers.yml
      version: "3.0"
  x-providerName: nexmo.com
  x-serviceName: numbers
externalDocs:
  description: Numbers product documentation on the Vonage Developer Portal
  url: https://developer.nexmo.com/numbers/overview
security:
  - apiKey: []
    apiSecret: []
paths:
  /account/numbers:
    get:
      description: Retrieve all the inbound numbers associated with your Vonage account.
      operationId: getOwnedNumbers
      parameters:
        - $ref: "#/components/parameters/application_id"
        - $ref: "#/components/parameters/has_application"
        - in: query
          name: country
          required: false
          schema:
            $ref: "#/components/schemas/country"
        - $ref: "#/components/parameters/pattern"
        - $ref: "#/components/parameters/search_pattern"
        - $ref: "#/components/parameters/size"
        - $ref: "#/components/parameters/index"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inbound-numbers"
            text/xml:
              schema:
                $ref: "#/components/schemas/inbound-numbers"
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/account-unauthorized"
            text/xml:
              schema:
                $ref: "#/components/schemas/account-unauthorized"
          description: Unauthorized
      summary: List the numbers you own
  /number/buy:
    post:
      description: Request to purchase a specific inbound number.
      operationId: buyANumber
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/number-details"
        description: Number details
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/response"
            text/xml:
              schema:
                $ref: "#/components/schemas/response"
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unauthorized"
            text/xml:
              schema:
                $ref: "#/components/schemas/unauthorized"
          description: Unauthorized
        "420":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/response420"
            text/xml:
              schema:
                $ref: "#/components/schemas/response420"
          description: Action failed
      summary: Buy a number
  /number/cancel:
    post:
      description: Cancel your subscription for a specific inbound number.
      operationId: cancelANumber
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/number-details"
        description: Number details
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/response"
            text/xml:
              schema:
                $ref: "#/components/schemas/response"
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unauthorized"
            text/xml:
              schema:
                $ref: "#/components/schemas/unauthorized"
          description: Unauthorized
      summary: Cancel a number
  /number/search:
    get:
      description: Retrieve inbound numbers that are available for the specified country.
      operationId: getAvailableNumbers
      parameters:
        - $ref: "#/components/parameters/country"
        - $ref: "#/components/parameters/type"
        - $ref: "#/components/parameters/pattern"
        - $ref: "#/components/parameters/search_pattern"
        - description: "Available features are `SMS`, `VOICE` and `MMS`. To look for numbers that support multiple features, use a comma-separated value: `SMS,MMS,VOICE`."
          example: SMS
          in: query
          name: features
          required: false
          schema:
            enum:
              - SMS
              - VOICE
              - SMS,VOICE
              - MMS
              - SMS,MMS
              - VOICE,MMS
              - SMS,MMS,VOICE
            type: string
        - $ref: "#/components/parameters/size"
        - $ref: "#/components/parameters/index"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/available-numbers"
            text/xml:
              schema:
                $ref: "#/components/schemas/available-numbers"
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/account-unauthorized"
            text/xml:
              schema:
                $ref: "#/components/schemas/account-unauthorized"
          description: Unauthorized
      summary: Search available numbers
  /number/update:
    post:
      description: Change the behaviour of a number that you own.
      operationId: updateANumber
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/number-details-update"
        description: Number details
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/response"
            text/xml:
              schema:
                $ref: "#/components/schemas/response"
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unauthorized"
            text/xml:
              schema:
                $ref: "#/components/schemas/unauthorized"
          description: Unauthorized
      summary: Update a number
components:
  parameters:
    application_id:
      description: The Application that you want to return the numbers for.
      example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      in: query
      name: application_id
      required: false
      schema:
        type: string
    country:
      description: The two character country code to filter on (in ISO 3166-1 alpha-2 format)
      in: query
      name: country
      required: true
      schema:
        $ref: "#/components/schemas/country"
    has_application:
      description: |
        Set this optional field to `true` to restrict your results to numbers
        associated with an Application (any Application). Set to `false` to
        find all numbers not associated with any Application. Omit the field
        to avoid filtering on whether or not the number is assigned to an
        Application.
      example: false
      in: query
      name: has_application
      required: false
      schema:
        type: boolean
    index:
      description: Page index
      example: 1
      in: query
      name: index
      required: false
      schema:
        default: 1
        type: integer
    msisdn:
      description: The inbound number you want to cancel, in [E.164 international format](/concepts/guides/glossary#e-164-format)
      example: "447700900000"
      in: query
      name: msisdn
      required: true
      schema:
        type: string
    pattern:
      description: The number pattern you want to search for. Use in conjunction with `search_pattern`.
      example: "12345"
      in: query
      name: pattern
      required: false
      schema:
        type: string
    search_pattern:
      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`
      example: 1
      in: query
      name: search_pattern
      required: false
      schema:
        default: 0
        enum:
          - 0
          - 1
          - 2
        type: integer
    size:
      description: Page size
      example: 10
      in: query
      name: size
      required: false
      schema:
        default: 10
        maximum: 100
        type: integer
    type:
      description: Set this parameter to filter the type of number, such as mobile or landline
      example: mobile-lvn
      in: query
      name: type
      required: false
      schema:
        enum:
          - landline
          - mobile-lvn
          - landline-toll-free
        type: string
  schemas:
    account-unauthorized:
      properties:
        error-code:
          description: The status code of the response. `200` indicates a successful request.
          example: "401"
          type: string
        error-code-label:
          description: The status code description
          example: authentication failed
          type: string
      type: object
      xml:
        name: inbound-numbers
    available-numbers:
      properties:
        count:
          description: The total amount of numbers available in the pool.
          example: 1234
          type: integer
        numbers:
          description: A paginated array of available numbers and their details.
          items:
            $ref: "#/components/schemas/availablenumber"
          type: array
      type: object
      xml:
        name: inbound-numbers
    availablenumber:
      properties:
        cost:
          description: The monthly rental cost for this number, in Euros
          example: "1.25"
          type: string
        country:
          $ref: "#/components/schemas/country"
        features:
          description: "The capabilities of the number: `SMS` or `VOICE` or `SMS,VOICE` or `SMS,MMS` or `VOICE,MMS` or `SMS,MMS,VOICE`"
          example:
            - VOICE
            - SMS
            - MMS
          items:
            type: string
          type: array
        msisdn:
          description: An available inbound virtual number.
          example: "447700900000"
          type: string
        type:
          description: "The type of number: `landline`, `landline-toll-free` or `mobile-lvn`"
          example: mobile-lvn
          type: string
      type: object
    country:
      description: The two character country code in ISO 3166-1 alpha-2 format
      example: GB
      maxLength: 2
      minLength: 2
      type: string
    inbound-numbers:
      properties:
        count:
          description: The total amount of numbers owned by the account
          example: 1
          type: integer
        numbers:
          description: A paginated array of numbers and their details
          items:
            $ref: "#/components/schemas/ownednumber"
          type: array
      type: object
      xml:
        name: inbound-numbers
    number-details:
      properties:
        country:
          $ref: "#/components/schemas/country"
        msisdn:
          description: An available inbound virtual number.
          example: "447700900000"
          type: string
        target_api_key:
          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.
          example: 1a2345b7
          type: string
      required:
        - country
        - msisdn
      type: object
    number-details-update:
      properties:
        app_id:
          description: The Application that will handle inbound traffic to this number.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789abc
          type: string
        country:
          $ref: "#/components/schemas/country"
        messagesCallbackType:
          deprecated: true
          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.
          enum:
            - app
          example: app
          type: string
        messagesCallbackValue:
          deprecated: true
          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.
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          type: string
        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.
          example: https://example.com/webhooks/inbound-sms
          type: string
        moSmppSysType:
          description: The associated system type for your SMPP client
          example: inbound
          type: string
        msisdn:
          description: An available inbound virtual number.
          example: "447700900000"
          type: string
        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.*
          enum:
            - sip
            - tel
            - app
          example: tel
          type: string
        voiceCallbackValue:
          description: A SIP URI or telephone number. Must be used with the `voiceCallbackType` parameter.
          example: "447700900000"
          type: string
        voiceStatusCallback:
          description: A webhook URI for Vonage to send a request to when a call ends
          example: https://example.com/webhooks/status
          type: string
      required:
        - country
        - msisdn
      type: object
    ownednumber:
      properties:
        country:
          $ref: "#/components/schemas/country"
        features:
          description: "The capabilities of the number: `SMS` or `VOICE` or `SMS,VOICE` or `SMS,MMS` or `VOICE,MMS` or `SMS,MMS,VOICE`"
          example:
            - VOICE
            - SMS
            - MMS
          items:
            type: string
          type: array
        messagesCallbackType:
          description: "The messages webhook type: always `app`"
          example: app
          type: string
        messagesCallbackValue:
          description: An Application ID
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          type: string
        moHttpUrl:
          description: The URL of the webhook endpoint that handles inbound messages
          example: https://example.com/webhooks/inbound-sms
          format: url
          type: string
        msisdn:
          description: An available inbound virtual number.
          example: "447700900000"
          type: string
        type:
          description: "The type of number: `landline`, `landline-toll-free` or `mobile-lvn`"
          example: mobile-lvn
          type: string
        voiceCallbackType:
          description: "The voice webhook type: `sip`, `tel`, or `app`"
          example: app
          type: string
        voiceCallbackValue:
          description: A SIP URI, telephone number or Application ID
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          type: string
      type: object
    response:
      properties:
        error-code:
          description: The status code of the response. `200` indicates a successful request.
          example: "200"
          type: string
        error-code-label:
          description: The status code description
          example: success
          type: string
      type: object
      xml:
        name: response
    response420:
      properties:
        error-code:
          description: The status code of the response. `200` indicates a successful request.
          example: "420"
          type: string
        error-code-label:
          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.
          example: Numbers from this country can be requested from the Dashboard (https://dashboard.nexmo.com/buy-numbers) as they require a valid local address to be provided before being purchased.
          type: string
      type: object
      xml:
        name: response
    unauthorized:
      properties:
        error-code:
          description: The status code of the response. `200` indicates a successful request.
          example: "401"
          type: string
        error-code-label:
          description: The status code description
          example: authentication failed
          type: string
      type: object
      xml:
        name: response
  securitySchemes:
    apiKey:
      description: You can find your API key in the [developer dashboard](https://dashboard.nexmo.com)
      in: query
      name: api_key
      type: apiKey
    apiSecret:
      description: You can find your API secret in the [developer dashboard](https://dashboard.nexmo.com)
      in: query
      name: api_secret
      type: apiKey
