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.

# Supported Params

The following params can be sent with the request:

Param Description
authorId 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 the 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 output of the action depends on whether the entry save was successful, and whether an Accept: application/json header was sent with the request.

Success JSON Output
JSON response with success, id, title, slug, authorUsername, dateCreated, dateUpdated, and postDate keys.
No Redirect response per the hashed redirect param.
No JSON response with an errors key set to the result of getErrors() (opens new window).
No No 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), getError() (opens new window), etc.

# 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 whether an Accept: application/json header was sent with the request.

Success JSON Output
JSON response with success and returnUrl keys.
No Redirect response per the hashed redirect param, or the user session’s return URL.
No JSON response with errorCode and error keys.
No No None; the request will be routed per the URI. loginName, rememberMe, errorCode, and errorMessage variables will be passed to the resulting template.

# 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.

# 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.)
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 of the action depends on whether the user save was successful, and whether an Accept: application/json header was sent with the request.

Success JSON Output
JSON response with success and id keys.
No Redirect response per the hashed redirect param, or the activateAccountSuccessPath config setting if email verification is not required.
No JSON response with an errors key.
No No 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), getError() (opens new window), etc.

# 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 an Accept: application/json header was sent with the request.

Success JSON Output
JSON response with a success key.
No Redirect response per the hashed redirect param.
No JSON response with an error key.
No No None; the request will be routed per the URI. errors and loginName variables will be passed to the resulting template.

# 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 whether an Accept: application/json header was sent with the request.

Success JSON Output
JSON response with success and (possibly) csrfTokenValue keys.
No Redirect response depending on the autoLoginAfterAccountActivation and setPasswordSuccessPath config settings, and whether the user has access to the control panel.
No JSON response with an error key.
No No None; the request will be routed per the URI. errors , code, id, and newUser variables will be passed to the resulting template.