API Reference

Developer Documentation

Everything you need to integrate verification into your platform.

Partner API

For WageGate and channel partners — provision companies and trigger verifications on their behalf.

Version 1.0

Overview

This API is for channel partners (like WageGate) who build and operate their own platform UI. Your end-users — lenders, mortgage companies, and financial institutions — log into your platform. Your platform calls WageGate APIs on their behalf.

You handle

Your end-users' experience and interface
Provisioning company accounts under your partner umbrella
Triggering verifications on behalf of your companies
Displaying results, managing billing, and handling webhooks

WageGate handles

Borrower-facing hosted verification flows
Document capture and income/employment analysis (via WageGate)
Metered billing and usage tracking
API key lifecycle management

Authentication

All API calls require a partner-level API key passed in the x-api-key header.

Header

x-api-key: tvos_partner_xxxxxxxxxxxxxxxx

Contact your WageGate account manager to receive your partner API key.

Base URL

https://storefront-os.replit.app

Company Management

Provision a Company Account

Creates a new company (lender) account under your partner umbrella. Returns an API key for that company and provisions their login credentials.

POST /api/partner/companies

curl -X POST https://storefront-os.replit.app/api/partner/companies \
  -H "x-api-key: <your-partner-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Lending",
    "contact_name": "Jane Doe",
    "contact_email": "contact@acmelending.com",
    "phone": "555-123-4567"
  }'

Field	Type	Status	Notes
company_name	string	Required	Legal or DBA name
contact_name	string	Required	Primary contact full name
contact_email	string	Required	Used for login + notifications
phone	string	Required	Primary contact phone

201 Created

{
  "company_id": "acme-lending",
  "api_key": "tvos_sub_xxxxxxxxxxxxxxxx",
  "login_email": "contact@acmelending.com",
  "temp_password": "Xk9#mQzP2v",
  "status": "active",
  "created_at": "2026-04-19T00:00:00Z"
}

The temp_password is shown once. Store it or relay it to the company immediately.

List Your Companies

GET /api/partner/companies

{
  "companies": [
    {
      "company_id": "acme-lending",
      "company_name": "Acme Lending",
      "contact_email": "contact@acmelending.com",
      "status": "active",
      "verifications_this_month": 47,
      "created_at": "2026-01-15T00:00:00Z"
    }
  ]
}

Update a Company Account

PATCH /api/partner/companies/:company_id

{
  "status": "suspended",
  "contact_email": "new@acmelending.com"
}

Run a Verification — Send to Borrower

Initiates a borrower-assisted verification. WageGate generates a secure link and sends it to the borrower via email. The borrower completes the hosted flow; results are delivered via webhook when complete.

POST /api/partner/verifications

curl -X POST https://storefront-os.replit.app/api/partner/verifications \
  -H "x-api-key: <your-partner-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "company_api_key": "tvos_sub_xxxxxxxxxxxxxxxx",
    "borrower_name": "Jane Smith",
    "borrower_email": "jane@example.com",
    "employer_name": "Acme Corp",
    "verification_type": "income_employment",
    "borrower_work_email": "jane@acmecorp.com",
    "reference_id": "LOAN-2026-00441"
  }'

Field	Type	Status	Notes
company_api_key	string	Required	The company's tvos_sub_xxx key
borrower_name	string	Required	Full name of the borrower
borrower_email	string	Required	Where the verification link is sent
employer_name	string	Required	Borrower's employer
verification_type	enum	Required	income_employment
borrower_work_email	string	Optional	Optional; improves match rate
reference_id	string	Optional	Your internal loan/file ID; passed through to results and webhooks; not used by the verification engine

201 Created

{
  "verification_id": "ver_abc123",
  "status": "pending",
  "borrower_link": "https://storefront-os.replit.app/verify/ver_abc123",
  "expires_at": "2026-04-26T00:00:00Z"
}

The borrower link is unique and single-use. It expires in 7 days.

Get Verification Result

GET /api/partner/verifications/:verification_id

{
  "verification_id": "ver_abc123",
  "status": "complete",
  "reference_id": "LOAN-2026-00441",
  "result": {
    "employer": "Acme Corp",
    "employment_status": "active",
    "income_annual": 87000,
    "income_period": "annual",
    "confidence": 0.97,
    "acceptance": "accepted",
    "verified_at": "2026-04-20T14:33:00Z"
  }
}

Status values: pending · in_progress · complete · failed · expired

List Verifications for a Company

GET /api/partner/verifications

GET /api/partner/verifications?company_id=acme-lending

# Optional query params: status, from_date, to_date, limit, offset

Webhooks

WageGate will POST to your registered webhook URL when a verification completes or fails.

Register a Webhook

POST /api/partner/webhooks

{
  "url": "https://your-platform.com/webhooks/wagegate",
  "events": ["verification.complete", "verification.failed"]
}

Webhook Payload — verification.complete

{
  "event": "verification.complete",
  "verification_id": "ver_abc123",
  "company_id": "acme-lending",
  "reference_id": "LOAN-2026-00441",
  "result": {
    "employer": "Acme Corp",
    "employment_status": "active",
    "income_annual": 87000,
    "confidence": 0.97,
    "acceptance": "accepted",
    "verified_at": "2026-04-20T14:33:00Z"
  }
}

All webhook requests include:

X-VOS-Signature header — HMAC-SHA256 of the raw body using your webhook secret
X-VOS-Event header — event type string
Respond 200 within 10 seconds; WageGate will retry 3x on failure

Usage & Billing

Get Usage Summary

GET /api/partner/usage

GET /api/partner/usage?company_id=acme-lending&month=2026-04

{
  "company_id": "acme-lending",
  "period": "2026-04",
  "verifications_completed": 47,
  "verifications_pending": 3,
  "wholesale_cost_cents": 4700,
  "retail_rate_cents": 150
}

wholesale_cost_cents is what WageGate bills you. retail_rate_cents is your configured markup — what you charge your companies is your business.

Error Reference

Code	Meaning
400	Bad request — missing or invalid fields
401	Invalid or missing API key
403	Your key does not have access to this resource
404	Verification or company not found
409	Company with this email already exists
429	Rate limit exceeded
500	Internal server error

All errors return:

{
  "error": "human_readable_code",
  "message": "Descriptive message about what went wrong"
}

Going Live Checklist

Receive your partner API key from your WageGate account manager
Register your webhook URL
Provision your first company account and verify login works
Submit a test verification and confirm webhook delivery
Set up Stripe billing for your account
Deploy to production

Questions? Contact your WageGate account manager.