Developer Docs
Download .md file (Feed to AI for context)
POST

Batch Trace

/v1/api/trace/
Description: Asynchronous batch endpoint for processing multiple addresses at once via CSV or JSON. Results are delivered via download_url when complete. For single-address instant lookups, use the Instant Trace Lookup endpoint instead.

⚠️ API Usage Policy: Do not abuse API POST calls. Accounts found to be abusing the API will be put on hold. Maximum rate limit is 10 POST trace requests per 5-minute window. Please use the API responsibly and in accordance with our Terms of Service - API Rate Limits & Abuse Policy.
Authentication: Bearer Token
Status codes: 200 OK, 400, 401, 403

Headers

  • Authorization = Bearer <YOUR_TOKEN>
  • Content-Type = multipart/form-data or application/json

Parameters

Name
In
Type
Required
Description
address_column
body
string
Yes
Column name for property address.
city_column
body
string
Yes
Column name for property city.
state_column
body
string
Yes
Column name for property state.
zip_column
body
string
No
Column for property ZIP (optional — for advanced traces, we return this from our data if not provided).
first_name_column
body
string
Yes
Column for owner first name (optional for advanced traces — we identify the owner for you).
last_name_column
body
string
Yes
Column for owner last name (optional for advanced traces — we identify the owner for you).
mail_address_column
body
string
Yes
Column for mailing address (optional for advanced traces — we return this from our data).
mail_city_column
body
string
Yes
Column for mailing city (optional for advanced traces — we return this from our data).
mail_state_column
body
string
Yes
Column for mailing state (optional for advanced traces — we return this from our data).
mailing_zip_column
body
string
No
Column for mailing ZIP (optional — for advanced traces, we return this from our data if not provided).
trace_type
body
string
No
Trace type: 'normal' (1 credit/lead) or 'advanced' (2 credits/lead). Defaults to 'normal'. For advanced traces, only address_column, city_column, and state_column are required — all other fields are optional as we identify the owner and return their full contact and mailing info.
csv_file
form-data
file
No
CSV file of records.
json_data
body
string
No
Raw JSON array of records (alternative to csv_file).

Example Request

curl -X POST 'https://tracerfy.com/v1/api/trace/' \
  -H 'Authorization: Bearer ' \
  -F 'csv_file=@/path/to/records.csv' \
  -F 'address_column=address' \
  -F 'city_column=city' \
  -F 'state_column=state' \
  -F 'zip_column=zip' \
  -F 'first_name_column=first_name' \
  -F 'last_name_column=last_name' \
  -F 'mail_address_column=mail_address' \
  -F 'mail_city_column=mail_city' \
  -F 'mail_state_column=mail_state' \
  -F 'mailing_zip_column=mailing_zip' \
  -F 'trace_type=normal'

Example Response 200

{
  "message": "Queue created",
  "queue_id": 456,
  "status": "pending",
  "created_at": "2025-01-02T10:15:00Z",
  "rows_uploaded": 100,
  "trace_type": "normal",
  "credits_per_lead": 1,
  "estimated_wait_seconds": 30
}