Add AI-powered matching to your app in 5 minutes.
MatchAgent is a matching engine API for dating apps, networking platforms, and roommate finders. Send user profiles, get ranked matches with explanations, coaching advice, and conversation starters — all in one request.
No signup. No API key. Just paste this into your terminal:
curl https://matchagent.newcool.io/api/demo/matches/1?n=3You will get back:
{
"user_id": 1,
"profile_summary": {
"name": "Valentina",
"age": 28,
"city": "Santiago"
},
"matches": [
{
"candidate_user_id": 2,
"score": 0.9234,
"explanation": {
"reasons": [
"Comparten valores de familia y crecimiento personal",
"Estilos de vida activos y al aire libre compatibles",
"Personalidades complementarias: extroversion equilibrada"
],
"risk": "Distancia moderada (120km) podria requerir planificacion",
"starters": [
"Vi que te gusta el senderismo -- conoces el Cajon del Maipo?",
"Ambos valoramos la familia. Tienes hermanos?",
"Tu perfil transmite buena energia -- que te motiva dia a dia?"
]
},
"coach": {
"approach_style": {
"label": "Autentico y directo",
"description": "Matias responde bien a la honestidad y el humor natural",
"pace": "Conversacion fluida, sin presionar"
},
"topics_to_explore": ["viajes", "metas personales", "cocina"],
"topics_to_avoid": ["ex parejas", "politica al inicio"]
},
"energy": {
"social": { "compatibility": "Mirror", "score": 0.85 },
"thinking": { "compatibility": "Complement", "score": 0.72 },
"pace": { "compatibility": "Mirror", "score": 0.91 },
"emotional": { "compatibility": "Complement", "score": 0.68 },
"overall": 0.79
}
}
],
"meta": {
"engine": "MatchAgent v1.3.0",
"latency_ms": 12.7,
"signals": ["values", "lifestyle", "personality", "interests", "logistics", "feedback"],
"retrieval": "ANN (pgvector cosine similarity)",
"scoring": "bidirectional weighted fusion + MMR diversity",
"mode": "demo"
}
}That is a single match out of three returned. Each match includes everything your app needs to create a great user experience.
| Signal | Description | Weight |
|---|---|---|
| Values | Core beliefs, life goals, family orientation | 35% |
| Lifestyle | Activity level, routines, social habits | 25% |
| Personality | Big Five traits, communication style | 20% |
| Interests | Hobbies, topics, shared activities | 15% |
| Logistics | Distance, schedule overlap (penalty) | -3% |
| Conflicts | Dealbreakers, past negative signals (penalty) | -2% |
Plus, every match response includes:
- Score -- A single 0-1 number you can sort and filter on
- Explanation -- Human-readable reasons why two people match (and what the risks are)
- Coach Advice -- Approach style, conversation pace, topics to explore, topics to avoid
- Energy Compatibility -- 4-dimensional compatibility map (social, thinking, pace, emotional) with Mirror/Complement/Stretch labels
- Conversation Starters -- Ready-to-use openers personalized to both profiles
# Demo endpoint (no API key required)
curl https://matchagent.newcool.io/api/demo/matches/1?n=3
# Production endpoint (requires API key)
curl -H "Authorization: Bearer ma_live_YOUR_KEY_HERE" \
https://matchagent.newcool.io/api/v1/matches/1?n=5const res = await fetch("https://matchagent.newcool.io/api/demo/matches/1?n=3");
const data = await res.json();
for (const match of data.matches) {
console.log(`Match score: ${match.score}`);
console.log(`Why: ${match.explanation.reasons[0]}`);
console.log(`Opener: ${match.explanation.starters[0]}`);
console.log(`Coach says: ${match.coach.approach_style.label}`);
console.log("---");
}import requests
r = requests.get("https://matchagent.newcool.io/api/demo/matches/1", params={"n": 3})
data = r.json()
for match in data["matches"]:
print(f"Score: {match['score']}")
print(f"Why: {match['explanation']['reasons'][0]}")
print(f"Open: {match['explanation']['starters'][0]}")
print(f"Coach: {match['coach']['approach_style']['label']}")
print("---")See the examples/ directory for complete, runnable scripts.
| Starter | Growth | Enterprise | |
|---|---|---|---|
| Price | $49/mo | $199/mo | $499/mo |
| Matches/month | 10,000 | 100,000 | Unlimited |
| 6-signal scoring | Yes | Yes | Yes |
| ANN retrieval | -- | Yes | Yes |
| MMR reranking | -- | Yes | Yes |
| Custom weights | -- | Yes | Yes |
| Coach API | Yes | Yes | Yes |
| Energy compatibility | Yes | Yes | Yes |
| Dedicated instance | -- | -- | Yes |
| SLA | -- | -- | 99.9% |
| Support | Priority | Slack + dedicated |
All plans include the demo sandbox for testing. No credit card required to start.
- You send user profiles (values, interests, personality traits, location)
- MatchAgent indexes them using pgvector embeddings
- When you request matches, the engine retrieves candidates via ANN search
- Candidates are scored using bidirectional weighted fusion across 6 signals
- Results are reranked with MMR (Maximal Marginal Relevance) for diversity
- You get back ranked matches with scores, explanations, coaching, and starters
The engine is written in Rust (Axum + Tokio), scores in ~13ms per request, and runs bidirectional consent matching so both sides have to be compatible.
Your App --> MatchAgent API --> pgvector (ANN retrieval)
--> scoring engine (6-signal fusion + MMR)
--> coach engine (approach + starters)
--> energy engine (4D compatibility)
<-- JSON response (~13ms)
Cold start: New users with sparse profiles get an exploration boost so they still receive quality matches while the engine learns their preferences from feedback signals.
MIT. Use the demo freely. Production use requires an API key.
Built by NewCool -- Rust-powered APIs for real-world applications.