Skip to main content

Recipe: Compliance Search

This recipe shows how to search completed (historical) instances for compliance and audit investigations.

Goal​

Find all completed loan-application instances in Q1 2026 where the applicant's document ID matches a specific value.

Query​

POST /v1/instances/search

{
  "definitionKey": "loan-application",
  "statusScope": "completed",
  "filter": {
    "variables.applicant.documentId": "12345678900",
    "endedAt": {
      "$gte": "2026-01-01T00:00:00Z",
      "$lt":  "2026-04-01T00:00:00Z"
    }
  },
  "sort": { "endedAt": -1 },
  "projection": {
    "variables.applicant.documentId": 1,
    "variables.loan_status": 1,
    "variables.amount": 1,
    "startedAt": 1,
    "endedAt": 1,
    "correlationId": 1
  },
  "page": { "limit": 200 }
}

Response​

{
  "results": [
    {
      "instanceId": "inst_xyz789",
      "definitionKey": "loan-application",
      "status": "completed",
      "startedAt": "2026-02-10T09:00:00Z",
      "endedAt": "2026-02-12T14:30:00Z",
      "correlationId": "loan-2026-0317",
      "variables": {
        "applicant": { "documentId": "12345678900" },
        "loan_status": "approved",
        "amount": 45000
      }
    }
  ],
  "nextCursor": null,
  "stats": {
    "returned": 3,
    "limit": 200,
    "scanMode": "Index Scan"
  }
}

nextCursor: null means all matching results fit in one page.

Best practices​

  • Always include a date range on startedAt or endedAt when querying statusScope: "completed" — it bounds the scan to a manageable window and improves performance.
  • Use correlationId when available — it is your stable external reference (e.g., a loan application number) and is always indexed, making it the fastest lookup key.
  • Combine with text search for narrative fields. To find matches in free-text notes alongside structured filters, add a text block:
{
  "statusScope": "completed",
  "filter": {
    "endedAt": { "$gte": "2026-01-01T00:00:00Z", "$lt": "2026-04-01T00:00:00Z" }
  },
  "text": {
    "query": "fraude confirmada",
    "mode": "fulltext",
    "fields": ["variables.notes", "variables.review_comments"]
  }
}

See Text Search for details.