Available Operations
 
 

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

Available Operations:

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
Host https://api.nexmo.com
GET /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

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
date_from
string

Start of time range for audit events. DateTime in ISO-8601 format.

date_to
string

End of time range for audit events. DateTime in ISO-8601 format.

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.

page
string

Page number starting with page 1.

size
integer

Number of elements per page.

Responses

200 OK
_embedded
object

Container containing the events array.

events
array of objects
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.

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.

Example Responses

200 401 403 404
{
  "_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
Host https://api.nexmo.com
OPTIONS /beta/audit/events

Authentication

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

Responses

200 OK
eventTypes
array of objects

An array of audit event types.

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

204 No Content
status
integer

The HTTP Status code of the error

error
string

A human readable description of the error AAA

message
string

A longer description of the error BBB

Example Responses

200 204 401 403
{
  "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
Host https://api.nexmo.com
GET /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

id
string | Required

The UUID of the audit event to retrieve

Responses

200 OK
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.

Example Responses

200 401 404
{
  "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"
}