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/formsAutenticazione
Obbligatoria
Includi uno di questi header nella richiesta:
Richiesta
Header
| Header | Obbligatorio | Descrizione |
|---|---|---|
Token | ✅ | La tua chiave API |
Authorization | ✅ | Bearer <jwt-token> |
Parametri del body
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
name | string | ✅ | Nome interno, fino a 191 caratteri. È anche il titolo push predefinito |
fields | array | ✅ | I campi del form, massimo 30. Almeno uno deve essere un campo che il visitatore compila |
settings | object | ❌ | Titolo, testi e design. Ogni chiave ha un valore predefinito |
application_tid | string | ❌ | Applicazione a cui appartengono gli invii |
device_tid | string | ❌ | TID del dispositivo di destinazione, oppure all. Ometti per tutti i dispositivi |
default_level | int | ❌ | Livello di priorità (-2..2) per gli invii. Vedi Livelli di priorità dei messaggi |
push_title | string | ❌ | Template del titolo push con token {Field label}, fino a 191 caratteri |
allowed_origins | array | ❌ | Host autorizzati a incorporare e inviare il form, massimo 10. Vuoto significa ovunque |
max_responses | int | ❌ | Chiude il form dopo questo numero di risposte. 0 (predefinito) è illimitato |
closes_at | string | ❌ | Orario di chiusura, RFC 3339. Salvato in UTC |
is_active | boolean | ❌ | false chiude subito il form. Il valore predefinito è true |
Campi
Ogni voce in fields:
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
id | string | ✅ | Unico nel form: lettere, cifre, _ e -, fino a 40 caratteri |
type | string | ✅ | Uno dei tipi sotto indicati |
label | string | ✅ | Mostrata sopra il campo, fino a 200 caratteri (2000 per paragraph) |
placeholder | string | ❌ | Solo per text, textarea, email, phone, number, url e dropdown |
required | boolean | ❌ | Ignorato dai campi di layout |
options | array | ✅ per i campi di scelta | Fino a 50 voci per dropdown, radio e checkboxes |
param | string | ✅ per hidden | Parametro URL da cui leggere il valore, es. utm_source |
| Gruppo | Tipi | Valore inviato |
|---|---|---|
| Testo | text, textarea, email, phone, number, url, date | Stringa. text è limitato a 1000 caratteri, textarea a 5000 |
| Scelta | dropdown, radio | Una delle options |
| Scelta | checkboxes | Array di options |
| Scelta | checkbox | Booleano, mostrato come Yes / No |
| Valutazione | rating (1–5), nps (0–10) | Numero |
| Layout | heading, paragraph, divider | Mai inviati |
| Tracciamento | hidden | Preso 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.
| Parametro | Tipo | Predefinito | Descrizione |
|---|---|---|---|
title | string | "" | Titolo sopra il form, fino a 200 caratteri |
top_text | string | "" | Testo introduttivo, fino a 2000 caratteri. Testo semplice; i link diventano cliccabili |
bottom_text | string | "" | Testo sotto il pulsante, fino a 2000 caratteri |
success_message | string | Thanks! Your response has been sent. | Mostrato dopo un invio, fino a 500 caratteri |
closed_message | string | This form is no longer accepting responses. | Mostrato quando il form è chiuso |
background_color | string | #f5f5f4 | Sfondo della pagina, #rrggbb |
card_color | string | #ffffff | Sfondo del form |
text_color | string | #1c1917 | Testo |
primary_color | string | #3f5cad | Colore di accento e, se non sovrascritto, del pulsante |
font_family | string | Inter | Un Google Font per nome |
font_size | int | 16 | 12–24 |
font_weight | int | 400 | 300, 400, 500, 600 o 700 |
border_radius | int | 10 | 0–48 |
hide_branding | boolean | false | Nasconde il link "Powered by Pocket Alert". Solo piani a pagamento — sul piano gratuito l'API lo reimposta a false |
submit | object | — | { "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
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"
}
}'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}`);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']}")$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.
{
"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
| Stato | Descrizione |
|---|---|
400 | Errore di validazione — il campo error indica quale campo o impostazione è errato |
401 | Non autorizzato — token non valido o mancante |
403 | Hai raggiunto il numero di form consentiti dal tuo piano |
500 | Creazione del form non riuscita |