Numerology Matching for Matrimony Sites, Beside the Kundli

Numerology matching fits on a matrimony site as one extra line on the match details panel. It sits under the kundli score, with a label of its own. Run it only when both members have turned it on. One call to POST /v1/compatibility sends the two birth dates and nothing else. Members then see one of four plain labels: Good fit, Neutral, Mixed or Not a good fit. A short reading comes with the label. There is no score, so there is nothing to rank or sort by.

The numbers match also reaches members the kundli match cannot. A kundli (birth chart) match needs each person's birth place, and it reads a birth time. The numbers match needs the date alone. So a member with a birth date and nothing more still gets a match line.

Here is one couple, run on Oct 19, 2026. Our sample pair is John Doe, born Aug 15, 1990, and Jane Doe, born Mar 22, 1992. With full birth details, the Astrology API's kundli match gave them 22.5 of 36 points and the verdict "workable". The Numerology API called the same pair Mixed. The two lines answer different questions. Show them apart, and never blend them into one number.

Three rules keep the feature calm for families. Never filter or hide a profile by its numbers. Keep each member's birth date and numbers off the other member's screen. And print the API's own labels and reading as they come.

Where numerology matching fits in the member journey

A member passes a few screens before sending an interest. The numbers line belongs on only some of them.

Give numbers a switch of its own. A family that follows kundli may not follow numerology. A separate switch lets a member keep one and skip the other. Show the numbers line only when both members turned it on. If one did not, leave the line out. A grayed-out line would tell the viewer that the other member said no.

Keep the label off search cards. A badge on each card turns the label into a sort key, seen before anyone reads a profile. A badge also runs a call for every card on the page, as the credits section below counts.

It reaches members the kundli match cannot

Some members know a birth date but not a birth time. The two matches treat them very differently.

We tested both edges on Oct 19, 2026. First, we sent the kundli match the two birth dates alone. It refused with a 422 answer and the code invalid_input, naming bride.latitude as the missing field. The numbers match took the same two dates and answered.

Next, we sent the kundli match dates and places, with no hours. The API read both births as midnight. Jane and John then scored 17.5 of 36 after the standard exceptions, with the verdict "difficult". With their real birth times, the same pair scored 22.5 and "workable". So never let a blank time field turn into midnight on the kundli line. The kundli matching guide for matrimony sites covers another route. It matches by nakshatra (birth star) and pada (its quarter), for members who know both.

The numbers match has no such gap. Every member with a birth date gets a numbers line. For a member with no time and no birth star, it can be the only match line the panel shows. Say so in a small note, such as "Kundli match needs a birth time."

The request, and what comes back

The request holds two birth dates, one under a and one under b. Our post on numerology compatibility explains how each person's numbers meet the other's in both directions. Here we look only at what a match panel needs.

The pair: John Doe (a), born Aug 15, 1990, and Jane Doe (b), 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"}}'

The answer from our run, trimmed. The four links and the not_claimed line are left out.

{
  "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" },
  "outcome": "mixed",
  "outcome_name": "Mixed",
  "reading": "Your numbers pull both ways. Some things come easily between you and some need patience."
}

John's birthday falls on the 15th. That makes his mulank (birth day number) 1 + 5 = 6. For his bhagyank (whole-date number), we sum all eight digits: 1 + 5 + 0 + 8 + 1 + 9 + 9 + 0 = 33, then 3 + 3 = 6. Jane's are 4 and 1. Our guide to the mulank, bhagyank and name number works through her sums too. Our free numerology calculator works out both numbers from any birth date. The outcome rests on how well the two sets of numbers get along, which our glossary calls friendly numbers.

Three fields feed the panel. The outcome_name field is the label to print, and reading is the line under it. The outcome field is the code for your own logic. Two more parts need care: each person's birth_date, and both people's numbers. The privacy section explains why.

Show the kundli score and the numbers side by side

One panel, two lines, two labels. Each line names its tradition and the API behind it, so a family never mixes them up. Here is the panel for John and Jane, from our two runs.

Guna milan is the traditional 36-point kundli score, and it reads the two Moons. The numbers match reads two birth dates. Neither one confirms or cancels the other. The kundli line comes from the Astrology API's kundli matching, with the same key.

Do not merge them. A blended "overall match" percent would be your site's own invention. Nobody could trace it to a rule in either API. The numbers outcome holds no points to add, on purpose. Turning Mixed into a number would make one up.

Lead with the line your members ask about most. On a site built around kundli, that is the kundli line. The numbers line sits under it as a second view.

Watch one shared code. Both answers can carry the word difficult. In the numbers answer it is the code behind the label Not a good fit. Print the label on the numbers line, so a family does not read it as an echo of the kundli verdict.

Roles work differently. The kundli match has bride and groom fields, since swapping the two people changes its score. The numbers match has no roles. Either member can go in a.

Never filter or hide matches by numbers

A "number match" filter in search can look like an easy feature. Do not build it. To see why, we ran Jane Doe against 31 partner profiles, born Jan 1 to Jan 31, 1991, one call per pair.

A filter that hides Not a good fit would take 8 people out of Jane's list. A "Good fit only" filter would take out 21. Neither filter reads a profile. It reads a birth day. In this list, the outcome followed the day of the month. The 8 partners born on the 1st, 3rd, 10th, 12th, 19th, 21st, 28th and 30th all got Not a good fit.

A filter costs both sides. A hidden profile is a person Jane never sees, for a reason she never chose. The hidden member gets fewer views and no way to know why. A number match shows a leaning. It does not decide events, and every answer from the API says so. A filter turns a leaning into a wall.

Let the member weigh it. Show the line on the panel, next to the kundli line and the rest of the profile. Do not sort by it or hide by it. Do not send fewer daily picks to a member who often gets Not a good fit.

Words that a family can read calmly

Plan for a parent reading the panel beside the member. Write any text of your own for that reader too.

Print the label and the reading, and nothing harsher. For John and Jane, the API's reading is "Your numbers pull both ways. Some things come easily between you and some need patience." The other three outcomes have short lines in the same even tone. Any text you add around them should match.

Keep the look as even as the words. Give all four labels one color and no icons. The API's words for Not a good fit are calm, and a red badge would undo that.

Do not borrow kundli's words. Kundli matching reports doshas (classical problem patterns) and the exceptions that cancel them. The numbers match names no dosha and offers no remedy. Keep those words off the numbers line.

Show Hindi to Hindi readers. Add lang=hi, and the labels and the reading come back in simple Hindi. Mixed becomes मिला-जुला, and Not a good fit becomes मेल नहीं खाता. The code in outcome stays in English, so your panel logic stays the same. An NRI (non-resident Indian) member in New York may read English while a parent reads Hindi. Each language is a call of its own.

Show the last line too. Each answer has a not_claimed field as well. It tells the family that the numbers show a leaning, not a ruling.

See the whole matrimony setup. Our page on numerology for matrimony platforms sets out the calls a matrimony site makes and the cost of reading one pair.

Keep birth dates and numbers private

A birth date is personal. The numbers match touches it in two places, and your design should guard both.

The answer repeats both birth dates. The a and b blocks each carry birth_date. Make the call on your server, not in the member's browser or phone app. Then pass the browser only what the panel shows: the label and the reading.

The other member's numbers give away part of a birth date. A mulank of 4 means a birth day on the 4th, 13th, 22nd or 31st. Add the bhagyank and a birth year, and the range shrinks fast. Jane's numbers are 4 and 1, and she was born in 1992. We sent the API all 43 dates of 1992 that fall on those four days. Only 8 came back with a bhagyank of 1: Mar 4, 13, 22 and 31, and Dec 4, 13, 22 and 31. A viewer who knows Jane's birth year and sees both numbers is down to 8 possible birthdays.

So the other member sees the outcome, not the numbers. Each member can see their own mulank and bhagyank on their own profile. Show someone else's numbers only if that person chose to show them.

Send birth dates in the request body. The call is a POST, and the dates travel in its body, not in the URL. A URL can show up in server logs. Our API reads the dates only to build its answer. Request bodies are not kept. Our privacy policy has the full terms.

Make the switch the consent. Our terms leave that part with your site: you tell members how their data is used. So next to the "Show number matches" switch, say in one line that the birth date is used for number matches.

What a match list costs in reading credits

One pair is one call to POST /v1/compatibility, and it costs 1 reading credit. One call never covers a whole list. So the cost follows where you put the call.

Jane's test list shows the scale. Her 31 profiles took 31 calls, which comes to 31 credits on a live key. A search page of 20 cards with badges would use 20 credits each time it loads. The panel spends credits only on people a member chose to open.

The kundli line costs its own call on the Astrology API side. Before you go live, a test key answers for John and Jane, the sample pair in our docs.

Build steps, in order

Check the fields before you build. The compatibility feature page sets out what the answer returns for two birth dates, with John and Jane as the example.

The short version

Numerology matching earns its place on a matrimony site as a second line under the kundli score. It needs two birth dates and nothing else, so it reaches members the kundli match cannot. Show it on the profile panel, labelled, when both members turned it on. Keep it out of search and filters. Keep birth dates and other members' numbers off the screen. In Jane's test list, a filter on Not a good fit would have hidden 8 of 31 people for their birth day alone.