# Matchup Labs APIs

> API-first products for the agentic AI economy. Each API turns a NYC public dataset into a commercial-grade developer primitive with SLAs, SDKs, webhooks, and MCP servers.

## NYC FHV Intelligence API

Real-time NYC TLC For-Hire Vehicle license verification and renewal-window intelligence. Covers the 80,000+ active FHV fleet (Uber, Lyft, black car, livery, WAV).

- OpenAPI spec: https://fhv.matchup.dev/openapi.yaml
- Base URL: https://fhv.matchup.dev/api/v1
- Auth: Bearer token via Authorization header
- MCP server: @matchuplabs/nycfhv-mcp (stdio transport)
- TypeScript SDK: @matchuplabs/nyc-fhv-sdk

### Endpoints

- GET /verify/{identifier} — Verify a TLC license by number, DMV plate, or VIN. Returns active status, expiration date, base affiliation, WAV flag. Auto-detects identifier type. 1 credit per call.
- GET /renewals/upcoming — Paginated list of vehicles expiring within N days. Filterable by base, WAV status, max vehicle year. 5 credits per page.
- POST /renewals/subscriptions — Subscribe a webhook to daily renewal-window push notifications. HMAC-SHA256 signed payloads. 0 credits to create; 1 credit per delivered event.
- GET /renewals/subscriptions — List the calling key's active subscriptions.
- DELETE /renewals/subscriptions/{id} — Cancel a subscription.

### Use cases

- Pre-flight verification before in-cab ad hardware install (TLC requires Interior Advertising Provider compliance)
- Renewal alerts for fleet operators managing 1,000+ TLC plate portfolios
- Plate-to-license resolution for parking apps extending commercial livery rates
- Pre-dispatch WAV + active verification for NEMT Medicaid trips
- Tool-callable TLC verification for AI dispatch agents

### Pricing

- Free: $0/mo, 500 credits, 30 req/min, best-effort SLA
- Starter: $99/mo, 25,000 credits, 120 req/min, 99.0% SLA
- Pro: $499/mo, 250,000 credits, 600 req/min, 99.5% SLA
- Enterprise: custom pricing, unlimited credits, custom rate limit, 99.9% SLA + DPA

### Credit math

- verify = 1 credit
- renewals/upcoming = 5 credits per page (50 results default)
- Subscription create/list/delete = 0 credits
- Webhook delivery = 1 credit per event
- Edge-cached verify hits do not consume credits

### Data source

NYC TLC For-Hire Vehicles - Active dataset (Socrata 8wbx-tsch). Refreshed daily 4-7 PM ET. Public record under NY State FOIL and NYC Local Law 11 of 2012.

### Contact

- Email: api@matchup.dev
- Signup: https://fhv.matchup.dev/signup
- Website: https://nycfhv.app
- More NYC APIs: https://nycapi.app