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.

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:

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, transaction decisions and agent integration guidance.