Listings API

Three calls get you from nothing to a listing with a live link: check the key, submit a batch, read the statuses back.

curl https://api.mpowebstudio.com/v1/me \
  -H "Authorization: Bearer $MPO_KEY"

curl -X POST https://api.mpowebstudio.com/v1/batches \
  -H "Authorization: Bearer $MPO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-batch" \
  -d '{
    "reference": "first-run",
    "networks": ["bing"],
    "listings": [{
      "external_id": "cl-1",
      "name": "Staff St. Towing & Auto Body",
      "address1": "67 Stagg St",
      "city": "Brooklyn",
      "state": "NY",
      "postal_code": "11206",
      "phone": "+1-347-554-2285",
      "category": "towing",
      "owner_email": "owner@example.com"
    }]
  }'

curl "https://api.mpowebstudio.com/v1/listings?batch_id=btc_…" \
  -H "Authorization: Bearer $MPO_KEY"

Rows a directory would reject come back in step 2 with the field and the reason, instead of being submitted. That is deliberate: a bad row costs you money and costs the listing account its standing.

Send your key as a bearer token on every request. The key carries its own mode, so a key sitting in a config file is never ambiguous.

Authorization: Bearer mpo_live_…   # real submissions
Authorization: Bearer mpo_test_…   # sandbox

Simulated outcomes are deterministic: the same external_id always gets the same result, so your test suite is stable. A test batch also fires the same signed webhooks a real run would, immediately — so you can verify your signature check before you ever send a live batch. POST /batches and GET /me report which mode produced them via livemode.

Every response carries a request id, in the body and in the X-Request-Id header. Quote it in an email and we can find the exact call.

Every error has the same shape, so you branch on type for retry behaviour, on code for the specific case, and show message to a human:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_status",
    "message": "Unknown status. Allowed: submitted, pending_verification, live, rejected, needs_data.",
    "param": "status",
    "docs": "https://mpowebstudio.com/listings/docs#invalid_status",
    "request_id": "req_9f2c1a77b3d4e5f6"
  }
}

type is the coarse switch a bare code cannot give you: api_error and rate_limit_error are worth retrying, invalid_request_error never is. param appears only when one field is at fault, and docs is anchored per code, so the link lands on the paragraph explaining that exact failure.

Rate limits are per key, not per IP, so another integrator behind the same network can never throttle you:

POST /batches takes up to 10,000 listings per call, as JSON or CSV.

Always send an Idempotency-Key. If the same key arrives again with the same body — a timeout, a retry from your queue — you get the original batch back with idempotent_replay: true instead of the listings being submitted and billed twice. If the same key arrives with a different body, you get 409 idempotency_key_reused: reusing a key for new work would silently swallow the new listings, so you need to see it.

{
  "batch_id": "btc_77f1c287c434",
  "reference": "oct-week1",
  "networks": ["bing"],
  "livemode": true,
  "received": 1000,
  "accepted": 987,
  "rejected": 13,
  "rejections": [
    {"external_id": "cl-10244", "field": "phone",    "reason": "not a valid number for this country"},
    {"external_id": "cl-10250", "field": "category", "reason": "unmapped category: \"duct guy\""},
    {"external_id": "cl-10261", "field": "address1", "reason": "must include a street number"},
    {"external_id": "cl-10277", "field": "phone",    "reason": "duplicate phone, same as cl-10231"}
  ],
  "request_id": "req_05c8e43244ac2dcf"
}

CSV works the same way: field names as column headers, Content-Type: text/csv, one listing per row, hours as mon=08:00-18:00;sat=closed. Optional headers: X-Batch-Reference, X-Networks.

GET /batches lists your batches newest first. GET /batches/{id} gives the status counts for one. GET /batches/{id}/report returns the end-of-batch report as CSV, or JSON with ?format=json — live rows first, failures last.

GET /listings returns per-listing status, paged with an opaque cursor. Filter by batch_id, status, network; limit up to 500. Page with next_cursor until it comes back null.

The place id is stable. Keep it and you can re-read or update a listing later without searching for it.

Register one HTTPS endpoint and we post an event whenever a listing goes live or is rejected.

curl -X POST https://api.mpowebstudio.com/v1/webhooks \
  -H "Authorization: Bearer $MPO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.com/hooks/mpo", "events": ["listing.live", "listing.rejected"]}'

The response carries a signing secret, shown once. Every delivery has an X-MPO-Signature header in the form t=1760680802,v1=3f8a1c…, where v1 is the HMAC-SHA256 — keyed with that secret — of the timestamp, a literal dot, and the raw body: "{t}.{raw_body}".

Signing the timestamp alongside the body is what makes a captured delivery expire. Reject anything where t is more than five minutes old, and compare the hex in constant time.

import crypto from "crypto";

app.post("/hooks/mpo", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-MPO-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const { t, v1 } = parts;

  // Reject replays: the signature covers the timestamp, so an old capture cannot be reused.
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);

  const expected = crypto
    .createHmac("sha256", process.env.MPO_WEBHOOK_SECRET)
    .update(t + ".")             // the timestamp and a literal dot,
    .update(req.body)            // then the RAW body, before JSON.parse
    .digest("hex");

  const a = Buffer.from(expected), b = Buffer.from(v1);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(400);

  const { event, data } = JSON.parse(req.body);
  // event: "listing.live" | "listing.rejected"
  res.sendStatus(200);
});

Each event is attempted once, with a five-second timeout, and deliveries are unordered. There is no retry queue today: if your endpoint is down we record the error and move on rather than stalling your listings. Every delivery carries an X-MPO-Event-Id header, repeated as id in the body — dedupe on it, so a retry we add later cannot hurt you.

Deliveries are best-effort: if your endpoint is down we record the error and keep going, so your listings never stall waiting on it. GET /listings stays the source of truth.

Duplicates are detected across your whole account, by phone and by name plus address, and returned as rejections rather than submitted twice.

Bing: we submit immediately; the business completes PIN verification; the listing publishes 7 to 12 calendar days after that. We resend the PIN once after 7 days and report who has not completed it.

Apple: not open yet. Our partner application is in review. Batches sent with "networks": ["apple"] are refused with 409 rather than silently accepted.

We do not guarantee a publication rate. It depends on your data and on how quickly business owners verify. What we do guarantee is the status and the exact reason for every listing.