Tell us what you owe us on a list. One call, keyed to the list id.

Where the list id comes from

It arrives with the data, in whichever way you receive it:

• CSV, by email or to a bucket: a List ID column on every row, all rows in one file carrying the same value. It is also in the delivery email.
• API or webhook: a list_id field on every record we post to you.
• Lost it: ask the endpoint. GET /api/v1/revenue?mode=lists returns your recent deliveries with their ids, dates, and record counts.

The id looks like ACMEWARRAN-4F2A-20260901-9B1C7E2A: your feed, the delivery date, and the delivery itself. It is stable forever and safe to store in your own system. Carrying it through to your reporting, so revenue can be grouped by it, is the one change on your side that makes all of this work.

Authentication

Every request carries your key in the X-API-Key header. It is the same key you already use with us if you pull data through the API. If you do not have one, ask your TDTM contact and we will issue one for reporting only.

Report revenue

POST one report, or up to 500 in a batch. Most buyers send one batch a month covering every list in the period. Daily and weekly work just as well.

curl -X POST https://www.talkdatatome.online/api/v1/revenue \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @revenue.json

{
  "reports": [
    {
      "list_id": "ACMEWARRAN-4F2A-20260901-9B1C7E2A",
      "revenue": 4120.00,
      "records_sold": 84,
      "external_id": "acme-2026-09-stmt"
    },
    {
      "list_id": "ACMEWARRAN-4F2A-20260902-2D77A1B4",
      "revenue": 3890.55,
      "records_sold": 71,
      "external_id": "acme-2026-09-stmt"
    }
  ]
}

What comes back

{
  "ok": true,
  "accepted": 2,
  "rejected": 0,
  "matched_to_a_delivery": 2,
  "results": [
    {
      "index": 0,
      "status": "stored",
      "list_id": "ACMEWARRAN-4F2A-20260901-9B1C7E2A",
      "match": "matched_run",
      "revenue_cents": 412000,
      "currency": "USD",
      "revision": 1,
      "replaced_revenue_cents": null,
      "warnings": []
    },
    { "index": 1, "status": "stored", "match": "matched_run", "revision": 1 }
  ]
}

Every report comes back with a match, which says how precisely we could tie your figure to a delivery. Nothing is ever rejected for failing to match: a figure we cannot place is still stored and flagged for a person here, because your revenue number is not something to lose over a mistyped id.

Or send every sale, one by one

If your reporting is good enough to send each sale, send those instead of a total. Post them to transactions rather than reports. Each one needs the list id, the amount, and occurred_on, the day it happened. record_ref is optional and is your own reference for the record that earned, which is what makes a question about one lead answerable later.

{
  "transactions": [
    {
      "list_id": "ACMEWARRAN-4F2A-20260901-9B1C7E2A",
      "revenue": 62.50,
      "occurred_on": "2026-09-14",
      "record_ref": "your-lead-id-88",
      "external_id": "sale-40192"
    },
    {
      "list_id": "ACMEWARRAN-4F2A-20260901-9B1C7E2A",
      "revenue": 145.00,
      "occurred_on": "2026-09-15",
      "external_id": "sale-40233"
    }
  ]
}

Individual sales and period totals price identically, so use whichever your systems produce. Sales are simply better evidence: a total is a claim, a list of sales can be pointed at. You can send both shapes in one request. If your sales and your monthly total cover the same list, we count the sales and set the total aside, so nothing is ever counted twice.

Tell us who converted, and we get better at finding more of them

A sale can also carry the person it was made on. Add an email or a phone to a transaction and we tie that sale to the exact record we sent you, which is what lets the next list lean toward the people who actually buy from you instead of the whole audience. It is optional, it is only read on a transaction, and it never changes what you are paid. The more of your sales carry it, the more precisely we can build for you.

{
  "transactions": [
    {
      "list_id": "ACMEWARRAN-4F2A-20260901-9B1C7E2A",
      "revenue": 62.50,
      "occurred_on": "2026-09-14",
      "email": "jane.doe@example.com"
    },
    {
      "list_id": "ACMEWARRAN-4F2A-20260901-9B1C7E2A",
      "revenue": 145.00,
      "occurred_on": "2026-09-15",
      "phone": "(415) 555-0142"
    },
    {
      "list_id": "ACMEWARRAN-4F2A-20260901-9B1C7E2A",
      "revenue": 80.00,
      "occurred_on": "2026-09-15",
      "email_sha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
    }
  ]
}

Send whichever form your system holds. Plaintext is fine and so is a hash: we read an md5, sha1 or sha256 by its length, and we match a plaintext address the way the rest of our platform does, so an address with dots or a +tag in it still finds the record. If you hash, hash the lowercased address, or for a phone the ten digits on their own.

Each identified sale comes back with an identity_match saying what we actually found. An identifier we could not place never reads as a match.

{
  "ok": true,
  "accepted": 3,
  "rejected": 0,
  "transactions": 3,
  "sales_tied_to_a_record": 2,
  "results": [
    { "index": 0, "status": "stored", "match": "matched_run", "identity_match": "matched" },
    { "index": 1, "status": "stored", "match": "matched_run", "identity_match": "matched" },
    {
      "index": 2, "status": "stored", "match": "matched_run", "identity_match": "no_match",
      "warnings": ["We could not find that person anywhere in the delivery you quoted. The revenue is stored exactly as you reported it; only the record link is missing."]
    }
  ]
}

One thing worth knowing if you restate a sale later: a sale that carried an identity is filed under that person, so send the same email or phone with the corrected figure and it replaces the original in place. Two sales on the same list on the same day are two separate sales when they name two different people.

Restating a figure

Revenue settles late. Send the corrected figure with the same list_id, period, and external_id and it replaces the old one in place, with the previous number kept alongside it. There is no delete and no need to tell us first. Retrying a request that timed out is safe for the same reason: the second send updates the first rather than doubling it.

If you cannot break it down by list

Report by feed and period instead. It is the least precise of the three, and revenue reported this way is spread across that feed's deliveries in the period, so start here if you must and move to list level when your reporting can carry the id.

{
  "feed_code": "ACMEWARRAN-4F2A",
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "revenue": 118400.00,
  "external_id": "acme-sept-total"
}

Look up your lists

curl "https://www.talkdatatome.online/api/v1/revenue?mode=lists&limit=50" \
  -H "X-API-Key: YOUR_KEY"

{
  "ok": true,
  "lists": [
    {
      "list_id": "ACMEWARRAN-4F2A-20260901-9B1C7E2A",
      "feed_code": "ACMEWARRAN-4F2A",
      "feed": "Acme warranty daily",
      "delivered_at": "2026-09-01T10:05:11.402Z",
      "records": 14294,
      "status": "success"
    }
  ]
}

Check what we hold

Read your own reports back at any time and reconcile against your books before an invoice is raised. Filter with since (a date or timestamp) or list_id.

curl "https://www.talkdatatome.online/api/v1/revenue?since=2026-09-01" \
  -H "X-API-Key: YOUR_KEY"

What we do with it

Your figure is used to work out the revenue share on the records in that list, and nothing else. It is never shown to another buyer, and a data partner supplying records sees only what their own records earned, never your totals, your feeds, or who else bought what.

An email or phone you send on a sale is hashed the moment it arrives and only the hash is kept. We do not store the address or the number, they are not written into the request record we keep for the figure, and they are used for one thing: pointing that sale at the record we already sent you. They play no part in what you are billed or paid, and they are never passed to anyone else.