Ingest Feedback Event

Ingest one outreach outcome event. This is how Satellyte learns which leads, titles, companies, and signal types produce better outcomes.

Endpoint

POST /api/v1/feedback/events

Authentication

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

Supported event types

`event_type`	Behavior
`open`	Accepted; no status mutation yet.
`click`	Accepted; no status mutation yet.
`reply`	Sets lead status to `replied`; updates `replied_at` and `reply_content`.
`positive_reply`	Sets status to `replied`; marks `feedback = positive`.
`bounce`	Sets status to `skipped`; marks `feedback = negative`.
`meeting_booked`	Sets status to `meeting_booked`; marks `feedback = positive`.

Supported sources

instantly, heyreach, webhook, manual, custom.

Request body

Field	Type	Required	Notes
`lead_id`	string	Yes	Lead ID in your workspace.
`event_type`	enum	Yes	One of the values in the table above.
`source`	enum	No	Defaults to `custom`.
`content`	string	No	Reply text, event detail, or failure reason.
`meeting_url`	string	No	Used with `meeting_booked`.
`occurred_at`	string (ISO)	No	Event time; defaults to now.
`metadata`	object	No	Reserved for future use.

cURL: positive reply

curl -i -X POST "https://api-staging.satellyte.ai/api/v1/feedback/events" \
  -H "X-Satellyte-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "LEAD_ID_HERE",
    "event_type": "positive_reply",
    "source": "webhook",
    "content": "Interested, send me more details."
  }'

cURL: meeting booked

curl -i -X POST "https://api-staging.satellyte.ai/api/v1/feedback/events" \
  -H "X-Satellyte-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "LEAD_ID_HERE",
    "event_type": "meeting_booked",
    "source": "webhook",
    "meeting_url": "https://meet.google.com/example",
    "content": "Meeting booked from outbound campaign."
  }'

Response (200)

{
  "data": {
    "accepted": true,
    "event_type": "positive_reply",
    "source": "webhook",
    "lead_id": "lead_123",
    "mutated_lead": true,
    "stored_event": false,
    "note": "Lead outcome updated using existing leads fields.",
    "lead": {
      "id": "lead_123",
      "status": "replied",
      "replied_at": "2026-05-02T12:00:00.000Z",
      "meeting_booked_at": null,
      "feedback": "positive",
      "feedback_reason": "Interested, send me more details."
    }
  }
}

Response fields

Field	Type	Notes
`accepted`	boolean	Always `true` for a recognized event type with a known lead.
`event_type`	string	Echoed event type.
`source`	string	Echoed source.
`lead_id`	string	Echoed lead id.
`mutated_lead`	boolean	Whether the lead record was updated.
`stored_event`	boolean	Reserved for future; whether a separate event log entry was written.
`note`	string	Free-form explanation of what changed.
`lead`	object	Updated lead snapshot (`id`, `status`, `replied_at`, `meeting_booked_at`, `feedback`, `feedback_reason`).

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, required event fields are missing, or the outcome/event type is unsupported.
`401`	`unauthorized`	Returned when `X-Satellyte-API-Key` is missing, invalid, or expired.
`404`	`lead_not_found`	Returned when `lead_id` does not exist in this workspace.
`429`	`rate_limit_exceeded`	Returned when the API key exceeds its configured rate limit.
`500`	`service_error`	Returned when Satellyte cannot ingest the feedback event. Retry with backoff.