The buyer integration playbook

Every buyer you add is a new integration, a new set of expectations, and a new way for your operation to break at 2am. Most operators treat buyer onboarding as a config task — fill in the endpoint, map the fields, turn it on. Then spend the next three weeks discovering what nobody asked about during setup.

Buyer integration is a project with a predictable failure pattern. The failures are almost never exotic. They're the same eight or nine things, every time, and they're all preventable by asking the right questions before touching a form.

This is the playbook.

Stage 1: The conversation before the config

Do this before you open any configuration screen. Most integration pain traces back to a question nobody asked here.

Commercial terms:

What are they paying, and per what? Per delivered lead, or per conversion?
If it's per conversion: what counts as a conversion, who decides, and how long do they get to decide? A conversion window you didn't agree on is a receivable you can't age.
Is there a volume commitment in either direction?
What's the return policy — what window, what reasons, what evidence?

Technical terms:

What's the endpoint, and what does it expect? Get their documentation before you promise a timeline.
How do they signal acceptance versus rejection? Ask for real example responses of both. Not the schema — the actual payloads. This is the single highest-value artifact you can get from a buyer, and it's the one most often skipped.
Where in their response is the price, if they're bidding?
Where in their response is the rejection reason?
What are their required fields, and what do they do when one is missing — reject, or accept and silently drop it?
Do they dedupe on their side? On what key, over what window?

Operational terms:

What hours do they actually want leads? In what timezone?
What's their daily capacity, and what happens when you exceed it — do they reject cleanly, or do they accept leads they can't work?
Who do you call when something breaks, and what's their response time?

That last question about capacity matters more than it sounds. A buyer that accepts everything and works nothing looks great in your reports for about a month, and then your return rate arrives all at once.

Write the answers down. The rest of the playbook is executing against them.

Stage 2: Delivery method and pricing model

Two decisions that constrain everything downstream.

Delivery method — how the lead gets to them:

Direct post — one call, full record, they accept or reject. Simplest. Right when the price is fixed and known.
Ping/post — a thin ping to get a bid or an interest signal, then a post with the full record if they win. Right when they price dynamically. Costs you a round trip and a second integration surface.
Email or store-only — real, and appropriate for buyers who can't take an API. Understand you're giving up real-time everything.

Pricing model — when revenue is real:

Per delivered lead — revenue books at delivery. Clean.
Per conversion — revenue books at confirmation. The lead sits pending until they tell you what happened.

The conversion model has a consequence people don't plan for: a pending sale is not revenue. Between delivery and confirmation, the lead has been committed to that buyer, it isn't going anywhere else, and you've booked nothing. Your reports will show it as pending, not sold, and that's correct — booking it as revenue at delivery and reversing it later is how you get phantom revenue that your finance team eventually notices in a bad way.

The other consequence is routing: a conversion-priced buyer has no bid to compete with, so putting them in a head-to-head auction against delivery-priced buyers doesn't work. They belong in a lower tier with no price floor. That's a routing decision made at integration time, and it's easier to get right now than to unpick later.

Stage 3: Payload mapping

You have fields. They want fields. The mapping between them is where the tedium lives.

Three distinct problems, often conflated:

Field naming. Their zip_code is your zip. Mechanical, template-level, boring, fine.

Value formatting. You hold CA; they want California. You hold a 10-digit string; they want +1 prefixed. You hold 1990-12-31; they want 12/31/1990. This is transformation — the same value, reshaped.

Value vocabulary. You hold Excellent; their enum only accepts A. You hold Homeowner; they want 1. This is a lookup table, not a format change, and it's worth keeping separate from formatting in your head because it changes for business reasons, not technical ones.

Practical rules:

Transform on the way out, never in the database. The lead is the lead. What a buyer wants is that buyer's problem, and if you normalize your stored data to buyer A's vocabulary, you've made buyer B's integration harder forever.
Fill the blank before you map it. A default applied after a lookup is a default the lookup never saw. Order matters in a transform chain: fallback first, then map, then type coercion last.
Omit rather than send empty. Buyers that validate strictly will reject {"middle_name": ""} where they'd have accepted the key not being there at all. If your platform can drop a key conditionally, use it — and know that an empty string is not null. A field that exists and is blank will not trip an existence check. This one detail accounts for a genuinely surprising share of "why did they reject that."
Beware silent no-ops. In most template engines, an unrecognized transformer name doesn't error — the value just passes through untouched. Your config looks right, the value looks wrong, nothing logs. Copy transformer names from documentation, never from memory, and verify with a test post rather than by reading your own config.

Stage 4: Response mapping — where it actually breaks

If one stage causes more production incidents than the rest combined, it's this one.

You must teach your platform to read the buyer's answer. Which response means accepted, which means rejected, which means duplicate, which means "my server is on fire, try again." Get this wrong and the failure is silent and expensive in both directions:

Reading a rejection as an acceptance — you book revenue for a lead the buyer threw away. It reconciles badly at month end.
Reading an acceptance as a rejection — you fall through to the next buyer and sell a lead you already sold. Now you have a compliance problem, not a reporting problem.

The rules:

Match on real responses, not on the documentation. Docs describe the happy path. Ask for a real accepted response and a real rejected response, then match against those bytes.
Test the rejection path explicitly. Everyone tests acceptance. Almost nobody sends a lead they know will be rejected to confirm it reads as a rejection. Do it — deliberately send a lead that fails their validation and watch what your platform concludes.
Beware substring matching. A rule looking for "duplicate" anywhere in the response will happily match "no duplicate found". Match on structure — a specific field at a specific path — not on the response containing a word.
Capture the rejection reason. If they tell you why, store it. Rejection reasons are the highest-signal data in your operation; a buyer who's telling you why and an operator who isn't listening is a wasted feedback loop.
Decide what an error means. A timeout is not a rejection. A 500 is not a rejection. If you treat infrastructure failures as "this buyer doesn't want this lead," you'll fall through to your next buyer every time their server hiccups and never notice they were down for an hour.

Stage 5: Postbacks and confirmation

If the buyer pays on conversion, they need to tell you when a conversion happens. That's an inbound postback, and it has three requirements:

An identifier that ties back to a specific record. They post back with the id you gave them at delivery. Whatever identifier scheme you use, the buyer must echo the one you sent, and it must be unambiguous about which sale it refers to — the lead alone often isn't enough if the same lead touched multiple buyers.
A status, and agreement on the vocabulary. Here's a trap: most systems normalize an unrecognized status to accepted. declined maps to rejected; declined_pending_review might not, and would land as an acceptance. Confirm the exact status strings they'll send, and confirm what your side does with a string it doesn't recognize.
Idempotency. Networks retry. Buyers re-send. A confirmation that arrives twice must not book revenue twice. If you're building this yourself, key on the transaction and short-circuit the repeat.

Also set the expiry: if a conversion window passes with no word, the pending sale resolves to rejected on its own. Without that, pending sales accumulate forever and your pending bucket becomes a graveyard nobody trusts.

Stage 6: Test before you send anything real

Non-negotiable. The order that works:

Send a test payload to their endpoint. Verify it's reachable, your credentials work, your headers land. You're testing plumbing, not logic.
Send a lead you expect to be accepted. Confirm your platform reads acceptance correctly, extracts the price correctly, and books it correctly.
Send a lead you expect to be rejected. Confirm you read the rejection as a rejection, and that you captured the reason. This is the step people skip.
If they bid: verify the price you extracted matches the price they sent. Off-by-a-field-path errors here are quiet and expensive.
If it's ping/post: verify the post carries what the ping promised, and that a lost ping doesn't post.
If it's conversion-priced: fire a confirmation postback yourself and watch the pending sale resolve. Then fire it twice and confirm it doesn't double-book.
Read the logs, not the summary. The request you actually sent, the response they actually returned. Summaries hide the field-level problem you're looking for.

One caution: understand exactly what your platform's test mode does. Test paths commonly bypass validation, deduplication, and fraud checks, and route to a dummy buyer — which is useful for testing your pipeline, and useless for testing this buyer's integration, because the real buyer never gets called. Those are different tools for different jobs. Make sure you know which one you're holding, or you'll conclude an integration works when nothing ever reached them.

Stage 7: Caps, schedule, and position

Before you turn it on:

Caps. Daily, weekly, monthly, and lifetime where it's available. Set them from the capacity conversation in Stage 1. A new buyer with no cap is an unbounded promise to a partner you've never worked with.
Schedule. With the timezone. A buyer set to business hours in the wrong timezone gets leads at 3am, works none of them, and returns them all. Timezone bugs in delivery schedules are a genuine classic.
Position. Where does this buyer sit — first in the waterfall, in the auction, in which tier, at what weight? A new buyer dropped into a weighted campaign will take a catch-up burst of volume on day one, because its realized share starts at zero and the engine is trying to close that gap. Expect it. Don't panic-adjust the weight while it's happening.

Stage 8: Go live small, and watch

Don't cut full volume to a new buyer on day one.

Start at a fraction of the volume you intend. A cap is the easiest throttle you have.
Watch the acceptance rate for the first day. An acceptance rate near 100% or near 0% almost always means a response-mapping problem, not a quality signal. Real acceptance rates live in between.
Watch the rejection reasons. A single reason dominating on day one is a mapping bug in disguise.
Watch latency. A buyer that's slow in testing is slower under volume, and in an auction a slow buyer just doesn't compete.
Reconcile at the end of week one. Your count against their count. Do it before it's a month of drift and a conversation about money.

Then ramp. The first week at low volume costs you a little revenue and saves you the incident.

Common failure modes

Symptom	Usual cause
Buyer receives nothing	Inactive, at cap, outside schedule, or filtered out before they're even considered
Buyer receives nothing, in a tiered setup	Their tier's price floor is above their bid — a zero-price buyer under a non-zero floor qualifies for nothing
Acceptance rate is 100% or 0%	Response mapping, not lead quality
Price comes through wrong or zero	Extraction pointing at the wrong path in their response
Pings time out	Their endpoint is slow; check whether repeated failures are tripping a circuit breaker and skipping them entirely
Header values arrive empty	Placeholder syntax wrong, or the field genuinely isn't in the payload
A conditionally-omitted key still sends	The field is an empty string, not null — empty is not absent
Multi-step ping fails on step 2	Step 2 is referencing a field from step 1's response that isn't shaped the way you assumed
Conversion-priced lead "stuck" in pending	Not stuck. That's the model. It resolves when they confirm, or when the window expires
Revenue disagrees with theirs at month end	Returns, timezone boundaries on the reporting day, or acceptances you read as rejections

Most of that table is Stage 1 and Stage 4 coming back around. The commercial questions you didn't ask, and the responses you mapped from documentation instead of from reality.

The takeaway

Buyer integration fails in predictable places: the questions nobody asked before the config, and the response mapping nobody tested against a real rejection.

Get their real accepted and rejected responses before you build. Transform outbound, never in your data. Test the rejection path, not just the happy path — and know whether your test mode is actually calling the buyer or a stand-in. Go live at a fraction of volume and reconcile in week one, while a discrepancy is still a conversation instead of an invoice.

None of this is difficult. It's just work that has to happen before the leads flow, and the entire cost of skipping it is paid later, at a worse time, in front of a buyer.