Projects CRUD

This page documents the create, read, update, and delete operations for projects.

---

List Projects

Endpoint

GET /api/projets

Query Parameters

Parameter	Type	Description
actif	boolean	Filter by active projects

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "PCH",
      "nom": "Programme de Cash Harmonise"
    }
  ]
}

---

Get Project Details

Endpoint

GET /api/projets/{id}

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "PCH",
    "nom": "Programme de Cash Harmonise",
    "description": "Conditional cash transfer program",
    "dateDebut": "2024-01-01",
    "dateFin": "2027-12-31",
    "actif": true,
    "lectureSeule": false,
    "bailleur": "World Bank",
    "peutCollecter": true,
    "peutScorer": true,
    "peutEnroler": true,
    "pmtMethode": {
      "id": "...",
      "nom": "PMT GB v2"
    },
    "organisation": {
      "id": "...",
      "nom": "MAS"
    },
    "createdAt": "2024-01-01T00:00:00+00:00"
  }
}

---

Create a Project

Endpoint

POST /api/projets

Request Body

{
  "code": "SAFETY",
  "nom": "Social Safety Net Program",
  "description": "Support program for vulnerable households",
  "dateDebut": "2026-07-01",
  "dateFin": "2029-06-30",
  "actif": true,
  "lectureSeule": false,
  "bailleur": "European Union",
  "peutCollecter": true,
  "peutScorer": true,
  "peutEnroler": true
}

Required Fields

Field	Description
code	Unique project code (max 20 characters)
nom	Project name (max 100 characters)

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "...",
    "code": "SAFETY",
    "nom": "Social Safety Net Program",
    "actif": true
  },
  "message": "Project created successfully"
}

---

Update a Project

Endpoint

PUT /api/projets/{id}

Request Body (partial)

{
  "actif": false,
  "lectureSeule": true,
  "dateFin": "2026-12-31"
}

Response

{
  "success": true,
  "data": { ... },
  "message": "Project updated"
}

---

Delete a Project

Endpoint

DELETE /api/projets/{id}

Conditions

Deletion is only allowed if:

• No households are associated with the project
• No beneficiaries are associated with the project
• No payment cycles are associated with the project

Success Response

{
  "success": true,
  "message": "Project deleted"
}

Failure Response

{
  "success": false,
  "error": "Cannot delete: 1500 associated households"
}

---

Archive a Project

To archive a project without deleting it:

Endpoint

PUT /api/projets/{id}

Body

{
  "actif": true,
  "lectureSeule": true,
  "peutCollecter": false,
  "peutScorer": false,
  "peutEnroler": false
}

This configuration:

• Keeps the project visible
• Prevents any data modifications
• Preserves the complete history

---

Project capabilities

There is no dedicated endpoint: the project details carry the actif, lectureSeule, peutCollecter, peutScorer and peutEnroler fields. A project can be modified if it is active and not read-only; an archived project refuses every write.

---

Taking over households from another project

A household has a single identity in the registry and can take part in several projects.

Method	Endpoint	Permission	Description
GET	/api/projets/{id}/menages-disponibles	registre.menages_view	Candidate households (page, limit 25 by default and 200 at most, source, region, horsCouverture=1)
POST	/api/projets/{id}/reprise	registre.menages_edit	Adds households to the project

{ "menageIds": ["<uuid>", "<uuid>"], "commentaire": "Reprise après ciblage" }

{ "success": true, "data": { "reprises": 2, "dejaPresents": 0, "introuvables": 0 } }

An archived project cannot take households (400); with no household selected: 400 Aucun ménage sélectionné.

---

Sync with the collection tool

Each project can have its own Kobo and/or Survey Solutions account; otherwise the global configuration applies.

Method	Endpoint	Description
GET	/api/projets/{id}/synchronisation	Project configuration
PUT	/api/projets/{id}/synchronisation	Saves the kobo and/or surveySolutions blocks
POST	/api/projets/{id}/synchronisation/test	Tests the connection ({"source": "kobo"} or Survey Solutions)

Only a manager or a user whose scope contains the project can read or change this configuration. Secrets are never returned: reading only says whether they are set, and a save that omits them keeps them.

---

Error Codes

Code	HTTP	Description
NOT_FOUND	404	Project not found
DUPLICATE_CODE	409	Code already used
HAS_DEPENDENCIES	400	Existing associated data
FORBIDDEN	403	Insufficient permission

---

Usage Examples

Create a Pilot Project

{
  "code": "PILOT-2026",
  "nom": "Pilot Program 2026",
  "description": "Pilot phase limited to Biombo region",
  "dateDebut": "2026-01-01",
  "dateFin": "2026-06-30",
  "actif": true,
  "peutCollecter": true,
  "peutScorer": false,
  "peutEnroler": false
}

Close a Completed Project

{
  "actif": true,
  "lectureSeule": true,
  "dateFin": "2026-05-31"
}