Reports API

The Reports API enables you to request a report of activity for your Vonage account.

Depending on your query pattern, you can choose from one of the two versions of the Reports API: asynchronous and synchronous. The asynchronous version is optimized for infrequent and large data queries (from several records to tens of millions). The synchronous version is optimized for frequent and periodic retrievals of small batches of data records (from one record to tens of thousand per query).

Only synchronous version supports retrival of data records by message/record ID.

Vonage recommends that you limit asynchronous queries to a maximum of 7 million records, by setting the start and end dates accordingly. On average, the asynchronous Reports API takes 5 - 10 minutes to generate 1 million records.

Reports API is a paid product. Full pricing is available at https://www.vonage.com/communications-apis/pricing/.

We recommend the monthly subscription option if you are going to retrieve more than 1M records per month.

Télécharger la spécification OpenAPI

Opérations disponibles

Load records synchronously

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

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

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Demande de renseignements Paramètres

product

string

The product to return records for.

Il doit s'agir de l'un d'entre eux :SMSSMS-TRAFFIC-CONTROLVOICE-CALLVOICE-FAILEDVOICE-TTSIN-APP-VOICEWEBSOCKET-CALLASRAMDVERIFY-APIVERIFY-V2NUMBER-INSIGHTNUMBER-INSIGHT-V2CONVERSATION-EVENTCONVERSATION-MESSAGEMESSAGESVIDEO-APINETWORK-API-EVENTREPORTS-USAGE

account_id

string

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

date_start

string

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

date_end

string

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

cursor

string

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

string

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

string

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

direction

string

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

Il doit s'agir de l'un d'entre eux :inboundoutbound

status

string

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

from

string

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

string

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

country

string

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

network

string

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

number

string

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

locale

string

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

include_message

boolean

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

show_concatenated

boolean

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

account_ref

string

Account reference. Optional for SMS.

call_id

string

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

leg_id

string

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

provider

string

Messaging provider. Optional for MESSAGES.

Il doit s'agir de l'un d'entre eux :whatsappsmsmmsmessengerviber_service_msginstagramrcs

number_type

string

Number type. Optional for VERIFY-API.

channel

string

Verification channel. Optional for VERIFY-V2.

Il doit s'agir de l'un d'entre eux :v2emailsilent_auth

parent_request_id

string

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

request_type

string

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

risk

string

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

swapped

boolean

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

conversation_id

string

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

session_id

string

Session ID. Optional for VIDEO-API.

meeting_id

string

Meeting ID. Optional for VIDEO-API.

product_name

string

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

request_session_id

string

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

product_path

string

API path. Optional for NETWORK-API-EVENT.

correlation_id

string

Correlation ID. Optional for NETWORK-API-EVENT.

Réponses
Type de contenu
application/json

Report data retrieved successfully

L'un des

_links

object

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

self

object

href

string(uri)

exemple

https://api.nexmo.com/v2/reports/sms/records?product=SMS&direction=outbound&date_start=2024-02-01T00:00:00Z&date_end=2024-02-02T00:00:00Z

object

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

href

string(uri)

exemplehttps://api.nexmo.com/v2/reports/sms/records?product=SMS&direction=outbound&cursor=MTY0OTQ3ODAwMDAwMA

cursor

string

exempleMTY0OTQ3ODAwMDAwMA

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

string

exemple8a2c4e6f-12d3-45b6-78c9-0a1b2c3d4e5f

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

request_id

string

exemplea91b34c2-5d98-4c0e-8f23-a6b1c7d4e9f0

Unique ID associated with this synchronous request.

request_status

string

exempleSUCCESS

The result status of the request.

Il doit s'agir de l'un d'entre eux :SUCCESSTRUNCATED

received_at

string

exemple2024-02-07T14:22:08+00:00

Timestamp when the request was processed by the Reports API.

items_count

integer(int64)

exemple50

The number of records returned in this page/response.

ids_not_found

string

exempleid-missing-1,id-missing-2

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

product

string

exempleSMS

Il doit s'agir de l'un d'entre eux :SMS

records

array

List of outbound SMS records

account_id

string

exemple12aa3456

The account ID (API key) of the Customer. Might be a main account id or a sub-account

message_id

string

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

Vonage's unique identifier for this message

account_ref

string

exemplecustomer1234

It's used to identify separate accounts using the SMS endpoint for billing purposes. The field is optional in SMS. It can be empty in the report

client_ref

string

exemplemy-personal-reference

If client-ref parameter were used by the Customer while calling SMS, the value with Client's own reference will be shown in this field. Up to 100 characters.

direction

string

exempleoutbound

Direction of the call, either inbound or outbound.

from

string

exemple447700900001

SMS sent from this phone number. The value specified by the Customer in from parameter in SMS request (can be numeric, alpha-numeric or short code)

string

exemple447700900000

SMS sent to this phone number. In other words, the destination phone number.

forced_from

string

exemple44770090045

The number used instead of from field by Vonage, but only if there are any special routing rules were applied. It will be empty if not applicable.

changed_from

string

exempleNXSMS

The number used instead of from field by Vonage, but only if if Number Pools API was used or if routing rules were changed due to compliance reasons. It will be empty if not applicable.

concatenated

string

exempleFALSE

Indicates whether the SMS was split up into multiple parts (due to its length). The field will be available in the report if Reports API were called with the parameter show_concatenated= true.

message_body

string

exempleHello World!

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

network

string

exemple12345

The network code of the destination phone number. Taken from a carrier lookup (or sometimes the numbering plan), and always a master network code. Usually an MCC/MNC but sometimes alpha e.g US-FIXED

network_name

string

exempleOrange Polska S.A.

The name of the network code

country

string

exemplePL

The ISO two letter country code to which the network code belongs in the numbering plan

country_name

string

exemplePoland

Country name of the country code

date_received

string

exemple2024-02-02T13:50:00+00:00

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

date_finalized

string

exemple2024-02-02T13:50:00+00:00

Date when the SMS message reached its final state. Format: yyyy-mm-ddThh:mm:ss±hh:mm Time zone: UTC

latency

string

exemple42

Latency of the request in ms

status

string

exempledelivered

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

error_code

string

exemple0

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

error_code_description

string

exempleDelivered

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

currency

string

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

total_price

string

exemple0.036

Price of the SMS request

string

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the record in the report

dcs

string

exemple0

DCS (Data Coding Scheme) is the encoding with which the message body was delivered to the phone. It is according to the value of the type parameter used in SMS request. DCS = 0 (the default value) is for GSM/text. DCS = 8 is for unicode text messages DCS = 4 is for binary text messages

validity_period

string

exemple240210092938000+

The validity period of the SMS message used in the ttl parameter of the SMS request. The duration in milliseconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours.

ip_address

string

exemple12.23.456.111

The IP address of the Customer's server calling SMS.

udh

string

exemple50003940401

User Data Header, available if SMS was split up into multiple parts (due to its length). Pay attention: UDHs are not unique values. An 8 bit concatenation UDH is always going to start from 050003, then the reference e.g. 00 and then the total parts and part index e.g. 0201 for the first part of a two part message

workflow_id

string

exemple3TcNjgZvTgbJ41bJGMiHQxf7s6UPsKUEnkhyY

RCS workflow_id. Populated only when an SMS is converted to RCS. It matches the workflow_id in the Messages report, allowing retrieval of the corresponding RCS record. Blank if not converted. See details about the feature here - SMS-to-RCS Transitioning with Branded Text

Exemple Réponse»SMS (Outbound)

{
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v2/reports/sms/records?product=SMS&direction=outbound&date_start=2024-02-01T00:00:00Z&date_end=2024-02-02T00:00:00Z"
      },
      "next": {
         "href": "https://api.nexmo.com/v2/reports/sms/records?product=SMS&direction=outbound&cursor=MTY0OTQ3ODAwMDAwMA"
      }
   },
   "cursor": "MTY0OTQ3ODAwMDAwMA",
   "iv": "8a2c4e6f-12d3-45b6-78c9-0a1b2c3d4e5f",
   "request_id": "a91b34c2-5d98-4c0e-8f23-a6b1c7d4e9f0",
   "request_status": "SUCCESS",
   "received_at": "2024-02-07T14:22:08+00:00",
   "items_count": 50,
   "ids_not_found": "id-missing-1,id-missing-2",
   "product": "SMS",
   "records": [
      {
         "account_id": "12aa3456",
         "message_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "account_ref": "customer1234",
         "client_ref": "my-personal-reference",
         "direction": "outbound",
         "from": "447700900001",
         "to": "447700900000",
         "forced_from": "44770090045",
         "changed_from": "NXSMS",
         "concatenated": "FALSE",
         "message_body": "Hello World!",
         "network": "12345",
         "network_name": "Orange Polska S.A.",
         "country": "PL",
         "country_name": "Poland",
         "date_received": "2024-02-02T13:50:00+00:00",
         "date_finalized": "2024-02-02T13:50:00+00:00",
         "latency": "42",
         "status": "delivered",
         "error_code": "0",
         "error_code_description": "Delivered",
         "currency": "",
         "total_price": "0.036",
         "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "dcs": "0",
         "validity_period": "240210092938000+",
         "ip_address": "12.23.456.111",
         "udh": "50003940401",
         "workflow_id": "3TcNjgZvTgbJ41bJGMiHQxf7s6UPsKUEnkhyY"
      }
   ]
}

Create an asynchronous report

Creates an asynchronous report generation request. The report will be processed in the background and you can check its status using the returned report ID. The API returns a combination of the standard required fields and those specified in the input payload.

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

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Corps de la demande
Type de contenu
application/json

L'un des

product

string

Exigée

exempleSMS

Product type for the report

account_id

string

Exigée

exemple12aa3456

date_start

string

exemple2024-02-02T13:50:00+00:00

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

date_end

string

exemple2024-02-07T14:22:08+00:00

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

include_subaccounts

boolean

exempletrue

Include data from sub-accounts

callback_url

string(uri)

exemplehttps://example.com/webhook

Webhook URL for completion notifications

direction

string

Exigée

exempleoutbound

Direction of the communication.

Il doit s'agir de l'un d'entre eux :inboundoutbound

status

string

exempledelivered

The final status of the message delivery filter

Il doit s'agir de l'un d'entre eux :deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

exemple447700900001

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

string

exemple447700900000

Recipient phone number

country

string

exemplePL

The ISO two letter country code

network

string

exemple12345

The network code of the destination phone number

client_ref

string

exemplemy-personal-reference

The optional custom reference value

account_ref

string

exemplecustomer1234

Account reference.

include_message

boolean

exempletrue

Determines whether the message body is included.

show_concatenated

boolean

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

Exemple Demande»SMS

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

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

Réponses
Type de contenu
application/json

Report creation request accepted

L'un des

request_id

string

Exigée

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

Exigée

exemplePENDING

Status of the request.

Il doit s'agir de l'un d'entre eux :PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

receive_time

string

Exigée

exemple2024-02-07T14:22:08+00:00

Time at which the request of the report was received.

start_time

string

Exigée

exemple2024-02-07T14:22:10+00:00

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

items_count

integer(int64)

Exigée

exemple1523

Number of records

_links

object

Exigée

HAL links

self

object

href

string(uri)

exemplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

download_report

object

href

string(uri)

exemplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Download URL

product

string

Exigée

exempleSMS

Product type for the report

account_id

string

Exigée

exemple12aa3456

date_start

string

exemple2024-02-02T13:50:00+00:00

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

date_end

string

exemple2024-02-07T14:22:08+00:00

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

include_subaccounts

boolean

exempletrue

Include data from sub-accounts

callback_url

string(uri)

exemplehttps://example.com/webhook

Webhook URL for completion notifications

direction

string

Exigée

exempleoutbound

Direction of the communication.

Il doit s'agir de l'un d'entre eux :inboundoutbound

status

string

exempledelivered

The final status of the message delivery filter

Il doit s'agir de l'un d'entre eux :deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

exemple447700900001

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

string

exemple447700900000

Recipient phone number

country

string

exemplePL

The ISO two letter country code

network

string

exemple12345

The network code of the destination phone number

client_ref

string

exemplemy-personal-reference

The optional custom reference value

account_ref

string

exemplecustomer1234

Account reference.

include_message

boolean

exempletrue

Determines whether the message body is included.

show_concatenated

boolean

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

Exemple Réponse»SMS

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

Get status of report

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

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

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

reportId

string

Exigée

Unique identifier of the report (request_id in response).

Réponses
Type de contenu
application/json

Report details retrieved successfully

L'un des

request_id

string

Exigée

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

Exigée

exemplePENDING

Status of the request.

Il doit s'agir de l'un d'entre eux :PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

receive_time

string

Exigée

exemple2024-02-07T14:22:08+00:00

Time at which the request of the report was received.

start_time

string

Exigée

exemple2024-02-07T14:22:10+00:00

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

items_count

integer(int64)

Exigée

exemple1523

Number of records

_links

object

Exigée

HAL links

self

object

href

string(uri)

exemplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

download_report

object

href

string(uri)

exemplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Download URL

product

string

Exigée

exempleSMS

Product type for the report

account_id

string

Exigée

exemple12aa3456

date_start

string

exemple2024-02-02T13:50:00+00:00

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

date_end

string

exemple2024-02-07T14:22:08+00:00

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

include_subaccounts

boolean

exempletrue

Include data from sub-accounts

callback_url

string(uri)

exemplehttps://example.com/webhook

Webhook URL for completion notifications

direction

string

Exigée

exempleoutbound

Direction of the communication.

Il doit s'agir de l'un d'entre eux :inboundoutbound

status

string

exempledelivered

The final status of the message delivery filter

Il doit s'agir de l'un d'entre eux :deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

exemple447700900001

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

string

exemple447700900000

Recipient phone number

country

string

exemplePL

The ISO two letter country code

network

string

exemple12345

The network code of the destination phone number

client_ref

string

exemplemy-personal-reference

The optional custom reference value

account_ref

string

exemplecustomer1234

Account reference.

include_message

boolean

exempletrue

Determines whether the message body is included.

show_concatenated

boolean

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

Exemple Réponse»SMS

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

Cancel the execution of a report

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

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

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

reportId

string

Exigée

Unique identifier of the report to abort (request_id in response).

Réponses
Type de contenu
application/json

Report aborted successfully

L'un des

request_id

string

Exigée

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

Exigée

exemplePENDING

Status of the request.

Il doit s'agir de l'un d'entre eux :PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

receive_time

string

Exigée

exemple2024-02-07T14:22:08+00:00

Time at which the request of the report was received.

start_time

string

Exigée

exemple2024-02-07T14:22:10+00:00

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

items_count

integer(int64)

Exigée

exemple1523

Number of records

_links

object

Exigée

HAL links

self

object

href

string(uri)

exemplehttps://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

download_report

object

href

string(uri)

exemplehttps://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Download URL

product

string

Exigée

exempleSMS

Product type for the report

account_id

string

Exigée

exemple12aa3456

date_start

string

exemple2024-02-02T13:50:00+00:00

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

date_end

string

exemple2024-02-07T14:22:08+00:00

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

include_subaccounts

boolean

exempletrue

Include data from sub-accounts

callback_url

string(uri)

exemplehttps://example.com/webhook

Webhook URL for completion notifications

direction

string

Exigée

exempleoutbound

Direction of the communication.

Il doit s'agir de l'un d'entre eux :inboundoutbound

status

string

exempledelivered

The final status of the message delivery filter

Il doit s'agir de l'un d'entre eux :deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

exemple447700900001

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

string

exemple447700900000

Recipient phone number

country

string

exemplePL

The ISO two letter country code

network

string

exemple12345

The network code of the destination phone number

client_ref

string

exemplemy-personal-reference

The optional custom reference value

account_ref

string

exemplecustomer1234

Account reference.

include_message

boolean

exempletrue

Determines whether the message body is included.

show_concatenated

boolean

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

Exemple Réponse»SMS

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

Get report data

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

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

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

file_id

string

Exigée

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the file.

Réponses
Type de contenu
application/octet-stream

Zip file containing CSV files

report

array

The report in CSV format inside the zip archive.

N'importe lequel

acc

string

exemple12aa3456

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

product_type

string

exemplereports

Report's API product. Always reports.

date_received

string

exemple2024-02-02T13:50:00+00:00

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

date_started

string

exemple2024-02-02T13:50:00+00:00

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

date_finished

string

exemple2024-02-02T13:50:00+00:00

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

status

string

exempleSUCCESS

Status of the report's request

account_id

string

exemple12aa3456

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

master_account_id

string

exemple88aa3456

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

is_charged

string

exempleTRUE

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

request_params

object

Base parameters for all report requests

product

string

Exigée

exempleSMS

Product type for the report

account_id

string

Exigée

exemple12aa3456

date_start

string

exemple2024-02-02T13:50:00+00:00

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

date_end

string

exemple2024-02-07T14:22:08+00:00

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

job_type

string

exempleASYNC_JOB

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

requested_product

string

exempleSMS

Product requested in the report.

items_written

integer

exemple134

Number of CDRs/records returned in the report

price

number

exemple0.0004

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

currency

string

exempleEUR

Currency of the price of the report

total_price

number

exemple120

The total price for the whole report

string

exempleab12345678c90-b1234-ba78-f1c3e400f28d

The unique id of the record in the report

Exemple Réponse

L'exemple de prévisualisation n'est actuellement pas pris en charge pour le type de contenu : application/octet-stream

Erreurs

Voici une liste non exhaustive des codes d'erreur susceptibles de se produire lors de l'utilisation de cette API.

Ces codes s'ajoutent à ceux de notre site codes d'erreur génériques.

Code Informations

Code	Informations
invalid-request-parameters	Description The provided payload is invalid Résolution Modify your request to provide a valid payload
invalid-abort-operation	Description The job is already in a terminated state such as `SUCCESS`, `TRUNCATED`, `FAILED` or `ABORTED`. Résolution None
rate-limit	Description The request was rate limited. Résolution The Reports API supports 5 requests per second when used Asynchronously, and 10 requests per second Synchronously. Slow down your request rate.

invalid-request-parameters

Description

The provided payload is invalid

Résolution

Modify your request to provide a valid payload

invalid-abort-operation

Description

The job is already in a terminated state such as SUCCESS, TRUNCATED, FAILED or ABORTED.

Résolution

None

rate-limit

Description

The request was rate limited.

Résolution

The Reports API supports 5 requests per second when used Asynchronously, and 10 requests per second Synchronously. Slow down your request rate.

Reports API

Opérations disponibles

Load records synchronously

Authentification

Demande de renseignements Paramètres

Réponses Type de contenuapplication/json

Exemple Réponse»SMS (Outbound)

Create an asynchronous report

Authentification

Corps de la demande Type de contenuapplication/json

Exemple Demande»SMS

Réponses Type de contenuapplication/json

Exemple Réponse»SMS

Get status of report

Authentification

Trajectoire Paramètres

Réponses Type de contenuapplication/json

Exemple Réponse»SMS

Cancel the execution of a report

Authentification

Trajectoire Paramètres

Réponses Type de contenuapplication/json

Exemple Réponse»SMS

Get report data

Authentification

Trajectoire Paramètres

Réponses Type de contenuapplication/octet-stream

Exemple Réponse

Erreurs

Réponses
Type de contenu
application/json

Corps de la demande
Type de contenu
application/json

Réponses
Type de contenu
application/json

Réponses
Type de contenu
application/json

Réponses
Type de contenu
application/json

Réponses
Type de contenu
application/octet-stream