API Specifications and Resources

Integrating RiskOS™ draws on four resources. Each answers a different question, and you move between them as you build: the documentation teaches concepts and steps, two complementary API specifications define the request and response contracts, and test cases let you validate against known outcomes before you go live.

Two of these resources are API specifications, and new integrators often expect a single one. They coexist on purpose because they describe different layers of the same evaluation:

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

You need the Evaluation API to run a workflow at all. You need the Enrichment API Reference as soon as you consume enrichment data — for example Document Verification, Phone Risk, or Watchlist results — because those request and response fields live only in the second specification.

The four integration resources

Documentation

The documentation on this site is where you start. It explains the concepts behind an evaluation — workflows, enrichments, solutions, decisions, and reason codes — and provides an end-to-end Solutions Overview plus the integration guides that follow.

Use the documentation to:

• Learn how RiskOS™ evaluates a request and returns a decision.
• Follow a guided integration path for your solution or enrichment.
• Find conceptual context that the API specifications alone don't provide.

Integration guides

Each guide walks you through integrating one solution or enrichment end to end — environment setup, workflow configuration, API requests, and best practices. The two API specifications that follow are the precise contracts these guides point to when you need exact field-level detail.

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 > Enrichment API Reference.

Test cases

Test cases are predefined Sandbox scenarios with known expected outcomes. Because Sandbox returns predefined results rather than running full production models, a test case lets you send a known input and confirm your integration reads the resulting decision, reason codes, and enrichment data correctly — before you handle live traffic.

Use test cases to:

• Validate that your integration handles ACCEPT, REJECT, and REVIEW decisions correctly.
• Confirm you parse reason codes and the data_enrichments array as expected.
• Exercise edge cases and specific enrichment outcomes without production data.

How the resources fit together

The two API 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.

The other two resources wrap around this contract: the documentation explains the concepts and steps before you write code, and test cases confirm your integration reads the contract correctly once you have. A typical integration moves through all four — read the guides, build against the two specifications, then validate with test cases in Sandbox.

Which resource to use

Related

• Solutions Overview — the pre-built solutions you can integrate with RiskOS™.
• 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.
• Test Workflows — validate workflows against historical cases or custom payloads in Sandbox.
• Webhooks — receive results for asynchronous checks.