}
;
return inner;
};
Person verification (KYC — Know Your Customer) confirms that an individual is who they claim to be. Palm verifies identity against authoritative sources, detects synthetic identities, runs velocity checks, and screens against sanctions and watchlists.
***
## What KYC verification checks
* **Identity matching:** Palm compares the submitted name, date of birth, SSN, and address against authoritative sources. Each field is checked independently, so you get granular results — you'll know if the name matched but the address didn't.
* **Synthetic identity detection:** A synthetic identity is a fabricated identity built by combining real and fake data. A fraudster might pair a real SSN (often belonging to a child, elderly person, or recent immigrant) with a fake name and address. These identities can pass basic checks because some of the data is real. Palm detects synthetic identities by analyzing patterns across identity attributes that indicate fabrication.
* **Velocity checks:** Palm tracks how frequently identity attributes appear across recent verifications. If the same SSN shows up in different verification requests in a week, that could be a strong fraud signal — even if each individual verification looks clean. Velocity checks catch patterns that point-in-time checks miss, including application fraud rings and credit stacking (rapidly applying for credit across multiple lenders).
* **Watchlist screening:** Palm screens against sanctions lists (OFAC SDN list and international equivalents), Politically Exposed Person (PEP) databases, and adverse media sources. A sanctions match means the person appears on a government list of individuals with whom financial transactions are restricted or prohibited. A PEP match means the person holds (or recently held) a prominent public function. PEPs aren't necessarily risky, but they require enhanced due diligence under most compliance frameworks.
## What you get back
* **Match results:** How each submitted field compares against authoritative identity records (`match`, `no_match`, `partial_match`, or `not_checked`).
* **Risk assessment:** A risk level (`low`, `medium`, `high`, or `critical`) with specific risk signals that explain the assessment.
* **Synthetic identity detection:** Whether Palm detects indicators of a fabricated identity.
* **Velocity checks:** How frequently identity attributes appear across recent verifications.
* **Watchlist screening:** Sanctions, PEP, and adverse media results.
* **Verification status:** `pending`, `in_progress`, `completed`, or `failed`.
## When to use this
Use person verification during onboarding, before extending credit, or when confirming authorized signers. Common scenarios: verifying beneficial owners, confirming officers during underwriting, or validating authorized representatives.
You can also verify people as part of a business verification by including them as associates. See [Verify a business](/verify/verify-a-business).
## Quickstart
**Prerequisites**
* A Palm API key — [Get access](/get-started/get-access)
* The person's name, date of birth, SSN, and address
### Verify a person
Send a `POST` request to `/v1/user/verification`:
```bash wrap Bash theme={null}
curl -X POST https://api.getpalm.com/v1/user/verification \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk_test_...' \
-d '{
"workflow_key": "user_verification_default",
"first_name": "Jane",
"last_name": "Smith",
"date_of_birth": "1985-03-15",
"ssn": "123-45-6789",
"address_line_1": "100 Main Street",
"city": "San Francisco",
"region": "CA",
"postal_code": "94105"
}'
```
### Request fields
The minimum request requires a `workflow_key`, the person's name, date of birth, SSN, and address — this runs core identity matching. Beyond that, send every identity field you collect: optional fields each unlock additional fraud checks, so the more you send, the more complete the assessment.
If a check's input isn't provided, that check simply doesn't run — a missing input is **not** treated as a risk factor and won't appear in `risk.reasons`.
#### Optional fields and what they unlock
| Field | What it adds |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `phone_number` | Enables identity-theft risk scoring. If omitted, that check doesn't run and isn't counted for or against the result. |
| `email` | Adds email-based fraud and velocity signals. |
| `ip_address` | Adds device/connection risk signals (session-based verifications). |
If your workflow is tuned for a specific field set and you're unsure what to send, [contact us](mailto:support@getpalm.com) — we'll align your workflow with the data you collect.
For the full field reference, types, and validation rules, see the [API Reference](/api-reference/introduction).
### Response
A successful verification returns match results, risk assessment, and - if associates were included - individual KYC results for each owner:
```json wrap JSON theme={null}
{
"user_id": "usr_9b2c4d...",
"verification_id": "ver_3e5f7a...",
"status": "completed",
"risk": {
"level": "low",
"reasons": []
},
"match": {
"first_name": "match",
"last_name": "match",
"date_of_birth": "match",
"ssn": "match",
"address_line_1": "match",
"city": "match",
"region": "match",
"postal_code": "match"
},
"synthetic": {
"is_synthetic": false,
"confidence_score": 12
},
"velocity": {
"email": 1,
"phone": 1,
"ssn": 1,
"address": 2
},
"watchlist": {
"status": "clear"
},
"created_at": "2026-01-15T10:30:00Z"
}
```
### Understanding the response
| Field | Description |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id` | Palm's identifier for the verified person. Use this for re-verification and audit trails. |
| `verification_id` | Unique identifier for this verification run. |
| `status` | Where the verification is in its lifecycle. `completed` means results are ready. `failed` means a system error occurred — retry the request. |
| `risk.level` | Overall risk assessment: `low`, `medium`, `high`, or `critical`. The level reflects the verification outcome — an identity that can't be verified against authoritative sources is elevated rather than returned as `low`. It also escalates on watchlist hits, synthetic-identity flags, field match failures, and address or identity red flags (for example a commercial or mail-drop address, no established history at the address, multiple identities tied to one address, or a thin identity history). |
| `risk.reasons` | The genuine risk factors that drove the assessment. An empty array means none were found — read it alongside `risk.level`. Checks that couldn't run because an optional input wasn't provided are **not** listed here. Example: `["identity_theft_indicators", "high_fraud_score"]`. |
| `synthetic.is_synthetic` | Whether Palm detected indicators of a fabricated identity. `true` automatically escalates risk significantly. |
| `synthetic.confidence_score` | Score from 0–100. Higher means more likely synthetic. Scores above 50 are concerning; above 70 are strong indicators of fabrication. |
| `velocity` | Count of recent verifications using each identity attribute. An `ssn` count of 1 means this SSN has only been seen in this verification. A count of 5+ in a short period is a fraud signal. |
| `watchlist.status` | `clear` means no matches. `potential_match` means a possible hit that needs review. `confirmed_match` means a definitive match against a sanctions, PEP, or adverse media list. |
### Watchlist matches
When `watchlist.status` is `potential_match` or `confirmed_match`, the response includes match details:
```json wrap JSON theme={null}
{
"watchlist": {
"status": "potential_match",
"matches": [
{
"type": "pep",
"name": "tauxbe",
"confidence_score": 72
}
]
}
}
```
Each match includes a `type`:
* **`sanctions`:** OFAC SDN list and international sanctions lists. A confirmed sanctions match means you likely cannot do business with this person under US law. This is the most serious watchlist result.
* **`pep`:** Politically Exposed Person. The person holds or recently held a prominent public function. A PEP designation doesn't mean the person is risky — it means enhanced due diligence is required under most regulatory frameworks.
* **`adverse_media`:** Negative news coverage related to financial crime, fraud, or regulatory action. Adverse media hits provide context for risk decisions but aren't definitive on their own — they require human review.
The `confidence_score` (0–100) indicates how closely the watchlist record matches the submitted identity. Scores above 90 are high-confidence matches.
**Name-only matches.** PEP and adverse-media hits matched on name alone — without date-of-birth corroboration — are reported as `potential_match` with a confidence score rather than as confirmed matches, and don't inflate the risk level. This keeps common names from triggering false positives. Sanctions matches are treated as high priority.
## Match fields
KYC verification can return match results for these fields:
| Field | Description |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_name` | Legal name only — "Bob" won't match "Robert" and will return `no_match` or `partial_match`. |
| `last_name` | Hyphenated names and name changes (marriage) can cause `partial_match` results. |
| `middle_name` | Middle name, if provided. |
| `date_of_birth` | A `no_match` on DOB is a strong negative signal — dates of birth rarely have legitimate data entry errors. |
| `ssn` | An SSN `no_match` is the strongest single negative signal — it means the SSN either doesn't exist, belongs to someone else, or was recently issued and hasn't propagated to all sources. |
| `email` | Email match against known identity records. |
| `phone_number` | Phone number match. |
| `address_line_1` | Street address. People move frequently, so an address `no_match` on its own is less concerning than SSN or DOB mismatches. |
| `city` | City match. |
| `region` | State/region match. |
| `postal_code` | ZIP code match. |
Only fields included in the verification request appear in match results. For match result types and risk level details, see [Verification Reference](/verify/verification-reference).
## Re-verification
Existing users can be re-verified by passing the `user_id`. Palm retrieves the current data from the vault and runs verification against stored values:
```bash wrap Bash theme={null}
curl -X POST https://api.getpalm.com/v1/user/usr_9b2c4d.../verification \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk_test_...' \
-d '{
"workflow_key": "user_verification_default",
"reference_id": "reverify_67890"
}'
```
Re-verification is useful when compliance requirements change, when there's a suspicious identity signal, or on a scheduled basis.
## Webhooks
Subscribe to `user.verification.completed` to receive async notification when a verification finishes. Webhook payloads include the verification ID, risk level, and summary match results.
## Next steps
