Available Operations
 
 

Nexmo Reports API

Beta

Nexmo's Reports API allows you to request a report of activity on your Nexmo account.

Depending on your query pattern, you can choose from one of the two versions of Reports API: asynchronous and synchronous. Asynchronous version is optimized for infrequent and large data queries (from several records to tens of millions). 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.

Nexmo recommends to limit asynchronous queries to a maximum of 20 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.

Available Operations:

Load records synchronously

Fetch usage data synchronously

GET https://api.nexmo.com/v2/reports/records
Host https://api.nexmo.com
GET /v2/reports/records

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Query Parameter

account_id
string | Required

The account for which the list of reports will be queried.

product
string | Required

The product to return records for

Must be one of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

Must be one of: inbound or outbound
id
string

The UUID of the message or call to be searched for.

If you specify id, you must not specify status, date_start or date_end.

date_start
string (date)

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 Nexmo 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 you provide this, you must provide date_end and must not provide id.

date_end
string (date)

Must be no more than 24 hours later than date_start

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 you provide this, you must provide date_start and must not provide id.

include_message
boolean

Include the message contents in the records. Only applicable for use with products SMS and MESSAGES, where it is optional.

Must be one of: true or false
type
string

The event type to search for. Only used, and is required, when product is CONVERSATIONS.

Must be one of: ip-voice or cs-custom-event
status
string

The SMS status to search for. Optional where product is SMS.

Must be one of: delivered, expired, failed, rejected, accepted, buffered, unknown or deleted

Responses

200 OK
request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array

Records in JSON format

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array

Records in JSON format

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array of objects

Records in JSON format

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.

call_id
string

UUID of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

network
string

Network used to send the request.

network_name
string

Name of the network used to send the request.

country
string

Country where the request was sent.

country_name
string

Country name where the request was sent.

date_start
string

Date of the start of the call.

date_end
string

Date of the end of the call.

duration
integer

Duration of the call in seconds.

status
string

Search only for voice call with the corresponding status.

One of: started, ringing, answered, machine, completed, timeout, failed, rejected, cancelled or busy
status_description
string

Description of the status of the call.

currency
string

Currency of the price of the request.

price
number

Price of the request.

total_price
number

Total price of the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array of objects

Records in JSON format

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.

request_id
string

UUID of the request.

from
string

Request from this number.

to
string

Request to this number.

locale
string

Locale used for the TTS.

number_type
string

Type of phone number to which requests are sent.

network
string

Network used to send the request.

network_name
string

Name of the network used to send the request.

country
string

Country where the request was sent.

country_name
string

Country name where the request was sent.

date_received
string

Date of the request.

date_finalized
string

Date when the request was finalized.

first_event_date
string

Date of the first verify event.

last_event_date
string

Date of the last verify event.

verify_status
string

Status of the verify request.

sms_event_count
integer

Number of sms sent for this verify request.

tts_event_count
integer

Number of tts sent for this verify request.

currency
string

Currency of the price of the request.

pricing_model
string

Pricing model used for this request.

price
number

Price of the request.

estimated_price
string

Estimated price of the verify request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array of objects

Records in JSON format

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.

request_id
string

UUID of the request.

product_type
string

Type of Number Insight request.

number
string

Number looked up for this request.

date_received
string

Date of the request.

status
string

Status of the Number Insight request.

response_code
string

Response code of the Number Insight request.

network
string

Network of the looked up number.

network_name
string

Network name of the looked up number.

network_type
string

Network type of the looked up number.

country
string

Country of the looked up number.

country_name
string

Country name of the looked up number.

valid
string

Is the looked up number valid.

ported
string

Is the looked up number ported.

reachable
string

Is the looked up number reachable.

first_name
string

First name of the owner of the looked up number.

last_name
string

Last name of the owner of the looked up number.

currency
string

Currency of the price of the request.

total_price
number

Total price of the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array of objects

Records in JSON format

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.

message_id
string

Id of the request.

client_ref
string

Search for messages with this client_ref.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

message_body
string

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

country
string

Country where the request was sent.

country_name
string

Country name where the request was sent.

provider
string

Provider of the message.

date_received
string

Date of the request.

date_finalized
string

Date when the request was finalized.

latency
integer

Latency of the request in ms.

status
string

Status of the message.

error_code
string

Error code of the message.

currency
string

Currency of the price of the request.

total_price
number

Total price of the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array of objects

Records in JSON format

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.

message_id
string

Id of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

message_body
string

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

provider
string

Provider of the message.

date_received
string

Date of the request.

currency
string

Currency of the price of the request.

total_price
number

Total price of the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array of objects

Records in JSON format

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.

request_id
string

UUID of the request.

application_id
string

Search only for requests attached to a particular Application ID.

conversation_id
string

Search only for Voice calls attached to this particular Conversation. This should include the "CON-" prefix.

user_id
string

User ID of the caller.

leg_id
string

Id of the leg.

date_start
string

Date of the start of the call.

date_end
string

Date of the end of the call.

duration
integer

Duration of the call in seconds.

status
string

Status of the conversation evnet.

currency
string

Currency of the price of the request.

price
number

Price of the request.

total_price
number

Total price of the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
received_at
string

Time at which the report request was received by the service.

price
number

Price of the request.

currency
string

Currency of the price of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_message
boolean

Include the text of messages in the report.

items_count
integer

The number of returned records

records
array of objects

Records in JSON format

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.

call_id
string

UUID of the request.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

call_date_start
string

Date of the start of the call.

date_start
string

Date of the start of the call.

date_end
string

Date of the end of the call.

duration
integer

Duration of the call in seconds.

status
string

Search only for ASR with corresponding status.

One of: ok or error
status_description
string

ASR error message.

currency
string

Currency of the price of the request.

price
number

Price of the request.

total_price
number

Total price of the request.

Example Responses

200 403 422
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "true",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "message_id": "0000000A",
      "client_ref": "abc123",
      "direction": "outbound",
      "from": "441234567890",
      "to": "441234567890",
      "network": "23415",
      "network_name": "Vodafone Limited",
      "country": "FR",
      "country_name": "France",
      "date_received": "2019-06-28T15:30:00+0000",
      "date_finalized": "2019-06-28T15:30:00+0000",
      "latency": "42",
      "status": "delivered",
      "error_code": "0",
      "error_code_description": "Delivered",
      "currency": "EUR",
      "total_price": "0.042",
      "message_body": "This is a text message"
    }
  ]
}
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "true",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "message_id": "0000000A",
      "direction": "inbound",
      "from": "441234567890",
      "to": "441234567890",
      "network": "23415",
      "network_name": "Vodafone Limited",
      "country": "FR",
      "country_name": "France",
      "date_received": "2019-06-28T15:30:00+0000",
      "currency": "EUR",
      "total_price": "0.042",
      "message_body": "This is a text message"
    }
  ]
}
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "false",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "call_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "direction": "outbound",
      "from": "441234567890",
      "to": "441234567890",
      "network": "23415",
      "network_name": "Vodafone Limited",
      "country": "FR",
      "country_name": "France",
      "date_start": "2019-06-28T15:30:00+0000",
      "date_end": "2019-06-28T15:30:00+0000",
      "duration": "42",
      "status": "started",
      "status_description": "The call was successful.",
      "currency": "EUR",
      "price": "0.042",
      "total_price": "0.042"
    }
  ]
}
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "false",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "from": "441234567890",
      "to": "441234567890",
      "locale": "en-gb",
      "number_type": "MOBILE",
      "network": "23415",
      "network_name": "Vodafone Limited",
      "country": "FR",
      "country_name": "France",
      "date_received": "2019-06-28T15:30:00+0000",
      "date_finalized": "2019-06-28T15:30:00+0000",
      "first_event_date": "2019-06-28T15:30:00+0000",
      "last_event_date": "2019-06-28T15:30:00+0000",
      "verify_status": "SUCCESS",
      "sms_event_count": "1",
      "tts_event_count": "1",
      "currency": "EUR",
      "pricing_model": "0",
      "price": "0.042",
      "estimated_price": "0.042"
    }
  ]
}
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "false",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "product_type": "HLR-LOOKUP",
      "number": "HLR-LOOKUP",
      "date_received": "2019-06-28T15:30:00+0000",
      "status": "Success",
      "response_code": "0",
      "network": "23415",
      "network_name": "Vodafone Limited",
      "network_type": "mobile",
      "country": "mobile",
      "country_name": "mobile",
      "valid": "valid",
      "ported": "ported",
      "reachable": "reachable",
      "first_name": "valid",
      "last_name": "valid",
      "currency": "EUR",
      "total_price": "0.042"
    }
  ]
}
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "true",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "message_id": "0000000A",
      "client_ref": "abc123",
      "direction": "outbound",
      "from": "441234567890",
      "to": "441234567890",
      "message_body": "This is a text message",
      "country": "FR",
      "country_name": "France",
      "provider": "whatsapp",
      "date_received": "2019-06-28T15:30:00+0000",
      "date_finalized": "2019-06-28T15:30:00+0000",
      "latency": "42",
      "status": "submitted",
      "error_code": "1300",
      "currency": "EUR",
      "total_price": "0.042"
    }
  ]
}
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "false",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "message_id": "0000000A",
      "direction": "outbound",
      "from": "441234567890",
      "to": "441234567890",
      "message_body": "This is a text message",
      "provider": "whatsapp",
      "date_received": "2019-06-28T15:30:00+0000",
      "currency": "EUR",
      "total_price": "0.042"
    }
  ]
}
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "false",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "application_id": "abc123",
      "conversation_id": "CON-abc123",
      "user_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "leg_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "date_start": "2019-06-28T15:30:00+0000",
      "date_end": "2019-06-28T15:30:00+0000",
      "duration": "42",
      "status": "0",
      "currency": "EUR",
      "price": "0.042",
      "total_price": "0.042"
    }
  ]
}
{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=SMS&direction=outbound&date_start=2020-03-05T13%3A00%3A00Z&date_end=2020-03-05T14%0A00%3A00Z&account_id=abcdef01"
    }
  },
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "received_at": "2019-06-28T15:30:00+0000",
  "price": "0.042",
  "currency": "EUR",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_message": "false",
  "items_count": 2,
  "records": [
    {
      "account_id": "abcdef01",
      "call_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "direction": "outbound",
      "from": "441234567890",
      "to": "441234567890",
      "call_date_start": "2019-06-28T15:30:00+0000",
      "date_start": "2019-06-28T15:30:00+0000",
      "date_end": "2019-06-28T15:30:00+0000",
      "duration": "42",
      "status": "ok",
      "status_description": "",
      "currency": "EUR",
      "price": "0.042",
      "total_price": "0.042"
    }
  ]
}
{
  "title": "Forbidden",
  "detail": "User not authorized to query the requested data",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "title": "Unprocessable entity",
  "invalid_parameters": [
    {
      "reason": "Missing required parameter",
      "name": "date_end"
    }
  ],
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "title": "Unprocessable entity",
  "invalid_parameters": [
    {
      "reason": "Could not resolve product name. Please use one of the following values [CONVERSATIONS, MESSAGES, NUMBER-INSIGHT, SMS, VERIFY-API, VERIFY-SDK, VOICE-CALL]",
      "name": "product"
    }
  ],
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "type": "https://developer.nexmo.com/api-errors/reports#invalid-filter",
  "title": "Invalid filter",
  "detail": "When using message_id, the following parameters are not supported: [date_start, date_end]",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}

List reports

List reports created by the specified account based on filtered provided.

GET https://api.nexmo.com/v2/reports
Host https://api.nexmo.com
GET /v2/reports

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Query Parameter

account_id
string | Required

The account for which the list of reports will be queried.

status
string | Required

A comma-separated list of report status values. Reports with any of the statuses specified are returned. The values in the comma-seperated list specified for status can be any of PENDING, PROCESSING, SUCCESS, ABORTED, FAILED, TRUNCATED.

date_from
string (date)

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date from which the list of reports will be queried. Format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z.

date_to
string (date)

ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date until which the list of reports will be queried. Format yyyy-mm-ddThh:mm:ss[.sss]±hh:mm or yyyy-mm-ddThh:mm:ss[.sss]Z.

Responses

200 OK
items_count
integer

The number of reports in the list.

string

URI of this search.

reports
array of objects

The list of reports.

Example Responses

200 400 401
{
  "items_count": 1,
  "self_link": "https://api.nexmo.com/v2/reports/",
  "reports": [
    {
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "request_status": "SUCCESS",
      "product": "SMS",
      "account_id": "abcdef01",
      "date_start": "2017-12-01T00:00:00+00:00",
      "date_end": "2018-01-01T00:00:00+00:00",
      "include_subaccounts": "false",
      "callback_url": "https://requestb.in/12345",
      "receive_time": "2019-06-28T15:30:00+0000",
      "start_time": "2019-06-28T15:30:00+0000",
      "_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"
        }
      },
      "items_count": 1,
      "direction": "outbound",
      "status": "delivered",
      "client_ref": "abc123",
      "account_ref": "abc123",
      "include_message": "true",
      "network": "23415",
      "from": "441234567890",
      "to": "441234567890"
    },
    {
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "request_status": "SUCCESS",
      "product": "VOICE-CALL",
      "account_id": "abcdef01",
      "date_start": "2017-12-01T00:00:00+00:00",
      "date_end": "2018-01-01T00:00:00+00:00",
      "include_subaccounts": "false",
      "callback_url": "https://requestb.in/12345",
      "receive_time": "2019-06-28T15:30:00+0000",
      "start_time": "2019-06-28T15:30:00+0000",
      "_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"
        }
      },
      "items_count": 1,
      "direction": "outbound",
      "network": "23415",
      "from": "441234567890",
      "to": "441234567890",
      "status": "started"
    },
    {
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "request_status": "SUCCESS",
      "product": "VERIFY-API",
      "account_id": "abcdef01",
      "date_start": "2017-12-01T00:00:00+00:00",
      "date_end": "2018-01-01T00:00:00+00:00",
      "include_subaccounts": "false",
      "callback_url": "https://requestb.in/12345",
      "receive_time": "2019-06-28T15:30:00+0000",
      "start_time": "2019-06-28T15:30:00+0000",
      "_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"
        }
      },
      "items_count": 1,
      "to": "441234567890",
      "network": "23415"
    },
    {
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "request_status": "SUCCESS",
      "product": "NUMBER-INSIGHT",
      "account_id": "abcdef01",
      "date_start": "2017-12-01T00:00:00+00:00",
      "date_end": "2018-01-01T00:00:00+00:00",
      "include_subaccounts": "false",
      "callback_url": "https://requestb.in/12345",
      "receive_time": "2019-06-28T15:30:00+0000",
      "start_time": "2019-06-28T15:30:00+0000",
      "_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"
        }
      },
      "items_count": 1,
      "number": "441234567890",
      "network": "23415"
    },
    {
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "request_status": "SUCCESS",
      "product": "MESSAGES",
      "account_id": "abcdef01",
      "date_start": "2017-12-01T00:00:00+00:00",
      "date_end": "2018-01-01T00:00:00+00:00",
      "include_subaccounts": "false",
      "callback_url": "https://requestb.in/12345",
      "receive_time": "2019-06-28T15:30:00+0000",
      "start_time": "2019-06-28T15:30:00+0000",
      "_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"
        }
      },
      "items_count": 1,
      "direction": "outbound",
      "from": "441234567890",
      "to": "441234567890",
      "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "include_message": "true"
    },
    {
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "request_status": "SUCCESS",
      "product": "CONVERSATIONS",
      "account_id": "abcdef01",
      "date_start": "2017-12-01T00:00:00+00:00",
      "date_end": "2018-01-01T00:00:00+00:00",
      "include_subaccounts": "false",
      "callback_url": "https://requestb.in/12345",
      "receive_time": "2019-06-28T15:30:00+0000",
      "start_time": "2019-06-28T15:30:00+0000",
      "_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"
        }
      },
      "items_count": 1,
      "type": "ip-voice",
      "conversation_id": "CON-abc123",
      "status": "0"
    },
    {
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "request_status": "SUCCESS",
      "product": "ASR",
      "account_id": "abcdef01",
      "date_start": "2017-12-01T00:00:00+00:00",
      "date_end": "2018-01-01T00:00:00+00:00",
      "include_subaccounts": "false",
      "callback_url": "https://requestb.in/12345",
      "receive_time": "2019-06-28T15:30:00+0000",
      "start_time": "2019-06-28T15:30:00+0000",
      "_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"
        }
      },
      "items_count": 1,
      "direction": "outbound",
      "from": "441234567890",
      "to": "441234567890",
      "status": "ok"
    }
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors/reports#invalid-request-parameters",
  "title": "Invalid request parameter",
  "detail": "Invalid request parameter.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Unauthorized",
  "detail": "You did not provide correct credentials.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}

Create an asynchronous report

Request a report on your account activity

POST https://api.nexmo.com/v2/reports
Host https://api.nexmo.com
POST /v2/reports

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Request body application/json

The parameters of the JSON body will be used to create and filter the report.
The value of the product field will define which product the report will be created for and which parameters are accepted.

product
string | Required

Which product you wish to generate a report for.

Must be one of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
account_id
string | Required

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.

direction
string | Required

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

Must be one of: inbound or outbound
date_start
string (date)

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 Nexmo 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 (date)

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.

include_subaccounts
boolean

Whether to include subaccounts or not.

Must be one of: true or false
callback_url
string (uri)

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

status
string

Search only for sms with the corresponding status.

Must be one of: delivered, expired, failed, rejected, accepted, buffered or unknown
client_ref
string

Search for messages with this client_ref.

account_ref
string

Search for messages with this account_ref.

include_message
boolean

Include the text of messages in the report.

network
string

Network used to send the request.

from
string

Request from this number.

to
string

Request to this number.

product
string | Required

Which product you wish to generate a report for.

Must be one of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
account_id
string | Required

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 (date)

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 Nexmo 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 (date)

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.

include_subaccounts
boolean

Whether to include subaccounts or not.

Must be one of: true or false
callback_url
string (uri)

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

Must be one of: inbound or outbound
network
string

Network used to send the request.

from
string

Request from this number.

to
string

Request to this number.

status
string

Search only for voice call with the corresponding status.

Must be one of: started, ringing, answered, machine, completed, timeout, failed, rejected, cancelled or busy
product
string | Required

Which product you wish to generate a report for.

Must be one of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
account_id
string | Required

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 (date)

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 Nexmo 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 (date)

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.

include_subaccounts
boolean

Whether to include subaccounts or not.

Must be one of: true or false
callback_url
string (uri)

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

to
string

Request to this number.

network
string

Network used to send the request.

product
string | Required

Which product you wish to generate a report for.

Must be one of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
account_id
string | Required

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 (date)

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 Nexmo 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 (date)

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.

include_subaccounts
boolean

Whether to include subaccounts or not.

Must be one of: true or false
callback_url
string (uri)

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

number
string

Search only request for the target number.

network
string

Network used to send the request.

product
string | Required

Which product you wish to generate a report for.

Must be one of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
account_id
string | Required

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.

direction
string | Required

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

Must be one of: inbound or outbound
date_start
string (date)

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 Nexmo 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 (date)

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.

include_subaccounts
boolean

Whether to include subaccounts or not.

Must be one of: true or false
callback_url
string (uri)

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

from
string

Request from this number.

to
string

Request to this number.

id
string

Search only messages with the specified uuid.

include_message
boolean

Include the text of messages in the report.

product
string | Required

Which product you wish to generate a report for.

Must be one of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
account_id
string | Required

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 (date)

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 Nexmo 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 (date)

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.

include_subaccounts
boolean

Whether to include subaccounts or not.

Must be one of: true or false
callback_url
string (uri)

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

type
string

Type of conversation request. Only used, and is required, when product is CONVERSATIONS.

Must be one of: ip-voice or cs-custom-event
conversation_id
string

Search only for Voice calls attached to this particular Conversation. This should include the "CON-" prefix.

status
string

Search only for conversation events with the specified event status.

product
string | Required

Which product you wish to generate a report for.

Must be one of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
account_id
string | Required

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 (date)

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 Nexmo 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 (date)

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.

include_subaccounts
boolean

Whether to include subaccounts or not.

Must be one of: true or false
callback_url
string (uri)

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

Must be one of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

status
string

Search only for ASR with corresponding status.

Must be one of: ok or error

Responses

200 OK
request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
status
string

Search only for sms with the corresponding status.

One of: delivered, expired, failed, rejected, accepted, buffered or unknown
client_ref
string

Search for messages with this client_ref.

account_ref
string

Search for messages with this account_ref.

include_message
boolean

Include the text of messages in the report.

network
string

Network used to send the request.

from
string

Request from this number.

to
string

Request to this number.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
network
string

Network used to send the request.

from
string

Request from this number.

to
string

Request to this number.

status
string

Search only for voice call with the corresponding status.

One of: started, ringing, answered, machine, completed, timeout, failed, rejected, cancelled or busy
request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

to
string

Request to this number.

network
string

Network used to send the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

number
string

Search only request for the target number.

network
string

Network used to send the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

id
string

Search only messages with the specified uuid.

include_message
boolean

Include the text of messages in the report.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

type
string

Type of conversation request. Only used, and is required, when product is CONVERSATIONS.

One of: ip-voice or cs-custom-event
conversation_id
string

Search only for Voice calls attached to this particular Conversation. This should include the "CON-" prefix.

status
string

Search only for conversation events with the specified event status.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

status
string

Search only for ASR with corresponding status.

One of: ok or error

Example Request » SMS

{
  "product": "SMS",
  "account_id": "abcdef01",
  "direction": "outbound"
}
{
  "product": "SMS",
  "account_id": "abcdef01",
  "direction": "outbound",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "status": "delivered",
  "include_message": "true",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890"
}

Example Request » Voice Call

{
  "product": "VOICE-CALL",
  "account_id": "abcdef01"
}
{
  "product": "VOICE-CALL",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "direction": "outbound",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890",
  "status": "started"
}

Example Request » Verify

{
  "product": "VERIFY-API",
  "account_id": "abcdef01"
}
{
  "product": "VERIFY-API",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "to": "441234567890",
  "network": "23415"
}

Example Request » Number Insight

{
  "product": "NUMBER-INSIGHT",
  "account_id": "abcdef01"
}
{
  "product": "NUMBER-INSIGHT",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "number": "441234567890",
  "network": "23415"
}

Example Request » Messages

{
  "product": "MESSAGES",
  "account_id": "abcdef01",
  "direction": "outbound"
}
{
  "product": "MESSAGES",
  "account_id": "abcdef01",
  "direction": "outbound",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "from": "441234567890",
  "to": "441234567890",
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "include_message": "true"
}

Example Request » Conversations

{
  "product": "CONVERSATIONS",
  "account_id": "abcdef01"
}
{
  "product": "CONVERSATIONS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "type": "ip-voice",
  "conversation_id": "CON-abc123",
  "status": "0"
}

Example Request » ASR

{
  "product": "ASR",
  "account_id": "abcdef01"
}
{
  "product": "ASR",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "direction": "outbound",
  "from": "441234567890",
  "to": "441234567890",
  "status": "ok"
}

Example Responses

200 400 401 403 422
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "PENDING",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "direction": "outbound",
  "status": "delivered",
  "client_ref": "abc123",
  "account_ref": "abc123",
  "include_message": "true",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "PENDING",
  "product": "VOICE-CALL",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "direction": "outbound",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890",
  "status": "started"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "PENDING",
  "product": "VERIFY-API",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "to": "441234567890",
  "network": "23415"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "PENDING",
  "product": "NUMBER-INSIGHT",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "number": "441234567890",
  "network": "23415"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "PENDING",
  "product": "MESSAGES",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "direction": "outbound",
  "from": "441234567890",
  "to": "441234567890",
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "include_message": "true"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "PENDING",
  "product": "CONVERSATIONS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "type": "ip-voice",
  "conversation_id": "CON-abc123",
  "status": "0"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "PENDING",
  "product": "ASR",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "direction": "outbound",
  "from": "441234567890",
  "to": "441234567890",
  "status": "ok"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-json",
  "title": "Malformed JSON",
  "detail": "Malformed JSON payload.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Unauthorized",
  "detail": "You did not provide correct credentials.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "type": "https://developer.nexmo.com/api-errors#forbidden",
  "title": "Forbidden",
  "detail": "User not authorized to query the requested data.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Unprocessable entity",
  "detail": "Unprocessable entity.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}

Get status of report

Retrieve status and metadata about a requested report.

GET https://api.nexmo.com/v2/reports/:report_id
Host https://api.nexmo.com
GET /v2/reports/:report_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

report_id
string | Required

UUID of the report request (request_id in response).

Responses

200 OK
request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
status
string

Search only for sms with the corresponding status.

One of: delivered, expired, failed, rejected, accepted, buffered or unknown
client_ref
string

Search for messages with this client_ref.

account_ref
string

Search for messages with this account_ref.

include_message
boolean

Include the text of messages in the report.

network
string

Network used to send the request.

from
string

Request from this number.

to
string

Request to this number.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
network
string

Network used to send the request.

from
string

Request from this number.

to
string

Request to this number.

status
string

Search only for voice call with the corresponding status.

One of: started, ringing, answered, machine, completed, timeout, failed, rejected, cancelled or busy
request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

to
string

Request to this number.

network
string

Network used to send the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

number
string

Search only request for the target number.

network
string

Network used to send the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

id
string

Search only messages with the specified uuid.

include_message
boolean

Include the text of messages in the report.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

type
string

Type of conversation request. Only used, and is required, when product is CONVERSATIONS.

One of: ip-voice or cs-custom-event
conversation_id
string

Search only for Voice calls attached to this particular Conversation. This should include the "CON-" prefix.

status
string

Search only for conversation events with the specified event status.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

status
string

Search only for ASR with corresponding status.

One of: ok or error

Example Responses

200 401 404
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "status": "delivered",
  "client_ref": "abc123",
  "account_ref": "abc123",
  "include_message": "true",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "VOICE-CALL",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890",
  "status": "started"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "VERIFY-API",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "to": "441234567890",
  "network": "23415"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "NUMBER-INSIGHT",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "number": "441234567890",
  "network": "23415"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "MESSAGES",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "from": "441234567890",
  "to": "441234567890",
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "include_message": "true"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "CONVERSATIONS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "type": "ip-voice",
  "conversation_id": "CON-abc123",
  "status": "0"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "ASR",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "from": "441234567890",
  "to": "441234567890",
  "status": "ok"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Unauthorized",
  "detail": "You did not provide correct credentials.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Invalid report ID",
  "detail": "Report aaaaaaaa-bbbb-cccc-dddd-0123456789ab does not exist, or you do not have access.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}

Cancel the execution of a report

Cancel the execution of a pending or processing report.

DELETE https://api.nexmo.com/v2/reports/:report_id
Host https://api.nexmo.com
DELETE /v2/reports/:report_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

report_id
string | Required

UUID of the report

Responses

200 OK
request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
status
string

Search only for sms with the corresponding status.

One of: delivered, expired, failed, rejected, accepted, buffered or unknown
client_ref
string

Search for messages with this client_ref.

account_ref
string

Search for messages with this account_ref.

include_message
boolean

Include the text of messages in the report.

network
string

Network used to send the request.

from
string

Request from this number.

to
string

Request to this number.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
network
string

Network used to send the request.

from
string

Request from this number.

to
string

Request to this number.

status
string

Search only for voice call with the corresponding status.

One of: started, ringing, answered, machine, completed, timeout, failed, rejected, cancelled or busy
request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

to
string

Request to this number.

network
string

Network used to send the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

number
string

Search only request for the target number.

network
string

Network used to send the request.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

id
string

Search only messages with the specified uuid.

include_message
boolean

Include the text of messages in the report.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

type
string

Type of conversation request. Only used, and is required, when product is CONVERSATIONS.

One of: ip-voice or cs-custom-event
conversation_id
string

Search only for Voice calls attached to this particular Conversation. This should include the "CON-" prefix.

status
string

Search only for conversation events with the specified event status.

request_id
string

UUID of the request.

request_status
string

Status of the request.

One of: PENDING, PROCESSING, SUCCESS, ABORTED, FAILED or TRUNCATED
product
string

Which product you wish to generate a report for.

One of: SMS, VOICE-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS or ASR
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 Nexmo 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.

include_subaccounts
boolean

Whether to include subaccounts or not.

One of: true or false
callback_url
string

URL to send a callback upon completion of the report. This POST callback contains the same information as the response to Get status of report.

receive_time
string

Time at which the report request was received by the service.

start_time
string

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

items_count
integer

The number of rows in the resulting file (when report has been completed).

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. Invalid for CONVERSATIONS, NUMBER-INSIGHT, VERIFY-API.

One of: inbound or outbound
from
string

Request from this number.

to
string

Request to this number.

status
string

Search only for ASR with corresponding status.

One of: ok or error

Example Responses

200 401 404
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "status": "delivered",
  "client_ref": "abc123",
  "account_ref": "abc123",
  "include_message": "true",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "VOICE-CALL",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890",
  "status": "started"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "VERIFY-API",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "to": "441234567890",
  "network": "23415"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "NUMBER-INSIGHT",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "number": "441234567890",
  "network": "23415"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "MESSAGES",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "from": "441234567890",
  "to": "441234567890",
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "include_message": "true"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "CONVERSATIONS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "type": "ip-voice",
  "conversation_id": "CON-abc123",
  "status": "0"
}
{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "ASR",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "from": "441234567890",
  "to": "441234567890",
  "status": "ok"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Unauthorized",
  "detail": "You did not provide correct credentials.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Invalid report ID",
  "detail": "Report aaaaaaaa-bbbb-cccc-dddd-0123456789ab does not exist, or you do not have access.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}

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.

GET https://api.nexmo.com/v3/media/:file_id
Host https://api.nexmo.com
GET /v3/media/:file_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

file_id
string | Required

UUID of the file.

Responses

200 Zip file containing CSV files
report
array of objects

The report in CSV format inside the zip archive.

Example Responses

200 401 404
Zip file containing CSV files
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Unauthorized",
  "detail": "You did not provide correct credentials.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Invalid report ID",
  "detail": "Report aaaaaaaa-bbbb-cccc-dddd-0123456789ab does not exist, or you do not have access.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}