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.

Descargar la especificación OpenAPI

Operaciones 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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Consulta Parámetros

product

string

The product to return records for.

Debe ser uno de: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.

Debe ser uno de: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.

Debe ser uno de:whatsappsmsmmsmessengerviber_service_msginstagramrcs

number_type

string

Number type. Optional for VERIFY-API.

channel

string

Verification channel. Optional for VERIFY-V2.

Debe ser uno de: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.

Respuestas
Tipo de contenido
application/json

Report data retrieved successfully

Uno de

_links

object

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

self

object

href

string(uri)

ejemplo

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)

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

cursor

string

ejemploMTY0OTQ3ODAwMDAwMA

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

string

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

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

request_id

string

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

Unique ID associated with this synchronous request.

request_status

string

ejemploSUCCESS

The result status of the request.

Debe ser uno de:SUCCESSTRUNCATED

received_at

string

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

Timestamp when the request was processed by the Reports API.

items_count

integer(int64)

ejemplo50

The number of records returned in this page/response.

ids_not_found

string

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

ejemploSMS

Debe ser uno de:SMS

records

array

List of outbound SMS records

account_id

string

ejemplo12aa3456

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

message_id

string

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

Vonage's unique identifier for this message

account_ref

string

ejemplocustomer1234

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

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

ejemplooutbound

Direction of the call, either inbound or outbound.

from

string

ejemplo447700900001

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

ejemplo447700900000

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

forced_from

string

ejemplo44770090045

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

ejemploNXSMS

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

ejemploFALSE

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

ejemploHello World!

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

network

string

ejemplo12345

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

ejemploOrange Polska S.A.

The name of the network code

country

string

ejemploPL

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

country_name

string

ejemploPoland

Country name of the country code

date_received

string

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

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

ejemplo42

Latency of the request in ms

status

string

ejemplodelivered

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

ejemplo0

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

ejemploDelivered

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

ejemplo0.036

Price of the SMS request

string

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the record in the report

dcs

string

ejemplo0

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

ejemplo240210092938000+

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

ejemplo12.23.456.111

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

udh

string

ejemplo50003940401

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

ejemplo3TcNjgZvTgbJ41bJGMiHQxf7s6UPsKUEnkhyY

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

Ejemplo Respuesta»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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Cuerpo de la solicitud
Tipo de contenido
application/json

Uno de

product

string

Requerido

ejemploSMS

Product type for the report

account_id

string

Requerido

ejemplo12aa3456

date_start

string

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

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

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

include_subaccounts

boolean

ejemplotrue

Include data from sub-accounts

callback_url

string(uri)

ejemplohttps://example.com/webhook

Webhook URL for completion notifications

direction

string

Requerido

ejemplooutbound

Direction of the communication.

Debe ser uno de:inboundoutbound

status

string

ejemplodelivered

The final status of the message delivery filter

Debe ser uno de:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

ejemplo447700900001

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

string

ejemplo447700900000

Recipient phone number

country

string

ejemploPL

The ISO two letter country code

network

string

ejemplo12345

The network code of the destination phone number

client_ref

string

ejemplomy-personal-reference

The optional custom reference value

account_ref

string

ejemplocustomer1234

Account reference.

include_message

boolean

ejemplotrue

Determines whether the message body is included.

show_concatenated

boolean

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

Ejemplo Solicitar»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
}

Respuestas
Tipo de contenido
application/json

Report creation request accepted

Uno de

request_id

string

Requerido

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

Requerido

ejemploPENDING

Status of the request.

Debe ser uno de:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

receive_time

string

Requerido

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

Time at which the request of the report was received.

start_time

string

Requerido

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

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

items_count

integer(int64)

Requerido

ejemplo1523

Number of records

_links

object

Requerido

HAL links

self

object

href

string(uri)

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

download_report

object

href

string(uri)

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

Download URL

product

string

Requerido

ejemploSMS

Product type for the report

account_id

string

Requerido

ejemplo12aa3456

date_start

string

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

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

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

include_subaccounts

boolean

ejemplotrue

Include data from sub-accounts

callback_url

string(uri)

ejemplohttps://example.com/webhook

Webhook URL for completion notifications

direction

string

Requerido

ejemplooutbound

Direction of the communication.

Debe ser uno de:inboundoutbound

status

string

ejemplodelivered

The final status of the message delivery filter

Debe ser uno de:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

ejemplo447700900001

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

string

ejemplo447700900000

Recipient phone number

country

string

ejemploPL

The ISO two letter country code

network

string

ejemplo12345

The network code of the destination phone number

client_ref

string

ejemplomy-personal-reference

The optional custom reference value

account_ref

string

ejemplocustomer1234

Account reference.

include_message

boolean

ejemplotrue

Determines whether the message body is included.

show_concatenated

boolean

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

Ejemplo Respuesta»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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Ruta Parámetros

reportId

string

Requerido

Unique identifier of the report (request_id in response).

Respuestas
Tipo de contenido
application/json

Report details retrieved successfully

Uno de

request_id

string

Requerido

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

Requerido

ejemploPENDING

Status of the request.

Debe ser uno de:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

receive_time

string

Requerido

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

Time at which the request of the report was received.

start_time

string

Requerido

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

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

items_count

integer(int64)

Requerido

ejemplo1523

Number of records

_links

object

Requerido

HAL links

self

object

href

string(uri)

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

download_report

object

href

string(uri)

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

Download URL

product

string

Requerido

ejemploSMS

Product type for the report

account_id

string

Requerido

ejemplo12aa3456

date_start

string

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

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

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

include_subaccounts

boolean

ejemplotrue

Include data from sub-accounts

callback_url

string(uri)

ejemplohttps://example.com/webhook

Webhook URL for completion notifications

direction

string

Requerido

ejemplooutbound

Direction of the communication.

Debe ser uno de:inboundoutbound

status

string

ejemplodelivered

The final status of the message delivery filter

Debe ser uno de:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

ejemplo447700900001

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

string

ejemplo447700900000

Recipient phone number

country

string

ejemploPL

The ISO two letter country code

network

string

ejemplo12345

The network code of the destination phone number

client_ref

string

ejemplomy-personal-reference

The optional custom reference value

account_ref

string

ejemplocustomer1234

Account reference.

include_message

boolean

ejemplotrue

Determines whether the message body is included.

show_concatenated

boolean

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

Ejemplo Respuesta»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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Ruta Parámetros

reportId

string

Requerido

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

Respuestas
Tipo de contenido
application/json

Report aborted successfully

Uno de

request_id

string

Requerido

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the request.

request_status

string

Requerido

ejemploPENDING

Status of the request.

Debe ser uno de:PENDINGPROCESSINGSUCCESSABORTEDFAILEDTRUNCATED

receive_time

string

Requerido

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

Time at which the request of the report was received.

start_time

string

Requerido

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

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

items_count

integer(int64)

Requerido

ejemplo1523

Number of records

_links

object

Requerido

HAL links

self

object

href

string(uri)

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

download_report

object

href

string(uri)

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

Download URL

product

string

Requerido

ejemploSMS

Product type for the report

account_id

string

Requerido

ejemplo12aa3456

date_start

string

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

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

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

include_subaccounts

boolean

ejemplotrue

Include data from sub-accounts

callback_url

string(uri)

ejemplohttps://example.com/webhook

Webhook URL for completion notifications

direction

string

Requerido

ejemplooutbound

Direction of the communication.

Debe ser uno de:inboundoutbound

status

string

ejemplodelivered

The final status of the message delivery filter

Debe ser uno de:deliveredexpiredaccepteddeletedunknownsubmittedfailedrejectedbuffered

from

string

ejemplo447700900001

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

string

ejemplo447700900000

Recipient phone number

country

string

ejemploPL

The ISO two letter country code

network

string

ejemplo12345

The network code of the destination phone number

client_ref

string

ejemplomy-personal-reference

The optional custom reference value

account_ref

string

ejemplocustomer1234

Account reference.

include_message

boolean

ejemplotrue

Determines whether the message body is included.

show_concatenated

boolean

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

Ejemplo Respuesta»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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Ruta Parámetros

file_id

string

Requerido

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

UUID of the file.

Respuestas
Tipo de contenido
application/octet-stream

Zip file containing CSV files

report

array

The report in CSV format inside the zip archive.

Cualquiera de

acc

string

ejemplo12aa3456

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

product_type

string

ejemploreports

Report's API product. Always reports.

date_received

string

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

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

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

ejemploSUCCESS

Status of the report's request

account_id

string

ejemplo12aa3456

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

master_account_id

string

ejemplo88aa3456

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

is_charged

string

ejemploTRUE

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

request_params

object

Base parameters for all report requests

product

string

Requerido

ejemploSMS

Product type for the report

account_id

string

Requerido

ejemplo12aa3456

date_start

string

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

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

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

job_type

string

ejemploASYNC_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

ejemploSMS

Product requested in the report.

items_written

integer

ejemplo134

Number of CDRs/records returned in the report

price

number

ejemplo0.0004

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

currency

string

ejemploEUR

Currency of the price of the report

total_price

number

ejemplo120

The total price for the whole report

string

ejemploab12345678c90-b1234-ba78-f1c3e400f28d

The unique id of the record in the report

Ejemplo Respuesta

La vista previa de ejemplo no es compatible actualmente con el tipo de contenido: application/octet-stream

Errores

La siguiente es una lista no exhaustiva de códigos de error que pueden producirse al utilizar esta API.

Estos códigos se suman a cualquiera de nuestros códigos de error genéricos.

Código Información

Código	Información
invalid-request-parameters	Descripción The provided payload is invalid Resolución Modify your request to provide a valid payload
invalid-abort-operation	Descripción The job is already in a terminated state such as `SUCCESS`, `TRUNCATED`, `FAILED` or `ABORTED`. Resolución None
rate-limit	Descripción The request was rate limited. Resolución 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

Descripción

The provided payload is invalid

Resolución

Modify your request to provide a valid payload

invalid-abort-operation

Descripción

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

Resolución

None

rate-limit

Descripción

The request was rate limited.

Resolución

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

Reports API

Operaciones disponibles

Load records synchronously

Autenticación

Consulta Parámetros

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta»SMS (Outbound)

Create an asynchronous report

Autenticación

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Solicitar»SMS

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta»SMS

Get status of report

Autenticación

Ruta Parámetros

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta»SMS

Cancel the execution of a report

Autenticación

Ruta Parámetros

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta»SMS

Get report data

Autenticación

Ruta Parámetros

Respuestas Tipo de contenidoapplication/octet-stream

Ejemplo Respuesta

Errores

Respuestas
Tipo de contenido
application/json

Cuerpo de la solicitud
Tipo de contenido
application/json

Respuestas
Tipo de contenido
application/json

Respuestas
Tipo de contenido
application/json

Respuestas
Tipo de contenido
application/json

Respuestas
Tipo de contenido
application/octet-stream