Umbraco Forms

BASE URL: https://api.umbraco.io

API version: 2.1

The availability of Umbraco Forms depend on the plan. See the Pricing & Features for an overview of which plans includes Forms.

Table of Contents

• Common Headers

• Authentication

• Errors

• Fields types

• Get forms

• Get by id

• Submit entry

Common Headers

Api-Version: 2.1
Umb-Project-Alias: {project-alias}

Authentication

Auth is required for this API meaning that you must supply a Bearer Token via an Authorization header or an API Key via an Authorization or Api-Key header.

Errors

If an error occurs you will receive a HTTP status code along with an API error code and an error message in the response body.

Status Code	Error Code	Message
400	BadRequest	Body cannot be empty.
401	Unauthorized	Authorization has been denied for this request.
403	Forbidden	You are not authorized to access the given resource.
404	NotFound	Form with id '{id}' could not be found.
422	ValidationFailed	Validation error.
500	InternalServerError	Internal server error.

JSON example:

{
  "error": {
    "code": "Unauthorized",
    "message": "Authorization has been denied for this request."
  }
}

Field types

The field types gets mapped to a more machine friendly name

Name	Alias	Value
Checkbox	checkbox	string("on") / boolean
Date	date	date (ISO8601)
Data Consent	dataConsent	string("on") / boolean
Dropdown	dropdown	string
Hidden	hidden	string
Long Answer	textarea	string
Multiple Choice	checkboxList	string
Password	password	string
Recaptcha2	recaptcha2	string(reCaptcha response)
Short Answer	text	string
Single Choice	radio	string
Title And Description	titleAndDescription	readonly

Get forms

Gets all forms.

URL: /forms

Method: GET

Permissions required : Access to Forms section of the Umbraco Backoffice

Success Response

Code: 200

Content Example:

{
  "_links": {
    "self": {
      "href": "/api/forms"
    },
    "forms": {
      "href": "/api/forms/2edaf583-cf66-4d57-930c-f0772c3d1c52"
    }
  },
  "_embedded": {
    "forms": [
      {
        "_id": "2edaf583-cf66-4d57-930c-f0772c3d1c52",
        "indicator": "*",
        "name": "Contact",
        "nextLabel": "Next",
        "previousLabel": "Previous",
        "submitLabel": "Submit",
        "disableDefaultStylesheet": false,
        "fieldIndicationType": "MARK_MANDATORY_FIELDS",
        "hideFieldValidation": false,
        "messageOnSubmit": "Thank you",
        "showValidationSummary": false,
        "pages": [
          {
            "fieldsets": [
              {
                "columns": [
                  {
                    "width": 12,
                    "fields": [
                      {
                        "caption": "Name",
                        "alias": "name",
                        "required": true,
                        "requiredErrorMessage": "Please provide a value for Name",
                        "settings": {
                          "placeholder": "John Smith",
                          "defaultValue": ""
                        },
                        "type": "text"
                      },
                      {
                        "caption": "Email",
                        "alias": "email",
                        "required": true,
                        "requiredErrorMessage": "Please provide a value for Email",
                        "settings": {
                          "placeholder": "[e-mail]",
                          "defaultValue": "",
                          "pattern": "[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+",
                          "patternInvalidErrorMessage": "Please enter a valid email address"
                        },
                        "type": "text"
                      },
                      {
                        "caption": "Message",
                        "alias": "message",
                        "required": false,
                        "requiredErrorMessage": "Please provide a value for Message",
                        "settings": {
                          "defaultValue": "",
                          "placeholder": ""
                        },
                        "type": "textarea"
                      },
                      {
                        "caption": "Consent for storing submitted data",
                        "alias": "dataConsent",
                        "required": true,
                        "requiredErrorMessage": "Consent is required to store and process the data in this form.",
                        "settings": {
                          "acceptCopy": "Yes, I give permission to store and process my data"
                        },
                        "type": "dataConsent"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ],
        "_links": {
          "self": {
            "href": "/api/forms/2edaf583-cf66-4d57-930c-f0772c3d1c52"
          }
        }
      }
    ]
  }
}

Get by ID

Get a specific form by its ID.

URL: /forms/{id}

Method: GET

Permissions required : Access to Forms section of the Umbraco Backoffice

Success Response

Code: 200

Content Example:

{
  "_id": "2edaf583-cf66-4d57-930c-f0772c3d1c52",
  "indicator": "*",
  "name": "Contact",
  "nextLabel": "Next",
  "previousLabel": "Previous",
  "submitLabel": "Submit",
  "disableDefaultStylesheet": false,
  "fieldIndicationType": "MARK_MANDATORY_FIELDS",
  "hideFieldValidation": false,
  "messageOnSubmit": "Thank you",
  "showValidationSummary": false,
  "pages": [
    {
      "fieldsets": [
        {
          "columns": [
            {
              "width": 12,
              "fields": [
                {
                  "caption": "Name",
                  "alias": "name",
                  "required": true,
                  "requiredErrorMessage": "Please provide a value for Name",
                  "settings": {
                    "placeholder": "John Smith",
                    "defaultValue": ""
                  },
                  "type": "text"
                },
                {
                  "caption": "Email",
                  "alias": "email",
                  "required": true,
                  "requiredErrorMessage": "Please provide a value for Email",
                  "settings": {
                    "placeholder": "[e-mail]",
                    "defaultValue": "",
                    "pattern": "[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+",
                    "patternInvalidErrorMessage": "Please enter a valid email address"
                  },
                  "type": "text"
                },
                {
                  "caption": "Message",
                  "alias": "message",
                  "required": false,
                  "requiredErrorMessage": "Please provide a value for Message",
                  "settings": {
                    "defaultValue": "",
                    "placeholder": ""
                  },
                  "type": "textarea"
                },
                {
                  "caption": "Consent for storing submitted data",
                  "alias": "dataConsent",
                  "required": true,
                  "requiredErrorMessage": "Consent is required to store and process the data in this form.",
                  "settings": {
                    "acceptCopy": "Yes, I give permission to store and process my data"
                  },
                  "type": "dataConsent"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "_links": {
    "self": {
      "href": "/api/forms/2edaf583-cf66-4d57-930c-f0772c3d1c52"
    }
  }
}

Submit entry

Submit form entries for a specific Form - this is what you would use when a form is submitted from your presentation layer.

URL: /forms/{id}/entries

Method: POST

Permissions required : Access to Forms section of the Umbraco Backoffice

Request

The JSON property names are the form field alias

{
  "name": "Jonh Smith",
  "email": "[e-mail]",
  "dataConsent": "on"
}

Success Response

Code: 202