Links

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

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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"dataConsent": "on"
}

Success Response

Code: 202