API propform (REST)

Con l'API propform puoi gestire i tuoi moduli, gli invii, le statistiche, i modelli PDF, le carte intestate, i collaboratori e le impostazioni dell’account da applicazioni esterne, ad esempio dai tuoi strumenti, script o piattaforme di automazione come Zapier, Make o n8n.

> URL di base: https://propform.io/api/v1 > > Tutte le richieste e le risposte sono in formato JSON (Content-Type: application/json). I timestamp sono in formato ISO-8601 (ad es. 2026-07-07T08:30:00+00:00).

Guida rapida in 3 passaggi

1. Creare una chiave API: Vai su Impostazioni → Chiavi API, clicca su Crea chiave API e copia la chiave visualizzata (formato pf_live_…). Per motivi di sicurezza, ti verrà mostrata solo questa volta.

2. Verifica la connessione: sostituisci pf_live_DEIN_KEY e accedi a:

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

   Risposta:

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

3. Prima richiesta effettiva – elenca i tuoi moduli:

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

Autenticazione

L’API utilizza le chiavi API come token bearer. Ogni richiesta richiede la chiave nell’intestazione Authorization (Authorization: Bearer pf_live_…). In assenza di chiave o in caso di chiave non valida, l’API risponde con 401.

• Puoi gestire le chiavi in Impostazioni → Chiavi API: crearle, assegnare loro un nome e revocarle in qualsiasi momento.
• Una chiave revocata perde immediatamente l’accesso.
• Per ogni account sono consentite al massimo 10 chiavi API.
• Tratta la chiave come una password: essa consente l’accesso completo ai tuoi moduli e ai tuoi invii. Non rivelarla nel frontend del browser né in repository pubblici.

Limiti di frequenza

• 60 richieste al minuto per chiave.
• Inoltre, 300 richieste al minuto per indirizzo IP (protezione dal sovraccarico).

In caso di superamento del limite, l’API risponde con 429 Too Many Requests e un’intestazione Retry-After (secondi che mancano al prossimo tentativo consentito). Inserisci una breve pausa nelle automazioni quando visualizzi questo stato.

Formato della risposta, impaginazione ed errori

Le risposte andate a buon fine forniscono i dati nel campo data.

Gli elenchi sono impaginati. Gestiscili tramite per_page (impostazione predefinita 25, max. 100) e page. La risposta contiene inoltre links e 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 }
}

Gli errori hanno sempre un campo message; in caso di errori di convalida (422), i dettagli per ciascun campo sono riportati in errors:

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

Moduli

Il modulo è una risorsa nell’API: puoi leggere e modificare le impostazioni relative all’invio delle e-mail e all’integrazione con ChatGPT direttamente sul modulo. I nomi dei campi corrispondono esattamente alle impostazioni nell’editor del modulo.

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

Caratteristiche importanti:

• Semantica PATCH: i campi che non invii rimangono invariati. Puoi quindi modificare singole impostazioni in tutta sicurezza.
• Attivare ("active": true) funziona solo finché non viene raggiunto il limite del tuo piano relativo ai moduli attivi (altrimenti 422). La disattivazione è sempre possibile.
• I moduli non possono essere eliminati tramite API: questa operazione è possibile solo nella dashboard, per scelta.
• Non sono modificabili, tra gli altri, slug, i contatori e i flag dei modelli. Le password (ad es. la password del modulo) sono modificabili, ma non compaiono mai nelle risposte.
• L'elenco contiene tutti i tuoi moduli – compresi quelli condivisi come modello da copiare. Il campo di sola lettura form_template indica questa condivisione; con il filtro template=0/1 puoi filtrare in base ad essa.
• Ogni risposta al modulo contiene l’url pubblico del modulo.

Impostazioni dei moduli utilizzate di frequente

Un modulo dispone di oltre 100 impostazioni (tutte quelle offerte anche dall’editor). Le più importanti:

Puoi visualizzare l’oggetto completo in qualsiasi momento tramite GET /forms/{id}.

👉 Trovi l'elenco completo di tutti i campi e formati nella referenza dei campi API.

Campi

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

Proprietà dei campi di uso frequente

Ordinamento: nel caso di reorder, l’ordine nell’array field_ids determina la nuova posizione. L'array deve contenere esattamente tutti gli ID dei campi del modulo (se ne manca uno o ne è presente uno estraneo → 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]}'

Configurazione dei campi di onOffice

GET /onoffice/fields fornisce la configurazione dei campi del tuo account onOffice – per ogni modulo (address, estate, task, calendar, agentsLog, file, project) tutti i campi con etichetta, tipo, lunghezza e valori consentiti. In questo modo puoi trovare i valori validi per onoffice_field_name. Con ?module=address puoi filtrare per un modulo.

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

> È necessario che la connessione all’API di onOffice funzioni correttamente; in caso contrario, l’endpoint risponde con 409.

Condizioni (regole)

L'endpoint di scrittura funziona come l'editor delle condizioni nella dashboard: tutte le regole vengono sempre salvate in una volta sola (non è possibile aggiungerne una singola alla volta). Quindi, leggi prima con GET, modifica l’elenco e invialo per intero tramite PUT. Una regola è costituita da clauses (condizioni «Se», collegate a mode = all/any) e actions (azioni "allora"):

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

• Operatori: equals, not_equals, empty, not_empty, starts_with, not_starts_with, contains, not_contains
• Azioni: 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
• Come destinazione sono consentiti, oltre agli ID dei campi, anche destinazioni virtuali: __form_title, __form_description, __submit, __submit_spinner, __multistep_back, __multistep_next (in questo caso solo set_label, show, hide; per lo spinner solo set_label).
• Tutti gli ID dei campi a cui si fa riferimento devono appartenere al modulo.
• Limiti per richiesta: max. 200 regole, 50 clausole/azioni ciascuna.
• Le condizioni sono disponibili, come nella dashboard, solo a partire dal piano con 10 moduli attivi (altrimenti 403).

Per i dettagli sul funzionamento delle regole, consulta Condizioni, regole e calcoli.

Invii e statistiche

Il contenuto di un invio (content) è raggruppato in base ai moduli di 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"
  }
}

Se nelle impostazioni sulla privacy hai disattivato il salvataggio dei dati degli invii, content è sempre null – l’invio viene comunque conteggiato nelle statistiche. La risposta stats contiene views, submissions e conversion_rate.

Webhook (nuovi invii in tempo reale)

Invece di interrogare regolarmente gli invii, puoi ricevere notifiche tramite webhook: propform invia immediatamente un POST al tuo URL ogni volta che viene effettuato un nuovo invio.

💡 Puoi gestire i webhook anche nel frontend, senza chiave API: nelle impostazioni alla voce «Webhooks» (per tutti i moduli) oppure direttamente nell'editor dei moduli alla voce «Webhook (Zapier, n8n, Make …)».

Requisiti per l’URL: deve essere accessibile pubblicamente e utilizzare http:// o https://. Gli indirizzi interni o locali (ad es. localhost, 127.0.0.1, IP di reti private) vengono rifiutati per motivi di sicurezza (422). Poiché i dati inviati vengono trasmessi, utilizza se possibile https://.

La risposta generata al momento della creazione contiene l’secret, con cui viene firmata ogni consegna (puoi recuperarlo in qualsiasi momento tramite 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"
  }
}

Ogni consegna contiene due intestazioni:

• X-Propform-Event – il tipo di evento (attualmente sempre submission.created)
• X-Propform-Signature – sha256=<HMAC-SHA256 des Request-Bodys mit deinem secret>

Esempio di payload:

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

Testo libero / messaggio con macro onOffice (payload_template)

Facoltativamente, puoi salvare un modello di testo libero per ogni abbonamento. Dopo ogni invio del modulo, propform vi risolve le macro onOffice (sui record creati o modificati dall'invio) e include il risultato nel payload come campo di messaggio dedicato: ideale come messaggio pronto per Slack e simili, senza dover assemblare nulla nel flusso di lavoro ricevente. Il nome del campo è text per impostazione predefinita (vedi sotto).

Esempio di modello:

Nuova richiesta di _Vorname _Name per _objekttitel → _getEstateLink

nel payload diventa:

"text": "Nuova richiesta di Max Mustermann per Traumwohnung am Stadtpark → https://smart.onoffice.de/…"

Nome del campo del messaggio (message_key): Per impostazione predefinita il campo si chiama text: così Slack, Microsoft Teams e Google Chat interpretano il payload direttamente come messaggio. Discord si aspetta content. Per Zapier/n8n/Make il nome è libero. Puoi modificarlo per ogni webhook tramite il parametro message_key (nel frontend alla voce «Nome del campo del messaggio»).

Da tenere presente:

• Funzionano le stesse macro dei modelli e-mail di propform (macro dei campi onOffice, _getAddressLink, _getEstateLink, …).
• Una macro può essere risolta solo se l'invio dispone del contesto di record corrispondente (ad es. _objekttitel richiede un immobile collegato). Senza contesto, la macro resta non risolta nel testo.
• I valori scritti solo dopo l'invio del webhook (caricamenti di file su onOffice, campi a selezione multipla scritti tramite «estendi») possono ancora mancare nel testo risolto.
• Senza modello di testo libero non viene inviato alcun campo messaggio.
• Massimo 5.000 caratteri.

Verifica della firma (consigliata)

Verifica la firma per assicurarti che la richiesta provenga effettivamente da propform. Calcola l’HMAC sul corpo della richiesta grezzo (non sul JSON analizzato) e confrontalo in tempo reale.

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);
});

Consegna, ripetizione e limiti

• Il tuo endpoint dovrebbe rispondere con uno stato 2xx. In caso di errori, propform tenta la consegna fino a 3 volte (con un intervallo di attesa).
• Se un abbonamento fallisce 20 volte consecutive, viene disattivato automaticamente (is_active: false, visibile tramite GET /webhooks). A quel punto basta ricrearlo.
• Per ogni account sono consentiti al massimo 20 abbonamenti webhook.
• Gli allegati non fanno parte del payload.

Gruppi di moduli

Puoi assegnare gli ID dei gruppi nel PATCH del modulo come form_groups (array).

Modelli PDF (generatore PDF)

propform può creare un proprio PDF da ogni invio (vedi Generatore PDF). Il modello di un modulo – elenco dei blocchi, design e impostazioni – lo leggi e lo scrivi completamente tramite 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"}}'

Caratteristiche importanti:

• La risposta è sempre lo stato normalizzato dopo il salvataggio – esattamente ciò che mostrerebbe anche l’editor dei modelli. Le chiavi sconosciute e i riferimenti a campi non validi vengono scartati silenziosamente: in caso di dubbio, confronta la risposta con ciò che hai inviato.
• L’elenco dei blocchi è un’istantanea: i campi che aggiungi tramite API dopo la creazione del modello non vi vengono inseriti automaticamente. Usa regenerate (sostituisce le tue personalizzazioni dei blocchi!) oppure integra i blocchi in modo mirato tramite PATCH.
• Se attivi settings.document_signing.enabled, propform provvede automaticamente a un blocco firma del documento nel modello (se non ne è già presente uno).

Riferimento del modello a blocchi

blocks è un array di blocchi. Ogni blocco ha type, un id assegnato automaticamente e proprietà specifiche del tipo (max. 300 blocchi per modello):

Riferimenti onOffice: in field/fieldlist puoi riportare, al posto di un ID di campo, anche un campo del record onOffice collegato: {"module": "address", "name": "Telefon1", "label": "Telefono"} (moduli address ed estate; il campo deve esistere nella tua configurazione dei campi onOffice).

Esempio:

{
  "blocks": [
    {"type": "heading", "text": "Autocertificazione dell'inquilino", "level": 1},
    {"type": "paragraph", "text": "Dati dell'interessato:"},
    {"type": "fieldlist", "field_ids": [4711, 4712, {"module": "estate", "name": "objekttitel", "label": "Immobile"}]},
    {"type": "pagebreak"},
    {"type": "signature", "field_id": null, "label": "Luogo, data, firma", "required": true}
  ]
}

Chiavi di design (design): font, heading_font, font_size (7–14), text_color/heading_color/accent_color (esadecimali), logo_url, logo_position (left/center/right), logo_width_mm (10–90), header_text, footer_text, show_page_numbers, letterhead_id (vedi Carte intestate) e letterhead_margin_top/right/bottom/left (0–100 mm, null = margini della carta intestata).

Chiavi delle impostazioni (settings): empty_fields (hide/dash), embed_uploaded_images, attach_uploaded_pdfs, document_signing.enabled.

Carte intestate

La tua carta intestata (PDF o immagine) viene posta come sfondo sotto ogni pagina del PDF generato – facoltativamente con un foglio successivo dedicato a partire dalla pagina 2:

Parametri di caricamento (POST, multipart): letterhead_name (obbligatorio), letterhead_first (obbligatorio, PDF/PNG/JPG fino a 10 MB – il primo foglio), letterhead_continuation (facoltativo – il foglio successivo, stesso tipo di file), letterhead_margin_top/right/bottom/left (facoltativi, mm), form_id (facoltativo – in questo modo la carta intestata diventa privata del modulo; senza, finisce nella libreria dell’account).

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

• I PDF crittografati o danneggiati vengono rifiutati con 422. Le immagini a bassa risoluzione vengono accettate, ma in tal caso la risposta contiene un avviso nel campo warning.
• Assegnazione al modulo: imposta design.letterhead_id nel PATCH del modello PDF (le carte intestate dell’account ovunque, quelle private del modulo solo nel rispettivo modulo).

Impostazioni dell’account

La risposta è raggruppata secondo le sezioni delle impostazioni della dashboard:

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 è di sola lettura per scelta: un cambio di sottodominio o dominio romperebbe tutti i link ai moduli già incorporati – questa operazione è possibile solo nella dashboard.
• staff_area.enabled può essere attivato solo se il tuo piano include posti collaboratore (seat_limit > 0, altrimenti 422). seat_limit stesso deriva dal piano e non è modificabile.
• Indirizzo e-mail (login), password, chiavi API, certificati e dati di abbonamento/pagamento non fanno parte dell’API.
• Gli slot e-mail in notifications vengono salvati come elenco compatto: dopo il salvataggio le posizioni vuote vengono compattate.

Configurazione onOffice

La risposta contiene tra l’altro api_type (normal/marketplace_api), connection_ok, credentials_set, email_onoffice_api_user (+ _is_functional), field_config_locale e reason_cancellation. Per motivi di sicurezza, il token e il secret dell’API non compaiono in nessuna risposta.

Modificabili tramite PATCH:

Collaboratori (area collaboratori)

I moduli con la protezione di accesso per collaboratori attivata sono raggiungibili solo dopo il login tramite magic link. I collaboratori e i gruppi alla base li gestisci tramite API:

• Il limite di posti del tuo piano (staff_area.seat_limit in /account) viene applicato rigorosamente alla creazione, all’attivazione e all’importazione (422). Solo i collaboratori attivi occupano un posto.
• Per i collaboratori onOffice, nome, e-mail e gruppi provengono dalla sincronizzazione giornaliera con onOffice – per questo motivo l’e-mail non è modificabile tramite API.
• Disattivare (is_active: false) termina immediatamente tutte le sessioni in corso del collaboratore.
• Se elimini un gruppo utilizzato nelle abilitazioni dei moduli, viene rimosso da esse; se non resta alcuna abilitazione, il modulo non è abilitato per nessuno (volutamente restrittivo) – in tal caso imposta di nuovo l’abilitazione.
• Quali moduli sono protetti e chi può vederli lo controlli tramite i campi del modulo staff_only_enabled, staff_allowed_member_ids e staff_allowed_group_ids nel PATCH del modulo; gli interruttori a livello di account (staff_area.enabled, session_days) si trovano in /account.

Suggerimenti per Zapier, Make & Co.

• Trigger «Nuovo invio»: crea un abbonamento al webhook (vedi sopra) – più affidabile e veloce rispetto alle interrogazioni periodiche.
• Alternativa al polling: prendere nota di GET /forms/{id}/submissions?sort=desc e del valore più alto già elaborato id.
• Test di connessione: GET /me.
• Riconoscimento di nuovi moduli: GET /forms?updated_since=….
• In caso di 429 inserire una breve attesa e rispettare l’intestazione Retry-After.

Gestione delle versioni

La versione attuale è v1 ed è fissata nel percorso (/api/v1). Aggiungiamo nuovi campi ed endpoint in modo retrocompatibile senza modificare la versione; pertanto, il tuo client dovrebbe semplicemente ignorare i campi sconosciuti presenti nelle risposte. Modifiche fondamentali e non retrocompatibili verrebbero pubblicate con una nuova versione (/api/v2).