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

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"
}