API propform (REST)

L'API propform vous permet de gérer vos formulaires, vos soumissions, vos statistiques, vos modèles PDF, vos papiers à en-tête, vos collaborateurs et les paramètres de votre compte à 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.
• La liste contient tous vos formulaires – y compris ceux partagés comme modèle à copier. Le champ en lecture seule form_template indique ce partage ; le filtre template=0/1 permet de filtrer selon ce critère.
• 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

Vous attribuez les identifiants de groupe dans le PATCH du formulaire sous la forme form_groups (tableau).

Modèles PDF (générateur de PDF)

propform peut générer son propre PDF à partir de chaque soumission (voir Générateur de PDF). Vous lisez et modifiez entièrement le modèle d'un formulaire – liste de blocs, design et paramètres – via l'API :

curl -X PATCH https://propform.io/api/v1/forms/123/pdf-template \
  -H "Authorization: Bearer pf_live_DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "design": {"accent_color": "#0d6efd"}}'

Particularités importantes :

• La réponse correspond toujours à l'état normalisé après l'enregistrement – exactement ce que l'éditeur de modèles afficherait. Les clés inconnues et les références de champ non valides y sont écartées silencieusement : en cas de doute, comparez la réponse avec ce que vous avez envoyé.
• La liste de blocs est un instantané : les champs que vous ajoutez via l'API après la création du modèle n'y sont pas intégrés automatiquement. Utilisez regenerate (remplace vos propres adaptations de blocs !) ou complétez les blocs de manière ciblée via PATCH.
• Si vous activez settings.document_signing.enabled, propform veille automatiquement à ce que le modèle contienne un bloc de signature de document (s'il n'en existe pas encore).

Référence du modèle de blocs

blocks est un tableau de blocs. Chaque bloc possède un type, un id attribué automatiquement et des propriétés dépendant du type (300 blocs au maximum par modèle) :

Références onOffice : dans field/fieldlist, vous pouvez, au lieu d'un identifiant de champ, afficher un champ de l'enregistrement onOffice lié : {"module": "address", "name": "Telefon1", "label": "Téléphone"} (modules address et estate ; le champ doit exister dans votre configuration des champs onOffice).

Exemple :

{
  "blocks": [
    {"type": "heading", "text": "Déclaration du locataire", "level": 1},
    {"type": "paragraph", "text": "Informations fournies par le candidat :"},
    {"type": "fieldlist", "field_ids": [4711, 4712, {"module": "estate", "name": "objekttitel", "label": "Bien"}]},
    {"type": "pagebreak"},
    {"type": "signature", "field_id": null, "label": "Lieu, date, signature", "required": true}
  ]
}

Clés de design (design) : font, heading_font, font_size (7–14), text_color/heading_color/accent_color (hexadécimal), logo_url, logo_position (left/center/right), logo_width_mm (10–90), header_text, footer_text, show_page_numbers, letterhead_id (voir Papiers à en-tête) ainsi que letterhead_margin_top/right/bottom/left (0–100 mm, null = marges du papier à en-tête).

Clés de paramètres (settings) : empty_fields (hide/dash), embed_uploaded_images, attach_uploaded_pdfs, document_signing.enabled.

Papiers à en-tête

Votre propre papier à en-tête (PDF ou image) est placé en arrière-plan sous chaque page du PDF généré – avec, en option, une feuille suivante distincte à partir de la page 2 :

Paramètres de téléversement (POST, multipart) : letterhead_name (obligatoire), letterhead_first (obligatoire, PDF/PNG/JPG jusqu'à 10 Mo – la première feuille), letterhead_continuation (facultatif – la feuille suivante, même type de fichier), letterhead_margin_top/right/bottom/left (facultatif, mm), form_id (facultatif – le papier à en-tête est alors réservé à ce formulaire ; sans indication, il rejoint la bibliothèque du compte).

curl -X POST https://propform.io/api/v1/letterheads \
  -H "Authorization: Bearer pf_live_DEIN_KEY" \
  -F "letterhead_name=Papier entreprise" \
  -F "letterhead_first=@briefbogen.pdf" \
  -F "letterhead_continuation=@folgebogen.pdf"

• Les PDF chiffrés ou endommagés sont refusés avec 422. Les images en basse résolution sont acceptées, mais la réponse contient alors une remarque dans le champ warning.
• Affectation au formulaire : définissez design.letterhead_id dans le PATCH du modèle PDF (les papiers à en-tête du compte partout, ceux réservés à un formulaire uniquement dans leur propre formulaire).

Paramètres du compte

La réponse est regroupée selon les sections de paramètres du tableau de bord :

curl -X PATCH https://propform.io/api/v1/account \
  -H "Authorization: Bearer pf_live_DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"styling": {"default_accent_color": "#0d6efd"}, "statistics": {"save_ips": false}}'

• domain est volontairement en lecture seule : un changement de sous-domaine ou de domaine casserait tous les liens de formulaire déjà intégrés – cela n'est possible que dans le tableau de bord.
• staff_area.enabled ne peut être activé que si votre forfait comprend des places de collaborateurs (seat_limit > 0, sinon 422). seat_limit lui-même découle du forfait et n'est pas modifiable.
• L'adresse e-mail (connexion), le mot de passe, les clés API, les certificats et les données d'abonnement/de paiement ne font pas partie de l'API.
• Les emplacements d'e-mail dans notifications sont enregistrés sous forme de liste compacte : les emplacements vides sont resserrés après l'enregistrement.

Configuration onOffice

La réponse contient notamment api_type (normal/marketplace_api), connection_ok, credentials_set, email_onoffice_api_user (+ _is_functional), field_config_locale et reason_cancellation. Pour des raisons de sécurité, le token et le secret de l'API n'apparaissent dans aucune réponse.

Modifiable via PATCH :

Collaborateurs (espace collaborateurs)

Les formulaires dont la protection d'accès collaborateurs est activée ne sont accessibles qu'après connexion via un lien e-mail (magic link). Vous gérez les collaborateurs et les groupes correspondants via l'API :

• La limite de places de votre forfait (staff_area.seat_limit sous /account) est strictement appliquée lors de la création, de l'activation et de l'import (422). Seuls les collaborateurs actifs occupent une place.
• Pour les collaborateurs onOffice, le nom, l'e-mail et les groupes proviennent de la synchronisation quotidienne avec onOffice – l'e-mail n'est donc pas modifiable via l'API.
• Désactiver (is_active: false) met immédiatement fin à toutes les sessions en cours du collaborateur.
• Si vous supprimez un groupe utilisé dans des partages de formulaires, il en est retiré ; s'il ne reste aucun partage, le formulaire n'est partagé avec personne (volontairement restrictif) – redéfinissez alors le partage.
• Vous contrôlez quels formulaires sont protégés et qui peut les voir via les champs de formulaire staff_only_enabled, staff_allowed_member_ids et staff_allowed_group_ids dans le PATCH du formulaire ; les réglages au niveau du compte (staff_area.enabled, session_days) se trouvent sous /account.

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).