Zum Inhalt springen

Formular absenden POST ​

Sende eine Antwort. Die Einsendung wird zu einer Nachricht im Konto des Besitzers und als Push-Benachrichtigung auf dessen Handy zugestellt — denselben Weg, den ein Webhook-Aufruf nimmt. Keine Authentifizierung.

Endpunkt ​

POST https://api.pocketalert.app/v1/forms/{tid}/submit

Authentifizierung ​

Nicht erforderlich

Jeder, der den Link hat, kann absenden. Der Besitzer legt fest, wer das darf: siehe erlaubte Ursprünge und die Limits unten.

Anfrage ​

Pfadparameter ​

ParameterTypPflichtBeschreibung
tidstring✅Formular-Kennung

Body-Parameter ​

ParameterTypPflichtBeschreibung
valuesobject✅Antworten, geordnet nach Feld-id
websitestring❌Honeypot. Weglassen; alles Nicht-Leere wird als Bot behandelt

Wert pro Feldtyp:

TypWert
text, textarea, email, phone, number, urlString. Format wird bei E-Mail, Telefon, Zahl und URL geprüft
dateString, YYYY-MM-DD
dropdown, radioString, einer der options des Feldes
checkboxesArray aus Strings aus options
checkboxBoolean
ratingZahl, 1–5
npsZahl, 0–10
hiddenString, üblicherweise aus der Seiten-URL übernommen

Layout-Felder (heading, paragraph, divider) nehmen keinen Wert entgegen, unbekannte Schlüssel werden ignoriert. Der Body ist auf 64 KB begrenzt.

Beispielanfrage ​

bash
curl -X POST "https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "message": "Do you ship to Canada?",
      "src": "newsletter"
    }
  }'
javascript
const response = await fetch(
  'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      values: {
        name: 'Jane Doe',
        email: '[email protected]',
        message: 'Do you ship to Canada?'
      }
    })
  }
);

const result = await response.json();
if (response.status === 400) {
  // result.fields = { email: "Enter a valid email address" }
  console.log(result.fields);
}
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
    json={
        'values': {
            'name': 'Jane Doe',
            'email': '[email protected]',
            'message': 'Do you ship to Canada?',
        }
    }
)

print(response.status_code, response.json())

Antwort ​

Erfolgreiche Antwort ​

200 OK

json
{ "status": "ok" }

Der Besitzer erhält eine Push-Benachrichtigung, die aus den Antworten gebaut wird. Informationen über den Besitzer — sein Tarif, seine Geräte, sein Kontingent — werden dem Besucher nicht offengelegt.

Validierungsfehler ​

400 Bad Request

fields ordnet einer Feld-id den Grund zu, warum sie abgelehnt wurde. Das zeigt die Formularseite unter jedem Eingabefeld an.

json
{
  "error": "Please check the highlighted fields.",
  "fields": {
    "email": "Enter a valid email address",
    "name": "This field is required"
  }
}

Geschlossenes Formular ​

410 Gone

json
{
  "error": "This form is no longer accepting responses.",
  "closed": true
}

error enthält das eigene closed_message des Besitzers.

Limits ​

LimitWert
Pro IP10 Einsendungen pro Minute
Pro Formular60 pro Minute, 300 pro Stunde
Kontingent des BesitzersJede Einsendung verbraucht eine Nachricht aus seinem Tageskontingent

Eine Einsendung, die das Tageslimit an Nachrichten des Besitzers überschreiten würde, erhält ein neutrales 429 mit einem Retry-After-Header und ohne Hinweis auf den Tarif.

Fehlerantworten ​

StatusBeschreibung
400Ungültiger Body, oder fields listet die zu korrigierenden Antworten auf
403Das Formular akzeptiert keine Einsendungen von dieser Website — siehe erlaubte Ursprünge
404Formular nicht gefunden
410Das Formular ist geschlossen
429Zu viele Einsendungen, oder der Besitzer hat heute keine Nachrichten mehr
500Das Formular ist falsch konfiguriert, oder die Nachricht konnte nicht erstellt werden

Pocket Alert Dokumentation