Integration Guide

Overview

This guide shows you how to:

Send a POST /api/evaluation request using the payment_screening workflow
Interpret the response and decision (ACCEPT, REVIEW, REJECT)
Use enrichment data for routing, review, and compliance workflows

Before you start

Make sure your RiskOS™ environment is provisioned with:

A workflow configured for the Payment Screening solution.

Verified global support coverage for the Payment Screening solution.

Quickstart

Endpoint

Start with Sandbox for development and testing, then move to Production for live applications.

https://riskos.sandbox.socure.com/api/evaluation

No real customer data
Free testing environment
Unlimited API calls

Authentication

In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.
Copy your API key securely.

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

Minimum example request

{
  "id": "txn-123",
  "timestamp": "2026-02-11T18:22:31Z",
  "workflow": "payment_screening",
  "data": {
    "transaction_type": "transfer",
    "source": {
      "type": "INDIVIDUAL",
      "individual": {
        "given_name": "Jane",
        "family_name": "Smith",
        "address": { "country": "US" }
      }
    },
    "destination": {
      "type": "INDIVIDUAL",
      "individual": {
        "given_name": "John",
        "family_name": "Doe",
        "address": { "country": "MX" }
      }
    }
  }
}

curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "id": "txn-123",
  "timestamp": "2026-02-11T18:22:31Z",
  "workflow": "payment_screening",
  "data": {
    "transaction_type": "transfer",
    "source": {
      "type": "INDIVIDUAL",
      "individual": {
        "given_name": "Jane",
        "family_name": "Smith",
        "address": {
          "country": "US"
        }
      }
    },
    "destination": {
      "type": "INDIVIDUAL",
      "individual": {
        "given_name": "John",
        "family_name": "Doe",
        "address": {
          "country": "MX"
        }
      }
    }
  }
}'

Decision handling

Decision	Action
`ACCEPT`	Allow the payment
`REVIEW`	Hold or route to manual review
`REJECT`	Block the payment

What matters for your integration

Category	Fields	How to use
Required to send	`id`, `timestamp`, `workflow`, `data`	Minimum fields required to submit a valid request
Required to act on	`decision`	Primary field used to determine application behavior
Required to store	`eval_id`	Persist for traceability, debugging, and support
Optional but useful	`tags`, `review_queues`, `notes`	Use for routing, review flows, and internal context
Diagnostic only	`data_enrichments`, `status`, `sub_status`	Use for debugging and analysis only — not for business decisions

Integration contract

endpoint: POST /api/evaluation
workflow: payment_screening

authentication:
  type: Bearer token
  header: Authorization

content_type: application/json

required_top_level_fields:
  - id
  - timestamp
  - workflow
  - data

primary_decision_field: decision

important_response_fields:
  - decision
  - eval_id
  - tags
  - review_queues

traceability_fields:
  - id
  - eval_id

do_not_use_for_primary_decision:
  - status
  - sub_status

How the workflow evaluates a transaction

After you submit an evaluation request, RiskOS™ evaluates the transaction across sanctions screening, entity risk, and compliance checks. Based on your workflow configuration, the transaction may be accepted, rejected, or routed to manual review.

Typical stages include:

Entity normalization Normalize sender and beneficiary data (name, address, instrument) for consistent screening.
Watchlist screening Screen source and destination entities against global watchlists (for example: OFAC, sanctions lists, PEPs).
Instrument screening Evaluate associated payment instruments such as:
- Bank accounts (for example: SWIFT/BIC)
- Crypto addresses
Match evaluation Assess match confidence, correlation scores, and supporting signals to determine risk severity.
Compliance routing Apply tags, notes, and routing logic to determine the final outcome.

flowchart TD
    A[Submit transaction] --> B[Normalize entities]
    B --> C[Watchlist screening]
    C -->|Confirmed match| R[REJECT]
    C -->|Potential match| RV[REVIEW]
    C -->|No match| AC[ACCEPT]

Request schema

The example below shows a common Payment Screening request with transaction amount, sender, beneficiary, and payment instrument details.

Example request

{
  "id": "txn-123456",
  "timestamp": "2026-02-11T18:22:31Z",
  "workflow": "payment_screening",
  "data": {
    "transaction_type": "transfer",
    "transaction_amount": {
      "source": {
        "amount": 6000,
        "currency": "USD"
      },
      "destination": {
        "amount": 90109,
        "currency": "BTC"
      }
    },
    "transaction_details": {
      "memo": "Rent July",
      "statement_descriptor": "XYZ Services"
    },
    "source": {
      "type": "INDIVIDUAL",
      "individual": {
        "given_name": "Jane",
        "family_name": "Smith",
        "date_of_birth": "1990-05-15",
        "address": {
          "country": "US"
        },
        "instrument": {
          "type": "BANK_ACCOUNT",
          "account": {
            "swift_bic": "CHASUS33",
            "institution_name": "Chase"
          }
        }
      }
    },
    "destination": {
      "type": "INDIVIDUAL",
      "individual": {
        "given_name": "John",
        "family_name": "Doe",
        "address": {
          "country": "MX"
        },
        "instrument": {
          "type": "CRYPTO_ADDRESS",
          "crypto_address": {
            "currency": "BTC",
            "network": "bitcoin",
            "address": "18uKfaUjgG52rVeXEi3wxnveww7zZuECtE"
          }
        }
      }
    }
  }
}

curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "id": "txn-123456",
  "timestamp": "2026-02-11T18:22:31Z",
  "workflow": "payment_screening",
  "data": {
    "transaction_type": "transfer",
    "transaction_amount": {
      "source": {
        "amount": 6000,
        "currency": "USD"
      },
      "destination": {
        "amount": 90109,
        "currency": "BTC"
      }
    },
    "transaction_details": {
      "memo": "Rent July",
      "statement_descriptor": "XYZ Services"
    },
    "source": {
      "type": "INDIVIDUAL",
      "individual": {
        "given_name": "Jane",
        "family_name": "Smith",
        "date_of_birth": "1990-05-15",
        "address": {
          "country": "US"
        },
        "instrument": {
          "type": "BANK_ACCOUNT",
          "account": {
            "swift_bic": "CHASUS33",
            "institution_name": "Chase"
          }
        }
      }
    },
    "destination": {
      "type": "INDIVIDUAL",
      "individual": {
        "given_name": "John",
        "family_name": "Doe",
        "address": {
          "country": "MX"
        },
        "instrument": {
          "type": "CRYPTO_ADDRESS",
          "crypto_address": {
            "currency": "BTC",
            "network": "bitcoin",
            "address": "18uKfaUjgG52rVeXEi3wxnveww7zZuECtE"
          }
        }
      }
    }
  }
}'

Request structure overview

id
timestamp
workflow
data
├─ transaction_type
├─ direction
├─ transaction_details
├─ transaction_amount
│  ├─ source (amount, currency)
│  └─ destination (amount, currency)
├─ source
│  ├─ type
│  ├─ individual | business
│  └─ instrument
└─ destination
   ├─ type
   ├─ individual | business
   └─ instrument

Conditional field requirements

The following fields depend on entity type and instrument type.

Entity type requirements

data.source.individual is required when data.source.type = "INDIVIDUAL".
data.source.business is required when data.source.type = "BUSINESS".
data.destination.individual is required when data.destination.type = "INDIVIDUAL".
data.destination.business is required when data.destination.type = "BUSINESS".

Instrument type requirements

instrument.account is required when instrument.type = "BANK_ACCOUNT".
instrument.crypto_address is required when instrument.type = "CRYPTO_ADDRESS".

Additional request guidance

Include transaction_amount to provide payment value and currency context.
Include transaction_details to provide memo or statement descriptor context.

Validation rules

id must be unique per evaluation request.
timestamp must be a valid RFC 3339 timestamp.
Enum values must match supported values exactly.

Field reference

Top-level fields

Field	Type	Required	Description	Example
`id`	String	Required	Required, customer-defined unique identifier for the request. This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows.	`"123456"`
`timestamp`	String `<Date-Time>`	Required	RFC 3339 timestamp indicating when the evaluation request was initiated by your system.	`"2022-07-28T06:10:54.298Z"`
`workflow`	String	Required	Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > Developer Workbench > Integration Checklist.	`"payment_screening"`
`data`	Object	Required	Container for the transaction payload.	See `data` fields below.

`data` fields

Field	Type	Required	Description	Example
`transaction_type`	String (enum)	Required	Single-select transaction type.	`"transfer"`
`direction`	String (enum)	Optional	Direction of the transaction.	`"credit"`
`transaction_details`	Object	Optional	Transaction detail fields.	See `transaction_details` fields below.
`transaction_amount`	Object	Optional	Source and destination amount details.	See `transaction_amount` fields below.
`source`	Object	Required	Source party information.	See `source` fields below.
`destination`	Object	Required	Destination party information.	See `destination` fields below.

`data.transaction_details` fields

Field	Type	Required	Description	Example
`memo`	String	Optional	Short transaction description.	`"Rent July"`
`statement_descriptor`	String	Optional	Descriptor that may appear on statements.	`"XYZ Services"`

`data.source` fields

Field	Type	Required	Description	Example
`type`	String (enum)	Required	Entity type of sender. Values: `"INDIVIDUAL"`, `"BUSINESS"`	`"INDIVIDUAL"`
`channel`	String (enum)	Optional	Consumer interaction channel (for example: `web`, `mobile`, `pos`).	`"mobile"`
`line_of_business`	String	Optional	Line of business associated with the request.	`"crypto_exchange"`
`ip_address`	String	Optional	IPv4 or IPv6 address associated with the source.	`"203.0.113.10"`
`individual`	Object	Conditional	Source individual details. Required when `type = "INDIVIDUAL"`.	See `individual` fields below.
`business`	Object	Conditional	Source business details. Required when `type = "BUSINESS"`.	See `business` fields below.
`external_device`	Object	Optional	External device data associated with the request.	See `external_device` fields below.

`data.source.individual` fields

Field	Type	Required	Description	Example
`id`	String	Optional	Unique internal identifier for the consumer.	`"ind-9876543"`
`given_name`	String	Conditional	Consumer's given name. Required when `type = "INDIVIDUAL"`.	`"Jane"`
`family_name`	String	Conditional	Consumer's family name. Required when `type = "INDIVIDUAL"`.	`"Smith"`
`suffix`	String	Optional	Name suffix, if applicable.	`"JR."`
`national_id`	String	Optional	Consumer’s national identification number.	`"123456789"`
`date_of_birth`	Date	Optional	Date of birth in `YYYY-MM-DD` format.	`"1990-05-15"`
`email`	String	Optional	Consumer’s primary email address.	`"[email protected]"`
`alternate_email`	String	Optional	Consumer’s alternate email address.	`"[email protected]"`
`phone_number`	String	Optional	Consumer’s phone number in E.164 format.	`"+1-312-555-1234"`
`alternate_phone_number`	String	Optional	Consumer’s alternate phone number.	`"+1-555-202-0147"`
`gender`	String (enum)	Optional	Consumer’s gender. Values: `Male`, `Female`, `Self Identify`.	`"Female"`
`address`	Object	Optional	Consumer address details.	See `address` fields below.
`instrument`	Object	Optional	Financial instrument details.	See `instrument` fields below.
`additional_context`	Object	Optional	Additional context and metadata.	See `additional_context` fields below.
`di_session_token`	String	Optional	Device intelligence session token.	`"eyJ0eXAiOiJK..."`

`data.source.individual.address` fields

Field	Type	Required	Description	Example
`line_1`	String	Optional	Street address line 1 (number and street name).	`"742 Evergreen Terrace"`
`line_2`	String	Optional	Additional address details (apartment, suite, etc.).	`"Apt 12B"`
`locality`	String	Optional	City, town, or locality.	`"Springfield"`
`minor_admin_division`	String	Optional	Minor administrative division (for example, district).	`"districtname"`
`major_admin_division`	String	Optional	Major administrative division (for example, state).	`"IL"`
`country`	String	Optional	Country in ISO 3166-1 alpha-2 format.	`"US"`
`postal_code`	String	Optional	Postal or ZIP code.	`"62704"`
`type`	String	Optional	Address type (for example, `HOME`, `WORK`).	`"HOME"`

`data.source.individual.instrument` fields

Field	Type	Required	Description	Example
`type`	String (enum)	Optional	Financial instrument type. Values: `"BANK_ACCOUNT"`, `"CRYPTO_ADDRESS"`.	`"BANK_ACCOUNT"`
`account`	Object	Conditional	Bank account details. Required when `type = "BANK_ACCOUNT"`.	See `account` fields below.
`crypto_address`	Object	Conditional	Crypto address details. Required when `type = "CRYPTO_ADDRESS"`.	See `crypto_address` fields below.

`data.source.individual.instrument.account` fields

Field	Type	Required	Description	Example
`id`	String	Optional	Client-provided unique account identifier.	`"78456158930"`
`type`	String (enum)	Optional	Bank account type.	`"CHECKING"`
`account_number`	String	Optional	Bank account number.	`"12345678901"`
`routing_number`	String	Optional	Routing number associated with the account.	`"122199983"`
`swift_bic`	String	Optional	SWIFT/BIC code.	`"CH-123"`
`iban`	String	Optional	International Bank Account Number (IBAN).	`"FR14 2004..."`
`opened_at`	String (ISO 8601)	Optional	Account open date and time in ISO 8601 format.	`"2022-05-26T05:02:09.985Z"`
`institution_name`	String	Optional	Financial institution name.	`"Chase"`
`country_code`	String	Optional	Country code of the account in ISO 3166-1 alpha-2 format.	`"US"`
`account_inquiries`	Array[String]	Optional	Types of account inquiries requested.	`["AVAILABILITY"]`
`institution_address`	Object	Optional	Financial institution address details. See fields below.	See `institution_address` fields below.
`account_snapshot`	Object	Optional	Account snapshot details. See fields below.	See `account_snapshot` fields below.

`data.source.individual.instrument.account.institution_address` fields

Field	Type	Required	Description	Example
`line_1`	String	Optional	Street address line 1 (number and street name).	`"200 Key Square St"`
`line_2`	String	Optional	Additional address details (apartment, suite, etc.).	`"New York"`
`locality`	String	Optional	City, town, or locality.	`"New York City"`
`minor_admin_division`	String	Optional	Minor administrative division (for example, district or borough).	`"Brooklyn"`
`major_admin_division`	String	Optional	Major administrative division (for example, state or province).	`"NY"`
`country`	String	Optional	Country in ISO 3166-1 alpha-2 format.	`"US"`
`postal_code`	String	Optional	Postal or ZIP code.	`"12345"`
`type`	String	Optional	Address type (for example, `HOME`, `WORK`).	`"HOME"`

`data.source.individual.instrument.account.account_snapshot` fields

Field	Type	Required	Description	Example
`timestamp`	String (ISO 8601)	Optional	Timestamp when the snapshot was taken.	`"2022-09-01T12:34:56.789Z"`
`account_view`	Object	Optional	Account balance and activity at snapshot time.	See `account_view` fields below.

`data.source.individual.instrument.account.account_snapshot.account_view` fields

Field	Type	Required	Description	Example
`available_balance`	Object	Optional	Available balance at snapshot time.	See `balance` fields below.
`current_balance`	Object	Optional	Current balance at snapshot time.	See `balance` fields below.
`last_activity_at`	Date-Time	Optional	Timestamp of the most recent account activity.	`"2022-03-21T21:50:07.623Z"`

`data.source.individual.instrument.account.account_snapshot.account_view.balance` fields

The available_balance and current_balance objects share the same structure.

Field	Type	Required	Description	Example
`amount`	Number	Optional	Monetary value of the balance.	`120000`
`currency`	String	Optional	Currency code in ISO 4217 format (for example, `USD`).	`"USD"`

`data.source.individual.instrument.crypto_address` fields

Field	Type	Required	Description	Example
`currency`	String (enum)	Optional	Crypto asset code. See supported values below.	`"XBT"`
`network`	String (enum)	Optional	Blockchain network name. See supported values below.	`"bitcoin"`
`address`	String	Optional	Wallet address.	`"18uKfa..."`

Supported `currency` values

Value	Name
`BTC`	Bitcoin
`XBT`	Bitcoin (ISO 4217)
`ETH`	Ethereum
`USDT`	Tether
`XMR`	Monero
`ZEC`	Zcash
`DASH`	Dash
`XRP`	Ripple
`LTC`	Litecoin
`BCH`	Bitcoin Cash
`TRX`	TRON
`ETC`	Ethereum Classic
`BNB`	Binance Coin
`SOL`	Solana

Supported `network` values

Value	Network Name
`bitcoin`	Bitcoin
`ethereum`	Ethereum
`tron`	Tron
`solana`	Solana
`bnb_chain`	BNB Chain
`polygon`	Polygon PoS
`avalanche_c_chain`	Avalanche C-Chain
`ethereum_classic`	Ethereum Classic
`xrp_ledger`	XRP Ledger
`monero`	Monero
`zcash`	Zcash
`dash`	Dash
`litecoin`	Litecoin
`bitcoin_cash`	Bitcoin Cash

`data.source.individual.additional_context` fields

Field	Type	Required	Description	Example
`user_consent`	Boolean	Optional	Indicates whether the consumer has provided consent.	`true`
`consent_timestamp`	Date-Time	Optional	Timestamp when consent was provided.	`"2020-09-13T23:11:12.000Z"`
`previous_reference_id`	String	Optional	Reference ID of a previous Socure transaction.	`"e9c170..."`
`user_name`	String	Optional	Username associated with the consumer.	`"johnsmith1979"`
`disclosure_purpose`	String (enum)	Optional	Disclosure purpose. Must be set to `GLBA_502(e)`.	`"GLBA_502(e)"`
`entity_type`	String	Optional	Entity type associated with the request.	`"individual"`
`entity_name`	String	Optional	Full name of the entity.	`"Jane Smith"`
`accept_list`	Boolean	Optional	Indicates whether the entity is on an accepted list.	`true`
`notes`	String	Optional	Additional notes about known risks or prior review.	`"Was reviewed and approved"`
`driver_license`	String	Optional	Driver’s license number.	`"000000000"`
`driver_license_state`	String	Optional	State or region that issued the driver’s license.	`"NY"`

`data.source.business` fields

Field	Type	Required	Description	Example
`id`	String	Optional	Unique identifier for the business entity.	`"029659c7-733e-444b-9d19-7d119c035bc6"`
`name`	String	Conditional	Legal business name. Required when `type = "BUSINESS"`.	`"Tech Innovators LLC"`
`primary_phone`	String	Optional	Business phone number in E.164 format.	`"+1-800-555-6789"`
`ein`	String	Optional	Employer Identification Number (EIN).	`"12-3456789"`
`website_url`	String	Optional	Business website URL.	`"https://techinnovators.com"`
`address`	Object	Optional	Business address details. See `address` fields below.	`{ ... }`
`instrument`	Object	Optional	Financial instrument details. See `instrument` fields below.	`{ ... }`
`formation`	Object	Optional	Business formation details. See `formation` fields below.	`{ ... }`

`data.source.external_device` fields

Field	Type	Required	Description	Example
`id`	String	Optional	Unique identifier for the device.	`"9876543"`
`session`	String	Optional	Session identifier associated with the device interaction.	`"567h89e293r8h3"`
`fingerprint`	String	Optional	Device fingerprint identifier used for risk analysis.	`"9823rh23hr9r23"`
`fingerprint_provider`	String	Optional	Provider or source of the fingerprint.	`"internal"`
`user_agent`	String	Optional	Full user agent string from the device or browser.	`"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."`
`device_type`	String	Optional	Device category.	`"Mobile"`
`is_known`	Boolean	Optional	Indicates whether the device has been previously observed.	`true`
`first_seen_time`	String (ISO 8601)	Optional	Timestamp when the device was first observed.	`"2022-07-28T06:10:54.298Z"`
`last_seen_time`	String (ISO 8601)	Optional	Timestamp when the device was most recently observed.	`"2022-07-28T06:10:54.298Z"`
`timezone_mismatch`	Boolean	Optional	Indicates whether the device timezone differs from expected location.	`false`
`ip_address`	String	Optional	IP address observed for the device session.	`"127.0.0.1"`
`is_ip_bad_proxy`	Boolean	Optional	Indicates whether the IP is associated with a known bad proxy.	`false`
`is_ip_proxy`	Boolean	Optional	Indicates whether the IP is identified as a proxy.	`false`
`ip_risk_score`	Number	Optional	Risk score assigned to the IP address.	`52.5`
`ip_isp`	String	Optional	Internet service provider associated with the IP address.	`"XYZ Communications"`
`ip_country_code`	String	Optional	Country code derived from the IP address.	`"US"`
`ip_city`	String	Optional	City derived from IP geolocation.	`"New York"`
`ip_region`	String	Optional	Region or state derived from IP geolocation.	`"NY"`
`is_ip_tor`	Boolean	Optional	Indicates whether the IP is associated with the Tor network.	`false`
`is_emulator`	Boolean	Optional	Indicates whether the device appears to be an emulator.	`false`

Interpret the response

When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results produced by your Payment Screening workflow.

Example response

{
  "id": "28340239423",
  "workflow": "payment_screening",
  "workflow_id": "7b5b3d61-2b9a-4f8a-9c11-1f3b2f4e9a12",
  "workflow_version": "1.0.0",
  "eval_source": "API",
  "eval_id": "9d2b0c1e-1b6a-4e1a-8b2f-7f5c8a3d1e22",
  "eval_start_time": "2026-02-11T18:22:31Z",
  "eval_end_time": "2026-02-11T18:22:40.835789195Z",
  "decision": "REVIEW",
  "decision_at": "2026-02-11T18:22:40.835789195Z",
  "status": "OPEN",
  "sub_status": "In Review",
  "tags": [
    "Sanctions Hit"
  ],
  "notes": "Watchlist: Screening Alert Found for payment parties and rails",
  "review_queues": [
    "Sanctions Review"
  ],
  "environment_name": "Production",
  "timestamp": "2026-02-11T18:22:31Z",
  "data": {
    "individual": {
      "given_name": "Vladimir",
      "family_name": "Putin",
      "address": {
        "country": "US"
      },
      "account": {},
      "docv": {
        "config": {
          "language": null,
          "send_message": null
        }
      },
      "additional_context": {
        "user_consent": null
      }
    },
    "channel": "api"
  },
  "case_history": [
    {
      "id": "28340239423",
      "case_event_id": "1a215979-70d1-4cb0-9803-3565d521d871",
      "event_name": "CaseCreated",
      "review_case_id": "9d2b0c1e-1b6a-4e1a-8b2f-7f5c8a3d1e22",
      "updated_at": "2026-02-11T18:22:40.837100045Z",
      "status": "OPEN",
      "sub_status": "In Review",
      "sub_status_id": "ff92efab-ac7d-4598-b05b-63b82fc95daf",
      "sub_status_color": "#65C769",
      "updated_tags": [
        "Sanctions Hit"
      ]
    },
    {
      "id": "28340239423",
      "case_event_id": "a3aa7ec5-a5e1-482a-a9e1-10e94d7ddad5",
      "event_name": "Notes Added",
      "review_case_id": "9d2b0c1e-1b6a-4e1a-8b2f-7f5c8a3d1e22",
      "reviewer_id": "UPDATED_THROUGH_SYSTEM",
      "updated_at": "2026-02-11T18:22:41.047332674Z",
      "notes": "Watchlist: Screening Alert Found for payment parties and rails"
    }
  ],
  "workflow_decision": "REVIEW",
  "data_enrichments": [
    {
      "enrichment_name": "Watchlist - Source Individual Screening",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "country": "US",
        "firstName": "Vladimir",
        "modules": [
          "watchlistpremier"
        ],
        "parentTxnId": "9d2b0c1e-1b6a-4e1a-8b2f-7f5c8a3d1e22",
        "riskOSId": "28340239423",
        "surName": "Putin",
        "workflow": "payment_screening"
      },
      "response": {
        "globalWatchlist": {
          "matches": {
            "OFAC SDN List": [
              {
                "comments": {
                  "address": [""],
                  "aka": [""],
                  "countries": [""],
                  "dateOfBirth": [""],
                  "entityType": [""],
                  "gender": [""],
                  "listName": [""],
                  "listingId": [""],
                  "name": [""],
                  "program": [""],
                  "sourceCode": [""],
                  "url": [""]
                },
                "entityCorrelationScore": 0,
                "entityId": "",
                "matchFields": [""],
                "matchScore": 0,
                "sourceUrls": [""]
              }
            ]
          },
          "reasonCodes": [""]
        },
        "referenceId": "ref-sender-name-5e6a3934"
      },
      "is_source_cache": false,
      "total_attempts": 1
    },
    {
      "enrichment_name": "Watchlist - Source Account Screening",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "country": "US",
        "bankname": "Chase",
        "modules": [
          "watchlistpremier"
        ],
        "parentTxnId": "9d2b0c1e-1b6a-4e1a-8b2f-7f5c8a3d1e22",
        "riskOSId": "28340239423",
        "swift_bic": "SWIFT:CHASUS33",
        "workflow": "payment_screening"
      },
      "response": {
        "globalWatchlist": {
          "matches": {
            "OFAC SDN List": [
              {
                "comments": {
                  "address": [""],
                  "aka": [""],
                  "countries": [""],
                  "dateOfBirth": [""],
                  "entityType": [""],
                  "gender": [""],
                  "listName": [""],
                  "listingId": [""],
                  "name": [""],
                  "program": [""],
                  "sourceCode": [""],
                  "url": [""]
                },
                "entityCorrelationScore": 0,
                "entityId": "",
                "matchFields": [""],
                "matchScore": 0,
                "sourceUrls": [""]
              }
            ]
          },
          "reasonCodes": [""]
        },
        "referenceId": "ref-sender-acct-19af2c11"
      },
      "is_source_cache": false,
      "total_attempts": 1
    },
    {
      "enrichment_name": "Watchlist - Destination Individual Screening",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "country": "US",
        "firstName": "Vladimir",
        "modules": [
          "watchlistpremier"
        ],
        "parentTxnId": "9d2b0c1e-1b6a-4e1a-8b2f-7f5c8a3d1e22",
        "riskOSId": "28340239423",
        "surName": "Putin",
        "workflow": "payment_screening"
      },
      "response": {
        "globalWatchlist": {
          "matches": {
            "OFAC SDN List": [
              {
                "comments": {
                  "address": [""],
                  "aka": [""],
                  "countries": [""],
                  "dateOfBirth": [""],
                  "entityType": [""],
                  "gender": [""],
                  "listName": [""],
                  "listingId": [""],
                  "name": [""],
                  "program": [""],
                  "sourceCode": [""],
                  "url": [""]
                },
                "entityCorrelationScore": 0,
                "entityId": "",
                "matchFields": [""],
                "matchScore": 0,
                "sourceUrls": [""]
              }
            ]
          },
          "reasonCodes": [""]
        },
        "referenceId": "ref-beneficiary-name-83bb01d2"
      },
      "is_source_cache": false,
      "total_attempts": 1
    },
    {
      "enrichment_name": "Watchlist - Destination Crypto Address Screening",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "country": "US",
        "currency": "Digital Currency Address - XBT",
        "modules": [
          "watchlistpremier"
        ],
        "parentTxnId": "9d2b0c1e-1b6a-4e1a-8b2f-7f5c8a3d1e22",
        "riskOSId": "28340239423",
        "crypto_address": "18uKfaUjgG52rVeXEi3wxnveww7zZuECtE",
        "workflow": "payment_screening"
      },
      "response": {
        "globalWatchlist": {
          "matches": {
            "OFAC SDN List": [
              {
                "comments": {
                  "address": [""],
                  "aka": [""],
                  "countries": [""],
                  "dateOfBirth": [""],
                  "entityType": [""],
                  "gender": [""],
                  "listName": [""],
                  "listingId": [""],
                  "name": [""],
                  "program": [""],
                  "sourceCode": [""],
                  "url": [""]
                },
                "entityCorrelationScore": 0,
                "entityId": "",
                "matchFields": [""],
                "matchScore": 0,
                "sourceUrls": [""]
              }
            ]
          },
          "reasonCodes": [""]
        },
        "referenceId": "ref-beneficiary-crypto-2a1c9e77"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "eval_status": "evaluation_completed"
}

Key response fields

RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, along with enrichment-specific results that depend on your workflow configuration.

Where to find specific results

Area	Fields	How to use it
Decision and routing	`decision`, `decision_at`, `tags`, `review_queues`, `notes`, `score`	Primary control signals. Branch application logic using `decision`. Use tags, queues, notes, and score for secondary routing, review, and explanation.
Module results	Module-specific fields (for example: `reasonCodes`, scores, extracted attributes)	Evidence and signals produced by workflow modules. Use for escalation, compliance review, investigation, and audit.
Identifiers and traceability	`id`, `eval_id`	Persist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases.
Enrichment execution	`data_enrichments[]` (`response`, `status_code`, `total_attempts`, `is_source_cache`)	Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses.
Workflow context	`workflow`, `workflow_id`, `workflow_version`	Understand which workflow ran and which version produced the result. Useful for debugging and historical analysis.
Evaluation lifecycle	`eval_status`, `status`, `sub_status`	Execution and case state only. Useful for monitoring and asynchronous workflows. Do not use for business decisions.
Execution context	`eval_source`, `eval_start_time`, `eval_end_time`, `environment_name`	Observability and performance metadata for latency tracking, environment validation, and API vs Dashboard attribution.

Decision and routing (primary control signals)

Use these fields to determine what action your application should take.

decision values are workflow-specific and may differ from the examples shown in this guide.

Field	Type	Description	Example
`decision`	String (enum)	Final evaluation result. Possible values: • `ACCEPT` • `REVIEW` • `REJECT` Note: Values depend on your workflow configuration.	`"REVIEW"`
`decision_at`	String `<Date-Time>`	RFC 3339 timestamp when the decision was finalized.	`"2026-02-11T18:22:40.835789195Z"`
`score`	Number	If configured, provides an aggregate risk score from the workflow.	(Not returned in this example)
`tags`	Array of Strings	Labels applied during the workflow to highlight notable signals or routing decisions.	`["Sanctions Hit"]`
`review_queues`	Array of Strings	Manual review queues the evaluation was routed to.	`["Sanctions Review"]`
`notes`	String	Additional context or explanation for the decision.	`"Watchlist: Screening Alert Found for payment parties and rails"`

Evaluation lifecycle and status

These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

Field	Type	Description	Example
`eval_status`	String (enum)	Indicates the current state of an evaluation in RiskOS™. Possible values: • `evaluation_completed` • `evaluation_paused` • `evaluation_in_progress`	`"evaluation_completed"`
`status`	String (enum)	Case-level status of the evaluation. Possible values: • `OPEN` • `CLOSED`	`"OPEN"`
`sub_status`	String	Provides additional detail about the evaluation status. Example values depend on workflow configuration.	`"In Review"`

Identifiers and traceability

Use these fields to correlate requests, logs, webhooks, and support cases.

Field	Type	Description	Example
`id`	String (UUID or custom string)	Customer-defined evaluation identifier. Used for request tracking and idempotency.	`"28340239423"`
`eval_id`	String (UUID)	RiskOS™-generated unique identifier for the evaluation.	`"9d2b0c1e-1b6a-4e1a-8b2f-7f5c8a3d1e22"`
`workflow`	String	Name of the workflow executed.	`"payment_screening"`
`workflow_id`	String (UUID)	Unique identifier for the workflow execution.	`"7b5b3d61-2b9a-4f8a-9c11-1f3b2f4e9a12"`
`workflow_version`	String	Version of the executed workflow.	`"1.0.0"`

Execution context

These fields provide timing and environment context for monitoring and debugging.

Field	Type	Description	Example
`eval_source`	String (enum)	Indicates where the evaluation was initiated from. Possible values: • `API`: Request submitted via the Evaluation API • `Dashboard`: Case created or evaluated through the RiskOS™ Dashboard	`"API"`
`eval_start_time`	String `<Date-Time>`	RFC 3339 timestamp when RiskOS™ started processing.	`"2026-02-11T18:22:31Z"`
`eval_end_time`	String `<Date-Time>`	RFC 3339 timestamp when processing finished.	`"2026-02-11T18:22:40.835789195Z"`
`environment_name`	String	Environment where the evaluation was executed. Typically `Sandbox` or `Production`.	`"Production"`

Enrichment results

Enrichment outputs are returned in the data_enrichments array.

Field	Type	Description	Example
`enrichment_name`	String	Display name for the enrichment or module executed.	`"Watchlist - Source Individual Screening"`
`enrichment_endpoint`	String	Endpoint that processed the enrichment request.	`"https://service.socure.com/api/3.0/EmailAuthScore"`
`enrichment_provider`	String	Provider name (Socure, vendor, or internal service).	`"Socure"`
`status_code`	Integer	HTTP status code returned by the enrichment call.	`200`
`request`	Object	Request payload sent to the enrichment service.	See `request` fields below.
`response`	Object	Normalized response returned by the enrichment service.	See `response` fields below.
`is_source_cache`	Boolean	Indicates whether cached data was used instead of a live call.	`false`
`total_attempts`	Integer	Number of attempts made to retrieve enrichment data.	`1`

Example `request` fields (varies by enrichment)

Field	Type	Description	Example
`phoneNumber`	String	Phone number submitted for verification or lookup.	`"+1-312-555-1234"`
`modules`	Array[String]	Data modules or services requested.	`["watchlistpremier"]`
`deviceSessionId`	String (UUID)	Session identifier for device intelligence requests.	`"7b3c2c04-0e7e-46e4-afe8-b905cdf91833"`
`customerUserId`	String	Your internal user identifier for the request.	`"129"`
`userId`	String	Normalized user identifier used for enrichment.	`"dwanyedever1975"`

Example `response` fields (varies by enrichment)

Response fields for Payment Screening enrichments will vary by which entity you are screening (individual, business, account, crypto_address), and which watchlists you are screening against.

View a breakdown of response fields by watchlist type in the Watchlist product integration guide.

Best practices for integration and maintenance

Validate request payloads against the schema before sending.
Use sandbox test identities for QA and automation.
Monitor decision, tags, and review_queues for routing and escalation.
Capture and persist eval_id and referenceId for traceability.

Validation checklist

Test coverage

Allowed payments → ACCEPT

Flagged payments → REVIEW

Blocked payments → REJECT

Edge cases tested and reviewed

Schema + error handling

Request fields match schema across environments

Errors are structured, descriptive, and retryable

Retry logic uses exponential backoff with jitter

Logging + observability

Log full request/response including eval_id

Include correlation IDs for traceability

Redact sensitive data (for example: national ID, account numbers, secrets)