Créer un formulaire POST
Créez un formulaire hébergé. Il est publié immédiatement à l'adresse https://frms.click/{tid}, et chaque envoi devient un message sur votre compte — voir Formulaires.
Point de terminaison
POST https://api.pocketalert.app/v1/formsAuthentification
Obligatoire
Incluez l'un de ces en-têtes dans votre requête :
Token: <your-api-key>— Obtenez-la dans Clés APIAuthorization: Bearer <jwt-token>— Depuis Se connecter
Requête
En-têtes
| En-tête | Obligatoire | Description |
|---|---|---|
Token | ✅ | Votre clé API |
Authorization | ✅ | Bearer <jwt-token> |
Paramètres du corps
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
name | string | ✅ | Nom interne, jusqu'à 191 caractères. Sert aussi de titre push par défaut |
fields | array | ✅ | Les champs du formulaire, 30 maximum. Au moins un doit être un champ que le visiteur remplit |
settings | object | ❌ | Titre, textes et design. Chaque clé a une valeur par défaut |
application_tid | string | ❌ | Application à laquelle appartiennent les envois |
device_tid | string | ❌ | TID de l'appareil cible, ou all. Omettez pour tous les appareils |
default_level | int | ❌ | Niveau de priorité (-2..2) des envois. Voir Niveaux de priorité des messages |
push_title | string | ❌ | Modèle de titre push avec des jetons {Field label}, jusqu'à 191 caractères |
allowed_origins | array | ❌ | Hôtes autorisés à intégrer et soumettre le formulaire, 10 maximum. Vide signifie partout |
max_responses | int | ❌ | Fermer le formulaire après ce nombre de réponses. 0 (par défaut) est illimité |
closes_at | string | ❌ | Heure de fermeture, RFC 3339. Stockée en UTC |
is_active | boolean | ❌ | false ferme le formulaire immédiatement. Valeur par défaut : true |
Champs
Chaque entrée de fields :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
id | string | ✅ | Unique dans le formulaire : lettres, chiffres, _ et -, jusqu'à 40 caractères |
type | string | ✅ | L'un des types ci-dessous |
label | string | ✅ | Affiché au-dessus de la saisie, jusqu'à 200 caractères (2000 pour paragraph) |
placeholder | string | ❌ | Uniquement pour text, textarea, email, phone, number, url et dropdown |
required | boolean | ❌ | Ignoré par les champs de mise en page |
options | array | ✅ pour les champs de choix | Jusqu'à 50 entrées pour dropdown, radio et checkboxes |
param | string | ✅ pour hidden | Paramètre d'URL dont la valeur est lue, par ex. utm_source |
| Groupe | Types | Valeur envoyée |
|---|---|---|
| Texte | text, textarea, email, phone, number, url, date | Chaîne. text est limité à 1000 caractères, textarea à 5000 |
| Choix | dropdown, radio | L'une des options |
| Choix | checkboxes | Tableau des options |
| Choix | checkbox | Booléen, affiché comme Yes / No |
| Évaluation | rating (1–5), nps (0–10) | Nombre |
| Mise en page | heading, paragraph, divider | Jamais envoyé |
| Suivi | hidden | Tiré de l'URL de la page, pas du visiteur |
Les valeurs email, téléphone, nombre, URL et date sont validées côté serveur ; la vérification du navigateur n'est qu'un confort, pas une garantie.
Paramètres d'affichage
Toutes les clés sont facultatives : tout ce que vous omettez conserve sa valeur par défaut.
| Paramètre | Type | Par défaut | Description |
|---|---|---|---|
title | string | "" | Titre au-dessus du formulaire, jusqu'à 200 caractères |
top_text | string | "" | Texte d'introduction, jusqu'à 2000 caractères. Texte brut ; les liens deviennent cliquables |
bottom_text | string | "" | Texte sous le bouton, jusqu'à 2000 caractères |
success_message | string | Thanks! Your response has been sent. | Affiché après un envoi, jusqu'à 500 caractères |
closed_message | string | This form is no longer accepting responses. | Affiché lorsque le formulaire est fermé |
background_color | string | #f5f5f4 | Fond de la page, #rrggbb |
card_color | string | #ffffff | Fond du formulaire |
text_color | string | #1c1917 | Texte |
primary_color | string | #3f5cad | Couleur d'accent et, sauf indication contraire, du bouton |
font_family | string | Inter | Une police Google Fonts par son nom |
font_size | int | 16 | 12–24 |
font_weight | int | 400 | 300, 400, 500, 600 ou 700 |
border_radius | int | 10 | 0–48 |
hide_branding | boolean | false | Masque le lien « Powered by Pocket Alert ». Offres payantes uniquement — sur l'offre gratuite, l'API le remet à false |
submit | object | — | { "text": "Submit", "color": "", "size": "md" }. size vaut sm, md ou lg ; une color vide suit primary_color |
Modèle de titre push
push_title construit le titre de la notification à partir des réponses :
New lead: {Name} ({Email})Les jetons renvoient aux champs par libellé, sans distinction de casse, plus {form} pour le nom du formulaire. Les jetons sans réponse disparaissent ; si rien ne reste, le titre revient à Form: {name}. Le modèle n'est jamais exposé sur la page publique.
Origines autorisées
Un identifiant de formulaire circule dans son lien public : par défaut, toute personne qui le possède peut intégrer le formulaire. allowed_origins met fin à cela : seuls les hôtes listés peuvent afficher le formulaire, et un envoi dont l'Origin (ou le Referer) ne figure pas dans la liste est rejeté avec un 403.
Indiquez des hôtes, pas des URL : example.com, app.example.com, *.example.com pour tous les sous-domaines, localhost:3000 pendant le développement. www. est ignoré.
Exemple de requête
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'];Réponse
Réponse de succès
201 Created
Le formulaire est en ligne. Partagez https://frms.click/{tid}, ou intégrez-le — voir Formulaires.
Le corps a la même structure qu'une entrée de Lister les formulaires.
{
"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"
}Réponses d'erreur
| Statut | Description |
|---|---|
400 | Erreur de validation — le champ error indique quel champ ou paramètre est incorrect |
401 | Non autorisé — jeton invalide ou absent |
403 | Vous avez atteint le nombre de formulaires autorisé par votre offre |
500 | Échec de la création du formulaire |