This page defines canonical terminology for RiskOS™ platform concepts. Use these terms consistently across conceptual documentation, tutorials, API references, and operational guides. ## Core platform terms | Preferred term | Avoid | Why | |----------------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Evaluation** | transaction, request, submission, event | "Evaluation" is the canonical RiskOS™ runtime entity. "Transaction" implies financial scope. "Request" conflates the API call with the processing. | | **Decision** | result, outcome, response, verdict | "Decision" is the specific field in the API response. "Result" is ambiguous (could mean the full response). | | **Workflow** | flow, pipeline, process, logic | "Workflow" is the RiskOS™ entity name. "Flow" is too generic and conflicts with Hosted Flow. | | **Enrichment** | product, module, service, data source | "Enrichment" is the canonical term in the workflow context. "Product" is acceptable as a synonym in marketing contexts only. | | **Signal** | variable, field, data point, metric | "Signal" specifically means enrichment-returned or computed data used in decisioning. "Variable" implies mutability. | | **Attribute** | input, parameter, field | "Attribute" specifically means an input data point from the evaluation request. "Field" is acceptable in API reference contexts. | | **Reason code** | reason, code, explanation | Always use the full compound "reason code." | | **Tag** | label, marker, flag | "Tag" is the RiskOS™ entity name. "Flag" implies boolean-only. | | **Derived value** | computed field, calculated value, output | "Derived value" distinguishes workflow-computed data from enrichment signals. | | **Case** | ticket, record, item | "Case" is the RiskOS™ entity in Case Management. | | **Hosted Flow** | hosted experience, Socure UX, flow | "Hosted Flow" or "Socure Hosted UX" are the canonical names. Never shorten to "flow" alone. | | **Step** | node, block, component, action | "Step" is the RiskOS™ term for workflow building blocks. | ## Status and lifecycle terms | Preferred term | Avoid | Context | |----------------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Status** | state (when referring to case lifecycle) | Use "status" for case lifecycle: Open, On Hold, Closed. "In Review", "Escalated", etc. are sub-statuses. | | **State** | status (when referring to evaluation runtime) | Use "state" for evaluation runtime: `evaluation_in_progress`, `evaluation_paused`, `evaluation_completed` | | **Lifecycle** | flow, progression | Use "lifecycle" for the full sequence of state/status transitions | | **Paused** | waiting, on hold (for evaluations) | Use "paused" for evaluation runtime. "On Hold" is a case status. Don't confuse with evaluation paused state. | ## Decision value formatting Always format decision values as uppercase code when referring to the API field value: | Correct | Avoid | |----------------------|------------------------------------------| | `ACCEPT` | Accept, accepted, Accepted | | `REJECT` | Reject, rejected, Rejected | | `REVIEW` | Review, review (when referring to the decision value) | `RESUBMIT` and `CANCEL` are Decision Rules step-level configuration values, not standard API decision values. Format them as code when referring to the step configuration. In prose describing the concept (not the API value), use sentence case: "The reviewer accepted the case." ## Workflow delivery terms | Preferred term | Definition | Avoid | |----------------------|----------------------------------------------------|-------------------------------------------| | **Custom workflow** | A workflow built and managed by the customer in the Workflow Editor | Standard workflow, manual workflow, API workflow | | **Hosted Flow** | A preconfigured workflow with a Socure-managed UI | Hosted workflow, managed workflow, Socure flow | | **Workflow Editor** | The visual workflow builder in the RiskOS™ Dashboard | Workflow Builder, Workflow Canvas, workflow designer | ## Enrichment and data terms | Preferred term | Avoid | When to use | |----------------------|------------------------------------------|-------------------------------------------------------------------| | **Enrichment step** | enrichment node, enrichment call | Referring to the workflow step type | | **Data service** | data source, API, provider | Referring to the external service an enrichment calls | | **Enrichment response**| enrichment result, enrichment output | Referring to the data returned by an enrichment | | **`data_enrichments`**| enrichments array, enrichment data | Referring to the specific API response field (always use backticks) | ## Integration terms | Preferred term | Avoid | When to use | |----------------------|------------------------------------------|-------------------------------------------------------------------| | **Evaluation API** | RiskOS™ API, evaluation endpoint | Referring to `POST /api/evaluation` | | **Sandbox** | test environment, staging, dev | Referring to the non-production RiskOS™ environment | | **Production** | live environment, prod | Referring to the production RiskOS™ environment | | **Webhook** | callback, notification, event push | Referring to RiskOS™ HTTPS POST notifications | | **SDK key** | API key (when referring to client-side credentials) | The client-side credential for mobile/web SDKs | | **API key** | secret key, auth key, bearer token | The server-side credential for API authentication | ## Usage in different content types | Content type | Terminology register | Example | |---------------------|-------------------------------------------|------------------------------------------------------| | **Conceptual** | Formal — use full canonical terms, define on first use | "An **evaluation** is a single execution of a workflow." | | **Tutorial** | Practical — use canonical terms without re-defining | "Send a `POST` request to trigger an evaluation." | | **Reference** | Precise — use exact API field names in backticks | "The `decision` field contains `ACCEPT`, `REJECT`, or `REVIEW`." | | **Operational** | Direct — use canonical terms, no definitions needed | "Check the evaluation status in the webhook payload." | ## Related concepts - [Evaluations](https://help.socure.com/riskos/docs/understanding-riskos#evaluations) — Canonical definition of the evaluation entity - [Workflows](https://help.socure.com/riskos/docs/understanding-riskos#workflows) — Canonical definition including workflow categories - [Decisions](https://help.socure.com/riskos/docs/understanding-riskos#decisions) — Canonical decision values and formatting - [Signals & Attributes](https://help.socure.com/riskos/docs/understanding-riskos#signals--attributes) — Data taxonomy with canonical term definitions - [Statuses & Lifecycle](https://help.socure.com/riskos/docs/statuses-and-lifecycle) — Status vs state distinction - [Integrating with RiskOS™](https://help.socure.com/riskos/docs/integrating-with-riskos) — Put these concepts into practice and send your first evaluation Updated 16 days ago