Mit der FoxPhone Public API können Sie Cloud Phones und Proxys Ihres Kontos auflisten sowie Geräte-Resets und Proxy-Zuweisungen gesammelt starten. Die aktuelle Version bietet die folgenden vier Endpunkte.
1. API-Schlüssel vorbereiten
Klicken Sie oben rechts auf Ihr Profilbild, wählen Sie Settings und öffnen Sie anschließend in Ihrem Konto die Seite API Key.
Erstellen Sie auf der API-Key-Seite einen Schlüssel. Pro Konto ist nur ein aktiver Schlüssel zulässig:
- Beim Neuerstellen wird der bisherige Schlüssel sofort ungültig.
- Nach dem Deaktivieren werden alle Public-API-Anfragen sofort abgelehnt.
- Der vollständige Schlüssel wird nur beim Erstellen einmal angezeigt. Speichern Sie ihn in einem kontrollierten Secret-Manager.
Übergeben Sie den Schlüssel im Request-Header:
X-API-Key: <your_api_key>Sicherheitshinweis: Geben Sie den API-Schlüssel niemals in URL, Request-Body, Quellcode, Logs oder Support-Tickets an. Ressourcen-IDs und Schlüssel in diesem Leitfaden sind Platzhalter.
2. Allgemeine Regeln
- Basis-URL der Produktionsumgebung:
https://api.foxphone.com/public_api/v1 - Für alle vier Endpunkte gilt gemeinsam ein Limit von 60 Anfragen pro Minute und API-Schlüssel.
- Für Listenparameter gilt:
page_numhat den Standardwert1;page_sizehat den Standardwert20, maximal100;searchist optional. - Batch-Anfragen akzeptieren 1 bis 100
pod_ids; Duplikate werden serverseitig entfernt. - Sie können nur auf Ressourcen des Kontos zugreifen, dem der API-Schlüssel gehört. Ein anderes Konto lässt sich nicht per Parameter auswählen.
- Findet die Vorprüfung eine ungültige Ressource oder einen konkurrierenden Vorgang, wird kein Element des gesamten Batches übermittelt.
- Treten nach Beginn der Übermittlung an das Remotesystem Teilfehler auf, werden bereits angenommene Vorgänge nicht zurückgerollt. Die Antwort listet Erfolge und Fehler getrennt auf.
3. Cloud Phones auflisten
Mit diesem Endpunkt rufen Sie die Cloud Phones des aktuellen Kontos paginiert ab:
GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-exampleMit search können Sie Cloud Phones nach Name oder pod_id suchen.
Beispielanfrage:
curl --fail-with-body
-H "X-API-Key: $API_KEY"
"https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=pod-example"Beispielantwort:
{
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "automation-phone",
"online_status": 1,
"operating_status": 0,
"proxy_id": "42"
}
]
}proxy_id ist 0 bedeutet, dass dem Cloud Phone derzeit kein Proxy zugewiesen ist.
4. Proxys auflisten
Mit diesem Endpunkt rufen Sie die vorhandenen Proxys des aktuellen Kontos paginiert ab:
GET /public_api/v1/proxies?page_num=1&page_size=20&search=42Mit search können Sie Proxys nach Name oder proxy_id suchen. Der Endpunkt gibt weder Proxy-Benutzernamen noch Passwörter zurück.
Beispielanfrage:
curl --fail-with-body
-H "X-API-Key: $API_KEY"
"https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=42"Beispielantwort:
{
"total": 1,
"proxies": [
{
"proxy_id": "42",
"name": "us-residential",
"proxy_type": "http",
"proxy_ip": "203.0.113.42",
"proxy_port": "10000",
"check_status": "available"
}
]
}5. Geräte-Resets gesammelt starten
Mit diesem Endpunkt übermitteln Sie Reset-Aufträge für mehrere Geräte:
POST /public_api/v1/phones/actions/reset
Content-Type: application/jsonRequest-Body:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Aktuelle Einschränkung: Der Reset-Endpunkt unterstützt im Request-Body keine Angabe von proxy_id oder anderen Proxy-Parametern. Warten Sie zum Ändern des Proxys das Ende des Resets ab und rufen Sie anschließend den Endpunkt zum Sammelbinden vorhandener Proxys auf.
Beispielanfrage:
curl --fail-with-body
-X POST
-H "Content-Type: application/json"
-H "X-API-Key: $API_KEY"
--data '{"pod_ids":["pod-example-001","pod-example-002"]}'
"https://api.foxphone.com/public_api/v1/phones/actions/reset"Läuft für ein Cloud Phone bereits ein Reset, gibt eine neue Anfrage während der Vorprüfung RESET_IN_PROGRESS zurück und übermittelt keinen doppelten Auftrag.
6. Vorhandene Proxys gesammelt zuweisen
Rufen Sie zuerst über die Proxy-Liste die proxy_id ab und verwenden Sie anschließend diesen Endpunkt:
POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/jsonRequest-Body:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Beispielanfrage:
curl --fail-with-body
-X POST
-H "Content-Type: application/json"
-H "X-API-Key: $API_KEY"
--data '{"pod_ids":["pod-example-001","pod-example-002"]}'
"https://api.foxphone.com/public_api/v1/proxies/42/bind"Der Proxy und alle Cloud Phones müssen zum aktuellen Konto gehören. Auch ausgeschaltete Phones können einen Proxy erhalten. Phones mit laufendem Reset, Ein-/Ausschaltvorgang, Neustart oder anderer Proxy-Operation werden bei der Vorprüfung abgelehnt.
7. Batch-Antworten
Geräte-Reset und Proxy-Zuweisung verwenden dieselbe Antwortstruktur:
{
"successful_pod_ids": ["pod-example-001"],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
}Bei fehlgeschlagener Vorprüfung werden HTTP 409 und der Fehlercode BATCH_PRECHECK_FAILED. In den Fehlermetadaten listet failed_items die jeweiligen pod_id, code und message; in diesem Fall wird kein Batch-Element übermittelt.
Fehler nach Beginn der Annahme durch das Remotesystem werden in der fachlichen Antwort über successful_pod_ids und failed_items als tatsächliches Ergebnis dargestellt.
8. Häufige Fehler
| HTTP-Status | Fehlercode | Beschreibung |
|---|---|---|
| 400 | INVALID_ARGUMENT | Ungültiges Parameterformat, ungültige Anzahl oder ungültiger Seitenwert |
| 401 | INVALID_API_KEY | API-Schlüssel fehlt, ist falsch formatiert oder ungültig |
| 403 | API_KEY_DISABLED | API-Schlüssel ist deaktiviert |
| 403 | USER_ACCOUNT_UNAVAILABLE | Das Konto des API-Schlüssels ist nicht verfügbar |
| 409 | BATCH_PRECHECK_FAILED | Batch-Vorprüfung fehlgeschlagen; nichts wurde übermittelt |
| 429 | RATE_LIMIT_EXCEEDED | Limit pro Minute überschritten |
Wiederholen Sie HTTP 429 später mit Backoff. Bei HTTP 409 beheben Sie zuerst anhand von failed_items den Ressourcenstatus und senden Sie dieselbe Anfrage nicht sofort erneut.
