Skip to main content
POST
/
v1
/
user
/
verification
Verify user identity
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    workflow_key: 'user_verification_default',
    first_name: 'John',
    last_name: 'Doe',
    date_of_birth: '1990-01-15',
    ssn: '123-45-6789',
    address_line_1: '123 Main St',
    city: 'San Francisco',
    region: 'CA',
    postal_code: '94102',
    reference_id: 'user_12345',
    middle_name: 'A',
    email: 'john.doe@example.com',
    phone_number: '+15551234567',
    address_line_2: 'Apt 4B',
    country: 'US',
    metadata: {external_id: 'user_789', source: 'web_application'}
  })
};

fetch('https://api.getpalm.com/v1/user/verification', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "660f9511-f30c-52e5-b827-557766551111",
  "status": "completed",
  "risk": {
    "level": "low",
    "reasons": [
      "SSN first seen recently in bureau data",
      "Address mismatch detected",
      "High velocity on phone number (5 applications in 24 hours)",
      "Device fingerprint associated with known fraud",
      "Synthetic identity indicators detected with 85% confidence"
    ]
  },
  "match": {
    "first_name": "match",
    "last_name": "match",
    "middle_name": "match",
    "date_of_birth": "match",
    "ssn": "match",
    "email": "match",
    "phone_number": "match",
    "address_line_1": "match",
    "address_line_2": "match",
    "city": "match",
    "region": "match",
    "postal_code": "match"
  },
  "created_at": "2025-10-24T10:30:00Z",
  "reference_id": "user_12345",
  "synthetic": {
    "is_synthetic": false,
    "confidence_score": 15,
    "indicators": [
      "SSN issued after applicant date of birth",
      "Credit file recently established"
    ]
  },
  "velocity": {
    "email": 1,
    "phone": 2,
    "ssn": 1,
    "address": 3
  },
  "device": {
    "risk_score": 10,
    "is_emulator": false,
    "is_vpn": false,
    "is_proxy": false
  },
  "watchlist": {
    "status": "clear",
    "matches": [
      {
        "type": "sanctions",
        "name": "ofac_sdn",
        "confidence_score": 85
      }
    ]
  },
  "updated_at": "2025-10-24T10:35:00Z"
}

Authorizations

​
Authorization
string
header
required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Body

application/json
​
workflow_key
string
default:user_verification_default
required

Workflow key to use for verification (determines required fields)

Pattern: ^[a-z0-9_]+$
Example:

"user_verification_default"

​
first_name
string
required

First name

Example:

"John"

​
last_name
string
required

Last name

Example:

"Doe"

​
date_of_birth
string<date>
required

Date of birth (YYYY-MM-DD)

Example:

"1990-01-15"

​
ssn
string
required

Social Security Number

Example:

"123-45-6789"

​
address_line_1
string
required

Street address line 1

Example:

"123 Main St"

​
city
string
required

City

Example:

"San Francisco"

​
region
string
required

Region (state/province/county)

Example:

"CA"

​
postal_code
string
required

Postal code

Example:

"94102"

​
reference_id
string

Your reference ID for tracking

Example:

"user_12345"

​
middle_name
string

Middle name or initial

Example:

"A"

​
email
string

Email address

Example:

"john.doe@example.com"

​
phone_number
string

Phone number

Example:

"+15551234567"

​
address_line_2
string

Street address line 2

Example:

"Apt 4B"

​
country
string

Country (2-letter ISO code)

Example:

"US"

​
metadata
object

Custom metadata

Example:
{
  "external_id": "user_789",
  "source": "web_application"
}

Response

Verification completed

​
user_id
string<uuid>
required

ID of the user entity created or verified

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
verification_id
string<uuid>
required

Unique verification ID

Example:

"660f9511-f30c-52e5-b827-557766551111"

​
status
enum<string>
required

Current status of the verification

Available options:
pending,
in_progress,
completed,
failed
Example:

"completed"

​
risk
object
required

Risk assessment with level and detailed reasons

​
match
object
required

Field-level match results (only fields included in verification request)

​
created_at
string<date-time>
required

ISO 8601 timestamp of when the verification was created

Example:

"2025-10-24T10:30:00Z"

​
reference_id
string

Your reference ID (if provided in request)

Example:

"user_12345"

​
synthetic
object

Synthetic identity detection results

​
velocity
object

Velocity checks showing frequency of identity attributes across recent requests

​
device
object

Device intelligence (available for session-based verifications)

​
watchlist
object

Watchlist screening results (sanctions, PEP, adverse media)

​
updated_at
string<date-time>

ISO 8601 timestamp of when the verification was last updated

Example:

"2025-10-24T10:35:00Z"