Overview

The LoginRadius Cloud Directory offers a powerful, centralized platform for managing and retrieving user identity data. It is designed to support scalable identity management through two key APIs:

User Identity API: Retrieve individual user profile data.
Aggregation API: Access aggregated data insights for the entire user base.

Organizations can leverage the Cloud Directory to analyze how user data is stored and managed, ensuring seamless identity recognition across their digital ecosystem.

Running Cloud Directory API

You need to be informed of the following information to run the cloud Directory API.

Base URL
Formatting your Identity Queries
Rules & Groups
Example Query
Example Rule

The following is the Base URL for all API requests:

https://cloud-api.loginradius.com/identity

Consider the following when running Rules & Groups:

The query object must contain at least one group or be {}, which retrieves all data based on the From and To values.
Each group can include one or more rules and subgroups.
Groups use an AND or OR operator with an array of rules or subgroups. However, an operator is not required for a single rule.
Each rule must specify a field name, an operator, and a value based on the field type.

Here is an example Query

"group": {
  "operator": "AND",
  "rules": [<rule>, <rule>, <group>]
}

Here is an example Rule

{
  "name": <Field Name>,
  "operator": <Supported operator by field type>,
  "value": <valid value based on field type>
}

Supported Types and Corresponding Operators/Values

The following are the different types of operators based on the type and corresponding values they can have

Supported Operators: >, >=, <, <=, BETWEEN, =, !=
Supported Values: It should be an integer as per the integer type.
Example: 1, 10, -1, 0
There should be a valid date for the date type.
Example: 2017-01-01

Supported Operators: =, !=
Supported Values: It should be a valid string.
The string search is case-sensitive.

Supported Operators: =, !=
Supported Values: true or false

Supported Operator: Contains, Not_Contains
Supported Values: Text

Supported Operators: EXISTS, NOT_EXISTS

Supported Keys and their Types

Refer to the Detailed Data Points table for a comprehensive list of LoginRadius profile fields, subfields, and their data types. This information ensures you select the appropriate operator when querying Cloud Directory APIs.

Querying Basic Fields

Here are a few examples of querying basic fields:

Query for searching user databases where the age is greater than 20

{
  "name": "Age",
  "operator": ">",
  "value": 20
}

Query for searching user databases where the age is between 20 & 50(Inclusive)

{
  "name": "Age",
  "operator": "BETWEEN",
  "value": [20, 50]
}

Note for Array of Strings/Integers: Querying a field that contains an array of strings will return the document if the array includes the specified value. For example, if a document has a "Roles" field with values ['Admin', 'Developer', 'QA'], a query for Roles = Admin or Roles = Developer will return the document. However, a query for Roles = Business will not return it.

Note for Range Fields: For the BETWEEN operator, the value should be an array. The first value will be used as FROM, and the second value will be used as TO. The values are inclusive. Example "value": [20, 50] translates to value being in between of 20 & 50(inclusive). The range is inclusive.

Querying NULL Values

To check for non-null values in a field, use the EXISTS operator:

{
  "name": "Gender",
  "operator": "EXISTS"
}

This rule returns documents where the Gender field has a non-null value.

Examples of non-null values:

{ "Gender": "," }
{ "Gender": "Male" }
{ "Gender": "" } // An empty string is considered non-null
{ "Gender": ["Male"] }
{ "Gender": ["Male", null] }

To check for null values, use the NOT_EXISTS operator:

{
  "name": "Gender",
  "operator": "NOT_EXISTS"
}

This rule returns documents where the Gender field is null or does not exist.

Examples of null values:

{ "Gender": null }
{ "Gender": [] }
{ "Gender": [null] }
{ "Gender1": "bar" } // The Gender field is missing

Querying Text

When searching text fields, values are analyzed using individual terms. Consider the following dataset with FirstName values:

Case	FirstName	Analyzed Terms
1	i am identity api	i, am, identity, api
2	i AM insights API	i, am, insights, api
3	i am@insights api's	i, am, insights, api's
4	i-am-customobject-api	i, am, customobject, api
5	i-customobject-am-api	i, am, customobject, api

Matching Rules
Matches all (1, 2, 3, 4, 5):

{
  "name": "FirstName",
  "operator": "Contains",
  "value": "am"
}
{
  "name": "FirstName",
  "operator": "Contains",
  "value": "AM"
}

Matches (1, 2, 4, 5):

{
  "name": "FirstName",
  "operator": "Contains",
  "value": "api"
}
{
  "name": "FirstName",
  "operator": "Contains",
  "value": "API"
}

Matches only (3):

{
  "name": "FirstName",
  "operator": "Contains",
  "value": "API's"
}

Matches all (1, 2, 3, 4, 5):

{
  "name": "FirstName",
  "operator": "Contains",
  "value": "am-customobject"
}

Here, "am-customobject" is split into "am" and "customobject", and since "am" exists in all entries, all five documents are returned.

Filtering Specific Results
To retrieve only case 3 & 4, combine multiple rules using AND:

"group": {
  "operator": "AND",
  "rules": [
    {
      "name": "FirstName",
      "operator": "=",
      "value": "am"
    },
    {
      "name": "FirstName",
      "operator": "=",
      "value": "customobject"
    }
  ]
}

This ensures that only documents containing both terms are matched.

Querying Dates

Date fields can be queried by passing a valid ISO8601 date value
Special Case: BirthDate supports MM-DD-YYYY format as well.

Searching user databases where the birthdate is 19th March 2019

{
            "name" : "BirthDate",
            "operator" : "=",
            "value" : "03-19-2019"
}

Searching user databases where the profiles are created after 05th March 2001

{
            "name" : "CreatedDate",
            "operator" : ">",
            "value" : "2001-03-05T18:30:00Z"
}

Querying Objects

You can access object fields using dot notation. Here's an example of an object field:

"SignupLog": {
  "UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0.",
  "Host": "example.com",
  "IP": "123.13.123.123"
}

To query nested fields, use dot notation:

Example Query:

{
  "name": "SignupLog.Host",
  "operator": "=",
  "value": "example.com"
}

Note: Ensure the sub-field type is correct before querying.

Querying an Array of Objects

You can use dot notation to query fields within an array of objects. The query will match if at least one object in the array satisfies the condition.

Example: Email Array in the user profile

"Email": [
  {
    "Type": "Primary",
    "Value": "[email protected]"
  },
  {
    "Type": "Secondary",
    "Value": "[email protected]"
  }
]

Query to match an email:

{
  "name": "Email.Value",
  "operator": "=",
  "value": "[email protected]"
}

Note: Ensure the sub-field type is correct before querying.

Example: Querying Positions

If a Position field is stored as text or a string, it supports both "=" and "Contains" operators:

{
  "name": "Positions.Position",
  "operator": "=",
  "value": "Developer"
}

{
  "name": "Positions.Position",
  "operator": "Contains",
  "value": "Developer"
}

Combining Rules into a Group

A group can contain one or more rules and sub-groups, each with an AND or OR operator applied.

Group Structure:

"group": {
    "operator": "AND",
    "rules": [<rule>, <rule>, <sub-group>]
}

Example: Nested Group Query

The following query retrieves users who:

Have EmailVerified = true
Have a Provider of either Google or Facebook

"group": {
    "operator": "AND",
    "rules": [
      {
        "name": "EmailVerified",
        "operator": "=",
        "value": true
      },
      {
        "group": {
          "operator": "OR",
          "rules": [
            {
              "name": "Provider",
              "operator": "=",
              "value": "Google"
            },
            {
              "name": "Provider",
              "operator": "=",
              "value": "Facebook"
            }
          ]
        }
      }
    ]
}

Example: Filtering Users by Date Range

Retrieve all users created between 2016-01-01 and 2016-12-31, ensuring from and to values are specified:

{
    "from": "2016-01-01",
    "to": "2016-12-31",
    "q": {
        "group": {
            "operator": "AND",
            "rules": [
              {
                "name": "EmailVerified",
                "operator": "=",
                "value": true
              },
              {
                "group": {
                  "operator": "OR",
                  "rules": [
                    {
                      "name": "Provider",
                      "operator": "=",
                      "value": "Google"
                    },
                    {
                      "name": "Provider",
                      "operator": "=",
                      "value": "Facebook"
                    }
                  ]
                }
              }
            ]
        }
    }
}

Use Case 1: Fetch Email Profiles Without a Registration Source

Retrieve email-based profiles that do not contain a RegistrationSource field:

{
  "group": {
    "operator": "AND",
    "rules": [
      {
        "name": "RegistrationSource",
        "operator": "NOT_EXISTS",
        "value": null
      },
      {
        "name": "Provider",
        "operator": "=",
        "value": "Email"
      }
    ]
  }
}

Result: Only email profiles that do not have a RegistrationSource are returned.

Use Case 2: Fetch Recently Updated Profiles

Retrieve profiles where the ModifiedDate is later than 2021-08-09T18:47:26Z:

{
  "group": {
    "operator": "AND",
    "rules": [
      {
        "name": "Provider",
        "operator": "=",
        "value": "Email"
      },
      {
        "name": "ModifiedDate",
        "operator": ">",
        "value": "2021-08-09T18:47:26Z"
      }
    ]
  }
}

Result: Returns profiles filtered based on the last modified date.