Replace a User Profile

Endpoint URL: {registrationDomain} /entity.replace



Description

Replaces all the attribute values in a user profile with a new set of attribute 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 that 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 section for details on error codes.


Respects the API Client Allow List:  Yes


API Client Permissions

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

owner
access_issuer
direct_access
direct_read_access
login_client
Yes
No
Yes
No
No


Authentication

This endpoint supports Basic authentication (recommended) as well as janrain-oauth and janrain-signed authentication. See the article Managing User Profiles by Using janrain-oauth Authentication for more information on how to use janrain-oauth in your API calls.

How to Create an Authentication String


Base URL

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

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

Your Capture domains (also known as Registration domains) can be found in the Console on the Manage Application page:

Examples

Example 1: Replacing 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 set of attributes and attribute values specified in the attributes parameter. Note that, in this simple example, that means that the user profile will only contain those two attribute values.


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
          

      Running this command in Postman


Example Response


{
  "stat": "ok"
}        
                                                    


Example 2: Replacing an entity by email

This command uses the key_attribute and key_value parameters to locate the user profile for the user with the email address gjack@test.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 gjack@test.com 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
          

      Running this command in Postman


Example Response


{
  "stat": "ok"
}        
                                                    


Example 3: Replacing a plural attribute only

This command uses the attribute_name parameter to limit updates to the statuses plural; no other attribute values will be 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
       

      Running this command in Postman


Example Response


{
  "stat": "ok"
}        
                                                    


Example 4: Using an access token to replace a user profile

The following command replaces the user profile of the user assigned the access token zkvc58xyvu254q4y. This command uses janrain-oauth authentication; see this page for more information.

curl -L -X POST \
  'https://se-demos-gstemp.us-dev.janraincapture.com/entity.replace?access_token=zkvc58xyvu254q4y' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'attributes={"givenName":"Matt","familyName":"Parker, Jr.",
    "email": "matt.parker.jr@example.com"}'


Example Response


{
  "stat": "ok"
}        
                                                    


Query Parameters

ParameterTypeRequiredDescription
idstringNoID of the user record. Required unless you are using the uuid or key_attribute parameter.
 
uuidstringNoUUID of the user record. Required unless you are using the id or key_attribute parameter.
 
key_attributestringNoName of a unique attribute in the schema. This parameter is required unless you are using the uuid or id parameter, and must be used in conjunction with the key_value parameter.
 
key_valuestringNoValue assigned to the key_attribute parameter.
 
type_namestringYesName of the entity type.
 
valuestringYesJSON-formatted value assigned to the attribute_name parameter. For backward compatibility, this attribute can also be referred to as the attributes parameter.
 
attribute_namestringYesPath of the attribute to be updated. This value path contains ids for each plural element. The default is the root path, which results in the entire plural being updated.
 
createdstringNoTimestamp generated when the entity was created. If this parameter is present but the value is incorrect, the command will fail.
 
lastUpdatedstringNoTimestamp generated when the entity was last updated. If this parameter is present but te value is incorrect, the command will fail.
 
include_recordstringNoWhen set to true, the newly-updated user record is returned as part of the API response. Note that, if the attribute_name is pointed to root, the entire record is returned. If it points to a subset of the record, only that data will be returned.