Choosing the right numerology endpoints is critical for building effective spiritual and self-discovery apps. Each endpoint calculates different aspects of a person's numerological profile, and understanding these differences ensures you build features that truly serve your users.

This comprehensive guide breaks down the core RoxyAPI Numerology endpoints, explaining what each calculates, when to use it, and how to optimize performance. By the end, you will know exactly which endpoints your app needs.

Understanding the Endpoint Categories

RoxyAPI's Numerology API organizes into five categories:

1. Core Numbers (Identity Foundation)

Life Path - Life purpose and direction
Expression - Natural talents and abilities
Soul Urge - Inner desires and motivations
Personality - How others perceive you
Birth Day - Special talents from birth day

2. Derived Numbers (Life Stages)

Maturity - Who you become in later life
Personal Year - Annual cycle and forecast

3. Karmic Analysis (Past Life Lessons)

Karmic Debt - Challenges from past lives (13, 14, 16, 19)
Karmic Lessons - Missing number analysis

4. Relationship Analysis

Compatibility - Two-person relationship dynamics

5. Comprehensive Analysis

Complete Chart - All numbers in one request

Let us dive deep into each endpoint.

Core Numbers: The Identity Foundation

These five numbers form your fundamental numerological identity. Most apps need at least 2-3 of these.

Life Path Number

Endpoint: POST /life-path

Input:

{
  "year": 1990,
  "month": 5,
  "day": 15
}

Response: Inspect the current response schema and live examples in the Numerology API reference.

What It Reveals: Your life purpose, natural path, core personality traits. This is the most important number in numerology - if you only calculate one number, make it this.

When to Use:

✅ Onboarding flows (get user's birth date)
✅ Profile pages (primary identity number)
✅ Compatibility matching (50% weight in compatibility)
✅ Daily insights and forecasts
✅ Life purpose guidance features

Master Numbers: Preserves 11, 22, 33 (unlike Personal Year which always reduces to single digits)

Performance: Single calculation per user, cache permanently (birth date never changes)

Use Case Example: Dating app showing "Life Path 3 - Creative Communicator" on profiles

Expression Number (Destiny Number)

Endpoint: POST /expression

Input:

{
  "fullName": "John William Smith"
}

Response: Inspect the endpoint response in the Numerology API reference.

What It Reveals: Natural talents, abilities, life goals, what you came here to do. Calculated from ALL letters in full birth name.

When to Use:

✅ Career guidance features
✅ Talent assessment tools
✅ Personal development apps
✅ Compatibility matching (30% weight)
✅ Name analysis features

Important: Requires exact birth name (not nickname or married name). Validate that users enter full legal name.

Calculation Method: Assigns numbers to letters (A=1, B=2, C=3... Z=26 wrapping around), sums all letters, reduces to single digit or master number.

Performance: Calculate once per user, cache permanently (birth name does not change)

Use Case Example: Career coaching app suggesting "Your Expression 7 indicates gifts for research, analysis, and spiritual teaching"

Soul Urge Number (Heart Desire Number)

Endpoint: POST /soul-urge

Input:

{
  "fullName": "John William Smith"
}

Response: Inspect the endpoint response in the Numerology API reference.

What It Reveals: Inner motivations, emotional needs, what your soul truly wants. Calculated from VOWELS ONLY in full birth name.

When to Use:

✅ Emotional intelligence features
✅ Self-discovery journaling prompts
✅ Meditation and mindfulness apps
✅ Compatibility matching (20% weight)
✅ Relationship counseling platforms

Vowels Used: A, E, I, O, U. Check the returned calculation to see which letters were counted.

Performance: Calculate once per user, cache permanently

Use Case Example: Meditation app providing "Your Soul Urge 6 craves harmony, service, and deep emotional connections"

Personality Number

Endpoint: POST /personality

Input:

{
  "fullName": "John William Smith"
}

Response: Inspect the endpoint response in the Numerology API reference.

What It Reveals: How others perceive you, first impressions, outer personality mask. Calculated from CONSONANTS ONLY in full birth name.

When to Use:

✅ Personal branding tools
✅ Professional development apps
✅ Communication skills training
✅ Social skills coaching
✅ Public speaking preparation

Calculation: Only consonants count (all letters except A, E, I, O, U)

Performance: Calculate once per user, cache permanently

Use Case Example: Professional networking app showing "You project Personality 8: authority, competence, and ambition"

Birth Day Number

Endpoint: POST /birth-day

Input:

{
  "day": 15
}

Response: Inspect the endpoint response in the Numerology API reference.

What It Reveals: Special talents and gifts associated with your birth day (1-31). This is a secondary number that adds nuance to Life Path.

When to Use:

✅ Birthday celebration features
✅ Complete numerology charts
✅ Talent discovery tools
⚠️ Usually NOT standalone (complement to Life Path)

Calculation: The day you were born (1-31) reduced to single digit or master number.

Performance: Extremely fast (no complex calculation), cache permanently

Use Case Example: Birthday greeting notification "Happy Birthday! Your Birth Day 6 gives you natural gifts for nurturing and creating harmony"

Derived Numbers: Life Stages and Cycles

These numbers change over time or combine other numbers.

Maturity Number

Endpoint: POST /maturity

Input:

{
  "lifePath": 3,
  "expression": 7
}

Response: Inspect the current response schema and live examples in the Numerology API reference.

What It Reveals: Who you become in your 40s-50s, blending Life Path and Expression energies. Shows maturation of personality.

When to Use:

✅ Midlife guidance features
✅ Complete numerology charts
✅ Long-term planning tools
⚠️ Requires Life Path and Expression first

Calculation: Life Path + Expression, reduced to single digit or master number

Performance: Calculate after Life Path and Expression, cache permanently

Use Case Example: Life planning app showing "In your 40s, you will embody Maturity Number 1: independent leadership and pioneering spirit"

Personal Year Number

Endpoint: POST /personal-year

Input:

{
  "month": 5,
  "day": 15,
  "year": 2026
}

Response: Inspect the current response schema and live examples in the Numerology API reference.

What It Reveals: Annual cycle and forecast for current year. Follows a 9-year repeating pattern.

When to Use:

✅ Daily insight features
✅ Yearly forecasts and planning
✅ Goal-setting tools aligned with numerology cycles
✅ Push notifications and engagement features

Important: Personal Year ALWAYS reduces to 1-9 (no master numbers in cycles). This differs from other numbers.

Calculation: Birth Month + Birth Day + Current Year, reduced to single digit

Performance: Cache until January 1st of next year (changes annually)

Use Case Example: Daily horoscope app sending "You are in Personal Year 5 - embrace freedom and change today"

Karmic Analysis: Past Life Lessons

These endpoints reveal challenges and lessons from past lives.

Karmic Debt Numbers

Endpoint: POST /karmic-debt

Input:

{
  "fullName": "John William Smith",
  "year": 1990,
  "month": 5,
  "day": 15
}

Response: Inspect the current response schema and live examples in the Numerology API reference.

What It Reveals: Special numbers (13, 14, 16, 19) appearing during calculation that indicate karmic challenges from past lives.

When to Use:

✅ Spiritual guidance apps
✅ Past life exploration features
✅ Challenge identification and growth planning
✅ Deep self-discovery tools

Karmic Debt Numbers:

13: Laziness and negativity in past life → Must work hard now
14: Misuse of freedom → Learn moderation and discipline
16: Destroyed relationships through arrogance → Rebuild with humility
19: Misuse of power → Learn selflessness and service

Performance: Calculate once per user, cache permanently

Use Case Example: Spiritual guidance app showing "You carry Karmic Debt 14 - focus on discipline and balanced living"

Karmic Lessons

Endpoint: POST /karmic-lessons

Input:

{
  "fullName": "John William Smith"
}

Response: Inspect the current response schema and live examples in the Numerology API reference.

What It Reveals: Numbers (1-9) missing from your full birth name, indicating areas where you need to develop skills.

When to Use:

✅ Personal development planning
✅ Skill gap identification
✅ Life coaching platforms
✅ Growth-focused journaling apps

Calculation: Converts name to numbers, identifies which 1-9 are absent

Performance: Calculate once per user, cache permanently

Use Case Example: Life coaching app suggesting "Your missing number 4 means focusing on discipline and practical skills will accelerate your growth"

Relationship Analysis

Compatibility

Endpoint: POST /compatibility

Input:

{
  "person1": {
    "lifePath": 5,
    "expression": 7,
    "soulUrge": 6
  },
  "person2": {
    "lifePath": 3,
    "expression": 9,
    "soulUrge": 2
  }
}

Response: Inspect the current response schema and live examples in the Numerology API reference.

What It Reveals: Relationship dynamics between two people with weighted compatibility scoring.

Scoring Formula:

Life Path: 50% weight (core compatibility)
Expression: 30% weight (goal alignment)
Soul Urge: 20% weight (emotional compatibility)

When to Use:

✅ Dating and matchmaking apps
✅ Relationship counseling platforms
✅ Team building and professional networking
✅ Friendship matching features

Performance: Cache for 7 days (numbers do not change but insights might be re-read)

Use Case Example: Dating app showing "91% Compatible - Exceptional Match" with detailed relationship advice

Comprehensive Analysis

Complete Numerology Chart

Endpoint: POST /chart

Input:

{
  "fullName": "John William Smith",
  "year": 1990,
  "month": 5,
  "day": 15,
  "currentYear": 2026
}

Response: Contains ALL numbers in single response:

Life Path
Expression
Soul Urge
Personality
Birth Day
Maturity
Personal Year
Karmic Debt (if present)
Karmic Lessons (if present)

What It Reveals: Complete numerological profile in one API call.

When to Use:

✅ Onboarding complete profile creation
✅ PDF report generation
✅ Comprehensive dashboard displays
✅ First-time analysis (all data at once)

Trade-offs:

✅ Pros: Single API call, consistent data, 1 request cost
⚠️ Cons: Large response size (~5KB), may include unused data

Performance: Calculate once during onboarding, cache permanently (except Personal Year updates annually)

Use Case Example: Numerology report generator creating PDF with all user numbers from single API call

Endpoint Selection Decision Tree

Use this flowchart to choose endpoints:

For New Users (Onboarding)

Start → Collect birth date and full name

Option A (Fast onboarding):
  → Calculate Life Path only
  → Show primary identity number
  → Calculate others on-demand

Option B (Complete profile):
  → Call /chart endpoint
  → Store all numbers
  → Display comprehensive overview

Recommendation: Option A for mobile apps (faster), Option B for desktop/web apps

For Dating/Relationship Apps

Minimum: Life Path + Expression + Soul Urge
  → Use for /compatibility endpoint
  → Display on profile cards
  → Cache permanently

Optional: Personality number
  → Add to profile "How others see me" section
  → Useful for first-impression optimization

For Spiritual/Self-Discovery Apps

Core set: Life Path + Expression + Soul Urge + Personality
  → Fundamental identity numbers

Add karmic analysis: Karmic Debt + Karmic Lessons
  → Deep self-discovery and challenge identification

Add cycles: Personal Year
  → Timely guidance and daily insights

For Wellness/Lifestyle Apps

Start: Personal Year
  → Daily/weekly insights
  → Low-commitment engagement

Expand: Life Path
  → Profile identity
  → Personalization

Full suite: Complete Chart
  → Premium feature
  → PDF reports

Performance Optimization Strategies

1. Caching Hierarchy

// Permanent cache (never expires)
const PERMANENT_NUMBERS = [
  'lifePath',
  'expression',
  'soulUrge',
  'personality',
  'birthDay',
  'maturity',
  'karmicDebt',
  'karmicLessons',
];

// Annual cache (expires Dec 31)
const ANNUAL_NUMBERS = ['personalYear'];

// Relationship cache (7 days)
const RELATIONSHIP_CACHE_TTL = 604800; // seconds

2. Batch Calculation Strategy

// Bad: Sequential calls (slow)
const lifePath = await calculateLifePath(user);
const expression = await calculateExpression(user);
const soulUrge = await calculateSoulUrge(user);

// Good: Parallel calls (fast)
const [lifePath, expression, soulUrge] = await Promise.all([
  calculateLifePath(user),
  calculateExpression(user),
  calculateSoulUrge(user),
]);

// Best: Single chart call (most efficient)
const chart = await calculateChart(user);

3. Lazy Loading Pattern

// Calculate only what user requests
async function getUserNumber(userId: string, numberType: string) {
  // Check cache first
  const cached = await getCachedNumber(userId, numberType);
  if (cached) return cached;

  // Calculate on-demand
  const result = await calculateNumber(userId, numberType);
  await cacheNumber(userId, numberType, result);

  return result;
}

4. Cost Optimization

Scenario: 10,000 users, each views 3 profiles per day

Approach A (No caching):

10,000 users × 3 profiles × 3 numbers = 90,000 requests a day
About 2.7 million requests a month

Approach B (Smart caching):

Initial calculation: 10,000 users × 3 numbers = 30,000 requests, once
Profile views: cache hits that never reach the API

Savings: caching cuts monthly request volume by about 98.9 percent. Every request is one unit on a flat plan, so the difference decides which plan you need, never a per-call bill.

Endpoint Comparison Matrix

Endpoint	Input Required	Cache Duration	Use Case	Priority
Life Path	Birth date	Permanent	Identity, compatibility	High
Expression	Full name	Permanent	Talents, career	High
Soul Urge	Full name	Permanent	Emotions, desires	Medium
Personality	Full name	Permanent	First impressions	Low
Birth Day	Day only	Permanent	Secondary talents	Low
Maturity	Life Path + Expression	Permanent	Midlife forecast	Low
Personal Year	Birth date + year	Until Dec 31	Daily insights	High
Compatibility	3 numbers × 2 people	7 days	Relationships	High
Karmic Debt	Name + birth date	Permanent	Spiritual growth	Medium
Karmic Lessons	Full name	Permanent	Skill development	Medium
Chart	Name + birth date	Permanent	Complete profile	High

Common Mistakes to Avoid

1. Over-fetching Data

❌ Calling /chart when only Life Path is needed
✅ Calculate specific endpoints on-demand

2. Under-caching

❌ Recalculating Life Path on every profile view
✅ Cache permanently (birth date never changes)

3. Ignoring Master Numbers

❌ Treating 11, 22, 33 as 2, 4, 6
✅ Check type: "master" in response, display accordingly

4. Wrong Name Input

❌ Using nickname "Bob" instead of "Robert"
✅ Always require full legal birth name

5. Personal Year Confusion

❌ Expecting master numbers in Personal Year
✅ Personal Year ALWAYS reduces to 1-9

Production Checklist

Cache Life Path, Expression, Soul Urge permanently
Update Personal Year cache on January 1st
Validate full legal name input (not nicknames)
Handle master numbers (11, 22, 33) specially in UI
Batch API calls with Promise.all()
Implement Redis cache-aside pattern
Monitor API usage and costs
Add fallback UI when API fails
Display calculations in tooltips for transparency
A/B test which numbers drive most engagement

Conclusion

Choosing the right numerology endpoints depends entirely on your app's purpose:

Dating apps: Life Path + Expression + Soul Urge + Compatibility
Career platforms: Life Path + Expression + Maturity
Spiritual apps: Life Path + Karmic Debt + Karmic Lessons + Personal Year
Wellness apps: Personal Year + Life Path
Complete profiles: Chart endpoint for everything at once

Start with Life Path (the foundation), add endpoints as needed, and cache aggressively. With smart endpoint selection and caching, you can build powerful numerology features while staying on the smallest plan even with thousands of users.

Ready to integrate? Try every endpoint free in the live playground, then pick a plan. Full documentation at roxyapi.com/docs.