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.
| Scope | Allows |
|---|---|
| uploads:write | Create, complete and read uploads |
| quotes:write | Create quotes |
| orders:write | Place list orders |
| searches:write | Place single searches |
| orders:read | Read and list orders |
| results:read | Get result download links |
| credit:read | Read the credit balance |
Endpoints
Paths are relative to the base URL. Reading an upload uses the same scope as writing one.
| Method | Path | Scope | What it does |
|---|---|---|---|
| POST | /uploads | uploads:write | Start a CSV upload; returns a signed address for the bytes |
| POST | /uploads/{upload_id}/complete | uploads:write | Finish the upload and set the column mapping |
| GET | /uploads/{upload_id} | uploads:write | Read the validation state of an upload |
| POST | /quotes | quotes:write | Freeze the price for a ready upload |
| POST | /orders | orders:write | Order a quoted list |
| POST | /searches | searches:write | Search one owner |
| GET | /orders | orders:read | List orders, newest first |
| GET | /orders/{order_id} | orders:read | Read one order |
| GET | /orders/{order_id}/download | results:read | Get a short-lived download link |
| GET | /credit | credit:read | Read 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/downloadFor 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"
}
}| Code | Status | Meaning |
|---|---|---|
| invalid_request | 400 | The request is malformed, has an unknown field, is not Content-Type: application/json or is missing Idempotency-Key |
| invalid_key | 401 | The key is missing, malformed, revoked or expired |
| insufficient_credit | 402 | The prepaid credit does not cover the reservation |
| insufficient_scope | 403 | The key lacks the scope the route needs |
| attestation_required | 403 | The account has not accepted the permissible-use terms |
| daily_spend_limit | 403 | The key's daily spending cap would be exceeded |
| not_found | 404 | No such route or resource, including another account's resources |
| idempotency_conflict | 409 | The Idempotency-Key was already used with a different request |
| upload_not_ready | 409 | The upload is not validated yet, or has expired |
| quote_expired | 409 | The quote lapsed; request a new one |
| quote_changed | 409 | The price moved since the quote |
| quote_consumed | 409 | The quote already became an order |
| result_not_ready | 409 | The order has no delivered file yet |
| upload_too_large | 413 | The file or request body exceeds its size limit |
| invalid_csv | 422 | The CSV could not be validated (reported as an upload's error_code) |
| invalid_mapping | 422 | The column mapping is not valid |
| row_count_mismatch | 422 | The validated record count changed (reserved; not returned today) |
| content_changed | 422 | The uploaded content changed after validation (reserved; not returned today) |
| rate_limited | 429 | Too 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_disabled | 503 | The API is switched off |
| temporarily_unavailable | 503 | A transient failure; retry with the same Idempotency-Key |
Questions
Is the Skipmatch API generally available?
How do I get an API key?
What does Idempotency-Key do?
Can an API order charge a card?
Is there a machine-readable description?
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.