Skip trace

Generated from DialerDigital/core commit 0fc18008b3c8 — spec openapi/dialer-v1.yaml v0.134.0. Do not edit by hand; see How this reference is built. Download the OpenAPI spec.

Español

Skip tracing (F0): a measured vendor lookup behind a per-tenant monthly cap with a hard cut. No invoice line yet.

Endpoints

Method	Path	Summary
POST	/v1/skip-trace/lookups	One measured skip-trace lookup
GET	/v1/skip-trace/cap	The tenant's monthly skip-trace limits and usage so far
PUT	/v1/skip-trace/cap	Set or clear the tenant's monthly skip-trace limits

One measured skip-trace lookup

POST /v1/skip-trace/lookups

Tenant scope (a dd_ key or a dashboard login). Order of refusals, none of which costs anything: 503 not_configured when the platform has no vendor configured (the vendor is never called), 409 duplicate_request for a request_key already used by this tenant, 429 skip_trace_cap_exceeded when the tenant's monthly cap (queries or USD) is reached — a HARD cut: the refused lookup is neither called nor measured. A vendor failure is 502 provider_error and is not charged. The subject and the results are never stored. There is no invoice line yet: it waits for the A3 gate.

Request body (JSON, required)

Field	Type	Required	Description
request_key	string	yes	The caller's idempotency key; one lookup per key per tenant.
subject	object	yes
subject.name	string	no
subject.phone	string	no
subject.address	string	no
subject.email	string	no

{
  "request_key": "lookup-2026-10-06-0001",
  "subject": {
    "name": "Jane Doe",
    "address": "1 Main St, Springfield"
  }
}

Responses

200

The vendor's matches and what the lookup cost.

Field	Type	Required	Description
results	array of object	yes
cost_usd	string	yes	Decimal string, USD.

{
  "results": [
    {
      "match": "fake"
    }
  ],
  "cost_usd": "0.10"
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

403 — Forbidden

The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

409

A request_key this tenant already used (duplicate_request).

422 — Unprocessable

Shape is fine, semantics are not (broken domain rule).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

429

The monthly cap is reached (skip_trace_cap_exceeded).

502

The vendor failed (provider_error); nothing was charged.

503

No vendor is configured (not_configured).

The tenant's monthly skip-trace limits and usage so far

GET /v1/skip-trace/cap

cap limits are null when unset (no limit). usage is the UTC calendar month to date; failed lookups do not count.

Responses

200

Limits and month-to-date usage.

Field	Type	Required	Description
cap	object (SkipTraceCap)	yes
cap.max_queries_per_month	integer,null	no
cap.max_usd_per_month	string,null	no	Decimal string in (0, 100000000), at most 4 decimals.
usage	object	yes
usage.queries	integer	yes
usage.spent_usd	string	yes

{
  "cap": {
    "max_queries_per_month": 100,
    "max_usd_per_month": "25.0000"
  },
  "usage": {
    "queries": 3,
    "spent_usd": "0.30"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

403 — Forbidden

The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

Set or clear the tenant's monthly skip-trace limits

PUT /v1/skip-trace/cap

A dd_ key or an account_admin login (otherwise 403). Replaces both limits; an omitted or null limit is cleared. Invalid values are 422 and nothing is stored.

Request body (JSON, required)

Field	Type	Required	Description
max_queries_per_month	integer,null	no
max_usd_per_month	string,null	no	Decimal string in (0, 100000000), at most 4 decimals.

{
  "max_queries_per_month": 100,
  "max_usd_per_month": "25"
}

Responses

200

The stored limits.

Field	Type	Required	Description
cap	object (SkipTraceCap)	yes
cap.max_queries_per_month	integer,null	no
cap.max_usd_per_month	string,null	no	Decimal string in (0, 100000000), at most 4 decimals.

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

403 — Forbidden

The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

422 — Unprocessable

Shape is fine, semantics are not (broken domain rule).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}