Community Workers API (Cuidadoras)

The Community Workers API manages community agents (cuidadoras) of the social protection program.

Overview

The Community Workers module manages field agents who perform activities such as: household registration, awareness campaigns, verification, GRM data collection, and vulnerable population monitoring.

Module Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                       COMMUNITY WORKER                                   │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Personal info: first name, last name, phone, email, etc.        │    │
│  │ Assignment zone: region, sector, locality                        │    │
│  │ Contract: type (volunteer/contracted), dates, status             │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                    │                                     │
│      ┌─────────────────────────────┼─────────────────────────────┐      │
│      ▼                             ▼                             ▼      │
│ ┌──────────────┐           ┌──────────────┐            ┌──────────────┐ │
│ │ ASSIGNMENTS  │           │  ACTIVITIES  │            │  TRAINING    │ │
│ │ Zone         │           │  Activity    │            │ Certifications│ │
│ │ history      │           │  reports     │            │ Evaluations  │ │
│ └──────────────┘           └──────────────┘            └──────────────┘ │
│                                    │                                     │
│                                    ▼                                     │
│                            ┌──────────────┐                             │
│                            │   PAYMENTS   │                             │
│                            │ Monthly slips│                             │
│                            │ + Batches    │                             │
│                            └──────────────┘                             │
└─────────────────────────────────────────────────────────────────────────┘

Main Endpoints

Endpoint	Method	Description
/api/community-workers	GET	List community workers
/api/community-workers	POST	Create a community worker
/api/community-workers/{id}	GET	Get community worker details
/api/community-workers/{id}	PUT/PATCH	Update a community worker
/api/community-workers/{id}	DELETE	Delete a community worker
/api/community-workers/stats	GET	Global statistics
/api/community-workers/bulk-status	POST	Bulk status update
/api/community-workers/check-duplicates	POST	Check for duplicates
/api/community-workers/{id}/affectations	GET	Assignment history
/api/community-workers/{id}/change-affectation	POST	Change assignment
/api/community-workers/{id}/activites	GET	Activity reports
/api/community-workers/{id}/certifications	GET	Certifications
/api/community-workers/{id}/evaluations	GET	Evaluations
/api/community-workers/{id}/photo	POST	Upload photo
/api/community-workers/{id}/photo	DELETE	Delete photo

Required Permissions

Permission	Description
ROLE_USER	View, create, update
ROLE_ADMIN	Delete

---

Data Model

CommunityWorker

Field	Type	Description
id	UUID	Unique identifier
code	string	Unique code (format: CW-REGION-SEQ)
prenom	string	First name
nom	string	Last name
nomComplet	string	Full name (computed)
sexe	string	M or F
dateNaissance	date	Date of birth
lieuNaissance	string	Place of birth
telephone	string	Phone number
email	string	Email address
niveauInstruction	string	Education level
pieceIdentite	string	ID document type
numeroPieceIdentite	string	ID document number
adresse	text	Full address
languePrincipale	string	Primary language
languesSecondaires	array	Secondary languages
typeContrat	string	volontaire or contractuel
dateRecrutement	date	Recruitment date
dateFinContrat	date	Contract end date
statut	string	Current status
photo	string	Photo path
region	object	Assigned region
secteur	object	Assigned sector
localite	object	Assigned locality
superviseur	object	Supervisor (another CW)
createdAt	datetime	Creation date
updatedAt	datetime	Last update date

Statuses

Status	Description
actif	Active community worker
en_formation	In initial training
suspendu	Temporarily suspended
inactif	Inactive or departed

Contract Types

Type	Description
volontaire	Volunteer agent, unpaid
contractuel	Contracted agent, paid

---

Statistics

The /api/community-workers/stats endpoint returns:

{
  "success": true,
  "data": {
    "total": 150,
    "actifs": 120,
    "enFormation": 15,
    "suspendus": 5,
    "inactifs": 10,
    "parSexe": {
      "M": 45,
      "F": 105
    },
    "tauxValidation": 85.5,
    "tauxCertification": 72.3,
    "parRegion": [
      {"region": "Oio", "count": 45},
      {"region": "Bafata", "count": 35}
    ]
  }
}

---

Error Codes

Code	HTTP Status	Description
NOT_FOUND	404	Community Worker not found
VALIDATION_ERROR	400	Invalid data (first/last name required)
INVALID_STATUS	400	Invalid status
FORBIDDEN	403	Insufficient permission