/entity.replace

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.

This endpoint includes the following methods:

  • POST

POST

Authentication

This endpoint supports Basic authentication (recommended) as well as janrain-oauth and janrain-signed authentication.

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:

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 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: Replace 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: Replace 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"
}        
                                                    

Authorized Clients

  • owner 
  • direct_access

Query Parameters

ParameterTypeRequiredDescription
idstring
ID of the user record. Required unless you are using the uuid or key_attribute parameter.
 
uuidstring
UUID of the user record. Required unless you are using the id or key_attribute parameter.
 
key_attributestring
Name 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_valuestring
Value 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.
 
createdstring
Timestamp generated when the entity was created. If this parameter is present but te value is incorrect, the command will fail.
 
lastUpdatedstring
Timestamp generated when the entity was last updated. If this parameter is present but te value is incorrect, the command will fail.
 
include_recordstring
When 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.