Nexmo Audit API

Nexmo's Audit API allows you to view details of changes to your account.

Download OpenAPI 3 Definition

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
string

Number of elements per page.


Must be between 1 and 100 		None 30

View response field descriptions

Response Fields

Field Description
_embedded

Container containing the events array.

Field Description
events
array of objects
Field Description
id

UUID of the audit event
event_type

The type of the audit event.
event_type_description

A description of the event type
created_at

When the audit event was created.
user_email

Email of the user whose account the audit event is associated with.
user_id

The ID of the user that the audit event is associated with.
account_id

The NEXMO_API_KEY of the Nexmo account that the audit event is associated with.
source

The source of the event. CD: Customer Dashboard DEVAPI: via Developer API

One of: CD or DEVAPI
source_ip

The IP address used to make the account change.
source_description

Description of the audit event source.

One of: Customer Dashboard or Developer API
source_country

ISO 3166-1 Alpha-2 country code recorded for the event.
context

A valid JSON object with information detailing the context of the audit event.
page

Pagination data.

Field Description
size

The total number of items in this response (page).
totalElements

The total number of items across all pages.
totalPages

The number of pages of data in the response.
number

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",
        "_links": {
          "self": {
            "href": "https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
          }
        },
        "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": "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

The type of the audit event.
description

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

UUID of the audit event
event_type

The type of the audit event.
event_type_description

A description of the event type
created_at

When the audit event was created.
user_email

Email of the user whose account the audit event is associated with.
user_id

The ID of the user that the audit event is associated with.
account_id

The NEXMO_API_KEY of the Nexmo account that the audit event is associated with.
source

The source of the event. CD: Customer Dashboard DEVAPI: via Developer API

One of: CD or DEVAPI
source_ip

The IP address used to make the account change.
source_description

Description of the audit event source.

One of: Customer Dashboard or Developer API
source_country

ISO 3166-1 Alpha-2 country code recorded for the event.
context

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",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "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"
      }
    }
  }
}
{
  "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"
}