Nexmo Audit API

Nexmo's Audit API allows you to view details of changes to your account. More information is available at https://developer.nexmo.com/audit/overview. Please note that the Audit API is currently in Beta

Download OpenAPI 3 Definition

Improve this specification

Retrieve audit events

Get a series of audit events describing changes made to your Nexmo account over time.

GET


          
          
          https://api.nexmo.com/beta/audit/events

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Query Parameter

Key	Description	Example	Default
event_type string	Filter results by this event type. Must be one of: `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` or `AUTORELOAD_DISABLE`	`APP_CREATE`	None
date_from string	Start of time range for audit events. DateTime in ISO-8601 format.	None	None
date_to string	End of time range for audit events. DateTime in ISO-8601 format.	None	None
search_text string	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.	None	None
page string	Page number starting with page 1.	None	None
size integer	Number of elements per page.	None	`30`

View response field descriptions

Response Fields

Field Description

_embedded
object

Container containing the events array.

Field Description

events
array of objects

Field	Description
id string	UUID of the audit event
event_type string	The type of the audit event. One of: `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` or `AUTORELOAD_DISABLE`
event_type_description string	A description of the event type
created_at string	When the audit event was created.
user_email string	Email of the user whose account the audit event is associated with.
user_id integer	The ID of the user that the audit event is associated with.
account_id string	The NEXMO_API_KEY of the Nexmo account that the audit event is associated with.
source string	The source of the event. CD: Customer Dashboard DEVAPI: via Developer API One of: `CD` or `DEVAPI`
source_ip string	The IP address used to make the account change.
source_description string	Description of the audit event source. One of: `Customer Dashboard` or `Developer API`
source_country string	ISO 3166-1 Alpha-2 country code recorded for the event.
context object	A valid JSON object with information detailing the context of the audit event.

page
object

Page containing results.

Field	Description
size integer	The total number of items in this response (page).
totalElements integer	The total number of items across all pages.
totalPages integer	The number of pages of data in the response.
number integer	Which page of the pagination sequence you are looking at.

{
  "_embedded": {
    "events": [
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "event_type": "APP_CREATE",
        "event_type_description": "Application created.",
        "created_at": "2018-07-04T11:41:32",
        "user_email": "user@example.org",
        "user_id": 1234567,
        "account_id": "abcd1234",
        "source": "CD",
        "source_ip": "192.0.2.0",
        "source_description": "Customer Dashboard",
        "source_country": "GB",
        "context": {
          "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": {
          "self": {
            "href": "https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "http://api.nexmo.com/beta/audit/events"
    },
    "next": {
      "href": "http://api.nexmo.com/beta/audit/events?page=2&size=30"
    },
    "last": {
      "href": "http://api.nexmo.com/beta/audit/events?page=2&size=30"
    }
  },
  "page": {
    "size": 100,
    "totalElements": 120,
    "totalPages": 2,
    "number": 1
  }
}

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required. JWT was not found in \"Authorization\" HTTP header."
}

{
  "status": 403,
  "error": "Forbidden",
  "message": "An example goes here"
}

{
  "status": 404,
  "error": "Not Found",
  "message": "Event with provided id: aaaaaaaa-bbbb-cccc-dddd-0123456789ab was not found"
}

Retrieve audit event types

Get audit event types.

OPTIONS


          
          
          https://api.nexmo.com/beta/audit/events

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

View response field descriptions

Response Fields

Field Description

eventTypes
array of objects

An array of audit event types.

Field Description

type
string

The type of the audit event.

One of: 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 or AUTORELOAD_DISABLE

description
string

A description of the event type

{
  "eventTypes": [
    {
      "type": "APP_CREATE",
      "description": "Application created."
    }
  ]
}

{
  "status": 204,
  "error": "No Content",
  "message": "No content"
}

No Content

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required. JWT was not found in \"Authorization\" HTTP header."
}

{
  "status": 403,
  "error": "Forbidden",
  "message": "An example goes here"
}

Retrieve individual audit event

Get the specified audit event.

GET


          
          
          https://api.nexmo.com/beta/audit/events/:id

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Path Parameters

Key	Description	Example	Default
id Required \| string	The UUID of the audit event to retrieve	`aaaaaaaa-bbbb-cccc-dddd-0123456789ab`	None

View response field descriptions

Response Fields

Field	Description
id string	UUID of the audit event
event_type string	The type of the audit event. One of: `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` or `AUTORELOAD_DISABLE`
event_type_description string	A description of the event type
created_at string	When the audit event was created.
user_email string	Email of the user whose account the audit event is associated with.
user_id integer	The ID of the user that the audit event is associated with.
account_id string	The NEXMO_API_KEY of the Nexmo account that the audit event is associated with.
source string	The source of the event. CD: Customer Dashboard DEVAPI: via Developer API One of: `CD` or `DEVAPI`
source_ip string	The IP address used to make the account change.
source_description string	Description of the audit event source. One of: `Customer Dashboard` or `Developer API`
source_country string	ISO 3166-1 Alpha-2 country code recorded for the event.
context object	A valid JSON object with information detailing the context of the audit event.

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "event_type": "APP_CREATE",
  "event_type_description": "Application created.",
  "created_at": "2018-07-04T11:41:32",
  "user_email": "user@example.org",
  "user_id": 1234567,
  "account_id": "abcd1234",
  "source": "CD",
  "source_ip": "192.0.2.0",
  "source_description": "Customer Dashboard",
  "source_country": "GB",
  "context": {
    "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": {
    "self": {
      "href": "https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  }
}

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required. JWT was not found in \"Authorization\" HTTP header."
}

{
  "status": 404,
  "error": "Not Found",
  "message": "Event with provided id: aaaaaaaa-bbbb-cccc-dddd-0123456789ab was not found"
}

API Developer

Nexmo Audit API

Nexmo Audit API

Retrieve audit events

Authentication

Query Parameter

Response Fields

HTTP response 200

HTTP response 401

HTTP response 403

HTTP response 404

Retrieve audit event types

Authentication

Response Fields

HTTP response 200

HTTP response 204

HTTP response 401

HTTP response 403

Retrieve individual audit event

Authentication

Path Parameters

Response Fields

HTTP response 200

HTTP response 401

HTTP response 404