GET /api/beneficiaires/{id}

Retrieves detailed information about a beneficiary.

Endpoint

GET /api/beneficiaires/{id}

URL Parameters

Parameter	Type	Description
id	UUID	Unique identifier of the beneficiary

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes

Success Response

Code: 200 OK

{
    "@context": "/api/contexts/Beneficiaire",
    "@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",
    "compteBancaire": null,
    "numeroMTN": null,
    "typeBeneficiaire": "principal",
    "actif": true,
    "sexe": "F",
    "statutEnrolement": "actif",
    "dateEnrolement": "2024-01-15T10:30:00+00:00",
    "dateSortie": null,
    "motifSortie": null,
    "documentVerifie": true,
    "dateVerificationDocument": "2024-01-20",
    "statutCycle": "actif",
    "prochaineRecertification": "2025-01-15",
    "estGradue": false,
    "dateGraduation": null,
    "tauxConformiteGlobal": "92.50",
    "nombreCyclesCompletes": 3,
    "dernierSuivi": "2024-06-15",
    "menage": {
        "@id": "/api/menages/1",
        "@type": "Menage",
        "id": 1,
        "codeMenage": "MEN-2024-00001",
        "tailleMenage": 5,
        "chefMenage": {
            "@id": "/api/chef_menages/1",
            "nomComplet": "Mamadou Diallo"
        },
        "region": {
            "@id": "/api/regions/1",
            "nom": "Dakar"
        },
        "commune": {
            "@id": "/api/communes/1",
            "nom": "Commune 1"
        }
    },
    "programme": {
        "@id": "/api/programmes/1",
        "@type": "Programme",
        "id": 1,
        "nom": "Transferts Monétaires 2024",
        "code": "TM-2024"
    },
    "beneficiairePrincipal": null
}

Error Responses

404 Not Found

{
    "@context": "/api/contexts/Error",
    "@type": "hydra:Error",
    "hydra:title": "An error occurred",
    "hydra:description": "Item not found for \"/api/beneficiaires/invalid-uuid\""
}

403 Forbidden

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

Examples

cURL

curl https://sig.ucp-pch.org/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getBeneficiaire = async (id) => {
    const response = await fetch(
        `https://sig.ucp-pch.org/api/beneficiaires/${id}`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );

    if (response.status === 404) {
        throw new Error('Beneficiary not found');
    }

    return response.json();
};

// Usage
try {
    const beneficiaire = await getBeneficiaire('550e8400-e29b-41d4-a716-446655440000');
    console.log(`Name: ${beneficiaire.nomComplet}`);
    console.log(`Type: ${beneficiaire.typeBeneficiaire}`);
    console.log(`Status: ${beneficiaire.statutCycle}`);
    console.log(`Completed cycles: ${beneficiaire.nombreCyclesCompletes}`);
    console.log(`Household: ${beneficiaire.menage.codeMenage}`);
} catch (error) {
    console.error(error.message);
}

Python

import requests

def get_beneficiaire(token, beneficiaire_id):
    response = requests.get(
        f'https://sig.ucp-pch.org/api/beneficiaires/{beneficiaire_id}',
        headers={'Authorization': f'Bearer {token}'}
    )

    if response.status_code == 404:
        raise Exception('Beneficiary not found')

    return response.json()

# Usage
beneficiaire = get_beneficiaire(token, '550e8400-e29b-41d4-a716-446655440000')
print(f"Code: {beneficiaire['codeBeneficiaire']}")
print(f"Name: {beneficiaire['nomComplet']}")
print(f"Payment method: {beneficiaire['modePaiement']}")
print(f"Compliance rate: {beneficiaire['tauxConformiteGlobal']}%")

Response Fields

Identity

Field	Type	Description
id	UUID	Unique identifier
codeBeneficiaire	string	Unique code (BEN-YYYY-NNNNN)
nomComplet	string	Full name of the beneficiary
telephone	string	Phone number
sexe	string	"M" or "F"

Payment

Field	Type	Description
modePaiement	string	Payment method (orange_money, wave, etc.)
compteMobile	string	Mobile Money account number
compteBancaire	string	Bank account number
numeroMTN	string	MTN Mobile Money number

Type and Status

Field	Type	Description
typeBeneficiaire	string	"principal" or "substitut"
actif	boolean	Active beneficiary
statutEnrolement	string	Enrollment status
statutCycle	string	Lifecycle status
documentVerifie	boolean	Identity document verified

Lifecycle

Field	Type	Description
dateEnrolement	datetime	Enrollment date
prochaineRecertification	date	Next recertification date
estGradue	boolean	Has completed the program
dateGraduation	date	Graduation date
nombreCyclesCompletes	integer	Number of completed payment cycles
tauxConformiteGlobal	decimal	Conditionality compliance rate (0-100)
dernierSuivi	date	Last field monitoring date

Notes

• Beneficiary identifiers are UUIDs
• A substitute beneficiary references their primary beneficiary via beneficiairePrincipal
• The compliance rate is calculated across all program conditionalities
• Recertification is periodically required to maintain eligibility