# TDLR License Search ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/tdlr/search` | | **Base URL** | `https://api.piloterr.com` | | **Credit Cost** | 1 credit per call | | **Documentation** | https://www.piloterr.com/library/tdlr-search | ## Description Search Texas TDLR licenses by name, city, county, or ZIP. license_type such as AIRREF is required for a useful search. 25 rows per page. ## Authentication - **Key Name:** `x-api-key` - **Location:** HTTP Header - **Get an API key:** https://app.piloterr.com/register ## Example Request ```bash curl --location --request GET 'https://api.piloterr.com/v2/tdlr/search' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### SMITH air conditioning contractors ```json { "results": [ { "dba": null, "url": "https://www.tdlr.texas.gov/LicenseSearch/SearchResultDetail.asp?1=AIRREF00000564", "city": null, "name": "SMITH, JAMES CHARLES JR", "notes": [], "phone": null, "county": "FORT BEND", "status": null, "subtype": null, "detail_id": "AIRREF00000564", "postal_code": null, "license_type": "Air Conditioning Contractors", "business_name": "JIMMY'S AIR CONDITIONING & HEATING", "license_number": "TACLA00000564E", "expiration_date": "12/24/2026", "license_type_code": "AIRREF", "original_issue_date": null } ], "pagination": { "next": "https://www.tdlr.texas.gov/LicenseSearch/SearchResultsListBrowse.asp?from=search&pht_oth_name=SMITH&tdlr_status=AIRREF&page=2", "page": 1, "per_page": 25, "total_pages": 7, "total_results": 153 } } ``` ## Documentation ## Overview Search the Texas TDLR active license list. `query` is a person or business name. `license_type` is the form code. For a useful search, send a type code such as `AIRREF` (air conditioning and refrigeration contractors). ``` GET https://api.piloterr.com/v2/tdlr/search?query=SMITH&license_type=AIRREF ``` Header: `x-api-key`. Each page has 25 rows. You must send a name, a city, a county, or a ZIP. A blank `license_type` searches every type and is rarely useful. A detail URL belongs on `/v2/tdlr/license` and returns 400 here. Search rows leave `status`, `subtype`, `dba`, and `original_issue_date` empty. Those fields are on the license endpoint. ## Parameters `query` is optional when `city`, `county`, or `postal_code` is set. Example: `SMITH`. `license_type` is optional on the request and required for a useful search. Example: `AIRREF`. `ALL` or a blank value searches every type. A code that is not 2 to 12 letters or digits returns 400. `city` is optional. Example: `Austin`. `county` is optional. Example: `TRAVIS`. `postal_code` is optional. Example: `78701`. `page` is optional and defaults to 1. Example: `2`. At least one of `query`, `city`, `county`, or `postal_code` is required. ## Response fields `license_number` is the public license, for example `TACLA00000564E`. `detail_id` is the TDLR detail key, for example `AIRREF00000564`. `url` is the SearchResultDetail link. Pass either `detail_id` or `url` to the license endpoint. `name` is the licensee. `business_name` is the business when the list prints one in parentheses. `expiration_date` is the list date, such as `12/24/2026`. `county` is the county. `city`, `postal_code`, and `phone` are filled when the list shows them, and are often null on this report. `license_type` is the heading of the result set, for example `Air Conditioning Contractors`. `license_type_code` is the code taken from `detail_id`, for example `AIRREF`. `status`, `subtype`, `dba`, `original_issue_date` are null on a normal list row. `notes` is an empty list. The license call fills them. ## Pagination `pagination.per_page` is 25. `pagination.page` starts at 1. `pagination.total_results` is the "records retrieved" count. `pagination.total_pages` is that count divided by 25, rounded up. `pagination.next` is a URL while `page` is below `total_pages`. On the last page `next` is null. For `SMITH` and `AIRREF` the live list had 153 records and 7 pages. Page 1 and page 2 each had 25 distinct `detail_id` values and did not overlap. Page 7 had 3 rows and `next` was null. ## Use cases - A general contractor in Fort Bend checks `AIRREF` licenses named SMITH before hiring a subcontractor. - A city permit desk lists air-conditioning contractors in Travis County with `county=TRAVIS` and `license_type=AIRREF`. - An insurer walks every 25-row page and flags `expiration_date` values inside 90 days, then opens `url` because the list omits status. ## Error codes - 400: no name, city, county, or ZIP, a bad license type code, a detail URL, or `page` below 1. - 404: no rows, or `page` is past the last page. - 401: missing API key.