Ping setup

Buyer preacceptance ping lets Callmart ask your system, in real time, whether you want a specific call. You run a small HTTPS endpoint. Callmart posts a few facts about the call to it. You answer yes or no within four seconds. That is the entire feature.

Ping is for wholesale buyer accounts. If you have not been set up as a wholesale buyer yet, apply first. A buyer with no enabled ping configuration is simply accepted immediately using their normal buying settings, which is the right setup for most people.

Before you start

• An approved wholesale buyer account on Callmart.
• A public HTTPS endpoint on port 443. Private, internal, or non-routable hostnames are rejected.
• A valid TLS certificate. This is a server to server request, so there is no browser to click through a warning.
• An API key you generate. You will paste it into your workspace and Callmart will send it back to you on every request so you can authenticate the call.
• Something that can answer in well under three seconds, consistently, including at your busiest moment.

Step 1: build the endpoint

Callmart sends an HTTP POST with a JSON body. Your endpoint reads it, decides, and replies with JSON. There is no handshake, no signature scheme, and no callback. One request, one response.

Every request carries your own API key in the Authorization header, in the form Bearer followed by the key. Check it on every request and reject anything that does not match. That header is how you know the request is really from Callmart.

POST https://your-endpoint.example.com/callmart/ping
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "request_id": "a3f1c9e2-7b44-4d1a-9e55-0c8b21d4f7a6",
  "offer_id":   "6d2e0b14-58c7-4a90-b3f1-9ac7e0d51b22",
  "caller_id":  "+13055550142",
  "state":      "FL",
  "expires_at": "2026-09-18T15:04:21.000Z",
  "is_test":    false
}

request_id

The unique identifier for this call opportunity. You must echo it back exactly in your response. Log it, because it is how you match a ping to the call that followed.

offer_id

Identifies which of your assigned feeds this call belongs to. Use it if you want different accept rules for different feeds.

caller_id

The caller's phone number in E.164 format, for example +13055550142. Use it for your own duplicate and suppression checks.

state

The two letter US state code for the caller, for example FL or TX. Useful if your licensing or staffing is state dependent.

expires_at

When the underlying reservation expires. There is no reason to respond after this, and you should not.

is_test

True for test traffic. Use it to exercise your endpoint without touching production logic or your own reporting.

Step 2: return the exact accept response

To accept a call, return JSON with accept set to true and the request_id copied exactly from the request. Both fields are required, and the request_id must match.

{ "accept": true, "request_id": "a3f1c9e2-7b44-4d1a-9e55-0c8b21d4f7a6" }

{ "accept": false, "request_id": "a3f1c9e2-7b44-4d1a-9e55-0c8b21d4f7a6" }

Anything that is not a clean acceptance is treated as a decline. That includes accept set to false, a request_id that does not match, a body that is not valid JSON, an unreachable host, a TLS failure, and a timeout. There is no partial acceptance and no retry.

Copy the request_id, do not regenerate it. Echoing a different ID is the most common reason a ping that looks correct is being counted as a decline.

import express from "express";

const app = express();
app.use(express.json());

app.post("/callmart/ping", (req, res) => {
  if (req.get("authorization") !== `Bearer ${process.env.CALLMART_PING_KEY}`) {
    return res.status(401).json({ accept: false });
  }

  const { request_id, caller_id, state, is_test } = req.body ?? {};
  if (!request_id) return res.json({ accept: false });

  // Decide fast. Never call a slow downstream system from here.
  const accept = is_test ? true : hasCapacityFor(state, caller_id);

  res.json({ accept, request_id });
});

app.listen(443);

Step 3: know your budget

These three numbers are the whole performance contract. Design against them rather than hoping.

Three seconds sounds generous until a database is under load. The rule that keeps endpoints healthy is simple: the ping handler must never do work whose latency you do not control. Read from memory or a local cache, decide, respond. Push anything slow to a background job.

Step 4: turn it on in your workspace

1. 01Sign in and open Delivery controlsGo to your workspace and find Delivery controls, then Buyer ping settings.
2. 02Enter your endpoint URLThe full HTTPS URL of your handler, on port 443, publicly reachable.
3. 03Enter your API keyThe key Callmart should send in the Authorization header. It is stored encrypted at rest with AES-256-GCM.
4. 04Save, then testExercise the endpoint with test traffic first and confirm you see the requests arriving and your responses being accepted.
5. 05Enable itOnce you trust your own responses, enable the configuration. From that point every proposed call is pinged.

Good practice

• Log every request_id with your decision and your response time. When something looks wrong, this is the only record that will settle it.
• Treat the ping as idempotent. Deciding twice on the same request_id must not double-count anything on your side.
• Prefer an explicit decline over a timeout. A fast no is useful to everyone. A timeout is just a slow no that cost four seconds.
• Default to declining when you are unsure. Accepting a call you cannot answer is worse than missing one.
• Alert on your own error rate and latency. Nothing tells you the endpoint is down except your own monitoring.
• Start narrow. Accept a small slice, confirm the calls that arrive match what you accepted, then widen.

One thing worth saying plainly: the ping decides whether a call is offered to you, not whether you are billed. Billing still follows the normal rule. Connected time starts when your destination answers, ringing is excluded, and the call is charged once it passes your buffer.

Common questions