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
- 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.
- Add funds to your wallet. API orders are paid from your wallet balance.
- 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
| Request | What it does |
|---|---|
GET /services | Services, current price per record or lead, and lead generation categories. |
GET /wallet | Your wallet balance. |
POST /orders | Place an order, charged to your wallet straight away. Needs a key that can place orders. |
GET /orders | Your 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}/results | Download 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."] }
}
}
| HTTP | Code | Meaning |
|---|---|---|
| 401 | unauthenticated | Missing, wrong or revoked API key. |
| 402 | insufficient_balance | Your wallet doesn't cover the order. Nothing was charged. |
| 403 | forbidden | The key is read-only, or the account can't use the API. |
| 404 | not_found | No such order on your account, or results aren't ready yet. |
| 422 | validation_failed | See details for each field. |
| 429 | rate_limited | More than 60 requests in a minute. Wait and retry. |
| 500 | server_error | Our 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.