API Reference

Base URL: https://api.maverick-ins.com/api/v1

Authentication: All endpoints require Authorization: Bearer <token> unless marked Public.

Swagger UI: https://api.maverick-ins.com/docs

Endpoint Groups

---

Jobs

Prefix: /jobs | Auth: Admin

POST /api/v1/jobs/scrape

Create a new Xpressdocs scraping job.

Response model: ScrapingJobResponse

GET /api/v1/jobs/{job_id}

Get status of a specific scraping job.

Response model: ScrapingJobResponse

GET /api/v1/jobs

List scraping jobs with optional filtering.

Response model: List

GET /api/v1/jobs/{job_id}/details

Get enhanced details for a specific scraping job.

Response model: JobDetailsResponse

GET /api/v1/jobs/{job_id}/logs

Get detailed logs for a specific job.

Response model: List

DELETE /api/v1/jobs/{job_id}

Cancel a pending or running scraping job.

GET /api/v1/jobs/stats/overview

Get overall job statistics.

DELETE /api/v1/jobs/{job_id}/permanent

Permanently delete a scraping job and its associated data.

POST /api/v1/jobs/{job_id}/restart

Restart a failed or cancelled job in-place.

Response model: ScrapingJobResponse

---

Contacts

Prefix: /contacts | Auth: Admin

GET /api/v1/contacts/

List contacts with filtering, search, and pagination.

Response model: ContactListResponse

GET /api/v1/contacts/stats

Get contact statistics.

Response model: ContactStats

POST /api/v1/contacts/

Create a new contact.

PUT /api/v1/contacts/{contact_id}

Update a contact.

DELETE /api/v1/contacts/{contact_id}

Delete a contact.

POST /api/v1/contacts/upload

Upload contacts via CSV file.

Response model: UploadResponse

GET /api/v1/contacts/export/csv

Export contacts as CSV.

POST /api/v1/contacts/{contact_id}/assign

Assign a contact to a different workspace.

GET /api/v1/contacts/verified

List verified contacts with filtering, search, and pagination.

Response model: ContactListResponse

GET /api/v1/contacts/verified/stats

Get verified contact statistics.

Response model: VerifiedContactStats

GET /api/v1/contacts/verified/{contact_id}

Get a single verified contact by ID.

GET /api/v1/contacts/verified/export/csv

Export verified contacts as CSV.

GET /api/v1/contacts/{contact_id}

Get a single contact by ID.

POST /api/v1/contacts/filter

Trigger contact filtering worker for a workspace.

POST /api/v1/contacts/verify

Trigger email verification worker for a workspace.

GET /api/v1/contacts/verification/bulk/jobs/latest

Get the latest bulk verification job for a workspace.

GET /api/v1/contacts/verification/bulk/jobs/{job_id}

Get status of a specific bulk verification job.

POST /api/v1/contacts/verification/resume

Resume a pending bulk verification job.

POST /api/v1/contacts/verification/reset-stuck

Reset contacts stuck in 'verifying' status back to 'ready_for_verification'.

---

Batches

Prefix: /batches | Auth: Admin

GET /api/v1/batches/

List weekly batches with filtering and pagination.

Response model: BatchListResponse

GET /api/v1/batches/stats

Get batch statistics.

Response model: BatchStats

GET /api/v1/batches/{batch_id}

Get batch details including associated contacts.

POST /api/v1/batches/generate

Generate monthly batch for a workspace.

POST /api/v1/batches/generate-all

Generate weekly batches for all workspaces.

POST /api/v1/batches/upload-all-pending

Atomically generate batches and upload all pending batches to Email Bison.

POST /api/v1/batches/{batch_id}/upload

Upload a batch to Email Bison.

POST /api/v1/batches/{batch_id}/retry

Retry uploading a failed batch to Email Bison.

GET /api/v1/batches/{batch_id}/download

Download batch contacts as CSV file.

DELETE /api/v1/batches/{batch_id}

Delete a batch.

DELETE /api/v1/batches/cleanup/by-month

Delete all batches for a specific month.

Response model: BatchDeleteByMonthResponse

---

Leads

Prefix: /leads | Auth: Admin

Endpoints defined in app/api/v1/leads.py (complex patterns, see source)

---

Admin

Prefix: /admin | Auth: Admin

GET /api/v1/admin/users

List all users with optional filtering.

POST /api/v1/admin/users/invite

Invite a new user to the platform.

PATCH /api/v1/admin/users/{user_id}

Update user profile.

DELETE /api/v1/admin/users/{user_id}

Deactivate a user (soft delete).

GET /api/v1/admin/workspaces

List all client workspaces.

POST /api/v1/admin/workspaces

Create a new client workspace.

POST /api/v1/admin/workspaces/generate-all-bison-tokens

Generate Email Bison API tokens for all workspaces that:

PATCH /api/v1/admin/workspaces/{workspace_name}

Update a workspace.

POST /api/v1/admin/workspaces/{workspace_name}/generate-bison-token

Generate an Email Bison API token for a workspace.

GET /api/v1/admin/filter-rules

List filter rules.

POST /api/v1/admin/filter-rules

Create a new filter rule.

PATCH /api/v1/admin/filter-rules/{rule_id}

Update a filter rule.

DELETE /api/v1/admin/filter-rules/{rule_id}

Delete a filter rule.

GET /api/v1/admin/audit-logs

List audit log entries.

GET /api/v1/admin/settings

Get system settings.

PUT /api/v1/admin/settings

Update system settings.

---

Credentials

Prefix: /credentials | Auth: Admin

POST /api/v1/credentials/

Create a new credential with password stored in Supabase Vault.

Response model: CredentialResponse

GET /api/v1/credentials/

List all credentials (without passwords).

Response model: List

GET /api/v1/credentials/{credential_id}

Get a single credential by ID.

PUT /api/v1/credentials/{credential_id}

Update a credential. If password provided, updates vault secret.

Response model: CredentialResponse

DELETE /api/v1/credentials/{credential_id}

Delete a credential and its vault secret.

POST /api/v1/credentials/{credential_id}/test

Test a credential by retrieving password from vault and validating.

Response model: TestCredentialResponse

GET /api/v1/credentials/for-state/{state}

Get appropriate credential for a specific state.

GET /api/v1/credentials/coverage/map

Get coverage map of all states and their available credentials.

Response model: StateCoverageResponse

---

Zipcodes

Prefix: /zipcodes | Auth: Admin

GET /api/v1/zipcodes/workspaces/{workspace_name}/assigned

Fetch assigned ZIP codes for a workspace.

GET /api/v1/zipcodes/assignments

List ZIP code assignments with optional filtering.

POST /api/v1/zipcodes/assignments

Assign a ZIP code to a workspace.

POST /api/v1/zipcodes/assignments/bulk

Bulk upload ZIP assignments from CSV.

DELETE /api/v1/zipcodes/assignments/{assignment_id}

Remove a ZIP assignment.

POST /api/v1/zipcodes/assignments/seed

Seed ZIP assignments from master-list.csv format.

POST /api/v1/zipcodes/assignments/bulk-delete

Bulk delete ZIP assignments by their IDs.

DELETE /api/v1/zipcodes/assignments/bulk

Bulk delete ZIP assignments.

GET /api/v1/zipcodes/assignments/export

Export ZIP assignments as CSV or JSON.

GET /api/v1/zipcodes/assignments/coverage

Get coverage statistics for ZIP assignments.

GET /api/v1/zipcodes/zip/search

Search ZIP codes from the master us_zip_codes table.

POST /api/v1/zipcodes/assignments/bulk-add

Add multiple ZIP code assignments to a workspace.

GET /api/v1/zipcodes/workspaces/{workspace_name}/stats

Get detailed assignment statistics for a workspace.

---

Geo

Prefix: /geo | Auth: Admin

GET /api/v1/geo/states

List all US states with optional region filtering.

Response model: List

GET /api/v1/geo/states/{abbreviation}

Get details for a specific state by abbreviation.

Response model: StateResponse

GET /api/v1/geo/states/{abbreviation}/zips

Get ZIP codes for a specific state with pagination.

GET /api/v1/geo/zip/{zip_code}

Get details for a specific ZIP code.

Response model: ZipCodeResponse

GET /api/v1/geo/viewport

Get ZIP codes visible in a map viewport (bounding box).

GET /api/v1/geo/coverage

Get coverage statistics showing assigned vs total ZIPs per state.

POST /api/v1/geo/lookup/state

Lookup state information for multiple ZIP codes.

GET /api/v1/geo/regions

List all geographic regions with their states.

GET /api/v1/geo/public/states

Public endpoint to get all US states.

GET /api/v1/geo/public/zip/{zip_code}/state

Public endpoint to get state for a ZIP code.

POST /api/v1/geo/public/lookup/states

Public endpoint to lookup states for multiple ZIP codes.

---

Bison

Prefix: `` | Auth: Admin | Email Bison lead/tag management

GET /api/v1/leads

List all leads in the current workspace (paginated).

Response model: LeadListResponse

GET /api/v1/leads/search

Search leads by email address.

GET /api/v1/leads/{lead_id}

Get details for a specific lead.

Response model: LeadResponse

DELETE /api/v1/leads/{lead_id}

Delete a single lead.

Response model: DeleteResponse

POST /api/v1/leads/bulk-delete

Delete multiple leads at once.

Response model: DeleteResponse

GET /api/v1/tags

List all tags in the current workspace.

Response model: TagListResponse

POST /api/v1/tags

Create a new tag.

GET /api/v1/tags/{tag_id}/leads

Get all leads with a specific tag.

DELETE /api/v1/tags/{tag_id}

Delete a tag.

Response model: DeleteResponse

POST /api/v1/tags/attach-to-leads

Attach tags to multiple leads.

POST /api/v1/tags/detach-from-leads

Remove tags from multiple leads.

GET /api/v1/uploaded-batches

List batches that have been uploaded to Email Bison.

Response model: UploadedBatchResponse

POST /api/v1/uploaded-batches/{batch_id}/revert

Revert a batch upload by deleting all leads that were uploaded.

GET /api/v1/infrastructure/accounts

List all email accounts with their Email Bison sync data.

GET /api/v1/infrastructure/summary

Get aggregated email infrastructure summary.

PATCH /api/v1/accounts/{account_id}/pause

Pause an email account in Email Bison.

PATCH /api/v1/accounts/{account_id}/resume

Resume a paused email account in Email Bison.

POST /api/v1/sync

Manually trigger Email Bison data sync.

Response model: SyncResponse

GET /api/v1/sync/status/{task_id}

Get status of a background sync task.

GET /api/v1/sync/last

Get information about the last sync for a workspace.

GET /api/v1/copy/overview

Aggregate KPI overview with campaign details. Omit workspace for all-workspace aggregation.

GET /api/v1/copy/variants

Scored email variants with z-test significance. Returns individual + aggregated-by-subject.

GET /api/v1/copy/campaigns

Campaign details with sequence steps for Copy Lab.

GET /api/v1/copy/templates

Template library with personalization variables and safety ratings.

PATCH /api/v1/campaigns/{campaign_id}/pause

Pause an active Email Bison campaign.

PATCH /api/v1/campaigns/{campaign_id}/resume

Resume a paused Email Bison campaign.

POST /api/v1/campaigns/{campaign_id}/duplicate

Duplicate an Email Bison campaign (creates a draft copy).

GET /api/v1/workspace-stats

Get workspace-level sending KPIs (sent, opens, replies, bounced, etc.).

GET /api/v1/workspace-chart

Get workspace time-series chart data (sent, replied, opens over time).

GET /api/v1/replies

List replies across workspace with search and filtering.

GET /api/v1/campaigns/{campaign_id}/replies

Get replies for a specific campaign.

PATCH /api/v1/replies/{reply_id}/interested

Toggle interested status on a reply.

GET /api/v1/campaigns/{campaign_id}/scheduled-emails

Get pending/scheduled emails for a campaign.

GET /api/v1/campaigns/{campaign_id}/sender-emails

Get sender email accounts attached to a campaign.

GET /api/v1/campaigns/{campaign_id}/chart-stats

Get time-series chart data for a specific campaign.

---

Progress

Prefix: /progress | Auth: Admin | SSE progress endpoints

GET /api/v1/progress/filtering/{task_id}

SSE endpoint for filtering task progress.

GET /api/v1/progress/verification/{task_id}

SSE endpoint for verification task progress.

GET /api/v1/progress/filtering/{task_id}/status

Get current filtering task status (non-streaming).

Response model: FilteringTaskProgress

GET /api/v1/progress/verification/{task_id}/status

Get current verification task status (non-streaming).

Response model: VerificationTaskProgress

---

Pipeline

Prefix: /pipeline | Auth: Admin | One-click pipeline execution

POST /api/v1/pipeline/execute

Execute complete pipeline with one click.

Response model: PipelineResponse

GET /api/v1/pipeline/{run_id}/status

Get detailed pipeline execution status.

Response model: PipelineStatusResponse

POST /api/v1/pipeline/{workspace_name}/from-stage

Execute pipeline starting from a specific stage.

Response model: PipelineResponse

GET /api/v1/pipeline/

List recent pipeline runs.

Response model: List

POST /api/v1/pipeline/{run_id}/cancel

Cancel a running pipeline.

POST /api/v1/pipeline/{run_id}/retry

Retry a failed pipeline from its failed stage.

POST /api/v1/pipeline/process-all

Process all clients that have pending work for the given month.

POST /api/v1/pipeline/upload-all

Upload all verified contacts that are pending upload.

---

Crm

Prefix: `` | Auth: Admin | CRM integration management

GET /api/v1/configs

List all CRM configurations.

Response model: List

GET /api/v1/configs/{workspace_name}

Get CRM configuration for a specific workspace.

Response model: CRMConfigResponse

PUT /api/v1/configs/{workspace_name}

Update CRM configuration for a workspace.

Response model: CRMConfigResponse

POST /api/v1/configs/{workspace_name}/test

Test CRM connection for a workspace.

Response model: CRMTestResponse

GET /api/v1/delivery-logs

Get CRM delivery logs.

Response model: List

GET /api/v1/health

Get CRM health summary across all workspaces.

Response model: Dict

POST /api/v1/retry-failed

Retry failed CRM deliveries.

---

Gap To Goal

Prefix: /contacts/gap-to-goal | Auth: Admin

POST /api/v1/contacts/gap-to-goal/fill

Fill contact gap from the master database.

Response model: GapToGoalFillResponse

GET /api/v1/contacts/gap-to-goal/availability

Check master database availability for a workspace.

Response model: AvailabilityResponse

GET /api/v1/contacts/gap-to-goal/zip-stats

Get ZIP code availability statistics from the master database.

Response model: List

GET /api/v1/contacts/gap-to-goal/pipeline-rates

Get historical pipeline attrition rates.

Response model: PipelineRatesResponse

GET /api/v1/contacts/gap-to-goal/calculate-pull

Calculate recommended pull count accounting for pipeline attrition.

Response model: PullCountCalculationResponse

GET /api/v1/contacts/gap-to-goal/health

Check master database health and connectivity.

Response model: MasterDbHealthResponse

---

Analytics

Prefix: /analytics | Auth: Auth

GET /api/v1/analytics/kpis

Get key performance indicators with REAL DATA.

Response model: KPIMetrics

GET /api/v1/analytics/time-series

Get time-series data for metrics.

GET /api/v1/analytics/contact-growth

Get contact growth metrics.

Response model: ContactGrowthMetrics

GET /api/v1/analytics/campaign-performance

Get campaign performance metrics with REAL DATA from campaign_metrics table.

GET /api/v1/analytics/workspace-comparison

Compare performance across all workspaces.

GET /api/v1/analytics/funnel

Get contact pipeline conversion funnel.

GET /api/v1/analytics/cost-analysis

Get cost analysis for verification and email sending.

GET /api/v1/analytics/debounce-usage

Get Debounce email verification usage statistics.

Response model: DebounceUsageStats

GET /api/v1/analytics/activity-feed

Get activity feed for the dashboard.

Response model: ActivityFeedResponse

GET /api/v1/analytics/client-pipeline-stats

Get pipeline statistics per client/workspace for the overview dashboard.

Response model: ClientPipelineResponse

GET /api/v1/analytics/activity-feed/summary

Get activity summary with counts by event type.

GET /api/v1/analytics/client-kpi-overview

Get comprehensive KPI overview for all clients.

GET /api/v1/analytics/comparisons

Get WoW (week-over-week) or MoM (month-over-month) metric comparisons.

Response model: ComparisonResponse

GET /api/v1/analytics/time-range

Get aggregated metrics for a specific time range.

Response model: TimeRangeResponse

---

Campaigns

Prefix: /campaigns | Auth: Auth

GET /api/v1/campaigns/

List campaigns with filtering and pagination.

Response model: CampaignListResponse

GET /api/v1/campaigns/{batch_id}

Get campaign details by batch ID.

POST /api/v1/campaigns/

Create a new campaign (weekly batch).

PATCH /api/v1/campaigns/{batch_id}

Update campaign details.

POST /api/v1/campaigns/{batch_id}/launch

Launch a campaign by uploading to Email Bison.

POST /api/v1/campaigns/{batch_id}/pause

Pause an active campaign in Email Bison.

GET /api/v1/campaigns/{batch_id}/stats

Get campaign performance statistics from Email Bison.

Response model: CampaignStats

GET /api/v1/campaigns/{batch_id}/export/csv

Export campaign contacts and results as CSV.

GET /api/v1/campaigns/bison/list

List all Email Bison campaigns for a specific workspace.

POST /api/v1/campaigns/{batch_id}/assign-to-bison-campaign

Assign a batch's leads to an Email Bison campaign.

---

Revenue

Prefix: /revenue | Auth: Auth

GET /api/v1/revenue/breakdown

Per-client revenue, costs, profit, and margins for a given month.

Response model: RevenueBreakdownResponse

GET /api/v1/revenue/totals

Aggregate revenue, cost, and profit totals across all clients.

Response model: RevenueTotalsResponse

GET /api/v1/revenue/forecast

Revenue projections for the month.

Response model: RevenueForecastResponse

GET /api/v1/revenue/historical

Month-over-month revenue comparison.

Response model: List

POST /api/v1/revenue/snapshot

Persist the current revenue state as a snapshot.

Response model: SnapshotResponse

---

Client Leads

Prefix: /client-leads | Auth: Auth

GET /api/v1/client-leads

List leads for a workspace with optional search, filtering, and pagination.

Response model: LeadListResponse

GET /api/v1/client-leads/stats

Get pipeline stage counts and summary statistics for a workspace.

Response model: PipelineStatsResponse

GET /api/v1/client-leads/{lead_id}

Get full details for a single lead.

Response model: LeadDetailResponse

PATCH /api/v1/client-leads/{lead_id}/stage

Update the pipeline stage for a lead.

Response model: UpdateLeadResponse

PATCH /api/v1/client-leads/{lead_id}/notes

Update the notes for a lead.

Response model: UpdateLeadResponse

GET /api/v1/client-leads/{lead_id}/activity

Get the activity timeline for a lead, including all email replies.

Response model: LeadActivityResponse

---

Replies

Prefix: /replies | Auth: Auth

GET /api/v1/replies

List replies for a workspace with filtering and pagination.

Response model: ReplyListResponse

GET /api/v1/replies/stats

Get reply statistics including counts by sentiment, interest level,

Response model: ReplyStatsResponse

GET /api/v1/replies/campaign/{campaign_id}

Get replies for a specific campaign within a workspace via Email Bison.

GET /api/v1/replies/{reply_id}

Get detailed information for a single reply by ID.

Response model: ReplyDetailResponse

POST /api/v1/replies/generate

Generate an AI-powered reply draft for a lead response.

Response model: GenerateReplyResponse

POST /api/v1/replies/send

Send a reply or mark it as handled.

Response model: SendReplyResponse

PATCH /api/v1/replies/{reply_id}/sentiment

Manually update the sentiment and interest classification for a reply.

Response model: UpdateSentimentResponse

PATCH /api/v1/replies/{reply_id}/interested

Toggle interested status on a reply via Email Bison.

---

Test

Prefix: /test | Auth: Public

POST /api/v1/test/scrape-no-auth

Create a scraping job WITHOUT authentication (for testing only).

Response model: ScrapingJobResponse

GET /api/v1/test/job/{job_id}

Get job status WITHOUT authentication (for testing only).

Response model: ScrapingJobResponse

GET /api/v1/test/health

Simple health check endpoint.

POST /api/v1/test/process-csv

Manually trigger CSV processing for a job (for testing only).

POST /api/v1/test/verify-emails

Manually trigger email verification for a workspace (for testing only).

GET /api/v1/test/verification-stats/{workspace_name}

Get verification statistics for a workspace (for testing only).

GET /api/v1/test/contacts/raw

Get raw contacts from database (for testing only).

GET /api/v1/test/contacts/verified

Get verified contacts from database (for testing only).

POST /api/v1/test/filter-contacts

Manually trigger contact filtering for a workspace (for testing only).

POST /api/v1/test/generate-batches

Manually trigger weekly batch generation (for testing only).

POST /api/v1/test/upload-batch

Manually trigger Email Bison batch upload (for testing only).

GET /api/v1/test/batch/{batch_id}

Get batch status and details (for testing only).

GET /api/v1/test/pipeline-stats/{workspace_name}

Get complete pipeline statistics for a workspace (for testing only).

---

Webhooks

Prefix: /webhooks | Auth: Public

POST /api/v1/webhooks/bison

Receive webhook events from Email Bison.

POST /api/v1/webhooks/bison/lead-interested

Dedicated endpoint for lead_interested webhooks.

GET /api/v1/webhooks/bison/health

Health check endpoint for Email Bison webhook.

GET /api/v1/webhooks/bison/stats

Get webhook processing statistics.

GET /api/v1/webhooks/bison/activity

Get recent webhook activity for the activity feed.

---

Sse

Prefix: `` | Auth: Public | No auth - SSE from authenticated frontend

GET /api/v1/dashboard

SSE endpoint for real-time dashboard updates.

GET /api/v1/clients

Get count of connected SSE clients (admin diagnostic).

---

Total endpoints discovered: 210