Vai al contenuto

Crea form POST ​

Crea un form ospitato. Viene pubblicato subito su https://frms.click/{tid} e ogni invio diventa un messaggio nel tuo account — vedi Forms.

Endpoint ​

POST https://api.pocketalert.app/v1/forms

Autenticazione ​

Obbligatoria

Includi uno di questi header nella richiesta:

  • Token: <your-api-key> — Ottienila da API Keys
  • Authorization: Bearer <jwt-token> — Da Login

Richiesta ​

HeaderObbligatorioDescrizione
Token✅La tua chiave API
Authorization✅Bearer <jwt-token>

Parametri del body ​

ParametroTipoObbligatorioDescrizione
namestring✅Nome interno, fino a 191 caratteri. È anche il titolo push predefinito
fieldsarray✅I campi del form, massimo 30. Almeno uno deve essere un campo che il visitatore compila
settingsobject❌Titolo, testi e design. Ogni chiave ha un valore predefinito
application_tidstring❌Applicazione a cui appartengono gli invii
device_tidstring❌TID del dispositivo di destinazione, oppure all. Ometti per tutti i dispositivi
default_levelint❌Livello di priorità (-2..2) per gli invii. Vedi Livelli di priorità dei messaggi
push_titlestring❌Template del titolo push con token {Field label}, fino a 191 caratteri
allowed_originsarray❌Host autorizzati a incorporare e inviare il form, massimo 10. Vuoto significa ovunque
max_responsesint❌Chiude il form dopo questo numero di risposte. 0 (predefinito) è illimitato
closes_atstring❌Orario di chiusura, RFC 3339. Salvato in UTC
is_activeboolean❌false chiude subito il form. Il valore predefinito è true

Campi ​

Ogni voce in fields:

ParametroTipoObbligatorioDescrizione
idstring✅Unico nel form: lettere, cifre, _ e -, fino a 40 caratteri
typestring✅Uno dei tipi sotto indicati
labelstring✅Mostrata sopra il campo, fino a 200 caratteri (2000 per paragraph)
placeholderstring❌Solo per text, textarea, email, phone, number, url e dropdown
requiredboolean❌Ignorato dai campi di layout
optionsarray✅ per i campi di sceltaFino a 50 voci per dropdown, radio e checkboxes
paramstring✅ per hiddenParametro URL da cui leggere il valore, es. utm_source
GruppoTipiValore inviato
Testotext, textarea, email, phone, number, url, dateStringa. text è limitato a 1000 caratteri, textarea a 5000
Sceltadropdown, radioUna delle options
SceltacheckboxesArray di options
SceltacheckboxBooleano, mostrato come Yes / No
Valutazionerating (1–5), nps (0–10)Numero
Layoutheading, paragraph, dividerMai inviati
TracciamentohiddenPreso dall'URL della pagina, non dal visitatore

I valori di email, telefono, numero, URL e data vengono validati sul server; il controllo del browser è una comodità, non la garanzia.

Impostazioni ​

Tutte le chiavi sono facoltative — ciò che ometti mantiene il valore predefinito.

ParametroTipoPredefinitoDescrizione
titlestring""Titolo sopra il form, fino a 200 caratteri
top_textstring""Testo introduttivo, fino a 2000 caratteri. Testo semplice; i link diventano cliccabili
bottom_textstring""Testo sotto il pulsante, fino a 2000 caratteri
success_messagestringThanks! Your response has been sent.Mostrato dopo un invio, fino a 500 caratteri
closed_messagestringThis form is no longer accepting responses.Mostrato quando il form è chiuso
background_colorstring#f5f5f4Sfondo della pagina, #rrggbb
card_colorstring#ffffffSfondo del form
text_colorstring#1c1917Testo
primary_colorstring#3f5cadColore di accento e, se non sovrascritto, del pulsante
font_familystringInterUn Google Font per nome
font_sizeint1612–24
font_weightint400300, 400, 500, 600 o 700
border_radiusint100–48
hide_brandingbooleanfalseNasconde il link "Powered by Pocket Alert". Solo piani a pagamento — sul piano gratuito l'API lo reimposta a false
submitobject—{ "text": "Submit", "color": "", "size": "md" }. size è sm, md o lg; un color vuoto segue primary_color

Template del titolo push ​

push_title costruisce il titolo della notifica dalle risposte:

New lead: {Name} ({Email})

I token fanno riferimento ai campi per etichetta, senza distinzione tra maiuscole e minuscole, più {form} per il nome del form. I token senza risposta vengono eliminati; se non resta nulla, il titolo ricade su Form: {name}. Il template non viene mai esposto nella pagina pubblica.

Origini consentite ​

L'ID del form viaggia nel suo link pubblico, quindi per impostazione predefinita chiunque lo possieda può incorporare il form. allowed_origins lo impedisce: solo gli host elencati possono incorniciare il form, e un invio il cui Origin (o Referer) non è nell'elenco viene rifiutato con 403.

Scrivi host, non URL: example.com, app.example.com, *.example.com per ogni sottodominio, localhost:3000 durante lo sviluppo. www. viene ignorato.

Esempio di richiesta ​

bash
curl -X POST "https://api.pocketalert.app/v1/forms" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact form",
    "push_title": "New lead: {Name}",
    "fields": [
      { "id": "name", "type": "text", "label": "Name", "required": true },
      { "id": "email", "type": "email", "label": "Email", "required": true },
      { "id": "message", "type": "textarea", "label": "Message" },
      { "id": "src", "type": "hidden", "label": "Source", "param": "utm_source" }
    ],
    "settings": {
      "title": "Get in touch",
      "top_text": "We reply within one business day.",
      "primary_color": "#3f5cad"
    }
  }'
javascript
const response = await fetch('https://api.pocketalert.app/v1/forms', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Contact form',
    push_title: 'New lead: {Name}',
    fields: [
      { id: 'name', type: 'text', label: 'Name', required: true },
      { id: 'email', type: 'email', label: 'Email', required: true },
      { id: 'message', type: 'textarea', label: 'Message' }
    ],
    settings: { title: 'Get in touch' }
  })
});

const form = await response.json();
console.log('Form link:', `https://frms.click/${form.tid}`);
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/forms',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'Contact form',
        'push_title': 'New lead: {Name}',
        'fields': [
            {'id': 'name', 'type': 'text', 'label': 'Name', 'required': True},
            {'id': 'email', 'type': 'email', 'label': 'Email', 'required': True},
            {'id': 'message', 'type': 'textarea', 'label': 'Message'},
        ],
        'settings': {'title': 'Get in touch'},
    }
)

form = response.json()
print(f"Form link: https://frms.click/{form['tid']}")
php
$form = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/forms', [
    'name' => 'Contact form',
    'push_title' => 'New lead: {Name}',
    'fields' => [
        ['id' => 'name', 'type' => 'text', 'label' => 'Name', 'required' => true],
        ['id' => 'email', 'type' => 'email', 'label' => 'Email', 'required' => true],
        ['id' => 'message', 'type' => 'textarea', 'label' => 'Message'],
    ],
    'settings' => ['title' => 'Get in touch'],
])->json();

echo 'Form link: https://frms.click/'.$form['tid'];

Risposta ​

Risposta di successo ​

201 Created

Il form è online. Condividi https://frms.click/{tid}, oppure incorporalo — vedi Forms.

Il body ha la stessa struttura di una voce di Get All Forms.

json
{
  "tid": "vml19aihrga216gt8apc5e3m9",
  "name": "Contact form",
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": true },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "message", "type": "textarea", "label": "Message" },
    { "id": "src", "type": "hidden", "label": "Source", "param": "utm_source" }
  ],
  "settings": {
    "title": "Get in touch",
    "top_text": "We reply within one business day.",
    "success_message": "Thanks! Your response has been sent.",
    "closed_message": "This form is no longer accepting responses.",
    "background_color": "#f5f5f4",
    "card_color": "#ffffff",
    "text_color": "#1c1917",
    "primary_color": "#3f5cad",
    "font_family": "Inter",
    "font_size": 16,
    "font_weight": 400,
    "border_radius": 10,
    "hide_branding": false,
    "submit": { "text": "Submit", "color": "", "size": "md" }
  },
  "application_tid": "",
  "device_tid": "",
  "default_level": null,
  "push_title": "New lead: {Name}",
  "allowed_origins": [],
  "max_responses": 0,
  "closes_at": null,
  "closed": false,
  "is_active": true,
  "submissions_count": 0,
  "last_submission_at": "",
  "created_at": "23.09.2026 11:40:02"
}

Risposte di errore ​

StatoDescrizione
400Errore di validazione — il campo error indica quale campo o impostazione è errato
401Non autorizzato — token non valido o mancante
403Hai raggiunto il numero di form consentiti dal tuo piano
500Creazione del form non riuscita

Documentazione di Pocket Alert