> 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/getting-started/quick-start.md). # Quick Start This guide lets you create your first campaign and generate your first cards in less than 10 minutes. **Application URL** : \ **API URL (production)** : `https://api.oomus.health`\ **API URL (development)** : `http://localhost:8000` *** ## Step 1 — Create a program account ### Through the web interface 1. Go to 2. Enter your organization's name, your email, and a secure password 3. Choose your plan when signing up (you can change it later) 4. Confirm your email, then log in ### Via the API ```bash # Create an account curl -X POST https://api.oomus.health/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "contact@your-programme.sn", "password": "YourPassword!", "full_name": "National Vaccination Program", "organization": "Ministry of Health of Senegal" }' ``` **Response:** ```json { "id": "usr_01HXYZ123ABC", "email": "contact@your-programme.sn", "full_name": "National Vaccination Program", "organization": "Ministry of Health of Senegal", "role": "programme_admin", "plan": "starter", "created_at": "2026-05-15T09:00:00Z" } ``` *** ## Step 2 — Authenticate ```bash # Get a JWT access token curl -X POST https://api.oomus.health/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "contact@your-programme.sn", "password": "YourPassword!" }' ``` **Response:** ```json { "access_token": "", "refresh_token": "", "token_type": "bearer" } ``` > Keep your `access_token`. Use the `refresh_token` to automatically get a new one without re-entering your credentials (handled by the client SDK). In all the following examples, replace `` with the value of your `access_token`. *** ## Step 3 — Configure your first campaign ### Through the web interface 1. From the Dashboard, click **"New campaign"** 2. Fill in the form: * **Name** : e.g. `EPI Vaccination - Dakar 2026` * **Type** : e.g. `vaccination` * **Prefix** : e.g. `DKR-VAC` (3–8 characters, uppercase) * **Language** : French / English / Wolof * **Card template** : select from the 11 available templates (e.g. `vaccination`) 3. Click **"Create campaign"** ### Via the API ```bash curl -X POST https://api.oomus.health/campaigns/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "EPI Vaccination - Dakar 2026", "campaign_type": "vaccination", "prefix": "DKR-VAC", "language": "fr", "template_id": "vaccination" }' ``` **Response:** ```json { "id": "camp_01HXYZ456DEF", "name": "EPI Vaccination - Dakar 2026", "status": "draft", "prefix": "DKR-VAC", "template_id": "vaccination", "created_at": "2026-05-15T09:05:00Z" } ``` *** ## Step 4 — Design your card (Card Studio) ### Through the web interface 1. From the campaign, click the tab **"Card Studio"** 2. The visual editor opens with your selected template 3. Customize: * **Logos** : upload up to 3 logos (program, partner, government) * **Colors** : choose your program's primary and secondary colors * **Dynamic fields** : configure the front fields (name, date, number) and back fields (additional information) * **QR code** : enable the QR and choose its style 4. Click **"PNG preview"** to view the result before generation 5. Save the design *** ## Step 5 — Generate the cards ### Start a generation job ```bash curl -X POST https://api.oomus.health/campaigns/camp_01HXYZ456DEF/jobs \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "beneficiaries": [ { "first_name": "Aminata", "last_name": "Diallo", "date_of_birth": "2020-03-15", "beneficiary_id": "BEN-001" }, { "first_name": "Moussa", "last_name": "Sow", "date_of_birth": "2019-07-22", "beneficiary_id": "BEN-002" } ], "dpi": 300, "include_mpi_id": true }' ``` **Response (job created):** ```json { "job_id": "job_01HXYZ789GHI", "campaign_id": "camp_01HXYZ456DEF", "status": "pending", "total_cards": 2, "created_at": "2026-05-15T09:10:00Z" } ``` ### Track progress The generation is **asynchronous**. Follow the progress via polling or WebSocket: ```bash # Polling (status check) curl -X GET https://api.oomus.health/jobs/job_01HXYZ789GHI \ -H "Authorization: Bearer " ``` **Response (in progress):** ```json { "job_id": "job_01HXYZ789GHI", "status": "generating", "progress": 65, "cards_generated": 1, "total_cards": 2, "started_at": "2026-05-15T09:10:05Z" } ``` **Response (completed):** ```json { "job_id": "job_01HXYZ789GHI", "status": "completed", "progress": 100, "cards_generated": 2, "total_cards": 2, "artifacts": { "pdf_url": "https://api.oomus.health/jobs/job_01HXYZ789GHI/download/pdf", "zip_url": "https://api.oomus.health/jobs/job_01HXYZ789GHI/download/zip", "verification_portal_url": "https://api.oomus.health/jobs/job_01HXYZ789GHI/download/portal" }, "completed_at": "2026-05-15T09:10:48Z" } ``` ### WebSocket connection (real-time) ```javascript // WebSocket connection for real-time progress const ws = new WebSocket( "wss://api.oomus.health/ws/jobs/job_01HXYZ789GHI?token=" ); ws.onmessage = (event) => { const data = JSON.parse(event.data); console.log(`Progress: ${data.progress}% — ${data.status}`); }; ``` *** ## Step 6 — Distribute the cards Once generation is complete, distribute the cards from the interface or via the API: * **WhatsApp** : from the "Distribution" tab of your campaign, send the cards with a personalized message * **SMS** : send a download link by SMS * **Google Wallet** : issuing individual or bulk passes * **Download** : download the PDF and ZIP for printing or archiving *** ## Step summary | Step | Action | Interface | | ---- | ----------------------------------------- | --------- | | 1 | Create a program account | Web / API | | 2 | Authenticate, get a JWT | API | | 3 | Create a campaign | Web / API | | 4 | Design the card (Card Studio) | Web only | | 5 | Launch generation | Web / API | | 6 | Distribute (WhatsApp, SMS, Google Wallet) | Web / API | *** ## Next steps * [Card Studio](/features/card-studio.md) — Master the visual editor * [Sovereign MPI identity](/features/mpi-sovereign-identity.md) — Enable deduplication * [DHIS2 integration](/features/dhis2-integration.md) — Sync from DHIS2 Tracker * [Plans & Features](/getting-started/plans-and-pricing.md) — Adapt your quota to your program --- # 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/getting-started/quick-start.md?ask=&goal= ``` `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.