Record one verified real-world execution of a prepared outreach, or a factual CORRECTION of an earlier one. Never resolves or signals an Action. Absence of a bounce is not delivery proof.

Two distinct operations share this endpoint.

NORMAL EXECUTION (no supersedesExecutionId): identity is externalSource + externalBatchId. A repeat answers 208 with the already recorded execution.

CORRECTION (supersedesExecutionId present): this is NOT a replay of the superseded row, even with the SAME externalBatchId — a correction fixes what Forbiz knows about the same real-world batch and is never a second send. It requires correctionNote, and its external execution identity must match the record being corrected. Its idempotency identity is the correction operation: outreach + superseded execution + Idempotency-Key (falling back to a hash of the correction). Retrying the same correction answers 208 with the existing correction, never the original. History keeps the superseded row; effective state, reconciliation and preflight all use ONE canonical selector: a record superseded by a later one is history, and of the records sharing one external execution identity only the newest is effective. In a chain original -> correction 1 -> correction 2 only the current effective record contributes to aggregates, so a chain can never inflate totals. Callers never supply any correction identity field themselves: the correction operation key is derived internally from the outreach, the superseded execution and the Idempotency-Key.

post/outreach/{id}/executions

Request

  • Base URL: https://forbiz.io/api/public/agent
  • URL: https://forbiz.io/api/public/agent/outreach/{id}/executions
  • Auth: HTTP bearer

Path parameters

idstring required

Headers

Idempotency-Keystring

Recommended on every mutating request. A replay with the same key is NOT applied twice: the server answers { ok, idempotent_replay: true, first_seen_at, status } describing the first attempt.

Request body

channel'email' | 'phone' | 'linkedin' | 'meeting' | 'other'
executedAtstring date-time

Required. When the send actually OCCURRED (alias: occurredAt). When Forbiz recorded it is stored separately as recorded_at and is never caller-supplied.

executionType'initial' | 'follow_up' | 'resend' | 'duplicate' | 'unknown' | 'other'

Classification of this execution. Defaults to 'unknown' — never guessed by Forbiz.

executionSourcestring
externalSourcestring
externalBatchIdstring

Canonical external execution identity together with externalSource: one NON-CORRECTION execution per outreach + (source:batch id). A replay answers 208 with the already recorded execution. A correction repeats the SAME value on purpose.

supersedesExecutionIdstring

Correction: records a NEW execution row that supersedes an earlier one on this outreach. Bypasses external-batch replay detection; requires correctionNote and a matching external execution identity. History is never rewritten or deleted, and no second real-world send is implied.

correctionNotestring

Required when supersedesExecutionId is present. State factually what was wrong in the superseded record.

automationMode'autonomous' | 'manual'

Defaults to manual (human-approved). 'autonomous' means no human approved this specific send, and it MUST pass the hard autonomous send budget: one slot per confirmed recipient is reserved atomically before the execution row is written. Exhausted budget answers 429 with code AUTONOMOUS_SEND_LIMIT_REACHED and execution_allowed=false plus limit/used/remaining/window_end. Retrying the SAME logical send (same Idempotency-Key, or same external source + batch id) reuses the original reservation and consumes nothing extra; a genuinely new send consumes a new slot. Corrections (supersedesExecutionId) never consume budget because they are not a second real-world send. A granted slot is not released automatically if the external send later fails — releasing on failure would allow an unbounded retry loop.

senderstring
recipientCountinteger
actualSubjectstring
actualBodySnapshotstring
preparedSubjectSnapshotstring
preparedBodySnapshotstring
preparedTemplateIdstring
executionIntegrity'matched' | 'modified' | 'unknown'
integrityNotestring

Required when executionIntegrity is 'modified'.

Response

Execution or correction recorded

okboolean
executionobject
is_correctionboolean
supersedes_execution_idstring

Changes

No recorded changes to this operation across all 1 revision of this API.