Use case

Numerology compatibility API for matrimony sites

Matrimony sites can show a numerology match beside the kundli (birth chart) score with API for Astrology (apiforastrology.com). Its numerology compatibility API reads two members' mulank (birth day number) and bhagyank (destiny number), both ways. It needs only two birth dates, so members with no birth time can be matched too. Each pair costs 1 reading credit.

Get a free API key Talk to us

Updated Nov 7, 2026

How it works

1Your site sends the two members' dates of birth.
2The API reads each member's numbers against the other's, in both directions.
3It returns one plain outcome and a short reading for the match card.

POST /v1/compatibility200 OK

{
  "a": {
    "mulank": 6,
    "bhagyank": 6
  },
  "b": {
    "mulank": 4,
    "bhagyank": 1
  },
  "outcome": "mixed",
  "reading": "Your numbers pull both ways. Some things come easily between you and some need patience."
}

John Doe and Jane Doe: each one's mulank and bhagyank, and the outcome read both ways. Real output for John Doe, born Aug 15, 1990, and Jane Doe, born Mar 22, 1992.

What you send, what you get, what it costs

What you send, what you get and what it costs in reading credits
You send	Two members' dates of birth for each match. No birth time or place.
You get	Each member's mulank and bhagyank, the four links between them, and one outcome: good, neutral, mixed or difficult. There is no score.
It costs	1 credit a pair. A member's profile is 3 credits, and a month of good dates 1 credit.
Credits in a plan	The Free plan has 150 reading credits a month. Paid plans have more: Starter 1,000, Growth 5,000, Scale 22,000. Failed calls are free.

How to add numerology compatibility to a matrimony site

01
Show each member's numbers
POST /v1/profile3 credits
A member's mulank, bhagyank and name number, each with a short reading, for the profile page.
02
Read every pair
POST /v1/compatibility1 credit
Each member's mulank and bhagyank, the four links between them, and one outcome: good, neutral, mixed or difficult. Nothing is scored, so show the outcome and its reading, not a number.
03
Suggest dates for the couple
POST /v1/dates1 credit
Every date of a month read for one person, with the good dates listed. Call it for each partner, and show the dates that are in both lists.

Credits per flow: 5 credits for one of each call above, on a live key.

Mulank 1 to 9 (driver numbers)

Step 2 in code: read every pair

Send the details as JSON with your API key in the Authorization header. The other steps work the same way. Each one links to its page in the API reference.

POST /v1/compatibility

# John Doe, born Aug 15, 1990, and Jane Doe, born Mar 22, 1992
curl -X POST "https://apiforastrology.com/api/numerology/v1/compatibility" \
  -H "Authorization: Bearer $ASTROLOGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"a":{"birth_date":"1990-08-15"},"b":{"birth_date":"1992-03-22"}}'

Response (lists shortened)200 OK

{
  "a": {
    "birth_date": "1990-08-15",
    "mulank": 6,
    "bhagyank": 6,
    "mulank_planet": "Venus"
  },
  "b": {
    "birth_date": "1992-03-22",
    "mulank": 4,
    "bhagyank": 1,
    "mulank_planet": "Rahu"
  },
  "links": [
    {
      "from": "mulank",
      "from_number": 6,
      "to_number": 4,
      "relation": "friend",
      "via": [
        "Rahu"
      ],
      "who": "a_to_b",
      "from_name": "mulank",
      "relation_name": "friendly"
    },
    {
      "from": "mulank",
      "from_number": 4,
      "to_number": 6,
      "relation": "friend",
      "via": [
        "Rahu"
      ],
      "who": "b_to_a",
      "from_name": "mulank",
      "relation_name": "friendly"
    }
  ],
  "outcome": "mixed",
  "outcome_name": "Mixed",
  "reading": "Your numbers pull both ways. Some things come easily between you and some need patience.",
  "not_claimed": "Numbers describe tendencies, not fixed events. Use them as a guide, not a rule.",
  "localization": {
    "lang": "en",
    "detail": "standard",
    "fell_back_to_en": [],
    "fell_back_to_standard": []
  }
}

Tips for going live

Show the numerology outcome next to the kundli matching result from the Astrology API (POST /v1/matching). Label each one, so members know which tradition says what.
The order of the two members does not change the outcome. Unlike kundli matching, there is no bride field and no groom field.
Show the reading with the outcome. Two pairs can both come out mixed for different reasons, and the links say which.
One call reads one pair. Call it once for each pair you show.
At a 429 error, wait for the seconds in the Retry-After header. Frequent 429s mean it is time for a larger plan.

Where the rules come from

The mulank (birth day number) is the day of birth, added down to one digit. The 1st, 10th, 19th and 28th all give 1, as in Cheiro's Book of Numbers (1926). Numerology turns a person's name and date of birth into numbers, as described by Encyclopaedia Britannica.

What it costs

Each pair costs 1 credit, so reading 100 new pairs a day uses about 3,000 credits a month.

Numerology uses reading credits from your plan, never calls, and the same key as the Astrology API. Test keys are free, with 1,000 test calls a month, and answer for the sample people. Failed requests are free.

Numerology API pricing

Features used here

From the blog

Common questions

All questions

How is numerology matching different from kundli matching?

Kundli matching (POST /v1/matching on the Astrology API) scores two birth charts out of 36 points. It needs full birth details. Numerology compatibility (POST /v1/compatibility) reads only the two birth dates. It gives a plain outcome and a short reading, with no score. You can show both on one match card.

About the kundli matching API

Does the numerology match change if we swap members a and b?

No. The API reads both directions, a to b and b to a, for the mulank and for the bhagyank. Swapping the two gives the same outcome. Only the who field of each link changes, from a_to_b to b_to_a.

About the compatibility API

What outcomes can a pair get?

One of four, by one stated rule: good, neutral, mixed or difficult. A friendly link and no unfriendly one is good. An unfriendly link and no friendly one is difficult. One of each is mixed, and neither is neutral. John Doe and Jane Doe come out mixed.

How a fit is decided

Can numerology match members who do not know their birth time?

Yes. Numerology uses only the date of birth, with no time or place. Every member who gives a birth date can be matched.

What a bhagyank is

Can we compare one profile with many others in a single call?

No. Each call to POST /v1/compatibility reads one pair and costs 1 credit. To show matches for one member, call it once for each pair.

See numerology credits

Can members see their own numbers on their profile?

Yes. POST /v1/profile gives a member's mulank (birth day number), bhagyank (destiny number) and name number, each with a short reading. It costs 3 credits.

About the core numbers

Can we suggest good dates for an engagement or a wedding?

POST /v1/dates reads every date of a month for one person and lists the good ones. Call it for each partner, and show the dates that are good for both. Each call costs 1 credit.

What favorable dates are

Numerology API

Start with a free test key

Create an account and a test key, then try each step above with the sample people. Need more than the largest plan? Write to us.

Get a free API key Open the API reference

Your first answer

John Doe, born Aug 15, 1990

POST /v1/profile200 OK

Mulank6Venus
Bhagyank6Destiny number
Name number7Ketu

Real API output. A free test key gets the same answer.

01
Test key: 1,000 test calls a month to build with
02
Free plan: 2,000 live calls a month, no card needed
03
One key: the same key, plan and reading credits as the Astrology API

Numerology compatibility API for matrimony sites

How it works

What you send, what you get, what it costs

How to add numerology compatibility to a matrimony site

Show each member's numbers

Read every pair

Suggest dates for the couple