Nexmo Reports API Beta

Nexmo's Reports API allows you to request a report of activity on your Nexmo account.
On average the Reports API takes 5 - 10 minutes to generate 1 million records. Nexmo recommends requesting only reports of up to a maximum of 20 million records, by setting the start and end dates accordingly.
Reports are generated as CSV files compressed in zip archives.

Download OpenAPI 3 Definition

Improve this specification

Create a 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
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 Required \| string	Direction of the request, either inbound or outbound. Must be one of: `inbound` or `outbound`	`outbound`	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 Beta

Create a 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