Numerology Compatibility API

One request, two people

curl -X POST https://simplenumerologyapi.com/v1/compatibility \
  -H 'X-API-Key: nk_…' \
  -H 'content-type: application/json' \
  -d '{"a":{"first_name":"María","last_name":"García López","birthdate":"1990-03-12"},
       "b":{"first_name":"Luis","last_name":"Ortega","birthdate":"1988-07-04"}}'

{
  "object": "compatibility",
  "score": 73,
  "rating": "good",
  "method": "families-polarity-v1",
  "numbers": {
    "life_path_number":   {"a": 7, "b": 1, "relationship": "natural", "score": 90},
    "destiny_number":     {"a": 5, "b": 1, "relationship": "natural", "score": 90},
    "soul_urge_number":   {"a": 4, "b": 6, "relationship": "neutral", "score": 60},
    "personality_number": {"a": 1, "b": 22, "relationship": "challenging", "score": 35},
    "birth_day_number":   {"a": 3, "b": 4, "relationship": "challenging", "score": 35}
  },
  "conventions": {"y_rule": "consonant", "name_reduction": "whole_name", "transliteration": "none"}
}

Reading the result

• score is 0–100, weighted across the five core numbers.
• rating buckets the score into strong, good, mixed or challenging, so you can pick copy without choosing thresholds yourself.
• numbers shows each pairing: both people’s numbers, their relationship (same, natural, neutral or challenging) and that pair’s score. This is what makes a result screen worth reading: “your life paths are a natural match, your personalities pull in different directions”.
• method names the scoring method. If it ever changes, it gets a new name, so stored scores stay comparable.

The same input always gives the same score, so you can cache results for every pair of users.

Built for matching at scale

Each compatibility check counts as one request. A dating app that scores a new user against a feed of candidates can stay inside the Starter plan’s 10,000 requests a month for a long time, and enable overage on paid plans so the feed never stops at the quota. See pricing.

Frequently asked questions

How is numerology compatibility calculated?

Each person’s life path, destiny, soul urge, personality and birthday numbers are compared pair by pair. Numbers from the same family are a natural match, and the five pair scores are weighted into one overall score.

Can I use the compatibility API in a dating app?

Yes. It is a plain JSON API, the free plan includes 100 checks a month, and names and birthdates are never stored, which keeps your users’ data out of a third party’s database.

Do both people need a full name?

Yes. Each person needs a first name, a last name and a birthdate, because three of the five compared numbers come from the name. The middle name is optional.

Is compatibility included in the free plan?

Yes. Every endpoint is available on every plan, including the free one.