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

All API requests require authentication using a Bearer token. Include your API key in the Authorization header of every request.

Authorization Header

Authorization: Bearer your-api-key-here

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
`/growth/*`	60 requests	Per minute
`/exports`	10 requests	Per hour
`/lists`	100 requests	Per minute
`/reps, /territories`	60 requests	Per minute
`/api-keys`	10 requests	Per minute

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, territories, and pipeline. Assign reps to territories by state and track companies through your sales process.

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"
  }
}

POST/sales/pipeline

Update a company's position in your sales pipeline.

Request Body

Pipeline stage update

{
  "companyId": 1234,
  "stageId": 2
}

Example

curl -X POST "https://enterprise.drillerdb.com/api/v1/sales/pipeline" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyId": 1234, "stageId": 2}'

Response

{
  "success": true,
  "companyId": 1234,
  "stageId": 2
}

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"
  }
}

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": "ddb_************************************",
      "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": "ddb_abc123def456...",
    "key_preview": "ddb_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
Pipeline stage updates
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)