openapi: 3.2.0
info:
  title: Vonage Events API
  version: 1.0.6
  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-label: Beta
  x-metaDescription: Find quick answers to questions about the Vonage Audit API in this reference guide. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Audit API Reference | Vonage API Documentation
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: vonage-audit-openapi.json, vonage-audit-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.nexmo.com/beta/audit
tags:
- name: Events
paths:
  /events:
    get:
      operationId: getEvents
      summary: Retrieve audit events
      description: Get a series of audit events describing changes made to your Vonage API account over time.
      parameters:
      - name: event_type
        description: Filter results by this event type.
        in: query
        schema:
          $ref: '#/components/schemas/EventTypes'
      - name: date_from
        schema:
          type: string
        description: Start of time range for audit events. DateTime in ISO-8601 format.
        in: query
      - name: date_to
        schema:
          type: string
        description: End of time range for audit events. DateTime in ISO-8601 format.
        in: query
      - name: search_text
        schema:
          type: string
        description: Return only audit events where the JSON object contains this search text. Must be legal text for a JSON attribute value, that is quotes and braces must be escaped.
        in: query
      - name: page
        schema:
          type: string
        description: Page number starting with page 1.
        in: query
      - name: size
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
        description: Number of elements per page.
        in: query
      security:
      - basicAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResp'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
      tags:
      - Events
    options:
      operationId: getEventsOptions
      summary: Retrieve audit event types
      description: Get audit event types.
      security:
      - basicAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventTypesResp'
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoContent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
      tags:
      - Events
    servers:
    - url: https://api.nexmo.com/beta/audit
  /events/{id}:
    get:
      operationId: getEvent
      summary: Retrieve individual audit event
      description: Get the specified audit event.
      parameters:
      - name: id
        schema:
          type: string
        description: The UUID of the audit event to retrieve
        in: path
        required: true
        example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      security:
      - basicAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEvent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
      tags:
      - Events
    servers:
    - url: https://api.nexmo.com/beta/audit
components:
  schemas:
    AuditEventType:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/EventTypes'
        description:
          type: string
          example: Application created.
          description: A description of the event type
    ErrorUnauthorized:
      type: object
      properties:
        status:
          type: integer
          example: 401
          description: The HTTP Status code of the error
        error:
          type: string
          example: Unauthorized
          description: A human readable description of the error
        message:
          type: string
          example: Full authentication is required. JWT was not found in "Authorization" HTTP header.
          description: A longer description of the error
    ErrorForbidden:
      type: object
      properties:
        status:
          type: integer
          example: 403
          description: The HTTP Status code of the error
        error:
          type: string
          example: Forbidden
          description: A human readable description of the error
        message:
          type: string
          example: An example goes here
          description: A longer description of the error
    ErrorNotFound:
      type: object
      properties:
        status:
          type: integer
          example: 404
          description: The HTTP Status code of the error
        error:
          type: string
          example: Not Found
          description: A human readable description of the error XXX
        message:
          type: string
          example: 'Event with provided id: aaaaaaaa-bbbb-cccc-dddd-0123456789ab was not found'
          description: A longer description of the error YYY
    ContextNumberLinking:
      type: object
      description: Number Linking
      properties:
        country:
          type: string
          description: The country of the number
          example: GB
        account:
          type: string
          description: Which account the number is associated with
          example: abcdef01
        msisdn:
          type: string
          description: The phone number linked/unlinked to your application
          example: '447000123456'
        applicationId:
          type: string
          description: UUID of the app the number is being linked/unlinked to
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
    NoContent:
      type: object
      properties:
        status:
          type: integer
          example: 204
          description: The HTTP Status code of the error
        error:
          type: string
          example: No Content
          description: A human readable description of the error AAA
        message:
          type: string
          example: No content
          description: A longer description of the error BBB
    CallbackUrl:
      type: object
      properties:
        method:
          type: string
          example: GET
          enum:
          - GET
          - POST
          description: The HTTP method used to make a callback to your application
        url:
          type: string
          example: https://example.org/my-app-callback
          format: url
          description: The URL used for a callback to your application
    ContextAppCreate:
      type: object
      description: App Creation
      properties:
        appId:
          type: string
          description: UUID of the app that was created
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
        created:
          type: object
          properties:
            accountId:
              type: string
              example: abcdef01
              description: Which account the app is associated with
            appId:
              type: string
              description: UUID of the app that was created
              example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
            name:
              type: string
              description: The name of the application created
              example: My Voice App
            answer_url:
              $ref: '#/components/schemas/CallbackUrl'
            event_url:
              $ref: '#/components/schemas/CallbackUrl'
            type:
              type: string
              example: voice
              description: The type of application created
    EventLink:
      type: object
      description: A link to this audit event object if you were to retrieve it individually.
      properties:
        self:
          properties:
            href:
              type: string
              format: uri
              description: URI of this document.
              example: https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
    AuditResp:
      type: object
      properties:
        _embedded:
          type: object
          description: Container containing the `events` array.
          properties:
            events:
              type: array
              items:
                $ref: '#/components/schemas/AuditEvent'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
        page:
          $ref: '#/components/schemas/PaginationData'
    AuditEventTypesResp:
      type: object
      properties:
        eventTypes:
          type: array
          description: An array of audit event types.
          items:
            $ref: '#/components/schemas/AuditEventType'
    ContextNumberUpdate:
      type: object
      description: Number Update
      properties:
        country:
          type: string
          description: The country of the number
        msisdn:
          type: string
          description: The phone number linked/unlinked to your application
          example: '447000123456'
        voice-type:
          type: string
          enum:
          - tel
          - sip
          - vxml
          - app
          example: app
          description: The type of endpoint the number has been forwarded to
        voice-value:
          type: string
          description: The value of the endpoint the number has been forwarded to
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
        http:
          type: string
          format: url
          description: The URL of the endpoint the number has been forwarded to
          example: https://example.org/my-app-callback
    PaginationLinks:
      type: object
      description: Container containing self, next and last page links.
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: URI of this document.
              example: http://api.nexmo.com/beta/audit/events
        next:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: URI of the next document.
              example: http://api.nexmo.com/beta/audit/events?page=2&size=30
        last:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: URI of the last document in the sequence.
              example: http://api.nexmo.com/beta/audit/events?page=2&size=30
    AuditEvent:
      type: object
      properties:
        id:
          type: string
          description: UUID of the audit event
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
        event_type:
          $ref: '#/components/schemas/EventTypes'
        event_type_description:
          type: string
          description: A description of the event type
          example: Application created.
        created_at:
          type: string
          description: When the audit event was created.
          example: '2018-07-04T11:41:32'
          format: date-time
        user_email:
          type: string
          description: Email of the user whose account the audit event is associated with.
          format: email
          example: user@example.org
        user_id:
          type: integer
          description: The ID of the user that the audit event is associated with.
          example: 1234567
        account_id:
          type: string
          description: The NEXMO_API_KEY of the Vonage API account that the audit event is associated with.
          example: abcd1234
        source:
          type: string
          description: 'The source of the event.

            CD: Customer Dashboard DEVAPI: via Developer API

            '
          enum:
          - CD
          - DEVAPI
          example: CD
        source_ip:
          type: string
          format: ipv4
          description: The IP address used to make the account change.
          example: 192.0.2.0
        source_description:
          type: string
          description: Description of the audit event source.
          format: A human readable description of the `source`.
          enum:
          - Customer Dashboard
          - Developer API
          example: Customer Dashboard
        source_country:
          type: string
          description: ISO 3166-1 Alpha-2 country code recorded for the event.
          example: GB
        context:
          type: object
          description: A valid JSON object with information detailing the context of the audit event.
          oneOf:
          - $ref: '#/components/schemas/ContextAppCreate'
          - $ref: '#/components/schemas/ContextNumberLinking'
          - $ref: '#/components/schemas/ContextNumberUpdate'
          example:
            created:
              accountId: abcdef01
              appId: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
              name: My voice app
              answer_url:
                method: GET
                url: https://example.org/call
              type: voice
              event_url:
                method: POST
                url: https://example.org/event
        _links:
          $ref: '#/components/schemas/EventLink'
    PaginationData:
      type: object
      description: Page containing results.
      properties:
        size:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
          example: 100
          description: The total number of items in this response (page).
        totalElements:
          type: integer
          example: 120
          description: The total number of items across all pages.
        totalPages:
          type: integer
          example: 2
          description: The number of pages of data in the response.
        number:
          type: integer
          example: 1
          description: Which page of the pagination sequence you are looking at.
    EventTypes:
      type: string
      description: The type of the audit event.
      example: APP_CREATE
      enum:
      - USER_STATUS
      - USER_UPDATE
      - USER_BILLING_UPDATE
      - USER_CREATE
      - USER_LOGIN
      - USER_LOGOUT
      - USER_PRODUCT_SEARCH
      - USER_API_KEYS_UPDATE
      - ACCOUNT_SECRET_DELETE
      - ACCOUNT_SECRET_CREATE
      - ACCOUNT_UPDATE_SPAMMER
      - ACCOUNT_UPDATE_SETTINGS_API
      - NUMBER_ASSIGN
      - NUMBER_UPDATED
      - NUMBER_RELEASE
      - NUMBER_LINKED
      - NUMBER_UNLINKED
      - APP_CREATE
      - APP_UPDATE
      - APP_DELETE
      - APP_DISABLE
      - APP_ENABLE
      - IP_WHITELIST_CREATE
      - IP_WHITELIST_DELETE
      - AUTORELOAD_ENABLE
      - AUTORELOAD_UPDATE
      - AUTORELOAD_DISABLE
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-refined-from:
- vonage-audit-openapi.json
- vonage-audit-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