openapi: 3.1.0 info: title: US SkipTracing Partner API version: "1.0" description: | Place skip tracing and lead generation orders, check their status and download results. Create an API key on the API page (in the menu after logging in) and send it as `Authorization: Bearer `. Orders are paid from your wallet balance. Every error has the same shape (see `Error`). Limit: 60 requests a minute per key. servers: - url: /api/v1 description: The customer site this file was downloaded from security: - apiKey: [] paths: /services: get: summary: Services, prices and lead categories responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: { $ref: "#/components/schemas/Service" } default: { $ref: "#/components/responses/Error" } /wallet: get: summary: Wallet balance responses: "200": description: OK content: application/json: schema: type: object properties: data: type: object properties: balance: { type: string, example: "120.50" } currency: { type: string, example: USD } default: { $ref: "#/components/responses/Error" } /orders: get: summary: List your orders, newest first parameters: - name: status in: query schema: { type: string, enum: [awaiting_payment, in_progress, delivered, cancelled] } - name: page in: query schema: { type: integer, minimum: 1 } responses: "200": description: 25 orders per page, with `links` and `meta` for paging. content: application/json: schema: type: object properties: data: type: array items: { $ref: "#/components/schemas/Order" } links: { type: object } meta: { type: object } default: { $ref: "#/components/responses/Error" } post: summary: Place an order, paid from your wallet description: Needs a key with "Can place orders". Send `Idempotency-Key` so a retried request returns the first order instead of placing another. parameters: - name: Idempotency-Key in: header schema: { type: string, maxLength: 100 } requestBody: required: true content: multipart/form-data: schema: { $ref: "#/components/schemas/NewOrder" } application/json: schema: { $ref: "#/components/schemas/NewOrder" } responses: "201": description: Order placed and charged. content: application/json: schema: type: object properties: data: { $ref: "#/components/schemas/Order" } "200": description: Same Idempotency-Key as an earlier request; that order is returned and nothing is charged. content: application/json: schema: type: object properties: data: { $ref: "#/components/schemas/Order" } "402": { $ref: "#/components/responses/Error" } default: { $ref: "#/components/responses/Error" } /orders/{orderNumber}: get: summary: One order parameters: - $ref: "#/components/parameters/OrderNumber" responses: "200": description: OK content: application/json: schema: type: object properties: data: { $ref: "#/components/schemas/Order" } default: { $ref: "#/components/responses/Error" } /orders/{orderNumber}/results: get: summary: Download the results file parameters: - $ref: "#/components/parameters/OrderNumber" responses: "200": description: The results file (CSV or XLSX). content: application/octet-stream: schema: { type: string, format: binary } default: { $ref: "#/components/responses/Error" } /updates/latest: get: summary: Latest white-label site release description: Used by US SkipTracing white-label sites. Also records the calling site's version and address. Releases are signed; sites verify `signature` over `manifest` with the built-in public key. parameters: - { name: version, in: query, required: false, schema: { type: string, example: "1.0.0" } } - { name: site, in: query, required: false, schema: { type: string, format: uri } } responses: "200": description: The newest active release, or `data` null when there is none. content: application/json: schema: type: object properties: data: nullable: true type: object properties: version: { type: string } notes: { type: string, nullable: true } is_security: { type: boolean } min_supported_version: { type: string, nullable: true } released_at: { type: string, format: date-time } manifest: { type: string, description: "Signed JSON with version, sha256 and size of the zip" } signature: { type: string, description: "Base64 Ed25519 signature of manifest" } download_url: { type: string, format: uri } default: { $ref: "#/components/responses/Error" } /updates/{version}/download: get: summary: Download a white-label release (zip) parameters: - { name: version, in: path, required: true, schema: { type: string, example: "1.0.1" } } responses: "200": description: The release zip. content: application/zip: schema: { type: string, format: binary } default: { $ref: "#/components/responses/Error" } webhooks: orderEvent: post: summary: Order delivered or cancelled description: | Sent to the address set under API → Automatic updates for `order.delivered` and `order.cancelled` (and `ping` from "Send a test update"). The signing secret is shown there as the "security code". Check the `USST-Signature` header: `t=,v1=." using your signing secret>`. Answer with any 2xx status. Other answers and timeouts (5 seconds) are retried after 10 s, 1 min, 5 min, 30 min and 2 h. parameters: - name: USST-Signature in: header required: true schema: { type: string, example: "t=1793465000,v1=5f2b…" } requestBody: content: application/json: schema: type: object properties: id: { type: string, example: evt_01JBXYZ } type: { type: string, enum: [order.delivered, order.cancelled, ping] } created_at: { type: string, format: date-time } data: { $ref: "#/components/schemas/Order" } responses: "200": { description: Received } components: securitySchemes: apiKey: type: http scheme: bearer parameters: OrderNumber: name: orderNumber in: path required: true schema: { type: string, example: USSDCOMX4G } responses: Error: description: | `unauthenticated` (401), `insufficient_balance` (402), `forbidden` (403), `not_found` (404), `validation_failed` (422, with `details` per field), `rate_limited` (429), `server_error` (500). content: application/json: schema: { $ref: "#/components/schemas/Error" } schemas: Error: type: object properties: error: type: object required: [code, message] properties: code: { type: string, example: validation_failed } message: { type: string } details: type: object additionalProperties: type: array items: { type: string } Service: type: object properties: service_type: { type: string, enum: [deep_skip_tracing, lead_generation] } name: { type: string } rate: { type: string, example: "0.0190", description: "US dollars per record or lead" } unit: { type: string, enum: [record, lead] } lead_categories: type: [object, "null"] additionalProperties: { type: string } NewOrder: type: object required: [service_type, total_leads] properties: service_type: { type: string, enum: [deep_skip_tracing, lead_generation] } total_leads: { type: integer, minimum: 1, maximum: 1000000, description: "Records in the file, or leads wanted" } file: { type: string, format: binary, description: "Skip tracing only: CSV or XLSX, up to 20 MB (multipart)" } lead_gen_categories: type: array items: { type: string } description: Lead generation only; keys from GET /services discount_code: { type: string } notes: { type: string, maxLength: 2000 } Order: type: object properties: order_number: { type: string, example: USSDCOMX4G } service_type: { type: string, enum: [deep_skip_tracing, lead_generation] } status: { type: string, enum: [awaiting_payment, in_progress, delivered, cancelled] } total_records: { type: integer } matched_records: { type: [integer, "null"] } lead_categories: { type: [array, "null"], items: { type: string } } file_name: { type: [string, "null"] } notes: { type: [string, "null"] } rate: { type: string, example: "0.0190" } discount: { type: string, example: "0.00" } amount: { type: string, example: "1.24" } refunded: { type: string, example: "0.61", description: "Refund for unmatched records, added to your wallet" } placed_at: { type: string, format: date-time } delivered_at: { type: [string, "null"], format: date-time } results_url: { type: [string, "null"], description: "Set once delivered" }