Find Contacts

Find decision-makers at a target company.

Endpoint

POST /api/v1/contacts/find

Authentication

All requests require the X-Satellyte-API-Key header. See Quickstart.

Request body

Field	Type	Required	Notes
`company_domain`	string	Conditional	Required if `linkedin_url` is not provided.
`linkedin_url`	string	Conditional	LinkedIn company URL. Required if `company_domain` is not provided.
`target_titles`	string[]	No	Titles to prioritize (for example `CEO`, `Founder`, `Head of Sales`).
`max_contacts`	number	No	Defaults to 10.

cURL

curl -i -X POST "https://api-staging.satellyte.ai/api/v1/contacts/find" \
  -H "X-Satellyte-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_domain": "stripe.com",
    "linkedin_url": "https://www.linkedin.com/company/stripe",
    "target_titles": ["CEO", "Founder", "Head of Sales"],
    "max_contacts": 3
  }'

Response (200)

{
  "data": [
    {
      "id": "https://www.linkedin.com/in/patrickcollison",
      "name": "Patrick Collison",
      "title": "Stripe CEO",
      "company": "Stripe",
      "role": "decision_maker",
      "linkedin_url": "https://www.linkedin.com/in/patrickcollison",
      "email": null,
      "location": "San Francisco, CA, US",
      "score": null,
      "outreach_angle": "Lead with business impact and buying signals relevant to Stripe CEO."
    }
  ]
}

Response fields

Field	Type	Notes
`id`	string	Opaque contact identifier.
`name`	string	Full name.
`title`	string	Job title.
`company`	string	Company name.
`role`	string	Inferred role bucket (`decision_maker`, `influencer`).
`linkedin_url`	string \| null	LinkedIn profile URL.
`email`	string \| null	Email if already known; call `/enrich/email` to discover.
`location`	string \| null	City, region, country.
`score`	number \| null	Lead score, when available.
`outreach_angle`	string	Suggested message angle.

Error responses

All failed calls use the standard error envelope documented in Errors.

Status	Code	Notes
`400`	`validation_error`	Returned when the request body is invalid, `company_domain` is missing or invalid, `target_titles` is invalid, or `max_contacts` is outside the supported range.
`401`	`unauthorized`	Returned when `X-Satellyte-API-Key` is missing, invalid, or expired.
`404`	`not_found`	Returned when Public API access is not enabled or the requested Public API resource is unavailable.
`429`	`rate_limit_exceeded`	Returned when the API key exceeds its configured rate limit.
`500`	`service_error`	Returned when the service cannot complete the request. Retry with backoff.