Submit Company Lookup

POST

api

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

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

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);

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

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

{
  "success": false,
  "error": {
    "code": "DOMAIN_REQUIRED",
    "message": "Domain is required"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, malformed, or disabled"
  }
}

{
  "success": false,
  "error": {
    "code": "MONTHLY_LIMIT_EXCEEDED",
    "message": "Monthly credit limit exceeded. Please contact administrator."
  }
}

{
  "success": false,
  "error": {
    "code": "SOURCE_ACCESS_DENIED",
    "message": "Access denied to sources: source_name"
  }
}

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

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

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);

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

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

{
  "success": false,
  "error": {
    "code": "DOMAIN_REQUIRED",
    "message": "Domain is required"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, malformed, or disabled"
  }
}

{
  "success": false,
  "error": {
    "code": "MONTHLY_LIMIT_EXCEEDED",
    "message": "Monthly credit limit exceeded. Please contact administrator."
  }
}

{
  "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:

Submit a lookup request with a domain
Receive a job ID immediately (202 Accepted)
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

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

data

object

Show child attributes

message

string

Additional information

Get Lookup ResultRetrieve the result of a company lookup job.

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

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

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);

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

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

{
  "success": false,
  "error": {
    "code": "DOMAIN_REQUIRED",
    "message": "Domain is required"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, malformed, or disabled"
  }
}

{
  "success": false,
  "error": {
    "code": "MONTHLY_LIMIT_EXCEEDED",
    "message": "Monthly credit limit exceeded. Please contact administrator."
  }
}

{
  "success": false,
  "error": {
    "code": "SOURCE_ACCESS_DENIED",
    "message": "Access denied to sources: source_name"
  }
}

​Overview

​Request

​Response

​Scheduling

​Errors

​Webhook URL Validation

Authorizations

Body

Response

Overview

Request

Response

Scheduling

Errors

Webhook URL Validation