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 (testObject) to the user entity type. The new plural contains two child attributes, testPluralOne and testPluralTwo,. Both of these are 256 character string attributes.

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 value

API reference: /entity.delete

Deletes a plural value from the user profile with the UUID 30dd1406-f59a-4145-a6de-b94b5e8cacf3. In this example, the value 30721 is removed from the plural janrain.properties.managedBy.

Be careful when using a command similar to this one. If you don’t get the attribute_name value exactly right, the operation ignores the plural and deletes the entire user profile instead.

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