propform API (REST)

With the propform API, you can manage your forms, submissions, statistics, PDF templates, letterheads, staff members and account settings from external applications – for example, from your own tools, scripts or automation platforms such as Zapier, Make or n8n.

> Base URL: https://propform.io/api/v1 > > All requests and responses are in JSON (Content-Type: application/json). Timestamps are in ISO 8601 format (e.g. 2026-07-07T08:30:00+00:00).

Quick start in 3 steps

1. Create an API key: Go to Settings → API Keys, click on Create API Key and copy the key displayed (format pf_live_…). For security reasons, it will be displayed to you only this once.

2. Test the connection: Replace pf_live_DEIN_KEY and call:

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

   Response:

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

3. First real query – list your forms:

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

Authentication

The API uses API keys as bearer tokens. Every request requires the key in the Authorization header (Authorization: Bearer pf_live_…). If no key is provided or the key is invalid, the API responds with 401.

• You can manage keys under Settings → API Keys: create, name and revoke them at any time.
• A revoked key loses access immediately.
• A maximum of 10 API keys are permitted per account.
• Treat the key like a password – it has full access to your forms and submissions. Do not disclose it in the browser frontend or in public repositories.

Rate Limits

• 60 requests per minute per key.
• Additionally, 300 requests per minute per IP address (to prevent overload).

If these limits are exceeded, the API responds with 429 Too Many Requests and an Retry-After header (seconds until the next permitted attempt). Include a short delay in your automations if you see this status.

Response format, pagination and errors

Successful responses return the data in the data field.

Lists are paginated. Control them via per_page (default 25, max. 100) and page. The response also contains links and 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 }
}

Errors always have an message field; for validation errors (422), the details for each field are contained in errors:

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

Forms

The form is a resource in the API: you can also read and write the settings for email sending and ChatGPT integration directly on the form. The field names correspond exactly to the settings in the form editor.

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

Important points to note:

• PATCH semantics: Fields that you do not include in the request remain unchanged. This means you can safely modify individual settings.
• Activate ("active": true) only works as long as your plan’s limit on active forms has not been reached (otherwise 422). Deactivation is always possible.
• Forms cannot be deleted via the API – this is deliberately restricted to the dashboard.
• Items that are not writable include slug, counters and template flags. Passwords (e.g. form password) are writable, but never appear in responses.
• The list contains all your forms – including those shared as copy templates. The read-only field form_template indicates that sharing; use the template=0/1 filter to filter by it.
• Every form response contains the form’s public url.

Frequently used form settings

A form has over 100 settings (all of which are also available in the editor). The most important ones are:

You can view the complete object at any time via GET /forms/{id}.

👉 You'll find the complete list of all fields and formats in the API field reference.

Fields

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

Frequently used field properties

Display variants via API

With display_variant you control how a field is displayed in the form — the stored value and the onOffice connection remain identical. null or empty = standard display. Valid values per field type:

Unknown values or values that don't match the field type are ignored when rendering (standard display). For cards, icons and images, select_option_meta provides the additional data per onOffice key value — a JSON string of the form:

{"haus": {"icon": "home", "description": "Detached or terraced house"}, "wohnung": {"image": "https://…/wohnung.jpg"}}

icon is an icon name from the integrated Tabler Icons set (lowercase letters/digits/hyphens only, e.g. home, building-estate, currency-euro), image an http(s) image URL (ideally from the media library), description a text below the option title (cards, icon and image tiles). Icons appear on icon tiles, in front of the option label in the button group and above the buttons of the Likert scale. Empty or unknown entries are ignored. For the slider, minimum/maximum value and step come from min_value/max_value/step (also for the from/to rangeslider); for the rating, max_value determines the number of steps (2–10, default 5).

Settings per display variant (all optional; unsuitable values are ignored when rendering):

Multi-select note: The tile/list displays show the options flat; there is no parent/child automation there. The stored multiselect_mode is left unchanged when you set a display variant and takes effect again as soon as you switch back to the default display.

Slider note: The simple slider — like the from/to slider — only sends a value after an interaction; an untouched slider behaves like an empty field.

Note: The older range slider via special_field: "range" keeps working unchanged (legacy). For new sliders we recommend display_variant: "slider" — if a field has both set, display_variant wins.

Link field via API

You create the Link field (display, link, create, edit and unlink connected onOffice records) with onoffice_module: "relationlist". The relation type consists of relation_type (e.g. estate:address:owner) plus relation_anchor_module (estate or address – which side is the loaded form record); on top of that come the switches relation_show_existing, relation_allow_search, relation_allow_create, relation_allow_edit, relation_allow_remove, the duplicate check (relation_duplicate_check + relation_duplicate_check_fields) and the mini-form element list relation_subform_elements (array of {type: "field", name, required, half} or layout elements {type: "headline"|"description"|"dividingline"|"collapsible", text}). For creation there are also relation_advisor_mode (anchor = use the agent of the loaded record, fixed = fixed user from relation_advisor_user_id) and relation_auto_open_create (open the mini form automatically when no connections are displayed). All values and limits are listed in the field reference.

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": "relationlist",
    "relation_type": "estate:address:owner",
    "relation_anchor_module": "estate",
    "label": "Owner",
    "relation_show_existing": true,
    "relation_allow_create": true,
    "relation_subform_elements": [
      {"type": "field", "name": "Vorname", "half": true},
      {"type": "field", "name": "Name", "required": true, "half": true},
      {"type": "field", "name": "Email", "required": true}
    ]
  }'

Sorting: For reorder, the order in the field_ids array determines the new position. The array must contain exactly all field IDs of the form (if one is missing or an unrelated one is included → 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]}'

onOffice field configuration

GET /onoffice/fields returns the field configuration for your onOffice account – per module (address, estate, task, calendar, agentsLog, file, project) – listing all fields with their label, type, length and permitted values. This is how you find the valid values for onoffice_field_name. Use ?module=address to filter by 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" } }
    }
  }
}

> A working onOffice API connection is required; otherwise, the endpoint will return 409.

POST /onoffice/fields/refresh reloads the field configuration from onOffice – for example after you have created a field or changed permitted values in onOffice. The refresh runs in the background: the response is 202 with data.status = pending; a few seconds later GET /onoffice/fields returns the new state. Both endpoints return a meta object with the time of the last build (updated_at), the language of the field labels (locale) and refresh_pending (true while a refresh triggered via the API is still running). Without this call, propform refreshes the configuration once a day and every time the form overview is opened. Limit: 120 calls per hour.

{
  "message": "…",
  "data": { "status": "pending", "already_pending": false },
  "meta": { "updated_at": "2026-09-08T06:12:41+02:00", "locale": "de", "refresh_pending": true, "last_refresh_failed": false }
}

Conditions (Rules)

The write endpoint works in the same way as the condition editor in the dashboard: All rules are always saved in one go (no individual additions). So first read the list using GET, modify it, and then send the entire list back using PUT. A rule consists of clauses (if conditions, linked to mode = all/any) and actions (Then actions):

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

• Operators: equals, not_equals, empty, not_empty, starts_with, not_starts_with, contains, not_contains
• Campaigns: 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
• In addition to field IDs, virtual targets are also permitted: __form_title, __form_description, __submit, __submit_spinner, __multistep_back, __multistep_next (only set_label, show, hide are permitted there; for the spinner, only set_label).
• All referenced field IDs must belong to the form.
• Limits per request: max. 200 rules, 50 clauses/actions each.
• As with the dashboard, conditions are only available from the plan with 10 active forms onwards (otherwise 403).

You can find details on how the rules work under Conditions, Rules & Calculations.

Submissions and statistics

The content of a submission (content) is grouped by onOffice module:

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

If you have disabled the saving of submission data in the privacy settings, content is always null – but the submission still counts towards the statistics. The stats response contains views, submissions and conversion_rate.

Webhooks (new submissions in real time)

Instead of regularly checking for submissions, you can be notified via a webhook: propform immediately sends an POST to your URL whenever a new submission is made.

💡 You can also manage webhooks in the frontend without an API key: in the settings under "Webhooks" (for all forms) or directly in the form editor under "Webhooks (Zapier, n8n, Make …)".

URL requirements: It must be publicly accessible and use http:// or https://. Internal or local addresses (e.g. localhost, 127.0.0.1, private network IPs) are rejected for security reasons (422). As the submission data is transmitted, please use https:// where possible.

The response when creating the delivery contains secret, which is used to sign each delivery (you can retrieve it later at any time using 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"
  }
}

Each delivery contains two headers:

• X-Propform-Event – the event type (currently always submission.created)
• X-Propform-Signature – sha256=<HMAC-SHA256 des Request-Bodys mit deinem secret>

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

Free text / message with onOffice macros (payload_template)

Optionally, you can store a free-text template for each subscription. After every form submission, propform resolves onOffice macros in it (against the records the submission created or edited) and includes the result as a dedicated message field in the payload — ideal as a ready-made message for Slack & co., without having to assemble anything in your receiving workflow. The field is named text by default (see below).

Example template:

New inquiry from _Vorname _Name about _objekttitel → _getEstateLink

becomes the following in the payload:

"text": "New inquiry from Max Mustermann about Traumwohnung am Stadtpark → https://smart.onoffice.de/…"

Message field name (message_key): By default the field is named text – this way Slack, Microsoft Teams and Google Chat interpret the payload directly as a message. Discord expects content. For Zapier/n8n/Make the name is arbitrary. You can change it per webhook via the message_key parameter (in the frontend via "Message field name").

Please note:

• The same macros work as in propform's email templates (onOffice field macros, _getAddressLink, _getEstateLink, …).
• A macro can only be resolved if the submission has a matching record context (e.g. _objekttitel requires a linked property). Without context, the macro remains unresolved in the text.
• Values that are only written after the webhook is sent (file uploads to onOffice, multiselect fields written via "extend") may still be missing from the resolved text.
• Without a free-text template, no message field is sent.
• Maximum 5,000 characters.

Verify the signature (recommended)

Verify the signature to ensure that the request really originates from propform. Calculate the HMAC using the raw request body (not the parsed JSON) and compare it in real time.

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

Delivery, retries and limits

• Your endpoint should respond with an 2xx status. In the event of errors, propform will attempt delivery up to 3 times (with a waiting period).
• If a subscription fails 20 times in a row, it is automatically deactivated (is_active: false, visible via GET /webhooks). Simply create it again afterwards.
• A maximum of 20 webhook subscriptions are permitted per account.
• File attachments are not part of the payload.

Form folders

Folders structure the forms overview in the dashboard. Each form sits in at most one folder (form_folder_id, null = "No folder"). Folders can have one sublevel (parent_id, at most two levels). Not to be confused with the form groups, which control the copy sharing.

Assign a form via the form PATCH using form_folder_id (ID of one of your folders, or null). Filter the forms list with ?folder=<id> or ?folder=none.

Form groups

You assign the group IDs in the form PATCH as form_groups (array).

PDF templates (PDF generator)

propform can generate its own PDF from every submission (see PDF generator). You can read and write a form's template – block list, design and settings – entirely via the 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"}}'

Important points to note:

• The response is always the normalised state after saving – exactly what the template editor would display. Unknown keys and invalid field references are silently discarded: if in doubt, compare the response with what you sent.
• The block list is a snapshot: fields you add via the API after the template has been created do not automatically end up in it. Use regenerate (which replaces your own block customisations!) or add the blocks specifically via PATCH.
• If you enable settings.document_signing.enabled, propform automatically ensures that the template contains a document signature block (if there is none yet).

Block model reference

blocks is an array of blocks. Each block has a type, an automatically assigned id and type-specific properties (max. 300 blocks per template):

onOffice references: In field/fieldlist, instead of a field ID you can also output a field of the linked onOffice record: {"module": "address", "name": "Telefon1", "label": "Phone"} (modules address and estate; the field must exist in your onOffice field configuration).

Example:

{
  "blocks": [
    {"type": "heading", "text": "Tenant self-disclosure", "level": 1},
    {"type": "paragraph", "text": "Details provided by the prospect:"},
    {"type": "fieldlist", "field_ids": [4711, 4712, {"module": "estate", "name": "objekttitel", "label": "Property"}]},
    {"type": "pagebreak"},
    {"type": "signature", "field_id": null, "label": "Place, date, signature", "required": true}
  ]
}

Design keys (design): font, heading_font, font_size (7–14), text_color/heading_color/accent_color (hex), logo_url, logo_position (left/center/right), logo_width_mm (10–90), label_column_width (20–60), header_text, footer_text, show_page_numbers, letterhead_id (see Letterheads) as well as letterhead_margin_top/right/bottom/left (0–100 mm, null = margins of the letterhead).

Settings keys (settings): empty_fields (hide/dash/blank), embed_uploaded_images, attach_uploaded_pdfs, embed_existing_files, embedded_image_size (small/column/full), document_signing.enabled.

Letterheads

Your own letterhead (PDF or image) is placed as a background under every page of the generated PDF – optionally with its own continuation sheet from page 2 onwards:

Upload parameters (POST, multipart): letterhead_name (required), letterhead_first (required, PDF/PNG/JPG up to 10 MB – the first sheet), letterhead_continuation (optional – the continuation sheet, same file types), letterhead_margin_top/right/bottom/left (optional, mm), form_id (optional – this makes the letterhead form-private; without it, it goes into the account library).

curl -X POST https://propform.io/api/v1/letterheads \
  -H "Authorization: Bearer pf_live_DEIN_KEY" \
  -F "letterhead_name=Company letterhead" \
  -F "letterhead_first=@letterhead.pdf" \
  -F "letterhead_continuation=@continuation-sheet.pdf"

• Encrypted or corrupted PDFs are rejected with 422. Low-resolution images are accepted, but the response then contains a note in the warning field.
• Assigning to a form: set design.letterhead_id in the PDF template PATCH (account letterheads can be used everywhere, form-private ones only in their own form).

Account settings

The response is grouped by the settings areas of the 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 is deliberately read-only: Changing the subdomain or domain would break all form links that are already embedded – this is only possible in the dashboard.
• staff_area.enabled can only be activated if your plan includes staff seats (seat_limit > 0, otherwise 422). seat_limit itself is determined by your plan and is not writable.
• Email address (login), password, API keys, certificates and subscription/payment data are not part of the API.
• The email slots in notifications are stored as a compact list: gaps are closed up after saving.

onOffice configuration

The response contains, among other things, api_type (normal/marketplace_api), connection_ok, credentials_set, email_onoffice_api_user (+ _is_functional), field_config_locale and reason_cancellation. For security reasons, the API token and secret never appear in any response.

Changeable via PATCH:

Staff members (staff area)

Forms with staff access protection enabled can only be reached after logging in via magic link. You manage the staff members and groups behind it via the API:

• The seat limit of your plan (staff_area.seat_limit under /account) is strictly enforced when creating, activating and importing (422). Only active staff members occupy a seat.
• For onOffice staff members, name, email and groups come from the daily onOffice sync – the email is therefore not changeable via the API.
• Deactivating (is_active: false) immediately ends all of the staff member's running sessions.
• If you delete a group that is used in form access settings, it is removed there; if no access entry remains, the form is accessible to nobody (deliberately restrictive) – set the access again in that case.
• Which forms are protected and who is allowed to see them is controlled via the form fields staff_only_enabled, staff_allowed_member_ids and staff_allowed_group_ids in the form PATCH; the account switches (staff_area.enabled, session_days) are under /account.

Tips for Zapier, Make & Co.

• ‘New submission’ trigger: Create a webhook subscription (see above) – more reliable and faster than regular polling.
• Polling alternative: Note GET /forms/{id}/submissions?sort=desc and the highest id already processed.
• Connection test: GET /me.
• Detect new forms: GET /forms?updated_since=….
• For 429, introduce a short delay and respect the Retry-After header.

Versioning

The current version is v1 and is fixed in the path (/api/v1). We add new fields and endpoints in a backwards-compatible manner without changing the version – your client should therefore simply ignore any unknown fields in responses. Fundamental, non-backwards-compatible changes would be released under a new version (/api/v2).