Skiptrace API Release Notes - November 2025

Release Date: November 18, 2025

Affected Endpoints: All Skiptrace API endpoints (V1 and V3 - both sync and async)

Overview

This release introduces two important enhancements to the Skiptrace API that improve data quality and user experience:

Geographic Validation: Non-US property addresses will not be skipped trace and will immediately return no match
Mobile Phone Prioritization: Mobile phone numbers are automatically prioritized in the response

1. Geographic Validation for US-Only Skip Tracing

What Changed

The Skiptrace API now validates that property addresses are located within the United States before processing skip trace requests. Addresses outside the US will be returned as not matched and will not be billed.

Customer Impact

Before:

Non-US addresses were processed but returned unreliable or no results

After:

Non-US addresses are immediately identified and returned as not matched
No API credits are consumed for invalid geographic requests
Batch requests with mixed US/non-US addresses will:
- Process all valid US addresses normally
- Return no match for non-US addresses in the response metadata

Response Behavior

Single Request with Non-US Address (V1 API):

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "results": {
    "persons": [
      {
        "propertyAddress": {
          "street": "145 Adelaide St W",
          "city": "Toronto",
          "state": "ON",
          "zip": "M5H 4"
        },
        "meta": {
          "matched": false,
          "error": false
        }
      }
    ]
  }
}

Single Request with Non-US Address (V3 API):

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "result": {
    "data": [
      {
        "input": {
          "propertyAddress": {
            "street": "145 Adelaide St W",
            "city": "Toronto",
            "state": "ON",
            "zip": "M5H 4"
          }
        },
        "persons": [],
        "meta": {
          "matched": false,
          "error": false
        }
      }
    ]
  }
}

Batch Request with Mixed Addresses:

US addresses: Processed normally and return skip trace results
Non-US addresses: Returned as not matched by meta.matched=false
Billing: Only matched US properties are counted as billable requests

What You Should Do

Update validation logic: If your application submits international addresses, implement client-side validation to filter non-US addresses before making API requests
Handle errors gracefully: Update error handling to catch and display geographic validation errors to end users
Check batch results: When processing batch requests, check the meta.matched field for each result to identify which addresses were outside the US or not matched

2. Mobile Phone Prioritization

What Changed

Phone numbers in skip trace responses are now automatically sorted to prioritize mobile phones over landline phones. This improves contact success rates by surfacing the most effective contact methods first.

Customer Impact

Before:

Phone numbers were returned in ranked order
Mobile phones could appear anywhere in the phone array
Users needed to manually filter or sort phones to find mobile numbers

After:

Mobile phone numbers automatically appear at the beginning of the phone array
Within each phone type (mobile/landline), phones are sorted by rank (highest first)
Contact workflows can immediately use the first phone numbers with higher success rates

Sorting Algorithm

The phone array is sorted as follows:

All mobile phones (sorted by rank, descending)
All landline phones (sorted by rank, descending)

Example Response:

{
  "phoneNumbers": [
    {
      "number": "5551234567",
      "type": "Mobile",
      "carrier": "T-Mobile",
      "rank": 100,
      "tested": true,
      "reachable": true
    },
    {
      "number": "5559876543",
      "type": "Mobile",
      "carrier": "Verizon",
      "rank": 95,
      "tested": true,
      "reachable": true
    },
    {
      "number": "5551112222",
      "type": "Land Line",
      "carrier": "AT&T",
      "rank": 90,
      "tested": false,
      "reachable": false
    }
  ]
}

Request Option: `prioritizeMobilePhones`

A new request option has been added to control this behavior:

Option Name: prioritizeMobilePhones

Type: Boolean

Default: true

Available In: All Skiptrace API versions (V1 and V3)

Usage:

{
  "requests": [
    {
      "propertyAddress": {
        "street": "123 Main St",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001"
      }
    }
  ],
  "options": {
    "prioritizeMobilePhones": true
  }
}

When to Disable:

Set to false if you have specific business logic that requires original phone ordering
Useful for A/B testing contact strategies
Can be controlled on a per-request basis

What You Should Do

Update phone selection logic: If your application selects phones from the array, you can now rely on the first phone numbers being mobile (when available)
Review contact workflows: Consider updating dialing/texting workflows to take advantage of the mobile-first ordering
Test integrations: Verify that your existing phone processing logic works correctly with the new ordering
Keep prioritizeMobilePhones default: Unless you have a specific reason to change it, keep the default value of true for optimal contact rates

Frequently Asked Questions

Geographic Validation

Q: Will I be charged for non-US address requests? A: No. Non-US addresses returned as not matched and do not count as billable requests.

Q: What if I'm not sure if an address is in the US? A: You can submit the request and check the meta.matched field in the response. If the address is outside the US, the API will return the meta data without charging your account.

Q: Can I skip trace Canadian or Mexican properties? A: No. Skip trace services are currently only available for properties located within the United States.

Q: What about US territories like Puerto Rico or Guam? A: US territories are supported. Only addresses completely outside US jurisdiction will return errors.

Mobile Phone Prioritization

Q: Will this change affect my existing integrations? A: The phone array structure remains the same. Only the order of phones within the array has changed. If your code simply iterates through the array, it will automatically benefit from mobile-first ordering.

Q: What if there are no mobile phones for a property? A: The API will return all available phone numbers (landlines only) in order of rank, exactly as before.

Q: Can I get the old phone ordering back? A: Yes, set "prioritizeMobilePhones": false in your request options to receive phones in their original order.

Q: Does this affect the phone rank scores? A: No. Rank scores are calculated independently and remain unchanged. The sorting only reorders how phones are presented in the response.

Q: Will mobile phones always have higher ranks than landlines? A: Not necessarily. Rank is based on data quality indicators independent of phone type. Mobile phones simply appear first in the array, then landlines, each group sorted by their respective ranks.

Migration Checklist

Use this checklist to ensure your integration is ready for these changes:

Geographic Validation

[ ] Added client-side validation to filter non-US addresses (optional but recommended)
[ ] Updated error handling to catch geographic validation errors
[ ] Modified batch processing logic to check meta.matched for each result
[ ] Updated user-facing error messages to explain US-only limitation

Mobile Phone Prioritization

[ ] Reviewed phone selection logic in your application
[ ] Tested that phone array iteration still works correctly
[ ] Considered updating contact workflows to leverage mobile-first ordering
[ ] Documented whether you're using the default prioritizeMobilePhones: true behavior