Try our conversational search powered by Generative AI!

Mar 1, 2024
(5 votes)

Headless forms reloaded (beta)

Forms is used on the vast majority of CMS installations. But using Forms in a headless setup is a bit of pain since the rendering pipeline is based on ASP.NET MVC. We do have an extension to our Content Delivery API that includes the generated forms HTML in the json model for a page, but if you want the frontend to control the look & feel of the rendered form, you’re fighting an uphill battle. Better then if Forms could just expose the raw forms configuration with a handy front-end SDK with a good default rendering.

Note: This feature is in Beta, you are welcome to use it, but we do have more changes coming before the official release. Beta packages will be removed once official packages are released.

What's in it?

  1. Forms 5 [package] [docs]
  2. New REST API [beta package] [beta docs]
  3. (optional) Graph integration [beta package] [beta docs]
  4. (optional) generic JS SDK [beta package] [beta docs] [repo]
  5. (optional) react specific SDK [beta package] [beta docs] [repo]

As a quick example I created the worlds least interesting form using a boilerplate Alloy MVC site, which yes is not headless, but that’s the point really. This is just good-old-forms under the hood.

With a reference to the headless forms beta feed we can add the new REST API and optionally swashbuckle:

<PackageReference Include="EPiServer.Forms" Version="5.8.0" />
<PackageReference Include="Optimizely.Headless.Form.Service" Version="0.1.0" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />

Getting the new endpoint setup is pretty easy, we need to add a service to startup.cs for the new API and optionally a service + some configuration for swagger:

// Enable OpenAPI documentation

//Configure the API headless forms API
services.AddOptimizelyHeadlessFormService(options =>
    // Enable swagger docs for headless forms API @ /_form/v1/docs/openapi.json
    options.EnableOpenApiDocumentation = true;

    options.FormCorsPolicy = new FormCorsPolicy
        AllowOrigins = new string[] { "_" }, //Enter '_' to allow any origins, multiple origins separate by comma 
        AllowCredentials = true


// Configure swagger UI to use the headless forms API spec
app.UseSwaggerUI(options =>
    options.SwaggerEndpoint("/_form/v1/docs/openapi.json", "Optimizely Headless Form API V1");

With that we get nice local documentation of the API available at /swagger/. In production you would probably want to configure OIDC for access to endpoints and docs.

To get the full form configuration you pass in the GUID of the form container in UUID N format i.e. without any “-“ separators

GET /_form/v1/form/2df32b30ade54eb3970e4ab5170fb5ff

  "key": "2df32b30ade54eb3970e4ab5170fb5ff",
  "properties": {
    "title": "test",
    "allowToStoreSubmissionData": true,
    "showSummarizedData": false,
    "confirmationMessage": "Thank you, come again!",
    "allowAnonymousSubmission": false,
    "allowMultipleSubmission": true,
    "showNavigationBar": true,
    "focusOnForm": true
  "formElements": [
      "key": "2697b674ec554f7a817ea1f977fc2204",
      "contentType": "TextboxElementBlock",
      "displayName": "New form element",
      "properties": {
        "validators": [
            "type": "RequiredValidator",
            "description": null,
            "model": {
              "message": "This field is required.",
              "validationCssClass": "ValidationRequired",
              "additionalAttributes": {
                "required": "",
                "aria-required": "true"
        "label": "Name",
        "placeHolder": "firstname lastname",
        "conditions": []
      "locale": "en",
      "localizations": {}
      "key": "3aa836ec620146cf8291263c51b4b44f",
      "contentType": "SubmitButtonElementBlock",
      "displayName": "New form element",
      "properties": {
        "validators": [],
        "label": "Go!",
        "conditions": []
      "locale": "en",
      "localizations": { "label": "Submit" }
  "locale": "en",
  "localizations": {
    "allowAnonymousSubmissionErrorMessage": "You must be logged in to submit this form. If you are logged in and still cannot post, make sure \"Do not track\" in your browser settings is disabled.",
    "allowMultipleSubmissionErrorMessage": "You already submitted this form.",
    "malformstepconfigruationErrorMessage": "Improperly formed FormStep configuration. Some steps are attached to pages, while some steps are not attached, or attached to content with no public URL."

Installing the Forms to Graph integration of course requires Optimizely Graph, and will simply add a new property “FormRenderTemplate” to the Graph model for a FormContainerBlock exposing the exact same json object available from the REST API.

query MyQuery {
  FormContainerBlock {
    items {

If we want to upgrade to a completely decoupled frontend we can use the react sample from the new forms SDK repository, but I think that warrants it’s own blog post.

Besides any notes you may have here or at for this beta release, we have plans to update the current authorization system for form submitters and refine the SDK to give you a better looking starting point.

Mar 01, 2024


Please login to comment.
Latest blogs
Optimizely and the never-ending story of the missing globe!

I've worked with Optimizely CMS for 14 years, and there are two things I'm obsessed with: Link validation and the globe that keeps disappearing on...

Tomas Hensrud Gulla | Apr 18, 2024 | Syndicated blog

Visitor Groups Usage Report For Optimizely CMS 12

This add-on offers detailed information on how visitor groups are used and how effective they are within Optimizely CMS. Editors can monitor and...

Adnan Zameer | Apr 18, 2024 | Syndicated blog

Azure AI Language – Abstractive Summarisation in Optimizely CMS

In this article, I show how the abstraction summarisation feature provided by the Azure AI Language platform, can be used within Optimizely CMS to...

Anil Patel | Apr 18, 2024 | Syndicated blog

Fix your Search & Navigation (Find) indexing job, please

Once upon a time, a colleague asked me to look into a customer database with weird spikes in database log usage. (You might start to wonder why I a...

Quan Mai | Apr 17, 2024 | Syndicated blog