API Reference

Account info, current balance, and this month’s usage.

Request

curl -H "Authorization: Bearer $PV_KEY" \
     https://vault.phantomdata.io/api/v1/me

Response 200

{
  "client": { "id": 142, "name": "Acme Outbound", "email": "ops@acme.com" },
  "pricing": { "type": "prepaid", "price_per_record": 0.05, "record_cap": 0 },
  "balance": 850.00,
  "trial_credits_remaining": 0,
  "add_funds_url": "https://vault.phantomdata.io/billing",
  "usage_this_month": { "records_pulled": 4321, "orders_placed": 8 },
  "total_orders": 47
}

Cheap pre-flight to see roughly how much data is cached for a list of ZIPs. Reads cache only — does not deduct from your balance. Up to 100 ZIPs per call.

Request

curl -X POST https://vault.phantomdata.io/api/v1/preview \
     -H "Authorization: Bearer $PV_KEY" \
     -H "Content-Type: application/json" \
     -d '{"zip_codes": ["33101", "33102", "33125"]}'

Response 200

{ "counts": { "33101": 12450, "33102": 8902, "33125": 14110 }, "total_cached": 35462 }

These are cached counts. Actual orders can pull beyond cache through our data providers.

Place an order against a set of ZIPs. Records are filtered to those with a mobile phone — we don’t deliver phoneless rows.

Body

Field	Type	Required	Notes
zip_codes	string[] or csv	yes	5-digit US ZIPs
quantity	int	one of	Target record count
want_all	bool	one of	Take everything available
filters	object	no	See filters below

Filters object

Key	Type	Example
property_type	string	"single_family", "condo", "multi_family"
owner_occupied	bool	true (skip absentee), false (only absentee)
min_value	int	300000
max_value	int	750000
tcpa_scrub	bool	true to drop TCPA litigators (adds per-record fee)
dnc_check	bool	true to flag DNC numbers (adds per-record fee)

Request

curl -X POST https://vault.phantomdata.io/api/v1/orders \
     -H "Authorization: Bearer $PV_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "zip_codes": ["33101", "33102"],
       "quantity": 500,
       "filters": { "property_type": "single_family", "owner_occupied": true }
     }'

Response 201

{ "order_id": 8421, "status": "pending", "zips": 2 }

Response 402 — Insufficient balance

{
  "error": "Insufficient balance",
  "message": "This order will cost ~$25.00 (500 records × $0.0500/record), but your balance is $4.10. Add funds at https://vault.phantomdata.io/billing before placing orders.",
  "balance": 4.10,
  "estimated_charge": 25.00,
  "shortfall": 20.90,
  "price_per_record": 0.05,
  "add_funds_url": "https://vault.phantomdata.io/billing"
}

Order status.

Request

curl -H "Authorization: Bearer $PV_KEY" \
     https://vault.phantomdata.io/api/v1/orders/8421

Response 200

{
  "id": 8421,
  "zip_codes": "33101,33102",
  "quantity": 500,
  "want_all": false,
  "status": "completed",
  "records_total": 487,
  "records_with_phone": 487,
  "has_download": true,
  "started_at": "2026-05-29T14:02:11",
  "completed_at": "2026-05-29T14:18:44",
  "created_at": "2026-05-29T14:01:55"
}

Order lifecycle

pending → processing → scraping → enriching → completed
                                      ↓
                                  failed

Poll every 10–30 seconds until status == "completed" (or "failed"). Typical processing is 5–25 minutes.

Last 50 orders, newest first.

curl -H "Authorization: Bearer $PV_KEY" \
     https://vault.phantomdata.io/api/v1/orders

Returns the order’s CSV. Only works once status == "completed".

curl -H "Authorization: Bearer $PV_KEY" \
     -o order_8421.csv \
     https://vault.phantomdata.io/api/v1/orders/8421/download

CSV columns (typical)

First Name, Last Name, Best Mobile 1, Best Mobile 2, Address, City, State, ZIP,
Email, Owner Occupied, Ownership Type, Landline, Mail Address, Mail City,
Mail State, Mail ZIP, Mail ZIP+4, Co-Owner Name

When tcpa_scrub or dnc_check are enabled, extra DNC and TCPA Litigator columns are appended.

Upload a CSV with phone numbers and we’ll scrub each row against TCPA litigators and the DNC list. Returns a job_id you poll for status.

Required CSV columns (case-insensitive)

• A column whose name contains phone, mobile, or cell
• One of: address, street, street_address, addr, address_line_1, address1
• One of: zip, zipcode, zip_code, postal_code, postal

Request

curl -X POST https://vault.phantomdata.io/api/v1/scrub/upload \
     -H "Authorization: Bearer $PV_KEY" \
     -F "file=@my_list.csv" \
     -F "list_name=April outbound batch"

Response 201

{ "job_id": 8500, "status": "pending", "rows": 12000, "valid_phones": 11842, "scrubbable_rows": 11800 }

Response 402 — Insufficient balance

{
  "error": "Insufficient balance",
  "message": "This scrub will cost ~$59.00 (11,800 phones × $0.0050/phone), but your balance is $4.10. Add funds via the dashboard or contact support.",
  "estimated_charge": 59.00,
  "balance": 4.10,
  "shortfall": 54.90
}

curl -H "Authorization: Bearer $PV_KEY" \
     https://vault.phantomdata.io/api/v1/scrub/8500

{
  "job_id": 8500,
  "status": "completed",
  "phones_scrubbed": 11800,
  "tcpa_litigators": 47,
  "dnc_flagged": 2103,
  "clean_count": 9650,
  "has_download": true
}

• type=clean (default) — only rows where the phone is not TCPA/DNC flagged
• type=full — every input row with two new columns: tcpa_litigator (bool) and dnc (bool)

curl -H "Authorization: Bearer $PV_KEY" \
     -o scrubbed_clean.csv \
     "https://vault.phantomdata.io/api/v1/scrub/8500/download?type=clean"