Vai al contenuto

Invia modulo POST ​

Invia una risposta. L'invio diventa un messaggio nell'account del proprietario e viene inviato come notifica push sul suo telefono: segue la stessa pipeline di una chiamata webhook. Nessuna autenticazione.

Endpoint ​

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

Autenticazione ​

Non richiesta

Chiunque abbia il link può inviare una risposta. Il proprietario controlla chi può farlo: vedi origini consentite e i limiti qui sotto.

Richiesta ​

Parametri di percorso ​

ParametroTipoObbligatorioDescrizione
tidstring✅Identificatore del modulo

Parametri del body ​

ParametroTipoObbligatorioDescrizione
valuesobject✅Risposte, con chiave l'id del campo
websitestring❌Honeypot. Non inviarlo: qualsiasi valore non vuoto viene trattato come bot

Valore per tipo di campo:

TipoValore
text, textarea, email, phone, number, urlStringa. Il formato viene validato per email, telefono, numero e URL
dateStringa, YYYY-MM-DD
dropdown, radioStringa, una delle options del campo
checkboxesArray di stringhe tratte da options
checkboxBooleano
ratingNumero, da 1 a 5
npsNumero, da 0 a 10
hiddenStringa, di norma ricavata dall'URL della pagina

I campi di layout (heading, paragraph, divider) non accettano valori, e le chiavi sconosciute vengono ignorate. Il body è limitato a 64 KB.

Esempio di richiesta ​

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())

Risposta ​

Risposta di successo ​

200 OK

json
{ "status": "ok" }

Il proprietario riceve una notifica push costruita con le risposte. Nessuna informazione sul proprietario (piano, dispositivi, quota) viene esposta al visitatore.

Errori di validazione ​

400 Bad Request

fields associa l'id di un campo al motivo per cui è stato rifiutato: è ciò che la pagina del modulo mostra sotto ogni input.

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

Modulo chiuso ​

410 Gone

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

error contiene il closed_message impostato dal proprietario.

Limiti ​

LimiteValore
Per IP10 invii al minuto
Per modulo60 al minuto, 300 all'ora
Quota del proprietarioOgni invio consuma un messaggio dal suo limite giornaliero

Un invio che supererebbe il limite giornaliero di messaggi del proprietario riceve un generico 429 con un header Retry-After, senza alcun riferimento al piano.

Risposte di errore ​

StatoDescrizione
400Body non valido, oppure fields elenca le risposte da correggere
403Il modulo non accetta invii da questo sito: vedi origini consentite
404Modulo non trovato
410Il modulo è chiuso
429Troppi invii, oppure il proprietario ha esaurito i messaggi per oggi
500Il modulo è configurato in modo errato, oppure non è stato possibile creare il messaggio

Documentazione di Pocket Alert