Humanform REST API

Five worked scenarios cover chair design, handheld products, desk ergonomics, automotive seating, and wearables/PPE. Each example lists verified measurement names from the 148-measurement dataset, explains percentile-range thinking (5th percentile female through 95th percentile male), and includes a live POST /v1/predict request and response.

Country-adjusted predictions are illustrated on the wearables example (US vs UK head girth). Browse all supported codes on the countries page, or install the MCP server, CLI, Google Sheets, Excel, or browse planned CAD plugins to run predictions from your design tools.

View all design examples

Send your API key in the Authorization header:

Authorization: Bearer hf_live_...

Missing, malformed, or revoked keys return 401 with Invalid API key or a missing header message.

Predict a single anthropometric measurement. Responses are country-adjusted when country is not US. Values are validated against empirical bounds before the response is returned and credits are deducted.

Request body

Response body

{
  "measurement": "AbdominalDepth",
  "gender": "Female",
  "country": "US",
  "value": 244.7,
  "unit": "mm"
}

Verified country-adjusted examples

These AbdominalDepth predictions use the same inputs with different countries and output units. Values were verified on production preview deployments.

POST https://api.humanform.app/v1/predict
Authorization: Bearer hf_live_...
Content-Type: application/json

{
  "measurement": "AbdominalDepth",
  "gender": "Female",
  "age": 34,
  "percentile": 50,
  "country": "US",
  "unit": "mm"
}

{
  "measurement": "AbdominalDepth",
  "gender": "Female",
  "country": "US",
  "value": 244.7,
  "unit": "mm"
}

{
  "measurement": "AbdominalDepth",
  "gender": "Female",
  "age": 34,
  "percentile": 50,
  "country": "UK",
  "unit": "mm"
}

{
  "measurement": "AbdominalDepth",
  "gender": "Female",
  "country": "UK",
  "value": 253.8,
  "unit": "mm"
}

// unit: "cm"  → 24.5 cm
// unit: "in"  → 9.63 in

// UK mm value converted:
// unit: "cm"  → 25.4 cm
// unit: "in"  → 9.99 in

UK responses are country-adjusted relative to US for the same inputs. cm and in values are rounded per unit rules (1 decimal for mm/cm, 2 for in).

Reverse lookup: given a measured body dimension, return the population percentile it corresponds to for the same measurement, gender, age, and country. One credit per successful lookup. Values below the 1st or above the 99th percentile envelope return a clear 422 error instead of an extrapolated percentile.

POST https://api.humanform.app/v1/percentile-lookup
Authorization: Bearer hf_live_...
Content-Type: application/json

{
  "measurement": "PoplitealHeight",
  "gender": "Female",
  "age": 34,
  "country": "US",
  "unit": "cm",
  "value": 43.1
}

{
  "measurement": "PoplitealHeight",
  "gender": "Female",
  "country": "US",
  "value": 43.1,
  "unit": "cm",
  "percentile": 52.3
}

{
  "error": "value_below_percentile_range",
  "message": "The provided value is below the 1st percentile for this measurement, gender, age, and country.",
  "measurement": "PoplitealHeight",
  "value": 43.1,
  "unit": "cm"
}

Public endpoint listing supported country codes, labels, and regions. No authentication required.

{
  "countries": [
    { "code": "US", "label": "United States", "region": "North America" },
    { "code": "UK", "label": "United Kingdom", "region": "Europe" }
  ]
}

Public operational stats for the dataset. No authentication required.

{
  "measurements": 148,
  "unit": "mm",
  "status": "operational"
}

The MCP server, CLI, and Google Sheets custom function and Excel custom function are available today. Planned CAD and DCC plugins (Rhino/Grasshopper, Fusion 360, Blender, SketchUp, Onshape) will follow the same pattern: enter your API key inside the tool, request predictions without raw HTTP.

Those plugins are not scheduled yet. See the plugins page for what is available now and what is planned.

Prefer your AI assistant over raw HTTP? Install the @humanform/mcp MCP server in Claude Desktop, Cursor, Claude Code, or any stdio MCP client. It wraps the same endpoints documented here with three tools: predict_measurement, percentile_lookup, list_measurements, and list_countries.

Browse the full measurement and country lists, or see the dedicated MCP install page for registry links and client setup.

{
  "mcpServers": {
    "humanform": {
      "command": "npx",
      "args": ["-y", "@humanform/mcp"],
      "env": { "HUMANFORM_API_KEY": "hf_live_..." }
    }
  }
}

Prefer your terminal over raw HTTP? Install the @humanform/cli CLI for predictions, percentile ranges, country comparisons, measurement search, and reverse percentile lookup. Commands mirror the REST endpoints documented here: predict, range, compare, measurements search, and percentile-lookup.

Run humanform login once to store your API key locally, or set HUMANFORM_API_KEY for CI. Add --json for machine-readable output. See the dedicated CLI install page for full examples and use cases.

humanform login

humanform predict \
  --measurement Stature \
  --gender Female \
  --age 34 \
  --percentile 50 \
  --country US \
  --unit cm

HUMANFORM_API_KEY="hf_live_..." humanform predict \
  --measurement Stature \
  --gender Male \
  --age 30 \
  --percentile 50 \
  --country US \
  --unit cm \
  --json

Prefer spreadsheets over raw HTTP? Copy the Apps Script from the Google Sheets install page into your workbook (Extensions → Apps Script). Set your API key from the Humanform menu, then use =HUMANFORM(measurement, gender, age, percentile, country, unit) in cells. Each distinct input combination calls POST /v1/predict with the same request body documented above.

The install page covers credit usage, caching, and when to paste results as values. Same credits and free tier as the REST API.

Prefer Excel over raw HTTP? Download the add-in manifest from the Excel install page and sideload it (Insert → Add-ins → Upload My Add-in). Save your API key in the Humanform task pane, then use =HUMANFORM.HUMANFORM(measurement, gender, age, percentile, country, unit) in cells. Excel requires the namespace prefix: use HUMANFORM.HUMANFORM, not bare HUMANFORM. Each distinct input combination calls POST /v1/predict with the same request body documented above.

The install page covers credit usage, caching, and when to paste results as values. Same credits and free tier as the REST API.

Error bodies include an error code and a human-readable message. Validation failures may include a details object with field errors.

{
  "error": "insufficient_credits",
  "message": "Account does not have enough credits for this request."
}

{
  "error": "prediction_out_of_bounds",
  "message": "Prediction result is outside plausible bounds for this measurement.",
  "measurement": "Stature",
  "valueMm": 3200,
  "bounds": { "minMm": 400, "maxMm": 2200 }
}