Reports API

The Reports API enables you to request a report of activity for your Vonage account.

Depending on your query pattern, you can choose from one of the two versions of the Reports API: asynchronous and synchronous. The asynchronous version is optimized for infrequent and large data queries (from several records to tens of millions). The synchronous version is optimized for frequent and periodic retrievals of small batches of data records (from one record to tens of thousand per query).

Only synchronous version supports retrival of data records by message/record ID.

Vonage recommends that you limit asynchronous queries to a maximum of 7 million records, by setting the start and end dates accordingly. On average, the asynchronous Reports API takes 5 - 10 minutes to generate 1 million records.

Reports API is a paid product. Full pricing is available at https://www.vonage.com/communications-apis/pricing/.

We recommend the unlimited option if you are going to retrieve more than 1M records per month.

Download OpenAPI Specification

Reports API

Endpoints for creating and managing report generation requests

Available Operations

Get Async Report Status

Retrieve the status and details of an async report using its report ID

gethttps://api.nexmo.com/v2/reports/:reportId

Authentication

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

Path Parameters

reportId

string

Required

Unique identifier of the report

Responses
Content Type
application/json

Report details retrieved successfully

One Of

request_params

One Of

direction

string

Required

SMS direction filter (mandatory)

Must be one of:inboundoutbound

status

string

SMS delivery status filter

Must be one of:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

Sender ID

string

Recipient phone number

country

string

Country code

network

string

Mobile network code

client_ref

string

Client reference

account_ref

string

Account reference

include_message

boolean

Include message content

show_concatenated

boolean

Show concatenated parts

gateway

string

SMS gateway

gateway_id

string

Gateway ID

request_id

string

Report identifier

status

string

Report status

receive_time

string(date-time)

Request received time

start_time

string(date-time)

Processing start time

download_url

string(uri)

Download URL

items_count

integer(int64)

Number of records

_links

object

HAL links

self

object

href

string(uri)

Example Response»SMS report response with SMS-specific request parameters

{
   "request_id": "string",
   "status": "string",
   "receive_time": "2019-08-24T14:15:22Z",
   "start_time": "2019-08-24T14:15:22Z",
   "download_url": "http://example.com",
   "items_count": 0,
   "request_params": {
      "direction": "inbound",
      "status": "delivered",
      "from": "string",
      "to": "string",
      "country": "string",
      "network": "string",
      "client_ref": "string",
      "account_ref": "string",
      "include_message": true,
      "show_concatenated": true,
      "gateway": "string",
      "gateway_id": "string"
   },
   "_links": {
      "self": {
         "href": "http://example.com"
      }
   }
}

Abort Async Report

Abort a pending or processing async report. Reports that are already completed cannot be aborted.

deletehttps://api.nexmo.com/v2/reports/:reportId

Authentication

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

Path Parameters

reportId

string

Required

Unique identifier of the report to abort

Responses
Content Type
application/json

Report aborted successfully

One Of

request_params

One Of

direction

string

Required

SMS direction filter (mandatory)

Must be one of:inboundoutbound

status

string

SMS delivery status filter

Must be one of:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

Sender ID

string

Recipient phone number

country

string

Country code

network

string

Mobile network code

client_ref

string

Client reference

account_ref

string

Account reference

include_message

boolean

Include message content

show_concatenated

boolean

Show concatenated parts

gateway

string

SMS gateway

gateway_id

string

Gateway ID

request_id

string

Report identifier

status

string

Report status

receive_time

string(date-time)

Request received time

start_time

string(date-time)

Processing start time

download_url

string(uri)

Download URL

items_count

integer(int64)

Number of records

_links

object

HAL links

self

object

href

string(uri)

Example Response»SMS report response with SMS-specific request parameters

{
   "request_id": "string",
   "status": "string",
   "receive_time": "2019-08-24T14:15:22Z",
   "start_time": "2019-08-24T14:15:22Z",
   "download_url": "http://example.com",
   "items_count": 0,
   "request_params": {
      "direction": "inbound",
      "status": "delivered",
      "from": "string",
      "to": "string",
      "country": "string",
      "network": "string",
      "client_ref": "string",
      "account_ref": "string",
      "include_message": true,
      "show_concatenated": true,
      "gateway": "string",
      "gateway_id": "string"
   },
   "_links": {
      "self": {
         "href": "http://example.com"
      }
   }
}

Search Async Reports

Search for existing async reports with optional filters

gethttps://api.nexmo.com/v2/reports

Authentication

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

Query Parameters

account_id

string

Account ID to filter reports (required for public endpoints)

status

string

Report status to filter by

Must be one of:PENDINGPROCESSINGSUCCESSFAILEDABORTED

date_from

string

Start date for report creation filter (ISO 8601 format)

date_to

string

End date for report creation filter (ISO 8601 format)

Responses

Search results retrieved successfully

Create an asynchronous report

Creates an asynchronous report generation request. The report will be processed in the background and you can check its status using the returned report ID.

posthttps://api.nexmo.com/v2/reports

Authentication

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

Request Body
Content Type
application/json

One Of

direction

string

Required

SMS direction filter (mandatory)

Must be one of:inboundoutbound

status

string

SMS delivery status filter

Must be one of:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

Sender ID

string

Recipient phone number

country

string

Country code

network

string

Mobile network code

client_ref

string

Client reference

account_ref

string

Account reference

include_message

boolean

Include message content

show_concatenated

boolean

Show concatenated parts

gateway

string

SMS gateway

gateway_id

string

Gateway ID

Example Request»SMS API request parameters

{
   "direction": "inbound",
   "status": "delivered",
   "from": "string",
   "to": "string",
   "country": "string",
   "network": "string",
   "client_ref": "string",
   "account_ref": "string",
   "include_message": true,
   "show_concatenated": true,
   "gateway": "string",
   "gateway_id": "string"
}

{
   "direction": "inbound",
   "status": "delivered",
   "from": "string",
   "to": "string",
   "country": "string",
   "network": "string",
   "client_ref": "string",
   "account_ref": "string",
   "include_message": true,
   "show_concatenated": true,
   "gateway": "string",
   "gateway_id": "string"
}

Responses
Content Type
application/json

Report creation request accepted

One Of

request_params

One Of

direction

string

Required

SMS direction filter (mandatory)

Must be one of:inboundoutbound

status

string

SMS delivery status filter

Must be one of:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

Sender ID

string

Recipient phone number

country

string

Country code

network

string

Mobile network code

client_ref

string

Client reference

account_ref

string

Account reference

include_message

boolean

Include message content

show_concatenated

boolean

Show concatenated parts

gateway

string

SMS gateway

gateway_id

string

Gateway ID

request_id

string

Report identifier

status

string

Report status

receive_time

string(date-time)

Request received time

start_time

string(date-time)

Processing start time

download_url

string(uri)

Download URL

items_count

integer(int64)

Number of records

_links

object

HAL links

self

object

href

string(uri)

Example Response»SMS report response with SMS-specific request parameters

{
   "request_id": "string",
   "status": "string",
   "receive_time": "2019-08-24T14:15:22Z",
   "start_time": "2019-08-24T14:15:22Z",
   "download_url": "http://example.com",
   "items_count": 0,
   "request_params": {
      "direction": "inbound",
      "status": "delivered",
      "from": "string",
      "to": "string",
      "country": "string",
      "network": "string",
      "client_ref": "string",
      "account_ref": "string",
      "include_message": true,
      "show_concatenated": true,
      "gateway": "string",
      "gateway_id": "string"
   },
   "_links": {
      "self": {
         "href": "http://example.com"
      }
   }
}

Create Sync Report

Generate and immediately return report data synchronously. Supports query parameters for filtering. For large datasets, consider using async reports instead. Two query modes are supported: date-based queries (using date_start/date_end) or ID-based queries (using the id parameter). When using ID queries, only a limited subset of parameters are allowed: product, account_id, direction, id, include_message, hide_prices, show_concatenated.

gethttps://api.nexmo.com/v2/reports/records

Authentication

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

Query Parameters

product

string

Product type for the report

Must be one of:SMSSMS-TRAFFIC-CONTROLVOICE-APIVOICE-REJECTEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLASRAMDNUMBER-VERIFYVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2CONVERSATION-MESSAGECONVERSATION-EVENTMESSAGESMEETINGSVIDEO-APICAMARA-QODNETWORK-API-EVENTVONAGE-QODREPORTS-USAGE

account_id

string

Your Vonage account ID

date_start

string

Start date for the report (ISO 8601 format). Required for date-based queries. Also supports relative dates like CURRENT_TIME-5M, CURRENT_TIME-5H, CURRENT_TIME-5D.

date_end

string

End date for the report (ISO 8601 format). Defaults to current time if not provided for date-based queries.

limit

integer(int64)

Min1

Max1000

Default1000

Maximum number of records to return (1-1000). Default is 1000.

cursor

string

Pagination cursor for retrieving the next page of results (date-based queries only)

string

Initialization vector for encrypted cursor pagination (date-based queries only)

string

Comma-separated list of record IDs to retrieve (max 20 IDs). When using this parameter, only product, account_id, direction, include_message, hide_prices, and show_concatenated are allowed.

direction

string

Direction filter - REQUIRED for SMS and Messages, optional for Voice (SMS/MESSAGES/VOICE-CALL/VOICE-FAILED/ASR).

Must be one of:inboundoutbound

status

string

Status filter (SMS/CONVERSATION-EVENT/IN-APP-VOICE/MESSAGES/VERIFY-V2/NUMBER-INSIGHT-V2)

from

string

Sender ID/number (SMS/MESSAGES/VOICE-CALL/VOICE-FAILED/ASR)

string

Recipient phone number (SMS/VOICE-CALL/VOICE-FAILED/ASR/MESSAGES/VERIFY-API/VERIFY-V2)

country

string

Country code filter (SMS/VOICE/MESSAGES/VERIFY-API/VERIFY-V2/NUMBER-INSIGHT)

network

string

Mobile network code filter (SMS/VOICE-CALL/VERIFY-API/VERIFY-V2/NUMBER-INSIGHT)

client_ref

string

Client reference (SMS)

number

string

Phone number for lookup (NUMBER-INSIGHT))

locale

string

Language/locale (VERIFY-API/VERIFY-V2)

include_message

boolean

Include message content in response (SMS/MESSAGES)

show_concatenated

boolean

Show concatenated message parts (SMS)

account_ref

string

Account reference (SMS)

gateway

string

SMS gateway (SMS)

gateway_id

string

Gateway ID (SMS)

call_id

string

Unique call identifier (VOICE-API/WEBSOCKET-CALL)

leg_id

string

Unique leg identifier for the call (IN-APP-VOICE)

provider

string

Messaging provider (MESSAGES)

number_type

string

Number type (VERIFY-API)

channel

string

Verification channel (VERIFY-V2)

parent_request_id

string

Parent request ID (VERIFY-V2)

request_type

string

Type of Request (NUMBER-INSIGHT-V2/NETWORK-API-EVENT)

risk

string

Risk assessment level (NUMBER-INSIGHT-V2)

swapped

boolean

Whether the number has been ported/swapped (NUMBER-INSIGHT-V2)

conversation_id

string

Conversation ID (CONVERSATION-EVENT/CONVERSATION-MESSAGE/IN-APP-VOICE)

session_id

string

Session ID (MEETINGS/VIDEO-API)

meeting_id

string

Meeting ID (VIDEO-API)

subtype

string

Meeting subtype classification (MEETINGS)

connection_count

integer(int32)

Number of participant connections (MEETINGS)

product_name

string

Product name for Network API event (NETWORK-API-EVENT)

request_session_id

string

Session ID for Network API (NETWORK-API-EVENT)

product_path

string

API path (NETWORK-API-EVENT)

correlation_id

string

Correlation ID (NETWORK-API-EVENT)

Responses
Content Type
application/json

Report data retrieved successfully

_links

object

HAL links for navigation

self

object

href

string(uri)

object

href

string(uri)

cursor

string

Cursor for pagination in synchronous requests

string

Initialization vector for encrypted message content

request_id

string

Unique request identifier

request_status

string

Synchronous request processing status

Must be one of:SUCCESSFAILURETRUNCATED

received_at

string(date-time)

Timestamp when the request was received

items_count

integer(int64)

Total number of records returned

records

array

Array of record data - structure varies based on product type

One Of

account_id

string

example12aa3456

The account ID (API key) of the Customer. Might be a main account id or a sub-account

message_id

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

Vonage's unique identifier for this message

account_ref

string

examplecustomer1234

It's used to identify separate accounts using the SMS endpoint for billing purposes. The field is optional in SMS API. It can be empty in the report

client_ref

string

examplemy-personal-reference

If client-ref parameter were used by the Customer while calling SMS API, the value with Client's own reference will be shown in this field. Up to 100 characters.

direction

string

exampleoutbound

Direction of the call, either "inbound" or "outbound".

from

string

example447700900001

SMS sent from this phone number. The value specified by the Customer in "from" parameter in SMS API request (can be numeric, alpha-numeric or short code)

string

example447700900000

SMS sent to this phone number. In other words, the destination phone number.

forced_from

string

example44770090045

The number used instead of "from" field by Vonage, but only if there are any special routing rules were applied. It will be empty if not applicable (e.g. "").

changed_from

string

exampleNXSMS

The number used instead of "from" field by Vonage, but only if if Number Pools API was used or if routing rules were changed due to compliance reasons. It will be empty if not applicable (e.g. "").

concatenated

string

exampleFALSE

Indicates whether the SMS was split up into multiple parts (due to its length). The field will be available in the report if Reports API were called with the parameter show_concatenated= "true".

message_body

string

exampleHello World!

Body of the message sent. Only present if include_message parameter is set to true.

network

string

example12345

The network code of the destination phone number. Taken from a carrier lookup (or sometimes the numbering plan), and always a master network code. Usually an MCC/MNC but sometimes alpha e.g US-FIXED

network_name

string

exampleOrange Polska S.A.

The name of the network code

country

string

examplePL

The ISO two letter country code to which the network code belongs in the numbering plan

country_name

string

examplePoland

Country name of the country code

date_received

string(date-time)

example{}

Date when Vonage received SMS API request. Format: yyyy-mm-ddThh:mm:ss±hh:mm Time zone: UTC

date_finalized

string(date-time)

example{}

Date when the SMS message reached its final state. Format: yyyy-mm-ddThh:mm:ss±hh:mm Time zone: UTC

latency

string

example42

Latency of the request in ms

status

string

exampledelivered

The state of SMS message in the delivery process. The statuses are according to SMS Delivery statuses explained on Developer portal and in KB article

error_code

string

example0

The status of the SMS request. Will be a non 0 value if there has been an error, or if the status is unknown. See the Delivery Receipt documentation for more details

error_code_description

string

exampleDelivered

Description of the error code of the SMS request. See the Delivery Receipt documentation for more details

currency

string

exampleEUR

Currency of the price of the SMS request.

total_price

string

example0.036

Price of the SMS request

price

string

example0.036

Price per message

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the record in the report

dcs

string

example0

DCS (Data Coding Scheme) is the encoding with which the message body was delivered to the phone. It is according to the value of the "type" parameter used in SMS API request. DCS = 0 (the default value) is for GSM/text. DCS = 8 is for unicode text messages DCS = 4 is for binary text messages

validity_period

string

example240210092938000+

The validity period of the SMS message used in the "ttl" parameter of the SMS request. The duration in milliseconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours.

ip_address

string

example12.23.456.111

The IP address of the Customer's server calling SMS API.

udh

string

example50003940401

User Data Header, available if SMS was split up into multiple parts (due to its length). Pay attention: UDHs are not unique values. An 8 bit concatenation UDH is always going to start from "050003", then the reference e.g. "00" and then the total parts and part index e.g. "0201" for the first part of a two part message

limit

integer

Maximum number of records requested

ids_not_found

string

Comma-separated list of record IDs that were not found (for ID-based queries)

Example Response

{
   "_links": {
      "self": {
         "href": "http://example.com"
      },
      "next": {
         "href": "http://example.com"
      }
   },
   "cursor": "string",
   "iv": "string",
   "request_id": "string",
   "request_status": "SUCCESS",
   "received_at": "2019-08-24T14:15:22Z",
   "items_count": 0,
   "records": [
      {
         "account_id": "12aa3456",
         "message_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "account_ref": "customer1234",
         "client_ref": "my-personal-reference",
         "direction": "outbound",
         "from": "447700900001",
         "to": "447700900000",
         "forced_from": "44770090045",
         "changed_from": "NXSMS",
         "concatenated": "FALSE",
         "message_body": "Hello World!",
         "network": "12345",
         "network_name": "Orange Polska S.A.",
         "country": "PL",
         "country_name": "Poland",
         "date_received": {},
         "date_finalized": {},
         "latency": "42",
         "status": "delivered",
         "error_code": "0",
         "error_code_description": "Delivered",
         "currency": "EUR",
         "total_price": "0.036",
         "price": "0.036",
         "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "dcs": "0",
         "validity_period": "240210092938000+",
         "ip_address": "12.23.456.111",
         "udh": "50003940401"
      }
   ],
   "limit": 0,
   "ids_not_found": "string"
}

Errors

The following is a non-exhaustive list of error codes that may occur while using this API.

These codes are in addition to any of our generic error codes.

Code Information

Code	Information
invalid-request-parameters	Description The provided payload is invalid Resolution Modify your request to provide a valid payload
invalid-abort-operation	Description The job is already in a terminated state such as `SUCCESS`, `TRUNCATED`, `FAILED` or `ABORTED`. Resolution None
rate-limit	Description The request was rate limited. Resolution The Reports API supports 5 requests per second when used Asynchronously, and 10 requests per second Synchronously. Slow down your request rate.

invalid-request-parameters

Description

The provided payload is invalid

Resolution

Modify your request to provide a valid payload

invalid-abort-operation

Description

The job is already in a terminated state such as SUCCESS, TRUNCATED, FAILED or ABORTED.

Resolution

None

rate-limit

Description

The request was rate limited.

Resolution

The Reports API supports 5 requests per second when used Asynchronously, and 10 requests per second Synchronously. Slow down your request rate.

Reports API

Reports API

Available Operations

Get Async Report Status

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response»SMS report response with SMS-specific request parameters

Abort Async Report

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response»SMS report response with SMS-specific request parameters

Search Async Reports

Authentication

Query Parameters

Responses

Create an asynchronous report

Authentication

Request Body Content Typeapplication/json

Example Request»SMS API request parameters

Responses Content Typeapplication/json

Example Response»SMS report response with SMS-specific request parameters

Create Sync Report

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Errors

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json