API Documentation

Estimate the cost, build the list (it can wait for you), download the CSV.

KEY='<PROPCONTACT_API_KEY>'

# 1 · estimate (free)
curl https://api.propcontact.net/v1/preview -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"filters":{"areas":[{"state":"NJ","city":"Cresskill"}],"has_wireless_phone":true},"max_results":40}'
# -> {"total_matching":3080,"eligible_for_export":3080,"estimated_credit_cost":40}

# 2 · build + wait (spends credits)
RESP=$(curl "https://api.propcontact.net/v1/lists?wait=55" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Cresskill mobiles","filters":{"areas":[{"state":"NJ","city":"Cresskill"}],"has_wireless_phone":true},"max_results":40}')
# -> {"list_id":"7087fe64-…","status":"ready","credits_held":40}

LIST_ID=$(printf '%s' "$RESP" | jq -r '.list_id // empty')
test -n "$LIST_ID" || { printf '%s
' "$RESP" >&2; exit 1; }

# 3 · download the CSV (free)
curl -sL https://api.propcontact.net/v1/lists/$LIST_ID/download -H "Authorization: Bearer $KEY" -o list.csv

Every request carries a Bearer key, created in your dashboard under Developer API. The full key is shown once at creation — store it in a secret manager.

Authorization: Bearer <PROPCONTACT_API_KEY>

• pc_live_… — production. Search/preview/detail are free; list builds and billable enrichment results spend credits.
• pc_test_… — sandbox. Free reads hit real data, but builds return a fake list and never spend credits. Wire up your integration with this first.

Scopes

Free (rate-limited): me, usage, search, preview, properties, dropdowns.

Spends credits: POST /lists and live async enrichment hold credits and settle their actual billable rows. After its separate activation notice, paid POST /append directly settles one credit only when a phone or email is returned. Nonmatches and contact-free matches cost zero. Reading an already built list or completed batch is free.

curl https://api.propcontact.net/v1/me -H "Authorization: Bearer $KEY"
# {"account_id":"…","credits_balance":123734,"active_plan_id":null,
#  "key":{"environment":"live","scopes":["search:read","lists:read","lists:write"],"rate_limit_per_min":120}}

When the balance cannot cover a write, POST /lists returns 402 insufficient_credits with detail.meta.{required, available, shortfall}; paid /append returns detail.{required, available}.

Every search/preview/build takes the same filters object.

CLEC does not mean mobile. CLEC is a source carrier classification, reported separately from wireless, landline, and any independently verified line status. It does not prove that a number is mobile or currently connected. For any source-matched number, use has_contact:true.

Enrichment accepts structured property addresses and returns one terminal result for every input. Your optional external_id and PropContact's input_index are echoed on every matched, not-found, ambiguous, or invalid row so you can join results without relying on a property ID.

Paid single-address append

curl https://api.propcontact.net/v1/append -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"records":[{"external_id":"crm-row-42","address":{"street":"101 Main St","unit":"2B","city":"Cresskill","state":"NJ","zip":"07626"}}]}'

POST /v1/append accepts exactly one records[] item. A live request requires an active account entitlement and Idempotency-Key. It settles one credit only when at least one phone or email is returned; not-found, ambiguous, invalid, and contact-free matches cost zero. Contact values are released only after settlement. An identical retry never debits twice. Use /v1/enrichments for every multi-row request. Test keys return one deterministic synthetic record, never read production addresses, and never spend credits.

Activation gate: this paid sync shape replaces the completed complimentary benchmark contract only after PropContact sends an explicit activation notice. Until then, use the live paid /v1/enrichments flow for address work.

Durable batches

{
  "records": [
    {
      "external_id": "crm-row-42",
      "address": {
        "street": "101 Main St", "unit": "2B", "city": "Cresskill",
        "state": "NJ", "zip": "07626"
      }
    }
  ],
  "options": {
    "email_verification": false,
    "line_lookup": false,
    "compliance_scrub": false
  }
}

Send a unique visible-ASCII Idempotency-Key for each logical batch and reuse it only for an identical retry. Poll status until it is complete, then page results untilnext_cursor is null. Inputs/results are scheduled for deletion after 14 days; minimal accounting facts follow the financial retention schedule.

Polling remains authoritative: separately entitled accounts may add webhook: { url, signing_secret? } for a signed status-only notification. Webhooks contain no contacts or input rows; fetch results from the authenticated results endpoint.

Matching and credits

An async batch holds at most one base credit per input, then settles only unique matched properties that contain a requested usable contact. Unused holds are restored. Duplicate inputs fan out to every caller row but charge once within that batch. Separate batches may be charged again under the partner freshness agreement; enrichment never silently removes a row because it appeared in an older list.

Contact metadata

Phones are returned wireless-first, followed by other source classifications. Each number may include E.164 normalization, source classification, identity-match quality/confidence/score, source DNC status, and connected status. A strong match means the source linked the number to this property's record on surname plus address or name, at the stated confidence. It is not identity verification, and it is not proof that the line is active, connected, reachable, mobile, or safe to contact. CLEC remains a separate source classification. A false or missing source DNC value is unknown, never "clear."

Base emails are unverified. Fresh carrier/LRN, provider-backed email validity, live line status, reassigned-number, DNC, and TCPA-litigator signals are unavailable in the initial release. Requests that enable email_verification, line_lookup, or compliance_scrub fail closed until a contracted provider, metering unit, data-processing terms, and account entitlement are enabled.

Completion notification

A webhook requires a public HTTPS callback on port 443 and separate exact-account entitlement. Supply a 32–256 character signing secret, or store the generated secret returned once on a fresh create. PropContact sends X-PropContact-Event-Id, X-PropContact-Delivery-Attempt, X-PropContact-Timestamp (Unix seconds), and X-PropContact-Signature in the form v1=<lowercase 64-hex HMAC-SHA256>.

signed_bytes = X-PropContact-Timestamp + "." + exact_raw_request_body
expected = "v1=" + hex(HMAC-SHA256(signing_secret, signed_bytes))

Verify the signature against the exact raw body before parsing JSON, compare it in constant time, reject a timestamp more than five minutes from your clock, require the body event_id to equal X-PropContact-Event-Id, and atomically deduplicate that event ID. A valid duplicate should return 2xx without doing the work twice. Transport failures, 408, 425, 429, and 5xx retry for about 32.5 hours; redirects are never followed. Always retain polling as the recovery path.

Every error responds {"detail":{"code","message"}}. Switch on detail.code.

Rate limits. Default 120 requests / 60 s per key (higher on request). Over the limit → 429 rate_limited with Retry-After: 60. Sleep, then retry.

Idempotency. Live POST /append and POST /enrichments require Idempotency-Key; POST /lists strongly recommends it. Generate one key per logical write and reuse it only for an identical retry. This prevents duplicate receipts, jobs, and charges.

Sandbox. A pc_test_… key lets you build integrations for free — POST /lists returns a fake list and entitled POST /append returns deterministic synthetic people. Free search reads use real data. Async POST /enrichments accepts live keys only.

Point your AI coding agent at this contract and it can wire the API into your app. The full spec with drop-in Python & TypeScript client classes is in our interactive reference. The core loop: preview (cost) → lists?wait= (build) → items / download.

import os, uuid, requests
BASE, KEY = "https://api.propcontact.net/v1", os.environ["PROPCONTACT_API_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
filters = {"areas": [{"state": "NJ", "city": "Cresskill"}], "has_wireless_phone": True}

r = requests.post(f"{BASE}/lists?wait=55",
    headers={**H, "Idempotency-Key": str(uuid.uuid4())},
    json={"filters": filters, "max_results": 40}).json()
rows = requests.get(f"{BASE}/lists/{r['list_id']}/items",
    params={"page_size": 500}, headers=H).json()["rows"]
print(len(rows), "contact records")