Quotient familial CAF & MSA Nouvelle version

Quotient familial délivré par la CAF ou la MSA et composition de la famille de l'allocataire.

Logo du fournisseur de données
Fournisseur de la donnée

CNAF & MSA


Périmètre

Particuliers concernés :

Cette API concerne les allocataires de la majorité des régimes :

  • ✅ le régime agricole (MSA) ;
  • ✅ le régime général ;
  • ✅ les titulaires de l’éducation nationale ;
  • ✅ les retraités de la fonction publique d’État et des collectivités locales ;
  • ✅ les régimes spéciaux suivants : artiste-auteur-compositeur, France Télécom, industries électriques et gazières, marin du commerce et pêche, mines (régime général), poste, RATP, SNCF, navigation intérieure en cas d’accord local et les pensions des autres régimes.

Ne sont pas concernés par cette API, les bénéficiaires des régimes suivants :

  • ❌ le régime des titulaires de l’Assemblée nationale et du Sénat ;
  • ❌ le régime de la navigation intérieure sauf lorsqu’un accord local est passé, et que le régime est alors pris en compte par la CAF.

Périmètre géographique :

  • ✅ France métropolitaine
  • ✅ DROM COM
  • ✅ Allocataires de nationalité étrangère

Actualisation de la donnée :

Les données sont mises à jour en temps réel, cette API opérée par la CNAV (Caisse nationale d’assurance vieillesse) est reliée au système d’information de la Caisse nationale des allocations familiales (CNAF) et à celui de la mutualité sociale agricole (MSA).

⚠️ Les informations obtenues sont représentatives de la situation connue par la CNAF et la MSA au moment de l’appel, il est donc possible qu’un quotient familial appelé pour un mois donné à un instant T, soit différent s’il est redemandé à un instant T+. En savoir plus.

Spécifications de l'API

Format de l'information

Donnée structurée JSON

Modalités d'appel

  • Identité pivot
  • FranceConnect Pictogramme fournisseurs de données regroupés
Détails des modalités

Disponibilité

Temps réel :
Page de statut des API
Disponible 24h/24 et 7j/7

Spécifications techniques :

Consulter le swagger Cas de tests

Modalités d'appel

L’API est uniquement appelable avec les informations de l’allocataire.
Il n’est pas possible d’interroger cette API avec les informations des ayants droit.


Deux modalités d’appel sont possibles :

Cette API est FranceConnectée FranceConnect

Avec la modalité d’appel FranceConnect.

Identité pivot

  • Nom de naissance*, nom d'usage, prénoms1, sexe*, date de naissance de l'allocataire** ;
  • Lieu de naissance :
    • Si le lieu de naissance est en France, la commune de naissance est obligatoire, elle peut être saisie de deux façons différentes :
      • Option 1 : Code COG de la commune de naissance*. En savoir plus ;
      • Option 2 : Nom de la commune de naissance* et code du département de naissance*. Pour cette option, la date de naissance est obligatoire. En savoir plus.
      Pour chacune des deux options ci-dessus, le code COG de la France 99100* doit également être renseigné en paramètre d'appel. Vous n'avez pas besoin de le demander à l'usager, il peut être déduit de la commune de naissance.
    • Si le lieu de naissance est à l'étranger : code COG du pays de naissance*.

* Obligatoire | ** Obligatoire pour l’option 2 du lieu de naissance. 1 Fournir plusieurs prénoms permet de limiter les risques d’homonymie mais un seul prénom peut fonctionner. Attention, l’usager doit compléter chaque prénom dans un champ distinct.

⚠️ Message API Particulier du 04.06.2024 : Nous avons constaté que les appels effectués sans nom de naissance et avec le nom d’usage ne fonctionnent pas dans une très grande partie des cas. Après investigation auprès de la CNAV (opérateur de l’API source), API Particulier a donc décidé de passer le paramètre “Nom de naissance” en obligatoire.

Les données

Cette API délivre :

  • la composition familiale du particulier, en savoir plus ;
  • le quotient familial CAF ou MSA du particulier. Par défaut, le quotient familial du mois en cours est transmis. Le QF de l’allocataire est disponible pour les 24 mois précédents en précisant le mois et l’année dans l’appel ;
  • l’adresse du particulier au format de La Poste. ⚠️ Cette adresse est déclarative. Si l’usager a changé d’adresse et n’a pas actualisé son adresse auprès de la CAF ou de la MSA, l’information sera donc obsolète.

Le quotient familial au sens de la CNAF ou de la MSA a une définition différente du quotient familial de l’administration fiscale, en savoir plus.

Le QF CNAF est calculé seulement pour les allocataires dont les ressources sont déclarées. En effet, pour calculer le quotient familial, la CNAF collecte tous les mois auprès de la DGFIP les ressources de l’individu (revenus salariés et non-salariés, du capital, rentes …). Elle récupère le bilan en fin d’année. Sans la réception de ces ressources, le QF CNAF ne peut être calculé : une erreur est renvoyée par l’API.

Si le particulier n’a plus d’allocations, son QF n’est pas renvoyé. Une erreur est transmise par l’API.

Informations renvoyées en JSON :

Données d'identité de l'allocataire et du conjoint
Liste des données d'identité de l'allocataire appelé et de celles du conjoint le cas échéant. La provenance de ces données n'est pas sourcée précisément et diffère selon la CAF ou la MSA.
Cette propriété contient 1 ou plusieurs éléments ayant les spécifications suivantes :
Nom
ex: JACQUES
Nom de naissance de l'allocataire ou du conjoint.
Nom d'usage
ex: DUPONT
Nom d'usage de l'allocataire ou du conjoint.
Prénoms
ex: JEAN-PIERRE THOMAS
Prénoms de l'allocataire ou du conjoint.
Date de naissance
ex: 2000-01-20
Date de naissance de l'allocataire ou du conjoint au format AAAA-MM-JJ.
Sexe
ex: M
Sexe de l'allocataire ou du conjoint.
Données d'identité des enfants composant la famille
Liste des données d'identité des enfants composant la famille, le cas échéant. La provenance de ces données n'est pas sourcée précisément et diffère selon la CAF ou la MSA.
Cette propriété contient 1 ou plusieurs éléments ayant les spécifications suivantes :
Nom de naissance
ex: DUPONT
Nom de naissance de l'enfant.
Nom d'usage
Nom d'usage de l'enfant.
Prénoms
ex: JEAN-PIERRE THOMAS JUNIOR
Prénoms de l'enfant.
Date de naissance
ex: 2000-01-20
Date de naissance de l'enfant au format AAAA-MM-JJ.
Sexe
ex: M
Sexe de l'enfant.
Adresse de la famille
Adresse de la famille au format de La Poste. Cette adresse est déclarative. Si l'usager a changé d'adresse et n'a pas actualisé son adresse auprès de la CAF ou de la MSA, l'information sera donc obsolète.
Identité du destinataire
ex: Monsieur JEAN JACQUES
Identité du destinataire : Civilité, titre ou qualité + nom et prénom
Complément d'information du destinataire ou point de remise
Complément d'information du point géographique
Voie
ex: 1 RUE DE LA GARE
Numéro et libellé de la voie.
Lieu-dit
Lieu-dit ou service particulier de distribution : poste restante, boîte postale.
Code postal
ex: 75002
Code postal et localité de destination.
Pays
ex: FRANCE
Informations du quotient familial (QF)
Données relatives à l'attribution du quotient familial CAF ou MSA.
Fournisseur du QF
ex: MSA
Indique si le quotient familial de l'allocataire provient de la CAF ou de la MSA.
Valeur du QF
ex: 1045
Valeur du quotient familial calculé par la CAF ou la MSA.
Année effective du QF
ex: 2023
Ce champ indique l'année effective du quotient familial appelé. C'est-à-dire l'année à laquelle s'applique le quotient familial. Cette année peut être différente de l'année de calcul du quotient si ce dernier a été recalculé suite à la réception d'informations rectifiant la situation de l'allocataire.
- Si aucune année et aucun mois n'ont été renseignés en paramètres d'appel, le quotient familial retourné sera celui du mois de l'année en cours. - Si aucune année n'a été renseignée et que le mois est renseigné, le quotient familial retourné sera celui du mois spécifié pour l'année en cours. En revanche, si la date finalement composée avec cette règle s'avère dans le futur (mois postérieur au moins en cours), l'API renvoie un erreur 400.
Mois effectif du QF
ex: 6
Mois effectif du quotient familial. C'est-à-dire le mois auquel s'applique le quotient familial. Ce mois peut être différent du mois de calcul du quotient si ce dernier a été recalculé suite à la réception d'informations rectifiant la situation de l'allocataire.
- Si aucun mois et aucune année n'ont été renseignés en paramètres d'appel, le quotient familial retourné sera celui du mois de l'année en cours. - Si le mois est renseigné mais qu'aucune année n'est saisie, le quotient familial retourné sera celui du mois spécifié pour l'année en cours. En revanche, si la date finalement composée avec cette règle s'avère dans le futur (mois postérieur au moins en cours), l'API renvoie un erreur 400. - Si aucun mois n'a été renseigné mais que l'année a été spécifiée en paramètres d'appel, le quotient familial retourné sera celui du mois en cours pour l'année spécifiée.
Année du calcul du QF
ex: 2023
Année lors de laquelle le calcul du quotient familial demandé a été effectué. Cette année peut différer de l'année effective du quotient familial.
Pour la CAF, le quotient familial est recalculé uniquement si de nouvelles informations sont venues rectifier la situation de l'allocataire.
Pour la MSA, le quotient familial est systématiquement recalculé ; l'année correspond donc toujours à l'année courante.
Mois du calcul du QF
ex: 9
Mois lors duquel le calcul du quotient familial demandé a été effectué. Ce mois peut différer du mois effectif du quotient familial.
Pour la CAF, le quotient familial est recalculé uniquement si de nouvelles informations sont venues rectifier la situation de l'allocataire.
Pour la MSA, le quotient familial est systématiquement recalculé ; le mois correspond donc toujours au mois en cours.

Questions & réponses

Le quotient familial retourné par l’API est le quotient familial de la CAF ou de la MSA. Ce QF est différent de celui de l’administration fiscale car il prend en compte les prestations familiales. Contrairement au quotient familial DGFIP calculé au moment de la déclaration de revenu, le QF CAF/MSA est revu à chaque changement de situation familiale et/ou professionnelle.

Calcul du QF CAF/MSA : Revenu imposable de l’année N-2 divisé par 12 + les prestations familiales du mois de référence, le tout divisé par le nombre de parts fiscales du foyer.

Source : Caf.fr

Le quotient familial CAF ou MSA d’un même mois peut changer. Il est recalculé fréquemment au cours du temps par la CAF et la MSA. En effet, la situation de la personne peut évoluer : perte d’un emploi, évolution des ressources, arrivée d’un enfant, majorité d’un enfant, modification de la législation, évolution des allocations logement etc.
Cette variation apparaît notamment entre le quotient familial du mois en cours appelé en début de mois ou en fin de mois.

Deplus, la date du calcul du quotient familial diffère selon qu’il s’agit du quotient de la CAF ou de la MSA.

  • La CAF effectue une sauvegarde des quotients recalculés uniquement lorqu’un changement subvient du côté de l’allocataire.

    Par exemple, un appel le 28 juin 2023, du quotient du mois en cours (juin 2023) : La CAF renverra le QF qu’elle a en mémoire, par exemple calculé le 19 juin 2023.

  • La MSA effectue un recalcul du quotient familial à chaque appel de l’API.

    Par exemple, un appel le 28 juin 2023 du quotient familial du mois en cours (juin 2023) : la MSA recalculera le QF le 28 juin 2023.

La notion de « composition familiale » peut correspondre à différentes définitions dans les administrations qui n’y comptent pas les mêmes personnes. Par exemple, pour calculer l’impôt sur le revenu d’un foyer, le service des impôts s’intéresse à une composition familiale appelée « foyer fiscal », et dont la nature est différente de celle renvoyée par cette API.

La composition familiale renvoyée par cette API correspond à celle établie pour effectuer le calcul du quotient familial, et donc à celle déclarée par les allocataires à la CAF et à la MSA.
Dans cette composition familiale, les personnes suivantes sont comprises :

  • L’adulte allocataire de la CAF ou de la MSA ;
  • Son ou sa conjointe le cas échéant ;
  • le ou les enfants dont la responsabilité affective et éducative, les frais liés au logement, à la nourriture et à l’éducation, sont assumés par l’allocataire qui n’est pas obligé d’avoir un lien de parenté direct. Les enfants sont pris en compte dès la grossesse, jusqu’à 21 ans en métropole (22 dans les DROM) et sous les conditions détaillées dans ce guide de la Caf.

Cette notion d’enfant à charge est différente de celle retenue par l’administration fiscale : par exemple, un enfant peut être toujours rattaché fiscalement à ses parents, mais ne plus faire partie de la composition familiale au sens de la CAF ou de la MSA.
C’est le cas d’un enfant ayant quitté le foyer de ses parents et ayant ouvert son propre dossier d’allocataire pour bénéficier d’une aide (par exemple les APL ou le RSA), mais qui souhaite tout de même être rattaché à la déclaration fiscale de ses parents.
Cet enfant appartiendra au même foyer fiscal que ses parents au sens de l’administration fiscale, mais à une famille différente selon la CAF ou la MSA.

Pour chacune des personnes de cette « famille » au sens de la CAF ou de la MSA, cette API renvoie les informations suivantes :

  • Nom d’usage ;
  • Prénoms ;
  • Jour, mois et année de naissance ;
  • Sexe.

Lorsque l’API est appelée avec l’identité pivot, pour identifier correctement le particulier, le système d’information a besoin de récupérer le lieu de naissance du particulier.

  • Pour les particuliers nés en France: le code COG pays 99100 est obigatoire. La commune de naissance est également obligatoire et peut-être renseignée via deux options différentes :

  • Pour les particuliers nés à l’étranger: le code COG pays est obigatoire.

Le code COG du pays de naissance est obligatoire pour tous les appels. Pour simplifier le parcours des usagers, évitez de demander aux particuliers nés en France de saisir leur pays de naissance, puisque vous pouvez le paramétrer directement -code COG pays France 99100-, dès qu’un particuloer renseigne les informations de sa commune de naissance (forcément en France).

Conditions d'utilisation des données

Ouverture de la donnée :

Donnée protégée

Conditions générales :

Cette API et l’utilisation de ses données est soumise aux CGU générales d’API Particulier, dont voici les principaux éléments auxquels vous vous engagez :

  • ne demander que les données strictement nécessaires ;
  • ne pas utiliser votre jeton d’accès pour une démarche différente de celle indiquée lors de votre demande (le cas échéant le jeton sera révoqué) ;
  • présenter les données obtenues uniquement aux seuls agents habilités et à tracer l’accès de ces agents aux données ;
  • ne pas commercialiser les données reçues et à ne pas les communiquer à des tiers en dehors des cas prévus par la loi.
L’ensemble des conditions sont consultables et téléchargeables ci-dessous :

CGU API Particulier

Spécifications de l'API

Format de l'information

Donnée structurée JSON

Modalités d'appel

  • Identité pivot
  • FranceConnect Pictogramme fournisseurs de données regroupés
Détails des modalités

Disponibilité

Temps réel :
Page de statut des API
Disponible 24h/24 et 7j/7

Spécifications techniques :

Consulter le swagger Cas de tests