> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lendflow.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Socure Fraud
## Socure Fraud
Use **Socure Fraud** to assess fraud and synthetic-identity risk for an individual. Lendflow sends the primary business owner's identity, contact, address, and business information to Socure and stores Socure's risk scores, identity-correlation scores, alert-list findings, and reason codes.
The Workflow Builder block is **Socure Fraud**, its service ID is `socure_fraud`, and it is available for **individual** entities in the **Fraud** block group.
## Requirements
Socure Fraud uses the primary business owner's information and the business legal name stored on the application. Every field marked required must be present and valid before Lendflow contacts Socure.
| Application field | Requirement | Notes |
| - | - | - |
| Primary owner's first name | Required | Must be a non-empty string. |
| Primary owner's last name | Required | Must be a non-empty string. |
| Primary owner's email address | Required | Must be a valid email address. |
| Primary owner's address country | Required | Must resolve to a valid country code. |
| Primary owner's street address | Required | Must be a non-empty string. |
| Primary owner's city | Required | Must be a non-empty string. |
| Primary owner's address state | Required | Must resolve to a valid state code. |
| Primary owner's ZIP code | Required | Must be a non-empty, valid ZIP code. |
| Primary owner's telephone | Required | Must pass Lendflow's U.S. phone-number validation. |
| Primary owner's SSN or ITIN | Required | Must be a valid SSN or ITIN. |
| Business legal name | Required | Must be a non-empty string. |
| Primary owner's date of birth | Required | Must be a valid date in `YYYY-MM-DD` format. |
| Primary owner's address line 2 | Optional | Additional address information. |
| Prequalification IP address | Optional | Must be a valid IPv4 or IPv6 address when present. |
The service does not treat address, email, telephone, SSN or ITIN, business
legal name, or date of birth as optional. If any required value is missing or
invalid, the run fails validation before a provider response is stored.
## API flow
### Start Socure Fraud
1. Call `PUT /api/applications/{application_id}/enrich` through [Enrich Business Credit Application](/api-reference/workflow-management/enrich-business-credit-application).
2. Set `provider` to `socure_fraud`.
3. Omit `options` or send an empty object. Socure Fraud does not require provider-specific options.
4. Omit `stage_id` unless you need to associate the run with a particular underwriting stage. When supplied, it must be the UUID of an underwriting stage in the application's current workflow.
5. Treat `{"data":{"onqueue":true}}` as confirmation that Lendflow queued the work, not that Socure completed it.
```json theme={"system"}
{
"provider": "socure_fraud",
"options": {},
"stage_id": "00000000-0000-4000-8000-000000000001"
}
```
You may omit both `options` and `stage_id`:
```json theme={"system"}
{
"provider": "socure_fraud"
}
```
### Retrieve status, response, and request data
Socure Fraud runs in a queued job. Poll [Get Commercial Data](/api-reference/workflow-management/get-commercial-data) until `data.statuses.socure.fraud` is `Success` or contains an error:
```http theme={"system"}
GET /api/applications/{application_id}/commercial_data?services[]=socure_fraud
```
The response exposes these Socure-specific paths:
| Result | API path | Type | Before a successful run |
| - | - | - | - |
| Latest service status | `data.statuses.socure.fraud` | string | `"Not yet started"` |
| Latest service date | `data.dates.socure_fraud` | string or null | `null` |
| Stored Socure response | `data.commercial_data.socure.fraud` | object or null | `null` |
| Sanitized request sent to Socure | `data.request_data.socure.fraud` | object or null | `null` |
The stored request is obfuscated by Lendflow. Use it to confirm which application values and Socure modules were used without exposing the complete SSN or ITIN.
## Data Orchestration availability and flow
Socure Fraud is available in Data Orchestration for individual applications. Its conditions can evaluate the returned address-risk, email-risk, phone-risk, synthetic-risk, and name-correlation scores.
1. In the Lendflow Dashboard, open **Builders > Data Orchestration**.
2. Create or edit a template and add **Socure Fraud** from the **Fraud** category.
3. Select the score that the condition should evaluate, configure the comparison, and connect each outcome.
4. Save and publish the template.
5. Call [Execute Data Orchestration](/api-reference/data-orchestration/execute-data-orchestration) at `POST /api/applications/{application_id}/data_orchestration/execute` with `template_id` and `application_id`. Include `stage_id` only when targeting a compatible workflow stage.
6. Treat `{"data":{"executed":true}}` as confirmation that Lendflow accepted the orchestration run, not as the completed Socure result.
7. Follow the run through [List Data Orchestration Logs](/api-reference/data-orchestration/list-data-orchestration-logs) and [Get Data Orchestration Log](/api-reference/data-orchestration/get-data-orchestration-log), and retrieve the provider payload through Get Commercial Data when needed.
Each Socure Fraud score has provider data as a prerequisite. If the application has no stored Socure Fraud record, Data Orchestration runs `socure_fraud` synchronously and then evaluates the returned score. If a record already exists, it satisfies the prerequisite and is reused by default. A returned `null` score is still a completed provider result and can be handled with a null condition; it is different from having no Socure Fraud record.
See [Data Orchestration](/product-guides/dashboard/data-orchestration/data-orchestration) for the complete template-building workflow.
## What the service returns
| Result area | Provider object | How to interpret it |
| - | - | - |
| Identity fraud | `fraud` | Contains one or more named fraud-model scores. The current response commonly identifies the model as `sigma`. A higher score indicates greater fraud risk. |
| Synthetic identity | `synthetic` | Contains one or more named synthetic-identity scores. A higher score indicates greater synthetic-identity risk. |
| Contact and address risk | `emailRisk`, `phoneRisk`, `addressRisk` | Each object scores the risk associated with the submitted value. Higher values indicate greater risk. |
| Identity correlation | `nameEmailCorrelation`, `namePhoneCorrelation`, `nameAddressCorrelation` | Each object scores the strength of the relationship between the submitted name and contact or address value. Higher values indicate stronger correlation. |
| Alert-list findings | `alertList` | Contains returned alert-list matches and explanatory reason codes. An empty `matches` array means Socure returned no matches for that request. |
| Provider traceability | `referenceId` | Identifies the Socure transaction for support and investigation. |
| Explanations | `reasonCodes` within each result object | Provides provider context for the corresponding result. Reason codes are not an independent pass or fail decision. |
### Representative response
The following sanitized response shows the major objects without reproducing a full provider payload:
```json theme={"system"}
{
"referenceId": "example-reference-id",
"fraud": {
"scores": [
{ "name": "sigma", "score": 0.461, "version": "3.0" }
],
"reasonCodes": ["I121"]
},
"synthetic": {
"scores": [
{ "name": "synthetic", "score": 0.1, "version": "2.0" }
],
"reasonCodes": ["R223"]
},
"emailRisk": {
"score": 0.01,
"reasonCodes": ["I520"]
},
"phoneRisk": {
"score": 0.01,
"reasonCodes": ["I620"]
},
"addressRisk": {
"score": 0.01,
"reasonCodes": ["I720"]
},
"nameEmailCorrelation": {
"score": 0.99,
"reasonCodes": ["I557"]
},
"namePhoneCorrelation": {
"score": 0.99,
"reasonCodes": ["I621"]
},
"nameAddressCorrelation": {
"score": 0.99,
"reasonCodes": ["I709"]
},
"alertList": {
"matches": [],
"reasonCodes": []
}
}
```
## Response attributes
### Fraud and synthetic-identity models
| Attribute | Type | Meaning | Possible values or units | When returned |
| - | - | - | - | - |
| `fraud` | object | Contains identity-fraud model results. | Object. | When Socure returns the requested fraud module. |
| `fraud.scores` | object\[] | Named fraud-model scores. | Array; it can be empty. | Within `fraud`. |
| `fraud.scores[].name` | string | Provider model name. | Commonly `sigma` in the current response shape. | For each returned model score. |
| `fraud.scores[].score` | number or null | Estimated identity-fraud risk. | Numeric score; higher means greater risk. | For each returned model; it can be `null` when Socure does not produce a score. |
| `fraud.scores[].version` | string or null | Provider model version. | Provider version string, such as `"3.0"`. | When supplied by Socure. |
| `fraud.reasonCodes` | string\[] | Codes explaining the fraud result. | Provider-defined codes; the array can be empty. | Within `fraud`. |
| `synthetic` | object | Contains synthetic-identity model results. | Object. | When Socure returns the requested synthetic module. |
| `synthetic.scores` | object\[] | Named synthetic-identity scores. | Array; it can be empty. | Within `synthetic`. |
| `synthetic.scores[].name` | string | Provider model name. | Commonly `synthetic` in the current response shape. | For each returned model score. |
| `synthetic.scores[].score` | number or null | Estimated risk that the submitted identity is synthetic. | Numeric score; higher means greater risk. | For each returned model; it can be `null` when Socure does not produce a score. |
| `synthetic.scores[].version` | string or null | Provider model version. | Provider version string, such as `"2.0"`. | When supplied by Socure. |
| `synthetic.reasonCodes` | string\[] | Codes explaining the synthetic-identity result. | Provider-defined codes; the array can be empty. | Within `synthetic`. |
### Contact and address risk
| Attribute | Type | Meaning | Possible values or units | When returned |
| - | - | - | - | - |
| `emailRisk` | object | Contains the email-risk score and reason codes. | Object. | When Socure returns the requested email-risk module. |
| `emailRisk.score` | number or null | Risk associated with the submitted email address. | Numeric score; higher means greater risk. | When Socure returns the email-risk module; it can be `null`. |
| `emailRisk.reasonCodes` | string\[] | Codes explaining the email-risk result. | Provider-defined codes; the array can be empty. | Within `emailRisk`. |
| `phoneRisk` | object | Contains the phone-risk score and reason codes. | Object. | When Socure returns the requested phone-risk module. |
| `phoneRisk.score` | number or null | Risk associated with the submitted telephone number. | Numeric score; higher means greater risk. | When Socure returns the phone-risk module; it can be `null`. |
| `phoneRisk.reasonCodes` | string\[] | Codes explaining the phone-risk result. | Provider-defined codes; the array can be empty. | Within `phoneRisk`. |
| `addressRisk` | object | Contains the address-risk score and reason codes. | Object. | When Socure returns the requested address-risk module. |
| `addressRisk.score` | number or null | Risk associated with the submitted physical address. | Numeric score; higher means greater risk. | When Socure returns the address-risk module; it can be `null`. |
| `addressRisk.reasonCodes` | string\[] | Codes explaining the address-risk result. | Provider-defined codes; the array can be empty. | Within `addressRisk`. |
### Identity correlations
| Attribute | Type | Meaning | Possible values or units | When returned |
| - | - | - | - | - |
| `nameEmailCorrelation` | object | Contains the name-to-email correlation score and reason codes. | Object. | When Socure returns this correlation result. |
| `nameEmailCorrelation.score` | number or null | Strength of the relationship between the submitted name and email address. | Numeric score; higher means stronger correlation. | When Socure returns the correlation; it can be `null`. |
| `nameEmailCorrelation.reasonCodes` | string\[] | Codes explaining the name-to-email result. | Provider-defined codes; the array can be empty. | Within `nameEmailCorrelation`. |
| `namePhoneCorrelation` | object | Contains the name-to-phone correlation score and reason codes. | Object. | When Socure returns this correlation result. |
| `namePhoneCorrelation.score` | number or null | Strength of the relationship between the submitted name and telephone number. | Numeric score; higher means stronger correlation. | When Socure returns the correlation; it can be `null`. |
| `namePhoneCorrelation.reasonCodes` | string\[] | Codes explaining the name-to-phone result. | Provider-defined codes; the array can be empty. | Within `namePhoneCorrelation`. |
| `nameAddressCorrelation` | object | Contains the name-to-address correlation score and reason codes. | Object. | When Socure returns this correlation result. |
| `nameAddressCorrelation.score` | number or null | Strength of the relationship between the submitted name and physical address. | Numeric score; higher means stronger correlation. | When Socure returns the correlation; it can be `null`. |
| `nameAddressCorrelation.reasonCodes` | string\[] | Codes explaining the name-to-address result. | Provider-defined codes; the array can be empty. | Within `nameAddressCorrelation`. |
### Alert list and request identity
| Attribute | Type | Meaning | Possible values or units | When returned |
| - | - | - | - | - |
| `alertList` | object | Contains alert-list matches and reason codes. | Object. | When Socure returns the requested alert-list module. |
| `alertList.matches` | array | Alert-list matches returned by Socure. | Provider match objects; an empty array means no match was returned. | When Socure returns the alert-list module. |
| `alertList.reasonCodes` | string\[] | Codes explaining the alert-list result. | Provider-defined codes; the array can be empty. | Within `alertList`. |
| `referenceId` | string | Socure's transaction identifier. | Provider-generated string. | On a provider response. |
### Score interpretation
The current integration and Dashboard treat Socure scores as numeric values on a zero-to-one scale. Examples in the stored response use values such as `0.01`, `0.461`, and `0.99`.
* For `fraud`, `synthetic`, `emailRisk`, `phoneRisk`, and `addressRisk`, a higher score represents greater risk.
* For name-correlation results, a higher score represents stronger correlation between the submitted identity elements.
* A score is provider evidence, not a Lendflow approval or decline decision. Define thresholds in your organization's policy and Data Orchestration conditions.
* `null` or a missing score means Socure did not return that score. It must not be interpreted as zero, low risk, or a failed API request.
Lendflow does not apply the historical thresholds or a fixed reason-code pass/fail policy in the service implementation. Review the complete returned objects and use the thresholds approved by your organization.
## Errors and statuses
| Signal | Meaning | Recommended action |
| - | - | - |
| HTTP `200` with `data.onqueue: true` | Lendflow accepted the enrichment request and queued the job. | Poll the commercial-data endpoint. |
| HTTP `401` | The Lendflow bearer token is missing or invalid. | Authenticate again and send a valid bearer token. |
| HTTP `403` | The authenticated user cannot enrich or view the application. | Use a token with the required application permissions. |
| HTTP `422` | The request has an invalid or unavailable provider, invalid options, or an invalid `stage_id`; application pre-validation can also reject the request. | Correct the request or application configuration before retrying. |
| `failed_at` is non-null | The queued service run failed. | Read `error`, correct the underlying issue, and start a new run. |
| `error` begins with `Validation failed:` | One or more required application values failed Socure request validation before the provider call. | Correct every listed application field before retrying. |
| `error` begins with `Socure error:` | Socure returned a non-success response. The message is derived from Socure's `msg` field. | Use the message and `referenceId`, when available, to correct the request or contact support. |
| Commercial-data status is `"Started"` | The queued job began but has not recorded a terminal result. | Continue polling. |
| Commercial-data status is `"Success"` | Lendflow stored the latest Socure response successfully. | Read `data.commercial_data.socure.fraud`. |
| Commercial-data status contains an error message | The job failed and the latest log message contains the failure reason. | Correct the reported validation, credential, or provider issue and retry. |
A provider finding, high risk score, reason code, or alert-list match is a completed fraud result. It is not the same as an API or execution failure.
## FAQ
Socure Fraud evaluates the application's primary business owner. The Workflow Builder block is available only for individual entities.
No. The current request validation requires the primary owner's email, country, street address, city, state, ZIP code, and U.S. telephone number. It also requires the owner's first and last name, SSN or ITIN, and date of birth, plus the business legal name. Address line 2 and the prequalification IP address are optional.
No. Set `provider` to `socure_fraud` and omit `options`, or send an empty object. Include `stage_id` only when you need to associate the run with a valid underwriting stage.
No. It means Lendflow queued an asynchronous job. Poll `data.statuses.socure.fraud` until it is `Success` or contains an error.
`data.commercial_data.socure.fraud` remains `null` until Lendflow stores a provider response. Inspect `data.statuses.socure.fraud` to distinguish a queued or running job from an error.
The selected score is marked as requiring provider data. Data Orchestration runs Socure Fraud synchronously to obtain that prerequisite, stores the response, and then evaluates the configured condition. Missing or invalid required application data causes that prerequisite run to fail.
A stored Socure Fraud record satisfies the score prerequisite and is reused by default. If your policy requires a fresh provider result, run `socure_fraud` again before evaluating the template.
No. A `null` or missing score means Socure did not return that score. Handle it explicitly with a null condition or a manual-review outcome; do not convert it to zero.
Not by themselves. Reason codes explain the associated provider result. Combine them with the returned scores, alert-list findings, and your organization's approved underwriting policy.