Numerology Compatibility API
Relationship dynamics between two people
Calculate numerology compatibility between two people using Pythagorean numerology. Accepts two input modes per person: pre-calculated Life Path, Expression, and Soul Urge numbers, or raw name and birthdate for automatic calculation. You can mix modes across persons (e.g. numbers for person1, raw inputs for person2). Provides comprehensive relationship analysis with overall compatibility score (0-100), individual aspect compatibility (Life Path 50% weight, Expression 30%, Soul Urge 20%), relationship strengths, challenges, and practical advice. Uses detailed compatibility matrix for all number combinations. Perfect for dating apps, relationship counseling platforms, matchmaking services, and compatibility tools. Get actionable insights for improving relationship dynamics.
Request
POST /api/v2/numerology/compatibility
Parameters
| Parameter | Type | Description |
|---|---|---|
| langquery | string enum | Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English. Default en. |
Request body
| Field | Type | Description |
|---|---|---|
| person1* | object | |
| person1.lifePath | integer | Person 1 Life Path number (1-9, 11, 22, 33). Optional if year, month, day are provided. |
| person1.expression | integer | Person 1 Expression number (1-9, 11, 22, 33). Optional if fullName is provided. |
| person1.soulUrge | integer | Person 1 Soul Urge number (1-9, 11, 22, 33). Optional if fullName is provided. |
| person1.fullName | string | Full birth name to calculate Expression and Soul Urge numbers automatically. Use instead of passing expression and soulUrge directly. |
| person1.year | integer | Birth year to calculate Life Path automatically. Use with month and day instead of passing lifePath directly. |
| person1.month | integer | Birth month (1-12). Required with year and day for automatic Life Path calculation. |
| person1.day | integer | Birth day (1-31). Required with year and month for automatic Life Path calculation. |
| person2* | object | |
| person2.lifePath | integer | Person 2 Life Path number (1-9, 11, 22, 33). Optional if year, month, day are provided. |
| person2.expression | integer | Person 2 Expression number (1-9, 11, 22, 33). Optional if fullName is provided. |
| person2.soulUrge | integer | Person 2 Soul Urge number (1-9, 11, 22, 33). Optional if fullName is provided. |
| person2.fullName | string | Full birth name to calculate Expression and Soul Urge numbers automatically. Use instead of passing expression and soulUrge directly. |
| person2.year | integer | Birth year to calculate Life Path automatically. Use with month and day instead of passing lifePath directly. |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
| person2.month | integer | Birth month (1-12). Required with year and day for automatic Life Path calculation. |
| person2.day | integer | Birth day (1-31). Required with year and month for automatic Life Path calculation. |
Example request
{
"person1": {
"lifePath": 5,
"expression": 7,
"soulUrge": 6,
"fullName": "John William Smith",
"year": 1990,
"month": 7,
"day": 15
},
"person2": {
"lifePath": 3,
"expression": 9,
"soulUrge": 2,
"fullName": "Jane Marie Doe",
"year": 1992,
"month": 3,
"day": 22
}
}Response
Structured JSON with documented fields, verified against NASA JPL Horizons across 828 gold-standard tests. Not hallucinated text.
{
"overallScore": 78,
"rating": "Very Compatible",
"lifePath": {
"person1": 5,
"person2": 3,
"compatibility": 85,
"description": "5 and 3 create an exciting dynamic partnership..."
},
"expression": {
"person1": 7,
"person2": 9,
"compatibility": 70,
"description": "7 and 9 share spiritual depth..."
},
"soulUrge": {
"person1": 6,
"person2": 2,
"compatibility": 90,
"description": "6 and 2 have complementary emotional needs..."
},
"strengths": [
"Complementary personalities",
"Shared values",
"Mutual growth support",
"Emotional harmony"
],
"challenges": [
"Different communication styles",
"Need for independence vs togetherness",
"Pace of life differences"
],
"advice": "This relationship thrives on mutual respect and space for individual growth. Focus on..."
}Response fields
| Field | Type | Description |
|---|---|---|
| overallScore* | number | Overall compatibility score (0-100) |
| rating* | string | Compatibility rating: Highly Compatible, Very Compatible, Compatible, Moderately Compatible, or Challenging. |
| lifePath* | object | |
| lifePath.person1* | number | Person 1 Life Path number |
| lifePath.person2* | number | Person 2 Life Path number |
| lifePath.compatibility* | number | Life Path compatibility score (0-100) |
| lifePath.description* | string | Detailed Life Path compatibility analysis |
| expression* | object | |
| expression.person1* | number | Person 1 Expression number |
| expression.person2* | number | Person 2 Expression number |
| expression.compatibility* | number | Expression compatibility score (0-100) |
| expression.description* | string | Detailed Expression compatibility analysis |
| soulUrge* | object | |
| soulUrge.person1* | number | Person 1 Soul Urge number |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
| soulUrge.person2* | number | Person 2 Soul Urge number |
| soulUrge.compatibility* | number | Soul Urge compatibility score (0-100) |
| soulUrge.description* | string | Detailed Soul Urge compatibility analysis |
| strengths* | array of string | Key relationship strengths |
| challenges* | array of string | Potential relationship challenges |
| advice* | string | Practical relationship advice |
Supported options
lang
Call it in your language in seconds.
Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.numerology.calculateNumCompatibility({ body: { person1: { lifePath: 5, expression: 7, soulUrge: 6, fullName: 'John William Smith', year: 1990, month: 7, day: 15 }, person2: { lifePath: 3, expression: 9, soulUrge: 2, fullName: 'Jane Marie Doe', year: 1992, month: 3, day: 22 } } })from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.numerology.calculate_num_compatibility(person1={'lifePath': 5, 'expression': 7, 'soulUrge': 6, 'fullName': 'John William Smith', 'year': 1990, 'month': 7, 'day': 15}, person2={'lifePath': 3, 'expression': 9, 'soulUrge': 2, 'fullName': 'Jane Marie Doe', 'year': 1992, 'month': 3, 'day': 22})use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->numerology->calculateNumCompatibility(person1: ['lifePath' => 5, 'expression' => 7, 'soulUrge' => 6, 'fullName' => 'John William Smith', 'year' => 1990, 'month' => 7, 'day' => 15], person2: ['lifePath' => 3, 'expression' => 9, 'soulUrge' => 2, 'fullName' => 'Jane Marie Doe', 'year' => 1992, 'month' => 3, 'day' => 22]);using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Numerology.Compatibility.PostAsync(new() { /* request fields above */ });import roxyapi "github.com/RoxyAPI/sdk-go"
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Numerology.CalculateNumCompatibility(ctx, nil, roxyapi.CalculateNumCompatibilityJSONRequestBody{ /* request fields above */ })curl -X POST "https://roxyapi.com/api/v2/numerology/compatibility" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"person1":{"lifePath":5,"expression":7,"soulUrge":6,"fullName":"John William Smith","year":1990,"month":7,"day":15},"person2":{"lifePath":3,"expression":9,"soulUrge":2,"fullName":"Jane Marie Doe","year":1992,"month":3,"day":22}}'Prefer to try before you write code? Run this Numerology endpoint live in the API playground and inspect a real production response.
Remote MCP for AI agents
Every Numerology endpoint is a callable tool on the Remote MCP server over Streamable HTTP. No local setup, no Docker. Claude, ChatGPT, Cursor, and any MCP client auto-discover the tools and ground their answers in verified data.
claude mcp add --transport http \
roxy-numerology https://roxyapi.com/mcp/numerology \
--header "X-API-Key: YOUR_KEY"Tool name for POST /numerology/compatibility: post_numerology_compatibility. Full MCP setup guide
What you can build
AI chatbots and assistants - integrate numerology readings into conversational AI, ChatGPT plugins, and virtual spiritual advisors with structured responses
Dating and relationship apps - add compatibility scoring to matchmaking algorithms, display Life Path synastry on profiles, show partnership potential scores
Personalized wellness platforms - generate automated numerology reports, birth chart PDFs, and daily/yearly guidance for meditation and self-discovery apps
Life coaching and therapy tools - support client sessions with Personal Year forecasts, karmic lesson identification, and life purpose clarity from Life Path analysis
Content generation systems - power horoscope-style content, numerology blog posts, and personalized email campaigns with accurate calculations and rich interpretations
Spiritual marketplaces and consultation services - enable quick numerology readings, tiered report generation (basic to premium), and automated client onboarding with full chart analysis
Drop-in UI components
Render Numerology Compatibility API responses without building charts yourself. These open source, framework-agnostic web components take the typed response and draw it, in React, Vue, Svelte, Angular, plain HTML, and WordPress.
Related capabilities
Numerology Compatibility API FAQ
What does the Numerology Compatibility API return?
Calculate numerology compatibility between two people using Pythagorean numerology. Every response is structured JSON with documented fields, not free text, so you map it straight into your product.
How do I authenticate with the Numerology Compatibility API?
Pass your key in the X-API-Key header on every request. Keys are delivered instantly at checkout with no approval queue. Use a secret sk key server side, or mint a publishable pk key locked to your origins for browser and no-code use.
Does the Numerology Compatibility API support multiple languages?
Yes. Append the lang query parameter to any endpoint for responses in English, German, Spanish, French, Hindi, Portuguese, Russian and Turkish. The translated payload includes the full interpretation text, not just field labels.
Is the Numerology Compatibility API available over Remote MCP for AI agents?
Yes. Every endpoint is exposed as a callable tool on the Remote MCP server at https://roxyapi.com/mcp/numerology over Streamable HTTP, so Claude, ChatGPT, Cursor, and any MCP client auto-discover it with no local setup or Docker.
How is the Numerology Compatibility API billed?
Flat pricing: 1 request equals 1 quota unit, REST and MCP identical, with no credit weighting or per-token markup. Every plan includes all 12 domains, so the Numerology Compatibility API is included at no extra cost.
What lang values does the Numerology Compatibility API accept?
The lang parameter accepts en, tr, de, es, hi, pt, fr, ru. Case-insensitive where it is a path value.
Start using Numerology Compatibility API today.
Ship a numerology app your users will love. This week.
All 12 domains included with every plan. Every endpoint, MCP server, SDK, and starters.
Plans from $39/mo, starting at $2.70 per domain on annual billing. No credit card required for testing.
View Pricing & Get API Key