Developer Docs

Skip Tracing API Documentation

Build on Tracerfy's skip tracing platform. Secure, scalable REST API designed for high-volume property owner contact data retrieval workflows.

Base URL
https://tracerfy.com/v1/api/
Auth
Authorization: Bearer <TOKEN>
GET

Fetch all Queue

/v1/api/queues/
Description: Returns all queues for the authenticated user. Each queue represents a trace job created via API or the app. While a queue is pending, the serializer hides rows_uploaded and credits_deducted for API queues. When complete, download_url is populated with a public CSV link.

Headers

  • Authorization = Bearer <YOUR_TOKEN>

Example Request

curl -X GET 'https://tracerfy.com/v1/api/queues/' -H 'Authorization: Bearer '

Example Response 200

[
  {
    "id": 123,
    "created_at": "2025-01-01T12:00:00Z",
    "pending": false,
    "download_url": "https://tracerfy.nyc3.cdn.digitaloceanspaces.com/tracerfy/9a584124-77c2-4612-b8e9-f9efe6fbdc3d.csv",
    "rows_uploaded": 2500,
    "credits_deducted": 2500,
    "queue_type": "api",
    "trace_type": "normal",
    "credits_per_lead": 1
  },
  {
    "id": 124,
    "created_at": "2025-01-02T14:30:00Z",
    "pending": false,
    "download_url": "https://tracerfy.nyc3.cdn.digitaloceanspaces.com/tracerfy/abc123.csv",
    "rows_uploaded": 100,
    "credits_deducted": 1500,
    "queue_type": "api",
    "trace_type": "enhanced",
    "credits_per_lead": 15
  }
]
GET

Fetch Single Queue

/v1/api/queue/:id
Description: Returns the property records associated with a queue's posted addresses. Object-level permission enforced: only the queue owner can access. Null contact fields are normalized to empty strings in the response.

Response varies based on trace_type:
• Normal Trace (trace_type='normal'): Returns basic property contact data (phones, emails, mailing address)
• Enhanced Trace (trace_type='enhanced'): Returns comprehensive data including up to 8 relatives with contact info, 5 aliases, 5 past addresses, and 5 business affiliations

Headers

  • Authorization = Bearer <YOUR_TOKEN>

Parameters

Name
In
Type
Required
Description
:id
path
integer
Yes
Queue ID

Example Request

curl -X GET 'https://tracerfy.com/v1/api/queue/123' -H 'Authorization: Bearer '

Example Response 200

// Normal Trace Response (trace_type='normal')
[
  {
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "mail_address": "PO Box 111",
    "mail_city": "Austin",
    "mail_state": "TX",
    "first_name": "Jane",
    "last_name": "Doe",
    "primary_phone": "5125550100",
    "primary_phone_type": "Mobile",
    "email_1": "[email protected]",
    "email_2": "",
    "email_3": "",
    "email_4": "",
    "email_5": "",
    "mobile_1": "5125550100",
    "mobile_2": "",
    "mobile_3": "",
    "mobile_4": "",
    "mobile_5": "",
    "landline_1": "",
    "landline_2": "",
    "landline_3": ""
  }
]

// Enhanced Trace Response (trace_type='enhanced')
[
  {
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "mail_address": "PO Box 111",
    "mail_city": "Austin",
    "mail_state": "TX",
    "mail_zip": "78701",
    "first_name": "Jane",
    "last_name": "Doe",
    "primary_phone": "5125550100",
    "primary_phone_type": "Mobile",
    "age": "45",
    "email_1": "[email protected]",
    "email_2": "",
    "email_3": "",
    "email_4": "",
    "email_5": "",
    "mobile_1": "5125550100",
    "mobile_2": "",
    "mobile_3": "",
    "mobile_4": "",
    "mobile_5": "",
    "landline_1": "",
    "landline_2": "",
    "landline_3": "",
    "alias_1": "Jane Doe",
    "alias_2": "J Doe",
    "alias_3": "",
    "alias_4": "",
    "alias_5": "",
    "past_address_1": "456 Old St, Austin, TX 78702",
    "past_address_2": "",
    "past_address_3": "",
    "past_address_4": "",
    "past_address_5": "",
    "business_1": "Doe Consulting LLC",
    "business_2": "",
    "business_3": "",
    "business_4": "",
    "business_5": "",
    "relative_1_name": "John Doe",
    "relative_1_mobile_1": "5125550101",
    "relative_1_mobile_2": "",
    "relative_1_mobile_3": "",
    "relative_1_landline_1": "5125550102",
    "relative_1_landline_2": "",
    "relative_1_email_1": "[email protected]",
    "relative_1_email_2": "",
    "relative_1_email_3": "",
    "relative_2_name": "Mary Smith",
    "relative_2_mobile_1": "5125550103",
    "relative_2_mobile_2": "",
    "relative_2_mobile_3": "",
    "relative_2_landline_1": "",
    "relative_2_landline_2": "",
    "relative_2_email_1": "",
    "relative_2_email_2": "",
    "relative_2_email_3": "",
    "relative_3_name": "",
    "relative_3_mobile_1": "",
    "relative_3_mobile_2": "",
    "relative_3_mobile_3": "",
    "relative_3_landline_1": "",
    "relative_3_landline_2": "",
    "relative_3_email_1": "",
    "relative_3_email_2": "",
    "relative_3_email_3": "",
    "relative_4_name": "",
    "relative_4_mobile_1": "",
    "relative_4_mobile_2": "",
    "relative_4_mobile_3": "",
    "relative_4_landline_1": "",
    "relative_4_landline_2": "",
    "relative_4_email_1": "",
    "relative_4_email_2": "",
    "relative_4_email_3": "",
    "relative_5_name": "",
    "relative_5_mobile_1": "",
    "relative_5_mobile_2": "",
    "relative_5_mobile_3": "",
    "relative_5_landline_1": "",
    "relative_5_landline_2": "",
    "relative_5_email_1": "",
    "relative_5_email_2": "",
    "relative_5_email_3": "",
    "relative_6_name": "",
    "relative_6_mobile_1": "",
    "relative_6_mobile_2": "",
    "relative_6_mobile_3": "",
    "relative_6_landline_1": "",
    "relative_6_landline_2": "",
    "relative_6_email_1": "",
    "relative_6_email_2": "",
    "relative_6_email_3": "",
    "relative_7_name": "",
    "relative_7_mobile_1": "",
    "relative_7_mobile_2": "",
    "relative_7_mobile_3": "",
    "relative_7_landline_1": "",
    "relative_7_landline_2": "",
    "relative_7_email_1": "",
    "relative_7_email_2": "",
    "relative_7_email_3": "",
    "relative_8_name": "",
    "relative_8_mobile_1": "",
    "relative_8_mobile_2": "",
    "relative_8_mobile_3": "",
    "relative_8_landline_1": "",
    "relative_8_landline_2": "",
    "relative_8_email_1": "",
    "relative_8_email_2": "",
    "relative_8_email_3": ""
  }
]
GET

Analytics

/v1/api/analytics/
Description: Aggregated summary for your account: total_queues, properties_traced (sum of posted addresses per queue), queues_pending, queues_completed, and current credit balance.

Headers

  • Authorization = Bearer <YOUR_TOKEN>

Example Request

curl -X GET 'https://tracerfy.com/v1/api/analytics/' -H 'Authorization: Bearer '

Example Response 200

{
  "total_queues": 12,
  "properties_traced": 18350,
  "queues_pending": 2,
  "queues_completed": 10,
  "balance": 940
}
POST

Begin Trace

/v1/api/trace/
Description: Starts a trace job from CSV or JSON. Specify trace_type='normal' (1 credit/lead) or 'enhanced' (15 credits/lead). Cleans and de-duplicates rows, then enqueues processing. If credits are insufficient and no saved Stripe payment method exists, the request is rejected. Returns a queue_id immediately; results are delivered via download_url when complete.

⚠️ 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.

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 for property address
city_column
body
string
Yes
Column for property city
state_column
body
string
Yes
Column for property state
zip_column
body
string
No
Property ZIP (optional)
first_name_column
body
string
Yes
Owner first name
last_name_column
body
string
Yes
Owner last name
mail_address_column
body
string
Yes
Mailing address
mail_city_column
body
string
Yes
Mailing city
mail_state_column
body
string
Yes
Mailing state
mailing_zip_column
body
string
No
Mailing ZIP (optional)
trace_type
body
string
No
Trace type: 'normal' (1 credit/lead) or 'enhanced' (15 credits/lead). Defaults to 'normal'.
csv_file
form-data
file
Yes
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
}
POST

Trace Webhooks

Account.webhook_url
Description: When a skip trace queue completes, Tracerfy POSTs the result to the webhook URL configured in your account profile. This is per-user and dynamic; no registration endpoint is required.

Headers

  • Content-Type = application/json

Example Request

Tracerfy sends this JSON to your Account.webhook_url when a trace completes.

Example Response 200

{
  "id": 365,
  "created_at": "2025-07-13T18:55:02.962332Z",
  "pending": false,
  "download_url": "https://tracerfy.nyc3.cdn.digitaloceanspaces.com/tracerfy/9a584124-77c2-4612-b8e9-f9efe6fbdc3d.csv",
  "rows_uploaded": 12,
  "credits_deducted": 12,
  "queue_type": "api",
  "trace_type": "normal",
  "credits_per_lead": 1
}
POST

Start DNC Scrub

/v1/api/dnc/scrub/
Description: Submit a phone list for DNC (Do Not Call) scrubbing. Upload a CSV with one or more phone columns, or pass a JSON array of phone numbers directly. Each phone is checked against Federal DNC, State DNC, DMA, and TCPA Litigator databases. 1 credit per phone checked.

Input options (pick one):
• CSV with single column: csv_file + phone_column (string)
• CSV with multiple columns: csv_file + phone_columns (array) — phones are merged & deduplicated
• JSON phone list: phones array via application/json

Headers

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

Parameters

Name
In
Type
Required
Description
csv_file
form-data
file
Yes
CSV file containing phone numbers. Required for Options 1 & 2. Do not send with phones.
phone_column
body
string
Yes
Single column name containing phone numbers (Option 1). Internally normalized to phone_columns. Mutually exclusive with phone_columns.
phone_columns
body
array[string]
Yes
List of column names containing phone numbers (Option 2). Phones are merged & deduplicated. When multiple columns are used, labels are prefixed with the column name, e.g. '(Phone_1) John Doe'. Mutually exclusive with phone_column.
label_column
body
string
No
Single column to label each phone (e.g., name). Internally normalized to label_columns. Mutually exclusive with label_columns.
label_columns
body
array[string]
No
List of columns to combine as a label for each phone (e.g., ["address", "city", "state"]). Values are joined with commas. When using multiple phone_columns, labels are also prefixed with the column name.
phones
body
array[string]
Yes
Direct list of phone numbers via JSON body (Option 3). Do not send with csv_file.

Example Request

# Option 1: CSV with a single phone column
curl -X POST 'https://tracerfy.com/v1/api/dnc/scrub/' \
  -H 'Authorization: Bearer ' \
  -F 'csv_file=@/path/to/phones.csv' \
  -F 'phone_column=Phone' \
  -F 'label_column=Name'

# Option 1b: CSV with multiple label columns
curl -X POST 'https://tracerfy.com/v1/api/dnc/scrub/' \
  -H 'Authorization: Bearer ' \
  -F 'csv_file=@/path/to/phones.csv' \
  -F 'phone_column=Phone' \
  -F 'label_columns=["Address", "City", "State"]'

# Option 2: CSV with multiple phone columns
curl -X POST 'https://tracerfy.com/v1/api/dnc/scrub/' \
  -H 'Authorization: Bearer ' \
  -F 'csv_file=@/path/to/phones.csv' \
  -F 'phone_columns=["Phone_1", "Phone_2"]' \
  -F 'label_column=Name'

# Option 3: JSON phone list (no CSV)
curl -X POST 'https://tracerfy.com/v1/api/dnc/scrub/' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{"phones": ["5125550100", "5125550101", "5125550102"]}'

Example Response 200

{
  "message": "DNC scrub started",
  "dnc_queue_id": 5,
  "created_at": "2025-01-15T09:30:00Z",
  "status": "pending",
  "phones_to_check": 150,
  "credits_per_phone": 1
}
POST

DNC Scrub from Trace

/v1/api/dnc/scrub-from-queue/
Description: Extract phone numbers from a completed trace queue from your skip tracing results and submit them for DNC scrubbing. Optionally specify which phone columns to include. Phones are deduplicated across all selected columns. 1 credit per phone checked.

Valid phone_columns: primary_phone, mobile_1, mobile_2, mobile_3, mobile_4, mobile_5, landline_1, landline_2, landline_3
If phone_columns is omitted, all 9 phone fields are included by default.

Headers

  • Authorization = Bearer <YOUR_TOKEN>
  • Content-Type = application/json

Parameters

Name
In
Type
Required
Description
queue_id
body
integer
Yes
ID of a completed trace queue to extract phones from.
phone_columns
body
array[string]
No
List of phone field names to include. Defaults to all 9 phone fields.

Example Request

curl -X POST 'https://tracerfy.com/v1/api/dnc/scrub-from-queue/' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{"queue_id": 37360, "phone_columns": ["primary_phone", "mobile_1", "mobile_2"]}'

Example Response 200

{
  "message": "DNC scrub started",
  "dnc_queue_id": 8,
  "created_at": "2025-01-15T10:00:00Z",
  "source_queue_id": 37360,
  "status": "pending",
  "phones_to_check": 23,
  "phone_columns_used": [
    "primary_phone",
    "mobile_1",
    "mobile_2"
  ],
  "credits_per_phone": 1
}
GET

Fetch DNC Queue

/v1/api/dnc/queue/:id
Description: Retrieve the status and results of a DNC scrub job. When complete, two download URLs are provided: download_url (all phones with DNC flags) and clean_download_url (only phones with no DNC flags). CSV columns: phone, label, national_dnc, state_dnc, dma, litigator, phone_type, is_clean.

Note: While the queue is still pending, the fields phones_checked, phones_clean, and credits_deducted are omitted from the response. They appear once the scrub completes.

Headers

  • Authorization = Bearer <YOUR_TOKEN>

Parameters

Name
In
Type
Required
Description
:id
path
integer
Yes
DNC Queue ID

Example Request

curl -X GET 'https://tracerfy.com/v1/api/dnc/queue/5' -H 'Authorization: Bearer '

Example Response 200

{
  "id": 5,
  "created_at": "2025-01-15T09:30:00Z",
  "pending": false,
  "download_url": "https://tracerfy.nyc3.cdn.digitaloceanspaces.com/tracerfy/full-results.csv",
  "clean_download_url": "https://tracerfy.nyc3.cdn.digitaloceanspaces.com/tracerfy/clean-results.csv",
  "rows_uploaded": 150,
  "phones_checked": 150,
  "phones_clean": 112,
  "credits_deducted": 150,
  "source_type": "upload"
}
POST

DNC Webhooks

Account.webhook_url
Description: When a DNC scrub completes, Tracerfy POSTs the result to the webhook URL configured in your account profile. The payload includes a type: "dnc_scrub" field to distinguish it from trace webhooks, plus DNC-specific fields like clean_download_url, phones_checked, and phones_clean.

Headers

  • Content-Type = application/json

Example Request

Tracerfy sends this JSON to your Account.webhook_url when a DNC scrub completes.

Example Response 200

{
  "id": 5,
  "type": "dnc_scrub",
  "created_at": "2025-01-15T09:30:00Z",
  "pending": false,
  "download_url": "https://tracerfy.nyc3.cdn.digitaloceanspaces.com/tracerfy/full-results.csv",
  "clean_download_url": "https://tracerfy.nyc3.cdn.digitaloceanspaces.com/tracerfy/clean-results.csv",
  "rows_uploaded": 150,
  "phones_checked": 150,
  "phones_clean": 112,
  "credits_deducted": 150,
  "source_type": "upload"
}