API propform (REST)

L'API propform vous permet de gérer vos formulaires, vos soumissions et vos statistiques à partir d'applications externes, par exemple à partir de vos propres outils, scripts ou plateformes d'automatisation telles que Zapier, Make ou n8n.

> URL de base : https://propform.io/api/v1 > > Toutes les requêtes et réponses sont au format JSON (Content-Type: application/json). Les horodatages sont au format ISO-8601 (par exemple, 2026-07-07T08:30:00+00:00).

Démarrage rapide en 3 étapes

1. Créer une clé API : Rendez-vous dans Paramètres → Clés API, cliquez sur Créer une clé API et copiez la clé affichée (format pf_live_…). Pour des raisons de sécurité, elle ne s'affichera qu'une seule fois.

2. Tester la connexion : Remplacez pf_live_DEIN_KEY et accédez à :

   curl https://propform.io/api/v1/me \
     -H "Authorization: Bearer pf_live_DEIN_KEY"
   

   Réponse :

   { "data": { "id": 42, "name": "Max Makler", "email": "max@makler.de" } }
   

3. Première requête réelle – lister vos formulaires :

   curl https://propform.io/api/v1/forms \
     -H "Authorization: Bearer pf_live_DEIN_KEY"

Authentification

L’API utilise des clés API comme jetons « bearer ». Chaque requête doit comporter la clé dans l’en-tête Authorization (Authorization: Bearer pf_live_…). En l’absence de clé ou si celle-ci n’est pas valide, l’API répond par 401.

• Vous gérez vos clés sous Paramètres → Clés API : vous pouvez en créer, les nommer et les révoquer à tout moment.
• Une clé révoquée perd immédiatement son accès.
• Chaque compte peut disposer d’un maximum de 10 clés API.
• Traitez la clé comme un mot de passe : elle donne un accès complet à vos formulaires et à vos soumissions. Ne la divulguez pas dans l’interface utilisateur du navigateur ni dans des dépôts publics.

Limites de débit

• 60 requêtes par minute et par clé.
• En outre, 300 requêtes par minute et par adresse IP (protection contre la surcharge).

En cas de dépassement, l’API renvoie 429 Too Many Requests et un en-tête Retry-After (nombre de secondes jusqu’à la prochaine tentative autorisée). Intégrez un court délai d’attente dans vos automatisations lorsque vous constatez ce statut.

Format de réponse, pagination et erreurs

Les réponses réussies fournissent les données dans le champ data.

Les listes sont paginées. Contrôlez-les via per_page (par défaut 25, max. 100) et page. La réponse contient également les champs links et meta :

{
  "data": [ { "id": 14, "internal_title": "Kontaktformular", "active": true } ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "...?page=2" },
  "meta": { "current_page": 1, "per_page": 25, "total": 63, "last_page": 3 }
}

Les erreurs comportent toujours un champ message ; en cas d’erreurs de validation (422), les détails par champ figurent dans errors :

{
  "message": "The url field is required.",
  "errors": { "url": ["The url field is required."] }
}

Formulaires

Dans l’API, le formulaire est une ressource : vous pouvez également lire et modifier les paramètres d’envoi d’e-mails et d’intégration de ChatGPT directement dans le formulaire. Les noms des champs correspondent exactement aux paramètres de l’éditeur de formulaire.

curl -X PATCH https://propform.io/api/v1/forms/123 \
  -H "Authorization: Bearer pf_live_DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Neuer Titel", "active": true}'

Particularités importantes :

• Sémantique PATCH : les champs que vous n’incluez pas dans la requête restent inchangés. Vous pouvez donc modifier certains paramètres en toute sécurité.
• La fonction Activer ("active": true) ne fonctionne que tant que la limite de formulaires actifs de votre forfait n’est pas atteinte (sinon, utilisez 422). La désactivation est toujours possible.
• Les formulaires ne peuvent pas être supprimés via l’API – cela n’est délibérément possible que dans le tableau de bord.
• Les éléments non modifiables sont notamment slug, les compteurs et les indicateurs de modèle. Les mots de passe (par exemple, le mot de passe du formulaire) sont modifiables, mais n’apparaissent jamais dans les réponses.
• Chaque réponse au formulaire contient le url public du formulaire.

Paramètres de formulaire fréquemment utilisés

Un formulaire dispose de plus de 100 paramètres (tous ceux proposés par l’éditeur). Les plus importants :

Vous pouvez consulter à tout moment l'objet complet via GET /forms/{id}.

👉 Vous trouverez la liste complète de tous les champs et formats dans la référence des champs de l'API.

Champs

curl -X POST https://propform.io/api/v1/forms/123/fields \
  -H "Authorization: Bearer pf_live_DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"onoffice_module": "address", "onoffice_field_name": "Vorname", "label": "Vorname", "required": true}'

Propriétés de champ fréquemment utilisées

Tri : pour reorder, l'ordre dans le tableau field_ids détermine la nouvelle position. Le tableau doit contenir exactement tous identifiants de champ du formulaire (s’il en manque un ou s’il y en a un qui n’appartient pas au formulaire → 422) :

curl -X PATCH https://propform.io/api/v1/forms/123/fields/reorder \
  -H "Authorization: Bearer pf_live_DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_ids": [4712, 4711, 4713]}'

Configuration des champs onOffice

GET /onoffice/fields fournit la configuration des champs de votre compte onOffice – par module (address, estate, task, calendar, agentsLog, file, project) tous les champs avec leur libellé, leur type, leur longueur et les valeurs autorisées. Cela te permet de trouver les valeurs valides pour onoffice_field_name. Avec ?module=address, tu peux filtrer par module.

{
  "data": {
    "address": {
      "Vorname":  { "label": "Vorname", "type": "varchar", "length": 50, "default": null, "permittedvalues": null },
      "Anrede":   { "label": "Anrede",  "type": "singleselect", "length": null, "default": null,
                    "permittedvalues": { "HERR": "Herr", "FRAU": "Frau" } }
    }
  }
}

> Une connexion API onOffice opérationnelle est requise ; dans le cas contraire, le point de terminaison renvoie 409.

Conditions (règles)

Le point de terminaison d’écriture fonctionne comme l’éditeur de conditions dans le tableau de bord : toutes les règles sont toujours enregistrées en une seule fois (pas d’ajout individuel). Commencez donc par lire avec GET, modifiez la liste, puis renvoyez-la dans son intégralité via PUT. Une règle se compose de clauses (conditions « si », liées par mode = all/any) et actions (actions « alors ») :

curl -X PUT https://propform.io/api/v1/forms/123/rules \
  -H "Authorization: Bearer pf_live_DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rules": [{
    "title": "Zusatzfeld einblenden",
    "mode": "all", "priority": 10, "is_enabled": 1, "run_on_init": 1,
    "clauses": [{"when_field_id": "4711", "operator": "equals", "value": "Ja"}],
    "actions": [{"order": 10, "action": "show", "target_field_id": "4712"}]
  }]}'

• Opérateurs : equals, not_equals, empty, not_empty, starts_with, not_starts_with, contains, not_contains
• Promotions : show, hide, enable, disable, require, optional, hide_option, unhide_option, set_value, set_label, make_readonly, unmake_readonly, enable_rules_by_tag, disable_rules_by_tag
• Outre les identifiants de champ, les destinations virtuelles sont également autorisées : __form_title, __form_description, __submit, __submit_spinner, __multistep_back, __multistep_next (dans ce cas, uniquement set_label, show, hide ; pour le spinner, uniquement set_label).
• Tous les identifiants de champ référencés doivent appartenir au formulaire.
• Limites par requête : 200 règles au maximum, 50 clauses/actions chacune.
• Comme dans le tableau de bord, les conditions ne sont disponibles qu’à partir du forfait comprenant 10 formulaires actifs (sinon 403).

Vous trouverez plus de détails sur le fonctionnement des règles sous Conditions, règles et calculs.

Soumissions et statistiques

Le contenu d'un envoi (content) est regroupé par modules onOffice :

{
  "data": {
    "id": 456, "form_id": 123, "index": 42,
    "content": { "address": { "Vorname": "Max", "Name": "Mustermann" }, "estate": { "Id": "131" } },
    "ip_address": "203.0.113.7",
    "created_at": "2026-07-07T08:30:00+00:00"
  }
}

Si vous avez désactivé l'enregistrement des données de soumission dans les paramètres de confidentialité, content correspond toujours à null – mais le formulaire est tout de même pris en compte dans les statistiques. La réponse stats contient views, submissions et conversion_rate.

Webhooks (nouvelles soumissions en temps réel)

Au lieu d'interroger régulièrement les soumissions, tu peux te faire notifier via un webhook : propform envoie immédiatement un POST à ton URL à chaque nouvelle soumission.

💡 Vous pouvez également gérer les webhooks dans l'interface, sans clé API : dans les paramètres, sous « Webhooks » (pour tous les formulaires) ou directement dans l'éditeur de formulaires, sous « Webhooks (Zapier, n8n, Make …) ».

Exigences relatives à l'URL : elle doit être accessible au public et utiliser http:// ou https://. Les adresses internes ou locales (par exemple localhost, 127.0.0.1, adresses IP de réseaux privés) sont refusées pour des raisons de sécurité (422). Étant donné que les données d'envoi sont transmises, utilisez si possible https://.

La réponse lors de la création contient le secret, avec lequel chaque envoi est signé (tu peux le récupérer à tout moment par la suite via GET /webhooks) :

{
  "data": {
    "id": 7, "event": "submission.created",
    "url": "https://example.com/hook", "form_id": 123,
    "secret": "a1b2c3…", "payload_template": null, "message_key": "text", "is_active": true,
    "failure_count": 0, "last_success_at": null, "last_failure_at": null,
    "created_at": "2026-07-07T08:30:00+00:00"
  }
}

Chaque envoi contient deux en-têtes :

• X-Propform-Event – le type d’événement (actuellement toujours submission.created)
• X-Propform-Signature – sha256=<HMAC-SHA256 des Request-Bodys mit deinem secret>

Exemple de charge utile :

{
  "event": "submission.created",
  "created_at": "2026-07-07T08:30:00+00:00",
  "form": { "id": 123, "slug": "aB3x…", "custom_slug": "kontakt", "title": "…", "internal_title": "…" },
  "submission": { "id": 456, "index": 42, "content": { "address": { "Vorname": "Max" } } },
  "onoffice_ids": { "address": { "ID": "789" } }
}

Texte libre / message avec macros onOffice (payload_template)

En option, vous pouvez enregistrer un modèle de texte libre pour chaque abonnement. Après chaque envoi de formulaire, propform y résout les macros onOffice (à partir des enregistrements créés ou modifiés par la soumission) et transmet le résultat dans la charge utile en tant que champ de message dédié — idéal comme message prêt à l'emploi pour Slack & co., sans rien devoir assembler dans votre workflow destinataire. Le champ s'appelle text par défaut (voir ci-dessous).

Exemple de modèle :

Nouvelle demande de _Vorname _Name concernant _objekttitel → _getEstateLink

devient dans la charge utile :

"text": "Nouvelle demande de Max Mustermann concernant Traumwohnung am Stadtpark → https://smart.onoffice.de/…"

Nom du champ du message (message_key) : Par défaut, le champ s'appelle text – ainsi Slack, Microsoft Teams et Google Chat interprètent la charge utile directement comme un message. Discord attend content. Pour Zapier/n8n/Make, le nom est libre. Vous pouvez le modifier par webhook via le paramètre message_key (dans l'interface, sous « Nom du champ du message »).

À noter :

• Les mêmes macros que dans les modèles d'e-mails de propform fonctionnent (macros de champs onOffice, _getAddressLink, _getEstateLink, …).
• Une macro ne peut être résolue que si la soumission dispose du contexte d'enregistrement correspondant (p. ex. _objekttitel nécessite un bien immobilier lié). Sans contexte, la macro reste non résolue dans le texte.
• Les valeurs qui ne sont écrites qu'après l'envoi du webhook (téléversements de fichiers vers onOffice, champs à sélection multiple écrits via « étendre ») peuvent encore manquer dans le texte résolu.
• Sans modèle de texte libre, aucun champ de message n'est envoyé.
• 5 000 caractères au maximum.

Vérification de la signature (recommandée)

Vérifiez la signature pour vous assurer que la requête provient bien de propform. Calculez le HMAC à partir du corps de la requête brut (et non à partir du JSON analysé) et comparez-le en temps réel.

PHP :

$secret    = 'DEIN_WEBHOOK_SECRET';
$body      = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PROPFORM_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Ungültige Signatur');
}
// ab hier: $body ist echt – json_decode($body, true) verarbeiten

Node.js (Express) :

const crypto = require('crypto');

// WICHTIG: express.raw() nutzen, damit der Body unverändert bleibt
app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
  const secret   = process.env.PROPFORM_WEBHOOK_SECRET;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  const got      = req.header('X-Propform-Signature') || '';

  if (expected.length !== got.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got))) {
    return res.status(403).send('Ungültige Signatur');
  }
  const payload = JSON.parse(req.body.toString());
  res.sendStatus(200);
});

Livraison, tentatives et limites

• Votre point de terminaison doit répondre avec un statut 2xx. En cas d’erreur, propform tente la livraison jusqu’à 3 fois (avec un délai d’attente).
• Si un abonnement échoue 20 fois de suite, il est automatiquement désactivé (is_active: false, visible via GET /webhooks). Il suffit ensuite de le recréer.
• Chaque compte peut disposer d’un maximum de 20 abonnements Webhook.
• Les pièces jointes ne font pas partie de la charge utile.

Groupes de formulaires

GET /form-groups répertorie vos groupes de formulaires avec leurs identifiants. Vous pouvez attribuer ces ID dans le PATCH du formulaire sous la forme form_groups (tableau).

Conseils pour Zapier, Make & Co.

• Déclencheur « Nouvelle soumission » : créer un abonnement au webhook (voir ci-dessus) – plus fiable et plus rapide que les requêtes régulières.
• Alternative à l’interrogation régulière : noter GET /forms/{id}/submissions?sort=desc et le id le plus élevé déjà traité.
• Test de connexion : GET /me.
• Détection de nouveaux formulaires : GET /forms?updated_since=….
• En cas de 429, prévoir un court délai d’attente et respecter l’en-tête Retry-After.

Gestion des versions

La version actuelle est v1 et est définie de manière fixe dans le chemin d'accès (/api/v1). Nous ajoutons de nouveaux champs et points de terminaison de manière rétrocompatible sans modifier la version ; votre client doit donc simplement ignorer les champs inconnus dans les réponses. Les modifications fondamentales non rétrocompatibles apparaîtraient sous une nouvelle version (/api/v2).