Skip to main content

Documentation Index

Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Identity Verification is the compliance primitive. Naive wraps Footprint behind 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 Footprint-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 Footprint 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.onefootprint.com/?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.onefootprint.com/?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.onefootprint.com/?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 (e.g. Doola).

​
Completing Verification (Validation Token)

After a member finishes KYC in the Footprint-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 Footprint session is created and the link is emailed to the member.

​
Member Statuses

StatusMeaning
pendingFootprint 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 Footprint 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_configuredFOOTPRINT_SECRET_KEY or FOOTPRINT_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_errorFootprint API errorRetry or check Footprint 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
    │   (Footprint 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 (e.g. Doola)