Ping Check API

What the Ping Check does

The Ping Check is a lightweight availability check. You send a zip code or a county, and we answer with a single boolean result:

The check contains no personal data — no name, phone, email or street address is sent. It is designed to be called on every lead, in real time, before the full post.

Where to send the request

Required headers

Authentication

Every request must carry your API key in the x-api-key header. Keys are issued per partner and per environment — the staging key will not work in production, and vice versa.

Body parameters

Send a flat JSON object. You must include at least one of zipcode or county.

{
  "zipcode": "33101"
}

{
  "county": "Miami-Dade"
}

Every response you can receive

All responses are JSON with Content-Type: application/json and always contain a result field.

Buyer available — post the lead

{
  "result": "true"
}

No buyer available — do not post

{
  "result": "false"
}

This is a normal, expected answer — not an error. It simply means that at this moment nobody can buy a lead in that area. The same zip code may return "true" minutes later, once budgets and daily caps reset or a new buyer subscribes.

Area not covered

{
  "result": "false"
}

The zip code or county was not found in our coverage table. Handle it exactly like "false".

Invalid request body

{
  "result": "error",
  "error": "[{\"field\":\"Zipcode\",\"reason\":\"field Zipcode is required
    when county is not present.\"}]"
}

Returned when neither zipcode nor county was sent, when a value exceeds its maximum length, or when a field has the wrong type. The error field is a JSON-encoded string containing an array of {field, reason} objects — decode it a second time if you want to log the detail. This response means your request must be fixed; retrying it unchanged will fail again.

Full response matrix

Why a ping returns “false”

Behind the boolean, every request runs through the same sequence of checks. The first check that fails for all buyers produces a "false".

1. Coverage

   The zip code or county must exist in our coverage table and resolve to a county and state.

2. Active subscription

   At least one buyer must hold an active subscription for that county and state.

3. Buyer can afford the lead

   The buyer’s remaining budget plus available credits must cover the lead price.

4. Daily cap not reached

   The buyer must not have already hit the number of leads they accept per day for that area.

5. National cap not reached

   The buyer must not have hit their nationwide daily lead limit across all areas.

Ready-to-adapt integration snippets

curl -X POST https://api.sellhousefast.com/prod/v1/leads/ping/check \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zipcode":"33101"}'

$ch = curl_init('https://api.sellhousefast.com/prod/v1/leads/ping/check');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        'x-api-key: ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode(['zipcode' => '33101']),
]);
$body = curl_exec($ch);
curl_close($ch);

$data     = json_decode($body, true);
$accepted = isset($data['result']) && $data['result'] === 'true';
// $accepted === true  ->  post the lead

const res = await fetch('https://api.sellhousefast.com/prod/v1/leads/ping/check', {
  method:  'POST',
  headers: {
    'x-api-key':    process.env.SHF_API_KEY,
    'Content-Type': 'application/json',
  },
  body:    JSON.stringify({ zipcode: '33101' }),
});

const data     = await res.json();
const accepted = data.result === 'true';   // string, not boolean

import os
import requests

r = requests.post(
    "https://api.sellhousefast.com/prod/v1/leads/ping/check",
    headers={"x-api-key": os.environ["SHF_API_KEY"]},
    json={"zipcode": "33101"},
    timeout=10,
)
accepted = r.json().get("result") == "true"

Before you go to production

• Ping right before posting. The result reflects budgets and caps at that exact second.
• Never cache a result. Not per zip code, not per minute.
• Set a client timeout of 10 seconds and treat a timeout as "false".
• Fail closed. Anything that is not exactly "true" means do not post.
• Send zip codes as strings so leading zeros survive ("07030", not 7030).
• Do not send personal data. Only zipcode and/or county are accepted; extra fields are ignored.
• Log the raw response body for at least 30 days — it is what we use together to resolve any discrepancy.
• Keep the API key server-side, in an environment variable or secrets manager — never in client-side code or in your repository.
• Test on staging first and remember to swap the API key when you move to production.

Frequently asked