Skip to main content
POST
/
queries
/
evaluate
Evaluate a query against the authenticated user's credentials
curl --request POST \
  --url https://api.sandbox.humanity.org/v2/queries/evaluate \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": {
    "check": {
      "claim": "<string>",
      "operator": "<unknown>",
      "value": "<unknown>"
    }
  }
}
'
{
  "type": "<unknown>",
  "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:
OperatorDescriptionExample
==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 }
inValue in array{ "claim": "identity.country", "operator": "in", "value": ["US", "CA", "UK"] }
notInValue not in array{ "claim": "identity.country", "operator": "notIn", "value": ["RU", "CN"] }
containsArray contains value{ "claim": "identity.social_accounts", "operator": "contains", "value": "github" }
isDefinedClaim exists{ "claim": "kyc.document_number", "operator": "isDefined" }
startsWithString prefix{ "claim": "identity.email", "operator": "startsWith", "value": "admin@" }
matchRegexRegex 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:
OperatorDescription
allOfAND - all conditions must pass
anyOfOR - at least one condition must pass
notNOT - 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:
LensDescription
pluckExtract single value at path
pickExtract subset of object fields
atArray 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": "user@example.com",
    "identity.country": "US"
  },
  "evaluatedAt": "2026-01-16T12:00:00.000Z",
  "claimsUsed": [
    { "path": "identity.email", "value": "user@example.com" },
    { "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:
CategoryExample Claims
identityidentity.age, identity.email, identity.country_of_residence
kyckyc.passed, kyc.document_country, kyc.last_updated_at
financialfinancial.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.

Response

200 - application/json

Query evaluation result

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.

​
expiresAt
string

Earliest credential expiry date (if any).