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.

Download OpenAPI 3 Definition
Improve this specification

Load records synchronously

Fetch usage data synchronously

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

Key Description Example Default
account_id
Required | string

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

 abcd1234 None
product
Required | string

The product to return records for


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

Direction of the request, either inbound or outbound.


Must be one of: inbound or outbound 		inbound None
message_id
string

The ID of the request.

If you provide this, you must not provide date_start or date_end

 inbound None
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 message_id to seven days ago.

 2017-12-01T00:00:00+0000 None
date_end
string | (date)

Must be within 1 hour of 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 message_id

 2018-01-01T00:00:00+0000 None
include_message
string

Include the message contents in the records


Must be one of: true or false 		true false
type
string

The event type to search for. Only used for type: CONVERSATIONS


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

The SMS status to search for. Only used for type: SMS


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

View response field descriptions

Response Fields

SMS (Outbound)
Field Description
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 request, either inbound or outbound.

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 or CONVERSATIONS
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
Field Description
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 request, either inbound or outbound.

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_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

Search only for sms with the corresponding status.

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

Error code of the request.
error_code_description
string

Description of the error code of the request.
currency
string

Currency of the price of the request.
total_price
number

Price of the request.
SMS (Inbound)
Field Description
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 request, either inbound or outbound.

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 or CONVERSATIONS
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
Field Description
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
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_received
string

Date of the request.
currency
string

Currency of the price of the request.
total_price
number

Price of the request.
Voice Call
Field Description
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 request, either inbound or outbound.

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 or CONVERSATIONS
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
Field Description
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 request, either inbound or outbound.

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.
Verify
Field Description
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 request, either inbound or outbound.

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 or CONVERSATIONS
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
Field Description
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.
Number Insight
Field Description
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 request, either inbound or outbound.

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 or CONVERSATIONS
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
Field Description
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.
Messages (Outbound)
Field Description
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 request, either inbound or outbound.

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 or CONVERSATIONS
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
Field Description
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 request, either inbound or outbound.

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.
Messages (Inbound)
Field Description
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 request, either inbound or outbound.

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 or CONVERSATIONS
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
Field Description
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 request, either inbound or outbound.

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.
IP Voice
Field Description
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 request, either inbound or outbound.

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 or CONVERSATIONS
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
Field Description
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.

 
{
  "_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"
    }
  ]
}
{
  "_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"
    }
  ]
}
{
  "_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"
    }
  ]
}
{
  "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"
}

Create an asynchronous report

Request a report on your account activity

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

Key Description Example Default
product
Required | string

Which product you wish to generate a report for.


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

 abcdef01 None
direction
Required | string

Direction of the request, either inbound or outbound.


Must be one of: inbound or outbound 		outbound None
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.

 2017-12-01T00:00:00+00:00 None
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.

 2018-01-01T00:00:00+00:00 None
include_subaccounts
boolean

Whether to include subaccounts or not.


Must be one of: true or false 		false 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.

 https://requestb.in/12345 None
status
string

Search only for sms with the corresponding status.


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

Search for messages with this client_ref.

 None None
account_ref
string

Search for messages with this account_ref.

 None None
include_message
boolean

Include the text of messages in the report.

 true false
network
string

Network used to send the request.

 23415 None
from
string

Request from this number.

 441234567890 None
to
string

Request to this number.

 441234567890 None
Key Description Example Default
product
Required | string

Which product you wish to generate a report for.


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

 abcdef01 None
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.

 2017-12-01T00:00:00+00:00 None
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.

 2018-01-01T00:00:00+00:00 None
include_subaccounts
boolean

Whether to include subaccounts or not.


Must be one of: true or false 		false 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.

 https://requestb.in/12345 None
direction
string

Direction of the request, either inbound or outbound.


Must be one of: inbound or outbound 		outbound None
network
string

Network used to send the request.

 23415 None
from
string

Request from this number.

 441234567890 None
to
string

Request to this number.

 441234567890 None
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 		started None
Key Description Example Default
product
Required | string

Which product you wish to generate a report for.


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

 abcdef01 None
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.

 2017-12-01T00:00:00+00:00 None
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.

 2018-01-01T00:00:00+00:00 None
include_subaccounts
boolean

Whether to include subaccounts or not.


Must be one of: true or false 		false 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.

 https://requestb.in/12345 None
to
string

Request to this number.

 441234567890 None
network
string

Network used to send the request.

 23415 None
Key Description Example Default
product
Required | string

Which product you wish to generate a report for.


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

 abcdef01 None
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.

 2017-12-01T00:00:00+00:00 None
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.

 2018-01-01T00:00:00+00:00 None
include_subaccounts
boolean

Whether to include subaccounts or not.


Must be one of: true or false 		false 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.

 https://requestb.in/12345 None
number
string

Search only request for the target number.

 441234567890 None
network
string

Network used to send the request.

 23415 None
Key Description Example Default
product
Required | string

Which product you wish to generate a report for.


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

 abcdef01 None
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.

 2017-12-01T00:00:00+00:00 None
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.

 2018-01-01T00:00:00+00:00 None
include_subaccounts
boolean

Whether to include subaccounts or not.


Must be one of: true or false 		false 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.

 https://requestb.in/12345 None
direction
string

Direction of the request, either inbound or outbound.


Must be one of: inbound or outbound 		outbound None
from
string

Request from this number.

 441234567890 None
to
string

Request to this number.

 441234567890 None
uuid
string

Search only messages with the specified uuid.

 441234567890 None
include_message
boolean

Include the text of messages in the report.

 true false
Key Description Example Default
product
Required | string

Which product you wish to generate a report for.


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

 abcdef01 None
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.

 2017-12-01T00:00:00+00:00 None
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.

 2018-01-01T00:00:00+00:00 None
include_subaccounts
boolean

Whether to include subaccounts or not.


Must be one of: true or false 		false 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.

 https://requestb.in/12345 None
type
string

Type of conversation request.


Must be one of: ip-voice 		ip-voice None
conversation_id
string

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

 CON-abc123 None
status
string

Search only for conversation events with the specified event status.

 0 None

View response field descriptions

Response Fields

SMS
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

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.
Voice Call
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

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
Verify
Field Description
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 or CONVERSATIONS
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.
Number Insight
Field Description
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 or CONVERSATIONS
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.
Messages
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

One of: inbound or outbound
from
string

Request from this number.
to
string

Request to this number.
uuid
string

Search only messages with the specified uuid.
include_message
boolean

Include the text of messages in the report.
Conversations
Field Description
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 or CONVERSATIONS
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.

One of: ip-voice
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": "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",
  "uuid": "441234567890",
  "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"
}
{
  "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"
}

List reports

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

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

Key Description Example Default
account_id
Required | string

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

 abcd1234 None
status
string

List of statuses of reports to list, comma separated. Statuses can be one of PENDING, PROCESSING, SUCCESS, ABORTED, FAILED, TRUNCATED.

 SUCCESS, FAILED None
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

 2019-06-28T00:00:00-00:00 None
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

 2019-06-28T23:59:59-00:00 None

View response field descriptions

Response Fields

Field Description
items_count
integer

The number of reports in the list.
reports
array of objects

The list of reports.
This array contains any of the following objects:
SMS
Voice Call
Verify
Number Insight
Messages
Conversations
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

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.
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

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
Field Description
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 or CONVERSATIONS
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.
Field Description
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 or CONVERSATIONS
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.
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

One of: inbound or outbound
from
string

Request from this number.
to
string

Request to this number.
uuid
string

Search only messages with the specified uuid.
include_message
boolean

Include the text of messages in the report.
Field Description
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 or CONVERSATIONS
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.

One of: ip-voice
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.

 
{
  "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",
      "uuid": "441234567890",
      "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"
    }
  ]
}
{
  "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"
}

Get status of report

Retrieve status and metadata about a requested report.

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

Key Description Example Default
report_id
Required | string

UUID of the report

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab None

View response field descriptions

Response Fields

SMS
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

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.
Voice Call
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

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
Verify
Field Description
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 or CONVERSATIONS
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.
Number Insight
Field Description
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 or CONVERSATIONS
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.
Messages
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

One of: inbound or outbound
from
string

Request from this number.
to
string

Request to this number.
uuid
string

Search only messages with the specified uuid.
include_message
boolean

Include the text of messages in the report.
Conversations
Field Description
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 or CONVERSATIONS
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.

One of: ip-voice
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": "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",
  "uuid": "441234567890",
  "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"
}
{
  "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

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

Key Description Example Default
report_id
Required | string

UUID of the report

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab None

View response field descriptions

Response Fields

SMS
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

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.
Voice Call
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

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
Verify
Field Description
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 or CONVERSATIONS
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.
Number Insight
Field Description
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 or CONVERSATIONS
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.
Messages
Field Description
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 or CONVERSATIONS
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 request, either inbound or outbound.

One of: inbound or outbound
from
string

Request from this number.
to
string

Request to this number.
uuid
string

Search only messages with the specified uuid.
include_message
boolean

Include the text of messages in the report.
Conversations
Field Description
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 or CONVERSATIONS
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.

One of: ip-voice
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": "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",
  "uuid": "441234567890",
  "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"
}
{
  "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

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

Key Description Example Default
file_id
Required | string

UUID of the file.

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab None

View response field descriptions

Response Fields

Field Description
report
array of objects

The report in CSV format inside the zip archive.
This array contains any of the following objects:
Outbound SMS
Inbound SMS
Voice Call
Verify
Number Insight
Outbound Messages
Inbound Messages
IP Voice Conversations
Field Description
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 request, either inbound or outbound.

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.
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.
latency
integer

Latency of the request in ms.
status
string

Search only for sms with the corresponding status.

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

Error code of the request.
error_code_description
string

Description of the error code of the request.
currency
string

Currency of the price of the request.
total_price
number

Price of the request.
Field Description
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 request, either inbound or outbound.

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.
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.
currency
string

Currency of the price of the request.
total_price
number

Price of the request.
Field Description
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 request, either inbound or outbound.

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.
Field Description
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.
Field Description
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.
Field Description
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 request, either inbound or outbound.

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.
Field Description
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 request, either inbound or outbound.

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.
Field Description
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.

 
{
  "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"
}