API docs v1
POST /v1/agency/prospects/{prospect_id}/contact-lookups

Find a prospect's contact

scope write:prospects cost 3 RU · 1 credit idempotent required

Look up a person to write to on the prospect's own website domain (Hunter) and save their email, name and title on the prospect. 1 credit, charged only when someone is found. A search already looks up its ten best candidates; this is for the rest. Answers 409 conflict when the prospect has an email or a lookup is running, and 400 validation_error when its website is missing or a page on a shared platform. Needs paid Agency Plus.

Path parameters

Query parameters

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Header parameters

  • Idempotency-Key string required

    Required with an API key, else 400 idempotency_key_required: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with dry_run=true.

Responses

Find a prospect's contact application/json
Type: ProspectContactLookup
  • credits_charged integer required

    1 when a contact was found, 0 when not (refunded).

  • found boolean required

    Whether someone was found; their email, name and title are on the prospect.

  • prospect Prospect required

    A saved prospect.

    Show fields
    Type: Prospect
    • company_name string required
    • has_pitch boolean required

      Whether a pitch email was written for it.

    • id string required
    • list_id string required
    • status enum required

      new, generating, ready, contacted, following_up, replied, won or lost.

    • address string (nullable) nullable
    • ai_visibility_score number (nullable) nullable

      Visibility score of its report, once run.

    • brand_id string (nullable) nullable

      The brand its report runs on, once one was made.

    • contact_email string (nullable) nullable
    • contact_lookup_started_at string (nullable) nullable

      When the running contact lookup started; null when none runs.

    • contact_name string (nullable) nullable
    • contact_title string (nullable) nullable
    • created_at string (nullable) nullable
    • demand_skip enum (nullable) nullable

      Why its website's Google demand is left out of the score: platform (a booking or site builder page), repeated_domain (the domain of businesses at other places too, a chain) or branch_page (a location page of a larger site). Null when it counts.

    • description string (nullable) nullable
    • linkedin_url string (nullable) nullable
    • lost_at string (nullable) nullable
    • lost_reason string (nullable) nullable

      Why a lost deal was lost: price, no_budget, chose_competitor, no_response, not_a_fit, timing or other.

    • not_ready_reasons array of string

      Why its outreach cannot go out as it stands (no_contact_email, report_running, nothing_to_send, empty_subject, empty_body); empty when it can. A prospect with any is never sent. The set is open.

    • object string

      default: `prospect`

    • opportunity_score integer (nullable) nullable

      Who to call first, 0 to 100: Google demand and reviews times the gap in AI answers, plus how reachable a contact is. Null until scored.

    • organic_keywords integer (nullable) nullable

      Google keywords its site ranks for, when read.

    • organic_traffic integer (nullable) nullable

      Estimated monthly Google visits, when read.

    • phone string (nullable) nullable
    • pipeline_stage string (nullable) nullable

      Where it stands in the outreach pipeline: found, report (its report runs, or is done with no pitch yet), drafted (a pitch waits for approval), approved, sent or closed (won or lost). The set is open.

    • pitch_approved_at string (nullable) nullable

      When its pitch was approved for sending.

    • pitch_queued_at string (nullable) nullable

      When a pitch was queued to be written for it.

    • rating number (nullable) nullable
    • report_error_code string (nullable) nullable

      Why its last report could not be built or run: insufficient_credits, brand_limit, research_failed, timed_out, out_of_credits, stuck, engines_failed or failed. Null once another starts. The set is open.

    • report_id string (nullable) nullable
    • report_stage string (nullable) nullable

      Where a report build stands before its run: researching, prompts or starting. Null otherwise.

    • report_viewed_at string (nullable) nullable

      When the prospect first opened the report.

    • reviews_count integer (nullable) nullable
    • revisit_at string (nullable) nullable

      Day a lost deal is due another look.

    • score_queued_at string (nullable) nullable

      When an imported prospect was queued for its score; it is scored once scored_at passes it.

    • scored_at string (nullable) nullable
    • send_queued_at string (nullable) nullable

      When its outreach was queued to start.

    • source string (nullable) nullable

      maps, ai, merged, widget, hosted, competitor or citation. The set is open.

    • updated_at string (nullable) nullable
    • website string (nullable) nullable
    • won_at string (nullable) nullable
  • prospect_id string required
  • object string

    default: `prospect.contact_lookup`

Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Not enough credits to complete this operation application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this operation"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}