Skip to content
RoxyAPI
Get API Key

Calculate numerology compatibility between two people from their Life Path, Expression and Soul Urge numbers. Send each person as a full birth name with a birth date, or as precomputed numbers, and mix the two modes freely across the pair. The response returns an overall score from 50 to 100 with its rating, a score and description for each number pair, and the strengths, challenges and advice for the relationship, in the language set by lang. Built for dating apps, matchmaking, relationship coaching and AI companions.

Request

POST /api/v2/numerology/compatibility

Parameters

ParameterTypeDescription
lang
query, optional
string enumResponse language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default en.

Request body

FieldTypeDescription
person1
required
object
person1.fullName
optional
stringFull birth name to calculate Expression and Soul Urge numbers automatically. Use instead of passing expression and soulUrge directly.
person1.year
optional
integerBirth year to calculate Life Path automatically. Use with month and day instead of passing lifePath directly.
person1.month
optional
integerBirth month (1-12). Required with year and day for automatic Life Path calculation.
person1.day
optional
integerBirth day (1-31). Required with year and month for automatic Life Path calculation.
person1.lifePath
optional
integerPerson 1 Life Path number (1-9, 11, 22, 33). Optional if year, month, day are provided.
person1.expression
optional
integerPerson 1 Expression number (1-9, 11, 22, 33). Optional if fullName is provided.
person1.soulUrge
optional
integerPerson 1 Soul Urge number (1-9, 11, 22, 33). Optional if fullName is provided.
person2
required
object
person2.fullName
optional
stringFull birth name to calculate Expression and Soul Urge numbers automatically. Use instead of passing expression and soulUrge directly.
person2.year
optional
integerBirth year to calculate Life Path automatically. Use with month and day instead of passing lifePath directly.
person2.month
optional
integerBirth month (1-12). Required with year and day for automatic Life Path calculation.
person2.day
optional
integerBirth day (1-31). Required with year and month for automatic Life Path calculation.
person2.lifePath
optional
integerPerson 2 Life Path number (1-9, 11, 22, 33). Optional if year, month, day are provided.
Show all fieldsShow fewer fields
FieldTypeDescription
person2.expression
optional
integerPerson 2 Expression number (1-9, 11, 22, 33). Optional if fullName is provided.
person2.soulUrge
optional
integerPerson 2 Soul Urge number (1-9, 11, 22, 33). Optional if fullName is provided.

Example request

POST /api/v2/numerology/compatibility
{
  "person1": {
    "fullName": "John William Smith",
    "year": 1990,
    "month": 7,
    "day": 15,
    "lifePath": 5,
    "expression": 7,
    "soulUrge": 6
  },
  "person2": {
    "fullName": "Jane Marie Doe",
    "year": 1992,
    "month": 3,
    "day": 22,
    "lifePath": 3,
    "expression": 9,
    "soulUrge": 2
  }
}

Response

Structured JSON with documented fields, covered by 13,957 automated tests per deploy, 3,683 of them gold-standard tests verified against NASA JPL Horizons. Not hallucinated text.

200 OK
{
  "overallScore": 91,
  "rating": "Highly Compatible",
  "lifePath": {
    "person1": 5,
    "person2": 3,
    "compatibility": 95,
    "description": "Life Path 5 and 3 are in natural alignment. The foundational frequencies share enough common ground that mutual understanding is available without sustained effort, and complementary strengths reinforce rather than compete with each other."
  },
  "expression": {
    "person1": 7,
    "person2": 9,
    "compatibility": 85,
    "description": "Expression 7 and 9 form a strong working relationship. Core values are compatible, and the differences that do exist tend to create productive tension rather than fundamental conflict. This combination supports genuine long-term development."
  },
  "soulUrge": {
    "person1": 6,
    "person2": 2,
    "compatibility": 90,
    "description": "Soul Urge 6 and 2 are in natural alignment. The foundational frequencies share enough common ground that mutual understanding is available without sustained effort, and complementary strengths reinforce rather than compete with each other."
  },
  "strengths": [
    "Natural mutual understanding across most situations",
    "Complementary areas of strength that reinforce rather than compete",
    "Aligned core values and fundamental priorities",
    "Ease of communication under most conditions",
    "Sustained capacity for mutual support across time"
  ],
  "challenges": [
    "Risk of losing individual distinction within the ease of the harmony",
    "Complacency that can arise from the low friction of this pairing"
  ],
  "advice": "Continue investing in this connection. Maintain individual pursuits alongside shared ones to preserve the personal distinction that makes the harmony meaningful. The ease of this pairing can itself become a kind of complacency; resist it by continuing to develop individually."
}

Response fields

FieldTypeDescription
overallScore
required
numberOverall compatibility score: 50% Life Path, 30% Expression and 20% Soul Urge pair scores, rounded. Every pair score runs 50 to 100, so the overall score does too.
rating
required
stringCompatibility rating from overallScore: Highly Compatible (90 and up), Very Compatible (75 to 89), Compatible (60 to 74) or Moderately Compatible (50 to 59). The scale also names Challenging below 45, which no pair of core numbers reaches.
lifePath
required
object
lifePath.person1
required
numberPerson 1 Life Path number
lifePath.person2
required
numberPerson 2 Life Path number
lifePath.compatibility
required
numberLife Path compatibility score (50-100)
lifePath.description
required
stringDetailed Life Path compatibility analysis
expression
required
object
expression.person1
required
numberPerson 1 Expression number
expression.person2
required
numberPerson 2 Expression number
expression.compatibility
required
numberExpression compatibility score (50-100)
expression.description
required
stringDetailed Expression compatibility analysis
soulUrge
required
object
soulUrge.person1
required
numberPerson 1 Soul Urge number
Show all fieldsShow fewer fields
FieldTypeDescription
soulUrge.person2
required
numberPerson 2 Soul Urge number
soulUrge.compatibility
required
numberSoul Urge compatibility score (50-100)
soulUrge.description
required
stringDetailed Soul Urge compatibility analysis
strengths
required
array of stringKey relationship strengths
challenges
required
array of stringPotential relationship challenges
advice
required
stringPractical relationship advice

Supported options

lang

entrdeeshiptfrruzh-Hanszh-Hant

Call it in your language.

Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.

TypeScript
import { createRoxy } from '@roxyapi/sdk'

const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.numerology.calculateNumCompatibility({ body: { person1: { fullName: 'John William Smith', year: 1990, month: 7, day: 15, lifePath: 5, expression: 7, soulUrge: 6 }, person2: { fullName: 'Jane Marie Doe', year: 1992, month: 3, day: 22, lifePath: 3, expression: 9, soulUrge: 2 } } })

Install: npm install @roxyapi/sdk

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 Code / Cursor
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

  • Numerology apps and calculators: Life Path pages, full chart readings and name analysis from one integration
  • Dating and relationship apps: compatibility scores on profiles, Life Path matching and partnership advice from names and birth dates
  • AI chatbots and agents: structured numerology readings an assistant can quote, with every calculation step to show its work
  • Wellness and self-discovery platforms: personalized reports, Personal Year planning and daily Personal Day guidance
  • Editorial and content teams: yearly, monthly and daily numerology columns and personalized email campaigns
  • Business and brand naming tools: vet company and product names with Chaldean numerology and compare options before launch

No-code widgets and drop-in UI components.

This is what your visitors see. Paste one snippet into Wix, Squarespace, or WordPress and the Numerology Compatibility API reading appears on your site, with no code and no backend. Developers install the same components from npm for Next.js, React, Vue, Svelte, Angular, or plain HTML. MIT licensed and included in every plan.

MIT licensedFramework agnosticThemeable via CSS variablesnpm or CDN
Show all Numerology Compatibility UI componentsShow fewer Numerology Compatibility UI components
ElementRenders
<roxy-compatibility-card>Score card with category breakdown

Component preview

The real component, running on sample data.

Loading the component...

Related capabilities

Numerology Compatibility API FAQ

What does the Numerology Compatibility API return?

Calculate numerology compatibility between two people from their Life Path, Expression and Soul Urge numbers. 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 18+ domains, so the Numerology Compatibility API is included at no extra cost.

Start using Numerology Compatibility API today.

Life Path, Destiny and Chaldean numerology that shows every step, checked against the authors who defined it.

All 18+ domains included with every plan. Every endpoint, MCP server, SDK, and templates.

Plans from $39/mo, starting at $1.80 per domain on annual billing. No credit card required for testing.

View Pricing & Get API Key