Get Lookup Result

GET

api

external

company-lookup

{jobId}

result

curl -X GET "https://api.gethuntd.com/api/v1/external/company-lookup/job_1705596234567_a1b2c3d4/result" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"

const jobId = 'job_1705596234567_a1b2c3d4';

const response = await fetch(
  `https://api.gethuntd.com/api/v1/external/company-lookup/${jobId}/result`,
  { headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
);

const data = await response.json();

if (response.status === 200) {
  console.log('Job completed');
} else if (response.status === 202) {
  console.log('Job still processing...');
}

import requests
import os

job_id = 'job_1705596234567_a1b2c3d4'

response = requests.get(
    f'https://api.gethuntd.com/api/v1/external/company-lookup/{job_id}/result',
    headers={'X-API-Key': os.environ['HUNTD_API_KEY']}
)

data = response.json()
print(f"Status: {data['status']}")

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "success",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "job_title": "Senior Software Engineer",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "company": "Example Corp",
      "company_domain": "example.com",
      "verifications": [
        {
          "source": "source_name",
          "isVerified": true,
          "verifiedAt": "2024-01-18T12:25:00.000Z",
          "status": "verified"
        }
      ]
    }
  ],
  "credits_used": 1,
  "created_at": "2024-01-18T12:30:00.000Z"
}

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "status": "processing",
  "message": "Job is still processing. Please try again later."
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Job ID is required"
  }
}

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

{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You do not have access to this job"
  }
}

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "error",
  "contacts": [],
  "credits_used": 0,
  "created_at": "2024-01-18T12:30:00.000Z",
  "error_code": "COMPANY_NOT_FOUND",
  "message": "We could not find a company for this domain. Please verify the domain."
}

curl -X GET "https://api.gethuntd.com/api/v1/external/company-lookup/job_1705596234567_a1b2c3d4/result" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"

const jobId = 'job_1705596234567_a1b2c3d4';

const response = await fetch(
  `https://api.gethuntd.com/api/v1/external/company-lookup/${jobId}/result`,
  { headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
);

const data = await response.json();

if (response.status === 200) {
  console.log('Job completed');
} else if (response.status === 202) {
  console.log('Job still processing...');
}

import requests
import os

job_id = 'job_1705596234567_a1b2c3d4'

response = requests.get(
    f'https://api.gethuntd.com/api/v1/external/company-lookup/{job_id}/result',
    headers={'X-API-Key': os.environ['HUNTD_API_KEY']}
)

data = response.json()
print(f"Status: {data['status']}")

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "success",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "job_title": "Senior Software Engineer",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "company": "Example Corp",
      "company_domain": "example.com",
      "verifications": [
        {
          "source": "source_name",
          "isVerified": true,
          "verifiedAt": "2024-01-18T12:25:00.000Z",
          "status": "verified"
        }
      ]
    }
  ],
  "credits_used": 1,
  "created_at": "2024-01-18T12:30:00.000Z"
}

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "status": "processing",
  "message": "Job is still processing. Please try again later."
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Job ID is required"
  }
}

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

{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You do not have access to this job"
  }
}

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "error",
  "contacts": [],
  "credits_used": 0,
  "created_at": "2024-01-18T12:30:00.000Z",
  "error_code": "COMPANY_NOT_FOUND",
  "message": "We could not find a company for this domain. Please verify the domain."
}

Overview

Retrieve the result of a company lookup job.

Path Parameters

Parameter	Type	Required	Description
`jobId`	string	Yes	Job ID from the lookup submission

Response Status Codes

HTTP Code	Status	Description
200	`success`	Job completed
202	`processing`	Job still processing
202	`queued`	Job waiting for daily limit reset
500	`error`	Job failed

Response Fields (Success/Error)

Field	Type	Description
`job_id`	string	The job identifier
`domain`	string	The domain that was looked up
`source`	string	Data source used for the lookup
`status`	string	Job status: `success` or `error`
`contacts`	array	Array of contacts found
`credits_used`	integer	Credits consumed (1 per contact)
`created_at`	string	ISO 8601 timestamp
`error_code`	string	Error code (only when status is `error`)
`message`	string	Error message (only when status is `error`)

Response Fields (Processing)

When the job is still processing (not yet in database):

Field	Type	Description
`job_id`	string	The job identifier
`status`	string	Always `processing`
`message`	string	Status message

Response Fields (Queued)

When the job is queued due to daily limit:

Field	Type	Description
`job_id`	string	The job identifier
`domain`	string	The domain that was looked up
`source`	string	Data source used for the lookup
`status`	string	Always `queued`
`contacts`	array	Empty array
`credits_used`	integer	0
`created_at`	string	ISO 8601 timestamp
`message`	string	Status message
`scheduled_processing_time`	string	When the job will be processed (ISO 8601)

Contact Object

Each contact in the contacts array contains:

Field	Type	Description
`first_name`	string	Contact’s first name
`last_name`	string	Contact’s last name
`email`	string	Contact’s email address
`job_title`	string	Contact’s job title
`linkedin_url`	string	LinkedIn profile URL
`company`	string	Company name
`company_domain`	string	Company domain
`verifications`	array	Verification status for each source

Verification Object

Each verification in the verifications array contains:

Field	Type	Description
`source`	string	Source name
`isVerified`	boolean/null	`true` if verified, `false` if not, `null` if pending
`verifiedAt`	string	ISO 8601 timestamp of when verification was performed
`status`	string	Status message
`error`	string	Error message (if verification failed)

Only contacts with isVerified: true for the requested source are returned in the response.

Polling Strategy

When polling for results:

Start polling after 5-10 seconds
Use exponential backoff (e.g., 5s, 10s, 20s)
Stop after 5 minutes

async function pollForResult(jobId, maxAttempts = 10) {
  const baseDelay = 5000;

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.gethuntd.com/api/v1/external/company-lookup/${jobId}/result`,
      { headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
    );

    if (response.status !== 202) {
      return await response.json();
    }

    await new Promise(r => setTimeout(r, baseDelay * Math.pow(2, attempt)));
  }

  throw new Error('Job timed out');
}

Errors

HTTP	Error Code	Description
400	`INVALID_REQUEST`	Job ID is required
401	`INVALID_API_KEY`	API key is missing, invalid, malformed, or disabled
403	`ACCESS_DENIED`	You do not have access to this job
500	`COMPANY_NOT_FOUND`	We could not find a company for this domain. Please verify the domain.
500	`INSUFFICIENT_CREDITS`	Insufficient credits to complete this request. Please contact administrator.
500	`INTERNAL_ERROR`	Something went wrong. Please try again.

Authorizations

X-API-Key

string

header

required

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

Path Parameters

jobId

string

required

The job ID returned from the company lookup submission

Example:

"job_1705596234567_a1b2c3d4"

Response

Job completed successfully

job_id

string

Example:

"job_1705596234567_a1b2c3d4"

domain

string

Example:

"example.com"

source

string

Data source used for the lookup

status

enum<string>

Job result status

Available options:

success,

error

contacts

object[]

Array of contacts found at the company

Show child attributes

credits_used

integer

Number of credits consumed (1 credit per contact)

Example:

5

created_at

string<date-time>

message

string

Status message (for error status)

error_code

string

Error code if status is error

API OverviewIntroduction to the Huntd External API

curl -X GET "https://api.gethuntd.com/api/v1/external/company-lookup/job_1705596234567_a1b2c3d4/result" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"

const jobId = 'job_1705596234567_a1b2c3d4';

const response = await fetch(
  `https://api.gethuntd.com/api/v1/external/company-lookup/${jobId}/result`,
  { headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
);

const data = await response.json();

if (response.status === 200) {
  console.log('Job completed');
} else if (response.status === 202) {
  console.log('Job still processing...');
}

import requests
import os

job_id = 'job_1705596234567_a1b2c3d4'

response = requests.get(
    f'https://api.gethuntd.com/api/v1/external/company-lookup/{job_id}/result',
    headers={'X-API-Key': os.environ['HUNTD_API_KEY']}
)

data = response.json()
print(f"Status: {data['status']}")

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "success",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "job_title": "Senior Software Engineer",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "company": "Example Corp",
      "company_domain": "example.com",
      "verifications": [
        {
          "source": "source_name",
          "isVerified": true,
          "verifiedAt": "2024-01-18T12:25:00.000Z",
          "status": "verified"
        }
      ]
    }
  ],
  "credits_used": 1,
  "created_at": "2024-01-18T12:30:00.000Z"
}

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "status": "processing",
  "message": "Job is still processing. Please try again later."
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Job ID is required"
  }
}

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

{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You do not have access to this job"
  }
}

{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "error",
  "contacts": [],
  "credits_used": 0,
  "created_at": "2024-01-18T12:30:00.000Z",
  "error_code": "COMPANY_NOT_FOUND",
  "message": "We could not find a company for this domain. Please verify the domain."
}

Getting started

Company Lookup

Overview

Get Lookup Result

Overview

Path Parameters

Response Status Codes

Response Fields (Success/Error)

Response Fields (Processing)

Response Fields (Queued)

Contact Object

Verification Object

Polling Strategy

Errors

Authorizations

Path Parameters

Response

​Overview

​Path Parameters

​Response Status Codes

​Response Fields (Success/Error)

​Response Fields (Processing)

​Response Fields (Queued)

​Contact Object

​Verification Object

​Polling Strategy

​Errors

Authorizations

Path Parameters

Response

Overview

Path Parameters

Response Status Codes

Response Fields (Success/Error)

Response Fields (Processing)

Response Fields (Queued)

Contact Object

Verification Object

Polling Strategy

Errors