Plan an intervention

POST /api/v1/enrollments/{enrollmentId}/interventions

Turns an alert into a tracked action on one enrollment: a reason, an owner, a deadline, a channel and the outcome it must achieve. Once the deadline passes without a closure, the intervention appears in the owner's work queue. An intervention is not the member's next action, and linking a blocker never changes that blocker's status.

Authorization

Organization role

Business authorization

The chosen ownerUserId must satisfy the same rule: an account that could not write on this enrollment cannot own an intervention on it. A platform-wide role grants nothing here. An enrollment of another organization, or one outside the caller's scope, is refused without revealing whether it exists.

Path parameters

Request headers

Request body

{
  "reason": "late",
  "title": "Catch-up call after two weeks without progress",
  "channel": "call",
  "ownerUserId": "1b7d2f30-0000-4000-8000-000000000000",
  "dueAt": "2026-09-05T16:00:00.000Z",
  "expectedOutcome": "A prospecting slot booked again for this week."
}

Example

curl -X POST "$COHORTE_API_BASE_URL/api/v1/enrollments/ENROLLMENT_ID/interventions" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: intervention-2026-09-02" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"late","title":"Catch-up call","channel":"call","ownerUserId":"OWNER_ID","dueAt":"2026-09-05T16:00:00.000Z","expectedOutcome":"A prospecting slot booked again."}'

Response

• 201 Created — the intervention was planned.
• 200 OK — the same Idempotency-Key replayed the original planning.
• 400 Bad Request — missing Idempotency-Key, invalid JSON, an unknown reason or channel, a past deadline, an owner who is not allowed on this enrollment, a blocker that is closed or belongs to another enrollment, or an enrollment that is not active.
• 401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
• 403 Forbidden — the bearer cannot plan an intervention on this enrollment.
• 404 Not Found — the enrollment is unknown or belongs to another organization.

Response fields

Example response

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "9f2c0a1e-0000-4000-8000-000000000000",
    "enrollmentId": "4af4cd8d-0000-4000-8000-000000000000",
    "reason": "late",
    "title": "Catch-up call after two weeks without progress",
    "channel": "call",
    "ownerUserId": "1b7d2f30-0000-4000-8000-000000000000",
    "ownerName": "Ines Fabre",
    "dueAt": "2026-09-05T16:00:00.000Z",
    "expectedOutcome": "A prospecting slot booked again for this week.",
    "status": "planned",
    "outcome": null,
    "closedAt": null,
    "closedBy": null,
    "closedByName": null,
    "blockerId": null,
    "plannedBy": "6d41ab55-0000-4000-8000-000000000000",
    "plannedByName": "Paul Vidal",
    "plannedAt": "2026-09-02T09:14:00.000Z"
  },
  "correlationId": "0f6b1d92-0000-4000-8000-000000000000"
}

Agent recipe

1. Read the cohort cockpit to find the members flagged late, at risk, absent or without a recent intervention.
2. Plan one intervention per member, with the reason that matches the signal and an owner who already works on that enrollment.
3. Close each intervention with its outcome once the contact happened.

Notes

• Retrying with the same Idempotency-Key returns the original intervention and creates no second record, audit entry or event.
• The intervention, its audit entry and the intervention.planned event are written in one transaction.
• An intervention is not the member's next action: several can be open at the same time on one enrollment, and none of them replaces what the member must do next.
• A linked blocker stays open. Closing the intervention never resolves it.
• No email or notification is sent by this endpoint.

Related

• List interventions
• Close an intervention
• Record a coaching session