Aller au contenu

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/forms

Authentification ​

Obligatoire

Incluez l'un de ces en-têtes dans votre requête :

  • Token: <your-api-key> — Obtenez-la dans Clés API
  • Authorization: Bearer <jwt-token> — Depuis Se connecter

Requête ​

En-têtes ​

En-têteObligatoireDescription
Token✅Votre clé API
Authorization✅Bearer <jwt-token>

Paramètres du corps ​

ParamètreTypeObligatoireDescription
namestring✅Nom interne, jusqu'à 191 caractères. Sert aussi de titre push par défaut
fieldsarray✅Les champs du formulaire, 30 maximum. Au moins un doit être un champ que le visiteur remplit
settingsobject❌Titre, textes et design. Chaque clé a une valeur par défaut
application_tidstring❌Application à laquelle appartiennent les envois
device_tidstring❌TID de l'appareil cible, ou all. Omettez pour tous les appareils
default_levelint❌Niveau de priorité (-2..2) des envois. Voir Niveaux de priorité des messages
push_titlestring❌Modèle de titre push avec des jetons {Field label}, jusqu'à 191 caractères
allowed_originsarray❌Hôtes autorisés à intégrer et soumettre le formulaire, 10 maximum. Vide signifie partout
max_responsesint❌Fermer le formulaire après ce nombre de réponses. 0 (par défaut) est illimité
closes_atstring❌Heure de fermeture, RFC 3339. Stockée en UTC
is_activeboolean❌false ferme le formulaire immédiatement. Valeur par défaut : true

Champs ​

Chaque entrée de fields :

ParamètreTypeObligatoireDescription
idstring✅Unique dans le formulaire : lettres, chiffres, _ et -, jusqu'à 40 caractères
typestring✅L'un des types ci-dessous
labelstring✅Affiché au-dessus de la saisie, jusqu'à 200 caractères (2000 pour paragraph)
placeholderstring❌Uniquement pour text, textarea, email, phone, number, url et dropdown
requiredboolean❌Ignoré par les champs de mise en page
optionsarray✅ pour les champs de choixJusqu'à 50 entrées pour dropdown, radio et checkboxes
paramstring✅ pour hiddenParamètre d'URL dont la valeur est lue, par ex. utm_source
GroupeTypesValeur envoyée
Textetext, textarea, email, phone, number, url, dateChaîne. text est limité à 1000 caractères, textarea à 5000
Choixdropdown, radioL'une des options
ChoixcheckboxesTableau des options
ChoixcheckboxBooléen, affiché comme Yes / No
Évaluationrating (1–5), nps (0–10)Nombre
Mise en pageheading, paragraph, dividerJamais envoyé
SuivihiddenTiré 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ètreTypePar défautDescription
titlestring""Titre au-dessus du formulaire, jusqu'à 200 caractères
top_textstring""Texte d'introduction, jusqu'à 2000 caractères. Texte brut ; les liens deviennent cliquables
bottom_textstring""Texte sous le bouton, jusqu'à 2000 caractères
success_messagestringThanks! Your response has been sent.Affiché après un envoi, jusqu'à 500 caractères
closed_messagestringThis form is no longer accepting responses.Affiché lorsque le formulaire est fermé
background_colorstring#f5f5f4Fond de la page, #rrggbb
card_colorstring#ffffffFond du formulaire
text_colorstring#1c1917Texte
primary_colorstring#3f5cadCouleur d'accent et, sauf indication contraire, du bouton
font_familystringInterUne police Google Fonts par son nom
font_sizeint1612–24
font_weightint400300, 400, 500, 600 ou 700
border_radiusint100–48
hide_brandingbooleanfalseMasque le lien « Powered by Pocket Alert ». Offres payantes uniquement — sur l'offre gratuite, l'API le remet à false
submitobject—{ "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 ​

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'];

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.

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"
}

Réponses d'erreur ​

StatutDescription
400Erreur de validation — le champ error indique quel champ ou paramètre est incorrect
401Non autorisé — jeton invalide ou absent
403Vous avez atteint le nombre de formulaires autorisé par votre offre
500Échec de la création du formulaire

Documentation de Pocket Alert