# TX TREC Real Estate License Status Delta (`titan_coder/tx-trec-real-estate-license-status-delta`) Actor

Watches named Texas real estate license holders in the official TREC registry and alerts only on a genuine status change (Revoked, Suspended, Probation, Surrendered, Expired). For brokerages, HR screening, title companies, insurers, due-diligence. Free when nothing changes.

- **URL**: https://apify.com/titan\_coder/tx-trec-real-estate-license-status-delta.md
- **Developed by:** [Radu Furtuna](https://apify.com/titan_coder) (community)
- **Categories:** Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 license status changeds

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## TX TREC Real Estate License Status Delta

Durable monitor for the official **Broker and Sales Agent License Holder Information** registry,
published by the Texas Real Estate Commission (TREC) as open data on `data.texas.gov`. Watch specific
license holders by their license number and get notified only when their license status genuinely
changes. No API key needed, no login, no captcha.

### Source

`https://data.texas.gov/resource/s7ft-44qi.json` — the Socrata Open Data API for "Broker and Sales Agent
License Holder Information" (dataset id `s7ft-44qi`). Confirmed live 13.09.2026: **324,647 rows**, updated
daily by TREC (`updated` field on the sample row: `2026-09-12T07:30:02`). `license_number` is the
dataset's unique, permanent identifier for one license (format: digits + dash + letter suffix, e.g.
`621981-B` for a Broker Individual, `9017234-BB` for a Broker Company, `1234567-SA` for a Sales Agent) —
not the license holder's name, which is never unique. The `status` field observed live (13.09.2026) takes
at least these 18 values: `Active` (187,617), `Expired less than 6 months` (89,912), `Inactive` (38,591),
`Expired more than 6 months` (5,656), `Revoked` (1,137), `Closed - Upgraded` (651), `Deceased` (376),
`Surrendered` (227), `Probation - Active` (203), `Suspended` (192), `Probation - Inactive` (37),
`Probated Suspension - Active` (25), `Military` (11), `Probated Revocation - Active` (4), `Deleted` (4),
`Inactive - Suspended` (2), `Archived` (1), `Probated Revocation - Inactive` (1).

### How it works

1. Each `watch` names exactly **one** license holder by `licenseNumber` (the TREC license number as
   published in the registry — look it up at
   [trec.texas.gov/apps/license-holder-search/](https://www.trec.texas.gov/apps/license-holder-search/)
   if you only have a name). One watch = one point query
   (`$where=license_number='<licenseNumber>'`) = one HTTP request per run.
2. The first check of a new watch establishes a baseline (no charge). Every later check compares the
   current `status` against the durable record of what it was last time.
3. Billing is tied **only to the `status` field** — not to name, address, related-license fields, or the
   routine `license_expiration_date` renewal that shifts for every actively licensed holder as they
   renew. A status that changes and later reverts (e.g. suspended, then reinstated, then suspended again
   for a new violation) bills every genuine transition, not just the first one — never silently
   deduplicated against an earlier occurrence of the same status value.
4. Genuinely new (first found) or status-changed records are pushed to the dataset and billed once each
   (`license-status-changed`); a check that finds nothing new costs nothing beyond the fixed platform run
   cost.

### Input

```json
{
  "monitorId": "my-trec-watch",
  "watches": [
    { "watchId": "new-hire-jones", "licenseNumber": "621981-B" }
  ],
  "notifyOn": "new_alerts",
  "webhookUrl": "https://example.com/webhook"
}
```

Add more license holders later under the same `monitorId` — each watch keeps its own independent history.
A `watchId` is permanently bound to the `licenseNumber` it first saw; pointing the same `watchId` at a
different license number later fails the run instead of silently mixing histories.

`socrataAppToken` is optional — `data.texas.gov` does not require a key for this dataset, but a free
Socrata app token from your own account raises the anonymous request-rate ceiling if you run many watches
across many monitors.

### Output row (per change)

`watchId, licenseNumber, changeType ("new"|"status_changed"), status, previousStatus, licenseType,
fullName, suffix, firstName, middleName, lastName, county, originalLicenseDate, licenseExpirationDate,
designatedSupervisorFlag, relatedLicenseType, relatedLicenseNumber, relatedLicenseFullName,
relatedLicenseSuffix, relatedLicenseStartDate, agencyIdentifier, keyName, updated, monitorId, runId,
discoveredAt, eventId, billed`

### Billing

Pay-per-event: `license-status-changed` — charged only for a watch's first found record (baseline is free)
or a genuine `status` transition since the previous check. Failed/blocked checks are never charged.

#### Delivery/billing guarantee: **at-most-once**, not exactly-once

The right to perform an irreversible action (dataset write + PPE charge) is granted by the only atomic
primitive Apify offers — `RequestQueue.addRequest(uniqueKey)` → `wasAlreadyPresent` — in a separate
named queue that acts as a permanent journal (`<prefix>-<monitorId>-claims`). The Apify Key-Value Store
has no CAS, no conditional write and no ETag, so it can only ever be a diagnostic state machine, never
the source of at-most-once.

Concretely: for one computed event, delivery and charging each happen **no more than once**. If the run
dies *after* taking the claim, the event may be **lost** (it stays `dataset_unknown`/`charge_unknown`
and is never re-delivered) — but you will never be billed twice. That is a deliberate trade: "never
overcharge" beats "never lose a row".

Boundaries of the guarantee, stated honestly:

- Between the internal lease check and the dataset write/charge there is an unavoidable TOCTOU gap; what
  actually protects your money is the claim gate, not the lease.
- The guarantee holds for as long as the named claims queue exists. Anyone with account access can
  delete or recreate it via Console/API, which starts the journal from zero. This is a boundary of any
  durable storage, not a defect of the protocol.
- The guarantee applies from the build in which the claim gate was introduced onward. Older builds must
  not keep running against the same `monitorId`.

### Important — read before relying on this for any hiring/transaction/compliance decision

**This registry is a publication of license status, not a certification of good standing or a complete
disciplinary record.** TREC maintains its own authoritative records and enforcement files; the public
dataset reflects what TREC has published, which can lag real-world disciplinary events. **This actor is an
informational monitor of CHANGES to that public publication — it is NOT a current "license to practice"
certification, NOT a disciplinary-history lookup, and NOT legal advice.** Always confirm directly at
[trec.texas.gov/apps/license-holder-search/](https://www.trec.texas.gov/apps/license-holder-search/) (or
with TREC directly) before acting on any single entry — especially for hiring, brokerage sponsorship,
transaction, or E\&O insurance decisions.

### Honest limits

- **The durable dataset is a delivery-attempt log, not a guaranteed mirror of the default dataset.**
  Each row is written to the durable dataset first, then mirrored to the run's default dataset before
  billing proceeds for that row. If the durable write succeeds but the default-dataset mirror write
  fails (e.g. transient Apify storage error), the item is marked `dataset_unknown`, billing for it is
  permanently blocked (fail-closed — we never charge for a row we can't confirm was delivered), and the
  run is not retried into re-creating that exact row. The durable dataset can therefore end up with a
  small number of orphan rows that were never mirrored and never billed. The **default dataset is the canonical log of rows successfully written to this
  run's output** (see its `run_summary` row) — but a default-dataset row does not by itself prove the
  row was billed: the row is written before `Actor.charge()` runs, so if charging then fails or comes
  back `charge_unknown`, the row is present but not confirmably paid. **`run_summary.eventsBilled` and
  Apify's own billing ledger are the source of truth for confirmed payment**, not the presence of a row
  in either dataset.
- **One watch = one license holder, one request.** There is no bulk/roster mode — to track a brokerage's
  agents, add one watch per license holder (up to 30 per run). This keeps the network cost fixed and
  predictable regardless of the registry's total size (324k+ rows), and keeps each license's history
  independently auditable.
- **A "not found" result on the very first check of a watch is reported honestly, not as an error** —
  `coverage.watches[].matched: false`. The registry does not delete records (confirmed live 13.09.2026:
  license holders with `status=Deleted` remain listed — `Deleted` is a published status VALUE, not a
  removed row; licenses expired in 1990, 2004, 2006, 2019, 2020, and 2021 are all still returned by a
  direct point query, each with a current `updated` timestamp from the daily refresh), so a typo'd
  `licenseNumber` will simply never match; it costs nothing and is safe to correct and retry under the
  same `watchId`.
- **A license number that WAS found on a previous check but is NOT found on a later one** is treated as
  `source_access_limited` for that watch this run — no baseline/history update, no billing. Since the
  registry doesn't delete rows (see above — even decades-old surrendered/revoked/deleted licenses stay
  queryable), this should never happen from a genuine data change; it's the honest fallback if the source
  ever answers unexpectedly.
- **Billing tracks only the `status` field**, deliberately excluding `license_expiration_date` (which
  shifts routinely on every renewal for every actively licensed holder) and related-license/address/agency
  fields (which can change administratively — a new sponsoring broker, a office move — without any change
  to license status). Those fields are still delivered in every row for context.
- We don't invent data: if the API ever returns something other than a bare JSON array, more than one row
  for a single `license_number` (violating the dataset's own uniqueness contract), or a row missing
  `license_number`/`status`, the run reports it honestly (`source_access_limited`) instead of guessing.

Author: OmniCoder (https://t.me/OmniCoder)

# Actor input Schema

## `monitorId` (type: `string`):

Name of this monitor's durable history (a-z, 0-9, dash; up to 40 chars).

## `watches` (type: `array`):

1-30 objects: {"watchId": "new-hire-jones", "licenseNumber": "621981-B"}. licenseNumber is the TREC license number as published in the registry (digits-letters, e.g. 1234567-SA for a Sales Agent, 621981-B for a Broker Individual, 9017234-BB for a Broker Company) — look it up at trec.texas.gov/apps/license-holder-search/ if you only have a name. One watch = one license holder. New licenses can be added later under the same monitorId.

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

Optional. data.texas.gov does not require a key for this dataset, but a free Socrata app token (from your own data.texas.gov account) raises the anonymous request-rate ceiling if you run many watches across many monitors. Leave empty for normal use — a handful of watches per run works fine without one.

## `notifyOn` (type: `string`):

new\_alerts — post the webhook only when new/changed paid status changes were delivered; always — post it every run; never — do not call webhookUrl at all.

## `webhookUrl` (type: `string`):

Optional. Receives a digest of delivered (paid) status changes as JSON. HTTPS only.

## Actor input object example

```json
{
  "monitorId": "my-trec-watch",
  "watches": [
    {
      "watchId": "example-broker",
      "licenseNumber": "621981-B"
    }
  ],
  "notifyOn": "new_alerts"
}
```

# Actor output Schema

## `results` (type: `string`):

Every row this run produced. Key fields: watchId, licenseNumber, changeType (new|status\_changed), status, previousStatus, licenseType, fullName, county. Informational only — not legal advice or a current-standing certification.

## `coverage` (type: `string`):

What this run actually covered and what it charged for: per-watch status/reason/matched, records delivered and billed, requested/attempted/succeeded/failed watch counts. Enough to reconcile every charge against every row.

## `digest` (type: `string`):

A short human-readable summary of what this run found, written every run.

# 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 = {
    "monitorId": "my-trec-watch",
    "watches": [
        {
            "watchId": "example-broker",
            "licenseNumber": "621981-B"
        }
    ],
    "notifyOn": "new_alerts"
};

// Run the Actor and wait for it to finish
const run = await client.actor("titan_coder/tx-trec-real-estate-license-status-delta").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 = {
    "monitorId": "my-trec-watch",
    "watches": [{
            "watchId": "example-broker",
            "licenseNumber": "621981-B",
        }],
    "notifyOn": "new_alerts",
}

# Run the Actor and wait for it to finish
run = client.actor("titan_coder/tx-trec-real-estate-license-status-delta").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 '{
  "monitorId": "my-trec-watch",
  "watches": [
    {
      "watchId": "example-broker",
      "licenseNumber": "621981-B"
    }
  ],
  "notifyOn": "new_alerts"
}' |
apify call titan_coder/tx-trec-real-estate-license-status-delta --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,titan_coder/tx-trec-real-estate-license-status-delta"
        }
    }
}
```

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/zu84Z3HpFmvaEJenS/builds/gfeB9EVyzefGoLZbq/openapi.json