Integration Guide

Sigma Synthetic Fraud API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Sigma Synthetic Fraud enrichment. You’ll learn how to send identity data, parse the response, and apply decision logic to support onboarding, trust and safety, fraud prevention, or compliance workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

A workflow configured for the Sigma Synthetic Fraud enrichment.

Choose your environment

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

Get an API key

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

How it works

Send a POST request to /api/evaluation with identity data.
Socure runs the request through configured RiskOS™ workflow with tailored enrichments.
Receive a decision (ACCEPT, REVIEW, or REJECT) and supporting metadata.
Apply your routing logic based on the result.

Start a new Risk Evaluation

Endpoint

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

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

Authentication and headers

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

Example request

📘
Note:
Do not pass placeholder or dummy values for any of these fields when you are not able to collect them from the end-user. Passing such values will lead to reduced accuracy and can impact future predictions. If you are not able to collect a field value from the consumer, pass null for that field.

{
    "id": "APP-123456",
    "timestamp": "2022-07-28T06:10:54.298Z",
    "workflow": "consumer_onboarding",
    "data":
    {
        "individual":
        {
            "given_name": "Shannon",
            "family_name": "Zhao",
            "national_id": "123456789",
            "date_of_birth": "1958-01-31",
            "email": "[email protected]",
            "phone_number": "+13475551234",
            "address":
            {
                "line_1": "234 Main Street",
                "line_2": "Apt. 3C",
                "locality": "Jersey City",
                "major_admin_division": "NJ",
                "country": "US",
                "postal_code": "07307"
            }
        },
        "ip_address" : "10.10.10.10"
    }
}

curl --location --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
    "id": "APP-123456",
    "timestamp": "2022-07-28T06:10:54.298Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Shannon",
        "family_name": "Zhao",
        "national_id": "123456789",
        "date_of_birth": "1958-01-31",
        "email": "[email protected]",
        "phone_number": "+13475551234",
        "address": {
          "line_1": "234 Main Street",
          "line_2": "Apt. 3C",
          "locality": "Jersey City",
          "major_admin_division": "NJ",
          "country": "US",
          "postal_code": "07307"
        }
      },
      "ip_address": "10.10.10.10"
    }
  }'

Request schema

Top-level fields

📘
Note:
The Sigma Synthetic product makes use of multiple input fields to determine both the score and reason codes. For the highest accuracy and performance all these fields should be collected and passed in the input, however the product will still work when select fields are not provided. The table below lists all input 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.	`"APP-123456"`
`timestamp`	String	Required	RFC 3339 timestamp indicating when the evaluation was initiated.	`"2022-07-28T06:10:54.298Z"`
`workflow`	String	Required	RiskOS™ workflow name configured in your environment.	`"consumer_onboarding"`
`data`	Object	Required	Main payload for the RiskOS™ workflow containing all request details.
→ `individual`	Object	Required	Individual identity object containing personal and address information.	See `individual` schema below.
→ `ip_address`	String	Recommended	IP address from which the consumer is accessing your service.	`"10.10.10.10"`

`individual` fields

Field	Type	Required	Description	Example
`given_name`	String	Required	Consumer’s first name.	`"Shannon"`
`family_name`	String	Required	Consumer’s last name.	`"Zhao"`
`national_id`	String	Optional (Recommended)	Consumer’s nine-digit SSN or ITIN. Hyphens are optional.	`"123456789"`
`date_of_birth`	String	Required If omitted, models may have reduced accuracy.	Consumer’s date of birth in `YYYY-MM-DD`, `YYYY/MM/DD`, or `YYYYMMDD` format.	`"1958-01-31"`
`email`	String	Required if neither `phone_number` nor both `address.line_1` and `address.postal_code` are provided.	Consumer’s email address.	`"[email protected]"`
`phone_number`	String	Required if neither `email` nor both `address.line_1` and `address.postal_code` are provided.	Consumer’s phone number in E.164 format (hyphens optional).	`"+13475551234"`
`address`	Object	Required if neither `email` nor `phone_number` is provided (must include `line_1` and `postal_code`).	Structured address object containing residence details.	See `address` schema below.

`address` fields

Field	Type	Required	Description	Example
`line_1`	String	Required if neither `email` nor `phone_number` is provided and must be accompanied by `postal_code`.	The first line of the consumer’s address.	`"234 Main Street"`
`line_2`	String	Optional (Recommended)	The second line of the address (e.g., apartment, suite, or unit number).	`"Apt. 3C"`
`locality`	String	Optional (Recommended)	The city or locality where the consumer resides.	`"Jersey City"`
`major_admin_division`	String	Optional (Recommended)	The state, province, or region where the consumer resides, in ISO 3166-2 format.	`"NJ"`
`postal_code`	String	Required if neither `email` nor `phone_number` is provided and must be accompanied by `line_1`.	The consumer’s five- or nine-digit ZIP code. Hyphens and spaces are optional.	`"07307"`
`country`	String	Required	The country where the consumer resides, in ISO 3166-1 alpha-2 format.	`"US"`

Example response

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

{
  "id": "APP-123456",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "decision": "ACCEPT",
  "tags": [],
  "review_queues": [],
  // ...
  "data_enrichments": [
    {
      "enrichment_name": "Socure Sigma Synthetic",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        // ...
      },
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "fraud": {
          "reasonCodes": [
            "I610",
            "I621",
            "I912",
            "I622",
            "I554",
            "I568",
            "I212",
            "R217",
            "I557",
            "I709",
            "I208",
            "I559"
          ],
          "scores": [
            {
              "name": "synthetic",
              "version": "4.0",
              "score": 0.684
            }
          ]
        }
      }
    }
  ]
}

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: The fields returned can be customized to fit your integration or business needs.	`"ACCEPT"`
`decision_at`	String `<Date-Time>`	RFC 3339 timestamp when the decision was finalized.	`"2025-09-12T16:42:08.513Z"`
`score`	Number	If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary `decision` value.	`0.94`
`tags`	Array of Strings	Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard.	`[]`
`review_queues`	Array of Strings	Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review.	`[]`
`notes`	String	Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context.	`"Auto-approved after successful verification"`

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)	Indicates the current state of an evaluation or case. Possible values: • `OPEN` • `CLOSED`	`"CLOSED"`
`sub_status`	String	Provides additional detail about the evaluation status. Example values: • `Under Review` • `Pending Verification` • `Accept` • `Reject`	`"Accept"`

Identifiers and traceability

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

Field	Type	Description	Example
`id`	String (UUID or custom string)	Your evaluation identifier within RiskOS™. Note: This is customer-generated.	`"APP-123456"`
`eval_id`	String (UUID)	RiskOS-generated unique identifier for the evaluation.	`"6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816"`
`workflow`	String	Name of the workflow executed.	`"consumer_onboarding"`
`workflow_id`	String (UUID)	Unique identifier for the workflow run.	`"dc7f261e-b158-477e-9770-7e4eae066156"`
`workflow_version`	String	Version of the executed workflow.	`"28.16.0"`

Execution context

These fields provide timing and environment context for the evaluation.

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 for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring.	`"2025-09-30T08:15:30.982Z"`
`eval_end_time`	String `<Date-Time>`	RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with `eval_start_time` to compute total processing time.	`"2025-09-30T08:15:31.215Z"`
`environment_name`	String	Indicates which environment the evaluation ran in. Typically `Sandbox` for testing or `Production` for live traffic.	`"Sandbox"`

Enrichment results

Enrichment outputs are returned in the data_enrichments array.

Field	Type	Description	Example
`enrichment_name`	String	Name of the enrichment service used in the evaluation.	`"Socure Sigma Synthetic"`
`enrichment_endpoint`	String (URL)	Endpoint URL where the enrichment request was made.	`"https://service.socure.com` `/api/3.0/EmailAuthScore"`
`enrichment_provider`	String	Provider or source of the enrichment data.	`"Socure"`
`status_code`	Integer	HTTP response code returned from the enrichment API call.	`200`
`request`	Object	Request payload sent to the enrichment endpoint.	See `request` schema below.
`response`	Object	Response payload returned from the enrichment endpoint.	See `response` schema below.

`request` fields

Field	Type	Description	Example
`country`	String	Country code in ISO 3166-1 alpha-2 format (e.g., `US`, `CA`, `GB`).	`"US"`
`firstName`	String	Consumer’s given name (first name).	`"Shannon"`
`surName`	String	Consumer’s family name (last name).	`"Zhao"`
`nationalId`	String	Government-issued identifier (e.g., SSN in the U.S. or national ID in other countries).	`"123456789"`
`dob`	String (YYYY-MM-DD)	Consumer’s date of birth in `YYYY-MM-DD` format.	`"1958-01-31"`
`streetAddress`	String	Street address line of the consumer’s residence.	`"234 Main Street"`
`city`	String	City of the consumer’s residence.	`"Jersey City"`
`state`	String	State, province, or region of the consumer’s residence.	`"NJ"`
`zip`	String	Postal or ZIP code of the consumer’s residence.	`"07307"`
`ipAddress`	String	IP address (IPv4 or IPv6) observed during the consumer’s session.	`"10.10.10.10"`
`phone`	String	Consumer’s phone number in E.164 format (e.g., `+13475550100`).	`"+13475551234"`
`email`	String	Consumer’s email address.	`"[email protected]"`

`response` fields

Field	Type	Description	Example
`referenceId`	String (UUID)	Unique identifier assigned to each enrichment after a RiskOS™ workflow is finalized.	`"f3863a33-69ca-43c2-90e0-8b4344a41a09"`
`fraud`	Object	Fraud assessment results returned by the enrichment service.	See `fraud` schema below.

`fraud` fields

Field	Type	Description	Example
`reasonCodes`	Array of Strings	List of reason codes explaining contributing risk signals.	`["I610", "I621", "I912", "I622", "I554", "I568", "I212", "R217", "I557", "I709", "I208", "I559"]`
`scores`	Array of Objects	Scoring models and confidence scores returned by the provider.	See `scores` schema below.

`scores` fields

Field	Type	Description	Example
`name`	String	Name of the scoring model used.	`"synthetic"`
`version`	String	Version of the scoring model.	`"4.0"`
`score`	Number	Confidence score between 0.0 and 1.0.	`0.684`

Sigma Synthetic Fraud API integration guide

Before you start

Choose your environment

Get an API key

How it works

Start a new Risk Evaluation

Endpoint

Authentication and headers

Example request

Request schema

Top-level fields

individual fields

address fields

Example response

Key response fields

Where to find specific results

Decision and routing (primary control signals)

Evaluation lifecycle and status

Identifiers and traceability

Execution context

Enrichment results

request fields

response fields

fraud fields

scores fields

`individual` fields

`address` fields

`request` fields

`response` fields

`fraud` fields

`scores` fields