log_action defaults
Exactly what log_action does to the stage and the follow-up time when you leave fields out.
log_action records something that was done or observed. Only action.summary is required. This page spells out what happens to the rest.
Which opportunity
opportunity_id: that opportunity (must belong to the project).url: the opportunity with that normalised URL; an unknown URL is tracked automatically (usetitleto name it).- Neither: the action is recorded alone, with no opportunity.
Stage
| You pass | Result |
|---|---|
stage omitted | The stage stays. The server never infers a stage from the action. |
stage equal to the current one | No stage change. |
stage different | Stage changes and a stage_changed event is recorded. |
Follow-up time
| Situation | Result |
|---|---|
next_followup given ({"in_days": 3}, {"at": "…"} or an ISO time) | Set to that. |
next_followup: null | Cleared. |
| Omitted, and the stage changed | Set from the new stage: contacted +3 days, replied +2 days, willing_to_talk +2 days; converted and dropped clear it. discovered has no default and leaves the time as it was. |
| Omitted, and the stage did not change | Left exactly as it was. |
The last row matters. Logging a second action on an opportunity that is already past its follow-up time does not push the time forward, so it stays in the briefing's today as followup_due until you set a new next_followup, pass null, or change the stage. The response returns opportunity.next_followup_at, so you can confirm the value without a second call.
track on an existing opportunity behaves the same way for next_followup: omitted means unchanged.
Other fields
| Field | Behaviour |
|---|---|
experiment_id | Attaches the action to the experiment, and attaches the opportunity to it if it has none yet. The response includes experiment_progress. |
link_code | The short link used in this action, for click attribution. |
outcome | Records a result. Attributed (direct) when tied to an opportunity or a link, otherwise unknown. If outcome.type is willing_to_talk and the stage is not, hints reminds you to pass the stage. |
note | Extra context; stored on the stage-change or note event. |
occurred_at | When it happened; default now. |
idempotency_key | A repeat with the same key returns the first result with duplicate: true and records nothing new. Use it whenever a retry is possible. |
Do not log
Private message text and personal data. A one-sentence summary such as "Sent a DM offering a call" is enough.