GET /api/beneficiaires

Retrieves the paginated list of beneficiaries.

Endpoint

GET /api/beneficiaires

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes

Query Parameters

Pagination

Parameter	Type	Default	Description
page	integer	1	Page number
itemsPerPage	integer	30	Items per page (max: 100)

Filters

Parameter	Type	Description
programme	IRI	Filter by program (/api/programmes/1)
typeBeneficiaire	string	Type: principal or substitut
statutCycle	string	Lifecycle status
actif	boolean	Active beneficiary (true/false)
documentVerifie	boolean	Identity document verified
search	string	Text search (code, name, phone)
region	IRI	Filter by household region
commune	IRI	Filter by household municipality

statutCycle Values

Value	Description
actif	Active beneficiary in the program
suspendu	Temporarily suspended
gradue	Completed the program (graduated)
sorti	Left the program
en_recertification	In recertification process

Sorting

Parameter	Values	Description
order[dateEnrolement]	asc, desc	Sort by enrollment date
order[nomComplet]	asc, desc	Sort by name
order[codeBeneficiaire]	asc, desc	Sort by code

Success Response

Code: 200 OK

{
    "@context": "/api/contexts/Beneficiaire",
    "@id": "/api/beneficiaires",
    "@type": "hydra:Collection",
    "hydra:totalItems": 856,
    "hydra:member": [
        {
            "@id": "/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000",
            "@type": "Beneficiaire",
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "codeBeneficiaire": "BEN-2024-00001",
            "nomComplet": "Fatou Diallo",
            "telephone": "771234567",
            "modePaiement": "orange_money",
            "compteMobile": "771234567",
            "typeBeneficiaire": "principal",
            "statutCycle": "actif",
            "actif": true,
            "documentVerifie": true,
            "sexe": "F",
            "nombreCyclesCompletes": 3,
            "menage": {
                "@id": "/api/menages/1",
                "codeMenage": "MEN-2024-00001"
            },
            "programme": {
                "@id": "/api/programmes/1",
                "nom": "Transferts Monétaires 2024"
            },
            "dateEnrolement": "2024-01-15T10:30:00+00:00"
        }
    ],
    "hydra:view": {
        "@id": "/api/beneficiaires?page=1",
        "@type": "hydra:PartialCollectionView",
        "hydra:first": "/api/beneficiaires?page=1",
        "hydra:last": "/api/beneficiaires?page=29",
        "hydra:next": "/api/beneficiaires?page=2"
    }
}

Examples

cURL - Simple List

curl https://sig.example.com/api/beneficiaires \
  -H "Authorization: Bearer TOKEN"

cURL - With Filters

curl "https://sig.example.com/api/beneficiaires?typeBeneficiaire=principal&statutCycle=actif&actif=true" \
  -H "Authorization: Bearer TOKEN"

cURL - Search

curl "https://sig.example.com/api/beneficiaires?search=Diallo" \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getBeneficiaires = async (filters = {}) => {
    const params = new URLSearchParams();

    if (filters.programme) params.append('programme', filters.programme);
    if (filters.typeBeneficiaire) params.append('typeBeneficiaire', filters.typeBeneficiaire);
    if (filters.statutCycle) params.append('statutCycle', filters.statutCycle);
    if (filters.actif !== undefined) params.append('actif', filters.actif);
    if (filters.search) params.append('search', filters.search);
    if (filters.page) params.append('page', filters.page);

    const response = await fetch(
        `https://sig.example.com/api/beneficiaires?${params}`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );

    return response.json();
};

// Usage
const data = await getBeneficiaires({
    typeBeneficiaire: 'principal',
    statutCycle: 'actif',
    actif: true
});

console.log(`Total: ${data['hydra:totalItems']} beneficiaries`);
data['hydra:member'].forEach(ben => {
    console.log(`${ben.codeBeneficiaire} - ${ben.nomComplet}`);
});

Python

import requests

def get_beneficiaires(token, **filters):
    response = requests.get(
        'https://sig.example.com/api/beneficiaires',
        headers={'Authorization': f'Bearer {token}'},
        params=filters
    )
    return response.json()

# Simple list
beneficiaires = get_beneficiaires(token)
print(f"Total: {beneficiaires['hydra:totalItems']}")

# With filters
beneficiaires = get_beneficiaires(
    token,
    typeBeneficiaire='principal',
    statutCycle='actif',
    actif='true'
)

for ben in beneficiaires['hydra:member']:
    print(f"- {ben['codeBeneficiaire']}: {ben['nomComplet']}")

Notes

• Beneficiaries are linked to a household (required relationship)
• A household can have one primary beneficiary and one substitute
• The sexe field is copied from the head of household for statistics purposes
• Text search works on code, name, and phone number