How to Add Kundli Matching to a Matrimony Site

To add kundli matching to a matrimony site, you need four things. Ask each member for a birth date, birth time and birth place at sign-up. Run one match call when a member opens a profile or adds it to a shortlist. Show three results on the profile: the score out of 36, the manglik check and a one-word conclusion with its reasons. Give members who do not know their birth time a way to match by birth star instead.

Kundli matching compares two birth charts the traditional way. Its main part is guna milan, a score out of 36 points. Our post on the 36 points of guna milan explains how each point is earned. This post is about the product around the score.

Here is a real result. We sent our API two sample people on Oct 13, 2026. Jane Doe (bride) was born Mar 22, 1992, at 2:45 PM in Chicago. John Doe (groom) was born Aug 15, 1990, at 10:30 AM in New York. They scored 22.5 out of 36. Both are manglik, which tradition reads as a balance. The conclusion was "workable".

The rest of this guide covers each product choice: the form, the timing, the card, the missing birth time and privacy.

What to ask for at sign-up

Matching needs four facts about every member. Each one has a job, and the first three can be missing.

John Doe was born in New York in August 1990, when the clock ran on daylight saving time. The API read that from the time zone name and worked from UTC-4, not UTC-5. Your form should turn the town into a latitude, a longitude and a time zone name like America/New_York. Then the API can do the rest.

Send the bride and the groom in their own fields, and never swap them. With the roles swapped, the same two people scored 24.5 instead of 22.5. Our rulebook lists this as rule KM-02.

Why a guessed birth time is worse than none

Many members do not know their birth time. A form that quietly fills in noon looks helpful, but it gives a member a score that may be wrong. We measured how wrong.

We kept Jane's details fixed and ran John's match at the start of every hour of his birth date. The answer changed twice in one day:

Between 8 AM and 9 AM, his Moon moved into a new nakshatra (birth star). Between 7 PM and 8 PM, it moved into a new sign. A guessed hour gave the true score in 11 of 24 hours. It gave the true conclusion, "workable", in only 8 of 24.

The conclusion can move even when the score stays put. From 5 PM to 7 PM it read "favorable", because one check counts houses from the rising sign, which changes every couple of hours. At 8 PM and 9 PM, John was not even manglik.

So give the form an "I don't know my birth time" choice. Do not fill in a default time.

How to match a member with no birth time

Many members know their birth star and its pada (one of its four quarters) from a family horoscope, even without a birth time. That is enough for the score.

Send those two values to POST /v1/matching/nakshatra. For Jane (Vishakha, pada 4) and John (Mrigashira, pada 1), it returned the same 22.5 out of 36. The score uses only the two Moons, so it does not need a full chart.

Two checks do need full charts: the manglik check and a count of difficult planets in each chart. The answer lists both as "not checked". Its conclusion was "favorable", one step better than the full match, because the check that raised a concern never ran. Show that clearly on the card. A plain line such as "Matched by birth star. Manglik not checked." keeps both families informed.

When to run the match

Each match is one API call for one pair of people. Your screens decide when those calls happen.

The profile page is the natural place. A member opens a profile, and the match runs for that pair. The shortlist is the second place, where a member lines up the profiles they are considering.

Search results are a poor fit. A page of 20 profiles would make 20 calls every time it loads, for matches nobody asked to see. Put a "See match" button on each search card instead. The call runs only when someone taps it.

Run matching only between members who both turned it on. A member who does not follow kundli matching should never see a score they did not ask for.

What to show on the match card

The answer from POST /v1/matching is long. It holds the eight factors, the southern checks, the manglik details and text for each part. A good card shows three things first and keeps the rest one tap away.

Here is a shortened copy of the real answer for Jane Doe (bride, Chicago) and John Doe (groom, New York):

{
  "bride": { "nakshatra": "Vishakha", "moon_sign": "Scorpio" },
  "groom": { "nakshatra": "Mrigashira", "moon_sign": "Taurus" },
  "total": 22.5,
  "total_after_cancellation": 22.5,
  "out_of": 36,
  "mangal": { "matched": true },
  "conclusion": {
    "verdict": "workable",
    "headline": "This match can work. The main checks pass, with 22.5 out of 36 points. But a few things need a closer look before you decide. They are listed below.",
    "concerns": [{ "check": "papa" }],
    "strengths": [
      { "check": "score_ok" },
      { "check": "nadi_clear" },
      { "check": "bhakoot_clear" },
      { "check": "mangal_matched" }
    ]
  }
}

Start with the score. Show total_after_cancellation, the score after the standard classical exceptions. The raw total comes back too, for families whose astrologer does not accept an exception.

Next comes one line from mangal. Manglik is about where Mars sits in each chart. When both people are manglik, or neither is, tradition sees no problem. Our post on the manglik check covers the details.

Then add the conclusion: the word in verdict, with the headline under it. Then list the strengths and the concerns, each with its text. The word follows a stated rule, KM-14 in our rulebook, so you can tell a member exactly why a match got its word.

Avoid a big score alone. Two pairs with the same total can have lost points in very different places. The strengths and concerns show where.

Use the API's words, in your members' language

A member reads this text about a person they may marry. The API writes it in plain, calm words. For Jane and John, it named one concern and four strengths. Its next steps said to show the points to an astrologer and to decide after that talk.

Add lang=hi to the same call for Hindi. The field names stay in English, so your code does not change. For Jane and John, the conclusion stayed "workable". The Hindi headline began "यह रिश्ता चल सकता है।"

Try it with two real births. Our free kundli matching tool runs on this same call. Enter any two births to see the score, the manglik line and the conclusion your card would show.

Keep birth details private

Birth time and place are personal details. Your design can use them for matching without ever showing them to other members.

Keep birth time and birth place off the public profile, and show only the match result to the other member. Let members change or remove their birth details at any time. Ask for consent at sign-up in one plain sentence, such as "Use my birth details for kundli matching."

Send birth details in the body of a POST request, never in the web address. Web addresses can appear in server logs.

On our side, the API uses birth details only to work out the answer, and request bodies are not stored. Our privacy policy has the full terms.

A build checklist

See every field. The kundli matching feature page lists what each answer holds. The matching reference shows every request and response field. Our page for matrimony sites has more steps for after a match is accepted.

The short version

Ask for date, time and place, and let members say they do not know the time. Run the match when someone opens a profile or shortlists it. Lead with the conclusion and its reasons, not the bare score. Match members with no birth time by birth star, and say so on the card.

On John Doe's birth date, a guessed hour gave three different scores and the right conclusion in only 8 of 24 hours. An "I don't know" choice and a birth-star match avoid that guess.