Skip to main content
Identity Verification is the compliance primitive. Naive’s KYC engine exposes a consistent API so agents can trigger KYC for every founder on a company formation, track each member’s verification status, and know exactly when all members are cleared for downstream processes like incorporation.

​
CLI First

# Start KYC for founders/members
naive verification start --members '[{"first_name":"Alice","last_name":"Smith","email":"alice@example.com","ownership_percentage":100,"role":"primary","is_responsible_party":true}]'

# Track status
naive verification list
naive verification status <verification-id>

​
Tools

ToolTypeDescriptionCost
start_verificationCoreStart KYC for a set of members with ownership percentagesFree
get_verificationInfoGet verification status + all member statusesFree
list_verificationsInfoList all verifications for the companyFree
complete_member_verificationCoreSubmit validation token after in-browser KYCFree
resend_verification_linkCoreResend/regenerate a member’s KYC linkFree

​
How It Works

  1. Start verification — provide members with names, emails, ownership percentages, and responsible party designation
  2. Primary member gets their hosted KYC link returned immediately in the response
  3. Secondary members are emailed their KYC links automatically
  4. Each member completes KYC in their browser (ID scan, selfie, SSN, address)
  5. Status updates arrive via verification webhooks or the validation token endpoint
  6. When all members pass, ready_for_formation becomes true

​
Starting Verification

curl -X POST https://api.usenaive.ai/v1/verification \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      {
        "first_name": "Alice",
        "last_name": "Smith",
        "email": "alice@example.com",
        "phone_number": "+15551234567",
        "ownership_percentage": 60,
        "role": "primary",
        "is_responsible_party": true
      },
      {
        "first_name": "Bob",
        "last_name": "Jones",
        "email": "bob@example.com",
        "ownership_percentage": 40,
        "role": "secondary",
        "is_responsible_party": false
      }
    ]
  }'
Response (201): 
{
  "id": "verification-uuid",
  "status": "in_progress",
  "primary_link": "https://verify.usenaive.ai/?type=user#obtok_xxx",
  "members": [
    {
      "id": "member-uuid-1",
      "role": "primary",
      "is_responsible_party": true,
      "first_name": "Alice",
      "last_name": "Smith",
      "email": "alice@example.com",
      "ownership_percentage": 60,
      "status": "link_ready",
      "link": "https://verify.usenaive.ai/?type=user#obtok_xxx"
    },
    {
      "id": "member-uuid-2",
      "role": "secondary",
      "is_responsible_party": false,
      "first_name": "Bob",
      "last_name": "Jones",
      "email": "bob@example.com",
      "ownership_percentage": 40,
      "status": "link_sent",
      "link": "https://verify.usenaive.ai/?type=user#obtok_yyy"
    }
  ]
}

​
Member Parameters

ParamTypeRequiredDescription
first_namestringYesLegal first name
last_namestringYesLegal last name
emailstringYesEmail address (used for KYC link delivery)
phone_numberstringNoPhone number in E.164 format
ownership_percentageintegerYes0-100, must sum to 100 across all members
rolestringYes"primary" (exactly one) or "secondary"
is_responsible_partybooleanYesIRS-facing person for formation (exactly one must be true)

​
Validation Rules

  • At least one member is required
  • Exactly one member must have role: "primary"
  • Exactly one member must have is_responsible_party: true
  • Ownership percentages must sum to exactly 100

​
Checking Status

curl https://api.usenaive.ai/v1/verification/verification-uuid \
  -H "Authorization: Bearer nv_sk_your_key"
Response: 
{
  "id": "verification-uuid",
  "status": "in_progress",
  "ready_for_formation": false,
  "members": [
    { "id": "member-uuid-1", "status": "pass", "email": "alice@example.com" },
    { "id": "member-uuid-2", "status": "link_sent", "email": "bob@example.com" }
  ]
}
ready_for_formation is true only when every member has status: "pass". This is the gate signal for downstream formation.

​
Completing Verification (Validation Token)

After a member finishes KYC in the hosted flow, the embedded SDK provides a validationToken. Submit it to get immediate status confirmation without waiting for the webhook: 
curl -X POST https://api.usenaive.ai/v1/verification/members/member-uuid/complete \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"validation_token": "valtok_xxx"}'
If a member’s link expires or they lost the email: 
curl -X POST https://api.usenaive.ai/v1/verification/members/member-uuid/resend \
  -H "Authorization: Bearer nv_sk_your_key"
A new KYC session is created and the link is emailed to the member.

​
Member Statuses

StatusMeaning
pendingKYC session not yet created (usually a transient error)
link_readyKYC link generated but not emailed (primary member — link in API response)
link_sentKYC link emailed to the member
in_progressMember started but hasn’t finished KYC
passIdentity verified successfully
failIdentity verification failed
incompleteMember abandoned the KYC flow
pending_reviewFlagged for manual review in the KYC dashboard

​
Verification Statuses

StatusMeaning
pendingJust created, sessions being generated
in_progressAt least one member hasn’t completed KYC
completedAll members passed
failedAt least one member failed

​
Error Handling

ErrorCauseRecovery
feature_not_configuredKYC_SECRET_KEY or KYC_PLAYBOOK_KEY not setConfigure env vars
invalid_inputValidation failed (percentages, roles, emails)Fix input per validation rules
resource_not_foundVerification or member UUID not foundCheck UUIDs
provider_errorVerification provider errorRetry or check the KYC dashboard

​
Typical Workflow

Agent receives task: "Set up identity verification for company incorporation"
    │
    ├─ POST /v1/verification                        → Start KYC for all founders
    │   { members: [{ role: "primary", ... }, { role: "secondary", ... }] }
    │   → verification_id, primary_link
    │
    ├─ Primary founder opens link in browser         → Completes KYC
    │
    ├─ POST /v1/verification/members/:id/complete    → Submit validation token
    │   → status: "pass"
    │
    ├─ Secondary members receive email               → Complete KYC via link
    │   (verification webhook updates their status)
    │
    ├─ GET /v1/verification/:id                      → Check progress
    │   → ready_for_formation: false (1/2 verified)
    │
    ├─ GET /v1/verification/:id                      → Check again
    │   → ready_for_formation: true (all verified)
    │
    └─ Ready for formation submission