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));

import requests

url = "https://api.getpalm.com/v1/user/verification"

payload = {
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.getpalm.com/v1/user/verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "660f9511-f30c-52e5-b827-557766551111",
  "status": "completed",
  "mode": "live",
  "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": {},
  "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"
}

{
  "type": "https://api.getpalm.com/problems/validation_error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/business/registry/search",
  "errors": [
    {
      "field": "name",
      "message": "name should not be empty",
      "code": "NOT_EMPTY"
    }
  ]
}

{
  "type": "https://api.getpalm.com/problems/authentication_error",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid authentication provided. Please provide one of the accepted authentication methods.",
  "instance": "/business/registry/search"
}

{
  "type": "https://api.getpalm.com/problems/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 60 seconds.",
  "instance": "/business/registry/search",
  "retry_after": 60,
  "limit": 100000,
  "remaining": 0,
  "reset": 1738540800
}

{
  "type": "https://api.getpalm.com/problems/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal server error occurred. Please contact support if this persists.",
  "instance": "/business/registry/search"
}

POST

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));

import requests

url = "https://api.getpalm.com/v1/user/verification"

payload = {
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.getpalm.com/v1/user/verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "660f9511-f30c-52e5-b827-557766551111",
  "status": "completed",
  "mode": "live",
  "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": {},
  "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"
}

{
  "type": "https://api.getpalm.com/problems/validation_error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/business/registry/search",
  "errors": [
    {
      "field": "name",
      "message": "name should not be empty",
      "code": "NOT_EMPTY"
    }
  ]
}

{
  "type": "https://api.getpalm.com/problems/authentication_error",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid authentication provided. Please provide one of the accepted authentication methods.",
  "instance": "/business/registry/search"
}

{
  "type": "https://api.getpalm.com/problems/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 60 seconds.",
  "instance": "/business/registry/search",
  "retry_after": 60,
  "limit": 100000,
  "remaining": 0,
  "reset": 1738540800
}

{
  "type": "https://api.getpalm.com/problems/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal server error occurred. Please contact support if this persists.",
  "instance": "/business/registry/search"
}

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"

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.

In test mode (sk_test_ key), the reserved key _simulate drives a deterministic outcome without calling the identity provider. Value is one of:

Risk levels: low (default), medium, high, critical
Scenarios: synthetic, watchlist, dob_mismatch, no_match
fail → terminal status: failed

When _simulate is omitted, the reserved test SSNs still drive the outcome. Ignored in live mode.

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"

mode

enum<string>

required

Test/live partition the verification was created under. Determined by the API key used.

Available options:

test,

live

Example:

"live"

risk

object

required

Risk assessment with level and detailed reasons

Show child attributes

match

object

required

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

Show child attributes

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

Show child attributes

velocity

object

Velocity checks showing frequency of identity attributes across recent requests

Show child attributes

device

object

Device intelligence (available for session-based verifications)

Show child attributes

watchlist

object

Watchlist screening results (sanctions, PEP, adverse media)

Show child attributes

updated_at

string<date-time>

ISO 8601 timestamp of when the verification was last updated

Example:

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

Verify TIN

Get business monitoring subscription status

⌘I