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. Supports trace_type='normal' (1 credit/lead), 'advanced' (2 credits/lead), and 'enhanced' (15 credits/lead). Enhanced targets a supplied person and requires first and last name columns with the associated address. 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 but recommended.
first_name_column
body
string
No
Person first-name column. Required for normal, custom, and enhanced traces. Not used by advanced owner lookup.
last_name_column
body
string
No
Person last-name column. Required for normal, custom, and enhanced traces. Not used by advanced owner lookup.
mail_address_column
body
string
No
Mailing address column. Required for normal traces; optional for advanced/enhanced traces.
mail_city_column
body
string
No
Mailing city column. Required for normal traces; optional for advanced/enhanced traces.
mail_state_column
body
string
No
Mailing state column. Required for normal traces; optional for advanced/enhanced traces.
mailing_zip_column
body
string
No
Column for mailing ZIP. Optional.
trace_type
body
string
No
Trace type: 'normal' (1 credit/lead), 'advanced' (2 credits/lead), or 'enhanced' (15 credits/lead). Defaults to 'normal'. Advanced discovers the owner from an address; Enhanced requires first and last name columns.
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
}