/

API REFERENCE · Published 2026-10-06 · Updated 2026-10-06 · SecureSMTP

Get a hosted form

GET /api/v1/forms/render/{slug}

GEThttps://securessmtp.com/api/v1/forms/render/{slug}

Returns the fields and settings of a form built in the dashboard form builder, so you can show it on your own page. Send the answers with POST /forms/submit.

Headers

x-securessmtp-api-keystringrequired
The site’s API key (qcs_live_…). x-securesmtp-api-key and x-qcs-api-key are accepted too. See Sites and API keys.

Path parameters

slugstringrequired
The form’s slug from the form builder. Lowercase letters, digits and hyphens only. The form must belong to the same account as the key’s site.

Request

curl https://securessmtp.com/api/v1/forms/render/contact \
  -H "x-securessmtp-api-key: $SECURESSMTP_API_KEY"

Response

200
{
  "ok": true,
  "form": {
    "id": "5d0c7a3e-2b1f-4c8d-9e6a-7f8b9c0d1e2f",
    "name": "Contact",
    "slug": "contact",
    "fields": [
      {
        "name": "name",
        "label": "Your name",
        "type": "text",
        "required": true,
        "placeholder": "Jane Doe"
      },
      {
        "name": "email",
        "label": "Email",
        "type": "email",
        "required": true,
        "placeholder": "[email protected]"
      },
      {
        "name": "topic",
        "label": "Topic",
        "type": "select",
        "required": false,
        "placeholder": "",
        "options": [
          "Sales",
          "Support"
        ]
      },
      {
        "name": "message",
        "label": "Message",
        "type": "textarea",
        "required": false,
        "placeholder": ""
      }
    ],
    "settings": {
      "submit_label": "Send message",
      "success_message": "Thanks! We’ll be in touch.",
      "brand_color": "#FF5500",
      "radius_preset": "medium",
      "button_align": "left",
      "field_tone": "light",
      "card_wrap": false
    },
    "updated_at": "2026-10-05T11:20:00.000Z"
  }
}
Response fields
okbooleanrequired
true.
form.idstringrequired
The form’s ID (UUID).
form.namestringrequired
The form’s name.
form.slugstringrequired
The slug you asked for.
form.fieldsobject[]required
The fields in order. Each has name (use it as the key in fields when you submit), label, type (text, email, tel, url, number, textarea, select, checkbox, date or time), placeholder, required and, for choices, options (string[]).
form.settingsobjectrequired
The form’s settings as saved in the builder: submit_label, success_message, notify_email, from_name, brand_color, radius_preset, button_align, field_tone, card_wrap. A key that was never set may be missing.
form.updated_atstringrequired
When the form was last changed (ISO 8601).

The response has Cache-Control: public, max-age=60, stale-while-revalidate=300 and an X-QCS-Form-Updated header with the same time as updated_at. Changes in the builder can take up to a minute to show.

Errors

Errors have an error field and no ok field. The slug is checked before the key.

HTTPValueMeaningWhat to do
400invalid_slugThe slug has characters other than a–z, 0–9 and hyphens.Copy the slug from the form builder.
401missing_api_keyNo key header was sent.Send the key in the x-securessmtp-api-key header.
401invalid_api_keyNo site has this key. Keys stop working as soon as they are rotated.Copy the current key from the dashboard, or rotate it to get a new one.
403site_disabledThe site is disabled.Check GET /blocks/status. See Blocks.
403site_has_no_ownerThe site is not linked to an account.Contact support.
404form_not_foundYour account has no form with this slug.Check the slug, and that the key belongs to a site in the same account.
410form_archivedThe form was archived.Restore it in the form builder or use another form.

See Hosted forms.

Previous
Submit a form
Next
Add a contact to a sequence