> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gethuntd.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit Company Lookup
> Submit an asynchronous company lookup job by domain. Returns a job ID to poll for results.
```bash cURL theme={null}
curl -X POST https://api.gethuntd.com/api/v1/external/company-lookup \
-H "Content-Type: application/json" \
-H "X-API-Key: hntd_abc12345_yoursecretkey" \
-d '{"domain": "example.com"}'
```
```bash cURL with webhook theme={null}
curl -X POST https://api.gethuntd.com/api/v1/external/company-lookup \
-H "Content-Type: application/json" \
-H "X-API-Key: hntd_abc12345_yoursecretkey" \
-d '{
"domain": "example.com",
"webhook_url": "https://yourapp.com/webhooks/huntd"
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.gethuntd.com/api/v1/external/company-lookup', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.HUNTD_API_KEY
},
body: JSON.stringify({ domain: 'example.com' })
});
const { data } = await response.json();
console.log('Job ID:', data.job_id);
```
```python Python theme={null}
import requests
import os
response = requests.post(
'https://api.gethuntd.com/api/v1/external/company-lookup',
headers={
'Content-Type': 'application/json',
'X-API-Key': os.environ['HUNTD_API_KEY']
},
json={'domain': 'example.com'}
)
data = response.json()
print(f"Job ID: {data['data']['job_id']}")
```
```json 202 theme={null}
{
"success": true,
"data": {
"job_id": "job_1705596234567_a1b2c3d4",
"domain": "example.com",
"sources": [
"source_name"
],
"scheduled_for": "immediate"
}
}
```
```json 400 theme={null}
{
"success": false,
"error": {
"code": "DOMAIN_REQUIRED",
"message": "Domain is required"
}
}
```
```json 401 theme={null}
{
"success": false,
"error": {
"code": "INVALID_API_KEY",
"message": "API key is missing, invalid, malformed, or disabled"
}
}
```
```json 402 theme={null}
{
"success": false,
"error": {
"code": "MONTHLY_LIMIT_EXCEEDED",
"message": "Monthly credit limit exceeded. Please contact administrator."
}
}
```
```json 403 theme={null}
{
"success": false,
"error": {
"code": "SOURCE_ACCESS_DENIED",
"message": "Access denied to sources: source_name"
}
}
```
## Overview
Submit an asynchronous company lookup job by domain. This is an async operation:
1. Submit a lookup request with a domain
2. Receive a job ID immediately (202 Accepted)
3. Poll for results or receive them via webhook
## Request
| Field | Type | Required | Description |
| ------------- | --------- | -------- | --------------------------------------------------------------------------------- |
| `domain` | string | Yes | Company domain (e.g., `example.com`) |
| `sources` | string\[] | No | Array of source names to query. Defaults to all sources assigned to your API key. |
| `webhook_url` | string | No | HTTPS URL to receive callback when job completes |
## Response
Returns `202 Accepted` with a job ID. See the response panel for examples of all status codes.
## Scheduling
* `immediate` - Job will process right away
* `delayed_24h` - Job queued due to daily limit (will process when limit resets)
## Errors
| HTTP | Error Code | Description |
| ---- | ------------------------ | ------------------------------------------------------------ |
| 400 | `DOMAIN_REQUIRED` | Domain is required |
| 400 | `INVALID_DOMAIN_FORMAT` | Invalid domain format. Expected: example.com |
| 400 | `INVALID_REQUEST` | Zod validation error |
| 400 | `INVALID_WEBHOOK_URL` | Webhook URL validation failed (see below) |
| 401 | `INVALID_API_KEY` | API key is missing, invalid, malformed, or disabled |
| 402 | `MONTHLY_LIMIT_EXCEEDED` | Monthly credit limit exceeded. Please contact administrator. |
| 403 | `SOURCE_ACCESS_DENIED` | Access denied to sources: \[list] |
### Webhook URL Validation
The `INVALID_WEBHOOK_URL` error may return one of these messages:
* Invalid URL format
* Webhook URL must use HTTPS
* Localhost URLs are not allowed
* Webhook URL resolves to a private IP address
* Webhook URL is a private IP address
## OpenAPI
````yaml POST /api/v1/external/company-lookup
openapi: 3.0.3
info:
title: Huntd External API
version: 1.0.0
description: >-
The Huntd External API provides programmatic access to company contact
lookup services.
contact:
name: Huntd Support
email: support@gethuntd.com
servers:
- url: https://api.gethuntd.com
description: Production API
security:
- ApiKeyAuth: []
paths:
/api/v1/external/company-lookup:
post:
tags:
- Company Lookup
summary: Submit Company Lookup
description: >-
Submit an asynchronous company lookup job by domain. Returns a job ID to
poll for results.
operationId: createCompanyLookup
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookupRequest'
examples:
basic:
summary: Basic lookup
value:
domain: example.com
withWebhook:
summary: With webhook callback
value:
domain: example.com
webhook_url: https://yourapp.com/webhooks/huntd
responses:
'202':
description: Job accepted
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookupJobResponse'
example:
success: true
data:
job_id: job_1705596234567_a1b2c3d4
domain: example.com
sources:
- source_name
scheduled_for: immediate
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitLookupError'
example:
success: false
error:
code: DOMAIN_REQUIRED
message: Domain is required
'401':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitLookupError'
example:
success: false
error:
code: INVALID_API_KEY
message: API key is missing, invalid, malformed, or disabled
'402':
description: Monthly limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitLookupError'
example:
success: false
error:
code: MONTHLY_LIMIT_EXCEEDED
message: Monthly credit limit exceeded. Please contact administrator.
'403':
description: Source access denied
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitLookupError'
example:
success: false
error:
code: SOURCE_ACCESS_DENIED
message: 'Access denied to sources: source_name'
components:
schemas:
CompanyLookupRequest:
type: object
required:
- domain
properties:
domain:
type: string
description: Company domain to search
example: example.com
sources:
type: array
items:
type: string
description: >-
Optional array of source names to query. If not provided, uses all
sources assigned to your API key.
example:
- source_one
- source_two
webhook_url:
type: string
format: uri
description: HTTPS URL to receive callback when job completes
example: https://yourapp.com/webhooks/huntd
CompanyLookupJobResponse:
type: object
properties:
success:
type: boolean
enum:
- true
data:
type: object
properties:
job_id:
type: string
description: Unique job identifier
example: job_1705596234567_a1b2c3d4
domain:
type: string
example: example.com
sources:
type: array
items:
type: string
description: Sources that will be queried
example:
- source_one
- source_two
scheduled_for:
type: string
enum:
- immediate
- delayed_24h
description: When the job will process
webhook_url:
type: string
description: Masked webhook URL (if provided)
message:
type: string
description: Additional information
SubmitLookupError:
type: object
description: Error response for submit company lookup endpoint
properties:
success:
type: boolean
enum:
- false
error:
type: object
properties:
code:
type: string
enum:
- DOMAIN_REQUIRED
- INVALID_DOMAIN_FORMAT
- INVALID_REQUEST
- INVALID_WEBHOOK_URL
- INVALID_API_KEY
- MONTHLY_LIMIT_EXCEEDED
- SOURCE_ACCESS_DENIED
message:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'API key in format: hntd_{id}_{secret}'
````