Download OpenAPI file

Partner API

Place skip tracing and lead generation orders from your own software, check their status, download results, and get told when an order is delivered.

Getting started

  1. Log in, open API in the menu and create a key. Choose "Can place orders" if the key will place orders. Copy the key: it's shown once.
  2. Add funds to your wallet. API orders are paid from your wallet balance.
  3. Send the key with every request:
curl https://services.usskiptracing.com/api/v1/wallet \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Base URL: https://services.usskiptracing.com/api/v1. Up to 60 requests a minute per key. Money is always a string in US dollars, like "45.00".

Endpoints

RequestWhat it does
GET /servicesServices, current price per record or lead, and lead generation categories.
GET /walletYour wallet balance.
POST /ordersPlace an order, charged to your wallet straight away. Needs a key that can place orders.
GET /ordersYour orders, newest first, 25 per page. Filter with ?status=in_progress, delivered, cancelled.
GET /orders/{number}One order: status, records matched, amount and refund.
GET /orders/{number}/resultsDownload the results file once the order is delivered.

Place a skip tracing order

curl https://services.usskiptracing.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: my-order-1001" \
  -F service_type=deep_skip_tracing \
  -F total_leads=250 \
  -F file=@list.csv

The file can be CSV, XLSX or JSON, up to 20 MB. A JSON file is a list of records, for example [{"first_name": "Jane", "last_name": "Doe", "property_address": "1 Main St, Austin, TX 78701"}].

Place a lead generation order

curl https://services.usskiptracing.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-order-1002" \
  -d '{"service_type":"lead_generation","total_leads":500,"lead_gen_categories":["probate","vacant"],"lead_area":"Cook County, IL"}'

lead_area is required for lead generation orders: where the leads should come from (city, county, state or ZIP codes). If lead_gen_categories includes other, also send lead_type_other describing the leads you want. GET /services lists every lead type.

The Idempotency-Key header is optional but recommended: if your request times out and you send it again with the same key, you get the first order back (HTTP 200) instead of a second order and a second charge.

An order

{
  "data": {
    "order_number": "USSDCOMX4G",
    "service_type": "deep_skip_tracing",
    "status": "delivered",
    "total_records": 250,
    "matched_records": 231,
    "amount": "4.75",
    "refunded": "0.36",
    "placed_at": "2026-10-31T17:06:07+00:00",
    "delivered_at": "2026-11-01T09:12:44+00:00",
    "results_url": "https://services.usskiptracing.com/api/v1/orders/USSDCOMX4G/results"
  }
}

Statuses: in_progress (paid, being worked on), delivered, cancelled. Unmatched records are refunded to your wallet automatically on delivery (refunded).

Errors

Every error has the same shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are missing or invalid.",
    "details": { "total_leads": ["The total leads field is required."] }
  }
}
HTTPCodeMeaning
401unauthenticatedMissing, wrong or revoked API key.
402insufficient_balanceYour wallet doesn't cover the order. Nothing was charged.
403forbiddenThe key is read-only, or the account can't use the API.
404not_foundNo such order on your account, or results aren't ready yet.
422validation_failedSee details for each field.
429rate_limitedMore than 60 requests in a minute. Wait and retry.
500server_errorOur side. Safe to retry with the same Idempotency-Key.

Webhooks

Set your webhook URL under API → Automatic updates (https only); the customer sees it as the "address to notify". We POST JSON to it when one of your orders is order.delivered or order.cancelled, order.results_updated when we replace an order's results file (download it again; results_id changes), wallet.low when your balance drops below the alert amount you set, and a ping when they press "Send a test update". The signing secret is shown there as the "security code".

{
  "id": "evt_01JBXYZ…",
  "type": "order.delivered",
  "created_at": "2026-11-01T09:12:45+00:00",
  "data": { …the same order fields as the API… }
}

Reply with any 2xx status within 5 seconds. Anything else is retried after 10 seconds, 1 minute, 5 minutes, 30 minutes and 2 hours, so the same id can arrive more than once.

Check the signature

Each request has a USST-Signature header: t=<unix time>,v1=<signature>. The signature is the hex HMAC-SHA256 of <t>.<raw request body> using your signing secret. Reject requests whose signature doesn't match or whose time is more than 5 minutes old.

// PHP
[$t, $v1] = sscanf($_SERVER['HTTP_USST_SIGNATURE'], 't=%d,v1=%s');
$body = file_get_contents('php://input');
$valid = hash_equals(hash_hmac('sha256', $t.'.'.$body, $secret), $v1) && abs(time() - $t) < 300;

// Node.js
const [, t, v1] = req.headers['usst-signature'].match(/t=(\d+),v1=([0-9a-f]+)/);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - t) < 300;

Questions? Contact our support team from your dashboard.