Skip to content

Skipmatch API documentation

The Skipmatch API lets your own software upload a property-owner CSV, get one price for the whole list, place the order and download the finished file. Every call is JSON over HTTPS with a bearer key, and every order is paid from prepaid credit, never a card.

Key facts

Price
a flat $0.03 a record at any list size from 50 to 100,000 records.
Unit
Priced per matched record.
Minimum order
50 records
Minimum charge
Minimum charge $0.50 when any record matches.
Single search
Single search: $0.10, charged only on a match, paid from prepaid credit ($10 minimum top-up).
Prepaid credit
Prepaid credit expires 12 months after your last credit purchase, single search or credit-paid list, and unused credit is refundable on request within 90 days of purchase.
Credit packs
As low as 2.4¢ a hit with prepaid credit. With the bonus, bulk hits paid from credit work out to 2.86¢ ($50), 2.73¢ ($100), 2.61¢ ($250), 2.5¢ ($500), 2.4¢ ($1,000) a hit.
Free tool
Check your list free at /tools/skip-trace-csv-checker. Check columns, split addresses and download a fixed CSV in your browser before tracing at $0.03 a record. No account needed.
Subscription
None. A list order is paid for on its own by card or prepaid credit.
Max per order
100,000 rows or 50 MB per file
Output
Up to 10 phones per owner, each with its line type (mobile, landline or VoIP), plus emails where found
Sources
3 core providers: idiCORE, Enformion and Delvepoint
Data grade
Investigator-grade data at small-business prices. The same class of databases private investigators license, self-serve with no investigator license: $0.03 a record, no subscription.
Not for
FCRA uses: credit, insurance, employment or tenant screening
Prices last changed
Last updated

Basics

The base URL is https://skipmatch.com/api/v1. Amounts are whole US cents, timestamps are UTC, and request bodies are JSON sent with Content-Type: application/json (up to 64 KiB). Responses are never cached and carry an X-Request-Id header; quote it when you write to support. A body with a field the route does not define is rejected. The machine-readable description is openapi.json (OpenAPI 3.1).

Authentication and scopes

Send Authorization: Bearer <key>. Keys are created in Settings by a signed-in person; the secret is shown once. A key carries scopes, a required daily spending cap and an expiry, and revoking it blocks new calls at once.

Scopes
ScopeAllows
uploads:writeCreate, complete and read uploads
quotes:writeCreate quotes
orders:writePlace list orders
searches:writePlace single searches
orders:readRead and list orders
results:readGet result download links
credit:readRead the credit balance

Endpoints

Paths are relative to the base URL. Reading an upload uses the same scope as writing one.

API endpoints
MethodPathScopeWhat it does
POST/uploadsuploads:writeStart a CSV upload; returns a signed address for the bytes
POST/uploads/{upload_id}/completeuploads:writeFinish the upload and set the column mapping
GET/uploads/{upload_id}uploads:writeRead the validation state of an upload
POST/quotesquotes:writeFreeze the price for a ready upload
POST/ordersorders:writeOrder a quoted list
POST/searchessearches:writeSearch one owner
GET/ordersorders:readList orders, newest first
GET/orders/{order_id}orders:readRead one order
GET/orders/{order_id}/downloadresults:readGet a short-lived download link
GET/creditcredit:readRead the prepaid credit balance

From CSV to results

A list order is six steps: start the upload, send the bytes, complete it with a column mapping, wait for validation, quote and order. Lists run from 50 to 100,000 records and up to 50 MB. Start with the upload:

curl -X POST https://skipmatch.com/api/v1/uploads \
  -H "Authorization: Bearer $SKIPMATCH_KEY" \
  -H "Idempotency-Key: upload-2026-10-23-001" \
  -H "Content-Type: application/json" \
  -d '{"filename":"owners.csv","bytes":183422}'

# 201
{
  "upload_id": "4f0c1c58-5d4b-4a43-9d57-0c4a9c3b5f11",
  "status": "awaiting_upload",
  "expires_at": "2026-10-24T17:04:11Z",
  "upload_url": "https://...",
  "upload_token": "...",
  "max_bytes": 52428800
}

Send the CSV bytes to upload_url with an HTTP PUT. The address works once and expires, so treat it as a secret. The rest of the flow:

# 1. Send the CSV bytes to upload_url (HTTP PUT)
# 2. Complete the upload with your column mapping
curl -X POST https://skipmatch.com/api/v1/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $SKIPMATCH_KEY" \
  -H "Idempotency-Key: complete-001" \
  -H "Content-Type: application/json" \
  -d '{"mapping":{"FirstName":"First Name","LastName":"Last Name",
        "MailingAddress":"Mail Addr","MailingCity":"Mail City",
        "MailingState":"Mail ST","MailingZip":"Mail Zip"}}'

# 3. Poll GET /uploads/$UPLOAD_ID until status is "ready"
# 4. Price it
curl -X POST https://skipmatch.com/api/v1/quotes \
  -H "Authorization: Bearer $SKIPMATCH_KEY" \
  -H "Idempotency-Key: quote-001" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"'$UPLOAD_ID'"}'

# 5. Order it, using the quote_id from step 4
curl -X POST https://skipmatch.com/api/v1/orders \
  -H "Authorization: Bearer $SKIPMATCH_KEY" \
  -H "Idempotency-Key: order-001" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"'$QUOTE_ID'"}'

# 6. Poll GET /orders/$ORDER_ID until status is "delivered", then
#    GET /orders/$ORDER_ID/download

For one owner, POST /searches takes a record keyed by FirstName, LastName, MailingAddress, MailingCity, MailingState, MailingZip (and the matching Property fields) and a max_charge_cents ceiling. It returns the same response as an order.

Orders move through queued and processing to delivered, or to failed. The download link lasts 300 seconds; ask again for a new one.

Idempotency and retries

Every POST requires an Idempotency-Key header: 1 to 200 visible ASCII characters, no commas. Repeat a timed-out request with the same key and body and you get the original result. A different body under the same key fails with 409 idempotency_conflict. Retry a 503 with the same key; wait Retry-After seconds after a 429.

Requests are limited per minute: 300 per IP address, 60 per key and 120 per account. An account can have up to 50 uploads waiting at once. Extra orders are never refused; they wait in line and run in order.

Placing an order reserves its maximum charge from prepaid credit, and what is not used is released when it finishes. See pricing for how lists are priced; the quote returns the price for yours.

AI assistants (MCP)

Assistants that support the Model Context Protocol can use the same API through https://skipmatch.com/mcp with your key as a bearer token, or through the link https://skipmatch.com/mcp/<your key> for assistants that only take a URL. The link carries the key, so keep it as private as the key; a separate key with a low daily cap is a good idea.

It offers credit balance, single search, list orders, order status, download results, list quote and place order. A list quote never spends credit; placing the order is a separate step. Scopes, the daily cap and rate limits are the key's own, and revoking the key turns the connector off.

Errors

Every failure uses one shape, and the code is stable:

HTTP/1.1 402 Payment Required
X-Request-Id: 0d0c9e1e-9f6a-4a53-a4a1-2f6a3c7b9d10
Cache-Control: no-store

{
  "error": {
    "code": "insufficient_credit",
    "message": "The account has insufficient prepaid credit.",
    "request_id": "0d0c9e1e-9f6a-4a53-a4a1-2f6a3c7b9d10"
  }
}
Error codes
CodeStatusMeaning
invalid_request400The request is malformed, has an unknown field, is not Content-Type: application/json or is missing Idempotency-Key
invalid_key401The key is missing, malformed, revoked or expired
insufficient_credit402The prepaid credit does not cover the reservation
insufficient_scope403The key lacks the scope the route needs
attestation_required403The account has not accepted the permissible-use terms
daily_spend_limit403The key's daily spending cap would be exceeded
not_found404No such route or resource, including another account's resources
idempotency_conflict409The Idempotency-Key was already used with a different request
upload_not_ready409The upload is not validated yet, or has expired
quote_expired409The quote lapsed; request a new one
quote_changed409The price moved since the quote
quote_consumed409The quote already became an order
result_not_ready409The order has no delivered file yet
upload_too_large413The file or request body exceeds its size limit
invalid_csv422The CSV could not be validated (reported as an upload's error_code)
invalid_mapping422The column mapping is not valid
row_count_mismatch422The validated record count changed (reserved; not returned today)
content_changed422The uploaded content changed after validation (reserved; not returned today)
rate_limited429Too many requests in a minute, or 50 uploads already pending; wait for Retry-After seconds. Extra orders are never refused: they wait in line and run in order
api_disabled503The API is switched off
temporarily_unavailable503A transient failure; retry with the same Idempotency-Key

Questions

Is the Skipmatch API generally available?

Yes. Access is turned on per account: write to support@skipmatch.com from your account's email and we will enable it. Then create a key in Settings.

How do I get an API key?

Keys are created in Settings by a signed-in person, never through the API itself. The secret is shown once, so store it when it appears. Each key has scopes, a required daily spending cap and an expiry, and can be revoked at any time.

What does Idempotency-Key do?

Every POST needs one. If a request times out, repeat it with the same key and the same body and you get the original result instead of a second upload, quote or order. The same key with a different body fails with 409 idempotency_conflict.

Can an API order charge a card?

No. API orders are paid only from prepaid credit. The full maximum is reserved when the order is placed, and whatever is not used is released when it finishes. If the credit does not cover the reservation the call fails with 402 insufficient_credit.

Is there a machine-readable description?

Yes. The OpenAPI 3.1 document is at https://skipmatch.com/openapi.json and covers every route, scope and error code on this page.

Price your list before you pay for it.

Create an account, upload the file, and see your total before you pay. Records with no phone and no email are never charged.

Price your list