Numerology Compatibility API

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

{
  "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,405 automated tests per deploy, 3,620 of them gold-standard tests verified against NASA JPL Horizons. Not hallucinated text.

{
  "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."
}

Supported options

Call it in your language.

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: { 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 } } })

from roxy_sdk import create_roxy

roxy = create_roxy("YOUR_API_KEY")
result = roxy.numerology.calculate_num_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})

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->numerology->calculateNumCompatibility(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]);

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":{"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}}'

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

Drop-in UI components and no-code widgets.

Render Numerology Compatibility API responses without building charts yourself. Install the npm package and drop these into Next.js, React, Vue, Svelte, Angular, or plain HTML, or embed the very same component on Squarespace, Wix, or WordPress by pasting one snippet, with no backend and no build step. They belong to one library that covers the entire spiritual stack rather than astrology alone, MIT licensed and included in every plan at no extra cost, never a separate product and never an upsell. The Numerology Compatibility API calculations, the interface that renders them, and the Remote MCP your agent calls, all behind one key, end to end.

Compatibility card widget snippetThe complete UI libraryExplore Roxy UI

Related capabilities

Numerology Compatibility API FAQ