Controller Actions

The following controller actions (opens new window) are available for front end forms:

Action Description
POST entries/save-entry Saves an entry.
POST users/login Logs a user in.
POST users/save-user Saves a user account.
POST users/send-password-reset-email Sends a password reset email.
POST users/set-password Sets a new password on a user account.

To invoke a controller action, send a POST request to Craft, with an action param set to the desired action path, either in the request body or query string.

# POST entries/save-entry

Saves an entry.

This can be used to save a new or existing entry, determined by the sourceId param.

See the Entry Form (opens new window) guide for an example of working with this action.

Note that all custom fields can updated by users. For this reason, you should not assume that custom fields are protected from modification simply because they are not included in the form.

# Supported Params

The following params can be sent with the request:

Param Description
author The ID of the user account that should be set as the entry author. (Defaults to the entry’s current author, or the logged-in user.)
enabledForSite Whether the entry should be enabled for the current site (1/0), or an array of site IDs that the entry should be enabled for. (Defaults to the enabled param.)
enabled Whether the entry should be enabled (1/0). (Defaults to enabled.)
entryId Fallback if sourceId isn’t passed, for backwards compatibility.
entryVariable The hashed name of the variable that should reference the entry, if a validation error occurs. (Defaults to entry.)
expiryDate The expiry date for the entry. (Defaults to the current expiry date, or null.)
failMessage The hashed flash notice that should be displayed, if the entry is not saved successfully. (Only used for text/html requests.)
fieldsLocation The name of the param that holds any custom field values. (Defaults to fields.)
fields[] An array of new custom field values, indexed by field handles. (The param name can be customized via fieldsLocation.) Only fields that are included in this array will be updated.
parentId The ID of the parent entry, if it belongs to a structure section.
postDate The post date for the entry. (Defaults to the current post date, or the current time.)
redirect The hashed URL to redirect the browser to, if the entry is saved successfully. (The requested URI will be used by default.)
revisionNotes Notes that should be stored on the new entry revision.
siteId The ID of the site to save the entry in.
slug The entry slug. (Defaults to the current slug, or an auto-generated slug.)
sourceId The ID of the entry to save, if updating an existing entry.
successMessage The hashed flash notice that should be displayed, if the entry is saved successfully. (Only used for text/html requests.)
title The entry title. (Defaults to the current entry title.)
typeId The entry type ID to save the entry as. (Defaults to the current entry type.)

# Output

The action’s output depends on whether the entry saved successfully and the request included an Accept: application/json header.

# Standard Request

Success Output
302 redirect response per the hashed redirect param.
None; the request will be routed per the URI. An entry variable will be passed to the resulting template. The template can access validation errors via getErrors() (opens new window), getFirstError() (opens new window), etc.

# With JSON Request Header

Success Output
200 JSON response with id, title, slug, authorUsername, dateCreated, dateUpdated, and postDate keys.
200 JSON response with an errors key set to the result of getErrors() (opens new window).

# POST users/login

Logs a user in.

See the Front-End User Accounts (opens new window) guide for an example of working with this action.

# Supported Params

The following params can be sent with the request:

Param Description
failMessage The hashed flash notice that should be displayed, if the user is not logged in successfully. (Only used for text/html requests.)
loginName The username or email of the user to login.
password The user’s password.
rememberMe Whether to keep the user logged-in for an extended period of time per the rememberedUserSessionDuration config setting (1/0).

# Output

The output of the action depends on whether the login was successful and the request included an Accept: application/json header.

# Standard Request

Success Output
302 redirect response per the hashed redirect param, or the user session’s return URL.
None; the request will be routed per the URI. loginName, rememberMe, errorCode, and errorMessage variables will be passed to the resulting template.

# With JSON Request Header

Success Output
200 JSON response with success and returnUrl keys.
200 JSON response with errorCode and error keys.

# POST users/save-user

Saves a user account.

This can be used to register a new user or update an existing one, determined by the userId param.

See the Front-End User Accounts (opens new window) guide for an example of working with this action.

Note that all custom fields can updated by users. For this reason, you should not assume that custom fields are protected from modification simply because they are not included in the form.

# Supported Params

The following params can be sent with the request:

Param Description
admin Whether the user should be saved as an admin (1/0). Only checked if the logged-in user is an admin.
currentPassword The user’s current password, which is required if email or newPassword are sent.
email The user’s email address. (Only checked if registering a new user, updating the logged-in user, or the logged-in user is allowed to administrate users.)
failMessage The hashed flash notice that should be displayed, if the user account is not saved successfully. (Only used for text/html requests.)
fieldsLocation The name of the param that holds any custom field values. (Defaults to fields.)
fields[] An array of new custom field values, indexed by field handles. (The param name can be customized via fieldsLocation.) Only fields that are included in this array will be updated.
firstName The user’s first name.
lastName The user’s last name.
newPassword The user’s new password, if updating the logged-in user’s account. (If registering a new user, send password.)
passwordResetRequired Whether the user must reset their password before logging in again (1/0). Only checked if the logged-in user is an admin.
password The user’s password, if registering a new user. (If updating an existing user, send newPassword.)
photo An uploaded user photo.
redirect The hashed URL to redirect the browser to, if the user account is saved successfully. (The requested URI will typically be used by default.)
sendVerificationEmail Whether a verification email should be sent before accepting the new email (1/0). (Only checked if email verification is enabled, and the logged-in user is allowed to opt out of sending it.)
successMessage The hashed flash notice that should be displayed, if the user account is saved successfully. (Only used for text/html requests.)
userId The ID of the user to save, if updating an existing user.
userVariable The hashed name of the variable that should reference the user, if a validation error occurs. (Defaults to user.)
username The user’s username. (Only checked if the useEmailAsUsername config setting is disabled.)

# Output

The output depends on whether the user save action was successful and the request included an Accept: application/json header.

# Standard Request

Success Output
302 redirect response per the hashed redirect param, or the activateAccountSuccessPath config setting if email verification is not required.
None; the request will be routed per the URI. A user variable will be passed to the resulting template. The template can access validation errors via getErrors() (opens new window), getFirstError() (opens new window), etc.

# With JSON Request Header

Success Output
200 JSON response with success and id keys.
200 JSON response with an errors key.

# POST users/send-password-reset-email

Sends a password reset email.

See the Front-End User Accounts (opens new window) guide for an example of working with this action.

# Supported Params

The following params can be sent with the request:

Param Description
loginName The username or email of the user to send a password reset email for.
successMessage The hashed flash notice that should be displayed, if the email is sent successfully. (Only used for text/html requests.)
userId The ID of the user to send a password reset email for. (Only checked if the logged-in user has permission to edit other users.)

# Output

The output of the action depends on whether the reset password email was sent successfully, and whether the request included an Accept: application/json header.

# Standard Request

Success Output
302 redirect response per the hashed redirect param.
None; the request will be routed per the URI. errors and loginName variables will be passed to the resulting template.

# With JSON Request Header

Success Output
200 JSON response with a success key.
200 JSON response with an error key.

# POST users/set-password

Sets a new password on a user account.

If the user is pending, their account will be activated as well.

# Supported Params

The following params can be sent with the request:

Param Description
code The user’s verification code.
failMessage The hashed flash notice that should be displayed, if the password is not set successfully. (Only used for text/html requests.)
id The user’s UUID.
newPassword The user’s new password.

# Output

The output of the action depends on whether the password was updated successfully and the request included an Accept: application/json header.

# Standard Request

Success Output
302 redirect response depending on the autoLoginAfterAccountActivation and setPasswordSuccessPath config settings, and whether the user has access to the control panel.
None; the request will be routed per the URI. errors , code, id, and newUser variables will be passed to the resulting template.

# With JSON Request Header

Success Output
200 JSON response with success and (possibly) csrfTokenValue keys.
200 JSON response with an error key.