Additional Entity and Entity Type API examples
Create an entity type
API reference: /entityType.create
Creates an entity type named user2. This entity type includes the following attributes:
- consent. A 200 character string value that is a required attribute and that needs to be unique throughout the entity type.
- consentDescription. A 1,000 character string value.
- consentAttributes. A plural value containing a single child attribute (consentName).
curl -X POST \
-H "Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY=" \
--data-urlencode type_name=user2 \
--data-urlencode attr_defs='[{"name":"consent","type":"string","length":200,"description": "The name of the consent in the user entity.","constraints":["unique", "required"]},{"name": "consentDescription","type":"string","length":1000,"description":"A short description of the consent."},{"name":"consentAttributes","type":"plural","description":"Attributes associated with the consent.","attr_defs":[{"name":"consentName","type": "string","length":200,"description":"An attribute name from the user entity.","features":["primary-key"],"constraints":["locally-unique", "required"]}]}]' \
https://my-app.janraincapture.com/entityType.create
The attr_defs member defines the attributes that make up the entity type schema. For the operation itself, the value of attr_defs needs to be formatted single JSON string. When expanded, that string looks like this:
[{
"name": "consent",
"type": "string",
"length": 200,
"description": "The name of the consent in the user entity.",
"constraints": ["unique", "required"]
}, {
"name": "consentDescription",
"type": "string",
"length": 1000,
"description": "A short description of the consent."
}, {
"name": "consentAttributes",
"type": "plural",
"description": "Attributes associated with the consent.",
"attr_defs": [{
"name": "consentName",
"type": "string",
"length": 200,
"description": "An attribute name from the user entity.",
"features": ["primary-key"],
"constraints": ["locally-unique", "required"]
}]
}]
Add an object to an entity type
API reference: /entityType.addAttribute
Adds an object attribute (testObject) to the user entity type. The new object contains two child attributes, testOne and testTwo, which are both 256 character string attributes. If this operation succeeds, testObject is automatically added to every user profile in the user entity type.
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg" \
--data-urlencode type_name=user \
--data-urlencode attr_defs='{"name":"testObject","type":"object","attr_defs":[{"name":"testOne","type":"string","length":256},{"name":"testTwo","type":"string","length": 256}]}' \
https://my-app.janraincapture.com/entityType.addAttribute
When expanded, the JSON value assigned to the attr_defs member looks like this:
{
"name": "testObject",
"type": "object",
"attr_defs": [{
"name": "testOne",
"type": "string",
"length": 256
}, {
"name": "testTwo",
"type": "string",
"length": 256
}]
}
Add a plural attribute to an entity type
API reference: /entityType.addAttribute
Adds a plural attribute (testPlural) to the user entity type. The new plural contains two child attributes, testPluralOne and testPluralTwo. Both of these are 256 character string attributes.
Object and plural attributes can be nested within another object or plural. Attribute nesting is limited to a depth of 5 attributes. For example:
- object1.plural2.object3.plural4.givenName
(This is a depth of 5 attributes and is allowed.)- object1.plural2.object3.plural4.object5.givenName
(This is a depth of 6 attributes and is NOT allowed.)
curl -X POST \
-H "Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY"\
--data-urlencode type_name=user \
--data-urlencode attr_defs='{"name":"testPlural","type":"plural","attr_defs":[{"name":"testPluralOne","type":"string","length":256},{"name":"testPluralTwo","type":"string","length": 256}]}'\
https://my-app.janraincapture.com/entityType.addAttribute
When expanded, the JSON value assigned to the attr_defs member looks like this:
{
"name": "testPlural",
"type": "plural",
"attr_defs": [{
"name": "testPluralOne",
"type": "string",
"length": 256
}, {
"name": "testPluralTwo",
"type": "string",
"length": 256
}]
}
Add a datetime attribute to an entity type
API reference: /entityType.addAttribute
Adds a dateTime attribute (emailPreVerified) to the user entity type.
curl -X POST \
-H "Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY"\
--data-urlencode type_name=user \
--data-urlencodeattr_def='{"name":"emailPreVerified","type":"dateTime"}' \
https://my-app.janraincapture.com/entityType.addAttribute
Return a subset of attributes from a user profile
API reference: /entity
Returns four user profile attribute values (email, givenName, familyName and created) for the user with the id 122463. These four attributes specify the user’s email address, first name, last name, and the date the user account was created.
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg="\
--data-urlencode type_name=user \
--data-urlencode id=122463 \
--data-urlencode attributes='["email", "familyName", "givenName", "created"]' \
https://my-app.janraincapture.com/entity
The returned information will look similar to this;
{
"result": {
"familyName": "Parker",
"email":"parkerm@example.com",
"givenName":"Matthew",
"created":"2015-12-31 18:54:59.900339 +0000"
},
"stat":"ok"
}
Return use profile information for a user with a specified email address
API reference: /entity
Returns the value of the created attribute for the user with the email address parkerm@example.com. To locate a user account by using an email address, set the key_attribute value to email (the name of the attribute that contains the user’s email address) and the key_value attribute to parkerm@example.com (the email address of the user you’re searching for).
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='["created"]'\
https://my-app.janraincapture.com/entity
The API response will look similar to the following:
{
"result":{
"created":"2015-10-05 21:37:13.031989 +0000"
},
"stat":"ok"
}
Verify a user password
API reference: /entity
Verifies the password assigned to the user with the ID 101860. To do this, the call specifies the attribute to be checked (password) and the supplied password value (p@ssw0rd). If the supplied value matches the user’s actual password, the values included in the attributes parameter are returned (in this case, the user’s displayName). If the supplied value does not match the user’s actual password, then a 350 invalid_password_value error is returned.
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
--data-urlencode type_name=user \
--data-urlencode id=101860 \
--data-urlencode password_attribute=password \
--data-urlencode password_value=p@ssw0rd \
--data-urlencode attributes='["displayName"]'\
https://my-app.janraincapture.com/entity
If the password is verified the API response looks similar to this:
{
"result":{
"displayName":"Karim Nafir"
},
"stat":"ok"
}
Find users who have supplied their birthday
API reference: /entity.find
Returns user profile information for all the users who have specified their date of birth in their user profile. In more technical terms, the operation returns data from all the user profiles where the birthday attribute isn’t null.
curl -X POST \
-H "Authorization: c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
--data-urlencode type_name=user \
--data-urlencode filter="birthday is not null" \
https://my-app.janraincapture.com/entity.find
To return information for all the users who haven’t specified their birthday in their user profile, use this operation (note the value of the filter member):
curl -X POST \
-H "Authorization: c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
--data-urlencode type_name=user \
--data-urlencode filter="birthday is null" \
https://my-app.janraincapture.com/entity.find
Return users who live in the US
API reference: /entity.find
Returns information about all the users who have set their primaryAddress.country attribute to US.
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
--data-urlencode type_name=user \
--data-urlencode filter="primaryAddress.country='US'" \
https://my-app.janraincapture.com/entity.find
To find all the users who don’t live in the US, use this command (note the != operator):
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
--data-urlencode type_name=user \
--data-urlencode filter="primaryAddress.country!='US'" \
https://my-app.janraincapture.com/entity.find
Use multiple conditions in a search filter
API reference: /entity.find
Returns information for the all users who work at Akamai (primaryAddress.company='Akamai') and who live in the US (primaryAddress.country='US').
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
--data-urlencode type_name=user \
--data-urlencode filter="primaryAddress.company='Akamai' and primaryAddress.country='US''" \
https://my-app.janraincapture.com/entity.find
To return users who live in the US or who live in Canada, use the or operator instead of the and operator;
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=" \
--data-urlencode type_name=user \
--data-urlencode filter="primaryAddress,country='US' or primaryAddress.country='CA'" \
https://my-app.janraincapture.com/entity.find
Return specified attributes for all users in an entity type
API reference: entity.find
Returns two attributes (displayName and email) for each user profile in the user entity type. If you don’t include the attributes member then, by default, the /entity.find operation returns all the attributes for each user profile.
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg="
--data-urlencode type_name=user \
--data-urlencode attributes='["displayName", "email"]' \
https://my-app.janraincapture.com/entity.find
Update a user account based on email address
API reference: entity.replace
Uses the key_attribute and key_value members to locate the user profile for the user with the email address gjack@example.com. The operation then replaces all the attribute values in that user profile with the values listed in the attributes parameter. In this simple (and somewhat-unrealistic) example, the gjack@example.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='"gjack@example.com"' \
--data-urlencode attributes='{"givenName":"Glen","familyName":"Jackson",
"email":"parkerm@example.com"}' \
https://my-app.janraincapture.com/entity.replace
Replace a plural attribute
API reference: /entity.replace
Updates the statuses plural in a user profile. Note that even though this API call uses the /entity.replace operation no other attribute values are changed or deleted. 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
Update a plural attribute
API reference: /entity.update
Updates the statuses plural (plural ID 5253) for the user with the id 121989. In this example, the status attribute is set to active.
curl -X POST \
-H "Authorization: Basic aW1fYV...NfbXk=" \
--data-urlencode type_name=user \
--data-urlencode id=121989 \
--data-urlencode attribute_name='/statuses#5253' \
--data-urlencode value='{"status":"active"}' \
https://my-app.janraincapture.com/entity.update
Update the user profile of a user with the specified email address
API reference: /entity.update
Uses the key_attribute and key_values members to locate the user profile for the user with the email address gjack@example.com, then changes the displayName for that user profile to Gary Jackson.
curl -X POST \
-H "Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY="\
--data-urlencode type_name=user \
--data-urlencode key_attribute=email \
--data-urlencode key_value='"gjack@example.com"'\
--data-urlencode attribute_name='displayName' \
--data-urlencode value='{"Gary Jackson"}'\
https://my-app.janraincapture.com/entity.update
Delete a plural entry
API reference: /entity.delete
WARNING. Be careful when using a command similar to the following. If you don’t get the attribute_name value exactly right, the operation ignores the plural and deletes the entire user profile instead.
Deletes a plural entry from the user profile with the UUID 30dd1406-f59a-4145-a6de-b94b5e8cacf3. In this example, the entry 30721 is removed from the plural janrain.properties.managedBy.
curl -X POST \
-H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg" \
--data-urlencode type_name=user \
--data-urlencode uuid=30dd1406-f59a-4145-a6de-b94b5e8cacf3 \
--data-urlencode attribute_name="janrain.properties.managedBy#30721" \
https://my-app.janraincapture.com/entity.delete
Updated 11 months ago