Skip trace in
one command.

The DataSkip CLI ships in the official npm package skiptrace (Node 18+, Apache-2.0). Create an API key in the dashboard (Settings → API), save it once, then trace addresses straight from your shell. Exit codes are script-friendly: 0 match, 1 miss, 2 usage error, 3 API error.

$ skiptrace config set-key pc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

$ skiptrace "123 Example St, Phoenix AZ 85001"

$ skiptrace lookup "44 Pine St" --city Bridgewater --state MA --zip 02324

$ skiptrace "123 Main St, Austin TX 78701" --json | jq '.phones'

The skiptrace package imports as a typed library. The API key falls back to the SKIPTRACE_API_KEY env var, then the saved CLI config, so new SkipTrace() with no arguments just works. It also ships skipBulk for up to 100 addresses in one call.

import { SkipTrace, ApiError } from 'skiptrace';

const st = new SkipTrace({ apiKey: process.env.SKIPTRACE_API_KEY });

try {
  const result = await st.skip('123 Example St, Phoenix AZ 85001');
  if (result.found) {
    console.log(result.contact.fullName, result.phones, result.emails);
  }
} catch (err) {
  if (err instanceof ApiError && err.status === 402) {
    // insufficient balance
  }
}

One endpoint, any language, with your API key as a Bearer token. A hit charges 4¢ and returns the full contact; a miss returns found: false and charges nothing.

$ curl -X POST https://app.dataskip.io/api/v1/skip-trace \
    -H "Authorization: Bearer pc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "address": "44 Pine St",
      "city": "Bridgewater",
      "state": "MA",
      "zip": "02324"
    }'

{
  "success": true,
  "found": true,
  "charged": 4,
  "contact": {
    "firstName": "J•••",
    "lastName": "C•••••",
    "fullName": "J••• C•••••",
    "propertyAddress": "44 Pine St",
    "propertyCity": "Bridgewater",
    "propertyState": "MA",
    "propertyZip": "02324",
    "mailingAddress": "44 Pine St",
    "mailingCity": "Bridgewater",
    "mailingState": "MA",
    "mailingZip": "02324"
  },
  "phones": [
    { "number": "(•••) •••-0182", "type": "mobile", "dnc": false },
    { "number": "(•••) •••-4415", "type": "landline", "dnc": true }
  ],
  "emails": ["j•••••@•••••.com"]
}

Skip trace up to 100 addresses in one API call, or a whole CSV in one job (never loop the single-lookup endpoint, which is limited to 500 lookups per minute per account). Either way you only pay for hits: misses are refunded automatically, even in bulk. The CSV pipeline handles bigger lists, up to 250,000 records, and previews the matched count and exact cost before anything is charged.

POST https://app.dataskip.io/api/v1/skip-trace-bulk

{
  "addresses": [
    { "address": "123 Sample Ave", "city": "Anytown", "state": "CA", "zip": "90210" },
    { "address": "456 Demo Blvd", "zip": "90211" }
  ]
}

{
  "success": true,
  "total": 2,
  "matched": 1,
  "totalCharged": 4,
  "results": [
    { "found": true, "charged": 4, "contact": { "fullName": "J••• C•••••" }, "phones": ["..."], "emails": ["..."] },
    { "found": false, "charged": 0, "contact": null, "phones": [], "emails": [] }
  ]
}

Up to 100 entries per request; only the address field is required per entry, and results come back in request order with the same shape as a single lookup. Billing matches single lookups: 4¢ per match, misses free. The worst case (every entry matching) is charged up front, a 402 with balanceRequired means the balance cannot cover the batch, and non-matches are refunded automatically when the request completes, so the net charge is always matches only. Rate limit: 250 bulk requests per minute per account, and 429 responses carry a Retry-After header.

await st.skipBulk(['123 Example St, Phoenix AZ 85001', { address: '44 Pine St', city: 'Bridgewater', state: 'MA', zip: '02324' }]);

In the SDK, skipBulk is on the client and as a one-shot export, fully typed (BulkLookupResponse). Free-form strings and structured objects mix in the same array.

For bigger lists, the CSV job pipeline takes one file of up to 250,000 addresses. Jobs created through the API also appear in the dashboard, and skiptrace bulk in the CLI runs this same pipeline.

$ curl -X POST https://app.dataskip.io/api/user/skip-trace \
    -H "Authorization: Bearer pc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "filename": "leads.csv",
      "columnMapping": { "address": "Property Address", "city": "City", "state": "State", "zip": "Zip" }
    }'

1. Create a job with POST /api/user/skip-trace and your CSV's column mapping (the address, city, state, and ZIP columns must all be mapped; owner first and last name columns are optional). The response returns a jobId and an uploadUrl.
2. Upload the raw CSV. Presigned uploads PUT the file to uploadUrl with Content-Type: text/csv and then call the uploaded endpoint; direct uploads POST the file as multipart form data.
3. Poll the job until its status is preview. The preview reports total rows, matched rows, and the total charge in cents.
4. Confirm to run the charge, or cancel free of charge. Only matched rows are billed, at 4¢ each; a 402 response means the balance cannot cover the job.
5. Poll until completed, then fetch the enriched CSV from downloadUrl. Matched rows gain owner names, phones, and emails; unmatched rows come back unchanged.

Job statuses: pending · uploaded · processing · preview · confirmed · generating · completed · failed · cancelled. A job never charges before the preview is confirmed.

Every error response from the DataSkip API is JSON with an error string that names the problem, and on 400 the invalid field. A 402 adds balanceRequired (the cents needed to run the request); a CSV job confirm can add dailyMissLimit when the account is over its daily unmatched-list cap. A miss is not an error: it is HTTP 200 with found: false.

{ "error": "Insufficient balance", "balanceRequired": 4 }

Always call the documented method: the lookup endpoints are POST only, and an unsupported method or an unknown path returns the app's own 405 or 404 page rather than an API error body, so check the path and method against openapi.json before calling.

A 429 carries a Retry-After header in seconds: wait that long, then retry. Never loop the single-lookup endpoint over a list; the bulk endpoint takes 100 addresses per call and the CSV pipeline takes 250,000 per job.

The DataSkip API is versioned in the URL path: /api/v1 is the current stable version, and openapi.json describes it. Backward-compatible changes (new endpoints, new optional request fields, new response fields) ship in place without a version change, so clients should ignore fields they do not recognize. Breaking changes ship as a new path version and never change how v1 behaves.

When a version or endpoint is scheduled for retirement, DataSkip announces it at least 6 months before the retirement date. During that notice period every response from the affected version carries a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the retirement date, plus a Link with rel="deprecation" pointing at the announcement. The same dates are published on this page, in developers.md, and in llms.txt. Nothing is deprecated today.