Back to Blog

How to Use the Human Design API in Zapier: A Step-by-Step Zap Recipe

No native Human Design app needed. Use Webhooks by Zapier as the trigger and a Custom Request action with a Bearer token to call the /v2/charts/coordinates endpoint from any Zap.

Posted by

What you'll build

Using Webhooks by Zapier as a trigger and an HTTP by Zapier Custom Request action with a Bearer token, you can call humandesignapi.nl's POST /v2/charts/coordinates endpoint from any Zap. This guide gives you the exact field-by-field setup, including the auth header trap that catches most first-timers.


The finished Zap looks like this: Webhooks trigger → HTTP Nominatim geocode → HTTP Custom Request to the HD API → Formatter JSON Parse → Email + Notion. Each step passes data to the next through Zapier's visual mapping interface, so there is no JavaScript to write.


Zapier has no first-party Human Design integration. Bodygraph.com offers a native Zapier app, but it bundles composite charts, coaching content, and features you may not need, at quote-based pricing. If you only need raw chart data wired into your own tools, the custom Zap approach in this guide gives you full control: transparent per-credit billing, no bundled extras, and a plain REST API you can call from anywhere. For a side-by-side comparison of all options, see Human Design API Comparison.

Prerequisites

You need three things before starting:

  • A Zapier account on the Starter plan or above. Multi-step Zaps require a paid plan. The free tier only supports single-step Zaps and will not work for this setup.
  • A humandesignapi.nl API key. The Developer plan at €35/month gives you 10,000 credits and unlocks POST /v2/charts/coordinates. Grab a key after signing up in the dashboard.
  • A trigger source. This guide uses Webhooks by Zapier directly. If your users submit birth data via a form, you can swap the webhook for a Tally, Typeform, or Google Forms trigger and skip the test payload step.

The quickstart guide and the authentication reference cover token setup and the full request shape in detail.

Step 1: Choose your trigger

Webhooks by Zapier (catch hook)

In Zapier, click Create Zap. Search for Webhooks by Zapier and choose the Catch Hook event. Zapier generates a unique webhook URL for this Zap. Copy it.


Send a test payload to that URL so Zapier can learn the structure of your data. Use curl or any HTTP client:

curl -X POST "https://hooks.zapier.com/hooks/catch/YOUR_ZAP_ID/" \
  -H "Content-Type: application/json" \
  -d '{
    "birthdate": "1990-06-15",
    "birthtime": "12:30",
    "location": "Amsterdam, Netherlands"
  }'

After Zapier receives the payload, click Test Trigger. Zapier will show the parsed fields so you can map birthdate, birthtime, and location in later steps.


Alternative triggers

If your users fill out a birth-data form, you can replace the webhook trigger with a native form integration. Tally and Typeform both have Zapier apps that expose each form field as a mapped token. Google Forms requires a Google Sheets intermediary step but works equally well. The remaining steps are identical regardless of which trigger you use.

Step 1b: Geocode the birth city to coordinates

Most birth-data forms collect a city or country name, not raw coordinates. This step converts a location string to latitude and longitude using OpenStreetMap Nominatim, a free geocoding API with no API key required. Add an HTTP by Zapier action step and choose the GET method.


Nominatim action settings

Set URL to:

https://nominatim.openstreetmap.org/search

Under Query String Parameters, add three entries:

q       = [location field from trigger step]
format  = json
limit   = 1

Under Headers, add one header to identify your app. Nominatim requires this to prevent anonymous bulk abuse:

User-Agent: YourAppName/1.0 (your@email.com)

Enable Unflatten (or the equivalent response-parsing toggle in your Zapier account's HTTP action UI). Nominatim returns a JSON array; because we passed limit=1, there will be exactly one result. Zapier exposes the first result's lat and lon as individually mappable fields once parsing is enabled.


Rate limit note: the public Nominatim instance caps usage at 1 request per second. A single Zap run stays well within that. If you later build a batch Zap that processes many records at once, add a Delay by Zapier step with at least a 1-second pause between iterations.


If your form already collects latitude and longitude directly, skip this step entirely and map those fields in Step 2.

Step 2: Add a Custom Request action

This is where the Human Design API call happens. Add another HTTP by Zapier action and choose Custom Request.


Method and URL

Set Method to POST and URL to:

https://api.humandesignapi.nl/v2/charts/coordinates

The auth header (the gotcha)

Under Headers, add one entry. This is where most first-timers get stuck:

Key:   Authorization
Value: Bearer YOUR_API_KEY

The entire value field must contain Bearer YOUR_API_KEY as a single string. Do not enter Bearer and the key in separate rows, and do not omit the Bearer prefix. Either mistake produces a 401 API_KEY_MISSING or API_KEY_INVALID error.


Replace YOUR_API_KEY with the key from your dashboard. Zapier stores this value in the action configuration, not in the webhook log, so it is never visible to people who can view your Zap history.


Request body

Set Body Type to JSON. In the Data field, enter the JSON object and map values from prior steps using Zapier's variable picker:

{
  "birthdate": "[birthdate from trigger]",
  "birthtime": "[birthtime from trigger]",
  "lat": [lat from Nominatim step],
  "lng": [lon from Nominatim step]
}

Note that lat and lng must be numbers, not strings. If your trigger passes them as strings (Nominatim returns them as strings), wrap them in a Formatter Numbers step before this action to ensure correct JSON types.


For the full request reference including all accepted fields, see the coordinates endpoint guide.

Step 3: Parse the response

Zapier's HTTP action sometimes returns the response body as a raw JSON string rather than parsed fields, depending on your account settings. If the output of the Custom Request step shows a single Body token rather than individual data.type, data.profile, and so on, add a Formatter step.


Add a Formatter by Zapier action. Choose Utilities as the event, then JSON Parse as the transform. Map the Body output from the HTTP action as the input. Zapier will parse the JSON and expose every field as a separate token: Data Type, Data Profile, Data Strategy, and so on.


If your HTTP action already returns parsed fields directly, skip this step.

Step 4: Send results downstream

With the chart data parsed and mapped, add your output steps.


Email by Zapier

Add an Email by Zapier action (or Gmail, if you prefer). Map chart fields into a simple template:

Subject: Human Design chart for [birthdate]

Type: [data.type]
Profile: [data.profile]
Strategy: [data.strategy]
Authority: [data.authority]
Definition: [data.definition]
Incarnation Cross: [data.incarnationCross]

This is enough for a coaching funnel email. For a deeper look at what every field means, see How to Read a Human Design Chart Programmatically.


Notion: Create Database Item

Add a Notion action and choose Create Database Item. Connect your Notion account and select the database where chart records should go. Map the following fields to database columns (create the columns in Notion first if they do not exist):

  • Name or title column → [birthdate]
  • type → [data.type]
  • profile → [data.profile]
  • centers → [data.centers] (Zapier will serialize the array as a comma-separated string)
  • channels → [data.channelsShort]
  • incarnationCross → [data.incarnationCross]

Chart data for a given birth input is deterministic: the same date, time, and location always produce the same chart. This means you can check your Notion database on repeat submissions and skip the API call if a matching record already exists, which saves credits.

Step 5: Test and turn on the Zap

Click Test Step on each action in sequence. The Custom Request step output should show Success True and a Data object with all chart fields populated. Response time is sub-500ms globally.


Here is an abbreviated real response for the test input above:

{
  "success": true,
  "message": "Chart generated from coordinates",
  "errorCode": "",
  "type": "ChartResult",
  "data": {
    "type": "Generator",
    "profile": "4/6",
    "strategy": "To Respond",
    "authority": "Sacral",
    "definition": "Split",
    "centers": ["Sacral", "Spleen"],
    "channelsShort": ["34-57", "10-20"],
    "incarnationCross": "Right Angle Cross of Planning (37/40 | 9/16)",
    "signature": "Satisfaction",
    "notSelfTheme": "Frustration"
  }
}

Once every step passes its test, click Publish Zap and flip it to On. Zapier will run the full sequence every time a payload arrives at the webhook URL.

Handling errors and rate limits

The rate limit is 100 requests per minute per API key. A single Zap run will never hit this organically. If you build a bulk Zap that processes many records in one run, add a Delay by Zapier step with a 1-second pause between iterations to stay well within the limit.


The most common error codes and what to do about them:

  • API_KEY_MISSING or API_KEY_INVALID — check that the Authorization header value starts with Bearer (with a space) followed by your key.
  • INVALID_LATITUDE or INVALID_LONGITUDE — the geocoding step returned a non-numeric value. Add a Formatter Numbers step to coerce the Nominatim lat and lon fields to numbers before the API call.
  • RATE_LIMIT_EXCEEDED — add a Delay step; if this happens on a single Zap, your account may have multiple Zaps sharing the same API key.
  • CREDITS_EXHAUSTED — no credits remaining this month. Upgrade your plan or wait for the monthly reset.

Full error code reference: error handling guide. Rate limiting details: rate limiting guide.

Cost comparison

Running this Zap requires two subscriptions: Zapier (Starter plan, ~$20/month) and humandesignapi.nl (Developer plan, €35/month for 10,000 credits). At 10,000 charts per month the API cost works out to €0.0035 per chart.


Bodygraph.com offers a native Zapier app, which is convenient if you are already a Bodygraph customer. The trade-off is that you are locked into their pricing tier rather than paying per call. humandesignapi.nl gives you transparent per-credit billing with no per-feature add-ons, which works out cheaper at moderate to high volume.


For the full plan breakdown, see humandesignapi.nl/pricing. The plans and credits guide covers overage behavior and what happens when you exceed your monthly allocation.

Next steps

Once your Zap is running, a few directions are worth exploring:

FAQ

Does Zapier have a native Human Design app?

Not a first-party one. Zapier has no official Human Design app. Bodygraph.com does offer a native Zapier integration, but it comes bundled with composite charts, coaching content, and other features at quote-based pricing. If you only need chart data piped into your own tools, humandesignapi.nl gives you the same underlying data at transparent per-credit rates, using the built-in HTTP by Zapier Custom Request action. This guide walks through the exact setup. For a full comparison, see our API comparison post.


What is the auth header gotcha everyone mentions?

In Zapier's Custom Request action, the Authorization header value must contain the full Bearer prefix in a single field. The correct entry is key Authorization, value Bearer YOUR_API_KEY. If you split the word Bearer into one row and the key into another, or if you omit the prefix entirely, the API returns a 401 with error code API_KEY_MISSING or API_KEY_INVALID.


Do I need a geocoding API key?

No. The POST /v2/charts/coordinates endpoint accepts latitude and longitude directly and resolves the timezone from coordinates automatically. For converting a city name to coordinates, this guide uses Nominatim, a free geocoding API that requires no API key. If your form already collects coordinates, the geocoding step is optional.


What happens when I run out of credits?

The API returns HTTP 402 with error code CREDITS_EXHAUSTED and success: false. Your Zap will fail at the Custom Request step. Credits reset monthly on your billing date. To avoid interruptions, upgrade to the Scale plan (€47.50/month for 50,000 credits) or monitor usage in the dashboard. See the plans and credits guide for overage details.

Ready to connect?

Generate your API key in the dashboard and copy it into the Zap header. You are 5 minutes from your first automated chart. Open dashboard →


Or compare plans first: See pricing →


For authentication setup and the full endpoint reference:


Background on the system: Human Design System (Wikipedia). Zapier Webhooks reference: Webhooks by Zapier. Zapier Custom Request reference: API Request actions in Zapier.