Title: wp_create_user_request
Published: October 5, 2018
Last modified: May 20, 2026

---

# wp_create_user_request( string $email_address = '', string $action_name = '', array $request_data = array(), string $status = 'pending' ): int|󠀁[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)󠁿

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#wp--skip-link--target)

Creates and logs a user request to perform a specific action.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#description)󠁿

Requests are stored inside a post type named `user_request` since they can apply
to both users on the site, or guests without a user account.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#parameters)󠁿

 `$email_address`stringoptional

User email address. This can be the address of a registered or non-registered user.

Default:`''`

`$action_name`stringoptional

Name of the action that is being confirmed. Required.

Default:`''`

`$request_data`arrayoptional

Misc data you want to send with the verification request and pass to the actions
once the request is confirmed.

Default:`array()`

`$status`stringoptional

Optional request status (pending or confirmed). Default `'pending'`.

Default:`'pending'`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#return)󠁿

 int|[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/) Returns
the request ID if successful, or a [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
object on failure.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#source)󠁿

    ```php
    function wp_create_user_request( $email_address = '', $action_name = '', $request_data = array(), $status = 'pending' ) {
    	$email_address = sanitize_email( $email_address );
    	$action_name   = sanitize_key( $action_name );

    	if ( ! is_email( $email_address ) ) {
    		return new WP_Error( 'invalid_email', __( 'Invalid email address.' ) );
    	}

    	if ( ! in_array( $action_name, _wp_privacy_action_request_types(), true ) ) {
    		return new WP_Error( 'invalid_action', __( 'Invalid action name.' ) );
    	}

    	if ( ! in_array( $status, array( 'pending', 'confirmed' ), true ) ) {
    		return new WP_Error( 'invalid_status', __( 'Invalid request status.' ) );
    	}

    	$user    = get_user_by( 'email', $email_address );
    	$user_id = $user && ! is_wp_error( $user ) ? $user->ID : 0;

    	// Check for duplicates.
    	$requests_query = new WP_Query(
    		array(
    			'post_type'     => 'user_request',
    			'post_name__in' => array( $action_name ), // Action name stored in post_name column.
    			'title'         => $email_address,        // Email address stored in post_title column.
    			'post_status'   => array(
    				'request-pending',
    				'request-confirmed',
    			),
    			'fields'        => 'ids',
    		)
    	);

    	if ( $requests_query->found_posts ) {
    		return new WP_Error( 'duplicate_request', __( 'An incomplete personal data request for this email address already exists.' ) );
    	}

    	$request_id = wp_insert_post(
    		array(
    			'post_author'   => $user_id,
    			'post_name'     => $action_name,
    			'post_title'    => $email_address,
    			'post_content'  => wp_json_encode( $request_data ),
    			'post_status'   => 'request-' . $status,
    			'post_type'     => 'user_request',
    			'post_date'     => current_time( 'mysql', false ),
    			'post_date_gmt' => current_time( 'mysql', true ),
    		),
    		true
    	);

    	return $request_id;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/user.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.0/src/wp-includes/user.php#L4775)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.0/src/wp-includes/user.php#L4775-L4827)

## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#related)󠁿

| Uses | Description | 
| [_wp_privacy_action_request_types()](https://developer.wordpress.org/reference/functions/_wp_privacy_action_request_types/)`wp-includes/user.php` |

Gets all personal data request types.

  | 
| [sanitize_email()](https://developer.wordpress.org/reference/functions/sanitize_email/)`wp-includes/formatting.php` |

Strips out all characters that are not allowable in an email.

  | 
| [is_email()](https://developer.wordpress.org/reference/functions/is_email/)`wp-includes/formatting.php` |

Verifies that an email is valid.

  | 
| [get_user_by()](https://developer.wordpress.org/reference/functions/get_user_by/)`wp-includes/pluggable.php` |

Retrieves user info by a given field.

  | 
| [WP_Query::__construct()](https://developer.wordpress.org/reference/classes/wp_query/__construct/)`wp-includes/class-wp-query.php` |

Constructor.

  | 
| [current_time()](https://developer.wordpress.org/reference/functions/current_time/)`wp-includes/functions.php` |

Retrieves the current time based on specified type.

  | 
| [wp_insert_post()](https://developer.wordpress.org/reference/functions/wp_insert_post/)`wp-includes/post.php` |

Inserts or updates a post in the database.

  | 
| [wp_json_encode()](https://developer.wordpress.org/reference/functions/wp_json_encode/)`wp-includes/functions.php` |

Encodes a variable into JSON, with some confidence checks.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [sanitize_key()](https://developer.wordpress.org/reference/functions/sanitize_key/)`wp-includes/formatting.php` |

Sanitizes a string key.

  | 
| [is_wp_error()](https://developer.wordpress.org/reference/functions/is_wp_error/)`wp-includes/load.php` |

Checks whether the given variable is a WordPress Error.

  | 
| [WP_Error::__construct()](https://developer.wordpress.org/reference/classes/wp_error/__construct/)`wp-includes/class-wp-error.php` |

Initializes the error.

  |

[Show 7 more](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#)

| Used by | Description | 
| [_wp_personal_data_handle_actions()](https://developer.wordpress.org/reference/functions/_wp_personal_data_handle_actions/)`wp-admin/includes/privacy-tools.php` |

Handle list table actions.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_create_user_request/?output_format=md#changelog)󠁿

| Version | Description | 
| [5.7.0](https://developer.wordpress.org/reference/since/5.7.0/) | Added the `$status` parameter. | 
| [4.9.6](https://developer.wordpress.org/reference/since/4.9.6/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_create_user_request%2F)
before being able to contribute a note or feedback.