# Read customer risk Use these read-only endpoints to explain a customer's risk or find customers who need attention. They do not buy checks, enrol customers, publish rules or release transfers. Customer risk and the risk of one transaction are different contexts. ## Availability This is a **SHADOW preview**, disabled by default. Myaza must enable the read capability for the environment; current scores additionally need a reviewed customer-risk configuration and qualified evidence. An API key alone does not activate it. Existing verification, workflow and transaction decisions are unchanged. Use a secret key on your backend. The key supplies the organisation and environment; do not send either in query parameters. Dashboard readers also need risk-read and individual- or business-read permission for the selected customer type. ## Choose a read All paths below start at your environment's `/api/v1` base URL. | Task | GET path | |---|---| | Current customer risk and its supporting evidence | `/risk-intelligence/customers/{entityId}/risk` | | Immutable assessment history | `/risk-intelligence/customers/{entityId}/risk/history` | | One exact historical assessment | `/risk-intelligence/customers/{entityId}/risk/snapshots/{snapshotId}` | | Filter by current risk | `/risk-intelligence/customers/risk-cohort?basis=CURRENT&subjectType=INDIVIDUAL` | | Filter by the latest retained assessment | `/risk-intelligence/customers/risk-cohort?subjectType=INDIVIDUAL` | Use `subjectType=BUSINESS` for business customers. Omitting `basis` deliberately selects historical, as-assessed results, not a fallback when current risk fails. In Dashboard, open **Customer assessments** and choose **Current** or **As assessed**. ## Filter risk and monitoring together For example, find currently high-risk individuals with active daily monitoring: ```bash curl --get "$MYAZA_API_URL/risk-intelligence/customers/risk-cohort" \ --header "Authorization: Bearer $MYAZA_SECRET_KEY" \ --data-urlencode 'basis=CURRENT' \ --data-urlencode 'subjectType=INDIVIDUAL' \ --data-urlencode 'includeMonitoring=true' \ --data-urlencode 'monitoringState=ACTIVE' \ --data-urlencode 'monitoringFrequency=DAILY' \ --data-urlencode 'level=HIGH' \ --data-urlencode 'pageSize=25' ``` Set `MYAZA_API_URL` to your environment's base URL including `/api/v1`. Keep `MYAZA_SECRET_KEY` in your backend secret store; never paste it into a browser. Monitoring inclusion requires Continuous Monitoring access and, for Dashboard sessions, `monitoring_subscriptions:read`. It is optional and valid only with `basis=CURRENT`. The same filtered population supplies customer rows, totals and risk-band counts; do not combine separate risk and monitoring pages yourself. Supported monitoring states are `ACTIVE`, `PAUSED`, `ENDED` and `NOT_ENROLLED`. Cadence is `HOURLY`, `DAILY`, `WEEKLY` or `MONTHLY`, including a customer override. `monitoringPolicyId` narrows by the latest subscription's policy. A null row-level `monitoring` means confirmed non-enrolment; missing or unavailable proof returns 503 for the combined read, never `NOT_ENROLLED`. Other filters are `level`, `assessmentState`, `status`, `disposition` and `search`. Search covers names and customer references, not encrypted government ID numbers. Use the returned `nextCursor` fields together and retain the same filters. Each page is a new observation, not a frozen export. The maximum page size is 100. ## Display the result safely - A numeric current headline requires `assessment.state=CURRENT` (or `current.assessmentState=CURRENT` on the single-customer endpoint). Read its score and level together. A null score is not zero. - A valid zero is Low. The versioned bands are Low 0–24, Medium 25–49, High 50–79 and Critical 80–100. The index is not a probability of fraud. - `PENDING`, `STALE`, `INCOMPLETE`, `UNAVAILABLE` and other non-current states must not show a retained number as current. Historical evidence remains a separate, explicitly as-assessed view when available. - Reconcile the selected assessment using its snapshot reference, retained factors and coverage. Contextual connections are not automatically score contributors. Do not add their values to the score again. - Refresh rows and totals together at `nextTransitionAt`, on return to the view and at least every 30 seconds. Off-page evidence may expire sooner than the visible rows. - With monitoring included, `monitoringObservation` has an independent clock. Compute its `nextTransitionAt - observedAt` duration separately from Core's duration. Use the shorter window, subtract the entire request time and measure the remaining display time monotonically. Never compare the two wall clocks. - Once that window expires, hide the current rows and totals until a valid refresh succeeds. Do not retain an old Low result during an outage. Responses are `no-store`. Invalid filters return 400; denied access returns 403; disabled preview or unavailable evidence returns 503. Unknown or inaccessible single customers return 404. These states do not authorise a transaction. ## Trace an assessment's evidence In **Risk evidence**, use **Why this score**, **Connections** and **History** for the same selected assessment. Connections offers a source map and an accessible list, with bounded pages and filters for contributions or supporting evidence. Open a finding for its retained observation time and source assessment or signal reference. Historical views never fetch today's findings to fill missing evidence. Solid connections represent retained point allocations. Supporting context adds no points; a minimum-risk adjustment comes from the model, not another check. Filtering or paging changes only what is visible, never the recorded total. The map is assessment lineage, not a live network of wallet owners or customers. Excluded or erased observations do not create invented edges. If a response's score and retained contributions conflict, the view stays unavailable. ## Integration acceptance Test individual and business reads, a real zero, unassessed customers, combined filters, cursor totals, expired evidence, missing monitoring proof, denied roles, another organisation/environment and delayed responses after a workspace switch. Reads must not create checks, charges or notifications. Compare an exact snapshot between the customer endpoint, cohort and history; do not compare independently observed live results as though time had stopped. Continue with [continuous monitoring](https://trust.myaza.co/documentation/monitoring-policies/markdown), [transaction decisions](https://trust.myaza.co/documentation/monitoring-events/markdown) and [agent integration guidance](https://trust.myaza.co/documentation/ai-integration/markdown).