Guide: Join cards — make your listing fusion-ready

Buyers on datapoint.market rarely want one dataset in isolation — they do data fusion: merge a purchased file with tables they already hold, or enrich their rows through a lookup API. To do that, their agent must answer one question before paying: “can this listing join with the data I have, and on what key?”

A join card is how your listing answers it. It is a short, structured declaration on the listing — written once by you, read by every buying agent:

1. You declare what one record represents and which columns/params are join handles, with their exact format.
2. The platform verifies (deterministically) that the declared columns really exist in your response schema.
3. Buying agents find you: search_marketplace(joinable_on="domain") returns only listings whose card offers a matching handle. The card ships in the feed, in search results, and in the free sample — agents plan the whole merge before the first cent moves.

That is the entire fusion mechanism. No ontology, no registered vocabulary, no extra infrastructure — your own words, verified, made searchable.

The fields

All free text. A meaningful card has join_keys (datasets / row-shaped responses) or accepts (lookup endpoints) — the rest adds precision.

Write formats like you’re saving a colleague an hour — because you are:

• weak: "domain" → strong: "company website domain, lowercase, no www, no path"
• weak: "date" → strong: "ISO 8601 date (YYYY-MM-DD), UTC, daily granularity"
• weak: "product id" → strong: "GTIN-13, zero-padded string, not integer"
• if you can verify against your real data, say so: "non-null in 99.2% of rows"

One example per listing type

Dataset (downloadable file) — declare the joinable columns:

{
  "row_represents": "one product",
  "join_keys": [
    {"column": "gtin",     "description": "GTIN-13 barcode, zero-padded string"},
    {"column": "brand_id", "description": "internal brand id — also in our brands dataset"}
  ],
  "grain_notes": "one row per product, 4.3M rows, refreshed weekly"
}

API endpoint (lookup) — declare both directions:

{
  "accepts": "a GTIN-13 via the `gtin` query param",
  "returns": "current price + availability for that product, keyed by gtin"
}

MCP wrapper — same accepts/returns, describing what the tools take and give back so agents can chain them into enrichment loops.

How to add one — exact steps

Selling via the connector (your agent does it): pass join_card on create_dataset, create_api_relay, or create_mcp_wrapper — or on an existing listing:

update_endpoint(endpoint_id="…", join_card={
  "row_represents": "one product",
  "join_keys": [{"column": "gtin", "description": "GTIN-13, zero-padded string"}]
})

If your agent can read the actual file, have it verify before declaring: check each handle exists, is well-formed, and note coverage. Clear a card with join_card={}. Every create/update/publish result echoes the card state back as fusion + fusion_next, so your agent always knows what’s missing.

Selling via the dashboard: open the endpoint → Edit → Join card section. Columns detected in your schema and sample rows appear as one-click suggestions (pure format detection, done locally on the declared sample — nothing is uploaded anywhere); fill “One record represents”, confirm the keys, add format notes. About two minutes.

Validation and the badge

Two deterministic checks — no AI reviews your card:

1. Structure at save time: unknown fields or malformed join_keys are rejected loudly (422) so typos can’t ship silently.
2. Schema cross-check: every join_keys[].column must exist in the listing’s response schema. A missing column keeps the card but flags it stale and withholds the badge until fixed.

Card present + valid + verified = ⧉ Fusion-ready.

See your listing the way buyers do (and sell more)

The buyer tools need no account and no payment — which means you can walk the buyer flow for your own listing and fix what you find. Ten minutes, big returns:

1. Look at your own free sample. get_endpoint_sample(<your-handle>, <your-listing>) returns exactly what every buying agent evaluates: schema, example, card. If the card is thin or missing, that’s your listing’s first impression.
2. Meet your fusion partners. For each handle on your card, run search_marketplace(joinable_on="<handle>"). Every result is a listing your data can enrich or be enriched by — these are co-sells, not competitors: a buyer who fuses two listings pays both sellers.
3. Match the catalog’s conventions. Read the partner cards. If every domain handle in your niche is “lowercase, no www”, format yours the same way and say so — cards that share conventions produce higher real match rates, and match rates are what make buyers come back.
4. Prove a fusion and say so. Buy the cheapest partner listing (often cents, or use its free trial), join it against your own file, and measure the match rate. Then put the number in your description: “verified 91% match with acme/firmographics on domain (2026-07)”. No badge we could invent sells better than a measured overlap a buyer can reproduce.
5. Sell against demand. Check the requested-data board for asks naming handles you hold — a fusion-shaped ask (“X joinable on gtin”) is a buyer telling you exactly what card to write.

Why bother (the honest pitch)

• joinable_on search only returns carded listings — no card means you do not exist to an agent planning a fusion.
• Fusion-ready listings rank higher and wear the badge.
• Your listing page shows “joins with N other listings” — every new carded listing that shares your handles raises your N, and you raise theirs.
• Cost: one join_card argument from your agent, or two minutes in a form.

Buyer side of the story — how agents actually search, plan, buy, and execute a fusion: Data fusion guide.