---
openapi: "3.0.0"
info:
  version: 2.0.5
  title: "Application API"
  description: |
    Nexmo provides an Application API to allow management of your Nexmo Applications.

    This API is backwards compatible with version 1. Applications created using version 1 of the API can also be managed using version 2 (this version) of the API.
  contact:
    name: Nexmo
    url: 'https://developer.nexmo.com/'
    email: devrel@nexmo.com
servers:
  - url: https://api.nexmo.com/v2/applications
security:
  - basicAuth: []
paths:
  /:
    post:
      summary: Create an application
      operationId: createApplication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - name
              properties:
                name:
                  description: "Application Name"
                  example: "Demo Application"
                  type: "string"
                keys:
                  type: object
                  properties:
                    public_key:
                      type: string
                      example: |
                          -----BEGIN PUBLIC KEY-----
                          MIIBIjANBgkqhkiG9w0BAQEFAAOCA
                          KOxjsU4pf/sMFi9N0jqcSLcjxu33G
                          d/vynKnlw9SENi+UZR44GdjGdmfm1
                          tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
                          0kYWekeIZawIwe/g9faFgkev+1xsO
                          OUNhPx2LhuLmgwWSRS4L5W851Xe3f
                          UQIDAQAB
                          -----END PUBLIC KEY-----
                      description: Public key
                capabilities:
                  type: object
                  description: "Your application can use multiple products. This contains the configuration for each product. This replaces the application `type` from version 1 of the Application API."
                  x-nexmo-developer-collection-description-shown: true
                  properties:
                    voice:
                      type: object
                      description: "Voice application webhook config"
                      x-nexmo-developer-collection-description-shown: true
                      properties:
                        webhooks:
                          type: object
                          properties:
                            answer_url:
                              type: object
                              description: "The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/answer
                                http_method:
                                  type: string
                                  example: GET
                                  enum:
                                    - GET
                                    - POST
                            fallback_answer_url:
                              type: object
                              description: |
                                  If your `answer_url` is offline or returns a HTTP error code, Nexmo will make a request to a
                                  `fallback_answer_url` if it is set. This URL must return an NCCO.
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://fallback.example.com/webhooks/answer
                                http_method:
                                  type: string
                                  example: GET
                                  enum:
                                    - GET
                                    - POST
                            event_url:
                              type: object
                              description: "Nexmo will send call events (e.g. `ringing`, `answered`) to this URL"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/event
                                http_method:
                                  type: string
                                  example: POST
                                  enum:
                                    - GET
                                    - POST
                    rtc:
                      type: object
                      description: "RTC / Client SDK application webhook config"
                      x-nexmo-developer-collection-description-shown: true
                      properties:
                        webhooks:
                          type: object
                          properties:
                            event_url:
                              type: object
                              description: "Nexmo will send RTC events to this URL"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/event
                                http_method:
                                  type: string
                                  example: POST
                                  enum:
                                    - GET
                                    - POST
                    messages:
                      type: object
                      description: "Messages and Dispatch application webhook config"
                      x-nexmo-developer-collection-description-shown: true
                      properties:
                        webhooks:
                          type: object
                          properties:
                            inbound_url:
                              type: object
                              description: "Nexmo will forward inbound messages to this URL"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/inbound
                                http_method:
                                  type: string
                                  example: POST
                                  enum:
                                    - POST
                            status_url:
                              type: object
                              description: "Nexmo will send message status updates (e.g. `delivered`, `seen`) to this URL"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/status
                                http_method:
                                  type: string
                                  example: POST
                                  enum:
                                    - POST
                    vbc:
                      type: object
                      description: "Specify `vbc` capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object."
                      x-nexmo-developer-collection-description-shown: true                                   
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApplicationResponse'
                  - type: object
                    properties:
                      keys:
                        type: object
                        properties:
                          public_key:
                            type: string
                            example: |
                              -----BEGIN PUBLIC KEY-----
                              MIIBIjANBgkqhkiG9w0BAQEFAAOCA
                              KOxjsU4pf/sMFi9N0jqcSLcjxu33G
                              d/vynKnlw9SENi+UZR44GdjGdmfm1
                              tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
                              0kYWekeIZawIwe/g9faFgkev+1xsO
                              OUNhPx2LhuLmgwWSRS4L5W851Xe3f
                              UQIDAQAB
                              -----END PUBLIC KEY-----
                          private_key:
                            type: string
                            example: |
                              -----BEGIN PRIVATE KEY-----
                              MIIEvQIBADANBgkqhkiG9w0BAQEFA
                              ASCBKcwggSjAgEAAoIBAQDEPpvi+3
                              RH1efQ\nkveWzZDrNNoEXmBw61w+O
                              0u/N36tJnN5XnYecU64yHzu2ByEr0
                              7iIvYbavFnADwl\nHMTJwqDQakpa3
                              8/SFRnTDq3zronvNZ6nOp7S6K7pcZ
                              rw/CvrL6hXT1x7cGBZ4jPx\nqhjqY
                              uJPgZD7OVB69oYOV92vIIJ7JLYwqb
                              -----END PRIVATE KEY-----
        '400':
          $ref: '#/components/responses/InvalidPayloadError'
        '401':
          $ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
        '405':
          $ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
        '406':
          $ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'
        '415':
          $ref: 'common/common_errors.yml#/components/responses/UnsupportedContentTypeHeader'

    get:
      operationId: listApplication
      summary: List available applications
      parameters:
        - name: page_size
          in: query
          description: The number of applications per page
          schema:
            type: integer
        - name: page
          in: query
          description: The current page number (starts at 1)
          schema:
            type: integer

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  page_size:
                    type: integer
                    example: 10
                    description: The number of applications per page
                  page:
                    type: integer
                    example: 1
                    description: The current page number (starts at 1)
                  total_items:
                    type: integer
                    example: 6
                    description: The total number of applications
                  total_pages:
                    type: integer
                    example: 1
                    description: The total number of pages returned
                  _embedded:
                    type: object
                    description: A list of applications matching your existing filters
                    properties:
                      applications:
                        type: array
                        items:
                          $ref: '#/components/schemas/ApplicationResponse'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                properties:
                  type:
                    type: string
                    example: 'https://developer.nexmo.com/api-errors/application#list-validation'
                  title:
                    type: string
                    example: Bad Request
                  detail:
                    type: string
                    example: The request failed due to validation errors
                  invalid_parameters:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: page_size
                        reason:
                          type: string
                          example: must be between 1 and 100
                  instance:
                    $ref: 'common/common_errors.yml#/components/fields/instance'
        '401':
          $ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
        '405':
          $ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
        '406':
          $ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'

  /{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the application
        example: 78d335fa323d01149c3dd6f0d48968cf
        schema:
          type: string
    get:
      operationId: getApplication
      summary: Get an application
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationResponse'
        '401':
          $ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
        '404':
          $ref: 'common/common_errors.yml#/components/responses/NotFoundError'
        '405':
          $ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
        '406':
          $ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'

    put:
      summary: Update an application
      operationId: updateApplication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - name
              properties:
                name:
                  description: "Application Name"
                  example: "Demo Application"
                  type: "string"
                keys:
                  type: object
                  properties:
                    public_key:
                      type: string
                      example: |
                          -----BEGIN PUBLIC KEY-----
                          MIIBIjANBgkqhkiG9w0BAQEFAAOCA
                          KOxjsU4pf/sMFi9N0jqcSLcjxu33G
                          d/vynKnlw9SENi+UZR44GdjGdmfm1
                          tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
                          0kYWekeIZawIwe/g9faFgkev+1xsO
                          OUNhPx2LhuLmgwWSRS4L5W851Xe3f
                          UQIDAQAB
                          -----END PUBLIC KEY-----
                      description: Public key
                capabilities:
                  type: object
                  description: "Your application can use multiple products. This contains the configuration for each product. This replaces the application `type` from version 1 of the Application API."
                  x-nexmo-developer-collection-description-shown: true
                  properties:
                    voice:
                      type: object
                      description: "Voice application webhook config"
                      x-nexmo-developer-collection-description-shown: true
                      properties:
                        webhooks:
                          type: object
                          properties:
                            answer_url:
                              type: object
                              description: "The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/answer
                                http_method:
                                  type: string
                                  example: GET
                                  enum:
                                    - GET
                                    - POST
                            fallback_answer_url:
                              type: object
                              description: |
                                  If your `answer_url` is offline or returns a HTTP error code, Nexmo will make a request to a
                                  `fallback_answer_url` if it is set. This URL must return an NCCO
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://fallback.example.com/webhooks/answer
                                http_method:
                                  type: string
                                  example: GET
                                  enum:
                                    - GET
                                    - POST
 
                            event_url:
                              type: object
                              description: "Nexmo will send call events (e.g. `ringing`, `answered`) to this URL"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/event
                                http_method:
                                  type: string
                                  example: POST
                                  enum:
                                    - GET
                                    - POST
                    rtc:
                      type: object
                      description: "RTC / Client SDK application webhook config"
                      x-nexmo-developer-collection-description-shown: true
                      properties:
                        webhooks:
                          type: object
                          properties:
                            event_url:
                              type: object
                              description: "Nexmo will send RTC events to this URL"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/event
                                http_method:
                                  type: string
                                  example: POST
                                  enum:
                                    - GET
                                    - POST
                    messages:
                      type: object
                      description: "Messages and Dispatch application webhook config"
                      x-nexmo-developer-collection-description-shown: true
                      properties:
                        webhooks:
                          type: object
                          properties:
                            inbound_url:
                              type: object
                              description: "Nexmo will forward inbound messages to this URL"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/inbound
                                http_method:
                                  type: string
                                  example: POST
                                  enum:
                                    - POST
                            status_url:
                              type: object
                              description: "Nexmo will send message status updates (e.g. `delivered`, `seen`) to this URL"
                              x-nexmo-developer-collection-description-shown: true
                              properties:
                                address:
                                  type: string
                                  example: https://example.com/webhooks/status
                                http_method:
                                  type: string
                                  example: POST
                                  enum:
                                    - POST
                    vbc:
                      type: object
                      description: "Specify the `vbc` capability to enable zero-rated calls for VBC number programmability service applications.  This must be an empty object."
                      x-nexmo-developer-collection-description-shown: true                                      
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApplicationResponse'
                  - type: object
                    properties:
                      keys:
                        type: object
                        properties:
                          public_key:
                            type: string
                            example: |
                              -----BEGIN PUBLIC KEY-----
                              MIIBIjANBgkqhkiG9w0BAQEFAAOCA
                              KOxjsU4pf/sMFi9N0jqcSLcjxu33G
                              d/vynKnlw9SENi+UZR44GdjGdmfm1
                              tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
                              0kYWekeIZawIwe/g9faFgkev+1xsO
                              OUNhPx2LhuLmgwWSRS4L5W851Xe3f
                              UQIDAQAB
                              -----END PUBLIC KEY-----
                          private_key:
                            type: string
                            example: |
                              -----BEGIN PRIVATE KEY-----
                              MIIEvQIBADANBgkqhkiG9w0BAQEFA
                              ASCBKcwggSjAgEAAoIBAQDEPpvi+3
                              RH1efQ\nkveWzZDrNNoEXmBw61w+O
                              0u/N36tJnN5XnYecU64yHzu2ByEr0
                              7iIvYbavFnADwl\nHMTJwqDQakpa3
                              8/SFRnTDq3zronvNZ6nOp7S6K7pcZ
                              rw/CvrL6hXT1x7cGBZ4jPx\nqhjqY
                              uJPgZD7OVB69oYOV92vIIJ7JLYwqb
                              -----END PRIVATE KEY-----
        '400':
          $ref: '#/components/responses/InvalidPayloadError'
        '401':
          $ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
        '404':
          $ref: 'common/common_errors.yml#/components/responses/NotFoundError'
        '405':
          $ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
        '406':
          $ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'
        '415':
          $ref: 'common/common_errors.yml#/components/responses/UnsupportedContentTypeHeader'
    delete:
      operationId: deleteApplication
      summary: Delete an application
      description: Deleting an application **cannot be undone**.
      responses:
        '204':
          description: Success
        '401':
          $ref: 'common/common_errors.yml#/components/responses/BadCredentialsError'
        '404':
          $ref: 'common/common_errors.yml#/components/responses/NotFoundError'
        '405':
          $ref: 'common/common_errors.yml#/components/responses/InvalidRequestMethod'
        '406':
          $ref: 'common/common_errors.yml#/components/responses/InvalidAcceptHeader'

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  responses:
    InvalidPayloadError:
      description: Invalid Request
      content:
        application/json:
          schema:
            properties:
              type:
                type: string
                example: 'https://developer.nexmo.com/api-errors/application#payload-validation'
              title:
                type: string
                example: Bad Request
              detail:
                type: string
                example: The request failed due to validation errors
              invalid_parameters:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      example: capabilities.voice.webhooks.answer_url.http_method
                    reason:
                      type: string
                      example: 'must be one of: GET, POST'
              instance:
                $ref: 'common/common_errors.yml#/components/fields/instance'
 
  schemas:
    ApplicationResponse:
      properties:
        id:
          type: string
          example: 78d335fa323d01149c3dd6f0d48968cf
          description: The application's ID
        name:
          type: string
          example: My Application
          description: Friendly identifier for your application. This is not unique
        capabilities:
          type: object
          description: Configuration for the products available in this application
          properties:
            voice:
              type: object
              description: Voice related configuration
              properties:
                webhooks:
                  type: object
                  properties:
                    answer_url:
                      type: object
                      properties:
                        address:
                          type: string
                          example: https://example.com/webhooks/answer
                          description: The URL that Nexmo requests when a call is placed/received. Must return an NCCO
                        http_method:
                          type: string
                          example: POST
                          description: The HTTP method used to fetch your NCCO from your `answer_url`
                    fallback_answer_url:
                      type: object
                      properties:
                        address:
                          type: string
                          example: https://fallback.example.com/webhooks/answer
                          description: |
                                  If your `answer_url` is offline or returns a HTTP error code, Nexmo will make a request to a
                                  `fallback_answer_url` if it is set. This URL must return an NCCO.
                        http_method:
                          type: string
                          example: POST
                          description: The HTTP method used to fetch your NCCO from your `answer_url`
                    event_url:
                      type: object
                      properties:
                        address:
                          type: string
                          example: https://example.com/webhooks/event
                          description: The URL that Nexmo sends events related to your call to
                        http_method:
                          type: string
                          example: POST
                          description: The HTTP method used to send events to your server
            messages:
              type: object
              description: Messages / Dispatch related configuration
              properties:
                webhooks:
                  type: object
                  properties:
                    inbound_url:
                      type: object
                      properties:
                        address:
                          type: string
                          example: https://example.com/webhooks/inbound
                          description: The URL that Nexmo forwards inbound messages to on your server
                        http_method:
                          type: string
                          example: POST
                          description: The HTTP method used to send inbound messages to your server
                    status_url:
                      type: object
                      properties:
                        address:
                          type: string
                          example: https://example.com/webhooks/status
                          description: The URL that Nexmo sends events related to your messages to
                        http_method:
                          type: string
                          example: POST
                          description: The HTTP method used to send events to your server (always `POST`)
            rtc:
              type: object
              description: RTC / Conversation Service related configuration
              properties:
                webhooks:
                  type: object
                  properties:
                    event_url:
                      type: object
                      properties:
                        address:
                          type: string
                          example: https://example.com/webhooks/event
                        http_method:
                          type: string
                          example: POST
            vbc:
              type: object
              description: "Specify the `vbc` capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object."

x-errors:
  payload-validation:
    description: Invalid request. See `invalid_parameters` field for details
    resolution: Review the documentation and send a valid `POST` request.
    link:
      text: View API reference
      url: /api/application.v2#createApplication

  list-validation:
    description: Invalid request. See `invalid_parameters` field for details
    resolution: Review the documentation and send a valid `GET` request.
    link:
      text: View API reference
      url: /api/application.v2#listApplication

  rate-limit:
    description: The request was rate limited
    resolution: The Redact API supports 170 requests per second. Reduce the frequency of your requests.
