OpenAPI Specifications

RiskOS™ documents its API surface in two complementary specifications. Each one describes a different layer of an evaluation, and you use them together during integration.

The two specifications

Evaluation API

The Evaluation API is the primary RiskOS™ API. It exposes a single endpoint, POST /evaluation, that accepts applicant data, runs your configured workflow, and returns an ACCEPT, REJECT, or REVIEW decision along with reason codes and enrichment results.

Use this specification to:

• Authenticate and send your first evaluation request.
• Understand the top-level request envelope and response schema.
• Read the final decision, reason codes, and the data_enrichments array.
• Handle webhooks for asynchronous, longer-running checks.

Where to find it:

• API Reference — the browsable reference on the RiskOS™ documentation site.
• OpenAPI Specification — the machine-readable spec for client SDK generation and request validation.

Enrichment API Reference

The Enrichment API Reference documents each enrichment (also called a product) individually — the fields you can include in that enrichment's request and the fields it returns in its response. Because your available enrichments depend on your account configuration, this reference is rendered live inside the RiskOS™ Dashboard rather than on the public documentation site.

Use this specification to:

• Look up the exact request and response schema for a specific enrichment, such as Document Verification, Phone Risk, Email Risk, or Watchlist.
• Interpret the request and response objects nested in each data_enrichments entry of an evaluation response.
• Confirm which fields a given enrichment expects before you configure it in a workflow.

Where to find it:

To open the Enrichment API Reference:

1. Sign in to the RiskOS™ Dashboard.
2. Go to Documentation in the navigation menu.
3. Select Enrichment API Reference.

How the two specifications fit together

The two specifications describe different layers of the same evaluation:

• The Evaluation API documents the outer request and response — the envelope you send and the decision you receive.
• The Enrichment API Reference documents the contents of each enrichment call nested inside that response.

Every evaluation response includes a data_enrichments array. Each entry represents one enrichment call and contains a request object (what RiskOS™ sent to the enrichment) and a response object (what the enrichment returned):

{
  "data_enrichments": [
    {
      "enrichment_name": "phoneRisk",
      "enrichment_provider": "Socure",
      "request": {  },
      "response": {  }
    }
  ]
}

The Evaluation API reference tells you that data_enrichments exists and describes its wrapper fields. The Enrichment API Reference tells you what the request and response objects inside each entry contain for a specific enrichment.

Which specification to use

Related

• Enrichments Overview — how enrichments add signals to an evaluation and appear in the response.
• API Reference — the complete Evaluation API specification.
• OpenAPI Specification — the machine-readable Evaluation API spec.
• Webhooks — receive results for asynchronous checks.