Compatibility Score¶

The Compatibility Score analyzes 9 core numerology numbers from two individuals (Life Path, Heart's Desire, Personality, etc.) and returns:

• Individual numerology profiles
• Pairwise compatibility scores
• Weighted overall score (0–100)
• Relationship insight

Perfect for dating, marriage, business, or friendship analysis. Master Numbers: Fully supported (11, 22, 33).

Endpoint¶

Required Headers¶

• X-API-Key: YOUR_API_KEY
• Host: api.numerologyapi.com
• Content-Type: application/json (POST only)

Create and manage API keys in the Numerology API dashboard.

Parameters¶

Person 1¶

Person 2¶

| language | string | Yes | Language code for the response. Supported values include en, fr, es, de, pt, ja, hi, ar, ru, tr, it, pl, nl, id, ko, th, ro, ur, gu, bn, vi, ta, te, mr, pa, zh, etc. | | lang | string | Yes | Alias for language. Use either language or lang. |

Add the optional lang query parameter to localize responses. Supported values: en, fr, es, de, pt, ja, hi, ar, ru, tr, it, pl, nl, id, ko, th, ro, ur, gu, bn, vi, ta, te, mr, pa, zh.

Example Requests¶

GET Request¶

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/compatibility-score?first_name_1=John&last_name_1=Doe&first_name_2=John&last_name_2=Doe&dob_1=1992-07-16&dob_2=1992-07-16&middle_name_1=&middle_name_2=&lang=en&num_sys=pythagorean" \
  --header "X-API-Key: YOUR_API_KEY"

POST Request (JSON Body)¶

curl --request POST \
  --url "https://api.numerologyapi.com/api/v1/compatibility-score?lang=en" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "first_name_1": "John",
  "last_name_1": "Doe",
  "first_name_2": "John",
  "last_name_2": "Doe",
  "dob_1": "1992-07-16",
  "dob_2": "1992-07-16",
  "middle_name_1": "",
  "middle_name_2": "",
  "num_sys": "pythagorean"
}'

{
  "numerology_system": "pythagorean",
  "person_1": {
    "full_name": "John Doe",
    "initials": "JD",
    "dob": "1992-07-16",
    "life_path": 8,
    "heart_desire": 8,
    "personality": 9,
    "hidden_passion": [
      5,
      6
    ],
    "destiny_number": 8,
    "attitude_number": 5,
    "subconscious_self_number": 5,
    "balance_number": 5,
    "rational_thought_number": 9
  },
  "person_2": {
    "full_name": "John Doe",
    "initials": "JD",
    "dob": "1992-07-16",
    "life_path": 8,
    "heart_desire": 8,
    "personality": 9,
    "hidden_passion": [
      5,
      6
    ],
    "destiny_number": 8,
    "attitude_number": 5,
    "subconscious_self_number": 5,
    "balance_number": 5,
    "rational_thought_number": 9
  },
  "compatibility_scores": {
    "life_path_score": 80,
    "heart_desire_score": 80,
    "personality_score": 85,
    "hidden_passion_score": 95,
    "destiny_number_score": 80,
    "attitude_number_score": 95,
    "subconscious_self_score": 95,
    "balance_number_score": 95,
    "rational_thought_score": 85,
    "overall_score": 86.8,
    "overall_insight": "Very strong & harmonious connection. Your energies flow together with grace and mutual support. This is a relationship that feels like 'coming home' — powerful synergy with only gentle adjustments needed."
  },
  "_enterprise": {
    "client": "The Numerology API",
    "plan": "Enterprise",
    "request_id": "92aa5c5bf8d310f1",
    "quota": "unlimited",
    "usage_tracking": true
  },
  "_api_metadata_": {
    "api_name": "The Numerology API by Dakidarts®",
    "api_version": "1.0.2",
    "endpoint_name": "compatibility_score",
    "endpoint_description": "Computes numerology compatibility score between two individuals.",
    "developer": "Dakidarts®",
    "copyright": "© 2026 Dakidarts®. All rights reserved.",
    "documentation_url": "https://docs.numerologyapi.com/",
    "response_timestamp": "2026-08-18T01:05:42.274217+01:00",
    "data_source": "Internal Engine",
    "cacheable_status": true,
    "report_issue": "https://github.com/dakidarts/the-numerology-api/issues",
    "response_language": "en",
    "supported_languages": [
      "en",
      "fr",
      "es",
      "de",
      "pt",
      "ja",
      "hi",
      "ar",
      "ru",
      "tr",
      "it",
      "pl",
      "nl",
      "id",
      "ko",
      "th",
      "ro",
      "ur",
      "gu",
      "bn",
      "vi",
      "ta",
      "te",
      "mr",
      "pa",
      "zh"
    ],
    "notes": ""
  }
}

Scoring Algorithm¶

The compatibility scoring algorithm uses a multi-layered approach that combines numerological wisdom with mathematical precision:

1. Root Number Mapping: All numbers (including Master Numbers 11, 22, 33) are mapped to their root vibrations (e.g., 11→2, 22→4, 33→6). Calculations use these root values for compatibility assessment.

2. Numerological Pair Definitions: Specific number pairs known for strong compatibility in numerology are assigned predetermined base scores. For example:

   • (1, 5) and (5, 1): 85 (Adventure-driven combination)
   • (1, 9) and (9, 1): 75 (Leadership meets humanitarianism)
   • (2, 6) and (6, 2): 90 (Nurturing partnership)

3. Fallback Calculation: If a pair is not explicitly defined, a standard formula is used: base_score = max(25, 100 - root_diff * 10), ensuring a minimum baseline compatibility of 25%.

4. Master Number Resonance Bonus: Pairs involving Master Numbers receive additional points if their root values are identical (+15) or adjacent (+8), reflecting their intensified spiritual energy.

5. Exact Match Bonus: When both original numbers (before root reduction) are identical, an extra +10 bonus is applied, acknowledging the resonance of shared vibration.

6. Final Calculation: The total score is the sum of the base score, master bonus, and exact match bonus, capped at 100%.

Scoring Weights¶

Overall Score = Weighted average of individual scores + Intensity Factor. Intensity Factor: A small boost (up to +5%) is applied if either person's Life Path or Heart's Desire is a Master Number, reflecting their potential for deeper spiritual connection.

Overall Insight Levels¶

Open Dashboard