Phantom Vault API

Returns your account details, pricing info, and current month usage.

Example Response

{
  "client": { "id": 42, "name": "Acme Corp", "email": "api@acme.com" },
  "pricing": { "type": "monthly", "price_per_record": 0.015, "record_cap": 250000 },
  "usage_this_month": { "records_pulled": 12500, "orders_placed": 8 },
  "total_orders": 64
}

Submit a new data order. The order enters a queue and is processed automatically. Previously delivered contacts are excluded.

Request Body (JSON)

Available Filters

Example Request

curl -X POST https://vault.phantomdata.io/api/v1/orders \
  -H "Authorization: Bearer pv_xxxx_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "zip_codes": ["78759", "78758"],
    "quantity": 1000,
    "filters": {
      "property_type": "single_family",
      "owner_type": "individuals",
      "min_sqft": 1200,
      "max_year_built": 2014
    }
  }'

Example Response

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

Returns your 50 most recent orders with status and record counts.

Example Response

{
  "orders": [
    {
      "id": 259, "zip_codes": "78759", "quantity": 1000,
      "status": "completed", "records_total": 1000,
      "records_with_phone": 1000, "has_download": true,
      "created_at": "2026-03-17T12:11:25"
    }
  ],
  "total": 1
}

Get detailed status of a specific order including record counts, cost breakdown, and timestamps.

Example Response

{
  "id": 259,
  "status": "completed",
  "zip_codes": "78759",
  "quantity": 1000,
  "records_total": 1000,
  "records_with_phone": 1000,
  "records_cached": 0,
  "records_batch": 496,
  "has_download": true,
  "started_at": "2026-03-17T12:11:25",
  "completed_at": "2026-03-17T12:13:13"
}

Download the completed order as a CSV file. Only available after order status is completed.

Example

curl -O -J https://vault.phantomdata.io/api/v1/orders/259/download \
  -H "Authorization: Bearer pv_xxxx_xxxx"

CSV Columns

first_name, last_name, address, city, state, zip, best_mobile, phone_2, email, property_type, estimated_value, equity_pct, year_built, sqft, owner_occupied, years_owned

Upload a CSV with phone + address + zip columns. Every row gets tagged with TCPA litigator and DNC flags. Returns a job_id you poll for completion.

Required columns (auto-detected, case-insensitive)

Example Request

curl -X POST https://vault.phantomdata.io/api/v1/scrub/upload \
  -H "Authorization: Bearer pv_xxxx_xxxx" \
  -F "file=@my_list.csv" \
  -F "list_name=Q2 cold-call list"

Example Response

{
  "job_id": 412,
  "status": "pending",
  "rows": 10000,
  "valid_phones": 9847,
  "scrubbable_rows": 9821
}

Poll until status is completed. Counts populate once the job finishes. Typical processing: a few minutes for 10K rows.

Example Response

{
  "job_id": 412,
  "status": "completed",
  "progress_pct": 100,
  "rows_input": 10000,
  "phones_scrubbed": 9821,
  "tcpa_litigators": 23,
  "dnc_flagged": 1402,
  "clean_count": 8396,
  "has_download": true
}

Two output modes via the type query param:

Example

curl -O -J "https://vault.phantomdata.io/api/v1/scrub/412/download?type=clean" \
  -H "Authorization: Bearer pv_xxxx_xxxx"

Check how many cached records are available in each ZIP before placing an order. Up to 100 ZIPs per request.

Example Request

curl -X POST https://vault.phantomdata.io/api/v1/preview \
  -H "Authorization: Bearer pv_xxxx_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "zip_codes": ["78759", "90210", "10001"] }'

Example Response

{
  "counts": { "78759": 4521, "90210": 1893, "10001": 756 },
  "total_cached": 7170
}

Returns up to 12 months of usage history including records pulled, orders placed, and billing amounts.

Example Response

{
  "usage": [
    {
      "month": "2026-03",
      "records_pulled": 12500,
      "orders_placed": 8,
      "batch_cost": 42.50,
      "amount_billed": 187.50
    }
  ]
}