Query Engine · Evaluate

Evaluate a query against the authenticated user’s credentials. This endpoint allows declarative queries to check user claims.

POST /queries/evaluate

Evaluate a query against the authenticated user's credentials

cURL

curl --request POST \
  --url https://api.sandbox.humanity.org/v2/queries/evaluate \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": {
    "check": {
      "claim": "<string>",
      "operator": "==",
      "value": "<unknown>"
    }
  }
}
'

200

{
  "type": "predicate",
  "passed": true,
  "evaluatedAt": "<string>",
  "evidence": {
    "claimsUsed": [
      {
        "path": "<string>",
        "value": "<unknown>",
        "credentialId": "<string>",
        "source": "<string>"
      }
    ],
    "checkResults": [
      {
        "claim": "<string>",
        "operator": "<string>",
        "expectedValue": "<unknown>",
        "actualValue": "<unknown>",
        "passed": true
      }
    ]
  },
  "expiresAt": "<string>"
}

SDK equivalent

// Predicate query (boolean check)
const result = await sdk.evaluateQuery({
  accessToken: token.accessToken,
  query: {
    check: { claim: 'identity.age', operator: '>=', value: 18 }
  }
});

// Projection query (data extraction)
const data = await sdk.evaluateQuery({
  accessToken: token.accessToken,
  query: {
    projections: [{ claim: 'identity.email', lens: 'pluck' }]
  }
});

The Query Engine allows declarative queries against user credentials. Use it for access control, eligibility checks, or data extraction without hardcoding preset names.

Query Types

Predicate Queries (Boolean Checks)

Return true or false based on credential values.

{
  "query": {
    "check": {
      "claim": "identity.age",
      "operator": ">=",
      "value": 18
    }
  }
}

Available Operators:

Operator	Description	Example
==	Equals	{ "claim": "kyc.passed", "operator": "==", "value": true }
!=	Not equals	{ "claim": "identity.country", "operator": "!=", "value": "US" }
>	Greater than	{ "claim": "financial.net_worth", "operator": ">", "value": 100000 }
>=	Greater than or equal	{ "claim": "identity.age", "operator": ">=", "value": 21 }
<	Less than	{ "claim": "identity.age", "operator": "<", "value": 65 }
<=	Less than or equal	{ "claim": "financial.loan_balance", "operator": "<=", "value": 50000 }
in	Value in array	{ "claim": "identity.country", "operator": "in", "value": ["US", "CA", "UK"] }
notIn	Value not in array	{ "claim": "identity.country", "operator": "notIn", "value": ["RU", "CN"] }
contains	Array contains value	{ "claim": "identity.social_accounts", "operator": "contains", "value": "github" }
isDefined	Claim exists	{ "claim": "kyc.document_number", "operator": "isDefined" }
startsWith	String prefix	{ "claim": "identity.email", "operator": "startsWith", "value": "admin@" }
matchRegex	Regex match	{ "claim": "identity.phone", "operator": "matchRegex", "value": "^\\+1" }

Compound Policies

Combine multiple checks with logical operators:

{
  "query": {
    "policy": {
      "allOf": [
        { "check": { "claim": "identity.age", "operator": ">=", "value": 21 } },
        { "check": { "claim": "identity.country", "operator": "==", "value": "US" } }
      ]
    }
  }
}

Logical Operators:

Operator	Description
allOf	AND - all conditions must pass
anyOf	OR - at least one condition must pass
not	NOT - negate the result

Nested Example:

{
  "query": {
    "policy": {
      "allOf": [
        { "check": { "claim": "kyc.passed", "operator": "==", "value": true } },
        {
          "policy": {
            "anyOf": [
              { "check": { "claim": "financial.net_worth", "operator": ">=", "value": 1000000 } },
              { "check": { "claim": "financial.income", "operator": ">=", "value": 200000 } }
            ]
          }
        }
      ]
    }
  }
}

Projection Queries (Data Extraction)

Extract values from credentials:

{
  "query": {
    "projections": [
      { "claim": "identity.email", "lens": "pluck" },
      { "claim": "identity.country", "lens": "pluck" }
    ]
  }
}

Lens Operators:

Lens	Description
pluck	Extract single value at path
pick	Extract subset of object fields
at	Array index access

Response Types

Predicate Response

{
  "type": "predicate",
  "passed": true,
  "evaluatedAt": "2026-01-16T12:00:00.000Z",
  "evidence": {
    "claimsUsed": [
      { "path": "identity.age", "value": 25, "credentialId": "cred_123" }
    ],
    "checkResults": [
      {
        "claim": "identity.age",
        "operator": ">=",
        "expectedValue": 18,
        "actualValue": 25,
        "passed": true
      }
    ]
  },
  "expiresAt": "2026-02-16T12:00:00.000Z"
}

Projection Response

{
  "type": "projection",
  "data": {
    "identity.email": "[e-mail]",
    "identity.country": "US"
  },
  "evaluatedAt": "2026-01-16T12:00:00.000Z",
  "claimsUsed": [
    { "path": "identity.email", "value": "[e-mail]" },
    { "path": "identity.country", "value": "US" }
  ],
  "expiresAt": "2026-02-16T12:00:00.000Z"
}

Claim Paths

Claims are accessed using dot-notation paths based on credential categories:

Category	Example Claims
identity	identity.age, identity.email, identity.country_of_residence
kyc	kyc.passed, kyc.document_country, kyc.last_updated_at
financial	financial.net_worth, financial.bank_balance, financial.loan_balance

Scope Requirements

Query evaluation respects OAuth scopes. You can only query claims covered by the granted scopes. For example:

• identity:read - Access to basic identity claims
• identity:date_of_birth - Access to age-related claims
• financial:net_worth - Access to net worth data

See the Scopes documentation for the full scope model.

Body

application/json

The query to evaluate

Request body for query evaluation.

query · object · required

The query to evaluate. Can be a simple check or compound policy.

Option 1

Option 2

Option 3

Show child attributes

Response

200 - application/json

Query evaluation result

Option 1

Option 2

Response from predicate query evaluation.

type · any · required

passed · boolean · required

Whether the query passed.

evaluatedAt · string · required

Timestamp when the query was evaluated.

evidence · object · required

Evidence collected during evaluation.

Show child attributes

expiresAt · string

Earliest credential expiry date (if any).