The simplest numerology REST JSON API

The whole integration

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

{
  "life_path_number": 7,
  "destiny_number": 11,
  "soul_urge_number": 33,
  "personality_number": 5,
  "karmic_debt_numbers": [],
  "…": "47 fields in all"
}

That is it: a POST, an API key in the X-API-Key header, and a JSON body. Only first_name, last_name and birthdate are required. middle_name and options are optional.

Why it stays simple

• Plain REST and JSON. Four endpoints, all POST with a JSON body: /v1/charts/pythagorean, /v1/charts/batch, /v1/cycles and /v1/compatibility.
• One header to authenticate. No OAuth flow, no token refresh and no request signing.
• Flat, predictable fields. Each number is a named field such as life_path_number, so you read it directly with no parsing.
• The same input gives the same output. The calculation is deterministic and its conventions are documented, so you can cache results forever.
• No SDK required. Use fetch, requests, curl or anything else. If you want types, generate a client from the OpenAPI 3.1 spec or import the Postman collection.

Errors you can read

Every error has the same shape, with a stable code you can branch on and a link to its documentation:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "first_name: first_name must contain at least one letter",
    "param": "first_name",
    "doc_url": "https://simplenumerologyapi.com/docs#error-parameter_invalid",
    "request_id": "3f9a2c41d0e84b7a9c6e15f2b8d0a7e4"
  }
}

Status codes mean what they say: 401 for a bad key, 402 when the quota runs out, 422 for invalid input and 429 with Retry-After when you go too fast.

In your language

const response = await fetch("https://simplenumerologyapi.com/v1/charts/pythagorean", {
  method: "POST",
  headers: { "X-API-Key": process.env.NUMEROLOGY_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({ first_name: "María", last_name: "García López", birthdate: "1990-03-12" }),
});
const chart = await response.json();
console.log(chart.life_path_number); // 7

import os
import requests

chart = requests.post(
    "https://simplenumerologyapi.com/v1/charts/pythagorean",
    headers={"X-API-Key": os.environ["NUMEROLOGY_API_KEY"]},
    json={"first_name": "María", "last_name": "García López", "birthdate": "1990-03-12"},
    timeout=10,
).json()
print(chart["life_path_number"])  # 7

There are full quickstarts for Python, JavaScript and PHP.

Frequently asked questions

Is this a REST API?

Yes. It is a JSON REST API over HTTPS. Every endpoint takes a JSON body and returns JSON, described by an OpenAPI 3.1 spec.

Do I need an SDK?

No. Any HTTP client works. Official Python and JavaScript SDKs exist if you prefer them, and you can generate a client for any language from the spec.

What is the minimum request?

A first name, a last name and a birthdate in YYYY-MM-DD format, sent as JSON with your API key in the X-API-Key header.

How do I get an API key?

Sign up with GitHub, Google, or your email and a password, then create a key on the account page. The free plan includes 100 requests a month and needs no card.

Does the API return XML?

No. Requests and responses are JSON only.