piv.day API-Referenz — Nummern, Domains, Proxys, White Pages

Zurück zur API-Übersicht .txt herunterladen

Dokumentation

Erste Schritte

REST API im Business-Tarif. Bearer-Tokens, JSON, idempotente Endpunkte, vorhersagbare Fehlercodes. Jeder Endpunkt enthält ein Anfrage- und Antwortbeispiel.

Base URL

https://app.piv.day/api/v1

Alle Endpunkte befinden sich unter diesem Präfix. Eine einzige Umgebung — keine separaten Staging-Hosts.

Authentifizierung

Authorization: Bearer YOUR_API_KEY

Schlüssel werden im Dashboard unter Einstellungen → API Keys erstellt. Jeder Schlüssel hat feingranulare Berechtigungen (Nummern lesen, SMS senden, Proxies kaufen usw.). Ein kompromittierter Token wird mit einem Klick rotiert — kein erneutes Onboarding des Teams erforderlich.

Konto

GET/api/v1/account

curl https://app.piv.day/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Ein einzelner Hilfs-Endpunkt — Kontostand und E-Mail des aktuellen Kontos. Praktisch zur Überprüfung, dass der Schlüssel funktioniert und die Authentifizierung korrekt eingerichtet ist.

{
  "success": true,
  "data": {
    "user_id": "usr-uuid-...",
    "balance": 150.50,
    "email": "u***@example.com",
    "team_id": null,
    "is_team_member": false
  }
}

GET /api/v1/account

Antwortformat

{
  "success": true,
  "data": { ... }
}

Alle Antworten sind JSON. Bei einem Fehler ist success = false und der Body enthält error.code und error.message.

Rate limits

100 Anfragen pro Minute pro API-Schlüssel. Das Limit gilt übergreifend für alle Endpunkte. Benötigen Sie mehr Spielraum für einen Lastspike? Schreiben Sie dem Telegram-Support und wir erhöhen das Limit. Bei Überschreitung erhalten Sie `429 RATE_LIMITED` und den `Retry-After`-Header — wie viele Sekunden bis zur nächsten Anfrage gewartet werden soll.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded, retry in 12s"
  }
}

429 Too Many Requests

Dokumentation

Nummern

Nummern kaufen, verlängern und wiederherstellen. SMS empfangen und senden. Google QR-Verifizierungen starten. Über Webhooks Ereignisse abonnieren.

Länder und Preise

GET/api/v1/numbers/countries

Gibt zum Kauf verfügbare Länder mit aktuellem Preis und SMS-Funktionen zurück. Alle Preise beinhalten den Rabatt Ihres Abonnements.

Antwortfelder

Feld	Typ	Beschreibung
`country_code`	string	Zweistelliger ISO-Ländercode (z. B. `SE`).
`price_per_month`	number	Endpreis für Ihren Tarif — was tatsächlich beim Kauf berechnet wird. Premium / Business-Rabatte sind bereits eingerechnet.
`base_price`	number	Preis ohne Rabatte (Free-Tarif). Wird zum Vergleich zurückgegeben, um zu sehen, wie viel das Abonnement spart.
`can_send_sms`	boolean	Ob ausgehende SMS von dieser Nummer unterstützt werden.
`can_receive_sms`	boolean	Ob eingehende SMS unterstützt werden.
`sms_send_price`	number\|null	Preis für ausgehende SMS, ebenfalls mit dem Tarifrabatt. `null`, wenn das Senden aus diesem Land nicht unterstützt wird.

GET/api/v1/numbers/countries

curl https://app.piv.day/api/v1/numbers/countries \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": [
    {
      "country_code": "SE",
      "price_per_month": 4.00,
      "base_price": 5.00,
      "can_send_sms": true,
      "can_receive_sms": true,
      "sms_send_price": 0.25
    },
    {
      "country_code": "GB",
      "price_per_month": 3.00,
      "base_price": 3.00,
      "can_send_sms": true,
      "can_receive_sms": true,
      "sms_send_price": 0.20
    }
  ]
}

Nummernliste des Kontos

GET/api/v1/numbers

Gibt eine Seite der Kontonummern mit Filtern nach Land, Status und Suche nach Nummer oder benutzerdefiniertem Namen zurück.

Query-Parameter

Feld	Typ	Beschreibung
`limit`	integer	Seitengröße (Standard 50, maximal 200).
`offset`	integer	Paginierungs-Offset.
`country`	string	ISO-Ländercode-Filter.
`status`	string	Einer von `active`, `expired`, `pending_restore`.
`search`	string	Teilzeichenkettensuche nach Telefonnummer oder benutzerdefiniertem Namen.

GET/api/v1/numbers

curl "https://app.piv.day/api/v1/numbers?country=SE&status=active&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "numbers": [
      {
        "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
        "phone_number": "+46764794425",
        "country_code": "SE",
        "status": "active",
        "created_at": "2026-05-01T10:00:00Z",
        "expires_at": "2026-05-31T10:00:00Z",
        "auto_renew": false,
        "custom_name": "Office line",
        "purchased_at": "2026-05-01T10:00:00Z",
        "next_renewal_date": "2026-05-31T10:00:00Z",
        "tags": ["support"],
        "can_send_sms": true,
        "can_receive_sms": true
      }
    ],
    "pagination": { "total": 1, "limit": 10, "offset": 0 }
  }
}

Einzelne Nummer per ID

GET/api/v1/numbers/{piv_num_id}

Vollständiger Nummernдатensatz: Status, Daten, Auto-Verlängerung, Tags, erlaubte SMS-Richtungen.

Fehler

Code	HTTP	Wann ausgelöst
`NUMBER_NOT_FOUND`	404	Nummer nicht gefunden oder gehört nicht zum Konto.

GET/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o

curl https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "country_code": "SE",
    "status": "active",
    "created_at": "2026-05-01T10:00:00Z",
    "expires_at": "2026-05-31T10:00:00Z",
    "auto_renew": false,
    "custom_name": "Office line",
    "purchased_at": "2026-05-01T10:00:00Z",
    "next_renewal_date": "2026-05-31T10:00:00Z",
    "tags": ["support"],
    "can_send_sms": true,
    "can_receive_sms": true
  }
}

Nummer kaufen

POST/api/v1/numbers/purchase

Kauft eine einzelne Nummer im gewählten Land für den angegebenen Zeitraum. Der Betrag wird vom Kontoguthaben abgezogen. Gibt piv_num_id zurück, das in allen weiteren Nummernoperationen verwendet wird.

Anfrage-Body

Feld	Typ	Beschreibung
`country_code`*	string	ISO-Ländercode.
`duration_months`*	integer	Mietdauer in Monaten (Minimum 1).
`auto_renew`*	boolean	Auto-Verlängerung direkt nach dem Kauf aktivieren.
`custom_name`	string	Optionaler, lesbarer Name für die Nummer.

Fehler

Code	HTTP	Wann ausgelöst
`COUNTRY_NOT_AVAILABLE`	400	Land nicht verfügbar oder keine Preise vorhanden.
`NO_NUMBERS_AVAILABLE`	400	Derzeit keine freien Nummern im angeforderten Land verfügbar.
`INSUFFICIENT_BALANCE`	402	Nicht genügend Guthaben für den Kauf.
`VALIDATION_ERROR`	400	Ungültige Felder im Anfrage-Body.

POST/api/v1/numbers/purchase

curl -X POST https://app.piv.day/api/v1/numbers/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "SE",
    "duration_months": 1,
    "auto_renew": false,
    "custom_name": "My Sweden Number"
  }'

200OK

{
  "success": true,
  "cost": 5.00,
  "numbers": [
    {
      "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
      "country_code": "SE",
      "phone_number": "+46764794425",
      "created_at": "2026-05-01T10:00:00Z",
      "expires_at": "2026-05-31T10:00:00Z",
      "auto_renew": false,
      "custom_name": "My Sweden Number"
    }
  ]
}

Nummer verlängern

POST/api/v1/numbers/{piv_num_id}/renew

Verlängert eine aktive Nummer für den angegebenen Zeitraum. Der Betrag wird beim Aufruf abgezogen.

Anfrage-Body

Feld	Typ	Beschreibung
`duration_months`*	integer	Anzahl der Monate, um die verlängert werden soll.

Fehler

Code	HTTP	Wann ausgelöst
`NUMBER_NOT_FOUND`	404	Nummer nicht gefunden oder gehört nicht zum Konto.
`COUNTRY_NOT_AVAILABLE`	400	Keine Preise für das Land der Nummer gefunden.
`INSUFFICIENT_BALANCE`	402	Nicht genügend Guthaben für die Verlängerung.

POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/renew

curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "duration_months": 1 }'

200OK

{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "old_expires_at": "2026-05-31T10:00:00Z",
    "new_expires_at": "2026-06-30T10:00:00Z",
    "cost": 5.00
  }
}

Nummer aktualisieren

PATCH/api/v1/numbers/{piv_num_id}

Derzeit kann nur der benutzerdefinierte Name aktualisiert werden.

Anfrage-Body

Feld	Typ	Beschreibung
`custom_name`*	string	Neuer Name für die Nummer.

Fehler

Code	HTTP	Wann ausgelöst
`NUMBER_NOT_FOUND`	404	Nummer nicht gefunden oder gehört nicht zum Konto.
`VALIDATION_ERROR`	400	Ungültiger Wert im Anfrage-Body.

PATCH/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o

curl -X PATCH https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_name": "Support line" }'

200OK

{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "country_code": "SE",
    "status": "active",
    "custom_name": "Support line",
    "auto_renew": false,
    "expires_at": "2026-05-31T10:00:00Z",
    "tags": []
  }
}

Auto-Verlängerung verwalten

PATCH/api/v1/numbers/{piv_num_id}/auto-renewal

Schaltet die automatische Verlängerung der Nummer ein oder aus. Wenn aktiviert, wird die Verlängerung automatisch 24 Stunden vor Ablauf abgebucht. Bei fehlendem Guthaben läuft die Nummer ab; Sie können sie über POST /numbers/restore innerhalb von 7 Tagen zurückfordern.

Anfrage-Body

Feld	Typ	Beschreibung
`auto_renew`*	boolean	Neuer Wert des Auto-Verlängerungs-Flags.

PATCH/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/auto-renewal

curl -X PATCH https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/auto-renewal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auto_renew": true }'

200OK

{
  "success": true,
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "phone_number": "+46764794425",
    "auto_renew": true
  }
}

Abgelaufene Nummern wiederherstellen

POST/api/v1/numbers/restore

Stellt abgelaufene Nummern innerhalb eines 7-Tage-Fensters wieder her. Übergeben Sie ein Array von piv_num_id — Nummern kehren mit SMS-Verlauf und gespeicherten Einstellungen zurück. Die Wiederherstellung kostet mehr als der Kauf einer neuen Nummer (enthält einen Wiederherstellungs-Multiplikator) — genaue Zahlen erscheinen vor der Bestätigung im Dashboard. Der endgültige Status jeder Nummer kommt über den number.restore_completed-Webhook; Rückerstattungen für erfolglose Nummern werden automatisch gutgeschrieben.

Anfrage-Body

Feld	Typ	Beschreibung
`piv_num_ids`*	string[]	Array der Nummern-IDs zur Wiederherstellung.

Fehler

Code	HTTP	Wann ausgelöst
`NO_RESTORABLE_NUMBERS`	404	Keine der angegebenen Nummern kann wiederhergestellt werden (7-Tage-Fenster abgelaufen oder nicht Ihre).
`INSUFFICIENT_BALANCE`	402	Nicht genügend Guthaben für die Wiederherstellung.

POST/api/v1/numbers/restore

curl -X POST https://app.piv.day/api/v1/numbers/restore \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "piv_num_ids": [
      "vzPA1-kHKSg-EAL7e-Jqd3o",
      "abc12-defgh-ijklm-nopqr"
    ]
  }'

200OK

{
  "success": true,
  "queued": 2,
  "skipped": 0,
  "total_charged": 9.00,
  "numbers": [
    {
      "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
      "phone_number": "+46764794425",
      "status": "pending"
    }
  ]
}

SMS-Verlauf für Nummer

GET/api/v1/numbers/{piv_num_id}/sms

Gibt ein- und ausgehende Nachrichten für die Nummer in umgekehrter chronologischer Reihenfolge zurück.

Query-Parameter

Feld	Typ	Beschreibung
`limit`	integer	Wie viele Nachrichten zurückgegeben werden sollen (Standard 50, max. 200).
`offset`	integer	Paginierungs-Offset.

GET/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms

curl "https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "42",
        "from_number": "+46764794425",
        "to_number": "+14155551234",
        "message_body": "Hello from piv.day",
        "direction": "outbound",
        "status": "delivered",
        "received_at": "2026-05-22T11:30:00Z"
      },
      {
        "id": "41",
        "from_number": "+14155551234",
        "to_number": "+46764794425",
        "message_body": "Hey, got your message!",
        "direction": "inbound",
        "status": "received",
        "received_at": "2026-05-22T11:35:00Z"
      }
    ],
    "pagination": { "total": 2, "limit": 20, "offset": 0 }
  }
}

SMS senden

POST/api/v1/numbers/{piv_num_id}/sms/send

Verfügbar für Länder, in denen ausgehende Nachrichten erlaubt sind (z. B. CA, GB, SE). Die Nachrichtenkosten werden beim Senden abgebucht.

Anfrage-Body

Feld	Typ	Beschreibung
`to_number`*	string	Empfängernummer im internationalen Format (E.164).
`message_body`*	string	Nachrichtentext. GSM-7 und UCS-2 werden unterstützt.

Fehler

Code	HTTP	Wann ausgelöst
`NUMBER_NOT_FOUND`	404	Nummer nicht gefunden oder gehört nicht zum Konto.
`NUMBER_EXPIRED`	403	Nummer ist bereits abgelaufen.
`NUMBER_NOT_ACTIVE`	400	Nummer befindet sich in einem Zustand, der das Senden nicht erlaubt.
`INSUFFICIENT_BALANCE`	402	Nicht genügend Guthaben zum Senden.
`INVALID_MESSAGE_FORMAT`	400	Nachrichteninhalt überschreitet die zulässige Länge oder enthält verbotene Zeichen.

POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms/send

curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+14155551234",
    "message_body": "Hello from piv.day"
  }'

200OK

{
  "success": true,
  "data": {
    "message_id": "42",
    "from_number": "+46764794425",
    "to_number": "+14155551234",
    "message_body": "Hello from piv.day",
    "status": "queued",
    "created_at": "2026-05-22T11:30:00Z"
  }
}

Google QR-Verifizierung starten

POST/api/v1/numbers/{piv_num_id}/verify

Startet eine Google QR-Verifizierung mit der angegebenen URL. Das Ergebnis — Erfolg oder Fehler — kommt über den Webhook verify.completed oder verify.failed. Der Betrag wird beim Einreihen der Aufgabe abgebucht.

Anfrage-Body

Feld	Typ	Beschreibung
`gv_url`*	string	Vollständige Google-Verifizierungs-URL (von der Google-Seite kopiert).

Fehler

Code	HTTP	Wann ausgelöst
`NUMBER_NOT_FOUND`	404	Nummer nicht gefunden oder gehört Ihnen nicht.
`NUMBER_NOT_ACTIVE`	400	Nummer ist nicht aktiv.
`SMS_DISABLED`	400	SMS-Versand ist für diese Nummer deaktiviert.
`INSUFFICIENT_BALANCE`	402	Nicht genügend Guthaben für die Verifizierung.
`PROXY_DEAD`	502	Proxy nicht verfügbar — Guthaben zurückerstattet.
`QUEUE_FULL`	503	Warteschlange voll, später nochmals versuchen — Guthaben zurückerstattet.
`SERVER_UNAVAILABLE`	503	Automatisierungsserver nicht verfügbar — Guthaben zurückerstattet.

POST/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/verify

curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gv_url": "https://gv.google.com/..." }'

202Accepted

{
  "success": true,
  "message": "Verification initiated"
}

Dokumentation

Proxy

Residential-IPv6 in Dutzenden Ländern. Massenkauf, Verlängerung, Restore mit gleichem Login und Passwort, Export im gewünschten Format.

Serverliste

GET/api/v1/proxy/servers

Verfügbare Proxy-Server mit Preisen.

GET/api/v1/proxy/servers

curl https://app.piv.day/api/v1/proxy/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "EU-DE-01",
        "country": "DE",
        "socks5_port": 1080,
        "http_port": 3128,
        "price_per_proxy": 0.50
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "EU-NL-01",
        "country": "NL",
        "socks5_port": 1080,
        "http_port": 3128,
        "price_per_proxy": 0.45
      }
    ]
  }
}

Bestellliste

GET/api/v1/proxy/orders

Liste deiner Proxy-Bestellungen mit Filterung nach Status oder Suche.

Query-Parameter

Feld	Typ	Beschreibung
`limit`	integer	Seitengröße. Standard 100, Maximum 500.
`offset`	integer	Paginierungsversatz.
`status`	string	Statusfilter: `active`, `expired`.
`search`	string	Bestellungen durchsuchen.

GET/api/v1/proxy/orders

curl "https://app.piv.day/api/v1/proxy/orders?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ord-uuid-...",
        "country": "DE",
        "quantity": 10,
        "price_per_proxy": 0.50,
        "price_total": 5.00,
        "status": "active",
        "purchased_at": "2026-01-01T00:00:00Z",
        "expires_at": "2026-02-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Eine Bestellung abrufen

GET/api/v1/proxy/orders/{id}

Details einer bestimmten Bestellung abrufen, einschließlich der Liste der Proxy-Zugangsdaten.

GET/api/v1/proxy/orders/ord-uuid-...

curl https://app.piv.day/api/v1/proxy/orders/ord-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "order": {
      "id": "ord-uuid-...",
      "country": "DE",
      "quantity": 10,
      "price_per_proxy": 0.50,
      "price_total": 5.00,
      "status": "active",
      "purchased_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-02-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "items": [
        {
          "login": "user1",
          "password": "pass1",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::1"
        }
      ]
    }
  }
}

Proxys kaufen

POST/api/v1/proxy/purchase

Proxys auf dem gewählten Server kaufen. Eine Anfrage erstellt eine Bestellung mit N Proxys (bis zu 500). Es gibt keine Bulk-Bestellungen — rufe die Methode erneut auf, wenn du mehr benötigst.

Anfrage-Body

Feld	Typ	Beschreibung
`server_id`*	string	Server-ID aus `GET /proxy/servers`.
`quantity`*	integer	Anzahl der zu kaufenden Proxys (1–500).
`months`*	integer	Mietdauer in Monaten (1–12).

Fehler

Code	HTTP	Wann ausgelöst
`INSUFFICIENT_BALANCE`	402	Nicht genug Guthaben.
`NOT_FOUND`	404	Proxy-Server nicht gefunden oder inaktiv.
`VALIDATION_ERROR`	400	Ungültiger Anfrage-Body.

POST/api/v1/proxy/purchase

curl -X POST https://app.piv.day/api/v1/proxy/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "quantity": 5,
    "months": 1
  }'

200OK

{
  "success": true,
  "data": {
    "order": {
      "id": "ord-uuid-...",
      "country": "DE",
      "quantity": 5,
      "price_total": 2.50,
      "status": "active",
      "expires_at": "2026-02-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "items": [
        {
          "login": "user1",
          "password": "pass1",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::1"
        },
        {
          "login": "user2",
          "password": "pass2",
          "host": "185.1.2.3",
          "socks5_port": 1080,
          "http_port": 3128,
          "ipv6": "2a00:1:2:3::2"
        }
      ]
    }
  }
}

Bestellung verlängern

POST/api/v1/proxy/orders/{id}/renew

Eine aktive Proxy-Bestellung um eine bestimmte Anzahl von Monaten verlängern.

Anfrage-Body

Feld	Typ	Beschreibung
`months`*	integer	Anzahl der hinzuzufügenden Monate.

POST/api/v1/proxy/orders/ord-uuid-.../renew

curl -X POST https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "months": 1 }'

200OK

{
  "success": true,
  "data": {
    "order_id": "ord-uuid-...",
    "cost": 5.00,
    "new_expires_at": "2026-03-01T00:00:00Z"
  }
}

Abgelaufene Bestellung wiederherstellen

POST/api/v1/proxy/orders/{id}/restore

Eine abgelaufene Proxy-Bestellung ohne Neukauf reaktivieren. Login, Passwort, IPv6-Adressen, Land und Bindungen bleiben dieselben. Die Laufzeit wird um 1 Monat verlängert. Eine Neukonfiguration des Antidetect-Browsers ist nicht nötig.

POST/api/v1/proxy/orders/ord-uuid-.../restore

curl -X POST https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../restore \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "order_id": "ord-uuid-...",
    "quantity": 10,
    "total_cost": 5.00,
    "expires_at": "2026-03-01T00:00:00Z"
  }
}

Proxys exportieren

GET/api/v1/proxy/orders/{id}/export

Die Proxy-Zugangsdaten der Bestellung als Textliste exportieren (login:password@host:port).

Query-Parameter

Feld	Typ	Beschreibung
`format`	string	Exportformat: `socks5`, `http` oder `both` (Standard `socks5`).

GET/api/v1/proxy/orders/ord-uuid-.../export

curl "https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../export?format=socks5" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "content": "user1:[email protected]:1080\nuser2:[email protected]:1080",
    "filename": "piv-day-proxy-ord-uuid--socks5.txt",
    "format": "socks5",
    "count": 2
  }
}

Dokumentation

Domains

Suche und Registrierung ohne KYC, automatisches Cloudflare und SSL, Verwaltung von DNS-Einträgen und Nameservern über die API.

Verfügbarkeitsprüfung

GET/api/v1/domains/search

Prüfen, ob eine Domain verfügbar ist und wie viel die Registrierung kostet.

Query-Parameter

Feld	Typ	Beschreibung
`q`*	string	Zu suchender Domainname, z. B. `mysite.com`.

GET/api/v1/domains/search

curl "https://app.piv.day/api/v1/domains/search?q=mysite.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "domain": "mysite.com",
    "available": true,
    "create_price": 12.50,
    "renew_price": 12.50,
    "currency": "USD"
  }
}

Domains auflisten

GET/api/v1/domains

Liste Ihrer registrierten Domains mit Filtermöglichkeit.

Query-Parameter

Feld	Typ	Beschreibung
`limit`	integer	Seitengröße. Standard 100, Maximum 500.
`offset`	integer	Offset für die Paginierung.
`status`	string	Domain-Status: `active`, `pending`, `expired`.
`cloudflare`	string	Nach Cloudflare-Status filtern: `true` oder `false`.
`auto_renew`	string	Nach automatischer Verlängerung filtern: `true` oder `false`.
`search`	string	Suche nach Domainname.

GET/api/v1/domains

curl "https://app.piv.day/api/v1/domains?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "dom-uuid-...",
        "domain_name": "mysite.com",
        "status": "active",
        "registered_at": "2026-01-01T00:00:00Z",
        "expires_at": "2027-01-01T00:00:00Z",
        "auto_renew": true,
        "cloudflare_enabled": true,
        "cloudflare_status": "active",
        "ssl_type": "lets_encrypt",
        "ssl_status": "active",
        "ssl_mode": "full",
        "ssl_expires_at": "2026-04-01T00:00:00Z",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Domain registrieren

POST/api/v1/domains

Eine neue Domain registrieren. Die Anfrage ist asynchron — gibt queue_id zur Nachverfolgung zurück. Cloudflare EIN: nameservers nicht übergeben; optional können dns_records und ssl_mode übergeben werden. Cloudflare AUS: dns_records und ssl_mode nicht übergeben; nameservers ist erforderlich (mindestens 2). Cloudflare-Nameserver geben wir nie preis.

Anfrage-Body

Feld	Typ	Beschreibung
`domain`*	string	Zu registrierender Domainname, z. B. `mysite.com`.
`period`*	integer	Registrierungsdauer in Jahren (1–10).
`cloudflare`*	boolean	Die Domain automatisch mit Cloudflare verbinden.
`auto_renew`*	boolean	Automatische Verlängerung aktivieren.
`ssl_mode`	string	`flexible` \| `full` \| `strict`. Nur bei `cloudflare: true`.
`nameservers`	string[]	Erforderlich bei `cloudflare: false` (≥2 NS). Verboten bei `cloudflare: true`.
`dns_records`	object[]	Initiale DNS-Einträge. Nur bei `cloudflare: true`.

Fehler

Code	HTTP	Wann ausgelöst
`DOMAIN_NOT_AVAILABLE`	400	Domain ist nicht für die Registrierung verfügbar.
`INSUFFICIENT_BALANCE`	402	Nicht genügend Guthaben.
`VALIDATION_ERROR`	400	Ungültiger Anfrage-Body.

POST/api/v1/domains

curl -X POST https://app.piv.day/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mysite.com",
    "period": 1,
    "cloudflare": true,
    "auto_renew": true,
    "ssl_mode": "full",
    "dns_records": [
      { "type": "A", "name": "@", "content": "1.2.3.4", "proxied": true }
    ]
  }'

POST/api/v1/domains

curl -X POST https://app.piv.day/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mysite.com",
    "period": 1,
    "cloudflare": false,
    "auto_renew": false,
    "nameservers": ["ns1.myhost.com", "ns2.myhost.com"]
  }'

202Accepted

{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "purchasing",
      "period": 1,
      "cloudflare_enabled": true,
      "auto_renew": true,
      "ssl_mode": "full",
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Registrierungswarteschlangen-Status

GET/api/v1/domains/queue/{id}

Den Status eines Registrierungs- oder Verlängerungs-Warteschlangeneintrags prüfen. Bei Status completed enthält die Antwort bereits die vollständige Domain-Karte — ein separater Aufruf an /domains/{id} ist nicht nötig.

GET/api/v1/domains/queue/que-uuid-...

curl https://app.piv.day/api/v1/domains/queue/que-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

pending / processing

{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain": "mysite.com",
    "status": "pending"
  }
}

completed — vollständige Karte

{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "status": "completed",
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "active",
      "registered_at": "2026-01-01T12:00:00Z",
      "expires_at": "2027-01-01T12:00:00Z",
      "auto_renew": true,
      "cloudflare_enabled": true,
      "cloudflare_status": "active",
      "ssl_type": "lets_encrypt",
      "ssl_status": "active",
      "ssl_mode": "full",
      "ssl_expires_at": "2026-04-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T12:00:00Z",
      "dns_records": [
        { "name": "@", "type": "A", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true }
      ]
    }
  }
}

Eine Domain abrufen

GET/api/v1/domains/{id}

Vollständige Informationen zu einer registrierten Domain abrufen. Das Feld nameservers ist nur vorhanden, wenn cloudflare_enabled: false.

GET/api/v1/domains/dom-uuid-...

curl https://app.piv.day/api/v1/domains/dom-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "domain": {
      "id": "dom-uuid-...",
      "domain_name": "mysite.com",
      "status": "active",
      "registered_at": "2026-01-01T12:00:00Z",
      "expires_at": "2027-01-01T12:00:00Z",
      "auto_renew": true,
      "cloudflare_enabled": true,
      "cloudflare_status": "active",
      "ssl_type": "lets_encrypt",
      "ssl_status": "active",
      "ssl_mode": "full",
      "ssl_expires_at": "2026-04-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T12:00:00Z",
      "dns_records": [
        { "name": "@", "type": "A", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true },
        { "name": "www", "type": "CNAME", "content": "mysite.com", "ttl": 1, "priority": null, "proxied": true }
      ]
    }
  }
}

Domain verlängern

POST/api/v1/domains/{id}/renew

Die Domain-Registrierung verlängern. Gibt queue_id zur Nachverfolgung zurück.

Anfrage-Body

Feld	Typ	Beschreibung
`period`*	integer	Anzahl der Jahre, um die verlängert wird.

POST/api/v1/domains/dom-uuid-.../renew

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "period": 1 }'

202Accepted

{
  "success": true,
  "data": {
    "queue_id": "que-uuid-...",
    "domain_id": "dom-uuid-...",
    "expires_at": "2027-01-01T12:00:00Z"
  }
}

Auto-Verlängerung umschalten

POST/api/v1/domains/{id}/auto-renew

Die automatische Verlängerung der Domain ein- oder ausschalten.

Anfrage-Body

Feld	Typ	Beschreibung
`auto_renew`*	boolean	Neuer Wert des Flags.

POST/api/v1/domains/dom-uuid-.../auto-renew

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../auto-renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auto_renew": true }'

200OK

{
  "success": true,
  "data": {
    "id": "dom-uuid-...",
    "auto_renew": true
  }
}

DNS-Einträge der Domain

GET/api/v1/domains/{id}/dns

DNS-Einträge der Domain auflisten (über Cloudflare).

GET/api/v1/domains/dom-uuid-.../dns

curl https://app.piv.day/api/v1/domains/dom-uuid-.../dns \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "records": [
      {
        "id": "rec-uuid-...",
        "type": "A",
        "name": "@",
        "content": "1.2.3.4",
        "ttl": 1,
        "priority": null,
        "proxied": true
      }
    ]
  }
}

DNS-Eintrag hinzufügen

POST/api/v1/domains/{id}/dns

Einen neuen DNS-Eintrag erstellen.

Anfrage-Body

Feld	Typ	Beschreibung
`type`*	string	Eintragstyp: `A`, `AAAA`, `CNAME`, `MX`, `TXT` usw.
`name`*	string	Name des Eintrags, z. B. `@` oder `subdomain`.
`content`*	string	Wert des Eintrags.
`ttl`	integer	TTL in Sekunden (`1` = automatisch).
`proxied`	boolean	Über Cloudflare weiterleiten.

POST/api/v1/domains/dom-uuid-.../dns

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../dns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "content": "1.2.3.4",
    "ttl": 1,
    "proxied": true
  }'

201Created

{
  "success": true,
  "data": {
    "record": {
      "id": "rec-uuid-...",
      "type": "A",
      "name": "@",
      "content": "1.2.3.4",
      "ttl": 1,
      "priority": null,
      "proxied": true
    }
  }
}

DNS-Eintrag aktualisieren

PUT/api/v1/domains/{id}/dns/{recordId}

Einen vorhandenen DNS-Eintrag per ID aktualisieren. Nur die übergebenen Felder werden überschrieben.

PUT/api/v1/domains/dom-uuid-.../dns/rec-uuid-...

curl -X PUT https://app.piv.day/api/v1/domains/dom-uuid-.../dns/rec-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "5.6.7.8" }'

DNS-Eintrag löschen

DELETE/api/v1/domains/{id}/dns/{recordId}

Einen DNS-Eintrag per ID löschen.

DELETE/api/v1/domains/dom-uuid-.../dns/rec-uuid-...

curl -X DELETE https://app.piv.day/api/v1/domains/dom-uuid-.../dns/rec-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

Cloudflare aktivieren

POST/api/v1/domains/{id}/cloudflare

Cloudflare für die Domain aktivieren. Wir geben keine Cloudflare-Nameserver zurück — die Delegierung wird auf unserer Seite eingerichtet. Das Deaktivieren von Cloudflare über diesen Endpunkt wird nicht unterstützt.

POST/api/v1/domains/dom-uuid-.../cloudflare

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../cloudflare \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

200OK

{
  "success": true,
  "data": {
    "domain_id": "dom-uuid-...",
    "ssl_mode": "flexible"
  }
}

Nameserver setzen

POST/api/v1/domains/{id}/ns-servers

Benutzerdefinierte Nameserver für die Domain festlegen.

POST/api/v1/domains/dom-uuid-.../ns-servers

curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../ns-servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nameservers": ["ns1.example.com", "ns2.example.com"] }'

200OK

{
  "success": true,
  "data": {
    "nameservers": [
      { "nameserver": "ns1.example.com", "order_index": 1 },
      { "nameserver": "ns2.example.com", "order_index": 2 }
    ]
  }
}

Dokumentation

Whites

White-Page-Generierung nach Nische und Tier. Jede Website ist einzigartig. Domain und Kontakte tauschen — ohne erneute Generierung.

Tiers auflisten

GET/api/v1/whites/tiers

Verfügbare Generierungs-Tiers mit Preisen. price ist der Preis pro Generierung, bereits auf Ihr Konto angepasst (Abonnement berücksichtigt), eine einzige Zahl. quality: "premium" kostet mehr (wird beim Erstellen berechnet). Blog nur bei v2_tier3: die ersten 3 Artikel sind enthalten, jeder weitere (bis 20) wird zu extra_article_price berechnet.

GET/api/v1/whites/tiers

curl https://app.piv.day/api/v1/whites/tiers \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "tiers": [
      {
        "tier_key": "v2_tier1",
        "name": "Landing",
        "generator_version": "v2",
        "min_articles": 0,
        "max_articles": 0,
        "price": 3.00,
        "extra_article_price": null
      },
      {
        "tier_key": "v2_tier2",
        "name": "Multi-page",
        "generator_version": "v2",
        "min_articles": 0,
        "max_articles": 0,
        "price": 6.00,
        "extra_article_price": null
      },
      {
        "tier_key": "v2_tier3",
        "name": "Full + Blog",
        "generator_version": "v2",
        "min_articles": 3,
        "max_articles": 20,
        "price": 10.00,
        "extra_article_price": 1.50
      }
    ]
  }
}

Whites auflisten

GET/api/v1/whites

Liste Ihrer Generierungsaufträge mit Filtermöglichkeit.

Query-Parameter

Feld	Typ	Beschreibung
`limit`	integer	Seitengröße. Standard 100, maximal 500.
`offset`	integer	Paginierungs-Offset.
`status`	string	`queued` \| `processing` \| `done` \| `failed`.
`tier_key`	string	`v2_tier1` \| `v2_tier2` \| `v2_tier3`.

GET/api/v1/whites

curl "https://app.piv.day/api/v1/whites?status=done&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "whites": [
      {
        "id": "job-uuid-...",
        "name": "My White",
        "status": 10,
        "tier_key": "v2_tier3",
        "quality": "standard",
        "niche": "IT Consulting",
        "country": "DE",
        "language": "de",
        "domain": "mysite.com",
        "result_url": null,
        "created_at": "2026-01-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 1, "limit": 20, "offset": 0 }
  }
}

Generierung starten

POST/api/v1/whites

Einen White-Page-Generierungsauftrag in die Warteschlange stellen. Die Zahlung erfolgt sofort. Der finale Status kommt über den Webhook white.completed / white.failed oder kann über GET /whites/{id} abgefragt werden.

Anfrage-Body

Feld	Typ	Beschreibung
`name`*	string	Auftragsname (2–20 Zeichen).
`tier_key`*	string	`v2_tier1` \| `v2_tier2` \| `v2_tier3`.
`niche`*	string	Website-Nische (bis zu 25 Zeichen).
`country`*	string	Ländercode (ISO 3166-1 alpha-2).
`language`*	string	Primäre Website-Sprache (ISO 639-1).
`quality`	string	`standard` \| `premium` (Standard: `standard`).
`languages`	string[]	Sprachenliste. Die erste ist im Preis enthalten; jede weitere kostet extra.
`domain`	string	Vollständige Domain (z. B. `example.com`). Keine Autovervollständigung.
`email`	string	Vollständige E-Mail-Adresse (z. B. `[email protected]`). Keine Autovervollständigung.
`phone`	string	Kontakttelefon.
`address`	string	Unternehmensadresse.
`legal_name`	string	Firmenname (rechtlich).
`style_hint`	string	Designstil (Random, Minimalistisch, Korporativ usw.).
`keywords`	string[]	SEO-Keywords.
`banned_words`	string[]	Im Inhalt verbotene Wörter.
`blog_count`	integer	Anzahl der Blog-Artikel 3–20. Nur für `v2_tier3`. Artikel über 3 kosten extra.
`contacts_mode`	string	`same` \| `template`.
`contacts_template`	string	Kontaktseiten-Template (wenn `contacts_mode=template`).
`facebook`	string	Vollständige Facebook-Seiten-URL.
`instagram`	string	Vollständige Instagram-Profil-URL.
`linkedin`	string	Vollständige LinkedIn-Profil-URL.
`youtube`	string	Vollständige YouTube-Kanal-URL.
`tiktok`	string	Vollständige TikTok-Profil-URL.

Fehler

Code	HTTP	Wann ausgelöst
`INSUFFICIENT_BALANCE`	402	Nicht genügend Guthaben.
`INVALID_TIER`	400	Kein Tier mit diesem Schlüssel gefunden.
`VALIDATION_ERROR`	400	Ungültiger Anfrage-Body.

POST/api/v1/whites

curl -X POST https://app.piv.day/api/v1/whites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Blog DE",
    "tier_key": "v2_tier3",
    "niche": "IT Consulting",
    "country": "DE",
    "language": "de",
    "quality": "premium",
    "languages": ["de", "en"],
    "domain": "techblog-de.com",
    "email": "[email protected]",
    "phone": "+49 30 123456",
    "address": "Berliner Str. 1, 10115 Berlin",
    "legal_name": "TechBlog GmbH",
    "style_hint": "Корпоративный",
    "keywords": ["IT", "consulting", "cloud"],
    "banned_words": ["cheap", "free"],
    "blog_count": 8,
    "contacts_mode": "same",
    "facebook": "https://facebook.com/techblogde",
    "instagram": "https://instagram.com/techblogde",
    "linkedin": "https://linkedin.com/company/techblogde"
  }'

200OK

{
  "success": true,
  "data": {
    "status": "queued",
    "white": {
      "id": "job-uuid-...",
      "name": "Tech Blog DE",
      "status": 0,
      "tier_key": "v2_tier3",
      "quality": "premium",
      "niche": "IT Consulting",
      "country": "DE",
      "language": "de",
      "domain": "techblog-de.com",
      "result_url": null,
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Einen White abrufen

GET/api/v1/whites/{id}

Den aktuellen Status eines Generierungsauftrags abrufen.

GET/api/v1/whites/job-uuid-...

curl https://app.piv.day/api/v1/whites/job-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "white": {
      "id": "job-uuid-...",
      "name": "Tech Blog DE",
      "status": 10,
      "tier_key": "v2_tier3",
      "quality": "premium",
      "niche": "IT Consulting",
      "country": "DE",
      "language": "de",
      "domain": "techblog-de.com",
      "result_url": null,
      "created_at": "2026-01-01T00:00:00Z"
    }
  }
}

Archiv herunterladen

GET/api/v1/whites/{id}/download

Einen kurzlebigen signierten Link zum fertigen White-Page-Archiv abrufen. Der Link ist ~5 Minuten gültig (siehe expires_at). Falls abgelaufen — einfach /download erneut aufrufen, wir stellen einen neuen aus. Wenn die White Page noch nicht generiert wurde, wird 409 NOT_READY zurückgegeben.

Query-Parameter

Feld	Typ	Beschreibung
`format`	string	Archivformat. Standard: `php`.

Fehler

Code	HTTP	Wann ausgelöst
`NOT_READY`	409	Die White Page wird noch generiert — nach `white.completed` erneut versuchen.

GET/api/v1/whites/job-uuid-.../download

curl "https://app.piv.day/api/v1/whites/job-uuid-.../download?format=php" \
  -H "Authorization: Bearer YOUR_API_KEY"

200OK

{
  "success": true,
  "data": {
    "url": "https://strg.piv.day/download/<user_id>/<job_id>?format=php&token=<hmac>&filename=<name>.zip",
    "filename": "example.com_2026-05-28_DE_en.zip",
    "format": "php",
    "expires_at": "2026-05-28T14:46:00Z"
  }
}

Domain und Kontakte tauschen

POST/api/v1/whites/{id}/config

Die Unternehmenskontaktdaten der White Page aktualisieren, ohne sie neu zu generieren.

POST/api/v1/whites/job-uuid-.../config

curl -X POST https://app.piv.day/api/v1/whites/job-uuid-.../config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "My Brand",
    "domain": "newdomain.com",
    "email": "[email protected]",
    "phone": "+49 30 123456",
    "address": "Berliner Str. 1, Berlin",
    "legal": "My Brand GmbH"
  }'

Dokumentation

Webhooks

Abonnieren Sie Plattform-Ereignisse: eingehende SMS, fertige Websites, ablaufende Bestellungen. Die Benachrichtigungs-URL wird im API-Schlüsselprofil festgelegt.

Wie sie ankommen

Wir senden einen einfachen POST mit JSON-Body an deine URL. Das Format ist für alle Events gleich: event_type, timestamp und ein data-Block. Dein Server muss innerhalb von 5 Sekunden mit einem 2xx antworten.

Bei fehlgeschlagener Zustellung

Bei nicht-2xx oder Timeout — bis zu 3 Wiederholungen mit 1s / 2s / 4s Backoff. Der vollständige Lieferverlauf befindet sich auf der API-Schlüssel-Seite im Dashboard. Schlagen alle drei fehl, wird das Event als failed markiert und kann manuell wiederholt werden.

Sicherheit

Verwende einen HTTPS-Endpunkt. Jede Anfrage kommt mit dem Header User-Agent: piv.day-webhook/1.0. Die Webhook-URL wird im API-Schlüssel-Profil konfiguriert.

Anfrageformat

POST <your webhook URL>
Content-Type: application/json
User-Agent: piv.day-webhook/1.0

{
  "event_type": "<event identifier>",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": { ... }
}

Alle Ereignisse

Ereignis	Wann ausgelöst
sms.received	Ein vertrauenswürdiger Absender hat soeben eine Nachricht an eine deiner Nummern gesendet.
sms.status_updated	Eine ausgehende SMS hat den Status geändert — zugestellt, fehlgeschlagen usw.
number.restore_completed	Ein Batch-Restore ist abgeschlossen — die finale Zusammenfassung landet hier.
verify.completed	Die Google-Kontoüberprüfung wurde erfolgreich abgeschlossen.
verify.failed	Etwas ist schief gelaufen — Google hat es nicht akzeptiert.
proxy.expires_soon	Noch etwa drei Tage bis zum Ende der Proxy-Bestellung.
domain.registered	Die Registrierungsbestellung wurde erfolgreich abgeschlossen — die Domain ist aktiv.
domain.failed	Die Bestellung wurde nicht abgeschlossen — häufige Ursache: Name wurde gerade registriert.
domain.expires_soon	Noch etwa eine Woche bis zum Ablauf der Domain.
white.completed	Der White-Generierungsauftrag wurde erfolgreich abgeschlossen.
white.failed	Der Auftrag ist fehlgeschlagen — das Guthaben wird dem Konto gutgeschrieben.

Eingehende SMS auf deine Nummer

sms.received

Meistens sind es Bestätigungscodes von Werbenetzwerken. Der Payload enthält sowohl den Rohtext als auch einen automatisch erkannten Code (wenn vorhanden), sodass du ihn direkt in deinen Workflow übergeben kannst ohne Parsing. Nachrichten von bekannten Spam-Absendern werden nicht weitergeleitet.

payload

{
  "event_type": "sms.received",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "text": "Your verification code is 123456",
    "code": "123456",
    "country": "SE",
    "received_at": "2026-05-22T12:34:56Z"
  }
}

Status der ausgehenden SMS geändert

sms.status_updated

Nützlich, wenn du Bestätigungen von deiner eigenen Nummer sendest und wissen möchtest, ob sie wirklich angekommen sind. Wenn der Status failed ist, enthält der Payload den Fehlercode und die Fehlermeldung des Netzbetreibers.

payload

{
  "event_type": "sms.status_updated",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "message_id": "42",
    "old_status": "sent",
    "new_status": "delivered",
    "error_code": null,
    "error_message": null
  }
}

Nummernwiederherstellung abgeschlossen

number.restore_completed

Enthält zwei Listen — welche Nummern zurückgekehrt sind und welche nicht. Der erstattete Betrag für fehlgeschlagene ist ebenfalls im Payload. Praktisch für Skripte, die intelligent wiederholen.

payload

{
  "event_type": "number.restore_completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "restored": [
      {
        "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
        "phone_number": "+46764794425",
        "country": "SE"
      }
    ],
    "failed": [
      {
        "piv_num_id": "abc12-defgh-ijklm-nopqr",
        "phone_number": "+46123456789",
        "country": "SE",
        "refunded": 7.50
      }
    ],
    "total_restored": 1,
    "total_failed": 1,
    "total_refunded": 7.50
  }
}

Google QR-Verifizierung erfolgreich

verify.completed

Wenn während des Vorgangs eine SMS mit Code angekommen ist, ist sie bereits hier — kein extra Abruf nötig. captured_phone und captured_message enthalten das, was Google gesendet hat.

payload

{
  "event_type": "verify.completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "task_id": 12,
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "status": "sms_sent",
    "captured_phone": "+14155551234",
    "captured_message": "Your Google verification code is 123456",
    "sms_message_id": 42,
    "sms_status": "queued"
  }
}

Google QR-Verifizierung fehlgeschlagen

verify.failed

error_code sagt dir genau was — Timeout, Ablehnung, ungültige URL. Fehlgeschlagene Verifizierungen werden automatisch dem Guthaben gutgeschrieben.

payload

{
  "event_type": "verify.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "task_id": 12,
    "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o",
    "status": "failed",
    "error_code": "VERIFY_TIMEOUT",
    "error_message": "Verification timed out"
  }
}

Proxy läuft bald ab

proxy.expires_soon

Gedacht für Nutzer ohne automatische Verlängerung: du siehst es rechtzeitig und entscheidest — verlängern oder die Kampagne beenden. Verknüpfe es mit POST /proxy/orders/{id}/renew für vollautomatische Verlängerung.

payload

{
  "event_type": "proxy.expires_soon",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "order_id": "ord-uuid-...",
    "country": "DE",
    "quantity": 10,
    "expires_at": "2026-05-25T00:00:00Z"
  }
}

Domain registriert

domain.registered

Wenn du bei der Bestellung Cloudflare und SSL angefordert hast, sind beide bereits aktiv — cloudflare_enabled zeigt den Status. Du kannst sofort DNS-Einträge hinzufügen oder die Website deployen.

payload

{
  "event_type": "domain.registered",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "registered_at": "2026-05-22T12:34:56Z",
    "expires_at": "2027-05-22T12:34:56Z",
    "cloudflare_enabled": true
  }
}

Domain-Registrierung fehlgeschlagen

domain.failed

Das error-Feld enthält eine menschenlesbare Erklärung. Der Betrag wird dem Guthaben gutgeschrieben. Wähle einen anderen Namen und versuche es erneut.

payload

{
  "event_type": "domain.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "error": "Domain is no longer available"
  }
}

Domain läuft bald ab

domain.expires_soon

Nützlich, wenn die automatische Verlängerung ausgeschaltet ist: du hast Zeit, manuell zu verlängern, bevor die Domain in die Redemption-Phase geht. Das auto_renew-Flag sagt dir, ob ein Eingriff nötig ist.

payload

{
  "event_type": "domain.expires_soon",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "domain_id": "dom-uuid-...",
    "domain_name": "mysite.com",
    "expires_at": "2026-05-29T00:00:00Z",
    "auto_renew": false
  }
}

White generiert

white.completed

Das Archiv ist über GET /whites/{id}/download verfügbar. Wenn für den White eine Domain gesetzt war, sind Sitemap und Kontakte bereits darauf eingestellt — bereit zum Deployen.

payload

{
  "event_type": "white.completed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "job_id": "job-uuid-...",
    "name": "My White",
    "tier_key": "t1",
    "country": "DE"
  }
}

White-Generierung fehlgeschlagen

white.failed

Das error-Feld erklärt den Grund. Starte direkt einen neuen Auftrag über POST /whites — kein Geldverlust.

payload

{
  "event_type": "white.failed",
  "timestamp": "2026-05-22T12:34:56Z",
  "data": {
    "job_id": "job-uuid-...",
    "name": "My White",
    "error": "Generation failed"
  }
}

Referenz

Fehlercodes

Jede Fehlerantwort folgt demselben Schema: HTTP-Status + Feld error.code + lesbares error.message.

Code	HTTP	Wann ausgelöst
`UNAUTHORIZED`	401	Schlüssel fehlt, ist abgelaufen oder wurde widerrufen.
`INSUFFICIENT_PERMISSIONS`	403	Der Schlüssel besitzt nicht den erforderlichen Scope für diese Aktion.
`PERMISSION_DENIED`	403	Der Zugriff auf Kontoebene erlaubt diese Aktion nicht (z. B. Funktion deaktiviert).
`VALIDATION_ERROR`	400	Ungültiger Anfragekörper. Die Meldung erklärt, welches Feld betroffen ist und warum.
`NUMBER_NOT_FOUND`	404	Die Nummer existiert nicht oder gehört nicht zum Konto.
`NUMBER_EXPIRED`	403	Die Nummer ist abgelaufen — nutzen Sie Restore (innerhalb von 7 Tagen) oder kaufen Sie eine neue.
`NUMBER_NOT_ACTIVE`	400	Die Nummer befindet sich in einem Zustand, der diese Operation nicht erlaubt.
`INSUFFICIENT_BALANCE`	402	Nicht genügend Guthaben für diese Operation.
`INVALID_MESSAGE_FORMAT`	400	Der SMS-Text ist zu lang oder enthält nicht erlaubte Zeichen.
`COUNTRY_NOT_AVAILABLE`	400	Das Land ist für Kauf oder Verlängerung nicht verfügbar.
`NO_NUMBERS_AVAILABLE`	400	Im gewählten Land sind derzeit keine freien Nummern verfügbar.
`NO_RESTORABLE_NUMBERS`	404	Keiner der angegebenen Nummern kann noch wiederhergestellt werden.
`RATE_LIMITED`	429	Rate limit überschritten. Warten Sie die im Header `Retry-After` angegebene Zeit.
`INTERNAL_ERROR`	500	Bei uns ist ein Fehler aufgetreten. Falls er anhält — wenden Sie sich an den Support.

Fehlerbeispiel

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough balance: required $5.00, available $1.20"
  }
}

Fehler entdeckt oder einen Endpunkt benötigt, der hier fehlt? Der Support antwortet auf Telegram innerhalb einer Stunde während der Geschäftszeiten.

Support kontaktieren