The Bastro API.

The scrub endpoint accepts phone arrays and returns registry verdicts. A separate controlled-pilot endpoint exercises the real-estate owner-resolution contract with synthetic fixtures only. Both use the same bearer-key boundary.

Every request carries an API key in the Authorization header. Keys are created and revoked in the dashboard under API keys — shown once at creation, stored hashed. Treat a key like a credential, because it is one: it can spend credits.

Authorization: Bearer <api key>

Submits one scrub job synchronously. Credits are debited at one flat rate per input row, however many scopes the job runs — the current rate is on the pricing page. Duplicate numbers are deduplicated before any vendor call is made.

Request

POST /api/v1/scrub HTTP/1.1
Host: bastro.ai
Authorization: Bearer <api key>
Content-Type: application/json

{
  "phones": [
    "+14155550142",
    "+12065550117",
    "+14155550142"
  ],
  "scopes": [
    "litigator",
    "dnc",
    "relocated"
  ]
}

phonesstring[]

Numbers to scrub, E.164 format (e.g. +14155550142). Duplicates count as input rows for billing but are deduplicated before vendor calls.

scopes('litigator' | 'dnc' | 'relocated')[]

Scrub scopes to run in this job. Every scope is vendor-backed and queried at job time.

Response — 200

{
  "job_id": "job_01J9ZX4R8QW2",
  "row_count": 3,
  "unique_count": 2,
  "matches": [
    {
      "phone": "+12065550117",
      "scope": "dnc",
      "source": "vendor",
      "reason": "Federal DNC registration"
    }
  ],
  "credits_used": 30
}

job_idstring

The job record. Verdicts, scopes, and timestamps are retained in your job history as the audit record.

row_countnumber

Input rows received — the billing basis.

unique_countnumber

Unique numbers after in-job dedupe — the vendor-call basis.

matchesMatch[]

One entry per flagged number per scope: { phone, scope, source, reason }. Source names the registry backing the verdict.

credits_usednumber

Credits debited for this job — a flat 10 credits per input row, whatever scopes run.

Example — curl

BASTRO_AUTH="Bearer $BASTRO_API_KEY"

curl -X POST \
  https://bastro.ai/api/v1/scrub \
  -H "Authorization: $BASTRO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": ["+14155550142"],
    "scopes": ["litigator", "dnc"]
  }'

The endpoint accepts one strict current-property-owner request. Unknown fields are rejected. In addition to bearer authentication, every request requires an idempotency key containing 8–200 letters, numbers, periods, underscores, colons, or dashes. Replaying the same key and canonical request returns the original job instead of creating another one.

Request

POST /api/v1/skip-trace/resolve HTTP/1.1
Host: bastro.ai
Authorization: Bearer <api key>
Idempotency-Key: owner-demo-0001
Content-Type: application/json

{
  "purpose_code": "real_estate_owner_outreach",
  "target_role": "current_property_owner",
  "property": {
    "address": {
      "line1": "100 Example Way",
      "line2": "Suite 200",
      "city": "Testville",
      "region": "MI",
      "postalCode": "48000",
      "countryCode": "US"
    }
  },
  "owner_hint": {
    "name": "Synthetic Example"
  },
  "channels": ["phone", "email"],
  "max_candidates_per_channel": 3
}

purpose_code"real_estate_owner_outreach"

Required exact value. Other purposes are rejected by the controlled-pilot contract.

target_role"current_property_owner"

Required requested role. The sandbox does not determine ownership; occupants, relatives, prior owners, and registered agents are not substitutes.

property.addressobject

Required structured US address with line1, city, region, postalCode, and countryCode="US". line2 is the only optional address field; APN is not accepted in v0.

owner_hint.namestring

Required caller-supplied owner-name hint, not a Bastro ownership determination. The strict endpoint accepts no DOB, SSN, or additional identity fields.

channels("phone" | "email")[]

Required non-empty array. Values must be unique and may contain only phone and/or email.

max_candidates_per_channelinteger · 1–3

Required by the documented v0 shape. It caps each requested channel independently.

Synthetic response — 200

{
  "request_id": "<job id>",
  "status": "MATCH",
  "as_of": "<ISO-8601 timestamp>",
  "requested_target_role": "current_property_owner",
  "synthetic": true,
  "replayed": false,
  "contacts": [
    {
      "id": "<synthetic contact id>",
      "channel": "phone",
      "value": "+12025550100",
      "rank": 1,
      "evidence_state": "candidate",
      "confidence": {
        "p_identity": null,
        "p_current": null,
        "p_reachable": null,
        "p_right_party_current": null
      },
      "synthetic": true
    }
  ],
  "policy": {
    "one_shot_design_target_ms": 5000,
    "current_timeout_scope": "provider_execution_only",
    "end_to_end_sla": false
  },
  "billing": {
    "mode": "synthetic_no_charge",
    "credits_reserved": 0,
    "credits_captured": 0,
    "credits_released": 0
  },
  "warning": "Synthetic fixture output only; no real person was searched."
}

Always inspect the response-level and contact-level synthetic flags and the warning. A candidate is not proof of consent, deliverability, or verified right-party identity. The response also includes policy versions, the one-shot design target, credit settlement fields, and measured request latency; those fields describe this execution and do not establish a hard end-to-end SLA, public pricing, or production performance.

Example — curl

curl -X POST   https://bastro.ai/api/v1/skip-trace/resolve   -H "Authorization: Bearer $BASTRO_API_KEY"   -H "Idempotency-Key: owner-demo-0001"   -H "Content-Type: application/json"   -d '{
    "purpose_code": "real_estate_owner_outreach",
    "target_role": "current_property_owner",
    "property": {
      "address": {
        "line1": "100 Example Way",
        "city": "Testville",
        "region": "MI",
        "postalCode": "48000",
        "countryCode": "US"
      }
    },
    "owner_hint": { "name": "Synthetic Example" },
    "channels": ["phone", "email"],
    "max_candidates_per_channel": 3
  }'

The v1 endpoint is limited to 10 requests per minute per key. Batch accordingly — one request with many numbers beats many requests with one. Errors are returned as JSON with a stable machine-readable code.

The same pipeline backs the dashboard uploader, so a job submitted by API appears in job history with the same verdicts, files, and audit trail as one submitted by hand.