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.
The Forms API is disabled by default. To enable it, set the Umbraco:Forms:Options:EnableFormsApi configuration key to true.
For example:
The API supports two endpoints, one for rendering a form and one for submitting it.
As well as this documentation, the definition of the API can also be reviewed via the Swagger UI, available at the following path: /umbraco/forms/api/swagger/index.html.
The Open API specification is available from: /umbraco/forms/api/openapi.json
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.
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.
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.
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.
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.
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. The string value can be anything, but it should not be susceptible to 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.
For an illustrative example showing how a form can be rendered, validated and submitted using the API and vanilla JavaScript, please see this gist.
Examples demonstrating how to handle a file upload and use reCAPTCHA fields are included.
Gets or sets the form entry's values.
Gets or sets an optional ID of the content page through which the form was submitted.
Gets or sets an optional culture code for which the form submission should be processed.
Gets or sets the form's ID.
Gets or sets the form's name.
Gets or sets the form's indicator for mandatory fields.
Gets or sets the form's CSS class.
Gets or sets the form's label for the next page button.
Gets or sets the form's label for the previous page button.
Gets or sets the form's button submit label.
Gets or sets a value indicating whether to disable the form's default stylesheet.
Gets or sets the form's field mandatory or optional field indication type.
Enumeration for field indications.
Gets or sets a value indicating whether to hide field validation.
Gets or sets the form's message to display on submission.
Gets or sets a value indicating whether the form's message to display on submission is in HTML format.
Gets or sets a value indicating whether to show the form's validation summary.
Gets or sets the form's page to redirect to following submission.
Gets or sets the form's pages.
Gets or sets the form page's caption.
Gets or sets the form page's condition.
Gets or sets the form condition's action type.
Enumeration for field condition display options.
Gets or sets the form condition's logic type.
Enumeration for field condition logic matches.
Gets or sets the form condition's rules.
Gets or sets fhe form condition rules's field.
Gets or sets fhe form condition rules's operator.
Enumeration for field condition rule operators.
Gets or sets fhe form condition rules's value.
Gets or sets the form page's fieldsets.
Gets or sets the form fieldset's ID.
Gets or sets the form fieldset's caption.
Gets or sets the form fieldset's condition.
Gets or sets the form condition's action type.
Enumeration for field condition display options.
Gets or sets the form condition's logic type.
Enumeration for field condition logic matches.
Gets or sets the form condition's rules.
Gets or sets fhe form condition rules's field.
Gets or sets fhe form condition rules's operator.
Enumeration for field condition rule operators.
Gets or sets fhe form condition rules's value.
Gets or sets the form fieldset's columns.
Gets or sets the form fieldset column's caption.
Gets or sets the form fieldset column's width.
Gets or sets the form fieldset column's fields.
Gets or sets the form field's ID.
Gets or sets the form field's catpion.
Gets or sets the form field's help text.
Gets or sets the form field's placeholder.
Gets or sets the form field's CSS class.
Gets or sets the form field's alias.
Gets or sets a value indicating whether the form field is required to be completed.
Gets or sets the form field's message to display if the required field is not completed.
Gets or sets the form field's validation pattern (regular expression).
Gets or sets the form field's message to display if the field does not match the provided pattern.
Gets or sets the form field's condition.
Gets or sets the form condition's action type.
Enumeration for field condition display options.
Gets or sets the form condition's logic type.
Enumeration for field condition logic matches.
Gets or sets the form condition's rules.
Gets or sets fhe form condition rules's field.
Gets or sets fhe form condition rules's operator.
Enumeration for field condition rule operators.
Gets or sets fhe form condition rules's value.
Gets or sets the form field's file upload options.
Gets or sets a value indicating whether all file extensions are allowed.
Gets or sets the allowed file extensions.
Gets or sets a value indicating whether multiple file uploads are allowed.
Gets or sets the form field's prevalues.
Gets or sets the form field prevalue's value.
Gets or sets the form field prevalue's caption.
Gets or sets the form field's settings.
Gets or sets the form field's type.
Gets or sets the form type's ID.
Gets or sets the form type's name.
Gets or sets a value indicating whether the form type's supports prevalues.
Gets or sets a value indicating whether the form type's supports file uploads.
Gets or sets a value indicating how the the field should be rendered, as a single input, multiple inputs within an an HTML fieldset (e.g. a radio button or check box list).