POST /api/menages

Creates a new household with its head of household and housing.

Endpoint

POST /api/menages

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	application/json	Yes

Request Body

{
    "tailleMenage": 5,
    "region": "/api/regions/1",
    "secteur": "/api/secteurs/1",
    "commune": "/api/communes/1",
    "localite": "/api/localites/1",
    "latitude": "14.7167",
    "longitude": "-17.4677",
    "altitude": "12.5",
    "precisionGps": "5.0",
    "nbEnfants04": 1,
    "nbEnfants514": 2,
    "nbAdultes1564": 2,
    "nbPersonnes65Plus": 0,
    "nbHandicapes": 0,
    "nbActifsOccupes": 2,
    "chefMenage": {
        "nomComplet": "Mamadou Diallo",
        "sexe": "M",
        "age": 45,
        "niveauEducation": "secondaire",
        "occupationPrincipale": "commerce",
        "statutMatrimonial": "marie",
        "telephone": "771234567",
        "numeroMobileMoney": "771234567"
    },
    "logement": {
        "typeLogement": "maison",
        "statutOccupation": "proprietaire",
        "nbPieces": 4,
        "materiauMur": "ciment",
        "materiauToit": "tole",
        "materiauSol": "ciment",
        "sourceEau": "robinet",
        "typeToilette": "wc_chasse",
        "sourceEclairage": "electricite",
        "combustibleCuisine": "gaz"
    }
}

Household Fields

Field	Type	Required	Description
tailleMenage	integer	Yes	Number of people (> 0)
region	IRI	Yes	Reference to region
secteur	IRI	Yes	Reference to sector
commune	IRI	Yes	Reference to municipality
localite	IRI	No	Reference to locality
latitude	string	No	GPS latitude (decimal)
longitude	string	No	GPS longitude (decimal)
nbEnfants04	integer	No	Children 0-4 years
nbEnfants514	integer	No	Children 5-14 years
nbAdultes1564	integer	No	Adults 15-64 years
nbPersonnes65Plus	integer	No	People 65+ years

Head of Household Fields

Field	Type	Required	Description
nomComplet	string	Yes	Full name
sexe	string	No	"M" or "F"
age	integer	No	Age
niveauEducation	string	No	Education level
occupationPrincipale	string	No	Activity
statutMatrimonial	string	No	Marital status
telephone	string	No	Phone number
numeroMobileMoney	string	No	Mobile Money number

Housing Fields

Field	Type	Required	Description
typeLogement	string	No	Housing type
statutOccupation	string	No	Occupancy status
nbPieces	integer	No	Number of rooms
materiauMur	string	No	Wall material
sourceEau	string	No	Water source

Success Response

Code: 201 Created

{
    "@context": "/api/contexts/Menage",
    "@id": "/api/menages/123",
    "@type": "Menage",
    "id": 123,
    "codeMenage": "MEN-2024-00123",
    "tailleMenage": 5,
    "statut": "en_attente",
    "chefMenage": {
        "@id": "/api/chef_menages/123",
        "nomComplet": "Mamadou Diallo"
    },
    "createdAt": "2024-01-15T10:30:00+00:00"
}

Error Responses

422 Unprocessable Entity - Validation error

{
    "@context": "/api/contexts/ConstraintViolationList",
    "@type": "ConstraintViolationList",
    "hydra:title": "An error occurred",
    "hydra:description": "tailleMenage: This value should be positive.",
    "violations": [
        {
            "propertyPath": "tailleMenage",
            "message": "This value should be positive."
        },
        {
            "propertyPath": "chefMenage.nomComplet",
            "message": "This value should not be blank."
        }
    ]
}

400 Bad Request

{
    "@context": "/api/contexts/Error",
    "@type": "hydra:Error",
    "hydra:title": "An error occurred",
    "hydra:description": "Syntax error"
}

Examples

cURL

curl -X POST https://sig.example.com/api/menages \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tailleMenage": 5,
    "region": "/api/regions/1",
    "secteur": "/api/secteurs/1",
    "commune": "/api/communes/1",
    "chefMenage": {
      "nomComplet": "Mamadou Diallo",
      "sexe": "M",
      "age": 45,
      "telephone": "771234567"
    },
    "logement": {
      "typeLogement": "maison",
      "nbPieces": 4
    }
  }'

JavaScript

const createMenage = async (data) => {
    const response = await fetch('https://sig.example.com/api/menages', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${localStorage.getItem('token')}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
    });

    if (response.status === 422) {
        const errors = await response.json();
        throw new Error(errors['hydra:description']);
    }

    if (!response.ok) {
        throw new Error('Error during creation');
    }

    return response.json();
};

// Usage
const newMenage = await createMenage({
    tailleMenage: 5,
    region: '/api/regions/1',
    secteur: '/api/secteurs/1',
    commune: '/api/communes/1',
    chefMenage: {
        nomComplet: 'Mamadou Diallo',
        sexe: 'M',
        telephone: '771234567'
    },
    logement: {
        typeLogement: 'maison',
        nbPieces: 4
    }
});

console.log(`Created: ${newMenage.codeMenage}`);

Python

import requests

def create_menage(token, data):
    response = requests.post(
        'https://sig.example.com/api/menages',
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        },
        json=data
    )

    if response.status_code == 422:
        errors = response.json()
        raise Exception(errors['hydra:description'])

    response.raise_for_status()
    return response.json()

# Usage
menage = create_menage(token, {
    'tailleMenage': 5,
    'region': '/api/regions/1',
    'secteur': '/api/secteurs/1',
    'commune': '/api/communes/1',
    'chefMenage': {
        'nomComplet': 'Mamadou Diallo',
        'sexe': 'M'
    },
    'logement': {
        'typeLogement': 'maison'
    }
})

print(f"Created: {menage['codeMenage']}")

Notes

• The codeMenage is automatically generated
• The initial status is en_attente (requires validation)
• GPS fields accept strings (decimal format)
• References (region, secteur, commune) use IRIs
• The head of household and housing are created automatically