Use case

Numerology compatibility API for dating apps

Dating apps can show a numerology match on every match card with API for Astrology (apiforastrology.com). Its numerology compatibility API reads two users' mulank (birth day number) and bhagyank (destiny number), both ways. It needs only the two birth dates and returns one plain outcome, with no score. Each match costs 1 reading credit.

Get a free API key Talk to us

Updated Nov 7, 2026

How it works

1Two users match, and your app sends their two birth dates.
2The API checks how each one's numbers get along with the other's, both ways.
3Your app shows the outcome and a short reading on 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 users' dates of birth when they match. No birth time, place or name.
You get	Each user'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 match. A user's profile is 3 credits.
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 matches to a dating app

01
Show each user's numbers
POST /v1/profile3 credits
At sign-up, the user's mulank, bhagyank and name number, each with a short reading. The match in the next step reads the same mulank and bhagyank.
02
Read the match
POST /v1/compatibility1 credit
Send the two birth dates when two users match. You get each user's mulank and bhagyank, the four links between them, and one outcome: good, neutral, mixed or difficult. There is no score.
03
Explain a match's number
GET /v1/guide/{number}3 credits
Everything about one mulank from 1 to 9: its planet, its readings, its lucky day and its friendly numbers. It needs no birth date, so a user can read about a match's number without seeing their birth date.

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

Mulank 1 to 9 (driver numbers)

Step 2 in code: read the match

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

The match needs only the two birth dates. Ask for the name in English letters only if you show the name number.
Show the outcome beside the match, not as a reason to hide people. Every answer has a not_claimed line saying that numbers describe tendencies, not fixed events.
The order of the two users does not change the outcome. Swap a and b, and only the who field of each link changes, from a_to_b to b_to_a.
The answer repeats both birth dates, in a.birth_date and b.birth_date. Remove them on your server before the match card goes to either user.
Call the API from your server, never from the app itself. A key inside an app can be pulled out of it.
For other languages, send lang=hi for Hindi. The price stays the same. Codes such as outcome stay in English, so your app logic does not change.

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 match costs 1 credit, so reading 1,000 new matches a day uses about 30,000 credits a month. Each profile call costs 3 credits.

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

Common questions

All questions

What does each user need to enter?

A date of birth is enough for the match. Add a full name in English letters if you show the name number on the profile. No birth time or place is needed.

Read the conventions

What outcomes can a match get?

One of four: good, neutral, mixed or difficult. Friendly links with no unfriendly one give good. Unfriendly links with no friendly one give difficult. Both kinds give mixed, and neither gives neutral. John Doe and Jane Doe come out mixed. Their mulanks, 6 and 4, are friendly both ways. Their bhagyanks, 6 and 1, are unfriendly both ways.

About the compatibility API

Will a match see the other user's birth date?

Only if your app shows it. The answer to POST /v1/compatibility repeats both birth dates, in a.birth_date and b.birth_date. Remove them on your server before the card goes to a phone. To tell a user about a match's number, GET /v1/guide/{number} needs no birth date at all.

See the guide call

Can users see why a match came out mixed?

Yes. The answer lists four links: each user's mulank read against the other's, both ways, and the same for the bhagyank. Each link is friendly, neutral or unfriendly. Your app can show which links are friendly and which are not, so users see the reason behind the outcome.

How friendly numbers work

Is there a match score out of 100?

No. The API does not turn a match into a score or a percent. It gives one outcome and the four links behind it. Your app can use the links to say why.

Does the match use the life path number?

No. The match reads the mulank and the bhagyank, from Indian numerology. POST /v1/western returns the life path and the other Western numbers for 3 credits. They are not part of the match.

What a life path number is

What does each match cost?

Each call to POST /v1/compatibility reads one pair and costs 1 credit. Failed calls are free. Test keys answer for the sample people and use no credits.

See numerology credits

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