Replace a user profile

Replaces the values in a plural attribute
Open Recipe

Replaces all the attribute values in a user profile with a new set of values. By default, any attributes not included in your API call are replaced with null values. All plural values are also set to null values, and any new plural elements included in the API call are assigned new IDs. Effectively, you're deleting all the existing information in a user profile (except for attributes, such as uuid, that can't be changed) and replacing the deleted information with a brand-new set of user profile data.

That said, however, by using the attribute_name parameter it is possible to use this endpoint to change a single attribute; this is often done to replace all the values in a plural attribute. In Example 3 (shown below), all the values in the statuses plural are removed (i.e., the current values are deleted and are replaced by an empty string). However, because the attribute_name parameter was used only the specified attribute (statuses) is affected. That means that, in this case, none of the other attributes in the user profile (displayName, givenName, familyName, etc.) are changed.

If you want to replace only a handful of attributes (for example, a user's displayName and phone), you might want to use the /entity.update endpoint instead. With /entity.update, attributes not included in your API call are simply ignored and are not replaced with null values.

Refer to the Registration error codes page for details on error codes.

API client permissions

The following table indicates the API clients that can and can't be used to call this operation:

owneraccess_issuerdirect_accessdirect_access_readlogin_client

Authentication

This operation supports Basic authentication (recommended) as well as janrain-oauth and janrain-signed authentication. See Get started for more information.

Base URL

The base URL for this operation is your Identity Cloud Capture domain; for example:

https://educationcenter.us-dev.janraincapture.com

Your Capture domain (also known as a Registration domain) can be found in Console on the Manage Application page.

Examples

Example 1: Replace an entity by UUID

This command replaces all the user profile attributes for the user with the uuid 6bbe7e58-bede-41b8-940b-5614c7607a4e with the new values specified in the attributes parameter. Note that, in this simple example, that means that the user profile will only contain two attribute values. All other attribtes will be set to a null value.

curl -X POST \
  -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
  --data-urlencode type_name=user \
  --data-urlencode uuid=6bbe7e58-bede-41b8-940b-5614c7607a4e \
  --data-urlencode attributes='{"givenName":"Bob","familyName":"Smith"}' \
  https://my-app.janraincapture.com/entity.replace

Example response

If your API call succeeds the response consists of the word ok:

{
  "stat": "ok"
}

Example 2: Locate a user account by email address

This command uses the key_attribute and key_value parameters to locate the user profile for the user with the email address parker@example.com; the API call then replaces all the attribute values in that user profiles with the values listed in the attributes parameter. That means that, in this simple example, the user profile will only contain two attribute values: givenName and familyName.

curl -X POST \
  -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
  --data-urlencode type_name=user \
  --data-urlencode key_attribute=email \
  --data-urlencode key_value='"parkerm@example.com"' \
  --data-urlencode attributes='{"givenName":"Mathew","familyName":"Parkerson",
  "email":"parkerm@example.com"}' \
  https://my-app.janraincapture.com/entity.replace

Example response

If your API call succeeds the response consists of the word ok:

{
  "stat": "ok"
}

Example 3: Replace a plural attribute only

This command uses the attribute_name parameter to limit updates to the statuses plural; no other attribute values are changed (or deleted) by this API call. In this example, the value of the statuses plural is set to an empty array ([]).

curl -X POST \
  -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
  --data-urlencode type_name=user \
  --data-urlencode uuid=678a31ef-c05d-4cd0-a3e5-70d3de33e3fb \
  --data-urlencode attribute_name="statuses" \
  --data-urlencode attributes=[] \
  https://my-app.janraincapture.com/entity.replace

Example response

If your API call succeeds the response consists of the status ok:

{
  "stat": "ok"
}

Parameters

All parameters need to be configured as x-www-form-urlencoded body parameters.

ParameterTypeRequiredDescription
idstringUnique identifier of the user record. Required unless you are using the uuid or key_attribute parameter.
uuidstringUnique identifier of the user record. Required unless you are using the id or key_attribute parameter.
key_attributestringName of a unique attribute in the schema that can identify the user account. This parameter is required unless you are using the uuid or id parameter.
key_valuestringValue assigned to the key_attribute parameter. For example, if key_attribute is set to email then key_value needs to be set to the email address of the user.

Note that string values need to be enclosed in double quotes.
type_namestringName of the entity type containing the user profile.
valueJSON stringValue assigned to the attribute_name parameter. If attribute_name references just one attribute you only need to supply a value. For example, Fred.

If attribute_name references multiple values then use JSON to specify each attribute value. For example, to assign values to the givenName and the familyName attributes use the syntax {"givenName":"Bob","familyName":"Smith"}.

For backward compatibility, this attribute can also be referred to as the attributes parameter.
attribute_namestringName or path of the attribute you're updating.
createddateTimeTimestamp generated when the entity was created. This value needs to match the value of the user's created attribute. If it doesn't the call fails.
lastUpdateddateTimeTimestamp generated when the entity was last updated. This value needs to match the value of the user's lastUpdated attribute. If it doesn't the call fails.
include_recordbooleanWhen true, the newly-updated user record is returned as part of the API response. Note that, if attribute_name is pointed to root, the entire record is returned. If it points to a subset of the record, only that data is returned.