# US FMCSA Insurance Gap, Permits & New LLC Signal Engine (`pipeforge/us-socrata-b2b-signal-crossjoin-engine`) Actor

Zero-proxy US public-record B2B signal engine: (1) FMCSA 3-table live BMC-91X insurance gap & phone cross-join, (2) 100% phone-verified $75K+ Austin & NYC commercial permits, (3) Colorado SOS & Texas Sales Tax new LLCs with Registered Agent proxy filtering.

- **URL**: https://apify.com/pipeforge/us-socrata-b2b-signal-crossjoin-engine.md
- **Developed by:** [Yaşar Kaan Özdamur](https://apify.com/pipeforge) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.50 / 1,000 verified b2b signal rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## US DOT FMCSA 3-Table Insurance Gap & Verified-Phone Commercial Permits Engine

Structured B2B lead intelligence engine built on official US federal and municipal Socrata Open Data APIs (`data.transportation.gov`, `data.austintexas.gov`, `data.cityofnewyork.us`).

Unlike single-table scrapers that output raw policy rows without phone numbers or unverified building permits with empty contractor fields, this Actor executes a **server-side batch SoQL Cross-Join** across three official tables and filters strictly for **100% phone-verified records**.

***

### Why Single-Table Socrata Scrapers Fail (And How Cross-Join Solves It)

| Data Source | Single-Table Scraper Problem | This Actor's Cross-Join Architecture |
| :--- | :--- | :--- |
| **US DOT FMCSA Insurance (`x96h-evps`)** | Contains `docket_number`, `usdot_number`, `policy_no`, and `BMC-91X` transaction dates, but **0% company names, 0% phone numbers, and 0% current authority status**. | Joins `x96h-evps` (daily `BMC-91X` filings) ⋈ `inys-ebih` (Authority & Contact table via batch `WHERE docket_number IN (...)`) ⋈ `az4n-8mr2` (Company Census `power_units`), returning **100% verified phone (`bus_telno`), company name (`legal_name`), street address, and `$0` BIPD insurance-gap flags**. |
| **Austin Building Permits (`3syk-w9eu`)** | Unfiltered queries return **72%–76% NULL project valuations** (minor residential plumbing/electrical work). | Enforces `permit_class_mapped='Commercial' AND total_job_valuation >= 75000 AND contractor_phone IS NOT NULL`, yielding **100% General Contractor company, contact name, direct phone, and verified dollar valuation (`$100K–$60M+`)**. |
| **NYC DOB Permits (`ipu4-2q9a`)** | Raw dumps include minor plumbing/signage rows and unparsed text dates (`MM/DD/YYYY`). | Filters strictly for `job_type IN ('NB', 'A1')` (New Buildings & Major Class-A1 Alterations) with **100% verified contractor phone (`permittee_s_phone__`) and NYC DOB license numbers**. |
| **CO SOS (`4ykn-tg5h`) & TX Sales Tax (`jrea-zgmq`)** | Raw business registry dumps are flooded with commercial Registered Agent proxy addresses (Northwest RA, LegalZoom, Incfile). | Automatically flags `COMMERCIAL_RA_PROXY` vs `DIRECT_OWNER_OR_OFFICE` so outbound teams can optionally exclude proxy filings (`excludeCommercialRaProxy: true`). |
| **Seattle (`76t5-zqzr`) & LA (`pi9x-tg5x`)** | Seattle commercial permits have **84% NULL contractor names and no phone column**; Los Angeles has **0% contractor/phone columns**. | **Excluded by design.** Every FMCSA and commercial permit record emitted is guaranteed to carry a non-empty company name and direct phone number. |

***

### Signal Priority Tags (`signal_priority`)

#### Mode A: `fmcsa_crossjoin` (Trucking Insurance Brokers, Freight Factoring & Fleet SaaS)

1. **`CRITICAL_BIPD_ZERO`**: Carrier holds an `Active` or existing operating authority in `inys-ebih`, has a recent `BMC-91X` transaction in `x96h-evps`, but currently shows **`bipd_file = 0.00`** ($0 Bodily Injury & Property Damage coverage on file — highest urgency compliance/re-quoting signal).
2. **`PENDING_NEW_BMC91X`**: Carrier operating authority is `Pending` with `bipd_file = 0.00` and a newly submitted `BMC-91X` policy filing processed today.
3. **`ACTIVE_RENEWAL`**: Established carrier (`Active` / `Inactive` with `bipd_file >= $750,000`) recording a new `BMC-91X` policy replacement or renewal.

#### Mode B: `permits_verified_phone` (Construction Equipment Rental, Subcontractors, B2B Suppliers)

1. **`TIER1_COMMERCIAL_1M_PLUS`**: Commercial project with reported job valuation >= `$1,000,000` and verified General Contractor phone.
2. **`TIER2_COMMERCIAL_75K_PLUS`**: Commercial project with reported job valuation between `$75,000` and `$999,999` and verified General Contractor phone.
3. **`TIER1_NYC_NEW_BUILDING_NB`**: NYC Department of Buildings `NB` (New Building) permit with verified contractor phone and DOB license.
4. **`TIER2_NYC_MAJOR_ALT_A1`**: NYC Department of Buildings `A1` (Major Alteration requiring new Certificate of Occupancy) with verified contractor phone and DOB license.

#### Mode C: `new_llc_tax` (Merchant Services, Business Banking, Bookkeeping & Web Agencies)

1. **`CO_NEW_LLC_DIRECT_OWNER`** / **`CO_NEW_LLC_RA_PROXY`**: Newly formed Colorado LLCs/Corps (`4ykn-tg5h`) tagged with Commercial Registered Agent proxy detection.
2. **`TX_ACTIVE_SALES_TAX_PERMIT`**: Active Texas Comptroller Sales Tax Permits (`jrea-zgmq`) with physical commercial storefront addresses and NAICS codes.

***

### Live Sample Output

#### 1. FMCSA 3-Table Cross-Join (`live_fmcsa_signals.csv`)

| `signal_priority` | `trans_date` | `docket_number` | `usdot_number` | `legal_name` | `phone_formatted` | `bus_city` | `bus_state_code` | `op_auth_status` | `bipd_file` | `max_cov_amount` | `power_units` |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **`CRITICAL_BIPD_ZERO`** | `2026-11-19` | `MC86474261` | `8560685` | S.B.S Logistics Services LLC | `+1 (832) 713-7688` | Houston | TX | Active | `0.00` | `750000.00` | `2` |
| **`CRITICAL_BIPD_ZERO`** | `2026-11-19` | `MC57106118` | `7050650` | Midnight Mile Trucking LLC | `+1 (513) 616-1205` | Springdale | OH | Active | `0.00` | `750000.00` | `1` |
| **`PENDING_NEW_BMC91X`** | `2026-11-19` | `MC64188851` | `4991621` | J7 Enterprises LLC | `+1 (573) 576-1858` | Cape Girardeau | MO | Pending | `0.00` | `750000.00` | `PENDING_CENSUS_SYNC` |
| **`PENDING_NEW_BMC91X`** | `2026-11-19` | `MC57299275` | `5826764` | CORREIA HEAVY CONTRACTING LLC | `+1 (848) 203-8998` | aberdeen | NJ | Pending | `0.00` | `750000.00` | `1` |
| **`ACTIVE_RENEWAL`** | `2026-11-19` | `MC371013` | `2368413` | GDK LOGISTICS INC | `+1 (201) 906-4734` | Lincoln Park | NJ | Active | `750000.00` | `750000.00` | `8` |
| **`ACTIVE_RENEWAL`** | `2026-11-19` | `MC75455713` | `6707247` | GARVIA TRANSPORT LLC | `+1 (484) 651-4549` | Temple | PA | Active | `1000000.00` | `1000000.00` | `6` |

#### 2. Verified-Phone Commercial Permits (`live_permits_signals.csv`)

| `signal_priority` | `source_city` | `permit_id` | `issue_date` | `contractor_company` | `contractor_contact` | `contractor_phone` | `license_or_trade` | `project_address` | `valuation_usd` |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **`TIER1_COMMERCIAL_1M_PLUS`** | `AUSTIN_TX` | `2026-084222 BP` | `2026-11-17` | Hensel Phelps Construction Co. | Bradley Winans | `+1 (512) 834-9848` | General Contractor | 10113 MAINTAINERS DR | `60000000.00` |
| **`TIER1_COMMERCIAL_1M_PLUS`** | `AUSTIN_TX` | `2020-158797 BP` | `2026-11-12` | Constructinople LLC | Eyad Kasemi | `+1 (909) 806-9750` | General Contractor | 1717 E ANDERSON LN SVRD EB | `4000000.00` |
| **`TIER2_COMMERCIAL_75K_PLUS`** | `AUSTIN_TX` | `2026-132873 BP` | `2026-11-18` | Hanna Design Group Inc | Robert Perry | `+1 (847) 719-0372` | General Contractor | 8602 FM 969 RD BLDG 3 | `775000.00` |
| **`TIER1_NYC_NEW_BUILDING_NB`** | `NYC_NY` | `321598188` | `2026-11-16` | PARK MANAGEMENT USA CORP | SHIA KOHN | `+1 (718) 210-3181` | `DOB-LIC-0621935` | 6 HOWARD AVE, BROOKLYN | `EST_MAJOR_NB_A1` |
| **`TIER1_NYC_NEW_BUILDING_NB`** | `NYC_NY` | `210182194` | `2026-11-16` | SPAXEL BUILDERS LLC | GUCIM GJONBALAJ | `+1 (347) 827-6153` | `DOB-LIC-0623192` | 1695 MONROE AVENUE, BRONX | `EST_MAJOR_NB_A1` |

***

### Input Configuration

```json
{
  "mode": "all",
  "limit": 15,
  "minPermitValuationUsd": 75000,
  "onlyCriticalBipdZero": false,
  "excludeCommercialRaProxy": false,
  "socrataAppToken": ""
}
```

- **`mode`** (`"all"` | `"both"` | `"fmcsa_crossjoin"` | `"permits_verified_phone"` | `"new_llc_tax"`): Selects which pipeline(s) to execute.
- **`limit`** (`integer`, default `15`, max `200`): Maximum enriched records returned per pipeline. Uses chunked 50-item batch `WHERE ... IN (...)` SoQL requests to stay well below public Socrata rate limits with `$0` proxy cost.
- **`minPermitValuationUsd`** (`integer`, default `75000`): Minimum commercial job valuation in USD for Austin building permits.
- **`onlyCriticalBipdZero`** (`boolean`, default `false`): When `true`, filters FMCSA output strictly to `CRITICAL_BIPD_ZERO` and `PENDING_NEW_BMC91X` records.
- **`excludeCommercialRaProxy`** (`boolean`, default `false`): When `true`, filters out Colorado LLCs filed via commercial Registered Agent proxies (e.g., Northwest RA, LegalZoom, Incfile).
- **`socrataAppToken`** (`string`, optional): Optional `X-App-Token` for Socrata APIs. If omitted or if the optional `az4n-8mr2` census endpoint returns `HTTP 429`, the engine logs `SKIPPED_HTTP_429_GRACEFUL` in `census_flag` and completes without failing.

***

### 1-Click AI Agent & MCP Server Integration (Claude, Cursor, n8n)

This Actor is natively MCP-ready via Apify's official Model Context Protocol endpoint—no server hosting required:

- **Single-Actor MCP Endpoint:** `https://mcp.apify.com/?actors=pipeforge/us-socrata-b2b-signal-crossjoin-engine`
- **2-Actor B2B Signal + Domain Trigger Chain:** `https://mcp.apify.com/?actors=pipeforge/us-socrata-b2b-signal-crossjoin-engine,pipeforge/b2b-domain-tech-stack-dns-ssl-sales-trigger`

Example prompt in **Claude Desktop / Cursor / n8n AI Agent**:

> *"Run `pipeforge/us-socrata-b2b-signal-crossjoin-engine` in `fmcsa_crossjoin` mode with `onlyCriticalBipdZero: true` and `limit: 25`, then return a call sheet of carriers with active authority, `$0` BIPD on file, fleet size, and formatted phone numbers."*

***

### n8n / Make.com / Clay Webhook Automation

1. Add an **HTTP Request** node (`POST https://api.apify.com/v2/acts/pipeforge~us-socrata-b2b-signal-crossjoin-engine/run-sync-get-dataset-items`) using `Header Auth` (`Authorization: Bearer <YOUR_APIFY_TOKEN>`) scheduled daily at `07:00 EST`.
2. Set `mode` to `"fmcsa_crossjoin"`, `"permits_verified_phone"`, or `"new_llc_tax"`.
3. Map `phone_formatted` / `contractor_phone`, `legal_name` / `contractor_company`, and `signal_priority` directly into HubSpot, Close CRM, Clay, Google Sheets, or Slack alerts.

# Actor input Schema

## `mode` (type: `string`):

Select Mode A (FMCSA 3-table insurance gap cross-join), Mode B (verified-phone commercial permits: Austin >= $75K + NYC NB/A1), Mode C (New LLC & Sales Tax Permits: Colorado SOS + Texas Comptroller with Registered Agent proxy detection), or All 3 modes.

## `limit` (type: `integer`):

Maximum number of cross-joined, phone-verified records to emit per feed (1 to 200 per run; default prefill is 15 for fast test runs).

## `minPermitValuationUsd` (type: `integer`):

Minimum total_job_valuation filter for Austin commercial building permits (filters out low-value residential/minor work).

## `onlyCriticalBipdZero` (type: `boolean`):

When enabled, excludes routine ACTIVE_RENEWAL filings and only outputs carriers with $0 BIPD on file or Pending new BMC-91X authority.

## `excludeCommercialRaProxy` (type: `boolean`):

When enabled, Mode C (new_llc_tax) filters out entities using commercial Registered Agents (LegalZoom, CT Corp, CSC, Northwest, Registered Agents Inc, Incfile) even if they report a separate principal HQ address.

## `socrataAppToken` (type: `string`):

Optional Socrata application token (X-App-Token) for elevated rate limits on the az4n-8mr2 fleet census table. If omitted or rate-limited (HTTP 429), the engine degrades gracefully without failing.

## Actor input object example

```json
{
  "mode": "all",
  "limit": 15,
  "minPermitValuationUsd": 75000,
  "onlyCriticalBipdZero": false,
  "excludeCommercialRaProxy": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "all",
    "limit": 15,
    "minPermitValuationUsd": 75000
};

// Run the Actor and wait for it to finish
const run = await client.actor("pipeforge/us-socrata-b2b-signal-crossjoin-engine").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "all",
    "limit": 15,
    "minPermitValuationUsd": 75000,
}

# Run the Actor and wait for it to finish
run = client.actor("pipeforge/us-socrata-b2b-signal-crossjoin-engine").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "all",
  "limit": 15,
  "minPermitValuationUsd": 75000
}' |
apify call pipeforge/us-socrata-b2b-signal-crossjoin-engine --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,pipeforge/us-socrata-b2b-signal-crossjoin-engine"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/DmdcHXgYtSEhimyfD/builds/nVPiUOACY25x4pxG0/openapi.json
