Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Headless/AJAX Forms

Umbraco Forms provides an API for client-side rendering and submission of forms. This will be useful when you want to handle forms in a headless style scenario.

Enabling the API

The Forms API is disabled by default. To enable it, set the Umbraco:Forms:Options:EnableFormsApi configuration key to true.

For example:

  "Umbraco": {
    "Forms": {
      "Options": {
        "EnableFormsApi": true
      }
    }
  }

API Definition

The API supports two endpoints, one for rendering a form and one for submitting it.

get
Path parameters
idstring · uuidRequired

The form's Id.

Query parameters
contentIdstringOptional

The Id of the content page on which the form is hosted.

culturestringOptional

The culture code for the form's localization context.

Responses
200

Success

application/json
idstring · uuidOptional
namestringOptional
indicatorstringOptional
cssClassstring · nullableOptional
nextLabelstring · nullableOptional
previousLabelstring · nullableOptional
submitLabelstring · nullableOptional
disableDefaultStylesheetbooleanOptional
fieldIndicationTypeinteger · enumOptionalPossible values:
hideFieldValidationbooleanOptional
messageOnSubmitstring · nullableOptional
messageOnSubmitIsHtmlbooleanOptional
showValidationSummarybooleanOptional
gotoPageOnSubmitstring · uuid · nullableOptional
get/umbraco/forms/delivery/api/v1/definitions/{id}
post
Path parameters
idstring · uuidRequired

The form's Id.

Body
contentIdstring · nullableOptional
culturestring · nullableOptional
Responses
202

Accepted

No content
post/umbraco/forms/delivery/api/v1/entries/{id}
No content

As well as this documentation, the definition of the API can also be reviewed via the Swagger UI.

This is available alongside the Umbraco 12 Content Delivery Api at: /umbraco/swagger/index.html. Select "Umbraco Forms API" from the "Select a definition" list to view the methods available.

Swagger UI

The Open API specification is available from: /umbraco/swagger/forms/swagger.json

Requesting a Form Definition

To request the definition of a form, the following request can be made:

The GET request requires the Guid identifying the form.

An optional contentId parameter can be provided, which can either be the integer or GUID identifier for the current page. If provided, the content item identified will be used for Forms features requiring information from the page the form is hosted on. This includes the parsing of "magic string" placeholders.

A culture parameter can also be provided, expected as an ISO code identifying a language used in the Umbraco installation (for example, en-US). This will be used to ensure the correct translation for dictionary keys is used. It will also retrieve page content from the appropriate language variant. If the parameter is not provided in the request, the default Umbraco language will be used.

Finally, an additionalData parameter can be provided as a dictionary. This information will be made available when rendering the form allowing it to be used as a source for "magic string" replacements.

If the requested form is not found, a 404 status code will be returned.

A successful request will return a 200 status code. An example response is as follows. It will differ depending on the pages, fields and other settings available for the form.

It's possible to define either a message displayed when a form is submitted, or a redirect to another website page.

With the former, the output will be as above, and as shown in this extract:

When a redirect is configured, details of the content ID and a route will be included, as follows:

Submitting a Form Entry

To submit a form entry, the following request can be made:

The POST request requires the Guid identifying the form.

It also requires a Content-Type header of application/json and accepts a body as per this example:

The values collection consists of a set of name/value pairs, where the name is the alias of a form field. The value is the value of the submitted field, which can either be a string, or an array of strings. In this way we support fields that accept multiple values, such as checkbox lists.

The contentId and culture parameters are optional. If provided they will be used to customize the response for the current page and language respectively.

Similarly the additionalData dictionary is optional. This data is associated with the created record and made available within workflows.

In the case of a validation error, a 422 "Unprocessable Entity" status code will be returned, along with a response similar to the following:

A successful response will return a 202 "Accepted" status code.

It will contain an object detailing the post-submission configured the form, for example:

File Uploads

The file upload field type is supported via the API for the rendering and submission of forms.

When retrieving a form definition, some additional detail is provided for fields of this type to allow for the appropriate rendering of the form interface:

When submitting a form, the value should be a JSON structure that provides a collection. Each item in the collection should contain the file name and the file contents as a base64 encoded data URL.

Securing the API

Antiforgery Protection

When posting forms in the traditional way, via a full page post back, an anti-forgery token is generated and validated. This provides protection against Cross-Site Request Forgery (CSRF) attacks.

The same protection is available for forms submitted via AJAX techniques.

In order to generate the token and provide it in the form post, the following code can be applied to the .cshtml template:

When posting the form, the header value generated can be provided, where it will be validated server-side before accepting the request.

API Key

The antiforgery token security approach is valid when building a client-side integration with API calls made from the browser.

Providing the token isn't possible though in other headless situations such as server-to-server requests. In these situations, an alternative approach to securing the API is available.

Firstly, with server-to-server integrations you will want to disable the antiforgery token protection.

This is done by setting the Umbraco:Forms:Security:EnableAntiForgeryTokenForFormsApi configuration key to a value of false.

You should then configure an API key Umbraco:Forms:Security:FormsApiKey. This can be any string value, but it should be complex enough to resist being guessed by a brute force attack.

With this in place any request to the Forms API will be rejected unless the configured value is provided in an HTTP header named Api-Key.

Rendering and Submitting forms with JavaScript

For an illustrative example showing how a form can be rendered, validated and submitted using the API and vanilla JavaScript, see this gist.

Examples demonstrating how to handle a file upload and use reCAPTCHA fields are included.

Working with the CMS Content Delivery API

The Content Delivery API provides headless capabilities within Umbraco by allowing you to retrieve content in JSON format.

When retrieving content that contains an Umbraco Forms form picker, the output by default will consist of the ID of the selected form:

With expanded output for the property, the full details of the form will be available. The structure and content of the form representation will be exactly the same as that provided by the Forms API itself.

Dynamic Form injection

For dynamic Form injection on a page, such as in a modal dialog, there's a specific JavaScript event and API method. This allows reinitializing Umbraco Forms for the new content.

PreviousLocalizationNextBlock List Labels

Last updated

Was this helpful?