Skip to main content
GET
/
api
/
v1
/
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"

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

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

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

​
Overview

Retrieve the result of a company lookup job.

​
Path Parameters

ParameterTypeRequiredDescription
jobIdstringYesJob ID from the lookup submission

​
Response Status Codes

HTTP CodeStatusDescription
200successJob completed
202processingJob still processing
202queuedJob waiting for daily limit reset
500errorJob failed

​
Response Fields (Success/Error)

FieldTypeDescription
job_idstringThe job identifier
domainstringThe domain that was looked up
sourcestringData source used for the lookup
statusstringJob status: success or error
contactsarrayArray of contacts found
credits_usedintegerCredits consumed (1 per contact)
created_atstringISO 8601 timestamp
error_codestringError code (only when status is error)
messagestringError message (only when status is error)

​
Response Fields (Processing)

When the job is still processing (not yet in database):
FieldTypeDescription
job_idstringThe job identifier
statusstringAlways processing
messagestringStatus message

​
Response Fields (Queued)

When the job is queued due to daily limit:
FieldTypeDescription
job_idstringThe job identifier
domainstringThe domain that was looked up
sourcestringData source used for the lookup
statusstringAlways queued
contactsarrayEmpty array
credits_usedinteger0
created_atstringISO 8601 timestamp
messagestringStatus message
scheduled_processing_timestringWhen the job will be processed (ISO 8601)

​
Contact Object

Each contact in the contacts array contains:
FieldTypeDescription
first_namestringContact’s first name
last_namestringContact’s last name
emailstringContact’s email address
job_titlestringContact’s job title
linkedin_urlstringLinkedIn profile URL
companystringCompany name
company_domainstringCompany domain
verificationsarrayVerification status for each source

​
Verification Object

Each verification in the verifications array contains:
FieldTypeDescription
sourcestringSource name
isVerifiedboolean/nulltrue if verified, false if not, null if pending
verifiedAtstringISO 8601 timestamp of when verification was performed
statusstringStatus message
errorstringError message (if verification failed)
Only contacts with isVerified: true for the requested source are returned in the response.

​
Polling Strategy

When polling for results:
  1. Start polling after 5-10 seconds
  2. Use exponential backoff (e.g., 5s, 10s, 20s)
  3. 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

HTTPError CodeDescription
400INVALID_REQUESTJob ID is required
401INVALID_API_KEYAPI key is missing, invalid, malformed, or disabled
403ACCESS_DENIEDYou do not have access to this job
500COMPANY_NOT_FOUNDWe could not find a company for this domain. Please verify the domain.
500INSUFFICIENT_CREDITSInsufficient credits to complete this request. Please contact administrator.
500INTERNAL_ERRORSomething 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

​
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