Bevor Sie beginnen

Dieser Leitfaden hilft Ihnen bei den ersten Schritten mit der Reports API. Ausführliche Informationen finden Sie in der Übersicht und API-Referenz.

Zu diesem Thema

Wählen Sie Ihren Ansatz

Die Reports API bietet zwei Methoden zum Abrufen Ihrer Aktivitätsdatensätze, die jeweils für unterschiedliche Abfragemuster und Datenmengen optimiert sind.

Synchron (in Echtzeit)

Der synchrone Ansatz eignet sich am besten für häufige Abfragen, bei denen bis zu Zehntausende von Datensätzen abgerufen werden. Bei einer synchronen Abfrage werden die Datensätze sofort in der API-Antwort zurückgegeben, was sie ideal für Echtzeit-Dashboards und Überwachungssysteme macht. Diese Methode unterstützt auch die Abfrage nach bestimmten Nachrichten- oder Datensatz-IDs, was nützlich ist, wenn Sie einzelne Transaktionen nachschlagen müssen. Obwohl sie für kleinere Datensätze effizient ist, empfehlen wir, synchrone Abfragen auf Tausende von Datensätzen pro Anfrage zu beschränken, um eine optimale Leistung zu gewährleisten.

Beispiel für einen Anwendungsfall: Abrufen des aktuellen SMS-Versandstatus für eine bestimmte Kampagne.

Asynchron (Hintergrundverarbeitung)

Bei größeren Datenanforderungen ist der asynchrone Ansatz für seltene Abfragen gedacht, bei denen Millionen von Datensätzen abgerufen werden müssen. Anstatt die Daten sofort zurückzugeben, erzeugt diese Methode eine herunterladbare ZIP-Datei mit CSV-Daten, während die Verarbeitung im Hintergrund erfolgt. Der Generierungsprozess dauert in der Regel 5-10 Minuten pro 1 Million Datensätze. Sie können entweder eine Callback-URL angeben, um eine Benachrichtigung zu erhalten, wenn die Verarbeitung abgeschlossen ist, oder regelmäßig den Status des Berichts abfragen. Um eine optimale Leistung zu gewährleisten, empfiehlt Vonage, asynchrone Abfragen auf maximal 7 Millionen Datensätze zu beschränken, indem Sie entsprechende Start- und Enddaten festlegen.

Beispiel für einen Anwendungsfall: Erstellen Sie einen monatlichen Bericht über alle Sprachanrufe.

Ihre erste Anfrage stellen

Beispiel für eine synchrone Anfrage

Abrufen von SMS-Datensätzen für einen bestimmten Datumsbereich:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=YOUR_ACCOUNT_ID&product=SMS&direction=outbound&date_start=2026-01-01T00:00:00Z&date_end=2026-01-06T23:59:59Z"

Beispiel einer asynchronen Anfrage

Erstellen Sie einen Bericht über alle im Dezember gesendeten Nachrichten:

curl -X POST "https://api.nexmo.com/v2/reports" \ -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "product": "MESSAGES", "account_id": "YOUR_ACCOUNT_ID", "direction": "outbound", "date_start": "2025-12-01T00:00:00Z", "date_end": "2025-12-31T23:59:59Z", "callback_url": "https://your-domain.com/reports/callback" }'

Authentifizierung

Für alle Reports API-Anfragen ist eine HTTP-Basisauthentifizierung mit Ihrem API-Schlüssel und -Geheimnis erforderlich:

-u "$VONAGE_API_KEY:$VONAGE_API_SECRET"

Ersetzen Sie $VONAGE_API_KEY und $VONAGE_API_SECRET mit Ihren Anmeldeinformationen aus dem Vonage Dashboard.

Gemeinsame Parameter

Diese Parameter werden bei den meisten Reports API-Aufrufen verwendet:

Parameter Erforderlich Beschreibung Beispiel
account_id Ihr Vonage API-Schlüssel (Account-ID) abcd1234
product Das abzufragende Vonage-Produkt SMS, MESSAGES, VOICE-CALL
date_start 🔸 Beginn des Datumsbereichs (ISO-8601-Format) 2026-01-01T00:00:00Z
date_end 🔸 Ende des Datumsbereichs (ISO-8601-Format) 2026-01-06T23:59:59Z
direction 🔸 Nachricht/Rufrichtung inbound oder outbound
id 🔸 Bestimmte Nachrichten- oder Datensatz-ID (nur Synchronisierung) Kann nicht mit Datumsbereich verwendet werden

Legende: = immer erforderlich | 🔸 = fakultativ oder produktspezifisch

Anforderungen an das Datumsformat

Die Daten müssen im ISO-8601-Format vorliegen:

  • UTC-Format: 2026-01-01T00:00:00Z
  • Mit Zeitzonenverschiebung: 2026-01-01T08:00:00+0800

Das ist wichtig: Bei der Verwendung von GET Anfragen mit + in Daten, URL-Kodierung der Daten:

curl -G --data-urlencode date_start="2026-01-01T08:00:00+0000" \ --data-urlencode date_end="2026-01-01T14:00:00+0000" \ -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=abcd1234&product=SMS&direction=outbound"

Abfrage nach ID vs. Datumsbereich

  • Nach ID: Abrufen eines bestimmten Datensatzes (nur synchron)
  • Nach Datumsbereich: Alle Datensätze innerhalb eines bestimmten Zeitraums abrufen
  • Sie können nicht beides verwenden: Wählen Sie entweder id OR date_start/date_end, nicht beides

Produktspezifische Parameter

Verschiedene Produkte unterstützen unterschiedliche Parameter. In diesem Abschnitt werden die erforderlichen und optionalen Parameter für jedes Produkt aufgeführt. Die vollständigen Parameterspezifikationen und Antwortformate finden Sie in der API-Referenz.

SMS

Erforderliche Parameter:

  • product - Eingestellt auf SMS
  • account_id - Ihr Vonage API-Schlüssel
  • direction - Sie müssen entweder inbound oder outbound

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)
  • status - Filter nach Lieferstatus (z.B., delivered, failed, expired)
  • from - Nummer des Absenders
  • to - Nummer des Empfängers
  • country - Filter nach Ländercode
  • network - Filter nach Netzwerk MCC-MNC
  • client_ref - Ihre Kundenreferenz
  • account_ref - Account-Referenz
  • include_message - Nachrichtentext in die Antwort einschließen (true/false)

Beispiel:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/records?account_id=abcd1234&product=SMS&direction=outbound&status=delivered&date_start=2026-01-01T00:00:00Z&date_end=2026-01-06T23:59:59Z"

SMS-VERKEHRSKONTROLLE

Erforderliche Parameter:

  • product - Eingestellt auf SMS-TRAFFIC-CONTROL
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

NACHRICHTEN

Erforderliche Parameter:

  • product - Eingestellt auf MESSAGES
  • account_id - Ihr Vonage API-Schlüssel
  • direction - Sie müssen entweder inbound oder outbound

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)
  • status - Filter nach Lieferstatus (z.B., submitted, delivered, read, rejected)
  • from - Kennung des Absenders
  • to - Kennung des Empfängers
  • provider - Filter nach Kanal (z.B., whatsapp, sms, mms, viber_service_msg, messenger, instagram, rcs)
  • include_message - Nachrichtentext in die Antwort einschließen (true/false)

VOICE-CALL

Erforderliche Parameter:

  • product - Eingestellt auf VOICE-CALL
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • direction - Rufrichtung (inbound oder outbound)
  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)
  • status - Anrufstatus (z.B., ANSWERED, MACHINE, ERROR)
  • from - Rufnummer des Anrufers
  • to - Angerufene Nummer
  • country - Filter nach Ländercode
  • network - Filter nach Netzwerk MCC-MNC
  • call_id - Spezifische Kennung des Anrufs

IN-APP-VOICE

Erforderliche Parameter:

  • product - Eingestellt auf IN-APP-VOICE
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)
  • status - Status der Anrufbeendigung
  • conversation_id - Konversations-ID
  • leg_id - Bestimmte Teilstrecke eines Anrufs

VOICE-TTS

Erforderliche Parameter:

  • product - Eingestellt auf VOICE-TTS
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

VOICE-FAILED

Erforderliche Parameter:

  • product - Eingestellt auf VOICE-FAILED
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • direction - Rufrichtung (inbound oder outbound)
  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • from - Rufnummer des Anrufers
  • to - Angerufene Nummer
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)
  • country - Ländercode-Filter

WEBSOCKET-AUFRUF

Erforderliche Parameter:

  • product - Eingestellt auf WEBSOCKET-CALL
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

ASR

Erforderliche Parameter:

  • product - Eingestellt auf ASR
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • direction - Rufrichtung (inbound oder outbound)
  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • from - Anrufer-ID
  • to - Angerufene Numbers
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

AMD

Erforderliche Parameter:

  • product - Eingestellt auf AMD
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

VERIFY-API

Erforderliche Parameter:

  • product - Eingestellt auf VERIFY-API
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)
  • to - Telefonnummer, die verifiziert wurde
  • network - Filter nach Netzwerk MCC-MNC

VERIFY-V2

Erforderliche Parameter:

  • product - Eingestellt auf VERIFY-V2
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • channel - Prüfungskanal (v2, email, silent_auth)
  • status - Status der Anfrage
  • parent_request_id - Filter nach übergeordneter Anfrage-ID, die v2-Verifizierungsanfragen mit den zugehörigen E-Mail- oder silent_auth-Ereignissen korreliert
  • country - Ländercode
  • locale - Sprache/Landschaft
  • network - Code des Mobilfunknetzes
  • to - Überprüfte Rufnummer
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

NUMBER-INSIGHT

Erforderliche Parameter:

  • product - Eingestellt auf NUMBER-INSIGHT
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)
  • number - Telefonnummer, die abgefragt wurde
  • network - Code des Mobilfunknetzes

NUMBER-INSIGHT-V2

Erforderliche Parameter:

  • product - Eingestellt auf NUMBER-INSIGHT-V2
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • request_type - Art der Einsichtsanfrage (z.B., fraud_score, sim_swap)
  • risk - Stufe der Risikobewertung
  • status- Numbers Status der Inspektionsanfrage
  • swapped - ob die Nummer portiert/getauscht wurde
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

GESPRÄCHSVERANSTALTUNG

Erforderliche Parameter:

  • product - Eingestellt auf CONVERSATION-EVENT
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • conversation_id - Spezifische Gesprächs-ID
  • status - Status der Veranstaltung
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

GESPRÄCHSNACHRICHT

Erforderliche Parameter:

  • product - Eingestellt auf CONVERSATION-MESSAGE
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • conversation_id - Spezifische Gesprächs-ID
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

VIDEO-API

Erforderliche Parameter:

  • product - Eingestellt auf VIDEO-API
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • session_id - ID der Videositzung
  • meeting_id - Kennung der Sitzung
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

NETZWERK-API-EREIGNIS

Erforderliche Parameter:

  • product - Eingestellt auf NETWORK-API-EVENT
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • product_name - Spezifisches Netzwerk-API-Produkt
  • request_session_id - Sitzungsidentifikator anfordern
  • product_path - API-Produktpfad
  • correlation_id - Korrelation ID
  • request_type - Typ der Netzwerk-API-Anfrage
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

BERICHTE-USAGE

Erforderliche Parameter:

  • product - Eingestellt auf REPORTS-USAGE
  • account_id - Ihr Vonage API-Schlüssel

Zusätzliche Parameter:

  • date_start / date_end - Datumsbereich für die Filterung von Datensätzen
  • id - Spezifische Datensatz-ID (kann nicht mit Datumsbereich verwendet werden)

Anmerkung: Alle Produkte unterstützen include_subaccounts wenn Sie asynchrone Berichte erstellen, um Daten von Subaccounts einzubeziehen. Ausführliche Informationen über Antwortformate und zusätzliche Filteroptionen finden Sie in der API-Referenz.

Arbeiten mit asynchronen Berichten

Wenn Sie einen asynchronen Bericht erstellen, erhalten Sie eine request_id um den Status des Berichts zu verfolgen:

Beispiel für eine Antwort:

{
  "request_id": "ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e",
  "request_status": "PENDING",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcd1234",
  "date_start": "2026-01-01T00:00:00+0000",
  "date_end": "2026-01-06T23:59:59+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e"
    }
  }
}

Berichtsstatus prüfen

Verwenden Sie die request_id um zu prüfen, ob Ihr Bericht fertig ist:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v2/reports/ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e"

Vollständigen Bericht herunterladen

Wenn der Berichtsstatus SUCCESS, extrahieren Sie die file_id aus der Antwort und dem Download:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \ "https://api.nexmo.com/v3/media/FILE_ID" \ -o report.zip

Die heruntergeladene ZIP-Datei enthält eine CSV-Datei mit Ihren Datensätzen. Die Dateien sind 72 Stunden lang verfügbar.

Siehe auch