Identity Verification API - KYC, Fraud and Risk Scores

Give it what you hold about a person - a name, an address, an email, a phone number, a date of birth - and get back whether those things belong together, how risky each one is, and a decision you can route on. One flat row per identity.

What this actor does

• Runs KYC and fraud scoring in a single call. Name, address, date of birth and national ID matching, an identity fraud score, synthetic identity detection, and separate risk scores for the email address, the phone number and the address, all from one submission of one identity.
• Answers the correlation question, not just the validity question. An email address can be perfectly real and still not belong to the person claiming it. This provider scores name to address, name to phone and name to email correlation separately, which is the difference between checking that a detail exists and checking that it fits.
• Returns a decision, not just numbers. When the decision module is enabled, your account's own rules are applied and the row comes back as accept, review or reject. Filter to reviews and you have a work queue; filter to rejects and you have an action list.
• Pools the reason codes. Every module reports its own reason codes for why it scored the way it did. In practice the question is what the evaluation objected to rather than which module objected, so they are gathered into one sorted list per row, with the per-module breakdown still available in the raw column.
• Speaks to both API generations. This provider runs two side by side: an older one that takes an explicit list of modules, and a newer one that runs a workflow configured in your dashboard. They use different hosts, different credential schemes and different request shapes. This actor accepts one neutral identity shape and translates it into whichever one your key belongs to.
• Handles per-account licensing gracefully. Modules are licensed individually, and one your account does not hold comes back empty rather than as an error. That leaves its columns blank instead of breaking the row, and the complete provider response is always kept in the raw column.
• Refuses empty records before they cost anything. An identity with no fields filled in costs a request and can only come back empty, so it is refused locally and recorded as a refusal.
• Names the environment in credential errors. The sandbox is a separate host rather than a flag, and sandbox credentials are refused by production with the same message a wrong key gets. When that happens, the error here says which environment and which generation the run used.
• Never charges for a miss. Only rows carrying an evaluation are billed.

Input

Field	What it does
identities	The people to evaluate, as a JSON array of objects.
platform	Which API generation to call: modules or workflow.
environment	Production or sandbox.
modules	Which checks to run on the modules endpoint.
extraModules	Any other module names your account is licensed for.
workflow	The workflow identifier, on the workflow endpoint.
decisions	Keep only accept, review, reject, refer or resubmit rows.
minFraudScore	Keep only rows scoring at or above this.
maxFraudScore	Keep only rows scoring at or below this.
maxEmailRiskScore	Keep only rows with email risk at or below this.
maxPhoneRiskScore	Keep only rows with phone risk at or below this.
maxAddressRiskScore	Keep only rows with address risk at or below this.
excludeReasonCodes	Drop rows carrying these reason codes.
requireReasonCodes	Keep only rows carrying these reason codes.
requestsPerMinute	Pace the run under your contract's rate limit.
skipNotFound	Leave misses and refusals out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own API key. Stored as a secret.

Example output

{
  "found": true,
  "platform": "modules",
  "query": "jane.doe@example.com",
  "email": "jane.doe@example.com",
  "mobileNumber": "12065550100",
  "fullName": "Jane Doe",
  "referenceId": "123a456b-789c-1234-567c-9307e6e0a83f",
  "decision": "accept",
  "fraudScore": 0.167,
  "fraudModelName": "sigma",
  "syntheticScore": 0.04,
  "emailRiskScore": 0.011,
  "phoneRiskScore": 0.002,
  "addressRiskScore": 0.364,
  "nameAddressCorrelation": 0.9096,
  "namePhoneCorrelation": 0.9984,
  "nameEmailCorrelation": 0.9791,
  "kycDecision": "REFER",
  "kycConfidence": 0,
  "kycFieldValidations": {
    "firstName": 0.99,
    "surName": 0.99,
    "streetAddress": 0.99,
    "city": 0.99,
    "state": 0.99,
    "zip": 0.99,
    "mobileNumber": 0.99,
    "dob": 0.99
  },
  "reasonCodes": ["I127", "I553", "I602", "I610", "I618", "I626", "I705", "I708"],
  "modulesReturned": ["nameAddressCorrelation", "namePhoneCorrelation", "fraud", "kyc", "addressRisk", "emailRisk"],
  "error": null,
  "raw": { }
}

Frequently asked questions

What is the difference between the modules endpoint and the workflow endpoint?

They are two generations of this provider's API running side by side, not two settings of one API. The modules endpoint takes an explicit list of what to evaluate in the request itself, so the run decides what happens. The workflow endpoint names a workflow you built in the provider's dashboard, so the dashboard decides what happens and the request just supplies the person. They use different hosts and different credential schemes, and a key issued for one is refused by the other exactly like a wrong key. If you are unsure, start with the modules endpoint.

Which modules should I turn on?

Only the ones you need, because each is licensed and billed separately and every extra module costs money on every identity. As a starting point: emailrisk or phonerisk alone is enough to screen a signup list; add kyc when you need to confirm a name, address and date of birth actually belong together; add fraud for an overall identity risk score; add synthetic when fabricated identities are the specific worry; add decision to have your own account rules applied and get an accept, review or reject back rather than raw numbers.

What happens if I ask for a module my account does not have?

Its block simply does not appear in the response, so the corresponding columns come back blank. It is not an error and it does not stop the run, which is convenient but also means a column of nulls can mean either "the module found nothing" or "you are not licensed for this". The modulesReturned column lists which blocks actually came back, so you can tell the two apart at a glance.

What do the scores mean?

They run from zero to one, where higher is riskier. That is a different scale from most fraud APIs, which use zero to one hundred, so a threshold copied from elsewhere will behave very strangely here. The correlation scores read the other way round: those are confidence that two details belong to the same person, so higher is better. The filters in this actor use the provider's own scale in both cases.

What are reason codes and why are they pooled into one column?

Reason codes are the specific findings behind a score, such as the email domain being newly registered or the address being a mail drop. Each module reports its own list. This actor gathers them all into one sorted column per row, because the practical question when reading a result is what the evaluation objected to rather than which module raised it. If you need the per-module attribution, it is preserved in the raw column. You can also filter on them directly, which is the right tool when a score threshold is too blunt.

Why does correlation matter more than validity?

Because most fraud uses real details. A stolen identity has a valid name, a valid address and a valid phone number, and every one of those checks out on its own. What does not check out is the combination: the phone number has no history with that name, or the person has never been associated with that address. Correlation scoring is what catches that, and it is the reason this kind of API exists rather than just a set of separate validators.

Do I have to write JSON to use this?

Only if you want the full identity. The identities field takes a JSON array of objects, which is what you need for name, address and date of birth checks. But a bare string in that list is read as an email address if it contains an at sign and as a phone number otherwise, so screening a plain list of contacts works without writing any JSON at all.

Why do I keep getting told my API key is invalid when it is not?

Almost always the environment or the generation. The sandbox is a separate host rather than a flag, so a sandbox key is refused by production with the same message a wrong key gets, and the same applies between the two API generations. Check that the environment and platform settings match the key you pasted in. The credential error from this actor names both, so the message tells you what to compare.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API key from Socure, which is the provider whose identity verification API this actor calls, taken from your provider dashboard and pasted into the apiKey field, where it is stored as an Apify secret. Your own contract, licensed modules and terms apply, and note that this provider licenses each module separately.

What happens when an identity returns nothing?

A negative verdict is a result, not a miss: the provider telling you a name and address do not correlate is exactly the question you asked, so that row is written and billed like any other. A miss is an identity the provider would not evaluate at all, and a refusal is an entry that never left this actor. Both are written with found: false and never billed. Set skipNotFound to true to leave them out entirely.

How much does a run cost?

Pricing is pay per result: you are charged for each identity evaluated into the dataset, and never for misses, for locally refused entries, for rows dropped by the filters, or for duplicates. Apify platform usage is included in the per-result price. Your own provider contract is separate and billed by them, per module.

Keyword map

identity verification API, KYC API, know your customer API, identity fraud detection, synthetic identity detection, email risk score, phone risk score, address risk score, name address correlation, identity resolution API, AML screening, watchlist screening API, customer onboarding verification, account opening fraud, first party fraud detection, third party fraud detection, digital identity verification, age verification API, SSN verification, date of birth verification, reason codes, risk decisioning API, accept review reject decision, fintech onboarding API, bank account opening KYC, identity graph API