For AI agents: visit https://help.socure.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI. ## Before you start [Skip link to Before you start](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#before-you-start) Make sure your RiskOS™ environment is provisioned with: [A workflow configured](https://help.socure.com/riskos/docs/sigma-first-party-fraud-riskos-setup) for the **Sigma First-Party Fraud** enrichment. ### Choose your environment [Skip link to Choose your environment](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#choose-your-environment) Start with **Sandbox** for development and testing, then move to **Production** for live applications. ```undefined https://riskos.sandbox.socure.com/api/evaluation ``` - **No real customer data** - **Free testing environment** - **Unlimited API calls** ```undefined https://riskos.socure.com/api/evaluation ``` - **Real customer data** - **API usage charges apply** - **Connects to live data services** ### Get an API key [Skip link to Get an API key](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#get-an-api-key) 1. In the Sandbox RiskOS™ Dashboard, go to [**Developer Workbench > API Keys**](https://riskos.sandbox.socure.com/developers/api-keys). 2. Copy your API key securely. 1. In the Production RiskOS™ Dashboard, go to [**Developer Workbench > API Keys**](https://riskos.socure.com/developers/api-keys). 2. Copy your API key securely ## How it works [Skip link to How it works](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#how-it-works) 1. Send a `POST` request to `/api/evaluation` with consumer identity data. 2. RiskOS™ runs the request through a configured workflow including the **First-Party Fraud enrichment**. 3. Receive a decision (`ACCEPT`, `REVIEW`, or `REJECT`) with: - Fraud risk score(s) - Reason codes - Risk signals 4. Apply your routing logic based on the result. * * * ## Start a new Risk Evaluation [Skip link to Start a new Risk Evaluation](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#start-a-new-risk-evaluation) ### Endpoint [Skip link to Endpoint](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#endpoint) SandboxProduction ```http POST https://riskos.sandbox.socure.com/api/evaluation ``` ```http POST https://riskos.socure.com/api/evaluation ``` ### Authentication and headers [Skip link to Authentication and headers](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#authentication-and-headers) Include your API key in the `Authorization` header as a **Bearer token**, along with standard JSON headers: HTTP ```http 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 [Skip link to Example request](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#example-request) JSONcURL ```json { "id": "Ananda_FPF-1761662048692", "timestamp": "2025-05-18T02:09:25Z", "workflow": "api_individual_onboarding", "data": { "line_of_business": "test1", "channel": "mobile", "individual": { "additional_context": { "disclosure_purpose": "GLBA_502(e)", "driver_license_number": "12342131", "driver_license_state": "CA", "previous_reference_id": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8" }, "id": "data-individual-id", "given_name": "Ananda", "family_name": "test", "date_of_birth": "1958-01-31", "national_id": "700-01-3784", "phone_number": "+12037986508", "address": { "line_1": "2 Moran Ave", "line_2": "Address Line 2", "locality": "Danbury", "major_admin_division": "CT", "country": "US", "postal_code": "068100000" }, "email": "j.smith@example.com" }, "ip_address": "10.10.10.10", "custom": { "customer_user_id": "custom-customer_user_id", "country_of_origin": "US", "amount": "124.56", "initiation_date": "2025-05-18T02:09:25Z", "use_case": "application", "unique_id_transaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150", "unique_id_user": "20688849", "unique_id_account": "2132", "direction": "originator", "description": "note", "origination_channel": "web", "merchant": "name", "mcc": "1234", "counter_party_institution": "test1", "counter_party_type": "business", "counter_party_routing": "2132", "counter_party_account": "21321", "transaction_location": "domestic" } } } ``` ```curl curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data-raw '{ "id": "Ananda_FPF-1761662048692", "timestamp": "2025-05-18T02:09:25Z", "workflow": "api_individual_onboarding", "data": { "line_of_business": "test1", "channel": "mobile", "individual": { "additional_context": { "disclosure_purpose": "GLBA_502(e)", "driver_license_number": "12342131", "driver_license_state": "CA", "previous_reference_id": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8" }, "id": "data-individual-id", "given_name": "Ananda", "family_name": "test", "date_of_birth": "1958-01-31", "national_id": "700-01-3784", "phone_number": "+12037986508", "address": { "line_1": "2 Moran Ave", "line_2": "Address Line 2", "locality": "Danbury", "major_admin_division": "CT", "country": "US", "postal_code": "068100000" }, "email": "j.smith@example.com" }, "ip_address": "10.10.10.10", "custom": { "customer_user_id": "custom-customer_user_id", "country_of_origin": "US", "amount": "124.56", "initiation_date": "2025-05-18T02:09:25Z", "use_case": "application", "unique_id_transaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150", "unique_id_user": "20688849", "unique_id_account": "2132", "direction": "originator", "description": "note", "origination_channel": "web", "merchant": "name", "mcc": "1234", "counter_party_institution": "test1", "counter_party_type": "business", "counter_party_routing": "2132", "counter_party_account": "21321", "transaction_location": "domestic" } } }' ``` ### Request schema [Skip link to Request schema](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#request-schema) #### Top-level fields [Skip link to Top-level fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#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. | `"Ananda_FPF-1761662048692"` | | `timestamp` | String | Required | RFC 3339 timestamp when the evaluation was initiated. | `"2025-05-18T02:09:25Z"` | | `workflow` | String | Required | RiskOS™ workflow name configured in your environment.
**Note:** The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request. | `"api_individual_onboarding"` | | `data` | Object | Required | Main payload containing contextual and individual information. | See `data` schema below. | #### `data` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#data-fields) | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `line_of_business` | String | Optional | Line of business or internal business segment identifier. | `"test1"` | | `channel` | String | Optional | Channel through which the user is onboarding (for example, `"mobile"`, `"web"`). **Note:** This field is reserved for future model versions and is not currently used in First-Party Fraud scoring. | `"mobile"` | | `individual` | Object | Required | Primary individual identity information. | See `individual` schema below. | | `ip_address` | String | Optional | Client IP address in IPv4/IPv6 format. Used for device intelligence checks. | `"10.10.10.10"` | | `custom` | Object | Optional | Custom transaction or contextual fields used for fraud risk evaluation. | See `custom` schema below. | #### `individual` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#individual-fields) | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `id` | String | Optional | Maps to the `userId` in enrichments or a customer’s internal identifier. Can be enabled as a searchable field in RiskOS™ Dashboard. | `"data-individual-id"` | | `given_name` | String | Required | Individual’s first or given name. | `"Ananda"` | | `family_name` | String | Required | Individual’s last or family name. | `"test"` | | `date_of_birth` | String | Required | Individual’s date of birth in ISO 8601 format (`YYYY-MM-DD`). | `"1958-01-31"` | | `national_id` | String | Required | Individual’s national ID (e.g., SSN or ITIN, hyphens optional). | `"700-01-3784"` | | `phone_number` | String | Required | Phone number in **E.164** format. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience. | `"+12037986508"` | | `email` | String | Required | Email address associated with the individual. | `"j.smith@example.com"` | | `address` | Object | Required | Physical mailing address of the individual. | See `address` schema below. | | `additional_context` | Object | Optional | Supplemental verification context (e.g., driver’s license info). | See `additional_context` schema below. | #### `address` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#address-fields) | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `line_1` | String | Required | Primary street address line. | `"2 Moran Ave"` | | `line_2` | String | Optional | Secondary address line (apartment, suite, unit, etc.). | `"Address Line 2"` | | `locality` | String | Required | City or locality of residence. | `"Danbury"` | | `major_admin_division` | String | Required | State, province, or region (ISO 3166-2 format). | `"CT"` | | `country` | String | Required | ISO 3166-1 alpha-2 country code. | `"US"` | | `postal_code` | String | Required | ZIP or postal code. | `"068100000"` | #### `additional_context` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#additional_context-fields) | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `disclosure_purpose` | String | Required | Regulatory disclosure or permissible purpose identifier. | `"GLBA_502(e)"` | | `driver_license_number` | String | Optional | Driver’s license number for identity verification. | `"12342131"` | | `driver_license_state` | String | Optional | Issuing state or region for the driver’s license. | `"CA"` | | `previous_reference_id` | String | Optional | Reference ID for linking to prior evaluations. | `"ffc170f2-b3e4-423b-a373-5d6e1e9b23f8"` | #### `custom` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#custom-fields) Use the `custom` object to send additional transaction and contextual data alongside the evaluation request. > **Important**: Fields in the `custom` object are **echoed back** in the enrichment `request` within the response for traceability and audit purposes. However, not all custom fields are actively used in the current First-Party Fraud scoring model. Specifically: > > - **`amount`**, **`direction`**, **`useCase`**, **`uniqueIdTransaction`**, **`uniqueIdUser`**, **`uniqueIdAccount`**, **`initiationDate`**, **`transactionLocation`**, **`mcc`**, **`merchant`**, **`counterPartyType`**, **`counterPartyInstitution`**, **`counterPartyRouting`**, **`counterPartyAccount`**, and **`description`** — Accepted and stored for consortium enrichment and future model versions. Provide these fields when available to maximize scoring accuracy as models evolve. > - **`origination_channel`** — Reserved for future model versions. Not now used in scoring. ## Example response [Skip link to Example response](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#example-response) When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results. JSON ```json { "id": "Ananda_FPF-1761662048692", "workflow": "api_individual_onboarding", "workflow_id": "20f661e5-5818-426f-ae1b-2f72f517cadd", "workflow_version": "63.3.0", "eval_source": "API", "eval_id": "f4e242b6-8f73-4a84-9f65-75163afee1ea", "eval_start_time": "2025-10-28T14:34:10.169683989Z", "eval_end_time": "2025-10-28T14:34:10.354256445Z", "decision": "REJECT", "decision_at": "2025-10-28T14:34:10.354117625Z", "status": "CLOSED", "sub_status": "Decline", "tags": [], "notes": "", "review_queues": [], "data_enrichments": [\ {\ "enrichment_name": "Socure Sigma First Party Fraud PROD SBX",\ "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",\ "enrichment_provider": "Socure",\ "status_code": 200,\ "request": {\ "amount": 124.56,\ "channel": "web",\ "city": "Danbury",\ "counterPartyAccount": "21321",\ "counterPartyInstitution": "test1",\ "counterPartyRouting": "2132",\ "counterPartyType": "business",\ "country": "US",\ "countryOfOrigin": "US",\ "customerUserId": "custom-customer_user_id",\ "description": "note",\ "direction": "originator",\ "disclosurePurpose": "GLBA_502(e)",\ "dob": "1958-01-31",\ "driverLicense": "12342131",\ "driverLicenseState": "CA",\ "email": "j.smith@example.com",\ "firstName": "Ananda",\ "initiationDate": "2025-10-28T14:34:08.693000Z",\ "ipAddress": "10.10.10.10",\ "mcc": "1234",\ "merchant": "name",\ "mobileNumber": "+12037986508",\ "modules": [\ "firstpartyfraud"\ ],\ "nationalId": "700-01-3784",\ "parentTxnId": "f4e242b6-8f73-4a84-9f65-75163afee1ea",\ "physicalAddress": "2 Moran Ave",\ "physicalAddress2": "Address Line 2",\ "previousReferenceId": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8",\ "riskOSId": "Ananda_FPF-1761662048692",\ "state": "CT",\ "surName": "test",\ "transactionLocation": "domestic",\ "uniqueIdAccount": "2132",\ "uniqueIdTransaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150",\ "uniqueIdUser": "20688849",\ "useCase": "application",\ "userId": "data-individual-id",\ "workflow": "api_individual_onboarding",\ "zip": "068100000"\ },\ "response": {\ "customerProfile": {\ "customerUserId": "custom-customer_user_id",\ "userId": "data-individual-id"\ },\ "firstPartyFraud": {\ "reasonCodes": [],\ "scores": [\ {\ "name": "Dispute Abuse",\ "score": 0.254,\ "version": "1.0"\ },\ {\ "name": "Identity Manipulation",\ "score": 0.401,\ "version": "1.0"\ }\ ],\ "signals": {\ // Socure returns additional raw address signals not shown here for brevity and sensitivity.\ }\ },\ "referenceId": "75e32176-81c5-4616-a449-b4cfc7bfbcda"\ },\ "is_source_cache": false,\ "total_attempts": 1\ }\ ], "computed": { "CONDITION": false, "socure_sigmafirstpartyfraud_response": { "__third_party_name__": "Socure Sigma First Party Fraud PROD SBX", "customerProfile": { "customerUserId": "custom-customer_user_id", "userId": "data-individual-id" }, "firstPartyFraud": { "reasonCodes": [], "scores": [\ {\ "name": "Dispute Abuse",\ "score": 0.254,\ "version": "1.0"\ },\ {\ "name": "Identity Manipulation",\ "score": 0.401,\ "version": "1.0"\ }\ ], "signals": { // Socure returns additional raw address signals not shown here for brevity and sensitivity. } }, "referenceId": "75e32176-81c5-4616-a449-b4cfc7bfbcda" } }, "aggregations": { "device_ip": null, "device_ip_address": { "id": "" }, "ip_address": {}, "primary_email": {}, "primary_phone": {}, "ssn": {} }, "eval_status": "evaluation_completed", "environment_name": "Sandbox" } ``` ### Key response fields [Skip link to Key response fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#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 [Skip link to Where to find specific results](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#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) [Skip link to Decision and routing (primary control signals)](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#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. | `"REJECT"` | | `decision_at` | String `` | RFC 3339 timestamp when the decision was finalized. | `"2025-10-28T14:34:10.354117625Z"` | | `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. | | | `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. | `""` | ### Evaluation lifecycle and status [Skip link to Evaluation lifecycle and status](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#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` | `"Reject"` | ### Identifiers and traceability [Skip link to Identifiers and traceability](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#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_. | `"Ananda_FPF-1761662048692"` | | `eval_id` | String (UUID) | RiskOS™-generated unique identifier for the evaluation. | `"f4e242b6-8f73-4a84-9f65-75163afee1ea"` | | `workflow` | String | Name of the workflow executed. | `"api_individual_onboarding"` | | `workflow_id` | String (UUID) | Unique identifier for the workflow run. | `"20f661e5-5818-426f-ae1b-2f72f517cadd"` | | `workflow_version` | String | Version of the executed workflow. | `"63.3.0"` | ### Execution context [Skip link to Execution context](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#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 `` | RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring. | `"2025-10-28T14:34:10.169683989Z"` | | `eval_end_time` | String `` | RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with `eval_start_time` to compute total processing time. | `"2025-10-28T14:34:10.354256445Z"` | | `environment_name` | String | Indicates which environment the evaluation ran in. Typically `Sandbox` for testing or `Production` for live traffic. | `"Sandbox"` | ### Enrichment results [Skip link to Enrichment results](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#enrichment-results) Enrichment outputs are returned in the `data_enrichments` array. | Field | Type | Description | Example | | --- | --- | --- | --- | | `enrichment_name` | String | Product name. | `"Socure Sigma First Party Fraud PROD SBX"` | | `enrichment_endpoint` | String (URL) | Endpoint invoked. | `"https://sandbox.socure.com/api`
`/3.0/EmailAuthScore"` | | `enrichment_provider` | String | Provider. | `"Socure"` | | `status_code` | Integer | HTTP status code. | `200` | | `request` | Object | Payload sent to provider. | See `request` fields below. | | `response` | Object | Payload returned by provider. | See `response` fields below. | | `is_source_cache` | Boolean | Response served from cache. | `false` | | `total_attempts` | Integer | Number of attempts. | `1` | #### `request` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#request-fields) > **Note**: The `request` object echoes back the input fields sent to the enrichment provider. These fields appear in the response for **traceability and debugging** — their presence doesn't mean they all influence scoring. See the notes that follow for fields reserved for future use. | Field | Type | Description | Example | | --- | --- | --- | --- | | `amount` | Number | Transaction amount. | `124.56` | | `channel` | String | Channel of interaction (maps from `custom.origination_channel` in the request). **Reserved for future model versions; not now used in scoring.** | `"web"` | | `city` | String | City. | `"Danbury"` | | `counterPartyAccount` | String | Counterparty account number. | `"21321"` | | `counterPartyInstitution` | String | Counterparty institution. | `"test1"` | | `counterPartyRouting` | String | Counterparty routing number. | `"2132"` | | `counterPartyType` | String | Counterparty type. | `"business"` | | `country` | String | Country (ISO 3166-1 alpha-2). | `"US"` | | `countryOfOrigin` | String | Country of origin (ISO 3166-1 alpha-2). | `"US"` | | `customerUserId` | String | Internal customer user ID. | `"custom-customer_user_id"` | | `description` | String | Description / note. | `"note"` | | `direction` | String | Transaction direction. | `"originator"` | | `disclosurePurpose` | String | Permissible purpose / disclosure code. | `"GLBA_502(e)"` | | `dob` | String | Date of birth (YYYY-MM-DD). | `"1958-01-31"` | | `driverLicense` | String | Driver license number. | `"12342131"` | | `driverLicenseState` | String | DL issuing state. | `"CA"` | | `email` | String | Email address. | `"j.smith@example.com"` | | `firstName` | String | First name. | `"Ananda"` | | `initiationDate` | String | Transaction initiation timestamp (RFC 3339). | `"2025-10-28T14:34:08.693000Z"` | | `ipAddress` | String | IP address. | `"10.10.10.10"` | | `mcc` | String | Merchant category code. | `"1234"` | | `merchant` | String | Merchant name. | `"name"` | | `mobileNumber` | String | Mobile phone (E.164). | `"+12037986508"` | | `modules` | Array of Strings | Modules requested. | `["firstpartyfraud"]` | | `nationalId` | String | National ID (e.g., SSN/ITIN). | `"700-01-3784"` | | `parentTxnId` | String (UUID) | Parent transaction / evaluation ID. | `"f4e242b6-8f73-4a84-9f65-75163afee1ea"` | | `physicalAddress` | String | Address line 1. | `"2 Moran Ave"` | | `physicalAddress2` | String | Address line 2. | `"Address Line 2"` | | `previousReferenceId` | String (UUID) | Prior enrichment reference ID. | `"ffc170f2-b3e4-423b-a373-5d6e1e9b23f8"` | | `riskOSId` | String | RiskOS™ request ID. | `"Ananda_FPF-1761662048692"` | | `state` | String | State / region. | `"CT"` | | `surName` | String | Surname / last name. | `"test"` | | `transactionLocation` | String | Domestic / international. | `"domestic"` | | `uniqueIdAccount` | String | Internal account ID. | `"2132"` | | `uniqueIdTransaction` | String | Internal transaction ID. | `"421AED9B-4CC4-4ECA-9A0B-..."` | | `uniqueIdUser` | String | Internal user ID. | `"20688849"` | | `useCase` | String | Business use case. | `"application"` | | `userId` | String | Subject user ID. | `"data-individual-id"` | | `workflow` | String | Workflow key (echoed). | `"api_individual_onboarding"` | | `zip` | String | Postal code. | `"068100000"` | #### `response` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#response-fields) | Field | Type | Description | Example | | --- | --- | --- | --- | | `customerProfile` | Object | Echoed subject/customer identifiers. | See `customerProfile` schema below. | | `firstPartyFraud` | Object | FPF model outputs (reasons, scores, signals). | See `firstPartyFraud` schema below. | | `referenceId` | String (UUID) | Unique identifier assigned to each enrichment after a RiskOS™ workflow is finalized. | `"75e32176-81c5-4616-a449-b4cfc7bfbcda"` | #### `customerProfile` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#customerprofile-fields) | Field | Type | Description | Example | | --- | --- | --- | --- | | `customerUserId` | String | Internal customer user ID. | `"custom-customer_user_id"` | | `userId` | String | Subject user ID. | `"data-individual-id"` | #### `firstPartyFraud` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#firstpartyfraud-fields) | Field | Type | Description | Example | | --- | --- | --- | --- | | `reasonCodes` | Array of Strings | Model reason codes explaining risk signals. | | | `scores` | Array of Objects | Model scores returned by the provider. | See `scores` schema below. | | `signals` | Object | Feature aggregates and metrics by category. | See [Risk Signals](https://help.socure.com/riskos/docs/risk-signals#/) for more information. | #### `scores` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#scores-fields) | Field | Type | Description | Example | | --- | --- | --- | --- | | `name` | String | Scoring model name. | `"Dispute Abuse"` | | `score` | Number | Score in `[0.000 … 1.000]`. | `0.254` | | `version` | String | Scoring model version. | `"1.0"` | #### `signals` fields [Skip link to [object Object], fields](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#signals-fields) See [Risk Signals](https://help.socure.com/riskos/docs/risk-signals#/) for more information. * * * ## Best practices [Skip link to Best practices](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#best-practices) - Collect and submit as much identity and contact data as possible for best accuracy - Always include `disclosure_purpose = GLBA_502(e)` to comply with FPF regulations - For performance at scale, parallelize calls and apply appropriate rate limits - Regularly update and review thresholds to align with business risk policy * * * ## Test in Sandbox [Skip link to Test in Sandbox](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#test-in-sandbox) You can simulate almost any identity scenario using our Test Personas JSON file. Each entry includes a realistic, sandbox-only identity and a ready-to-use API request payload. Many entries also include the expected response to help you validate your `/api/evaluation` integration before going live. - **Endpoint**: `POST /api/evaluation` - **Base URL (Sandbox)**: `https://riskos.sandbox.socure.com/api/evaluation` - **Auth**: `Authorization: Bearer YOUR_SANDBOX_KEY` ### Test cases - Unhappy path [Skip link to Test cases - Unhappy path](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#test-cases---unhappy-path) #### Test case 1: Invalid GLBA disclosure [Skip link to Test case 1: Invalid GLBA disclosure](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#test-case-1-invalid-glba-disclosure) Example requestExample response ```curl curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'X-API-Version: 2025-01-01.orion' \ --data-raw '{ "id": "Ananda_FPF-987654", "timestamp": "2025-08-13T06:10:54.298Z", "workflow": "api_individual_onboarding", "data": { "line_of_business": "test1", "channel": "mobile", "individual": { "additional_context": { "disclosure_purpose": "GLBA_502", "driver_license_number": "12342131", "driver_license_state": "CA", "previous_reference_id": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8" }, "id": "data-individual-id", "given_name": "Ananda", "family_name": "test", "date_of_birth": "1958-01-31", "national_id": "700-01-3784", "phone_number": "+12037986508", "address": { "line_1": "2 Moran Ave", "line_2": "Address Line 2", "locality": "Danbury", "major_admin_division": "CT", "country": "US", "postal_code": "068100000" }, "email": "j.smith@example.com" }, "ip_address": "10.10.10.10", "custom": { "customer_user_id": "custom-customer_user_id", "country_of_origin": "US", "amount": "124.56", "initiation_date": "2025-08-13T06:10:54.298Z", "use_case": "application", "unique_id_transaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150", "unique_id_user": "20688849", "unique_id_account": "2132", "direction": "originator", "description": "note", "origination_channel": "web", "merchant": "name", "mcc": "1234", "counter_party_institution": "test1", "counter_party_type": "business", "counter_party_routing": "2132", "counter_party_account": "21321", "transaction_location": "domestic" } } }' ``` ```json { "id": "Ananda_FPF-987654", "workflow": "api_individual_onboarding", "workflow_id": "20f661e5-5818-426f-ae1b-2f72f517cadd", "workflow_version": "63.3.0", "eval_source": "API", "eval_id": "2b914ae7-1faa-4405-9839-6c17badf6c0d", "eval_start_time": "2025-10-29T16:18:24.42846889Z", "eval_end_time": "2025-10-29T16:18:24.595010816Z", "decision": "REJECT", "decision_at": "2025-10-29T16:18:24.594882056Z", "status": "CLOSED", "sub_status": "Decline", "tags": [], "notes": "", "review_queues": [], "data_enrichments": [\ {\ "enrichment_name": "Socure Sigma First Party Fraud",\ "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",\ "enrichment_provider": "Socure",\ "status_code": 400,\ "request": {\ "amount": 124.56,\ "channel": "web",\ "city": "Danbury",\ "counterPartyAccount": "21321",\ "counterPartyInstitution": "test1",\ "counterPartyRouting": "2132",\ "counterPartyType": "business",\ "country": "US",\ "countryOfOrigin": "US",\ "customerUserId": "custom-customer_user_id",\ "description": "note",\ "direction": "originator",\ "disclosurePurpose": "GLBA_502",\ "dob": "1958-01-31",\ "driverLicense": "12342131",\ "driverLicenseState": "CA",\ "email": "j.smith@example.com",\ "firstName": "Ananda",\ "initiationDate": "2025-08-13T06:10:54.298Z",\ "ipAddress": "10.10.10.10",\ "mcc": "1234",\ "merchant": "name",\ "mobileNumber": "+12037986508",\ "modules": [\ "firstpartyfraud"\ ],\ "nationalId": "700-01-3784",\ "parentTxnId": "2b914ae7-1faa-4405-9839-6c17badf6c0d",\ "physicalAddress": "2 Moran Ave",\ "physicalAddress2": "Address Line 2",\ "previousReferenceId": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8",\ "riskOSId": "Ananda_FPF-987654",\ "state": "CT",\ "surName": "test",\ "transactionLocation": "domestic",\ "uniqueIdAccount": "2132",\ "uniqueIdTransaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150",\ "uniqueIdUser": "20688849",\ "useCase": "application",\ "userId": "data-individual-id",\ "workflow": "api_individual_onboarding",\ "zip": "068100000"\ },\ "response": {\ "response": "{\"status\":\"Error\",\"referenceId\":\"78b6d16b-91ee-4bf0-8c21-0be13321657e\",\"data\":{},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Please resubmit the transaction with a valid GLBA disclosure purpose.\"}"\ },\ "is_source_cache": false,\ "total_attempts": 1\ }\ ], "computed": { "CONDITION": false, "socure_sigmafirstpartyfraud_error": { "error_code": "EXTERNAL_ERROR", "error_msg": "{\"status\":\"Error\",\"referenceId\":\"78b6d16b-91ee-4bf0-8c21-0be13321657e\",\"data\":{},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Please resubmit the transaction with a valid GLBA disclosure purpose.\"}", "http_status": 400, "is_retryable": false } }, "aggregations": { "device_ip": null, "device_ip_address": { "id": "" }, "ip_address": { "app_count_per_ip_12hr": 0, "app_count_per_ip_15day": 77, "app_count_per_ip_1day": 5, "app_count_per_ip_1hr": 0, "app_count_per_ip_1min": 0, "app_count_per_ip_30day": 78, "app_count_per_ip_30min": 0, "app_count_per_ip_60day": 78, "app_count_per_ip_7day": 42, "app_count_per_ip_90day": 80, "fraud_count_per_ip_12hr": 0, "fraud_count_per_ip_15day": 0, "fraud_count_per_ip_1day": 0, "fraud_count_per_ip_1hr": 0, "fraud_count_per_ip_1min": 0, "fraud_count_per_ip_30day": 0, "fraud_count_per_ip_30min": 0, "fraud_count_per_ip_60day": 0, "fraud_count_per_ip_7day": 0, "fraud_count_per_ip_90day": 0, "id": "10.10.10.10" }, "primary_email": { "app_count_per_email_12hr": 0, "app_count_per_email_15day": 203, "app_count_per_email_1day": 14, "app_count_per_email_1hr": 0, "app_count_per_email_1min": 0, "app_count_per_email_30day": 231, "app_count_per_email_30min": 0, "app_count_per_email_60day": 231, "app_count_per_email_7day": 100, "app_count_per_email_90day": 232, "fraud_count_per_email_12hr": 0, "fraud_count_per_email_15day": 0, "fraud_count_per_email_1day": 0, "fraud_count_per_email_1hr": 0, "fraud_count_per_email_1min": 0, "fraud_count_per_email_30day": 0, "fraud_count_per_email_30min": 0, "fraud_count_per_email_60day": 0, "fraud_count_per_email_7day": 0, "fraud_count_per_email_90day": 0, "id": "j.smith@example.com" }, "primary_phone": { "app_count_per_phone_12hr": 0, "app_count_per_phone_15day": 77, "app_count_per_phone_1day": 5, "app_count_per_phone_1hr": 0, "app_count_per_phone_1min": 0, "app_count_per_phone_30day": 98, "app_count_per_phone_30min": 0, "app_count_per_phone_60day": 135, "app_count_per_phone_7day": 42, "app_count_per_phone_90day": 154, "fraud_count_per_phone_12hr": 0, "fraud_count_per_phone_15day": 0, "fraud_count_per_phone_1day": 0, "fraud_count_per_phone_1hr": 0, "fraud_count_per_phone_1min": 0, "fraud_count_per_phone_30day": 0, "fraud_count_per_phone_30min": 0, "fraud_count_per_phone_60day": 0, "fraud_count_per_phone_7day": 0, "fraud_count_per_phone_90day": 0, "id": "+12037986508" }, "ssn": { "app_count_per_ssn_12hr": 0, "app_count_per_ssn_15day": 0, "app_count_per_ssn_1day": 0, "app_count_per_ssn_1hr": 0, "app_count_per_ssn_1min": 0, "app_count_per_ssn_30day": 1, "app_count_per_ssn_30min": 0, "app_count_per_ssn_60day": 28, "app_count_per_ssn_7day": 0, "app_count_per_ssn_90day": 46, "fraud_count_per_ssn_12hr": 0, "fraud_count_per_ssn_15day": 0, "fraud_count_per_ssn_1day": 0, "fraud_count_per_ssn_1hr": 0, "fraud_count_per_ssn_1min": 0, "fraud_count_per_ssn_30day": 0, "fraud_count_per_ssn_30min": 0, "fraud_count_per_ssn_60day": 0, "fraud_count_per_ssn_7day": 0, "fraud_count_per_ssn_90day": 0, "id": "vault:v1:cFYLTIMr5fum0KW16PsblhVwG2+J9+UFdYMCJsP/IE4/BlrEp8fj" } }, "eval_status": "evaluation_completed", "environment_name": "Sandbox" } ``` #### Test case 2: Invalid DOB [Skip link to Test case 2: Invalid DOB](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#test-case-2-invalid-dob) Example requestExample response ```curl curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'X-API-Version: 2025-01-01.orion' \ --data-raw '{ "id": "Ananda_FPF-1761754896062", "timestamp": "2025-10-29T16:21:36.758526301Z", "workflow": "api_individual_onboarding", "data": { "line_of_business": "test1", "channel": "mobile", "individual": { "additional_context": { "disclosure_purpose": "GLBA_502(e)", "driver_license_number": "12342131", "driver_license_state": "CA", "previous_reference_id": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8" }, "id": "data-individual-id", "given_name": "Ananda", "family_name": "test", "date_of_birth": "2058-01-31", "national_id": "700-01-3784", "phone_number": "+12037986508", "address": { "line_1": "2 Moran Ave", "line_2": "Address Line 2", "locality": "Danbury", "major_admin_division": "CT", "country": "US", "postal_code": "068100000" }, "email": "j.smith@example.com" }, "ip_address": "10.10.10.10", "custom": { "customer_user_id": "custom-customer_user_id", "country_of_origin": "US", "amount": "124.56", "initiation_date": "2025-10-29T16:21:36.758526301Z", "use_case": "application", "unique_id_transaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150", "unique_id_user": "20688849", "unique_id_account": "2132", "direction": "originator", "description": "note", "origination_channel": "web", "merchant": "name", "mcc": "1234", "counter_party_institution": "test1", "counter_party_type": "business", "counter_party_routing": "2132", "counter_party_account": "21321", "transaction_location": "domestic" } } }' ``` ```json { "id": "Ananda_FPF-1761754896062", "workflow": "api_individual_onboarding", "workflow_id": "20f661e5-5818-426f-ae1b-2f72f517cadd", "workflow_version": "63.3.0", "eval_source": "API", "eval_id": "2be05711-1775-4abb-96e1-f696448b82bd", "eval_start_time": "2025-10-29T16:23:03.73211217Z", "eval_end_time": "2025-10-29T16:23:03.988128748Z", "decision": "REJECT", "decision_at": "2025-10-29T16:23:03.987981588Z", "status": "CLOSED", "sub_status": "Decline", "tags": [], "notes": "", "review_queues": [], "data_enrichments": [\ {\ "enrichment_name": "Socure Sigma First Party Fraud PROD SBX",\ "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",\ "enrichment_provider": "Socure",\ "status_code": 400,\ "request": {\ "amount": 124.56,\ "channel": "web",\ "city": "Danbury",\ "counterPartyAccount": "21321",\ "counterPartyInstitution": "test1",\ "counterPartyRouting": "2132",\ "counterPartyType": "business",\ "country": "US",\ "countryOfOrigin": "US",\ "customerUserId": "custom-customer_user_id",\ "description": "note",\ "direction": "originator",\ "disclosurePurpose": "GLBA_502(e)",\ "dob": "2058-01-31",\ "driverLicense": "12342131",\ "driverLicenseState": "CA",\ "email": "j.smith@example.com",\ "firstName": "Ananda",\ "initiationDate": "2025-10-29T16:21:36.758526301Z",\ "ipAddress": "10.10.10.10",\ "mcc": "1234",\ "merchant": "name",\ "mobileNumber": "+12037986508",\ "modules": [\ "firstpartyfraud"\ ],\ "nationalId": "700-01-3784",\ "parentTxnId": "2be05711-1775-4abb-96e1-f696448b82bd",\ "physicalAddress": "2 Moran Ave",\ "physicalAddress2": "Address Line 2",\ "previousReferenceId": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8",\ "riskOSId": "Ananda_FPF-1761754896062",\ "state": "CT",\ "surName": "test",\ "transactionLocation": "domestic",\ "uniqueIdAccount": "2132",\ "uniqueIdTransaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150",\ "uniqueIdUser": "20688849",\ "useCase": "application",\ "userId": "data-individual-id",\ "workflow": "api_individual_onboarding",\ "zip": "068100000"\ },\ "response": {\ "response": "{\"status\":\"Error\",\"referenceId\":\"18d4733a-2b29-4e33-b4aa-ce9bf49ab7f4\",\"data\":{\"parameters\":[\"Invalid date. Please resubmit the transaction using dates conforming to ISO 8601 format (e.g. yyyy-MM-dd, yyyy/MM/dd or yyyyMMdd or yyyy-MM-dd). Future dates are not accepted.\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid date. Please resubmit the transaction using dates conforming to ISO 8601 format (e.g. yyyy-MM-dd, yyyy/MM/dd or yyyyMMdd or yyyy-MM-dd). Future dates are not accepted.\"}"\ },\ "is_source_cache": false,\ "total_attempts": 1\ }\ ], "computed": { "CONDITION": false, "socure_sigmafirstpartyfraud_error": { "error_code": "EXTERNAL_ERROR", "error_msg": "{\"status\":\"Error\",\"referenceId\":\"18d4733a-2b29-4e33-b4aa-ce9bf49ab7f4\",\"data\":{\"parameters\":[\"Invalid date. Please resubmit the transaction using dates conforming to ISO 8601 format (e.g. yyyy-MM-dd, yyyy/MM/dd or yyyyMMdd or yyyy-MM-dd). Future dates are not accepted.\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid date. Please resubmit the transaction using dates conforming to ISO 8601 format (e.g. yyyy-MM-dd, yyyy/MM/dd or yyyyMMdd or yyyy-MM-dd). Future dates are not accepted.\"}", "http_status": 400, "is_retryable": false } }, "aggregations": { "device_ip": null, "device_ip_address": { "id": "" }, "ip_address": { "app_count_per_ip_12hr": 46, "app_count_per_ip_15day": 198, "app_count_per_ip_1day": 46, "app_count_per_ip_1hr": 7, "app_count_per_ip_1min": 1, "app_count_per_ip_30day": 300, "app_count_per_ip_30min": 8, "app_count_per_ip_60day": 493, "app_count_per_ip_7day": 134, "app_count_per_ip_90day": 675, "fraud_count_per_ip_12hr": 0, "fraud_count_per_ip_15day": 0, "fraud_count_per_ip_1day": 0, "fraud_count_per_ip_1hr": 0, "fraud_count_per_ip_1min": 0, "fraud_count_per_ip_30day": 0, "fraud_count_per_ip_30min": 0, "fraud_count_per_ip_60day": 0, "fraud_count_per_ip_7day": 0, "fraud_count_per_ip_90day": 0, "id": "10.10.10.10" }, "primary_email": { "app_count_per_email_12hr": 38, "app_count_per_email_15day": 228, "app_count_per_email_1day": 38, "app_count_per_email_1hr": 7, "app_count_per_email_1min": 1, "app_count_per_email_30day": 435, "app_count_per_email_30min": 8, "app_count_per_email_60day": 854, "app_count_per_email_7day": 127, "app_count_per_email_90day": 1311, "fraud_count_per_email_12hr": 0, "fraud_count_per_email_15day": 0, "fraud_count_per_email_1day": 0, "fraud_count_per_email_1hr": 0, "fraud_count_per_email_1min": 0, "fraud_count_per_email_30day": 0, "fraud_count_per_email_30min": 0, "fraud_count_per_email_60day": 0, "fraud_count_per_email_7day": 0, "fraud_count_per_email_90day": 0, "id": "j.smith@example.com" }, "primary_phone": { "app_count_per_phone_12hr": 46, "app_count_per_phone_15day": 199, "app_count_per_phone_1day": 46, "app_count_per_phone_1hr": 7, "app_count_per_phone_1min": 1, "app_count_per_phone_30day": 303, "app_count_per_phone_30min": 8, "app_count_per_phone_60day": 491, "app_count_per_phone_7day": 135, "app_count_per_phone_90day": 675, "fraud_count_per_phone_12hr": 0, "fraud_count_per_phone_15day": 0, "fraud_count_per_phone_1day": 0, "fraud_count_per_phone_1hr": 0, "fraud_count_per_phone_1min": 0, "fraud_count_per_phone_30day": 0, "fraud_count_per_phone_30min": 0, "fraud_count_per_phone_60day": 0, "fraud_count_per_phone_7day": 0, "fraud_count_per_phone_90day": 0, "id": "+12037986508" }, "ssn": { "app_count_per_ssn_12hr": 31, "app_count_per_ssn_15day": 54, "app_count_per_ssn_1day": 31, "app_count_per_ssn_1hr": 6, "app_count_per_ssn_1min": 1, "app_count_per_ssn_30day": 56, "app_count_per_ssn_30min": 10, "app_count_per_ssn_60day": 58, "app_count_per_ssn_7day": 53, "app_count_per_ssn_90day": 58, "fraud_count_per_ssn_12hr": 0, "fraud_count_per_ssn_15day": 0, "fraud_count_per_ssn_1day": 0, "fraud_count_per_ssn_1hr": 0, "fraud_count_per_ssn_1min": 0, "fraud_count_per_ssn_30day": 0, "fraud_count_per_ssn_30min": 0, "fraud_count_per_ssn_60day": 0, "fraud_count_per_ssn_7day": 0, "fraud_count_per_ssn_90day": 0, "id": "vault:v1:3G22PDjlKy4NTmqXN+0TzAuF5iX4brRSe+HgRk2AiST9y9KNK/M/" } }, "eval_status": "evaluation_completed", "environment_name": "Sandbox" } ``` #### Test case 3: Invalid SSN [Skip link to Test case 3: Invalid SSN](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#test-case-3-invalid-ssn) Example requestJSON ```curl curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'X-API-Version: 2025-01-01.orion' \ --data-raw '{ "id": "Ananda_FPF-1761755062290", "timestamp": "2025-10-29T16:24:22.943842813Z", "workflow": "api_individual_onboarding", "data": { "line_of_business": "test1", "channel": "mobile", "individual": { "additional_context": { "disclosure_purpose": "GLBA_502(e)", "driver_license_number": "12342131", "driver_license_state": "CA", "previous_reference_id": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8" }, "id": "data-individual-id", "given_name": "Ananda", "family_name": "test", "date_of_birth": "1958-01-31", "national_id": "70s0-01-3784", "phone_number": "+12037986508", "address": { "line_1": "2 Moran Ave", "line_2": "Address Line 2", "locality": "Danbury", "major_admin_division": "CT", "country": "US", "postal_code": "068100000" }, "email": "j.smith@example.com" }, "ip_address": "10.10.10.10", "custom": { "customer_user_id": "custom-customer_user_id", "country_of_origin": "US", "amount": "124.56", "initiation_date": "2025-10-29T16:24:22.943842813Z", "use_case": "application", "unique_id_transaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150", "unique_id_user": "20688849", "unique_id_account": "2132", "direction": "originator", "description": "note", "origination_channel": "web", "merchant": "name", "mcc": "1234", "counter_party_institution": "test1", "counter_party_type": "business", "counter_party_routing": "2132", "counter_party_account": "21321", "transaction_location": "domestic" } } }' ``` ```json { "id": "Ananda_FPF-1761755062290", "workflow": "api_individual_onboarding", "workflow_id": "20f661e5-5818-426f-ae1b-2f72f517cadd", "workflow_version": "63.3.0", "eval_source": "API", "eval_id": "e0201df4-c2b1-4bc8-8ed3-8328d36f2316", "eval_start_time": "2025-10-29T16:24:57.546546537Z", "eval_end_time": "2025-10-29T16:24:57.678430554Z", "decision": "REJECT", "decision_at": "2025-10-29T16:24:57.678290623Z", "status": "CLOSED", "sub_status": "Decline", "tags": [], "notes": "", "review_queues": [], "data_enrichments": [\ {\ "enrichment_name": "Socure Sigma First Party Fraud PROD SBX",\ "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",\ "enrichment_provider": "Socure",\ "status_code": 400,\ "request": {\ "amount": 124.56,\ "channel": "web",\ "city": "Danbury",\ "counterPartyAccount": "21321",\ "counterPartyInstitution": "test1",\ "counterPartyRouting": "2132",\ "counterPartyType": "business",\ "country": "US",\ "countryOfOrigin": "US",\ "customerUserId": "custom-customer_user_id",\ "description": "note",\ "direction": "originator",\ "disclosurePurpose": "GLBA_502(e)",\ "dob": "1958-01-31",\ "driverLicense": "12342131",\ "driverLicenseState": "CA",\ "email": "j.smith@example.com",\ "firstName": "Ananda",\ "initiationDate": "2025-10-29T16:24:22.943842813Z",\ "ipAddress": "10.10.10.10",\ "mcc": "1234",\ "merchant": "name",\ "mobileNumber": "+12037986508",\ "modules": [\ "firstpartyfraud"\ ],\ "nationalId": "70s0-01-3784",\ "parentTxnId": "e0201df4-c2b1-4bc8-8ed3-8328d36f2316",\ "physicalAddress": "2 Moran Ave",\ "physicalAddress2": "Address Line 2",\ "previousReferenceId": "ffc170f2-b3e4-423b-a373-5d6e1e9b23f8",\ "riskOSId": "Ananda_FPF-1761755062290",\ "state": "CT",\ "surName": "test",\ "transactionLocation": "domestic",\ "uniqueIdAccount": "2132",\ "uniqueIdTransaction": "421AED9B-4CC4-4ECA-9A0B-BB4E0554D9FB_036002247_1220594_2021-09-24_150",\ "uniqueIdUser": "20688849",\ "useCase": "application",\ "userId": "data-individual-id",\ "workflow": "api_individual_onboarding",\ "zip": "068100000"\ },\ "response": {\ "response": "{\"status\":\"Error\",\"referenceId\":\"1d7c4c8c-2445-4814-b4b5-de7f13614149\",\"data\":{\"parameters\":[\"Invalid nationalId. Please resubmit the transaction with a nationalID containing 4 or 9 numerical digits.\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid nationalId. Please resubmit the transaction with a nationalID containing 4 or 9 numerical digits.\"}"\ },\ "is_source_cache": false,\ "total_attempts": 1\ }\ ], "computed": { "CONDITION": false, "socure_sigmafirstpartyfraud_error": { "error_code": "EXTERNAL_ERROR", "error_msg": "{\"status\":\"Error\",\"referenceId\":\"1d7c4c8c-2445-4814-b4b5-de7f13614149\",\"data\":{\"parameters\":[\"Invalid nationalId. Please resubmit the transaction with a nationalID containing 4 or 9 numerical digits.\"]},\"customerProfile\":{\"customerUserId\":\"custom-customer_user_id\",\"userId\":\"data-individual-id\"},\"msg\":\"Invalid nationalId. Please resubmit the transaction with a nationalID containing 4 or 9 numerical digits.\"}", "http_status": 400, "is_retryable": false } }, "aggregations": { "device_ip": null, "device_ip_address": { "id": "" }, "ip_address": { "app_count_per_ip_12hr": 47, "app_count_per_ip_15day": 199, "app_count_per_ip_1day": 47, "app_count_per_ip_1hr": 8, "app_count_per_ip_1min": 1, "app_count_per_ip_30day": 301, "app_count_per_ip_30min": 9, "app_count_per_ip_60day": 494, "app_count_per_ip_7day": 135, "app_count_per_ip_90day": 677, "fraud_count_per_ip_12hr": 0, "fraud_count_per_ip_15day": 0, "fraud_count_per_ip_1day": 0, "fraud_count_per_ip_1hr": 0, "fraud_count_per_ip_1min": 0, "fraud_count_per_ip_30day": 0, "fraud_count_per_ip_30min": 0, "fraud_count_per_ip_60day": 0, "fraud_count_per_ip_7day": 0, "fraud_count_per_ip_90day": 0, "id": "10.10.10.10" }, "primary_email": { "app_count_per_email_12hr": 39, "app_count_per_email_15day": 229, "app_count_per_email_1day": 39, "app_count_per_email_1hr": 8, "app_count_per_email_1min": 1, "app_count_per_email_30day": 436, "app_count_per_email_30min": 9, "app_count_per_email_60day": 857, "app_count_per_email_7day": 129, "app_count_per_email_90day": 1314, "fraud_count_per_email_12hr": 0, "fraud_count_per_email_15day": 0, "fraud_count_per_email_1day": 0, "fraud_count_per_email_1hr": 0, "fraud_count_per_email_1min": 0, "fraud_count_per_email_30day": 0, "fraud_count_per_email_30min": 0, "fraud_count_per_email_60day": 0, "fraud_count_per_email_7day": 0, "fraud_count_per_email_90day": 0, "id": "j.smith@example.com" }, "primary_phone": { "app_count_per_phone_12hr": 47, "app_count_per_phone_15day": 200, "app_count_per_phone_1day": 47, "app_count_per_phone_1hr": 8, "app_count_per_phone_1min": 1, "app_count_per_phone_30day": 304, "app_count_per_phone_30min": 9, "app_count_per_phone_60day": 493, "app_count_per_phone_7day": 137, "app_count_per_phone_90day": 677, "fraud_count_per_phone_12hr": 0, "fraud_count_per_phone_15day": 0, "fraud_count_per_phone_1day": 0, "fraud_count_per_phone_1hr": 0, "fraud_count_per_phone_1min": 0, "fraud_count_per_phone_30day": 0, "fraud_count_per_phone_30min": 0, "fraud_count_per_phone_60day": 0, "fraud_count_per_phone_7day": 0, "fraud_count_per_phone_90day": 0, "id": "+12037986508" }, "ssn": { "app_count_per_ssn_12hr": 3, "app_count_per_ssn_15day": 4, "app_count_per_ssn_1day": 3, "app_count_per_ssn_1hr": 2, "app_count_per_ssn_1min": 1, "app_count_per_ssn_30day": 4, "app_count_per_ssn_30min": 2, "app_count_per_ssn_60day": 4, "app_count_per_ssn_7day": 4, "app_count_per_ssn_90day": 4, "fraud_count_per_ssn_12hr": 0, "fraud_count_per_ssn_15day": 0, "fraud_count_per_ssn_1day": 0, "fraud_count_per_ssn_1hr": 0, "fraud_count_per_ssn_1min": 0, "fraud_count_per_ssn_30day": 0, "fraud_count_per_ssn_30min": 0, "fraud_count_per_ssn_60day": 0, "fraud_count_per_ssn_7day": 0, "fraud_count_per_ssn_90day": 0, "id": "vault:v1:MXkx4tDbu4ExKBH8B2Y9yVp+16eeyx8KdKJ7gKqRYc8euOycp1aGIQ==" } }, "eval_status": "evaluation_completed", "environment_name": "Sandbox" } ``` ## Validation checklist [Skip link to Validation checklist](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#validation-checklist) ### Test coverage [Skip link to Test coverage](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#test-coverage) Known good identities → `ACCEPT` Bad or mismatched identities → `REJECT` or `REVIEW` Edge cases logged and reviewed ### Schema and error handling [Skip link to Schema and error handling](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#schema-and-error-handling) Fields match schema across environments Errors are structured and retryable Use exponential fallback with jitter for resubmissions ### Logging and observability [Skip link to Logging and observability](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#logging-and-observability) Log full request and response Include correlation IDs Redact secrets from logs ### Exception routing [Skip link to Exception routing](https://help.socure.com/riskos/docs/sigma-first-party-fraud-integration-guide\#exception-routing) Escalation paths defined for `REVIEW` Support team has access to logs and scores Updated about 2 months ago * * * Did this page help you? Yes No Copy Page