Profile Scoring API

What it does

You upload a CSV of de-identified demographic combinations (the nine columns below). Each row comes back tagged with its matching profile from the Verosynthea 8-profile typology and a confidence flag, delivered as a scored CSV you download, with a JSON summary in the response. The model is the same one behind the Profiling product, but here you submit your own combinations instead of selecting a geography.

Common uses: segmentation, persona inference, market sizing, and population diversity audits, for any demographic data (not only customers). The endpoint never stores your data past the single request: the upload is scored, written to a temporary download, and discarded.

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get a key from your account dashboard after signing in. Keys are per-account; treat them like passwords. Full auth details: /docs/api/authentication.

Endpoint

POST https://au-1649c624b9314bc69db4c92e74cddbf1.ecs.ap-southeast-2.on.aws/api/score

Request: multipart/form-data

Upload a CSV as the file field. Each row is one combination: one value per column from the nine columns below. Include any of your own columns (an id or label, say); they are preserved verbatim in the scored output so you can join the results back. No unique identifier is required.

Example CSV

id,age_group,sex,marital_status,household_role,income,education,occupation,industry,labour_force
CUST_1,Early career,Female,Partnered,Family head,High,Bachelor or higher,Managers and professionals,Knowledge services,Full-time employed
CUST_2,Senior,Male,Single,Non-family,Low,Year 11 or below,Not in employment,Other / Not employed,Not in labour force

Response body (JSON)

{
  "status": "complete",
  "credits_charged": 1,
  "rows_scored": 2,
  "rows_failed": 0,
  "download_url": "https://<bucket>.s3.<region>.amazonaws.com/scoring/results/<job_id>.csv?...",
  "download_expires_at": "2026-05-26T10:30:00Z",
  "data_quality": {
    "rows_with_invalid_values": 0,
    "invalid_value_details": []
  },
  "profile_summary": {
    "profiles_assigned": {
      "5": { "name": "Established partnered households", "count": 1 },
      "0": { "name": "Labourers and operators", "count": 1 }
    },
    "low_confidence_count": 0,
    "low_confidence_pct": 0.0
  },
  "job_id": "..."
}

The download_url is a temporary (24 h) link to the scored CSV: your original rows plus a profile_name and profile_confidence column. Full field reference + error response shapes: /docs/api/data-format, /docs/api/error-codes.

Python

import os
import requests

API_KEY = os.environ["VEROSYNTHEA_API_KEY"]  # ask_live_...
API_BASE = "https://au-1649c624b9314bc69db4c92e74cddbf1.ecs.ap-southeast-2.on.aws"

# Upload your CSV of de-identified combinations.
with open("combinations.csv", "rb") as f:
    resp = requests.post(
        f"{API_BASE}/api/score",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": ("combinations.csv", f, "text/csv")},
        # data={"webhook_url": "https://you.example.com/hook"},  # optional
        timeout=120,
    )
resp.raise_for_status()
out = resp.json()

print(out["rows_scored"], "rows,", out["credits_charged"], "credits")

# Download the scored CSV (original rows + profile_name + profile_confidence).
scored = requests.get(out["download_url"], timeout=120)
scored.raise_for_status()
with open("scored.csv", "wb") as f:
    f.write(scored.content)

Longer Python example with retries and the async path for large files: /docs/api/examples/python.

curl

curl https://au-1649c624b9314bc69db4c92e74cddbf1.ecs.ap-southeast-2.on.aws/api/score \
  -H "Authorization: Bearer $VEROSYNTHEA_API_KEY" \
  -F "file=@combinations.csv;type=text/csv"
  # optional: -F "webhook_url=https://you.example.com/hook"

# The response JSON includes download_url; fetch the scored CSV:
# curl -o scored.csv "<download_url from the response>"

Required columns

Each combination is one value from each of the nine columns below. Send the friendly bucket names, or the raw ABS category labels, and we map them for you. Extra fields are silently dropped (never used for scoring). Missing required fields return a 400 with an explicit list of what was missing per input index.

You may also add an optional label column, any text you choose, echoed back on each result so you can merge scores to your own data. No unique identifier is required.

Buckets group standard categories from the ABS Census 2021 dictionary (variable codes shown above). Full canonical value list per field: /docs/api/variable-reference.

Pricing

1 credit per 100 combinations scored. Fractional: a request of 250 combinations costs 2.5 credits. Credits are deducted on successful response only; 4xx and 5xx error responses do not deduct.

Buy credits: /pricing. Credit bundles include commercial use rights.

Rate limits

• 60 requests per minute per API key
• Up to 100 MB / 1,000,000 rows per file
• Files of 10,000 rows or fewer are scored synchronously (one response with the download_url); larger files return 202 and are processed asynchronously
• Soft cap of 50 concurrent in-flight requests per account

Exceeding the rate limit returns a 429 with Retry-After in the header.

Going deeper

This page covers the surface most callers need. For specific reference material, jump directly:

• Getting started — your first scored request, end to end
• Authentication — API keys, rotation, scoping
• Data format — request + response shapes in full
• Variable reference — canonical value lists per ABS code
• Error codes — 400 / 401 / 402 / 429 / 5xx shapes
• FAQ — edge cases, performance tuning