---
title: "Create initiative"
method: POST
path: "/api/v1/initiatives"
tags: ["Initiatives"]
---

# Create initiative

`POST /api/v1/initiatives`

Create a draft initiative — only a name is required. For a WhatsApp initiative, link an approved template before launching.

## Request body

- object
  - `name` string, required — Initiative name.
  - `language` 'en' | 'es' | 'pt'
  - `objective` string — What the initiative aims to learn.
  - `context` string — Background the conversation draws on.
  - `maxAttempts` integer — Outreach attempts per participant. Default 3.
  - `isRecurring` boolean — Recurring initiative: keeps processing newly added participants on a schedule instead of ending after one pass. Default false.
  - `flagCondition` string, nullable — Natural-language condition; conversations matching it get flagged during analysis. Set null to clear.
  - `identityDeflection` string, nullable — Custom reply when a contact asks whether they are talking to a bot. Set null to clear.
  - `channel` 'WHATSAPP' | 'EMAIL' — Default WHATSAPP.
  - `guidingQuestions` object[] — The questions the conversation aims to answer.
    - `questionText` string, required — The question to cover.
    - `answerType` 'OPEN' | 'MULTIPLE_CHOICE' | 'BOOLEAN' | 'SCALE' — Default OPEN.
    - `priority` integer
    - `scaleMin` integer, nullable
    - `scaleMax` integer, nullable
    - `options` string[] — Answer options (MULTIPLE_CHOICE only).

## Response `201`

Success

- object
  - `id` string, required — Initiative id.
  - `name` string, required
  - `channel` 'WHATSAPP' | 'EMAIL', required
  - `status` 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'COMPLETED' | 'CANCELED', required
  - `language` string, required — Conversation language, e.g. `es`.
  - `objective` string, nullable, required
  - `isRecurring` boolean, required — Whether the initiative keeps processing newly added participants on a schedule.
  - `flagCondition` string, nullable, required — Natural-language condition; matching conversations get flagged during analysis.
  - `identityDeflection` string, nullable, required — Custom reply when a contact asks whether they are talking to a bot.
  - `createdAt` string, required — ISO 8601 timestamp.
  - `updatedAt` string, required — ISO 8601 timestamp.
  - `activatedAt` string, nullable, required
  - `completedAt` string, nullable, required
  - `canceledAt` string, nullable, required
  - `pausedAt` string, nullable, required
  - `context` string, nullable, required
  - `maxAttempts` integer, required
  - `guidingQuestions` object[], required
    - `id` string, required
    - `questionText` string, required
    - `answerType` string, required
    - `priority` integer, required
    - `scaleMin` integer, nullable, required
    - `scaleMax` integer, nullable, required
    - `options` object[], required
      - `id` string, required
      - `label` string, required
      - `position` integer, required

## Other responses

- `400` — Validation failed or the request cannot proceed.
- `401` — Missing, malformed, or revoked API key.
- `404` — The resource does not exist in this organization.
- `409` — Conflicts with the current state (duplicates, wrong lifecycle state).
- `422` — The request is well-formed but semantically invalid.
- `429` — Rate limit exceeded — retry after `Retry-After`.
- `500` — Internal server error.
- `503` — Transient error — retry with a narrower request.

---

[API](https://skmtc.net/useboom/apis/boom-api.md) · [All operations](https://skmtc.net/useboom/apis/boom-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useboom/boom-api/versions/00f873e07076/schema)