API Documentation
Common exposes a REST API that powers the member dashboard, provider portal, and admin console. This reference covers every endpoint available on the platform.
Authentication
Common uses NextAuth.js for authentication. After signing in, the session is persisted as an HTTP-only cookie. All browser-based requests are authenticated automatically via the session cookie.
For server-to-server calls you can pass a Bearer token in the Authorization header. Tokens are issued via the sign-in flow.
Authorization: Bearer <your-token>Getting Started
- Register — Create an account via
POST /api/register - Verify your email — Click the verification link or call
POST /api/auth/verify-emailwith the token - Sign in — Authenticate via
POST /api/auth/signinto receive your session - Make requests — Include the session cookie or Bearer token in subsequent API calls
Authentication Endpoints
Account creation, sign-in, email verification, and password management.
Authenticate a user with email/password credentials or an OAuth provider. Returns a session cookie on success.
{
"email": "member@example.com",
"password": "securePassword123"
}{
"url": "/dashboard"
}Create a new member account. Sends a verification email on success. Optional fields let us personalize savings estimates immediately.
{
"name": "Jane Smith",
"email": "jane@example.com",
"password": "securePassword123",
"householdSize": 3,
"zipCode": "90210",
"isHomeowner": true
}{
"id": "clx1abc23000108l4...",
"name": "Jane Smith",
"email": "jane@example.com",
"message": "Account created. Please verify your email."
}Verify a user's email address using the token sent to their inbox.
{
"token": "abc123def456..."
}Request a password reset email. Always returns 200 to prevent email enumeration.
{
"email": "jane@example.com"
}Reset the user's password using a valid reset token.
{
"token": "resetToken123...",
"password": "newSecurePassword456"
}Provider Endpoints
Browse, search, and view service providers. These endpoints are public and require no authentication.
List all providers with optional filters for category, tier, and pagination. Returns a paginated array of provider summaries.
Query Parameters:
?category=internet
&tier=gold
&page=1
&limit=20{
"providers": [
{
"id": "clx2prov01...",
"name": "FiberFast Internet",
"category": "internet",
"tier": "gold",
"description": "High-speed fiber optic internet",
"savingsPercent": 22,
"logo": "/images/providers/fiberfast.png"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 47,
"totalPages": 3
}
}Get full details for a single provider including their current pricing tiers, coverage areas, and member reviews.
{
"id": "clx2prov01...",
"name": "FiberFast Internet",
"category": "internet",
"tier": "gold",
"description": "High-speed fiber optic internet",
"savingsPercent": 22,
"website": "https://fiberfast.example.com",
"logo": "/images/providers/fiberfast.png",
"coverageAreas": ["CA", "NY", "TX"],
"plans": [
{
"name": "Basic",
"price": 39.99,
"commonPrice": 31.19,
"features": ["100 Mbps", "Unlimited data"]
}
]
}Submit a provider application to join the Common network. No authentication required -- applications are reviewed by the admin team.
{
"companyName": "Acme Utilities",
"contactName": "John Doe",
"contactEmail": "john@acme.com",
"category": "energy",
"website": "https://acme.com",
"description": "Renewable energy provider serving the midwest."
}{
"applicationId": "clx3app01...",
"status": "pending",
"message": "Application received. We will review within 5 business days."
}Provider Portal Endpoints
Endpoints for authenticated providers to manage their bids, contracts, analytics, and profile. Requires the PROVIDER role.
List all bids submitted by the authenticated provider. Supports pagination and filtering by status.
No additional details available for this endpoint.
Submit a new bid to offer services to Common members. Bids are reviewed by the admin team before going live.
{
"category": "internet",
"planName": "Fiber 500",
"retailPrice": 79.99,
"commonPrice": 59.99,
"description": "500 Mbps fiber with unlimited data",
"coverageAreas": ["CA", "OR", "WA"],
"contractLength": 12,
"features": ["No data caps", "Free installation"]
}{
"id": "clx4bid01...",
"status": "pending_review",
"createdAt": "2026-03-03T10:30:00Z",
"message": "Bid submitted for review."
}Get details for a specific bid including review status and admin feedback.
No additional details available for this endpoint.
List active and past contracts between the provider and Common.
No additional details available for this endpoint.
View analytics for the provider including member sign-ups, revenue, and engagement metrics.
No additional details available for this endpoint.
Retrieve the provider's public profile including logo, description, and contact details.
No additional details available for this endpoint.
Update the provider's public profile. Fields not included in the request body are left unchanged.
{
"description": "Updated company description",
"website": "https://newsite.example.com",
"logo": "/images/providers/new-logo.png"
}Eligibility Verification API
Real-time API for providers to verify Common member eligibility. Providers authenticate with an API key issued by Common, sent as a Bearer token. This is how telecom, insurance, and other affinity discount programs verify membership — when a member uses their Common discount, your system calls our API to confirm eligibility.
Authentication
Each provider receives an API key from Common. Include it in every request:
Authorization: Bearer <provider-api-key>Rate limit: 100 requests per minute per API key (configurable per provider).
Test Mode
Use these test member IDs to validate your integration without real member data:
test-member-active— returns active/eligibletest-member-inactive— returns inactivetest-member-notfound— returns not_found
Code Examples
cURL
curl -X POST https://usecommon.com/api/v1/eligibility/verify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "jane@example.com"}'Python
import requests
resp = requests.post(
"https://usecommon.com/api/v1/eligibility/verify",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"email": "jane@example.com"}
)
data = resp.json()
if data["eligible"]:
print(f"Active since {data['member_since']}")
Node.js
const resp = await fetch("https://usecommon.com/api/v1/eligibility/verify", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "jane@example.com" }),
});
const data = await resp.json();
console.log(data.eligible); // true or falseJava
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://usecommon.com/api/v1/eligibility/verify"))
.header("Authorization", "Bearer YOUR_API_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(
"{\"email\":\"jane@example.com\"}"))
.build();
HttpResponse<String> response =
client.send(request, HttpResponse.BodyHandlers.ofString());Verify a single member's eligibility in real time. Provide at least one of member_id, email, or identity. The provider's system calls this when a member attempts to use their Common discount.
{
"member_id": "clx1abc23000108l4...",
// OR
"email": "jane@example.com",
// OR
"identity": {
"full_name": "Jane Smith",
"date_of_birth": "1990-05-15",
"address_zip": "72002"
}
}// Eligible member:
{
"eligible": true,
"membership_status": "active",
"membership_tier": "family",
"member_since": "2026-04-01",
"household_size": 4,
"region": "72",
"verified_at": "2026-04-15T10:30:00Z"
}
// Not eligible:
{
"eligible": false,
"reason": "not_found | inactive | suspended | cancelled",
"verified_at": "2026-04-15T10:30:00Z"
}Verify eligibility for up to 500 members in a single request. Same authentication. Each entry in the array uses the same identifier format as the single verify endpoint.
{
"members": [
{ "email": "jane@example.com" },
{ "member_id": "clx1abc23..." },
{ "identity": { "full_name": "John Doe", "address_zip": "72002" } }
]
}{
"results": [
{ "eligible": true, "membership_status": "active", "membership_tier": "family", ... },
{ "eligible": false, "reason": "not_found", ... },
{ "eligible": true, "membership_status": "active", ... }
],
"total": 3,
"eligible_count": 2,
"verified_at": "2026-04-15T10:30:00Z"
}Get aggregate eligibility statistics for your provider. Returns total active Common members and total members in your operating regions. No individual member data is exposed.
{
"total_active_members": 12450,
"total_in_provider_regions": 8320,
"as_of": "2026-04-15T10:30:00Z"
}List your eligibility file export history. Returns metadata for past full and delta exports generated for your provider.
{
"data": [
{
"id": "clx...",
"fileName": "common_eligibility_full_20260415.csv",
"exportType": "full",
"recordCount": 8320,
"status": "generated",
"createdAt": "2026-04-15T02:00:00Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 45 }
}Member Endpoints
Manage enrolled providers and view savings data. Requires an authenticated member session.
List all providers the authenticated member is currently enrolled with.
{
"enrolledProviders": [
{
"id": "clx2prov01...",
"name": "FiberFast Internet",
"category": "internet",
"enrolledAt": "2026-01-15T08:00:00Z",
"monthlySavings": 18.80,
"plan": "Fiber 500"
}
]
}Enroll the authenticated member with a provider plan.
{
"providerId": "clx2prov01...",
"planId": "clx5plan01..."
}Remove enrollment with a provider. Requires the provider ID in the request body.
{
"providerId": "clx2prov01..."
}View the member's total savings breakdown across all enrolled providers, including monthly and yearly estimates.
{
"totalMonthlySavings": 127.40,
"totalYearlySavings": 1528.80,
"byCategory": {
"internet": 18.80,
"energy": 42.00,
"insurance": 55.60,
"wireless": 11.00
},
"enrolledProviders": 4
}Get your Common Card application status and recent transactions.
{
"data": {
"id": "clx...",
"status": "active",
"cardLastFour": "4242",
"cardStatus": "active",
"appliedAt": "2026-04-01T00:00:00Z",
"activatedAt": "2026-04-05T00:00:00Z"
},
"transactions": [...],
"totalSavings": 384.50
}Request a Common Card. One active application per member.
{
"shippingAddress": {
"line1": "123 Main St",
"city": "Bentonville",
"state": "AR",
"zip": "72712"
}
}Manage your Common Card: freeze, unfreeze, or report lost.
{
"action": "freeze | unfreeze | report_lost"
}List available healthcare plans based on your region and current open enrollment periods.
No additional details available for this endpoint.
Get your current healthcare enrollment details including plan, coverage tier, and dependents.
No additional details available for this endpoint.
Enroll in a healthcare plan. Requires active open enrollment.
{
"planId": "clx...",
"coverageTier": "FAMILY",
"dependents": [
{ "name": "John Smith", "dateOfBirth": "2015-03-20", "relationship": "child" }
]
}Terminate healthcare coverage. Coverage continues through end of current month.
{
"enrollmentId": "clx...",
"reason": "Switching to employer coverage"
}Membership Endpoints
Create, view, and manage cooperative membership status.
Get the authenticated user's current membership status, tier, and billing information.
{
"id": "clx6mem01...",
"tier": "standard",
"status": "active",
"startDate": "2026-01-01T00:00:00Z",
"nextBillingDate": "2026-04-01T00:00:00Z",
"monthlyFee": 9.99,
"enrolledProviders": 4,
"totalSavings": 1528.80
}Create a new membership. Initiates the cooperative onboarding flow.
{
"tier": "standard",
"paymentMethodId": "pm_1abc..."
}Update membership tier, payment method, or other membership preferences.
{
"tier": "premium",
"paymentMethodId": "pm_2def..."
}Admin Endpoints
Platform administration endpoints. Restricted to users with the ADMIN role.
List all providers on the platform with filtering and pagination.
No additional details available for this endpoint.
Create a new provider entry directly (bypasses the application flow).
No additional details available for this endpoint.
Get full details for a specific provider including internal notes and status.
No additional details available for this endpoint.
Update a provider's information, tier, or status.
No additional details available for this endpoint.
List all bids across all providers with filtering by status, category, and date range.
No additional details available for this endpoint.
Get full details for a specific bid.
No additional details available for this endpoint.
Review and approve or reject a bid. Optionally include feedback for the provider.
{
"status": "approved",
"feedback": "Great pricing. Approved for launch."
}Perform bulk actions on multiple bids such as approve, reject, or archive.
{
"bidIds": ["clx4bid01...", "clx4bid02..."],
"action": "approve"
}List all members with search, filtering, and pagination.
No additional details available for this endpoint.
Get detailed information for a specific member including enrollment history.
No additional details available for this endpoint.
Update a member's role, status, or membership tier.
No additional details available for this endpoint.
View platform-wide analytics including member growth, total savings, provider performance, and revenue metrics.
No additional details available for this endpoint.
View the audit log of administrative actions across the platform.
No additional details available for this endpoint.
List all registered organizations (enterprise partners).
No additional details available for this endpoint.
Get details for a specific organization.
No additional details available for this endpoint.
Update an organization's status, plan, or settings.
No additional details available for this endpoint.
Enterprise Endpoints
APIs for organization-level enrollment and management. These endpoints are currently under development.
Register an organization to offer Common benefits to employees. This endpoint is coming soon and is not yet available.
{
"organizationName": "Acme Corp",
"contactName": "HR Admin",
"contactEmail": "hr@acmecorp.com",
"employeeCount": 250
}Enterprise APIs are under active development. If you are interested in integrating Common as a workplace benefit, please reach out to enterprise@usecommon.com.
Other Endpoints
Waitlist and referral management.
Add an email address to the Common waitlist. Returns a confirmation and queue position.
{
"email": "interested@example.com",
"zipCode": "10001"
}{
"message": "You have been added to the waitlist.",
"position": 1842
}Get the authenticated user's referral code and list of referred members.
{
"referralCode": "JANE-2X8K",
"referredCount": 3,
"earnedCredits": 30.00,
"referrals": [
{
"name": "Alex M.",
"joinedAt": "2026-02-10T12:00:00Z",
"status": "active"
}
]
}Send a referral invitation to an email address.
{
"email": "friend@example.com"
}Rate Limiting
All API endpoints are rate-limited. Authenticated requests allow up to 100 requests per minute. Unauthenticated requests are limited to 20 requests per minute. If you exceed the limit you will receive a 429 Too Many Requests response.