---
title: 'Match Prediction Agent'
description: 'Match Prediction Agent API with Multi-Language Support'
---

# Match Prediction Agent

The Match Prediction Agent analyzes compatibility between two dating profiles using advanced AI algorithms. The agent provides detailed compatibility scores, reasoning, and common interests analysis - all with **35+ language support** for localized explanations.

## 🚀 Endpoint

### Match Prediction
**POST** `/api/v1/ai-agents/match/predict`

Analyzes compatibility between two user profiles and provides detailed match analysis.

## 📝 Request Format

### Match Prediction Request
```json
{
  "userProfile": "Adventure-loving photographer who enjoys hiking and coffee",
  "potentialMatchProfile": "Nature enthusiast who loves outdoor activities and travel",
  "userInterests": ["photography", "hiking", "coffee", "travel"],
  "matchInterests": ["outdoors", "travel", "photography", "music"],
  "location": "San Francisco, CA",
  "language": "en"
}
```

## 🔧 Request Parameters

| Parameter | Type | Required | Description | Example |
|-----------|------|----------|-------------|---------|
| `userProfile` | string | ✅ | Current user's profile description | "Adventure-loving photographer..." |
| `potentialMatchProfile` | string | ✅ | Potential match's profile description | "Nature enthusiast who loves..." |
| `userInterests` | array[string] | ✅ | Current user's interests | ["photography", "hiking", "coffee"] |
| `matchInterests` | array[string] | ✅ | Potential match's interests | ["outdoors", "travel", "photography"] |
| `location` | string | ✅ | Geographic location for context | "San Francisco, CA" |
| `language` | string | ✅ | User's preferred language | "en", "es", "fr", "sw" |

### Supported Languages
- **English (en)** - Default
- **Spanish (es)** - Español
- **French (fr)** - Français
- **Swahili (sw)** - Kiswahili
- **Arabic (ar)** - العربية
- **Chinese (zh)** - 中文
- **Hindi (hi)** - हिन्दी
- **Portuguese (pt)** - Português
- **Russian (ru)** - Русский
- **Japanese (ja)** - 日本語
- **Korean (ko)** - 한국어
- **German (de)** - Deutsch
- **Italian (it)** - Italiano
- And 20+ more languages...

## 📊 Response Format

### Success Response
```json
{
  "success": true,
  "data": {
    "matchScore": 0.85,
    "reasoning": "High compatibility based on shared outdoor interests and photography passion. Both users show adventurous spirits and appreciation for nature, creating strong foundation for meaningful connection.",
    "commonInterests": [
      "photography",
      "outdoor activities",
      "travel",
      "nature appreciation"
    ],
    "confidence": 0.92
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

### Multi-Language Response Examples

#### Spanish Response
```json
{
  "success": true,
  "data": {
    "matchScore": 0.85,
    "reasoning": "Alta compatibilidad basada en intereses al aire libre compartidos y pasión por la fotografía. Ambos usuarios muestran espíritus aventureros y apreciación por la naturaleza, creando una base sólida para una conexión significativa.",
    "commonInterests": [
      "fotografía",
      "actividades al aire libre",
      "viajes",
      "apreciación por la naturaleza"
    ],
    "confidence": 0.92
  }
}
```

#### French Response
```json
{
  "success": true,
  "data": {
    "matchScore": 0.85,
    "reasoning": "Compatibilité élevée basée sur des intérêts extérieurs partagés et une passion pour la photographie. Les deux utilisateurs montrent des esprits aventureux et une appréciation pour la nature, créant une base solide pour une connexion significative.",
    "commonInterests": [
      "photographie",
      "activités extérieures",
      "voyage",
      "appréciation de la nature"
    ],
    "confidence": 0.92
  }
}
```

#### Swahili Response
```json
{
  "success": true,
  "data": {
    "matchScore": 0.85,
    "reasoning": "Ufanani wa juu kulingana na maslahi ya nje yanayoshirikiwa na shauku ya picha. Watumiaji wote wanaonyesha roho za kihamasiri na kuthamini asili, kuunda msingi imara wa uhusiano wa maana.",
    "commonInterests": [
      "picha",
      "shughuli za nje",
      "safari",
      "kuthamini asili"
    ],
    "confidence": 0.92
  }
}
```

## 🔍 Response Fields

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `matchScore` | float | Compatibility score (0.0-1.0) | 0.85 |
| `reasoning` | string | Detailed explanation of compatibility | "High compatibility based on..." |
| `commonInterests` | array[string] | Shared interests and hobbies | ["photography", "outdoor activities"] |
| `confidence` | float | AI confidence in prediction (0.0-1.0) | 0.92 |

### Match Score Interpretation

| Score Range | Compatibility Level | Description |
|-------------|-------------------|-------------|
| 0.9 - 1.0 | **Exceptional** | Very high compatibility, strong potential |
| 0.8 - 0.89 | **High** | Good compatibility, promising connection |
| 0.7 - 0.79 | **Good** | Moderate compatibility, worth exploring |
| 0.6 - 0.69 | **Fair** | Some compatibility, limited potential |
| 0.5 - 0.59 | **Moderate** | Basic compatibility, uncertain potential |
| 0.0 - 0.49 | **Low** | Limited compatibility, low potential |

## 🧪 Testing Examples

### English Match Prediction
```bash
curl -X POST "https://agents.joinwink.app/api/v1/ai-agents/match/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userProfile": "Adventure-loving photographer who enjoys hiking and coffee",
    "potentialMatchProfile": "Nature enthusiast who loves outdoor activities and travel",
    "userInterests": ["photography", "hiking", "coffee", "travel"],
    "matchInterests": ["outdoors", "travel", "photography", "music"],
    "location": "San Francisco, CA",
    "language": "en"
  }'
```

### Spanish Match Prediction
```bash
curl -X POST "https://agents.joinwink.app/api/v1/ai-agents/match/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userProfile": "Fotógrafo amante de la aventura que disfruta del senderismo y el café",
    "potentialMatchProfile": "Entusiasta de la naturaleza que ama las actividades al aire libre y los viajes",
    "userInterests": ["fotografía", "senderismo", "café", "viajes"],
    "matchInterests": ["aire libre", "viajes", "fotografía", "música"],
    "location": "San Francisco, CA",
    "language": "es"
  }'
```

### French Match Prediction
```bash
curl -X POST "https://agents.joinwink.app/api/v1/ai-agents/match/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userProfile": "Photographe amateur d'aventure qui aime la randonnée et le café",
    "potentialMatchProfile": "Passionné de nature qui aime les activités extérieures et les voyages",
    "userInterests": ["photographie", "randonnée", "café", "voyage"],
    "matchInterests": ["extérieur", "voyage", "photographie", "musique"],
    "location": "San Francisco, CA",
    "language": "fr"
  }'
```

## 🔗 Integration Examples

### JavaScript/TypeScript
```typescript
class MatchPredictionService {
  private baseURL = 'https://agents.joinwink.app/api/v1/ai-agents';
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async predictMatch(user1: any, user2: any, language: string = 'en'): Promise<any> {
    const response = await fetch(`${this.baseURL}/match/predict`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userProfile: user1.profile,
        potentialMatchProfile: user2.profile,
        userInterests: user1.interests,
        matchInterests: user2.interests,
        location: user1.location,
        language
      })
    });

    return response.json();
  }

  async getMatchInsights(matchData: any, language: string = 'en'): Promise<any> {
    // Additional analysis based on match prediction
    const insights = await this.predictMatch(matchData.user1, matchData.user2, language);
    return {
      ...insights,
      recommendations: this.generateRecommendations(insights.data.matchScore, language)
    };
  }

  private generateRecommendations(score: number, language: string): string[] {
    if (score >= 0.8) {
      return language === 'es' 
        ? ["¡Excelente compatibilidad! Considera iniciar una conversación", "Tienen muchos intereses en común"]
        : ["Excellent compatibility! Consider starting a conversation", "You have many interests in common"];
    }
    return language === 'es'
      ? ["Compatibilidad moderada, pero vale la pena explorar", "Enfócate en intereses compartidos"]
      : ["Moderate compatibility, but worth exploring", "Focus on shared interests"];
  }
}
```

### React Native
```javascript
class MatchPredictionService {
  constructor(apiKey) {
    this.baseURL = 'https://agents.joinwink.app/api/v1/ai-agents';
    this.apiKey = apiKey;
  }

  async predictMatch(user1, user2, language = 'en') {
    const response = await fetch(`${this.baseURL}/match/predict`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userProfile: user1.profile,
        potentialMatchProfile: user2.profile,
        userInterests: user1.interests,
        matchInterests: user2.interests,
        location: user1.location,
        language
      })
    });

    return response.json();
  }

  async getBatchPredictions(users, currentUser, language = 'en') {
    const predictions = [];
    
    for (const user of users) {
      try {
        const prediction = await this.predictMatch(currentUser, user, language);
        predictions.push({
          userId: user.id,
          ...prediction.data
        });
      } catch (error) {
        console.error(`Failed to predict match for user ${user.id}:`, error);
      }
    }

    // Sort by match score
    return predictions.sort((a, b) => b.matchScore - a.matchScore);
  }
}
```

## 🚀 Best Practices

### 1. Language Handling
- **Always specify language**: Include user's language preference in every request
- **Localized reasoning**: Ensure compatibility explanations are culturally appropriate
- **Consistent terminology**: Use consistent language across all match predictions

### 2. Profile Analysis
- **Rich context**: Provide detailed profile descriptions for better analysis
- **Interest matching**: Include comprehensive lists of user interests
- **Location context**: Consider geographic factors in compatibility

### 3. Result Interpretation
- **Score context**: Explain what match scores mean to users
- **Actionable insights**: Provide clear next steps based on compatibility
- **Confidence levels**: Communicate AI confidence in predictions

## ⚠️ Error Handling

### Common Errors

| Error Code | Description | Solution |
|------------|-------------|----------|
| `invalid_profile` | Profile text too short or missing | Ensure profiles are detailed (50+ characters) |
| `missing_interests` | No interests provided | Include at least 3-5 user interests |
| `invalid_language` | Unsupported language code | Use supported language codes (en, es, fr, etc.) |
| `insufficient_data` | Not enough data for prediction | Provide more detailed profile information |

### Error Response Example
```json
{
  "success": false,
  "error": {
    "code": "insufficient_data",
    "message": "Not enough profile data for accurate prediction",
    "details": "Please provide more detailed profile descriptions",
    "language": "en"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

## 📈 Rate Limits

- **Standard Plan**: 100 requests/hour
- **Premium Plan**: 500 requests/hour  
- **Enterprise Plan**: 2000 requests/hour

## 🔮 Advanced Features

### Compatibility Analysis
- **Multi-dimensional scoring**: Considers interests, values, lifestyle, and goals
- **Cultural awareness**: Adapts analysis based on user's cultural background
- **Behavioral patterns**: Learns from user interactions and preferences

### Predictive Insights
- **Long-term potential**: Assesses compatibility beyond initial attraction
- **Communication style**: Analyzes potential communication patterns
- **Shared values**: Identifies core value alignment

### Quality Assurance
- **Confidence scoring**: Provides reliability metrics for each prediction
- **Fallback mechanisms**: Ensures response quality even with limited data
- **Continuous learning**: Improves accuracy based on user feedback

## 🎯 Use Cases

### Dating Apps
- **Initial matching**: Screen potential matches based on compatibility
- **Conversation starters**: Generate relevant conversation topics
- **Date suggestions**: Recommend activities based on shared interests

### Relationship Counseling
- **Compatibility assessment**: Evaluate long-term relationship potential
- **Communication insights**: Identify potential communication challenges
- **Growth opportunities**: Suggest areas for relationship development

### Social Networking
- **Friend matching**: Connect users with similar interests
- **Group formation**: Create communities based on shared passions
- **Event recommendations**: Suggest relevant social activities

---

**Previous**: [Bio Optimization Agent](/api-reference/ai-agents/bio-optimization) | **Next**: [Chat Response Agent](/api-reference/ai-agents/chat-response)
