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 monthly subscription option if you are going to retrieve more than 1M records per month.

Download OpenAPI Specification
Available Operations

Load records synchronously

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

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

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Query Parameters

product
string

The product to return records for.

Must be one of:SMSSMS-TRAFFIC-CONTROLVOICE-CALLVOICE-FAILEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLASRAMDVERIFY-APIVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2CONVERSATION-EVENTCONVERSATION-MESSAGEMESSAGESVIDEO-APINETWORK-API-EVENTREPORTS-USAGE
account_id
string

The account ID (API key) you wish to search for. This can differ from the API key in the authorization header because some accounts can request reports for other accounts, e.g. a primary account owner wants to create a report for one of its subaccounts.

date_start
string

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when reports should begin. It filters on the time the API call was received by Vonage and corresponds to the field date_received (date_start for Voice) in the report file. It is inclusive, i.e. the provided value is less than or equal to the value in the field date_received (date_start for Voice) in the CDR.
If unspecified, defaults to seven days ago.

date_end
string

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z) for when report should end. It is exclusive, i.e. the provided value is strictly greater than the value in the field date_received in the CDR.
If unspecified, defaults to the current time.

cursor
string

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

iv
string

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

id
string

The UUID of the message or call to be searched for. You can specify a comma-separated list of UUIDs (maximum 20 UUIDs). If UUIDs are not found they are listed in the response in the ids_not_found field. When the id parameter is specified, only the following parameters are accepted: product, account_id, direction, include_message and show_concatenated.

direction
string

Direction of the communication, either inbound (received by our services), or outbound (originated from our services). Required for products SMS and MESSAGES. Optional for VOICE-CALL,VOICE-FAILED, ASR.

Must be one of:inboundoutbound
status
string

Status of the event. Optional for SMS, CONVERSATION-EVENT, IN-APP-VOICE, MESSAGES, VOICE-CAL, VERIFY-V2, NUMBER-INSIGHT-V2.

from
string

Sender ID/number. Optional for SMS, MESSAGES, VOICE-CALL, VOICE-FAILED, ASR.

to
string

Recipient phone number. Optioanl for SMS, VOICE-CALL, VOICE-FAILED, ASR, MESSAGES, VERIFY-API, VERIFY-V2.

country
string

Country code filter. Optional for SMS, VOICE-CALL, VOICE-FAILED, ASR, MESSAGES, VERIFY-API, VERIFY-V2, NUMBER-INSIGHT, NUMBER-INSIGHT-V2, NETWORK-API-EVENT.

network
string

Mobile network code filter. Optional for SMS, VOICE-CALL, VOICE-FAILED, ASR, VERIFY-API, VERIFY-V2, NUMBER-INSIGHT, NUMBER-INSIGHT-V2, NETWORK-API-EVENT.

client_ref
string

Client reference. Optional for SMS, MESSAGES, VERIFY-API, VERIFY-V2, NUMBER-INSIGHT, NUMBER-INSIGHT-V2, CONVERSATION-EVENT, CONVERSATION-MESSAGE, IN-APP-VOICE, VIDEO-API, NETWORK-API-EVENT.

number
string

Phone number for lookup. Optional for NUMBER-INSIGHT, NUMBER-INSIGHT-V2.

locale
string

Language/locale. Optional for VERIFY-API, VERIFY-V2.

include_message
boolean

Include message content in response. Optional for SMS, MESSAGES.

show_concatenated
boolean

A boolean flag that determines whether the concatenated field is included in the report. Optional for SMS with direction=outbound.

account_ref
string

Account reference. Optional for SMS, MESSAGES.

call_id
string

Unique call identifier. Optional for VOICE-CALL, VOICE-FAILED, ASR, WEBSOCKET-CALL.

leg_id
string

Unique leg identifier for the call. Optional for IN-APP-VOICE.

provider
string

Messaging provider. Optional for MESSAGES.

Must be one of:whatsappsmsmmsmessengerviber_service_msginstagramrcs
number_type
string

Number type. Optional for VERIFY-API.

channel
string

Verification channel. Optional for VERIFY-V2.

Must be one of:v2emailsilent_auth
parent_request_id
string

Filter by parent request ID, which correlates v2 verification requests with their associated email or silent_auth events. Optional for VERIFY-V2.

request_type
string

Type of Request. Optional for NUMBER-INSIGHT-V2, NETWORK-API-EVENT.

risk
string

Risk assessment level. Optional for NUMBER-INSIGHT-V2.

swapped
boolean

Whether the number has been ported/swapped. Optional for NUMBER-INSIGHT-V2.

conversation_id
string

Conversation ID. Optional for CONVERSATION-EVENT, CONVERSATION-MESSAGE, IN-APP-VOICE.

session_id
string

Session ID. Optional for VIDEO-API.

meeting_id
string

Meeting ID. Optional for VIDEO-API.

product_name
string

Product name for Network API event. Optional for NETWORK-API-EVENT.

request_session_id
string

Session ID for Network API. Optional for NETWORK-API-EVENT.

product_path
string

API path. Optional for NETWORK-API-EVENT.

correlation_id
string

Correlation ID. Optional for NETWORK-API-EVENT.

Responses
Content Type
application/json

Report data retrieved successfully

One Of
_links
object

HAL links for navigation and pagination. The next link is only present if more records are available.

self
object
href
string(uri)
examplehttps://api.nexmo.com/v2/reports/sms/records?product=SMS&direction=outbound&date_start=2024-02-01T00:00:00Z&date_end=2024-02-02T00:00:00Z
next
object

Link to the next page of records. Present only if pagination is applicable.

href
string(uri)
examplehttps://api.nexmo.com/v2/reports/sms/records?product=SMS&direction=outbound&cursor=MTY0OTQ3ODAwMDAwMA
cursor
string
exampleMTY0OTQ3ODAwMDAwMA

Cursor for paginating results. Present only if pagination is applicable.

iv
string
example8a2c4e6f-12d3-45b6-78c9-0a1b2c3d4e5f

Initialization vector for cursor processing. Present only if pagination is applicable.

request_id
string
examplea91b34c2-5d98-4c0e-8f23-a6b1c7d4e9f0

Unique ID associated with this synchronous request.

request_status
string
exampleSUCCESS

The result status of the request.

Must be one of:SUCCESSTRUNCATED
received_at
string
example2024-02-07T14:22:08+00:00

Timestamp when the request was processed by the Reports API.

items_count
integer(int64)
example50

The number of records returned in this page/response.

ids_not_found
string
exampleid-missing-1,id-missing-2

A comma-separated list of IDs if the request was made by ID and some were not found.

product
string
exampleSMS
Must be one of:SMS
records
array

List of outbound SMS records

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. 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, 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 request (can be numeric, alpha-numeric or short code)

to
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.

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.

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
example2024-02-02T13:50:00+00:00

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

date_finalized
string
example2024-02-02T13:50:00+00:00

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 final status of the message delivery, derived from the Delivery Receipt (DLR) provided by the carrier/supplier. The statuses are according to "SMS Delivery statuses" explained on Developer portal and in KB article

error_code
string
example0

The specific code indicating the result of the Vonage handoff to the supplier. A code of 0 typically indicates a successful handoff. See the Delivery Receipt documentation for more details

error_code_description
string
exampleDelivered

A short text explanation for the value in error_code. This confirms the immediate status of the message handover from Vonage to the destination carrier/supplier. See the Delivery Receipt documentation for more details

currency
string

Currency of the price of the SMS request. Always returns an empty string.

total_price
string
example0.036

Price of the SMS request

id
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 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.

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

workflow_id
string
example3TcNjgZvTgbJ41bJGMiHQxf7s6UPsKUEnkhyY

Unique ID for the failover workflow.

Example Response»SMS (Outbound)

{
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/sms/records?product=SMS&direction=outbound&date_start=2024-02-01T00:00:00Z&date_end=2024-02-02T00:00:00Z"
      },
      "next": {
         "href": "https://api.nexmo.com/v2/reports/sms/records?product=SMS&direction=outbound&cursor=MTY0OTQ3ODAwMDAwMA"
      }
   },
   "cursor": "MTY0OTQ3ODAwMDAwMA",
   "iv": "8a2c4e6f-12d3-45b6-78c9-0a1b2c3d4e5f",
   "request_id": "a91b34c2-5d98-4c0e-8f23-a6b1c7d4e9f0",
   "request_status": "SUCCESS",
   "received_at": "2024-02-07T14:22:08+00:00",
   "items_count": 50,
   "ids_not_found": "id-missing-1,id-missing-2",
   "product": "SMS",
   "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": "2024-02-02T13:50:00+00:00",
         "date_finalized": "2024-02-02T13:50:00+00:00",
         "latency": "42",
         "status": "delivered",
         "error_code": "0",
         "error_code_description": "Delivered",
         "currency": "",
         "total_price": "0.036",
         "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "dcs": "0",
         "validity_period": "240210092938000+",
         "ip_address": "12.23.456.111",
         "udh": "50003940401",
         "workflow_id": "3TcNjgZvTgbJ41bJGMiHQxf7s6UPsKUEnkhyY"
      }
   ]
}

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. The API returns a combination of the standard required fields and those specified in the input payload.

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

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Request Body
Content Type
application/json

One Of
product
string
Required
exampleSMS

Product type for the report

Must be one of:SMSSMS-TRAFFIC-CONTROLVOICE-CALLVOICE-FAILEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLASRAMDVERIFY-APIVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2CONVERSATION-EVENTCONVERSATION-MESSAGEMESSAGESVIDEO-APINETWORK-API-EVENTREPORTS-USAGESMS
account_id
string
Required
example12aa3456

The account ID (API key) you wish to search for. This can differ from the API key in the authorization header because some accounts can request reports for other accounts, e.g. a primary account owner wants to create a report for one of its subaccounts.

date_start
string
example2024-02-02T13:50:00+00:00

Start date for the report (ISO 8601 format). Not mandatory for async requests - defaults to CURRENT_TIME-7D if not provided.

date_end
string
example2024-02-07T14:22:08+00:00

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

include_subaccounts
boolean
exampletrue

Include data from sub-accounts

callback_url
string(uri)
examplehttps://example.com/webhook

Webhook URL for completion notifications

direction
string
Required
exampleoutbound

Direction of the communication.

Must be one of:inboundoutbound
status
string
exampledelivered

The final status of the message delivery filter

Must be one of:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered
from
string
example447700900001

SMS sent from this phone number. The value specified by the Customer in from parameter in SMS request

to
string
example447700900000

Recipient phone number

country
string
examplePL

The ISO two letter country code

network
string
example12345

The network code of the destination phone number

client_ref
string
examplemy-personal-reference

The optional custom reference value

account_ref
string
examplecustomer1234

Account reference.

include_message
boolean
exampletrue

Determines whether the message body is included.

show_concatenated
boolean

A boolean flag that determines whether the concatenated field is included in the report

Example Request»SMS

{
   "product": "SMS",
   "account_id": "12aa3456",
   "date_start": "2024-02-02T13:50:00+00:00",
   "date_end": "2024-02-07T14:22:08+00:00",
   "include_subaccounts": true,
   "callback_url": "https://example.com/webhook",
   "direction": "outbound",
   "status": "delivered",
   "from": "447700900001",
   "to": "447700900000",
   "country": "PL",
   "network": "12345",
   "client_ref": "my-personal-reference",
   "account_ref": "customer1234",
   "include_message": true,
   "show_concatenated": false
}

Responses
Content Type
application/json

Report creation request accepted

One Of
request_id
string
Required
exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status
string
Required
examplePENDING

Status of the request.

Must be one of:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED
receive_time
string
Required
example2024-02-07T14:22:08+00:00

Time at which the request of the report was received.

start_time
string
Required
example2024-02-07T14:22:10+00:00

Time at which the report processing of the report has started.

items_count
integer(int64)
Required
example1523

Number of records

_links
object
Required

HAL links

self
object
href
string(uri)
examplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
download_report
object
href
string(uri)
examplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Download URL

product
string
Required
exampleSMS

Product type for the report

Must be one of:SMSSMS-TRAFFIC-CONTROLVOICE-CALLVOICE-FAILEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLASRAMDVERIFY-APIVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2CONVERSATION-EVENTCONVERSATION-MESSAGEMESSAGESVIDEO-APINETWORK-API-EVENTREPORTS-USAGESMS
account_id
string
Required
example12aa3456

The account ID (API key) you wish to search for. This can differ from the API key in the authorization header because some accounts can request reports for other accounts, e.g. a primary account owner wants to create a report for one of its subaccounts.

date_start
string
example2024-02-02T13:50:00+00:00

Start date for the report (ISO 8601 format). Not mandatory for async requests - defaults to CURRENT_TIME-7D if not provided.

date_end
string
example2024-02-07T14:22:08+00:00

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

include_subaccounts
boolean
exampletrue

Include data from sub-accounts

callback_url
string(uri)
examplehttps://example.com/webhook

Webhook URL for completion notifications

direction
string
Required
exampleoutbound

Direction of the communication.

Must be one of:inboundoutbound
status
string
exampledelivered

The final status of the message delivery filter

Must be one of:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered
from
string
example447700900001

SMS sent from this phone number. The value specified by the Customer in from parameter in SMS request

to
string
example447700900000

Recipient phone number

country
string
examplePL

The ISO two letter country code

network
string
example12345

The network code of the destination phone number

client_ref
string
examplemy-personal-reference

The optional custom reference value

account_ref
string
examplecustomer1234

Account reference.

include_message
boolean
exampletrue

Determines whether the message body is included.

show_concatenated
boolean

A boolean flag that determines whether the concatenated field is included in the report

Example Response»SMS

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "request_status": "PENDING",
   "receive_time": "2024-02-07T14:22:08+00:00",
   "start_time": "2024-02-07T14:22:10+00:00",
   "items_count": 1523,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      },
      "download_report": {
         "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   },
   "product": "SMS",
   "account_id": "12aa3456",
   "date_start": "2024-02-02T13:50:00+00:00",
   "date_end": "2024-02-07T14:22:08+00:00",
   "include_subaccounts": true,
   "callback_url": "https://example.com/webhook",
   "direction": "outbound",
   "status": "delivered",
   "from": "447700900001",
   "to": "447700900000",
   "country": "PL",
   "network": "12345",
   "client_ref": "my-personal-reference",
   "account_ref": "customer1234",
   "include_message": true,
   "show_concatenated": false
}

Get status of report

Retrieve the status and details of an asynchronous report using its report ID. Note that there is a data retention period of 4 days, so reports older than 4 days will not be able to be retrieved.

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

Authentication

KeyDescriptionWhereExample
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 (request_id in response).

Responses
Content Type
application/json

Report details retrieved successfully

One Of
request_id
string
Required
exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status
string
Required
examplePENDING

Status of the request.

Must be one of:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED
receive_time
string
Required
example2024-02-07T14:22:08+00:00

Time at which the request of the report was received.

start_time
string
Required
example2024-02-07T14:22:10+00:00

Time at which the report processing of the report has started.

items_count
integer(int64)
Required
example1523

Number of records

_links
object
Required

HAL links

self
object
href
string(uri)
examplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
download_report
object
href
string(uri)
examplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Download URL

product
string
Required
exampleSMS

Product type for the report

Must be one of:SMSSMS-TRAFFIC-CONTROLVOICE-CALLVOICE-FAILEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLASRAMDVERIFY-APIVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2CONVERSATION-EVENTCONVERSATION-MESSAGEMESSAGESVIDEO-APINETWORK-API-EVENTREPORTS-USAGESMS
account_id
string
Required
example12aa3456

The account ID (API key) you wish to search for. This can differ from the API key in the authorization header because some accounts can request reports for other accounts, e.g. a primary account owner wants to create a report for one of its subaccounts.

date_start
string
example2024-02-02T13:50:00+00:00

Start date for the report (ISO 8601 format). Not mandatory for async requests - defaults to CURRENT_TIME-7D if not provided.

date_end
string
example2024-02-07T14:22:08+00:00

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

include_subaccounts
boolean
exampletrue

Include data from sub-accounts

callback_url
string(uri)
examplehttps://example.com/webhook

Webhook URL for completion notifications

direction
string
Required
exampleoutbound

Direction of the communication.

Must be one of:inboundoutbound
status
string
exampledelivered

The final status of the message delivery filter

Must be one of:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered
from
string
example447700900001

SMS sent from this phone number. The value specified by the Customer in from parameter in SMS request

to
string
example447700900000

Recipient phone number

country
string
examplePL

The ISO two letter country code

network
string
example12345

The network code of the destination phone number

client_ref
string
examplemy-personal-reference

The optional custom reference value

account_ref
string
examplecustomer1234

Account reference.

include_message
boolean
exampletrue

Determines whether the message body is included.

show_concatenated
boolean

A boolean flag that determines whether the concatenated field is included in the report

Example Response»SMS

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "request_status": "PENDING",
   "receive_time": "2024-02-07T14:22:08+00:00",
   "start_time": "2024-02-07T14:22:10+00:00",
   "items_count": 1523,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      },
      "download_report": {
         "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   },
   "product": "SMS",
   "account_id": "12aa3456",
   "date_start": "2024-02-02T13:50:00+00:00",
   "date_end": "2024-02-07T14:22:08+00:00",
   "include_subaccounts": true,
   "callback_url": "https://example.com/webhook",
   "direction": "outbound",
   "status": "delivered",
   "from": "447700900001",
   "to": "447700900000",
   "country": "PL",
   "network": "12345",
   "client_ref": "my-personal-reference",
   "account_ref": "customer1234",
   "include_message": true,
   "show_concatenated": false
}

Cancel the execution of a report

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

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

Authentication

KeyDescriptionWhereExample
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 (request_id in response).

Responses
Content Type
application/json

Report aborted successfully

One Of
request_id
string
Required
exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status
string
Required
examplePENDING

Status of the request.

Must be one of:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED
receive_time
string
Required
example2024-02-07T14:22:08+00:00

Time at which the request of the report was received.

start_time
string
Required
example2024-02-07T14:22:10+00:00

Time at which the report processing of the report has started.

items_count
integer(int64)
Required
example1523

Number of records

_links
object
Required

HAL links

self
object
href
string(uri)
examplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
download_report
object
href
string(uri)
examplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Download URL

product
string
Required
exampleSMS

Product type for the report

Must be one of:SMSSMS-TRAFFIC-CONTROLVOICE-CALLVOICE-FAILEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLASRAMDVERIFY-APIVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2CONVERSATION-EVENTCONVERSATION-MESSAGEMESSAGESVIDEO-APINETWORK-API-EVENTREPORTS-USAGESMS
account_id
string
Required
example12aa3456

The account ID (API key) you wish to search for. This can differ from the API key in the authorization header because some accounts can request reports for other accounts, e.g. a primary account owner wants to create a report for one of its subaccounts.

date_start
string
example2024-02-02T13:50:00+00:00

Start date for the report (ISO 8601 format). Not mandatory for async requests - defaults to CURRENT_TIME-7D if not provided.

date_end
string
example2024-02-07T14:22:08+00:00

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

include_subaccounts
boolean
exampletrue

Include data from sub-accounts

callback_url
string(uri)
examplehttps://example.com/webhook

Webhook URL for completion notifications

direction
string
Required
exampleoutbound

Direction of the communication.

Must be one of:inboundoutbound
status
string
exampledelivered

The final status of the message delivery filter

Must be one of:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered
from
string
example447700900001

SMS sent from this phone number. The value specified by the Customer in from parameter in SMS request

to
string
example447700900000

Recipient phone number

country
string
examplePL

The ISO two letter country code

network
string
example12345

The network code of the destination phone number

client_ref
string
examplemy-personal-reference

The optional custom reference value

account_ref
string
examplecustomer1234

Account reference.

include_message
boolean
exampletrue

Determines whether the message body is included.

show_concatenated
boolean

A boolean flag that determines whether the concatenated field is included in the report

Example Response»SMS

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "request_status": "PENDING",
   "receive_time": "2024-02-07T14:22:08+00:00",
   "start_time": "2024-02-07T14:22:10+00:00",
   "items_count": 1523,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      },
      "download_report": {
         "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   },
   "product": "SMS",
   "account_id": "12aa3456",
   "date_start": "2024-02-02T13:50:00+00:00",
   "date_end": "2024-02-07T14:22:08+00:00",
   "include_subaccounts": true,
   "callback_url": "https://example.com/webhook",
   "direction": "outbound",
   "status": "delivered",
   "from": "447700900001",
   "to": "447700900000",
   "country": "PL",
   "network": "12345",
   "client_ref": "my-personal-reference",
   "account_ref": "customer1234",
   "include_message": true,
   "show_concatenated": false
}

Get report data

Download a zipped archive of the rendered report. The file is available for download for 72 hours.
The zip file will be named <PRODUCT>_<REPORT_ID>.zip
The csv file in the zip archive will be named as report_<PRODUCT>_<ACCOUNT_ID>_<DATE>.csv the date will be formatted as yyyyMMdd.

gethttps://api.nexmo.com/v3/media/:file_id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

file_id
string
Required
exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the file.

Responses
Content Type
application/octet-stream

Zip file containing CSV files

report
array

The report in CSV format inside the zip archive.

Any Of
acc
string
example12aa3456

Account authenticated when making Reports API call. Not necessarily the same as account_id for which reports data is requested.

product_type
string
examplereports

Report's API product. Always reports.

date_received
string
example2024-02-02T13:50:00+00:00

Date when report was requested by Customer by calling Reports API. Format: yyyy-mm-ddThh:mm:ss±hh:mm Time zone: UTC

date_started
string
example2024-02-02T13:50:00+00:00

Date when Reports API started processing the request. Format: yyyy-mm-ddThh:mm:ss±hh:mm Time zone: UTC

date_finished
string
example2024-02-02T13:50:00+00:00

Date when Reports API finished processing the request. Format: yyyy-mm-ddThh:mm:ss±hh:mm Time zone: UTC

status
string
exampleSUCCESS

Status of the report's request

account_id
string
example12aa3456

The account ID (API key) for which the report data is generated.

master_account_id
string
example88aa3456

Master account ID of requested account. If Master account is not available, the field will be equal to account_id.

is_charged
string
exampleTRUE

Would be TRUE if the report request was charged, otherwise - FALSE

request_params
object

Base parameters for all report requests

product
string
Required
exampleSMS

Product type for the report

Must be one of:SMSSMS-TRAFFIC-CONTROLVOICE-CALLVOICE-FAILEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLASRAMDVERIFY-APIVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2CONVERSATION-EVENTCONVERSATION-MESSAGEMESSAGESVIDEO-APINETWORK-API-EVENTREPORTS-USAGE
account_id
string
Required
example12aa3456

The account ID (API key) you wish to search for. This can differ from the API key in the authorization header because some accounts can request reports for other accounts, e.g. a primary account owner wants to create a report for one of its subaccounts.

date_start
string
example2024-02-02T13:50:00+00:00

Start date for the report (ISO 8601 format). Not mandatory for async requests - defaults to CURRENT_TIME-7D if not provided.

date_end
string
example2024-02-07T14:22:08+00:00

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

job_type
string
exampleASYNC_JOB

This is either sync or async Reports API request. Possible values: SYNC_JOB_FROM_ID, SYNC_JOB_FROM_DATES, ASYNC_JOB

requested_product
string
exampleSMS

Product requested in the report.

items_written
integer
example134

Number of CDRs/records returned in the report

price
number
example0.0004

The price for the CDR in the report (individual record in the report)

currency
string
exampleEUR

Currency of the price of the report

total_price
number
example120

The total price for the whole report

id
string
exampleab12345678c90-b1234-ba78-f1c3e400f28d

The unique id of the record in the report

Example Response

Example preview is currently not supported for content type: application/octet-stream

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.

CodeInformation
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.