Partner API Integration Guide

01What this integration does

You send us business listings. We publish them on the BizScout marketplace. When a buyer enquires, we send you their details so your team can follow up. When a listing's marketplace status changes, we tell you.

The happy path

1. POST /listings. We answer 201 with publication_state: "queued".
2. We publish it automatically, normally within seconds.
3. We POST listing.status_changed with publication_state: "published". A GET now returns a public_url.
4. A buyer enquires. We POST buyer_inquiry.created with their contact details.
5. When the business sells, tell us — PATCH to SOLD, or send a deal event — and we take it off the marketplace.

If your receiver is unavailable at step 3 or 4, we retry for about 24 hours, and you can catch up by reading the API (section 8).

02Getting started

URL shape

Versioned and slug-scoped. There is no /api segment.

https://partner.api.bizscout.com/v1/{partner_slug}/listings

# for acme-deals:
https://partner.api.bizscout.com/v1/acme-deals/listings

How your requests reach us

Your requests arrive at our API gateway. It validates your X-API-Key and forwards the request to the API, which verifies your signature and does the work.

That means a rejection can come from either layer, and the two look different:

IP allowlisting. We do not require you to call us from fixed addresses. If you need us to allowlist your egress IPs, tell us at onboarding — and tell us just as clearly if you cannot guarantee fixed addresses, so we never build an edge rule that silently blocks you.

03Authentication

Every request carries your API key. Every request that changes something also carries an HMAC signature.

A request that fails authentication returns 403 with a deliberately uninformative message.

3.1Signing your requests

X-BizScout-Signature: t=<unix_seconds>,v1=<hex_digest>

v1 = HMAC_SHA256(signing_secret, "<t>" + "." + <raw request body bytes>)

Three rules that cause most first-integration failures:

1. Sign the exact bytes you transmit. Never re-serialise parsed JSON to build the signing message — key order and whitespace will differ and every signature will fail.
2. A request with no body signs the empty string — not {}, not null. This applies to DELETE, which is not exempt.
3. The timestamp window is 300 seconds either side. A clock running fast fails exactly like one running slow. Intermittent 403s on otherwise valid requests are almost always NTP.

Send only one signature header. If something in your network path duplicates or joins it, we treat it as ambiguous and refuse the request.

const { createHmac } = require('node:crypto');

function sign(secret, rawBody) {
  const t = Math.floor(Date.now() / 1000);
  const v1 = createHmac('sha256', secret)
    .update(`${t}.`)
    .update(rawBody)          // '' for a bodyless request
    .digest('hex');
  return `t=${t},v1=${v1}`;
}

const body = JSON.stringify(payload);   // sign and send the SAME string
await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
    'X-BizScout-Signature': sign(SIGNING_SECRET, body),
  },
  body,
});

3.2Verifying our webhooks

Same scheme, inverted. Verify over the raw body as received, before parsing.

const { createHmac, timingSafeEqual } = require('node:crypto');

function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(
    String(header).split(',').map(p => p.split('=').map(s => s.trim()))
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;

  // Reject anything outside 300 seconds, in either direction.
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false;

  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.`)    // the timestamp EXACTLY as sent
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(String(parts.v1 || ''));
  return a.length === b.length && timingSafeEqual(a, b);
}

Use a constant-time comparison, and make sure your framework gives you the raw body — many parse and discard it by default.

04Conventions

4.1Status codes

4.2Errors

{
  "error": {
    "code": "bad_request",
    "message": "Validation failed",
    "request_id": "1e0e9c01-f0eb-4dff-9d62-c73be1762a44",
    "details": [
      { "message": "title must be shorter than or equal to 200 characters" },
      { "message": "property listing_titel should not exist" }
    ]
  }
}

4.3Idempotency

• POST /listings is keyed on partner_listing_id. A repeat returns 200 with the listing as it already exists — the replayed body is discarded. This is not an upsert; use PATCH to change a listing.
• Batches are safe to resubmit. Items already created report existing.
• Events are keyed on event_id, permanently. A duplicate returns 202 with the original acknowledgement and is not applied twice. Never generate a new event_id for a retry.

4.4Sending null

4.5Limits, money and time

• Bodies are capped at 10 MB.
• Money is whole dollars. 1250000 means $1,250,000. No decimals, no currency field — all values are USD.
• Time is ISO 8601 in UTC.
• Unknown fields are rejected with a 400, so a typo fails loudly instead of being silently dropped. Put your own data in metadata, which we store and echo back untouched.

05Endpoints

All paths are relative to https://<base>/v1/{partner_slug}. Each endpoint below carries its own request fields, responses and failure modes.

POST https://partner.api.bizscout.com/v1/acme-deals/listings
X-API-Key: <key>
X-BizScout-Signature: t=1788530199,v1=<hex>
Content-Type: application/json

{
  "partner_listing_id": "f0512332-435d-4b56-a546-859d18de38ba",
  "title": "Established Residential HVAC Service Company",
  "description": "Full-service residential HVAC company with 18 years of operating history.",
  "industry": "HVAC Services",
  "listing_status": "ACTIVE",
  "asking_price": 2450000,
  "cash_flow": 610000,
  "detailed_location": "Phoenix, AZ",
  "broker_name": "Dana Whitfield",
  "broker_email": "dana@acme-deals.example.com",
  "metadata": { "internal_ref": "AD-2026-114" }
}

{
  "partner_listing_id": "f0512332-435d-4b56-a546-859d18de38ba",
  "bizscout_listing_id": "4067763",
  "listing_status": "ACTIVE",
  "publication_state": "queued",
  "title": "Established Residential HVAC Service Company",
  "asking_price": 2450000,
  "metadata": { "internal_ref": "AD-2026-114" },
  "created_at": "2026-09-04T10:14:22.881Z",
  "updated_at": "2026-09-04T10:14:22.881Z"
}

POST .../listings/batch

{ "listings": [ { …create fields… }, { …create fields… } ] }

{
  "batch_id": "58a58536-d849-4f5b-ac7e-f5a579559f3a",
  "status": "queued",
  "total": 2,
  "status_url": "https://partner.api.bizscout.com/v1/acme-deals/listings/batch/58a58536-…"
}

{
  "batch_id": "58a58536-d849-4f5b-ac7e-f5a579559f3a",
  "status": "completed",
  "total": 2,
  "processed": 2,
  "summary": { "total": 2, "created": 1, "existing": 1, "failed": 0 },
  "results": [
    { "partner_listing_id": "…", "status": "created",  "listing": { "bizscout_listing_id": "4067764" } },
    { "partner_listing_id": "…", "status": "existing", "listing": { "bizscout_listing_id": "4067701" } }
  ]
}

PATCH .../listings/f0512332-435d-4b56-a546-859d18de38ba

{ "asking_price": 2295000 }

DELETE .../listings/f0512332-435d-4b56-a546-859d18de38ba
X-API-Key: <key>
X-BizScout-Signature: t=1788530412,v1=<hex over the EMPTY string>

{ "data": [ { …enquiry… } ], "has_more": true, "next_cursor": "18240" }

POST .../listing-events
{
  "event_id": "0d1f4c22-9d0e-4a57-9f7b-2f1f1f0f9a10",
  "event_type": "listing.status_changed",
  "partner_listing_id": "f0512332-435d-4b56-a546-859d18de38ba",
  "status": "UNDER_LOI",
  "occurred_at": "2026-09-04T10:00:00Z"
}

→ 202 { "accepted": true, "event_id": "0d1f4c22-…", "bizscout_event_id": "18240" }

POST .../deal-events
{
  "event_id": "9a41c0de-7f22-4a10-8b6e-0d51b2c8e441",
  "event_type": "deal.stage_changed",
  "partner_listing_id": "f0512332-435d-4b56-a546-859d18de38ba",
  "partner_deal_id": "ad_deal_301",
  "stage": "DEAL_CLOSED_WON",
  "occurred_at": "2026-09-04T10:30:00Z"
}

06The listing lifecycle

Two values move independently. You own one; we own the other.

Re-sending a status a listing already has changes nothing and produces no webhook. Neither does a change between two unpublished states, such as UNDER_LOI to SOLD.

What “published” means: publication_state is published, the listing is live and searchable on the marketplace, and the API returns a public_url. Getting there normally takes seconds — we enrich the listing first, and there is no human review step.

07Webhooks you must receive

Give us one base URL. We POST beneath it:

Route on the path, or on the event field in the body — both are reliable.

7.1Headers on every delivery

7.2Envelope

7.3Payloads

listing.status_changed

{
  "id": "evt_77c94ff2-1a90-42f1-b595-5b7c3d22c1c5",
  "event": "listing.status_changed",
  "api_version": "v1",
  "occurred_at": "2026-09-03T23:07:10.866Z",
  "data": {
    "bizscout_listing_id": "1532472",
    "partner_listing_id": "2320db81-0b25-4975-9ece-eac35b2575b5",
    "publication_state": "published",
    "listing_status": "ACTIVE",
    "changed_at": "2026-09-03T23:07:10.866Z"
  }
}

buyer_inquiry.created

{
  "id": "evt_6c342746-2561-4643-879d-24f52ba3f689",
  "event": "buyer_inquiry.created",
  "api_version": "v1",
  "occurred_at": "2026-08-17T22:22:59Z",
  "data": {
    "inquiry_id": "bs_inq_10482",
    "buyer": {
      "first_name": "Michael",
      "last_name": "Anderson",
      "email": "michael.anderson@example.com",
      "phone": "+1-415-555-0187",
      "role": "pro"
    },
    "listing": {
      "bizscout_listing_id": "4067763",
      "partner_listing_id": "f0512332-435d-4b56-a546-859d18de38ba"
    },
    "purchase_timeframe": "0-3 months",
    "message": "Hi, I am interested in acquiring this business...",
    "created_at": "2026-08-17T22:22:59Z"
  }
}

7.4Retries

Answer 2xx as soon as you have durably accepted the event, then process. Each request times out after 10 seconds.

After the fifth attempt we stop, permanently. There is no later automatic redelivery. If you were unavailable for a day, reconcile using section 8.

7.5Deduplication is your responsibility

A retry re-sends the same id and the same occurred_at; only the attempt number and the signature change.

08Reconciliation

The enquiries endpoint returns every enquiry we attempted to deliver for that listing, failures included — a complete record from our side, not just successful deliveries.

09Onboarding checklist

Step 9 matters: until it is done, a signing bug on your side can pass every earlier step.