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
id string	The ID of the request. If you provide this, you must not provide `date_start` or `date_end`	`aaaaaaaa-bbbb-cccc-dddd-0123456789ab`	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 `id`.	`2017-12-01T00:00:00+0000`	None
date_end string \| (date)	Must be no more than 24 hours later than `date_start` ISO-8601 extended time zone offset or ISO-8601 UTC zone offset formatted date (format `yyyy-mm-ddThh:mm:ss[.sss]±hh:mm` or `yyyy-mm-ddThh:mm:ss[.sss]Z`) for when report should end. It is exclusive, i.e. the provided value is strictly greater than the value in the field `date_received` in the CDR. If you provide this, you must provide `date_start` and must not provide `id`.	`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.

self_link
string

URI of this search.

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

Nexmo Reports API

Nexmo Reports API

Load records synchronously

Authentication

Query Parameter

Response Fields

HTTP response 200

HTTP response 403

HTTP response 422

Create an asynchronous report

Authentication

Request body application/json

Response Fields

HTTP response 200

HTTP response 400

HTTP response 401

HTTP response 403

HTTP response 422

List reports

Authentication

Query Parameter

Response Fields

HTTP response 200

HTTP response 400

HTTP response 401

Get status of report

Authentication

Path Parameters

Response Fields

HTTP response 200

HTTP response 401

HTTP response 404

Cancel the execution of a report

Authentication

Path Parameters

Response Fields

HTTP response 200

HTTP response 401

HTTP response 404

Get report data

Authentication

Path Parameters

Response Fields

HTTP response 200

HTTP response 401

HTTP response 404