Identity Cloud: Entity and EntityType API v2

Manage user accounts and user profiles for Identity Cloud.

Learn more:


Overview

The Entity and EntityType API endpoints are used for managing user accounts and user profiles (entities) as well as the databases that maintain those user profiles (entity types).

An entity is a record in your registration application. You can use the /entity endpoints to view, add, edit, or delete entities from your records. You can also use the /entity endpoints to search for user accounts.

Important: Querying Large Datasets

When using the entity.find endpoint to iterate over large sets of data (> 100,000), queries should be optimized using natural database sorting by sorting on the id attribute. This has two benefits:

  • Records created between when the time iteration begins and when the time iteration ends are included in the results.

  • Efficient and consistent performance querying and loading for each page of results.

The following tips will help you optimize your queries:

  • Use the attributes parameter to limit the number of attributes returned for each record to minimize the size of the HTTP payload.

  • Experiment with the max_results parameter to optimize for responses under 10 seconds.

  • Include the timeout parameter (up to 60 seconds) if, and only if, you are unable to keep responses under 10 seconds using the max_results parameter.

Meanwhile, the /entityType endpoints are used when working with user profile schemas. These endpoints can manipulate record information for a single record or a group of records. The /entityType endpoints also allow you to do such things as:

  • Modify user profile schemas by adding, removing, or modifying attributes (the individual data fields within the schema).

  • Add, remove, or modify data validation rules to schema attributes.

  • Use “access schemas” to manage access to attributes. For example, you might give some your support personnel the right to view specific user attributes (such as name, address, and phone number) while not allowing those personnel to modify or delete those attributes.

Accessing the Entity and EntityType API endpoints

The Entity and EntityType API uses the following syntax for endpoint URLs:

https://{app}.janraincapture.com/{endpoint}

To access you entity and entityType endpoints, replace {app} with the name of your Capture domain, and replace {endpoint} with the appropriate endpoint name. For example:

https://akamai-documentation.us-dev.janraincapture.com/entityType/list

Authentication

All the Entity and EntityType API endpoints can use either Basic authentication or HMAC (Hash Message Authentication Code) authentication. To create a Basic authentication string, combine your API client ID, a colon (:), and your client secret into a single value. For example, if your client ID is abcdefg and your client secret is hijklmnop, that value would look like this:

abcdefg:hijklmnop

Next, take the newly created string and base64 encode it. For example, on a Mac, you can base encode the string using this command:

echo -n "abcdefg:hijklmnop" | base64

Or, if you’re running Microsoft Windows, you can encode the string by using a Windows PowerShell command similar to this:

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("abcdefg:hijklmn"))

The resulting value (e.g., YWJjZGVmZzpoaWprbG1ub3A=) should be used in your authentication header.

If you are making API calls using Postman, select Basic Auth as your identification type, then use the client ID as the username and the client secret as the password.

Alternatively, you can use a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. Using this helps to protect against replay attacks, and ensures that client secrets are well protected.

To generate an HMAC signature you will need the following:

  • The root-anchored API endpoint (for example, /entity.find).

  • The parameters of the API call as key=value pairs, sorted alphabetically and separated by newlines (\n).

  • The date as specified in the Date header in your request.

  • Your API client secret.

  • Your API client ID.

After you have that information, complete the following procedure:

  1. Concatenate the endpoint, datetime, and sorted parameters with newline characters (\n). This creates the string you will sign.

  2. Use the client secret to sign the string using SHA–1, then base64 encode the result.

  3. Prepend your client ID to this signature with a colon (:).

The resulting string is a signature that uniquely identifies a single request. For example:

Authorization: Signature apkrahlfumwse2e9nvrrotv6vchuptzw:Pm0y2b8b/tH4HrEqKqSm7zQk1s8=

The following Python script can be used to create an HMAC signature:

importhmac
frombase64 importb64encode
fromhashlib importsha1
defmake_signed_auth_header(endpoint, params, datetime, client_id, secret):
    kv_params = ['{}={}'.format(k, v) fork, v inparams.items()]
    kv_params.sort()
    kv_string = '\n'.join(kv_params)
    str_to_sign = '{}\n{}\n{}\n'.format(endpoint, datetime, kv_string)
    hashed_str = b64encode(hmac.new(secret, str_to_sign, sha1).digest())
    return{'Authorization': 'Signature {}:{}'.format(client_id, hashed_str)}

In addition to Basic and HMAC authentication, some of the Entity and EntityType endpoints can use access tokens to support a custom variant of OAuth authentication. The following endpoints accept OAuth access token authentication:

  • /entity
  • /entity.delete
  • /entity.replace
  • /entity.update
  • /entityType

For example:

Authorization: OAuth SlAV32hkKG

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Entities  
List user profile values POST /entity{?type_name,attribute_name,id,password_attribute,password_value,attributes,created,lastUpdated,key_attribute,key_value}
Create multiple user accounts POST /entity.bulkCreate{?all_attributes,type_name}
Count user records POST /entity.count{?type_name,filter}
Create a profile POST /entity.create{?attributes,type_name,include_record}
Delete a profile POST /entity.delete{?uuid,type_name,attribute_name,id,created,lastUpdated,key_attribute,key_value}
Invalidate current session POST /entity.deleteAccess{?id,uuid,key_attribute,key_value}
Search for users POST /entity.find{?type_name,filter,max_results,sort_on,attributes}
Replace profile values POST /entity.replace{?uuid,type_name,id,attribute_name,include_record,value,created,lastUpdated,key_attribute,key_value}
Update profile values POST /entity.update{?uuid,type_name,id,attribute_name,include_record,value,created,lastUpdated,key_attribute,key_value}
Entity Types  
Get an entity type GET /entityType{?type_name}
Add an attribute POST /entityType.addAttribute{?attr_def,type_name}
Add data validation POST /entityType.addRule{?attributes,description,definition,type_name}
Create an entity type POST /entityType.create{?attr_defs,type_name}
Delete an entity type access schema POST /entityType.deleteAccessSchema{?for_client_id,type_name,access_type}
Get an entity type access schema POST /entityType.getAccessSchema{?for_client_id,type_name,access_type}
List entity types POST /entityType.list
Remove an attribute POST /entityType.removeAttribute{?attribute_name,type_name}
Remove a validation rule POST /entityType.removeRule{?uuid,type_name}
List validation rules POST /entityType.rules{?type_name}

List user profile values

Retrieve a single entity (and any nested objects).

POST /entity{?type_name,attribute_name,id,password_attribute,password_value,attributes,created,lastUpdated,key_attribute,key_value}

Sample: /entity?type_name=user&attribute_name=displayName&id=999&password_attribute=password&password_value=p%40ssw0rd&attributes=%5B%22email%22%2C%20%22familyName%22%2C%20%22givenName%22%2C%20%22created%22%5D&created=2018-11-15%2001%3A58%3A01.862312%20%2B0000&lastUpdated=2018-10-05%2021%3A37%3A13.031989%20%2B0000&key_attribute=%5B%22email%22%5D&key_value=karim.nafir%40mail.com

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.
Optional query parameters
attribute_name String displayName Attribute to be returned. When used, values are only returned for the specified attribute. (By default, all attribute values are returned.)
attributes String ["email", "familyName", "givenName", "created"] JSON array of attributes to be returned. When used, values are only returned for the specified attributes. (By default, all attribute values are returned.)
created String 2018-11-15 01:58:01.862312 +0000 Timestamp generated when the entity was created. If this value is present but is incorrect, the call fails.
id Integer 999 ID of the user record. Required unless you are using the uuid or key_attribute parameter.
key_attribute String ["email"] Name of a unique attribute used with schema. Required if you are not using the id or uuid parameters, and must be used in conjunction with the key_value parameter.
key_value String karim.nafir@mail.com Value for the attribute specified by the key_attribute parameter. String values must be enclosed in quotes.
lastUpdated String 2018-10-05 21:37:13.031989 +0000 Timestamp generated when the entity was last updated. If this value is present but is incorrect, the call fails.
password_attribute String password Path to a schema attribute that includes a password constraint. You can use the password_attribute and password_value parameters together. Use password_attribute to specify the attribute to authenticate against, and password_value to specify the authenticating password.
password_value String p@ssw0rd Plaintext value that is matched against the password attribute specified in the password_attribute parameter. If successful, the entity is returned. If unsuccessful, the API call fails.

Status 200 application/json

Object type: UserProfile

Download schema: entity.json

Response body:

{
    "stat": "ok",
    "result": {
        "birthday": null,
        "familyName": "Doe",
        "id": 999,
        "middleName": null,
        "emailVerified": "2015-11-15 01:58:01 +0000",
        "gender": "male",
        "lastUpdated": "2016-03-13 19:39:17.856608 +0000",
        "password": null,
        "email": "johndoe@example.com",
        "givenName": "John",
        "currentLocation": null,
        "deactivateAccount": null,
        "lastLogin": "2016-03-13 19:39:17 +0000",
        "created": "2015-11-15 01:58:01.862312 +0000",
        "displayName": "John Doe",
        "uuid": "12345abc-1234-abcd-1234-12345abcde12",
        "aboutMe": null,
        "display": null,
        "profiles": [],
        "photos": [],
        "statuses": [],
        "primaryAddress": {
            "company": null,
            "address2": "",
            "stateAbbreviation": "NM",
            "zipPlus4": null,
            "city": "",
            "address1": "",
            "phone": "5551234567",
            "zip": "",
            "mobile": null,
            "country": "United States"
        }
    }
}

Sample curl requests

curl -X POST -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode type_name=user \
    --data-urlencode id=999\
    --data-urlencode created='2014-11-15 01:58:01.862312 +0000'\
    https://my-app.janraincapture.com/entity
curl -X POST -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode id=999 \
    --data-urlencode attributes='["email", "familyName", "givenName", "created"]' \
    https://my-app.janraincapture.com/entity
curl -X POST -H "Authorization: Basic aW1fYV...NfbXk=" \
    --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
curl -X POST -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode type_name=user \
    --data-urlencode id=999\
    --data-urlencode password_attribute=password \
    --data-urlencode password_value=Test123 \
    --data-urlencode attributes='["created"]'\
    https://my-app.janraincapture.com/entity

Create multiple user accounts

Create multiple new data records of a specific entityType in a single API call. If the request is structurally valid and properly authorized, it is added independently. The result contains a list of uuid_results and ID results from each record addition or a failure message for each record.

POST /entity.bulkCreate{?all_attributes,type_name}

Sample: /entity.bulkCreate?all_attributes=%5B%7B%22familyName%22%3A%22Jones%22%2C%20%22givenName%22%3A%22Abe%22%2C%20%20%22email%22%3A%22jonesa%40example.com%22%2C%20%22statuses%22%3A%5B%7B%22status%22%3A%22active%22%2C%20%20%22statusCreated%22%3A%222015-12-15T07%3A36%3A25Z%22%7D%5D%7D%2C%20%7B%22givenName%22%3A%22Jackson%22%2C%20%20%22familyName%22%3A%22Gordon%22%2C%20%22email%22%3A%22gjack%40test.com%22%2C%20%22statuses%22%3A%5B%7B%22status%22%3A%20%22inactive%22%2C%20%22statusCreated%22%3A%222015-10-12T04%3A00%3A00Z%22%7D%5D%7D%2C%20%7B%22givenName%22%3A%22Sally%22%2C%20%20%22familyName%22%3A%20%22Smith%22%2C%20%22email%22%3A%22ssmith%40myorg.org%22%7D%5D&type_name=user

Parameter Type Sample Description
Required query parameters
all_attributes String [{"familyName":"Jones", "givenName":"Abe", "email":"jonesa@example.com", "statuses":[{"status":"active", "statusCreated":"2015-12-15T07:36:25Z"}]}, {"givenName":"Jackson", "familyName":"Gordon", "email":"gjack@test.com", "statuses":[{"status": "inactive", "statusCreated":"2015-10-12T04:00:00Z"}]}, {"givenName":"Sally", "familyName": "Smith", "email":"ssmith@myorg.org"}] Attribute names and values (formatted as a JSON object) for the entity. This argument is parsed as one entity – if any part of the argument fails to parse, the entire request will be rejected.
type_name String user Name of the entityType.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "uuid_results": [
        "efd7fe4e-c0a2-4b80-876e-1d06df393579",
        "3314d744-09a9-4264-a17f-402d3e4824e7",
        "639dbbbc-6cac-4054-83be-92e08ced155f"
    ],
    "results": [
        11393,
        11395,
        11397
    ]
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user\
    --data-urlencode all_attributes='[{"familyName":"Jones","givenName":"Abe",
      "email":"jonesa@example.com","statuses":[{"status":"active",
      "statusCreated":"2015-12-15T07:36:25Z"}]},{"givenName":"Jackson",
      "familyName":"Gordon","email":"gjack@test.com","statuses":[{"status":
      "inactive","statusCreated":"2015-10-12T04:00:00Z"}]},{"givenName":"Sally",
      "familyName": "Smith","email":"ssmith@myorg.org"}]' \
    https://my-app.janraincapture.com/entity.bulkCreate

Count user records

Count the number of records in an entityType that match a query contained in the filter parameter.

POST /entity.count{?type_name,filter}

Sample: /entity.count?type_name=user&filter=birthday%20is%20not%20null

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.
Optional query parameters
filter String birthday is not null A query against record fields. If this parameter is not included, all records in the entity are counted. For more information on constructing queries, see entity.find.

Status 200 application/json

Response body:

{
    "total_count": 15,
    "stat": "ok"
}

Sample curl request

curl -X POST -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode filter='birthday is not null'\
    https://my-app.janraincapture.com/entity.count

Create a profile

Create a new data record for an entityType. Once created, the new ID and uuid values are returned.

POST /entity.create{?attributes,type_name,include_record}

Sample: /entity.create?attributes=%7B%22givenName%22%3A%22Matt%22%2C%22familyName%22%3A%22Parker%22%2C%20%22email%22%3A%22parkerm%40example.com%22%2C%22statuses%22%3A%5B%7B%22status%22%3A%22active%22%2C%20%22statusCreated%22%3A%222015-12-15T07%3A36%3A25Z%22%7D%5D%7D&type_name=user&include_record=true

Parameter Type Sample Description
Required query parameters
attributes String {"givenName":"Matt","familyName":"Parker", "email":"parkerm@example.com","statuses":[{"status":"active", "statusCreated":"2015-12-15T07:36:25Z"}]} Attribute names and values (formatted as a JSON object) for the entity. Note that you do not need to include all the possible user profile attributes – the new record will be created using whatever attributes and attribute values you supply.
type_name String user Name of the entityType.
Optional query parameters
include_record Boolean true When set to true, the API response includes all the attributes and attribute values assigned to the new record.

Status 200 application/json

Response body:

{
    "id": 11649,
    "uuid": "02b0c68d-7d7a-49d8-a88d-022585b0f877",
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user\
    --data-urlencode attributes='{"givenName":"Matt","familyName":"Parker",
      "email":"parkerm@example.com","statuses":[{"status":"active",
      "statusCreated":"2015-12-15T07:36:25Z"}]}' \
    https://my-app.janraincapture.com/entity.create

Delete a profile

Delete a single entity (and any nested objects) from an application, or delete an element of a plural. Data removed with this API call are permanently deleted.

POST /entity.delete{?uuid,type_name,attribute_name,id,created,lastUpdated,key_attribute,key_value}

Sample: /entity.delete?uuid=bc90747f-ebc0-4fc2-8f38-c393d64a8248&type_name=user&attribute_name=janrain.properties.managedBy%2330721&id=999&created=2018-11-15%2001%3A58%3A01.862312%20%2B0000&lastUpdated=2018-10-05%2021%3A37%3A13.031989%20%2B0000&key_attribute=%5B%22email%22%5D&key_value=karim.nafir%40mail.com

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.
uuid String bc90747f-ebc0-4fc2-8f38-c393d64a8248 Unique identifier for the entity. Must be used unless you are using the ID or key_attribute parameters to identify the user record.
Optional query parameters
attribute_name String janrain.properties.managedBy#30721 Attribute path to the plural element to be deleted. Specific instances within a plural are referenced by a combination of the attribute path, a hashtag (#), and the instance ID. For example, janrain.properties.managedBy#30721 points to plural instance 30721 in the plural attribute janrain.properties.managedBy.
created String 2018-11-15 01:58:01.862312 +0000 Timestamp generated when the entity was created. If this value is present but is incorrect, the call fails.
id Integer 999 ID of the entity to be deleted. This parameter is required when not using the uuid or key_attribute and key_value parameters. The primary key of the parent object.
key_attribute String ["email"] Name of a unique attribute used with schema. Required if you are not using the id or uuid parameters, and must be used in conjunction with the key_value parameter.
key_value String karim.nafir@mail.com Value for the attribute specified by the key_attribute parameter. String values must be enclosed in quotes.
lastUpdated String 2018-10-05 21:37:13.031989 +0000 Timestamp generated when the entity was last updated. If this value is present but is incorrect, the call fails.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl-X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode uuid=abcde12345abcde12345abcde12345abcde1 \
    https://my-app.janraincapture.com/entity.delete

Invalidate current session

This API call removes all existing access grants associated with the selected entity from the Registration service. This permanently removes all access tokens, all refresh tokens, and all refresh secrets associated with the entity. The intention is to invalidate sessions that are associated with the selected entity, and force the user to sign in again at the point the client attempts to use any of the access grants for that entity. Any access token stored in a browser or mobile application, any refresh token stored on a server or refresh secret generated in a mobile application is invalidated and cannot be used again. Note that this endpoint does not remove access grants that may be managed by other services, such as Single Sign-On.

POST /entity.deleteAccess{?id,uuid,key_attribute,key_value}

Sample: /entity.deleteAccess?id=11649&uuid=2efede78-fdf7-4e38-9785-4a82de768b9f&key_attribute=%5B%22email%22%5D&key_value=karim.nafir%40mail.com

Parameter Type Sample Description
Optional query parameters
id Integer 11649 Entity ID. Required if you are not using the uuid or key_attributes parameters.
key_attribute String ["email"] Name of a unique attribute used with schema. Required if you are not using the id or uuid parameters, and must be used in conjunction with the key_value parameter.
key_value String karim.nafir@mail.com Value for the attribute specified by the key_attribute parameter. String values must be enclosed in quotes.
uuid String 2efede78-fdf7-4e38-9785-4a82de768b9f Unique identifier for the user record. Required if you are not using the ID or key_attribute parameters.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode uuid=2efede78-fdf7-4e38-9785-4a82de768b9f \
    https://my-app.janraincapture.com/entity.deleteAccess

Search for users

Retrieve user information from an application. These data entities are returned in JSON format. This information may be filtered using the optional parameters provided.

POST /entity.find{?type_name,filter,max_results,sort_on,attributes}

Sample: /entity.find?type_name=user&filter=gender%3D%27male%27&max_results=250&sort_on=%5B%22familyName%22%2C%20%22givenName%22%5D&attributes=%5B%22displayName%22%2C%20%22email%22%5D

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.
Optional query parameters
attributes String ["displayName", "email"] JSON array of attributes to be returned. By default, all attributes and attribute values are returned.
filter String gender='male' Expression used to filter the result. By default, all records are returned.
max_results Integer 250 Integer value between 1 and 1000, inclusive, specifying the maximum number of records to be returned. The default value is 100.
sort_on String ["familyName", "givenName"] JSON array of attributes used to specify the sort order. By default, results are sorted in ascending order. To sort in descending order, place a minus sign (-) directly in front of the appropriate attribute.

Status 200 application/json

Response body:

{
    "result_count": 6,
    "stat": "ok",
    "results": [
        {
            "displayName": "ian",
            "email": "ian@example.com"
        },
        {
            "displayName": "Rex",
            "email": "rex@example.com"
        },
        {
            "displayName": "sam",
            "email": "smann@example.com"
        },
        {
            "displayName": "alex",
            "email": "alex@example.com"
        },
        {
            "displayName": "john.j",
            "email": "jj@example.com"
        },
        {
            "displayName": "daniel",
            "email": "daniel@example.com"
        }
    ]
}

Sample curl request

curl -X POST -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user\
    --data-urlencode attributes='["displayName", "email"]' \
    https://my-app.janraincapture.com/entity.find

Replace profile values

Replace part of an entity with a value. The entity.replace call can be destructive. Any object attributes that you do not specify are replaced with null values. Plural values are replaced, and all new elements are automatically assigned IDs. For an additive operation, use entity.update.

POST /entity.replace{?uuid,type_name,id,attribute_name,include_record,value,created,lastUpdated,key_attribute,key_value}

Sample: /entity.replace?uuid=bc90747f-ebc0-4fc2-8f38-c393d64a8248&type_name=user&id=999&attribute_name=clients&include_record=true&value=%7B%22givenName%22%3A%22Mathew%22%2C%20%22familyName%22%3A%22Parkerson%22%2C%20%22email%22%3A%22parkerm%40example.com%22%7D&created=2018-11-15%2001%3A58%3A01.862312%20%2B0000&lastUpdated=2018-10-05%2021%3A37%3A13.031989%20%2B0000&key_attribute=%5B%22email%22%5D&key_value=karim.nafir%40mail.com

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.
uuid String bc90747f-ebc0-4fc2-8f38-c393d64a8248 Unique identifier for the entity. Must be used unless you are using the ID or key_attribute parameters to identify the user record.
Optional query parameters
attribute_name String clients Path 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 record being updated.
created String 2018-11-15 01:58:01.862312 +0000 Timestamp generated when the entity was created. If this value is present but is incorrect, the call fails.
id Integer 999 ID of the entity. This parameter is required when not using the uuid or key_attribute and key_value parameters. The primary key of the parent object.
include_record Boolean true When set to true, the API response includes all the attributes and attribute values assigned to the new record.
key_attribute String ["email"] Name of a unique attribute used with schema. Required if you are not using the id or uuid parameters, and must be used in conjunction with the key_value parameter.
key_value String karim.nafir@mail.com Value for the attribute specified by the key_attribute parameter. String values must be enclosed in quotes.
lastUpdated String 2018-10-05 21:37:13.031989 +0000 Timestamp generated when the entity was last updated. If this value is present but is incorrect, the call fails.
value String {"givenName":"Mathew", "familyName":"Parkerson", "email":"parkerm@example.com"} JSON-formatted value assigned to the attribute_name parameter. For backward compatibility, this attribute can also be referred to as the attributes parameter.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl requests

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode uuid=0987098709870987 \
    --data-urlencode attributes='{"givenName":"Bob","familyName":"Smith"}'\
    https://my-app.janraincapture.com/entity.replace
curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --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

Update profile values

Updates part of an existing entity by appending attributes with data. This data is provided in a JSON object that specifies the path to the attribute, and the value to use. Any object attributes not in the JSON provided are left alone. Plural values are appended, unless an ID is provided, in which case the plural data is replaced.

POST /entity.update{?uuid,type_name,id,attribute_name,include_record,value,created,lastUpdated,key_attribute,key_value}

Sample: /entity.update?uuid=bc90747f-ebc0-4fc2-8f38-c393d64a8248&type_name=user&id=999&attribute_name=clients&include_record=true&value=%7B%22givenName%22%3A%22Mathew%22%2C%20%22familyName%22%3A%22Parkerson%22%2C%20%22email%22%3A%22parkerm%40example.com%22%7D&created=2018-11-15%2001%3A58%3A01.862312%20%2B0000&lastUpdated=2018-10-05%2021%3A37%3A13.031989%20%2B0000&key_attribute=%5B%22email%22%5D&key_value=karim.nafir%40mail.com

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.
uuid String bc90747f-ebc0-4fc2-8f38-c393d64a8248 Unique identifier for the entity. Must be used unless you are using the ID or key_attribute parameters to identify the user record.
Optional query parameters
attribute_name String clients Path 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 record being updated.
created String 2018-11-15 01:58:01.862312 +0000 Timestamp generated when the entity was created. If this value is present but is incorrect, the call fails.
id Integer 999 ID of the entity. This parameter is required when not using the uuid or key_attribute and key_value parameters. The primary key of the parent object.
include_record Boolean true When set to true, the API response includes all the attributes and attribute values assigned to the new record.
key_attribute String ["email"] Name of a unique attribute used with schema. Required if you are not using the id or uuid parameters, and must be used in conjunction with the key_value parameter.
key_value String karim.nafir@mail.com Value for the attribute specified by the key_attribute parameter. String values must be enclosed in quotes.
lastUpdated String 2018-10-05 21:37:13.031989 +0000 Timestamp generated when the entity was last updated. If this value is present but is incorrect, the call fails.
value String {"givenName":"Mathew", "familyName":"Parkerson", "email":"parkerm@example.com"} JSON-formatted value assigned to the attribute_name parameter. For backward compatibility, this attribute can also be referred to as the attributes parameter.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl requests

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode uuid=0987098709870987 \
    --data-urlencode attributes='{"givenName":"Matt","familyName":"Parker"}'\
    https://my-app.janraincapture.com/entity.update
curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode id=11777\
    --data-urlencode attribute_name='/statuses#11905'\
    --data-urlencode value='{"status":"active"}'\
    https://my-app.janraincapture.com/entity.update
curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode key_attribute=email \
    --data-urlencode key_value='"parkerm@example.com"'\
    --data-urlencode value='{"displayName":"parkerm"}'\
    https://my-app.janraincapture.com/entity.update

Get an entity type

Return a JSON representation of an existing entityType.

GET /entityType{?type_name}

Sample: /entityType?type_name=user

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.

Status 200 application/json

Object type: EntityType

Download schema: entityType.json

Response body:

{
    "stat": "ok",
    "schema": {
        "name": "user",
        "attr_defs": [
            {
                "name": "id",
                "type": "id"
            },
            {
                "name": "lastUpdated",
                "type": "version"
            },
            {
                "name": "birthday",
                "type": "string",
                "length": 10
            },
            {
                "name": "zipcode",
                "type": "string",
                "length": 5
            },
            {
                "name": "name",
                "type": "object",
                "attr_defs": [
                    {
                        "name": "id",
                        "type": "id"
                    },
                    {
                        "name": "firstName",
                        "type": "string",
                        "length": 128
                    },
                    {
                        "name": "lastName",
                        "type": "string",
                        "length": 128
                    }
                ]
            }
        ]
    }
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user\
    https://my-app.janraincapture.com/entityType

Add an attribute

Adds an attribute to an existing entityType schema and all stored objects of that type. Each attribute requires a type which defines the nature of the data to be stored.

POST /entityType.addAttribute{?attr_def,type_name}

Sample: /entityType.addAttribute?attr_def=%7B%22name%22%3A%22testPlural%22%2C%20%22type%22%3A%22plural%22%2C%20%22attr_defs%22%3A%5B%7B%22name%22%3A%22testPOne%22%2C%20%22type%22%3A%22string%22%2C%20%22length%22%3A256%7D%2C%20%7B%22name%22%3A%22testTwo%22%2C%20%22type%22%3A%22string%22%2C%20%22length%22%3A%20256%7D%5D%7D&type_name=user

Parameter Type Sample Description
Required query parameters
attr_def String {"name":"testPlural", "type":"plural", "attr_defs":[{"name":"testPOne", "type":"string", "length":256}, {"name":"testTwo", "type":"string", "length": 256}]} Attribute (formatted as a JSON object) to be added to the entityType.
type_name String user Name of the entityType.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "schema": {
        "name": "user",
        "attr_def": [
            {
                "description": "simple identifier for this entity",
                "name": "id",
                "type": "id"
            },
            {
                "description": "globally unique identifier for this entity",
                "name": "uuid",
                "type": "uuid"
            },
            {
                "description": "when this entity was created",
                "name": "created",
                "type": "dateTime"
            },
            {
                "description": "when this entity was last updated",
                "name": "lastUpdated",
                "type": "dateTime"
            },
            {
                "case-sensitive": false,
                "length": 1000,
                "name": "Description",
                "type": "string"
            },
            {
                "case-sensitive": false,
                "length": null,
                "name": "Name",
                "type": "string"
            },
            {
                "case-sensitive": true,
                "length": 50,
                "name": "fullName",
                "type": "string"
            }
        ]
    }
}

Sample curl requests

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode attr_def='{"name":"fullName","type":"string","length":50}'\
    https://my-app.janraincapture.com/entityType.addAttribute
curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode attr_def='{"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
curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode attr_def='{"name":"testPlural","type":"plural",
      "attr_defs":[{"name":"testPOne","type":"string","length":256},
      {"name":"testPTwo","type":"string","length": 256}]}'\
    https://my-app.janraincapture.com/entityType.addAttribute
curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user\
    --data-urlencodeattr_def='{"name":"emailPreVerified","type":"dateTime"}' \
    https://my-app.janraincapture.com/entityType.addAttribute

Add data validation

This call creates rules for user data validation on specific attributes in your schema. User data can be validated or transformed by this rule when it is added or updated. Example uses for entityType.addRule: 1) defining a validation rule that rejects strings that don’t match a regular expression, such as rejecting username values that are not in the English alphabet; and, 2) truncating input to a certain length.

POST /entityType.addRule{?attributes,description,definition,type_name}

Sample: /entityType.addRule?attributes=%5B%22givenName%22%2C%20%22familyName%22%5D&description=This%20is%20a%20rule%20to%20accept%20only%20English%20letters%20and%20have%20a%20maximum%20Length%20of%2035&definition=%7B%22and%22%3A%20%5B%7B%22match-all%22%3A%22%5Ba-zA-Z%5D%2A%22%7D%2C%20%7B%22max-length%22%3A25%7D%5D%7D&type_name=user

Parameter Type Sample Description
Required query parameters
attributes String ["givenName", "familyName"] JSON array of the attributes to which the rule will be applied. The default is all attributes.
definition String {"and": [{"match-all":"[a-zA-Z]*"}, {"max-length":25}]} JSON-formatted object defining the rule.
description String This is a rule to accept only English letters and have a maximum Length of 35 Brief description of the rule and its purpose.
type_name String user Name of the entityType.

Status 200 application/json

Object type: ValidationRule

Download schema: entityType-addRule.json

Response body:

{
    "stat": "ok",
    "result": {
        "description": "This is a rule to accept only English letters and have a maximum Length of 25",
        "uuid": "ed23abc2-5023-477d-b728-b4cfdc885f3e",
        "attributes": [
            "/givenName"
        ],
        "definition": {
            "and": [
                {
                    "match-all": "[a-zA-Z]*"
                },
                {
                    "max-length": 25
                }
            ]
        }
    }
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode attributes=["givenName"] \
    --data-urlencode description="This is a rule to accept only English letters and have a maximum Length of 25"\
    --data-urlencode definition='{"and": [{"match-all":"[a-zA-Z]*"}, {"max-length":25}]}'\
    https://my-app.janraincapture.com/entityType.addRule

Create an entity type

Create a new entityType with the specified set of attributes.

POST /entityType.create{?attr_defs,type_name}

Sample: /entityType.create?attr_defs=%5B%7B%22name%22%3A%22name%22%2C%20%22type%22%3A%22string%22%2C%20%20%22case-sensitive%22%3Afalse%7D%2C%20%7B%22name%22%3A%22description%22%2C%20%22type%22%3A%22string%22%2C%20%22length%22%3A%201000%2C%20%22case-sensitive%22%3Afalse%7D%5D&type_name=user

Parameter Type Sample Description
Required query parameters
attr_defs String [{"name":"name", "type":"string", "case-sensitive":false}, {"name":"description", "type":"string", "length": 1000, "case-sensitive":false}] Initial set of attributes (formatted as a JSON object) to be added to the entityType.
type_name String user Name of the entityType.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "schema": {
        "name": "user_test",
        "attr_defs": [
            {
                "name": "id",
                "description": "simple identifier for this entity",
                "type": "id"
            },
            {
                "name": "uuid",
                "description": "globally unique identifier for this entity",
                "type": "uuid"
            },
            {
                "name": "created",
                "description": "when this entity was created",
                "type": "dateTime"
            },
            {
                "name": "lastUpdated",
                "description": "when this entity was last updated",
                "type": "dateTime"
            },
            {
                "length": 1000,
                "name": "description",
                "type": "string",
                "case-sensitive": false
            },
            {
                "length": null,
                "name": "name",
                "type": "string",
                "case-sensitive": false
            }
        ]
    }
}

Sample curl requests

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user_test \
    --data-urlencode attr_defs='[{"name":"name","type":"string",
      "case-sensitive":false},{"name":"description","type":"string","length":
      1000,"case-sensitive":false}]'\
    https://my-app.janraincapture.com/entityType.create
curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user2 \
    --data-urlencode attr_defs='[{"name":"testPlural","type":"plural",
      "attr_defs":'[{"name":"testPOne","type":"string","length":256},
      {"name":"testPTwo","type":"string"}]},{"name":"testObject",
      "type":"object","attr_defs":[{"name":"testOne","type":"string","length":256},
      {"name":"testTwo","type":"string"}]},
      {"name":"name","type":"string","case-sensitive":false},
      {"name":"description","type":"string","length":1000,"case-sensitive":false}]' \
    https://my-app.janraincapture.com/entityType.create

Delete an entity type access schema

Deletes the specified access schema for a client. Access schemas define the subset of attributes that a client has read or write access to. Deleting an access schema will grant a client read or write access to all attributes again. This action cannot be undone. Before deleting an access schema we recommend saving a backup of the current access schema using the entityType.getAccessSchema API.

POST /entityType.deleteAccessSchema{?for_client_id,type_name,access_type}

Sample: /entityType.deleteAccessSchema?for_client_id=0987fghi0987fghi&type_name=user&access_type=write

Parameter Type Sample Description
Required query parameters
access_type Enumeration write Type of access schema, either read, write, read_with_token, or write_with_token.
for_client_id String 0987fghi0987fghi Client ID of the client whose access schema is being deleted.
type_name String user Name of the entityType.

Status 200 application/json

Response body:

{
    "result": "access schema was deleted.",
    "stat": "ok"
}

Sample curl request

curl -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode type_name=user \
    --data-urlencode for_client_id=0987fghi0987fghi \
    --data-urlencode access_type=write \
    https://my-app.janraincapture.com/entityType.deleteAccessSchema

Get an entity type access schema

Retrieve the access schema for a particular client. An access schema defines the subset of attributes to which a client has read or write access.

POST /entityType.getAccessSchema{?for_client_id,type_name,access_type}

Sample: /entityType.getAccessSchema?for_client_id=0987fghi0987fghi&type_name=user&access_type=write

Parameter Type Sample Description
Required query parameters
access_type Enumeration write Type of access schema, either read, write, read_with_token, or write_with_token.
for_client_id String 0987fghi0987fghi Client ID of the client whose access schema is being deleted.
type_name String user Name of the entityType.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "schema": {
        "name": "user",
        "attr_defs": [
            {
                "name": "id",
                "description": "simple identifier for this entity",
                "type": "id"
            },
            {
                "name": "uuid",
                "description": "globally unique identifier for this entity",
                "type": "uuid"
            },
            {
                "name": "created",
                "description": "when this entity was created",
                "type": "dateTime"
            },
            {
                "name": "lastUpdated",
                "description": "when this entity was last updated",
                "type": "dateTime"
            },
            {
                "case-sensitive": false,
                "name": "Description",
                "length": 1000,
                "type": "string"
            },
            {
                "case-sensitive": false,
                "name": "Name",
                "length": null,
                "type": "string",
                "constraints": [
                    "alphanumeric"
                ]
            }
        ]
    }
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk=" \
    --data-urlencode type_name=user \
    --data-urlencode for_client_id=0987fghi0987fghi \
    --data-urlencode access_type=write \
    https://my-app.janraincapture.com/entityType.getAccessSchema

List entity types

Return a JSON representation of all entityTypes.

POST /entityType.list

Status 200 application/json

Response body:

{
    "stat": "ok",
    "results": [
        "user"
    ]
}

Sample curl request

curl -H "Authorization: Basic aW1fYV...NfbXk="\
    https://my-app.janraincapture.com/entityType.list

Remove an attribute

Remove an existing attribute from an entityType. Note that all data associated with this attribute will be lost.

POST /entityType.removeAttribute{?attribute_name,type_name}

Sample: /entityType.removeAttribute?attribute_name=fullName&type_name=user

Parameter Type Sample Description
Required query parameters
attribute_name String fullName Name of the attribute to be deleted.
type_name String user Name of the entityType.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "schema": {
        "name": "user",
        "attr_defs": [
            {
                "description": "simple identifier for this entity",
                "name": "id",
                "type": "id"
            },
            {
                "description": "globally unique identifier for this entity",
                "name": "uuid",
                "type": "uuid"
            },
            {
                "description": "when this entity was created",
                "name": "created",
                "type": "dateTime"
            },
            {
                "description": "when this entity was last updated",
                "name": "lastUpdated",
                "type": "dateTime"
            },
            {
                "case-sensitive": false,
                "length": 1000,
                "name": "Description",
                "type": "string"
            },
            {
                "case-sensitive": false,
                "length": null,
                "name": "Name",
                "type": "string"
            }
        ]
    }
}

Sample curl request

curl -X POST \
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user \
    --data-urlencode attribute_name=fullName \
    https://my-app.janraincapture.com/entityType.removeAttribute "stat": "ok"

Remove a validation rule

This removes any data validation currently configured for a specific attribute in a schema.

POST /entityType.removeRule{?uuid,type_name}

Sample: /entityType.removeRule?uuid=bc90747f-ebc0-4fc2-8f38-c393d64a8248&type_name=user

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.
uuid String bc90747f-ebc0-4fc2-8f38-c393d64a8248 UUID assigned to the rule to be deleted. You can return rule UUIDs by using the entityType.rules endpoint.

Status 200 application/json

Response body:

{
    "stat": "ok"
}

Sample curl request

curl -X POST
    -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user
    --data-urlencode uuid=0987-fghi-0987-fghi
    https://my-app.janraincapture.com/entityType.removeRule

List validation rules

This lists the data validation rules that are currently set on a specific entityType. Each rule has a uuid identifier associated with it which is listed as well.

POST /entityType.rules{?type_name}

Sample: /entityType.rules?type_name=user

Parameter Type Sample Description
Required query parameters
type_name String user Name of the entityType.

Status 200 application/json

Response body:

{
    "stat": "ok",
    "results": [
        {
            "description": "This is a rule to accept only English letters and have a maximum Length of 25",
            "uuid": "656670ad-ae24-43a2-8ab1-a8b070c19bb8",
            "attributes": [
                "/givenName"
            ],
            "definition": {
                "and": [
                    {
                        "match-all": "[a-zA-Z]*"
                    },
                    {
                        "max-length": 25
                    }
                ]
            }
        }
    ]
}

Sample curl request

curl -G -H "Authorization: Basic aW1fYV...NfbXk="\
    --data-urlencode type_name=user\
    https://my-app.janraincapture.com/entityType.rules

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

UserProfile

Return information for the specified entity (user profile).

Download schema: entity.json

Sample POST response:

{
    "stat": "ok",
    "result": {
        "birthday": null,
        "familyName": "Doe",
        "id": 999,
        "middleName": null,
        "emailVerified": "2015-11-15 01:58:01 +0000",
        "gender": "male",
        "lastUpdated": "2016-03-13 19:39:17.856608 +0000",
        "password": null,
        "email": "johndoe@example.com",
        "givenName": "John",
        "currentLocation": null,
        "deactivateAccount": null,
        "lastLogin": "2016-03-13 19:39:17 +0000",
        "created": "2015-11-15 01:58:01.862312 +0000",
        "displayName": "John Doe",
        "uuid": "12345abc-1234-abcd-1234-12345abcde12",
        "aboutMe": null,
        "display": null,
        "profiles": [],
        "photos": [],
        "statuses": [],
        "primaryAddress": {
            "company": null,
            "address2": "",
            "stateAbbreviation": "NM",
            "zipPlus4": null,
            "city": "",
            "address1": "",
            "phone": "5551234567",
            "zip": "",
            "mobile": null,
            "country": "United States"
        }
    }
}

UserProfile members

Member Type Description
UserProfile: Return information for the specified entity (user profile).
result UserProfile.result Properties and property values associated with the user profile.
stat String Indicates the current status of the operation.
UserProfile.result: Properties and property values associated with the user profile.
aboutMe String, Null Biographical information about the user.
birthday String, Null User’s date of birth.
created String UTC timestamp specifying the date and time that the user profile was created.
currentLocation String, Null User’s current geographic location.
deactivateAccount String, Null UTC timestamp specifying the date and time that the user account was deactivated.
displayName String User’s display name.
email String User’s email address.
emailVerified String UTC timestamp specifying when the user’s email address was verified.
familyName String User’s last name.
gender String User’s preferred gender.
givenName String User’s first name.
id Integer Identifier assigned to the user profile.
lastLogin String UTC timestamp specifying the last time that the user logged on.
lastUpdated String UTC timestamp specifying the last time the user profile was updated.
middleName String, Null User’s middle name.
password String, Null User password. The password itself is not accessible.
photos Array URLs pointing to photos of the user.
primaryAddress UserProfile.result.primaryAddress JSON-formatted object containing address and phone number information for the user.
profiles Array Collection of social identity accounts associated with the user.
uuid String Unique identifier assigned to the user.
UserProfile.result.primaryAddress: JSON-formatted object containing address and phone number information for the user.
address1 String First address line of the user’s home address.
address2 String Second address line of the user’s home address.
city String User’s home city.
company String, Null The user’s company or organization.
country String User’s country of residence.
mobile String, Null User’s mobile phone number.
phone String User’s home phone number.
stateAbbreviation String Two-letter abbreviation for the user’s home state.
zip String User’s home zip code.
zipPlus4 String, Null User’s home zip code, in the Zip Plus 4 format.

EntityType

Describes the components that make up an Identity Cloud entity type. Entity types are a special kind of database that store Identity Cloud user profiles. Each entity type is based on a schema, a blueprint that specifies the kind of data that can be stored in that entity type. In turn, schemas are composed of attributes, which are functionally equivalent to database fields.

Download schema: entityType.json

Sample GET response:

{
    "stat": "ok",
    "schema": {
        "name": "user",
        "attr_defs": [
            {
                "name": "id",
                "type": "id"
            },
            {
                "name": "lastUpdated",
                "type": "version"
            },
            {
                "name": "birthday",
                "type": "string",
                "length": 10
            },
            {
                "name": "zipcode",
                "type": "string",
                "length": 5
            },
            {
                "name": "name",
                "type": "object",
                "attr_defs": [
                    {
                        "name": "id",
                        "type": "id"
                    },
                    {
                        "name": "firstName",
                        "type": "string",
                        "length": 128
                    },
                    {
                        "name": "lastName",
                        "type": "string",
                        "length": 128
                    }
                ]
            }
        ]
    }
}

EntityType members

Member Type Description
EntityType: Describes the components that make up an Identity Cloud entity type. Entity types are a special kind of database that store Identity Cloud user profiles. Each entity type is based on a schema, a blueprint that specifies the kind of data that can be stored in that entity type. In turn, schemas are composed of attributes, which are functionally equivalent to database fields.
schema EntityType.schema Schema associated with the entity type. Each entity type can have only one schema.
stat String Indicates the current status of the operation.
EntityType.schema: Schema associated with the entity type. Each entity type can have only one schema.
attr_defs EntityType.schema.attr_defs[] JSON-formatted object containing attribute names and datatypes.
name String Attribute definitions (attr_defs) for the entity type schema.
EntityType.schema.attr_defs[]: JSON-formatted object containing attribute names and datatypes.
name String Name of an individual attribute within the entity type schema.
type String Datatype of the individual attribute.

ValidationRule

Creates data validation rules that can be applied to specific attributes in an entity type schema. User data can either be rejected by a data validation rule (for example, an improperly formatted email address) or can even by changed by a data validation rule (for example, truncating input that exceeds the maximum number od characters).

Download schema: entityType-addRule.json

Sample POST response:

{
    "stat": "ok",
    "result": {
        "description": "This is a rule to accept only English letters and have a maximum Length of 25",
        "uuid": "ed23abc2-5023-477d-b728-b4cfdc885f3e",
        "attributes": [
            "/givenName"
        ],
        "definition": {
            "and": [
                {
                    "match-all": "[a-zA-Z]*"
                },
                {
                    "max-length": 25
                }
            ]
        }
    }
}

ValidationRule members

Member Type Description
ValidationRule: Creates data validation rules that can be applied to specific attributes in an entity type schema. User data can either be rejected by a data validation rule (for example, an improperly formatted email address) or can even by changed by a data validation rule (for example, truncating input that exceeds the maximum number od characters).
result ValidationRule.result Properties and property values for the newly created rule.
stat String Indicates the status of the operation.
ValidationRule.result: Properties and property values for the newly created rule.
attributes Array JSON array of the schema attributes that the rule will be applied to. By default, rules apply to all the attributes in the schema.
definition ValidationRule.result.definition JSON-formatted object that defines the data validation rule.
description String Brief description of the validation rule.
uuid String Unique identifier assigned to the rule.
ValidationRule.result.definition: JSON-formatted object that defines the data validation rule.
and ValidationRule.result.definition.and[] Rule properties and property values.
ValidationRule.result.definition.and[]: Rule properties and property values.
match-all String Indicates data cannot be validated unless it matches all the supplied criteria.

Errors

This section provides details on the error responses generated by the Entity and EntityType API.

Error responses

Entity and EntityType API errors are returned as JSON objects similar to the following:

{
    "request_id": "7bfy5j6vmec9w8qv",
    "type_name": "user2",
    "code": 222,
    "error_description": "entity type does not exist: user2",
    "error": "unknown_entity_type",
    "stat": "error"
}

Each error response includes an error code. However, error codes are sometime shared by multiple events. For example, a 200 error code can refer to any of the following errors:

  • Invalid argument when searching for a user account
  • Invalid client ID or client secret
  • Invalid JSON

Note, too that the stat property indicates that the API call failed. If your API call succeeds, you’ll get a similar response. However, a success response will not have an err section and the stat will be set to ok:

{
    "results": [
        "Documentation",
        "Test",
        "consent_purposes",
        "consent_purposes_2",
        "user"
    ],
    "stat": "ok"
}

Entity and EntityType API error responses are summarized in the following table:

Code Description
100 Missing argument. A required parameter was omitted.
200 Invalid argument. An invalid argument was displayed when searching for user profiles.
200 Invalid client ID or client secret. In configuring Basic authentication,either your client ID or client secret was incorrect.
200 JSON error. Your JSON was syntactically invalid.
205 No authentication provided. You must run your command using Basic authentication, with the client ID as the username and the client secret as the password.
222 Unknown entity type. The specified entity type could not be found.

The Entity and EntityType API always generates a 200 HTTP response code, even if the API call fails. Because of that, use the error codes summarized above and the stat property to determine the success or failure of an API call.


Last modified: 8/28/2019