Push Leads

Push a set of leads to a configured outreach destination.

Endpoint

POST /api/v1/leads/push

Authentication

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

Request body

Field	Type	Required	Notes
`lead_ids`	string[]	Yes	Leads to push. Must belong to this workspace.
`destination`	string	Yes	One of `webhook_url`, `heyreach`, `instantly`.
`webhook_url`	string	Conditional	Required when `destination` is `webhook_url`.

Supported destinations

Destination	Status	Notes
`webhook_url`	Implemented	Real POST dispatch to the URL you supply.
`heyreach`	Guarded	Requires the workspace to have HeyReach integration/list mapping configured.
`instantly`	Guarded	Requires the workspace to have Instantly integration/campaign mapping configured.

cURL: webhook dispatch

curl -i -X POST "https://api-staging.satellyte.ai/api/v1/leads/push" \
  -H "X-Satellyte-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_ids": ["lead_1", "lead_2"],
    "destination": "webhook_url",
    "webhook_url": "https://example.com/webhook"
  }'

Response (200): dispatched

{
  "data": {
    "status": "dispatched",
    "destination": "webhook_url",
    "lead_count": 2,
    "requested_lead_count": 2,
    "missing_lead_ids": [],
    "dispatched": true,
    "provider_status_code": 200,
    "provider_response": "{\"ok\":true}"
  }
}

Response (200): dispatch failed

{
  "data": {
    "status": "dispatch_failed",
    "destination": "webhook_url",
    "lead_count": 0,
    "requested_lead_count": 2,
    "missing_lead_ids": ["lead_1", "lead_2"],
    "dispatched": false,
    "provider_status_code": 501,
    "provider_response": "Unsupported method"
  }
}

Response fields

Field	Type	Notes
`status`	string	`dispatched` or `dispatch_failed`.
`destination`	string	Echoed destination.
`lead_count`	number	Number of leads actually dispatched.
`requested_lead_count`	number	Number requested in the call.
`missing_lead_ids`	string[]	Leads that did not exist in this workspace or were not pushed.
`dispatched`	boolean	Whether the dispatch succeeded end-to-end.
`provider_status_code`	number	Destination's HTTP status (your webhook, HeyReach, or Instantly).
`provider_response`	string	Truncated body returned by the destination.

Unknown or missing leads are returned transparently in missing_lead_ids rather than raising errors.

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, the destination is missing or unsupported, or the requested lead IDs are malformed.
`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. Missing lead IDs are reported in `missing_lead_ids` in successful dispatch responses rather than raising this error.
`429`	`rate_limit_exceeded`	Returned when the API key exceeds its configured rate limit.
`500`	`service_error`	Returned when Satellyte cannot complete the dispatch request. Retry with backoff.