DrillerDB API Documentation

Access 12,000+ drilling and well service companies through our REST API. Search companies, manage lists, and export data programmatically.

Get Started with API Access

Base URL

https://enterprise.drillerdb.com/api/v1

Authentication

The API supports three authentication methods. For programmatic access, use an API key with the drdb_ prefix.

1. API Key (Programmatic Access)

Create keys in Settings > API Keys. Keys use the drdb_ prefix.

Authorization: Bearer drdb_your-api-key-here

2. Mobile JWT (iOS/Android Apps)

Obtain a JWT via POST /api/v1/auth/mobile/login, then include it as a Bearer token. Refresh with POST /api/v1/auth/mobile/refresh.

3. Web Session (Dashboard)

Cookie-based sessions via NextAuth. Write operations require an X-CSRF-Token header.

Secure by Default

All API requests must be made over HTTPS. Requests over HTTP will fail.

Keep Keys Secret

Never expose API keys in client-side code or commit them to version control.

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Endpoint	Limit	Window
`/companies`	100 requests	Per minute
`/exports`	10 requests	Per hour
`/search/parse`	20 requests	Per minute
`/auth/mobile/login`	5 requests	Per 15 minutes

When rate limited, you'll receive a 429 response with a Retry-After header indicating when you can retry.

Companies

Search and retrieve drilling company data. Results are filtered based on your organization's tier and geographic permissions.

GET/companies

Search for drilling companies with filters. Results are paginated and respect your organization's tier restrictions.

Query Parameters

Name	Type	Required	Description
`q`	string	Optional	Search query for company name
`state`	string	Optional	Filter by state (comma-separated for multiple)
`city`	string	Optional	Filter by city name (partial match)
`size_bucket`	string	Optional	Filter by company size: solo, micro, small, medium, large
`status`	string	Optional	Filter by status: active, maybe_closed, closed
`service_category`	string	Optional	Filter by service category
`has_email`	boolean	Optional	Filter for companies with email
`has_phone`	boolean	Optional	Filter for companies with phone
`has_website`	boolean	Optional	Filter for companies with website
`min_rating`	number	Optional	Minimum rating (1-5). Uses SERP-derived rating when available, otherwise falls back to stored Google rating.
`lat`	number	Optional	Latitude for proximity search
`lng`	number	Optional	Longitude for proximity search
`radius_miles`	number	Optional	Radius in miles (requires lat/lng)
`limit`	number	Optional	Results per page (default: 20, max: 100)
`offset`	number	Optional	Pagination offset
`sort`	string	Optional	Sort field: name, city, state, rating
`order`	string	Optional	Sort order: asc, desc

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/companies?state=TX&size_bucket=medium&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1234,
      "name": "ABC Drilling Services",
      "address": "123 Main St",
      "city": "Houston",
      "state": "TX",
      "zip": "77001",
      "phone": "(713) 555-1234",
      "email": "contact@abcdrilling.com",
      "website": "https://abcdrilling.com",
      "status": "active",
      "size_bucket": "medium",
      "service_categories": [
        "water_well",
        "geothermal"
      ],
      "google_data": {
        "rating": 4.5,
        "review_count": 28,
        "place_id": "ChIJ..."
      },
      "equipment_detected": [
        "drill_rig",
        "service_truck"
      ]
    }
  ],
  "meta": {
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

GET/companies/:id

Get detailed information about a specific company by ID.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	Company ID

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/companies/1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": 1234,
    "name": "ABC Drilling Services",
    "slug": "abc-drilling-services",
    "address": "123 Main St",
    "city": "Houston",
    "state": "TX",
    "zip": "77001",
    "phone": "(713) 555-1234",
    "email": "contact@abcdrilling.com",
    "website": "https://abcdrilling.com",
    "description": "Family-owned drilling company since 1985",
    "latitude": 29.7604,
    "longitude": -95.3698,
    "status": "active",
    "status_confidence": 0.95,
    "size_bucket": "medium",
    "employee_count": 25,
    "service_categories": [
      "water_well",
      "geothermal"
    ],
    "google": {
      "rating": 4.5,
      "review_count": 28,
      "place_id": "ChIJ..."
    },
    "social": {
      "facebook": "https://facebook.com/abcdrilling",
      "instagram": null,
      "linkedin": null
    },
    "satellite": {
      "image_url": "https://...",
      "analyzed_at": "2025-01-10T08:00:00Z",
      "equipment": [
        "drill_rig",
        "truck"
      ]
    },
    "org_notes": {
      "note": "Good prospect",
      "tags": [
        "priority"
      ]
    },
    "last_updated": "2025-01-15T10:30:00Z"
  }
}

GET/companies/geo

Get lightweight company data for map markers. Returns only id, name, lat, lng for performance with 12k+ companies.

Query Parameters

Name	Type	Required	Description
`state`	string	Optional	Filter by state (comma-separated)
`city`	string	Optional	Filter by city name
`size_bucket`	string	Optional	Filter by company size
`has_email`	boolean	Optional	Filter for companies with email
`has_phone`	boolean	Optional	Filter for companies with phone
`has_website`	boolean	Optional	Filter for companies with website

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/companies/geo?state=TX" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1234,
      "name": "ABC Drilling",
      "lat": 29.7604,
      "lng": -95.3698
    },
    {
      "id": 1235,
      "name": "XYZ Wells",
      "lat": 29.7854,
      "lng": -95.3248
    }
  ],
  "meta": {
    "total": 5432,
    "limited": false
  }
}

GET/companies/:id/contacts

Get all contacts (decision makers, owners, licensed drillers) for a company.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	Company ID

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/companies/1234/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "company_id": 1234,
    "company_name": "ABC Drilling Services",
    "contacts": [
      {
        "id": 1,
        "full_name": "John Smith",
        "first_name": "John",
        "last_name": "Smith",
        "title": "Owner",
        "role": "owner",
        "is_primary": true,
        "email": "john@abcdrilling.com",
        "phone": "(713) 555-1234",
        "phone_type": "mobile",
        "linkedin_url": "https://linkedin.com/in/johnsmith",
        "source": "website",
        "confidence": 0.95,
        "license_number": "WD-12345",
        "license_state": "TX",
        "license_type": "water_well",
        "license_expires": "2026-12-31",
        "is_active": true
      }
    ],
    "total": 3
  }
}

GET/companies/:id/reviews

Get all customer reviews for a company with summary statistics.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	Company ID

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/companies/1234/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "company_id": 1234,
    "company_name": "ABC Drilling Services",
    "summary": {
      "google_rating": 4.5,
      "google_review_count": 28,
      "calculated_avg_rating": 4.4,
      "total_reviews": 28,
      "most_recent_review_date": "2025-01-10",
      "review_velocity": 2.5,
      "rating_distribution": {
        "1": 0,
        "2": 1,
        "3": 2,
        "4": 8,
        "5": 17
      },
      "by_source": {
        "google": 28
      }
    },
    "reviews": [
      {
        "id": 1,
        "source": "google",
        "author_name": "Jane Doe",
        "rating": 5,
        "review_text": "Great service, very professional team.",
        "publish_date": "2025-01-10",
        "relative_time": "2 weeks ago"
      }
    ]
  }
}

GET/companies/:id/satellite

Get satellite imagery and AI-detected equipment analysis for a company location.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	Company ID

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/companies/1234/satellite" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "company_id": 1234,
    "company_name": "ABC Drilling Services",
    "location": {
      "latitude": 29.7604,
      "longitude": -95.3698
    },
    "primary_image": "https://app.drillerdb.com/satellite/1234.jpg",
    "provider": "google",
    "analyzed_at": "2025-01-10T08:00:00Z",
    "location_type": "commercial_yard",
    "equipment": {
      "drill_rigs": 3,
      "service_trucks": 5,
      "water_trucks": 2,
      "trailers": 4,
      "storage_tanks": 2,
      "pipe_racks": 1,
      "personal_vehicles": 8,
      "facility_sqft_estimate": 25000,
      "confidence": 0.85
    },
    "zoom_levels": [
      20,
      19,
      18
    ],
    "analyses": [],
    "total_images": 6
  }
}

Lists

Create and manage saved lists of companies for your sales workflows.

GET/lists

Get all saved lists for your organization.

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/lists" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "name": "Texas Prospects",
      "type": "static",
      "query_params": null,
      "company_count": 45,
      "created_by": {
        "id": 1,
        "name": "John Doe"
      },
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-12T14:30:00Z"
    }
  ],
  "meta": {
    "total": 5
  }
}

POST/lists

Create a new saved list.

Request Body

List creation payload

{
  "name": "Priority Prospects",
  "type": "static"
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/lists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Priority Prospects", "type": "static"}'

Response

{
  "data": {
    "id": 10,
    "name": "Priority Prospects",
    "type": "static",
    "query_params": null,
    "company_count": 0,
    "created_by": {
      "id": 1,
      "name": "John Doe"
    },
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

GET/lists/:id

Get details of a specific saved list.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	List ID

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/lists/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": 1,
    "name": "Texas Prospects",
    "type": "static",
    "query_params": null,
    "company_count": 45,
    "created_by": {
      "id": 1,
      "name": "John Doe"
    },
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-01-12T14:30:00Z"
  }
}

PUT/lists/:id

Update a saved list's name.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	List ID

Request Body

List update payload

{
  "name": "Updated List Name"
}

Example

curl -X PUT "https://enterprise.drillerdb.com/api/v1/lists/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated List Name"}'

Response

{
  "data": {
    "id": 1,
    "name": "Updated List Name",
    "type": "static",
    "query_params": null,
    "company_count": 45,
    "created_by": {
      "id": 1,
      "name": "John Doe"
    },
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

DELETE/lists/:id

Delete a saved list and all its company associations.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	List ID

Example

curl -X DELETE "https://enterprise.drillerdb.com/api/v1/lists/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "message": "List deleted successfully"
}

GET/lists/:id/companies

Get all companies in a saved list.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	List ID

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/lists/1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1234,
      "name": "ABC Drilling",
      "city": "Houston",
      "state": "TX",
      "phone": "(713) 555-1234",
      "email": "contact@abcdrilling.com",
      "added_at": "2025-01-12T10:00:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "list_id": 1
  }
}

POST/lists/:id/companies

Add companies to a saved list.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	List ID

Request Body

Array of company IDs to add

{
  "companyIds": [
    1234,
    1235,
    1236
  ]
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/lists/1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyIds": [1234, 1235, 1236]}'

Response

{
  "message": "Companies added to list",
  "data": {
    "list_id": 1,
    "added_count": 3,
    "total_count": 48
  }
}

DELETE/lists/:id/companies

Remove companies from a saved list.

Query Parameters

Name	Type	Required	Description
`id`	integer	Required	List ID

Request Body

Array of company IDs to remove

{
  "companyIds": [
    1234,
    1235
  ]
}

Example

curl -X DELETE "https://enterprise.drillerdb.com/api/v1/lists/1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyIds": [1234, 1235]}'

Response

{
  "message": "Companies removed from list",
  "data": {
    "list_id": 1,
    "removed_count": 2,
    "total_count": 43
  }
}

Exports

Export company data in CSV, Excel, or JSON format. Exports run asynchronously for large datasets.

POST/exports

Create a new export job. The export runs asynchronously. Poll the status endpoint to check progress.

Request Body

Export configuration with search filters

{
  "format": "csv",
  "state": [
    "TX",
    "OK"
  ],
  "size_bucket": [
    "medium",
    "large"
  ],
  "has_email": true
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/exports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "csv", "state": ["TX"], "has_email": true}'

Response

{
  "data": {
    "id": "exp_abc123",
    "status": "pending",
    "format": "csv",
    "created_at": "2025-01-15T12:00:00Z"
  },
  "message": "Export job created. Poll the status endpoint to check progress."
}

GET/exports

List recent export jobs for your organization.

Query Parameters

Name	Type	Required	Description
`limit`	number	Optional	Results per page (default: 20, max: 100)
`offset`	number	Optional	Pagination offset

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/exports?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "exp_abc123",
      "status": "completed",
      "format": "csv",
      "record_count": 1250,
      "error": null,
      "created_at": "2025-01-15T12:00:00Z",
      "completed_at": "2025-01-15T12:01:30Z"
    }
  ],
  "meta": {
    "total": 15,
    "limit": 20,
    "offset": 0
  }
}

GET/exports/:jobId

Get export job status. Add ?download=true to download the file when complete.

Query Parameters

Name	Type	Required	Description
`jobId`	string	Required	Export job ID
`download`	boolean	Optional	Set to true to download file

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/exports/exp_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# To download the file:
curl -X GET "https://enterprise.drillerdb.com/api/v1/exports/exp_abc123?download=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o export.csv

Response

{
  "data": {
    "id": "exp_abc123",
    "status": "completed",
    "format": "csv",
    "record_count": 1250,
    "error": null,
    "created_at": "2025-01-15T12:00:00Z",
    "completed_at": "2025-01-15T12:01:30Z",
    "download_url": "/api/v1/exports/exp_abc123?download=true"
  }
}

Growth Intelligence

Identify high-potential companies using lead scoring, growth trends, and permit data. Find hot leads, accelerating companies, and year-over-year growth leaders.

GET/growth

Get growth intelligence summary with counts of hot leads, accelerating companies, and YoY leaders.

Query Parameters

Name	Type	Required	Description
`states`	string	Optional	Comma-separated state codes to filter by

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/growth?states=TX,OK" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "hot_leads": 45,
    "accelerating": 120,
    "yoy_leaders": 85,
    "cooling": 30
  }
}

GET/growth/hot

Get companies with high lead scores (≥70). These are companies showing strong growth signals.

Query Parameters

Name	Type	Required	Description
`states`	string	Optional	Comma-separated state codes to filter by
`limit`	number	Optional	Maximum results (default: 50, max: 200)

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/growth/hot?states=TX&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1234,
      "name": "ABC Drilling Services",
      "city": "Houston",
      "state": "TX",
      "lead_score": 85,
      "score_change_30d": 12,
      "permit_count_ytd": 45,
      "review_velocity": 3.2
    }
  ],
  "meta": {
    "total": 45,
    "limit": 50
  }
}

GET/growth/trending

Get companies with accelerating growth (score increasing ≥10 points in 30 days).

Query Parameters

Name	Type	Required	Description
`states`	string	Optional	Comma-separated state codes to filter by
`limit`	number	Optional	Maximum results (default: 50, max: 200)

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/growth/trending?states=TX&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1235,
      "name": "XYZ Wells Inc",
      "city": "Dallas",
      "state": "TX",
      "lead_score": 72,
      "score_change_30d": 18,
      "trend_direction": "up"
    }
  ],
  "meta": {
    "total": 120,
    "limit": 50
  }
}

GET/growth/yoy

Get companies with significant year-over-year permit growth.

Query Parameters

Name	Type	Required	Description
`states`	string	Optional	Comma-separated state codes to filter by
`limit`	number	Optional	Maximum results (default: 50, max: 200)

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/growth/yoy?states=TX&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1236,
      "name": "Premier Drilling Co",
      "city": "Midland",
      "state": "TX",
      "permits_this_year": 120,
      "permits_last_year": 85,
      "yoy_growth_pct": 41.2
    }
  ],
  "meta": {
    "total": 85,
    "limit": 50
  }
}

Sales

Manage your sales team and territories. Assign reps to territories by state to organize your coverage.

GET/reps

List all sales reps in your organization.

Query Parameters

Name	Type	Required	Description
`status`	string	Optional	Filter by status: active, inactive, or all
`include_stats`	boolean	Optional	Include company and demo counts

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/reps?status=active&include_stats=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "name": "John Smith",
      "email": "john@company.com",
      "phone": "(555) 123-4567",
      "title": "Senior Sales Rep",
      "status": "active",
      "territory_name": "Texas Region",
      "states": [
        "TX",
        "OK"
      ],
      "company_count": 45,
      "demos_scheduled": 3
    }
  ]
}

POST/reps

Create a new sales rep.

Request Body

Sales rep details

{
  "name": "Jane Doe",
  "email": "jane@company.com",
  "phone": "(555) 987-6543",
  "title": "Sales Representative",
  "status": "active"
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/reps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@company.com", "title": "Sales Representative"}'

Response

{
  "data": {
    "id": 2,
    "name": "Jane Doe",
    "email": "jane@company.com",
    "phone": "(555) 987-6543",
    "title": "Sales Representative",
    "status": "active",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

GET/territories

List all territories in your organization with assigned reps.

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/territories" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "name": "Texas Region",
      "rep_id": 1,
      "rep_name": "John Smith",
      "states": [
        "TX",
        "OK",
        "NM"
      ],
      "company_count": 1250,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

POST/territories

Create a new territory with state assignments. Each state can only be assigned to one territory.

Request Body

Territory configuration

{
  "name": "Southwest Region",
  "rep_id": 2,
  "states": [
    "AZ",
    "NV",
    "UT"
  ]
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/territories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Southwest Region", "rep_id": 2, "states": ["AZ", "NV", "UT"]}'

Response

{
  "data": {
    "id": 2,
    "name": "Southwest Region",
    "rep_id": 2,
    "rep_name": "Jane Doe",
    "states": [
      "AZ",
      "NV",
      "UT"
    ],
    "company_count": 0,
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Alerts

Configure alerts to be notified when companies hit growth thresholds or show significant score changes.

GET/alerts

Get growth alert configurations for your organization.

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "alert_type": "hot_lead",
      "enabled": true,
      "threshold_value": 70,
      "frequency": "daily",
      "filter_states": [
        "TX",
        "OK"
      ]
    },
    {
      "id": 2,
      "alert_type": "score_spike",
      "enabled": false,
      "threshold_value": 15,
      "frequency": "realtime",
      "filter_states": null
    }
  ]
}

PUT/alerts

Update a growth alert configuration.

Request Body

Alert update payload

{
  "alert_type": "hot_lead",
  "enabled": true,
  "threshold_value": 75,
  "frequency": "daily",
  "filter_states": [
    "TX",
    "OK",
    "LA"
  ]
}

Example

curl -X PUT "https://enterprise.drillerdb.com/api/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alert_type": "hot_lead", "enabled": true, "threshold_value": 75}'

Response

{
  "data": {
    "id": 1,
    "alert_type": "hot_lead",
    "enabled": true,
    "threshold_value": 75,
    "frequency": "daily",
    "filter_states": [
      "TX",
      "OK",
      "LA"
    ],
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

Weather

County-level weather disruption intelligence, scored daily against a 5-year per-county baseline so anomalies (not just absolute conditions) trigger. Sourced from Visual Crossing, which aggregates NWS / NOAA observations. Use these endpoints to drive marketing journeys, sales-timing workflows, and field-operations alerts.

GET/weather/disruptions

Returns counties currently flagged as weather-disrupted, with affected company counts and centroid coordinates. Scored daily against a 5-year per-county baseline so anomalies (not just absolute conditions) trigger. Defaults to the most recent score date if no date param is provided.

Query Parameters

Name	Type	Required	Description
`date`	string	Optional	Score date in YYYY-MM-DD format. Defaults to most recent.

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/weather/disruptions?date=2026-04-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "fips_code": "48113",
      "county_name": "Dallas",
      "state": "TX",
      "triggers": [
        "Severe Weather",
        "High Wind"
      ],
      "conditions": {
        "tempmax": 92.3,
        "windgust": 58.1,
        "precip": 1.42
      },
      "company_count": 142,
      "centroid_lat": 32.7767,
      "centroid_lng": -96.797
    }
  ],
  "meta": {
    "date": "2026-04-15",
    "total_disrupted_counties": 87,
    "total_affected_companies": 3870
  }
}

GET/weather/disruptions/summary

Returns aggregated disruption stats for a given day: total disrupted counties, total affected companies, and breakdowns by trigger type and by state. Useful for headline metrics and dashboards.

Query Parameters

Name	Type	Required	Description
`date`	string	Optional	Score date in YYYY-MM-DD format. Defaults to most recent.

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/weather/disruptions/summary?date=2026-04-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "date": "2026-04-15",
  "total_disrupted_counties": 87,
  "total_affected_companies": 3870,
  "by_trigger": {
    "Severe Weather": {
      "counties": 42,
      "companies": 1820
    },
    "High Wind": {
      "counties": 38,
      "companies": 1605
    },
    "Heavy Rain": {
      "counties": 19,
      "companies": 720
    },
    "Lightning Risk": {
      "counties": 12,
      "companies": 410
    }
  },
  "by_state": [
    {
      "state": "TX",
      "counties": 22,
      "companies": 980
    },
    {
      "state": "OK",
      "counties": 14,
      "companies": 612
    },
    {
      "state": "KS",
      "counties": 9,
      "companies": 350
    }
  ]
}

GET/weather/disruptions/history

Returns daily aggregates of disrupted counties and trigger breakdowns over a rolling window. Useful for trend charts and seasonal pattern analysis. Maximum 180 days.

Query Parameters

Name	Type	Required	Description
`days`	integer	Optional	Window size in days (default: 30, max: 180).
`state`	string	Optional	Filter to a single state by 2-letter code.

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/weather/disruptions/history?days=30&state=TX" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "date": "2026-04-13",
      "counties": 64,
      "by_trigger": {
        "Severe Weather": 28,
        "High Wind": 22,
        "Heavy Rain": 14
      }
    },
    {
      "date": "2026-04-14",
      "counties": 71,
      "by_trigger": {
        "Severe Weather": 33,
        "High Wind": 25,
        "Lightning Risk": 13
      }
    },
    {
      "date": "2026-04-15",
      "counties": 87,
      "by_trigger": {
        "Severe Weather": 42,
        "High Wind": 38,
        "Heavy Rain": 19,
        "Lightning Risk": 12
      }
    }
  ],
  "days": 30
}

GET/weather/disruptions/companies

Returns drilling and pump-service companies located in a single disrupted county, identified by 5-digit FIPS code. Includes county-level trigger and condition metadata plus the 5-year baselines used to detect anomalies.

Query Parameters

Name	Type	Required	Description
`fips`	string	Required	5-digit FIPS code (state + county).

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/weather/disruptions/companies?fips=48113" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1234,
      "name": "ABC Drilling Services",
      "city": "Houston",
      "state": "TX",
      "phone": "(713) 555-1234",
      "email": "contact@abcdrilling.com"
    }
  ],
  "meta": {
    "fips_code": "48113",
    "county_name": "Dallas",
    "state": "TX",
    "triggers": [
      "Severe Weather",
      "High Wind"
    ],
    "total": 142,
    "conditions": {
      "tempmax": 92.3,
      "windgust": 58.1,
      "precip": 1.42
    },
    "baselines": {
      "temp_low_p5": 28.4,
      "temp_high_p95": 96.8,
      "wind_p95": 42,
      "precip_p95": 1.2,
      "snow_p95": 0,
      "data_days": 1825
    }
  }
}

GET/weather/disruptions/all-companies

Returns ALL companies across every disrupted county for a given day, with lead scores and pipeline status. Supports rich filtering (state, trigger type, minimum lead score, has email or phone) and sorting. Designed for sales-targeting workflows like "who in the office today should we call."

Query Parameters

Name	Type	Required	Description
`date`	string	Optional	Score date in YYYY-MM-DD format. Defaults to most recent.
`state`	string	Optional	Filter by state, comma-separated for multiple.
`trigger`	string	Optional	Filter by trigger type, comma-separated for multiple. Valid values: Severe Weather, Heavy Rain, Heavy Snow, Ice Storm, High Wind, Extreme Cold, Extreme Heat, Lightning Risk.
`min_score`	integer	Optional	Minimum lead score (0-100).
`has_email`	boolean	Optional	Only return companies with an email on file. Pass 1 to enable.
`has_phone`	boolean	Optional	Only return companies with a phone on file. Pass 1 to enable.
`not_contacted`	boolean	Optional	Only return companies not contacted in the last 7 days. Pass 1 to enable.
`sort`	string	Optional	Sort field: lead_score, name, state, size_bucket, last_contacted_at. Default: lead_score.
`order`	string	Optional	Sort order: asc or desc. Default: desc.
`limit`	integer	Optional	Results per page (default: 200, max: 1000).
`offset`	integer	Optional	Pagination offset.

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/weather/disruptions/all-companies?state=TX&trigger=Severe%20Weather&min_score=60&has_phone=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1234,
      "name": "ABC Drilling Services",
      "city": "Dallas",
      "state": "TX",
      "phone": "(214) 555-1234",
      "email": "contact@abcdrilling.com",
      "size_bucket": "medium",
      "county_fips": "48113",
      "county_name": "Dallas",
      "triggers": [
        "Severe Weather",
        "High Wind"
      ],
      "conditions": {
        "tempmax": 92.3,
        "windgust": 58.1
      },
      "lead_score": 78,
      "last_contacted_at": "2026-04-08T14:22:00Z",
      "pipeline_stage_id": 3
    }
  ],
  "meta": {
    "date": "2026-04-15",
    "total": 3870,
    "limit": 200,
    "offset": 0,
    "disrupted_states": [
      "TX",
      "OK",
      "KS",
      "NM",
      "AR"
    ]
  }
}

Lightning

Verify whether a documented lightning strike occurred near a pump installation, well site, or any other location of interest. Powered by Xweather's global lightning network, with cloud-to-ground strike data including timestamp, peak amperage, polarity, and sub-kilometer median location accuracy per the vendor. Useful for warranty claim adjudication, root-cause analysis, and surge-protection campaign targeting.

POST/lightning/verify

Verifies whether a documented lightning strike occurred near a specified location on a given date. Returns a verdict (confirmed, plausible, inconclusive, no_evidence) plus the closest and strongest strikes detected within a 16 km search radius and a 4-day window centered on the claim date. Powered by Xweather's global lightning network. Useful for warranty claim adjudication and root-cause analysis. Each call is logged for audit purposes.

Request Body

Strike verification payload

{
  "lat": 32.7767,
  "lon": -96.797,
  "claim_date": "2026-04-15",
  "address": "123 Main St, Dallas TX 75202",
  "well_id": 5491823,
  "notes": "Customer reports controller failure morning after storm."
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/lightning/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat": 32.7767, "lon": -96.7970, "claim_date": "2026-04-15"}'

Response

{
  "data": {
    "verdict": "confirmed",
    "verdict_description": "3 cloud-to-ground strike(s) detected within 500m of the location. Equipment damage from direct strike or ground current is highly plausible.",
    "location": {
      "latitude": 32.7767,
      "longitude": -96.797,
      "address": "123 Main St, Dallas TX 75202"
    },
    "claim_date": "2026-04-15",
    "search_window": {
      "from": "2026-04-14",
      "to": "2026-04-17"
    },
    "strikes": {
      "direct": [
        {
          "timestamp": "2026-04-15T18:42:13Z",
          "latitude": 32.777,
          "longitude": -96.7972,
          "distance_km": 0.31,
          "peak_current_ka": 28.4,
          "type": "CG",
          "polarity": "-",
          "sensor_count": 8
        }
      ],
      "nearby": [],
      "area": []
    },
    "summary": {
      "total_strikes": 3,
      "closest_strike_km": 0.31,
      "closest_strike_amps": 28.4,
      "strongest_strike_amps": 32.7
    },
    "well_match": {
      "well_id": 5491823,
      "well_state": "TX",
      "owner_name": "John Smith"
    }
  }
}

GET/lightning/search

Returns the raw list of cloud-to-ground and intra-cloud strikes detected within a radius of a point over a date range. No verdict logic - this is the underlying strike feed. Use this when you need every strike (e.g. for mapping or counting), and use /lightning/verify when you want a warranty-style yes/no answer. Maximum search radius is 50 km.

Query Parameters

Name	Type	Required	Description
`lat`	number	Required	Latitude of the search point.
`lon`	number	Required	Longitude of the search point.
`from`	string	Required	Start of search window (YYYY-MM-DD).
`to`	string	Required	End of search window (YYYY-MM-DD).
`radius_km`	number	Optional	Search radius in kilometers (default: 1.6, max: 50).

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/lightning/search?lat=32.7767&lon=-96.7970&from=2026-04-14&to=2026-04-17&radius_km=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "timestamp": "2026-04-15T18:42:13Z",
      "latitude": 32.777,
      "longitude": -96.7972,
      "distance_km": 0.31,
      "peak_current_ka": 28.4,
      "type": "CG",
      "polarity": "-",
      "sensor_count": 8
    },
    {
      "timestamp": "2026-04-15T18:43:01Z",
      "latitude": 32.7745,
      "longitude": -96.7989,
      "distance_km": 0.42,
      "peak_current_ka": 32.7,
      "type": "CG",
      "polarity": "-",
      "sensor_count": 9
    }
  ],
  "meta": {
    "lat": 32.7767,
    "lon": -96.797,
    "radius_km": 1.6,
    "from": "2026-04-14",
    "to": "2026-04-17",
    "total_strikes": 2
  }
}

GET/lightning/history

Returns the audit log of every Lightning verification call your organization has made: who ran it, location, claim date, verdict, and closest-strike summary. Paginated.

Query Parameters

Name	Type	Required	Description
`page`	integer	Optional	Page number (default: 1).
`limit`	integer	Optional	Results per page (default: 25, max: 100).

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/lightning/history?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 482,
      "user_name": "Jane Operations",
      "latitude": 32.7767,
      "longitude": -96.797,
      "address": "123 Main St, Dallas TX 75202",
      "well_id": 5491823,
      "claim_date": "2026-04-15",
      "verdict": "confirmed",
      "strikes_found": 3,
      "closest_strike_km": 0.31,
      "closest_strike_amps": 28.4,
      "notes": "Customer reports controller failure morning after storm.",
      "created_at": "2026-04-16T09:14:22Z"
    }
  ],
  "meta": {
    "total": 38,
    "page": 1,
    "limit": 25,
    "total_pages": 2
  }
}

MCP Server

Connect Claude, Cursor, or any MCP-compatible AI client directly to DrillerDB Enterprise. Your team can ask natural-language questions like "show me my top 20 prospects in Texas with permits in the last 90 days" or "which companies in my Austin territory had a market signal this week," and the agent answers using live, tenant-scoped data — no glue code, no scheduled exports.

Server URL

https://enterprise.drillerdb.com/api/mcp

Authentication

OAuth 2.1 with PKCE. The server publishes standard discovery metadata at:

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server

Required scope: mcp:read:enterprise. Most MCP clients handle the OAuth dance automatically — you just paste the server URL and approve access.

Claude (claude.ai or Claude Desktop)

Settings > Connectors > Add Custom Connector. Paste the server URL, approve in the OAuth popup, and DrillerDB tools appear in your conversations.

https://enterprise.drillerdb.com/api/mcp

Cursor / Other MCP Clients

Add an HTTP-streamable MCP server with the URL below. The client will guide you through the OAuth login.

https://enterprise.drillerdb.com/api/mcp

Available Tools

All tools are read-only and tenant-scoped to your organization's allowed states and verticals. Every invocation is recorded to the audit log.

Tool	What it does	Key inputs
`search_companies`	Search the prospect directory by state, vertical, size, lead score, employee count, well-permit activity, and free-text name. Up to 100 results.	`q`, `state`, `vertical`, `size_bucket`, `min_score`, `has_recent_permits`, `min_wells_last_90d`, `limit`, `offset`, `sort`
`get_company_detail`	Full profile for a single company: contact info, branches, contacts, equipment, market signals, lead score breakdown.	`company_id`
`get_lead_score`	Lead score and the contributing sub-scores (permit recency / volume / growth, online presence, company profile, relationship) plus 30/90/365-day permit counts.	`company_id`
`search_contacts`	Search decision-maker contacts (owners, executives, managers, sales, purchasing) by name, title, email, role, or company.	`q`, `company_id`, `role`, `has_email`, `has_phone`
`list_my_lists`	Return the saved lists in your organization (static and smart), with company counts and metadata.	`limit`
`get_list_companies`	Return the companies inside a saved list, with lead score and added-at metadata.	`list_id`, `limit`, `offset`
`list_my_territories`	List the territories assigned to the calling rep, or all territories org-wide for managers.	`all`
`list_recent_market_signals`	Recent buying-intent signals (equipment purchases, hiring spikes, expansion, etc.) in your territory, with company match and confidence.	`signal_type`, `states`, `days_back`, `status`
`top_companies_by_revenue`	Rank drilling companies by permit-derived total revenue estimate. Returns ranked revenue, year, methodology, confidence, total wells, and lead score.	`states`, `vertical`, `min_revenue`, `estimate_year`, `limit`
`top_companies_by_wells`	Rank companies by wells drilled. Three metric options: confirmed (curated aggregate), permits_total (every public permit), permits_recent (last 365 days).	`metric`, `states`, `vertical`, `size_bucket`, `min_wells`

Schemas are validated at runtime; pass --describe through your MCP client to see the full Zod schema for any tool.

Admin

Manage API keys and team members. These endpoints require admin privileges.

GET/api-keys

List all API keys for your organization (masked). Shows key preview only.

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "name": "Production Key",
      "key_preview": "drdb_************************************",
      "is_active": true,
      "created_at": "2025-01-01T00:00:00Z",
      "last_used_at": "2025-01-15T10:30:00Z",
      "created_by": {
        "id": 1,
        "name": "John Smith"
      }
    }
  ],
  "meta": {
    "total": 2,
    "active": 1
  }
}

POST/api-keys

Create a new API key (admin only). The full key is only shown once upon creation.

Request Body

API key name

{
  "name": "Integration Key"
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Integration Key"}'

Response

{
  "data": {
    "key": "drdb_abc123def456...",
    "key_preview": "drdb_abc************************************",
    "name": "Integration Key"
  },
  "message": "API key created successfully. Save this key now - it cannot be retrieved again.",
  "warning": "This is the only time you will see the full API key. Store it securely."
}

GET/team/invites

List pending team invitations (admin only).

Example

curl -X GET "https://enterprise.drillerdb.com/api/v1/team/invites" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "email": "newuser@company.com",
      "role": "sales_rep",
      "status": "pending",
      "created_at": "2025-01-15T10:00:00Z",
      "expires_at": "2025-01-22T10:00:00Z",
      "invited_by": {
        "id": 1,
        "name": "Admin User"
      }
    }
  ]
}

POST/team/invites

Invite a new team member (admin only). Roles: admin, sales_rep, api_user.

Request Body

Invitation details

{
  "email": "newuser@company.com",
  "role": "sales_rep"
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/team/invites" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "newuser@company.com", "role": "sales_rep"}'

Response

{
  "message": "Invite created successfully",
  "inviteUrl": "https://enterprise.drillerdb.com/invite/abc123...",
  "expiresAt": "2025-01-22T10:00:00Z"
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure.

Code	Description
200	Success
201	Created successfully
400	Bad request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Access denied
404	Not found - Resource missing
429	Rate limit exceeded
500	Server error

Error Response Format

{
  "error": "Bad Request",
  "message": "Invalid export format."
}

Changelog

Recent updates to the DrillerDB API.

v1.1.0January 13, 2026

Growth Intelligence & Sales

Growth Intelligence API: Hot leads, trending, YoY
Company contacts with decision makers
Company reviews with ratings
Satellite imagery & equipment detection
Sales rep & territory management
Growth alerts & API key management

v1.0.0December 30, 2025

Initial Release

Company search with filters and pagination
Company detail endpoint
Geographic search for maps
Lists management (CRUD)
Export jobs (CSV, Excel, JSON)