Listing Verification

Overview

Hub verification gives AI agents and human users a reliable signal of publisher credibility. Every listing starts at Tier 1 (Unverified) and can be advanced through three higher tiers — each requiring progressively stronger identity proof. Higher tiers earn:

A trust badge displayed on your listing
Ranking boosts in Hub search results and the Directory API
Eligibility for composite skill inclusion (Tier 2+ required; verification_tier_min filter lets agents raise the bar further)

Verification tiers

Tier	Badge	How to earn
1 — Unverified	(none)	Default at listing creation
2 — Phone Verified	✓ Phone Verified	SMS code via Twilio Verify
3 — Business Verified	✓ Business Verified	GBP cross-reference (internal) or $25 flat fee (external)
4 — Premium Verified	★ Premium Verified	Manual review by the ezForge team; $100 flat fee (external)

Internal listings (linked to a Ready business via businessId) run automated checks instead of collecting a fee. External listings (businessId null, externalUrl set) pay a one-time flat fee per tier advancement.

Ready Pro/Premium auto-promotion

Users on a Professional or Premium Ready subscription whose linked business is already business-verified in Ready are automatically promoted to Tier 3 at no additional charge. This sync runs daily.

Advancing verification

All verification actions go through a single endpoint:

POST /api/v1/hub/listings/:id/verify

Authentication: session cookie (user must own the listing).

Tier 2 — Phone Verification

Step 1 — Send SMS code

{
  "tier": 2,
  "action": "send",
  "phone": "+15005550006"
}

Response:

{ "data": { "action": "phone_code_sent", "tier": 1 } }

Step 2 — Confirm code

{
  "tier": 2,
  "action": "verify",
  "phone": "+15005550006",
  "code": "123456"
}

Response on success:

{ "data": { "action": "upgraded", "tier": 2 } }

Tier 3 — Business Verification

Prerequisite: listing must be at Tier 2.

{ "tier": 3 }

Internal listing (Ready business linked):

{ "data": { "action": "upgraded", "tier": 3 } }

External listing (fee required — $25):

{
  "data": {
    "action": "checkout_required",
    "tier": 2,
    "checkoutUrl": "https://checkout.stripe.com/..."
  }
}

After successful payment, the Stripe webhook upgrades the listing to Tier 3 automatically.

Tier 4 — Premium Verification

Prerequisite: listing must be at Tier 3.

{ "tier": 4 }

Internal listing (queued for manual review):

{ "data": { "action": "queued_for_review", "tier": 3 } }

External listing (fee required — $100):

{
  "data": {
    "action": "checkout_required",
    "tier": 3,
    "checkoutUrl": "https://checkout.stripe.com/..."
  }
}

After payment, the listing enters the manual review queue. Tier 4 is granted by the ezForge team, not automatically on payment.

Request reference

Field	Type	Required	Description
`tier`	`2 \| 3 \| 4`	Yes	Target verification tier
`action`	`"send" \| "verify"`	Tier 2 only	Default: `"send"`
`phone`	`string`	Tier 2	E.164 format, e.g. `+15005550006`
`code`	`string`	Tier 2 + `action="verify"`	4–8 digit SMS code

Response actions

`action`	Meaning
`phone_code_sent`	SMS dispatched; call again with `action="verify"`
`upgraded`	Listing tier was immediately advanced
`checkout_required`	Payment needed; redirect user to `checkoutUrl`
`queued_for_review`	Submitted to manual review queue (Tier 4)
`no_change`	Listing is already at or above the requested tier

Error codes

Status	Code	Cause
`400`	—	Malformed body or missing required fields
`401`	—	Not authenticated
`404`	`NOT_FOUND`	Listing not found or not owned by you
`422`	`PREREQUISITE_NOT_MET`	Required previous tier not satisfied
`422`	`VERIFICATION_CODE_INVALID`	SMS code incorrect or expired
`422`	`BUSINESS_VERIFICATION_INELIGIBLE`	GBP match or 30-day account age requirement not met
`429`	—	Rate limit exceeded
`503`	`TWILIO_NOT_CONFIGURED`	Twilio credentials missing (internal error)
`503`	`STRIPE_NOT_CONFIGURED`	Stripe credentials missing (internal error)

Annual re-verification

Verified listings (Tier 2+) are subject to an annual re-verification window. Eleven months after the last tier update, the listing is flagged for re-verification and the owner receives a reminder. Listings that are not re-verified within 12 months may be downgraded (email dispatch and downgrade logic tracked in follow-up issues). The re-verification window is currently measured from the listing’s updated_at timestamp (reset by tier changes and content edits alike), not from the listing’s creation date. A dedicated last_verified_at field is planned as a follow-up.

​Overview

​Verification tiers

​Ready Pro/Premium auto-promotion

​Advancing verification

​Tier 2 — Phone Verification

​Tier 3 — Business Verification

​Tier 4 — Premium Verification

​Request reference

​Response actions

​Error codes

​Annual re-verification