> For the complete documentation index, see [llms.txt](https://docs.oomus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oomus.org/features/campaigns.md).

# Campaign management

Campaigns are the central unit of Oomus CampaignID. Each campaign groups together a set of cards generated for a given program, period, and target beneficiary group.

***

## Campaign creation — wizard assistant

Campaign creation is done through a 5-step wizard:

### Step 1 — General information

| Field           | Description                                     | Example                         |
| --------------- | ----------------------------------------------- | ------------------------------- |
| **Name**        | Descriptive name of the campaign                | `EPI Vaccination - Dakar 2026`  |
| **Type**        | Type of health program                          | `vaccination`                   |
| **Prefix**      | Unique alphanumeric code (3–8 chars, uppercase) | `DKR-VAC`                       |
| **Description** | Optional description                            | `Dakar district pilot campaign` |

### Step 2 — Language

Select the main language of the campaign:

* **French** (`fr`)
* **English** (`en`)
* **Wolof** (`wo`)

The language affects field labels on the cards, distribution messages (SMS/WhatsApp), and the generated verification portal.

### Step 3 — Template selection

Choose from the 11 templates available in Card Studio. The template can be customized after the campaign is created.

### Step 4 — DPI configuration

Select the target resolution according to your end use (digital display, laser printing, PVC). Available options depend on your plan.

### Step 5 — Review and validation

Full summary before creation. Check the settings — the prefix and type can no longer be changed after creation.

***

## Campaign types

| Type          | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `vaccination` | Vaccination program (EPI, routine, mass campaign)              |
| `mild`        | Distribution of long-lasting insecticide-treated nets          |
| `nutrition`   | Nutritional follow-up (children, pregnant/breastfeeding women) |
| `antenatal`   | Prenatal care and maternal consultations                       |
| `hiv`         | HIV/PTME program (sensitive data — restricted access)          |
| `insurance`   | Universal health insurance                                     |
| `refugee`     | Humanitarian identification of refugees                        |
| `identity`    | National health identity                                       |
| `lab`         | Biological tests and laboratory follow-up                      |
| `cps`         | Community social protection                                    |
| `farmercard`  | Agricultural and rural health                                  |

***

## Card generation

### Asynchronous generation

Card generation is a **asynchronous** process managed by a task queue engine (Celery + Redis). This means your request is accepted immediately and processed in the background, without blocking your interface.

**Generation process:**

```
API request → Quota validation → Job creation → Celery queue
→ Worker generates the cards (PNG, PDF, QR)
→ ZIP assembly + verification portal
→ Status update → WebSocket notification
```

### Real-time progress tracking — WebSocket

Connect to the progress WebSocket to receive live updates:

```
wss://api.oomus.health/ws/jobs/{job_id}?token={access_token}
```

WebSocket events send:

```json
{
  "event": "progress",
  "job_id": "job_01HXYZ789GHI",
  "status": "generating",
  "progress": 45,
  "cards_generated": 450,
  "total_cards": 1000,
  "eta_seconds": 28
}
```

### Generated artifacts

At the end of a successful job, the following artifacts are available:

| Artifact                | Description                                | Format             |
| ----------------------- | ------------------------------------------ | ------------------ |
| **PDF**                 | All front/back cards in a single file      | Multi-page PDF     |
| **ZIP**                 | Individual cards (one card = one PNG)      | ZIP archive        |
| **Verification portal** | Offline portal with SHA-256 registry       | Static HTML + JSON |
| **Manifest**            | Structured list of beneficiaries and codes | JSON               |

***

## Job lifecycle

### Campaign statuses

```
draft → preview_ready → generating → completed
                                   ↘ failed
```

| Status          | Description                            |
| --------------- | -------------------------------------- |
| `draft`         | Campaign created, design not finalized |
| `preview_ready` | Design validated, ready for generation |
| `generating`    | Generation job in progress             |
| `completed`     | Generation completed successfully      |
| `failed`        | Generation failed (see logs)           |

### Job statuses

| Status       | Description                         |
| ------------ | ----------------------------------- |
| `pending`    | Job created, awaiting processing    |
| `processing` | Worker processing                   |
| `generating` | Active card generation              |
| `packaging`  | PDF, ZIP, portal assembly           |
| `completed`  | Job completed, artifacts available  |
| `failed`     | Failure (automatic quota refund)    |
| `cancelled`  | Manually canceled before processing |

***

## Automatic refund in case of failure

If a generation job fails, the consumed quota is **automatically refunded** to your account. No manual action is required.

The refund includes:

* The beneficiary quota deducted at launch
* Any SMS/WhatsApp credits pre-allocated to the job

A refund log is available in **Billing > Transactions**.

***

## DPI options by campaign

Each generation job can specify an independent DPI resolution:

| DPI | Cost factor | Recommended use                   |
| --- | ----------- | --------------------------------- |
| 300 | ×1.0        | Digital sharing (WhatsApp, email) |
| 450 | ×1.4        | Laser printing, laminated badges  |
| 600 | ×2.0        | High-quality PVC printing         |

***

## Interface — Mature healthcare design (v5.7)

Since v5.7, the Campaigns page has adopted a professional clinical design suited to healthcare institutions:

| Element                 | Behavior                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Palette**             | Background `#060D1A` (deep navy), surfaces `#0C1628`, accent `#0EA5E9` (medical cyan) — unified palette `C`                                       |
| **KPI tiles**           | 4 tiles in the header: Total programs, In progress, Completed, Cards distributed — each with icon and radial glow                                 |
| **Subtitle**            | "Manage your health card distribution programs" — health product identity                                                                         |
| **Type badges**         | 12 campaign types with contextual Lucide icon (Shield = CPS, Stethoscope = Prenatal, Microscope = Lab, Leaf = Agriculture…) and tinted background |
| **Status**              | Pill capsule with tinted background, animated dot only for `generating`                                                                           |
| **Row actions**         | Always visible at 35% opacity (no hover required), full opacity on hover                                                                          |
| **Sticky table header** | Fixed columns while scrolling, background `rgba(255,255,255,0.018)`                                                                               |
| **Row hover**           | Tinted cyan background `rgba(14,165,233,0.03)`                                                                                                    |
| **Detail panel**        | Colored type strip at the top, info in bordered card, action buttons with colored icons                                                           |
| **Empty state**         | Cyan Stethoscope icon + contextual health text                                                                                                    |

***

## Multi-campaign management

A program account can manage an unlimited number of campaigns simultaneously (within the total beneficiary quota of the plan).

Management features:

* **Filtering** by status, type, date, prefix
* **Search** by name or ID
* **Duplication** of a campaign (copy of settings, new prefix)
* **Archiving** completed campaigns
* **Export** of the campaign list in CSV

***

## Full example via API

```bash
# 1. Create the campaign
curl -X POST https://api.oomus.health/campaigns/ \\
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "MILD Distribution - Thiès 2026",
    "campaign_type": "mild",
    "prefix": "THS-MILD",
    "language": "fr",
    "template_id": "mild"
  }'

# 2. Start generation
curl -X POST https://api.oomus.health/campaigns/camp_01HXYZ/jobs \\
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "beneficiaries": [...],
    "dpi": 300,
    "include_mpi_id": true
  }'

# 3. Check status
curl -X GET https://api.oomus.health/jobs/job_01HXYZ \\
  -H "Authorization: Bearer <YOUR_TOKEN>"

# 4. Download artifacts (once "completed")
curl -X GET https://api.oomus.health/jobs/job_01HXYZ/download/zip \\
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -o "cards_thies_2026.zip"
```

***

## Next steps

* [Card Studio](/features/card-studio.md) — Customize card design
* [Multichannel distribution](/features/distribution.md) — Send the generated cards
* [Offline verification](/features/verification.md) — Use the verification portal
* [API reference — Campaigns & Jobs](/api-reference/campaigns-and-jobs.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.oomus.org/features/campaigns.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.