Skip to main content
POST
/
api
/
v1
/
external
/
company-lookup
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"}'

{
  "success": true,
  "data": {
    "job_id": "job_1705596234567_a1b2c3d4",
    "domain": "example.com",
    "sources": [
      "source_name"
    ],
    "scheduled_for": "immediate"
  }
}

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

{
  "success": true,
  "data": {
    "job_id": "job_1705596234567_a1b2c3d4",
    "domain": "example.com",
    "sources": [
      "source_name"
    ],
    "scheduled_for": "immediate"
  }
}

​
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

FieldTypeRequiredDescription
domainstringYesCompany domain (e.g., example.com)
sourcesstring[]NoArray of source names to query. Defaults to all sources assigned to your API key.
webhook_urlstringNoHTTPS 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

HTTPError CodeDescription
400DOMAIN_REQUIREDDomain is required
400INVALID_DOMAIN_FORMATInvalid domain format. Expected: example.com
400INVALID_REQUESTZod validation error
400INVALID_WEBHOOK_URLWebhook URL validation failed (see below)
401INVALID_API_KEYAPI key is missing, invalid, malformed, or disabled
402MONTHLY_LIMIT_EXCEEDEDMonthly credit limit exceeded. Please contact administrator.
403SOURCE_ACCESS_DENIEDAccess 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

Authorizations

​
X-API-Key
string
header
required

API key in format: hntd_{id}_{secret}

Body

application/json
​
domain
string
required

Company domain to search

Example:

"example.com"

​
sources
string[]

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
string<uri>

HTTPS URL to receive callback when job completes

Example:

"https://yourapp.com/webhooks/huntd"

Response

Job accepted

​
success
enum<boolean>
Available options:
true,
false
​
data
object
​
message
string

Additional information