Can predictions help balance search results?

No. Search ranking and visibility affect sellers’ income, so predictions should not be used there. Keep them in aggregate reporting that informs community programs.

What if one batch item fails?

The batch still returns 200 with an error object on that item. Items that succeeded are complete, so never resend the whole batch. Retry only the failed items.

Can we include shop names or handles?

You can send usernames, but many shop names contain no personal name and will return unknown. Results are usually more meaningful when you use the owner’s first name.

Gender prediction · Marketplaces

Aggregate gender analytics for marketplace communities

Marketplace community teams often ask whether their seller base is broad and whether outreach programs reach new groups. The Finowl gender API estimates how shop owners’ first names are typically used, so analysts can produce aggregate reports on seller cohorts and buyer segments without asking every user an extra onboarding question.

The line on a two-sided platform is clear: predictions must not influence search ranking, listing visibility, fees, payouts, dispute outcomes or who can buy and sell. They belong in aggregate dashboards that inform programs and outreach, with unknown results shown openly and with people free to describe themselves in their own profiles.

Try it in the sandbox About gender

USE CASES

Where it fits in marketplaces

Seller program reach
Estimate the aggregate composition of sellers who join an accelerator or mentoring program and compare it with the overall seller base to see where outreach might be widened.
Category community reports
Summarize estimated seller and buyer mixes by category each quarter for internal community reports, with confidence thresholds applied and unknown results reported as a separate group.
Historical cohort backfills
Use the batch endpoint to process past seller cohorts in groups of up to 50 names, building a trend line of community composition without contacting sellers again.
Marketing creative checks
Compare the estimated audience reached by seller recruitment campaigns with your goals, informing creative and channel choices rather than targeting, ranking or excluding any individual seller or buyer.

HOW TO INTEGRATE

The workflow

1
Pull seller first names and shop country codes from your analytics warehouse into an enrichment job.
2
Send groups of up to 50 items to POST /v1/gender/batch with unique ids that map back to analytics rows.
3
Check each item for an error object, since a 200 response can contain item-level failures, and retry only those items.
4
Aggregate identified results above your confidence threshold and keep unknowns as a visible category.
5
Keep the derived field out of ranking, payments and moderation systems entirely.

POST /v1/gender/batch

curl https://api.finowl.co/v1/gender/batch \
  -H "Authorization: Bearer $FINOWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "id": "seller-1042",
      "type": "name",
      "value": "Jean",
      "country": "FR"
    },
    {
      "id": "seller-1043",
      "type": "name",
      "value": "Jean",
      "country": "US"
    },
    {
      "id": "seller-1044",
      "type": "email",
      "value": "handmade.by.lucia@example.com"
    }
  ]
}'

Each item costs 1 credit in the default dataset-only batch mode. Jean leans differently in France and the US, so pass the shop country.

GOOD PRACTICE

Before you ship

Never let predictions affect ranking, fees, payouts, moderation or eligibility to trade. On a marketplace those decisions have direct financial effects on people.
Seller names are personal data. Mention gender inference in your privacy notice, restrict access to the derived data and keep it in analytics storage only.
Do not display predicted gender on shop pages or profiles. If sellers want to share identity information, offer optional, self-described profile fields they control.

Read the API reference for every field and error code. Each lookup costs 1 credit (3 when it requests AI); see pricing.

A FEW GOOD QUESTIONS

Common questions