Statut prime d'activité

Statut bénéficiaire de la prime d'activité, majorée ou non.

Fournisseur de la donnée

CNAF & MSA

Périmètre

Particuliers concernés :

✅ Le périmètre de l’API est a priori exhaustif et couvre tous les bénéficiaires de la prime d’activité (PPA).

Les enfants d’un allocataire de la prime d’activité ne sont pas considérés comme des bénéficiaires.

⚙️ Vérification en cours avec le fournisseur de données pour confirmer le périmètre exact.

Périmètre géographique :

✅ France Métropolitaine
✅ Départements d’Outre-mer
❌ Les collectivités d’Outre-mer, ayant un autre système de sécurité sociale, ne sont pas concernées par cette API.
⚙️ Personne de nationalité étrangère - Vérification en cours avec le fournisseur de la donnée pour confirmer la prise en charge. D’un point de vue métier, des prestations sont bien délivrées à une personne étrangère ayant un numéro d’immatriculation en attente (NIA) mais nous ne savons pas encore si le NIA est supporté par l’API.

Actualisation de la donnée :

Les données sont mises à jour en temps réel et issues du répertoire national commun de la protection sociale (RNCPS) opéré par la CNAV (Caisse nationale d’assurance vieillesse). Les données du répertoire sont remontées directement par les différents organismes comme la CNAF pour les assurés du régime général et la MSA pour les assurés au régime agricole.

Cas d'usages

Fiches pratiques et cas d'usages pour lesquels l'API est utile :

Spécifications de l'API

Format de l'information

Donnée structurée JSON

Modalités d'appel

Identité pivot
FranceConnect

Détails des modalités

Disponibilité

Page de statut des API

Disponible 24h/24 et 7j/7

Limite d'appels

20 requêtes / seconde
(partagé entre API du groupe)

Spécifications techniques :

Consulter le swagger Cas de tests

Modalités d'appel

L’API est appelable avec l’identité de l’allocataire principal ou avec celle d’une personne composant son foyer (conjoint, enfants et autres ayants droit).

⚠️ Les enfants en garde partagée (résidence alternée) ne sont pas couverts : l’API ne peut pas être appelée avec leur identité.

Cette API propose deux modalités d’appel :

FranceConnect

Avec la modalité d’appel FranceConnect.

Identité pivot

Avec les données d’identité :

Nom de famille (nom de naissance)¹, nom d’usage, prénoms³, sexe⁴, date de naissance de l’allocataire², code COG du pays de naissance¹ ;
Commune de naissance (fortement recommandé) :
- Si le lieu de naissance est en France, la commune de naissance 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.

¹ Obligatoire
² Obligatoire pour l’option 2 du lieu de naissance.
³ 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.
⁴ Fortement recommandé pour optimiser l’identification du particulier.

Les données

Cette API indique si le particulier est bénéficiaire de la prime d’activité, En précisant la date d’ouverture du droit.

Informations renvoyées en JSON :

Aperçu d'un exemple de réponse JSON

Est bénéficiaire de la prime d'activité

prime_activite ex: true

Indique que le particulier est bénéficiaire de la prime d'activité au moment de l'appel.

Prime d'activité avec majoration

prime_activite_majoration

Indique que la prime d'activité du particulier bénéficiaire est majorée au moment de l'appel.
Si ce champ est à false, cela signifie que la prime d'activité n'est pas majorée.
Ce champ sera null si le particulier n'est pas bénéficiaire de la prime d'activité.

Date d'ouverture du droit à la prime d'activité

prime_activite ex: 1992-11-20

Date de début de droit à la prime d'activité si le particulier est bénéficiaire.
Ce champ est null dans le cas où le particulier n'est pas bénéficiaire de la prime d'activité.

Les scopes

Les champs de la réponse signalés par une étiquette violette ne sont retournés que si votre jeton porte le scope correspondant. En savoir plus sur le mécanisme des scopes.

Statut Prime activité (prime_activite)
Prime activité majoration (prime_activite_majoration)

Erreurs

Lorsque cette API ne peut pas retourner les informations demandées, elle renvoie un code erreur. Les erreurs communes à toutes les API (jeton, paramètres obligatoires, quotas) sont décrites dans la nomenclature des codes erreurs ; celles qui suivent sont celles que cet endpoint peut renvoyer, y compris les erreurs génériques de son fournisseur de données.

Cette liste est aussi servie au format JSON, sans jeton, sur https://particulier.api.gouv.fr/api/errors?operation_id=api_particulier_v3_cnav_prime_activite_with_civility.

422 — Entité non traitable
Code	Signification
`00363`	Entité non traitable La date de naissance n'est pas correctement formatté
`00365`	Entité non traitable Le lieu de naissance n'est pas correctement formaté
`00367`	Entité non traitable Le ou les prénoms sont manquants.
`00400`	Entité non traitable Le code pays INSEE n'est pas correctement formaté
`00405`	Entité non traitable Le request_id n'est pas correctement formaté : l'en-tête X-Request-Id, s'il est fourni, doit être un UUID v4
`00420`	Entité non traitable Le nom de naissance est manquant
`00422`	Entité non traitable L'annee de naissance est manquante
`00427`	Entité non traitable Le sexe de l'état civil est manquant
`00428`	Entité non traitable Le code cog du département de naissance est manquant ou invalide
`36560`	Identité non reconnue par le fournisseur de données Les paramètres d'identité fournis ne correspondent à aucune personne connue du fournisseur de données.
`36561`	Paramètres de civilité refusés par le fournisseur de données Un ou plusieurs paramètres de civilité ont été refusés par le fournisseur de données.

404 — Non trouvé
Code	Signification
`10003`	Dossier allocataire absent MSA Le dossier allocataire n'a pas été trouvé auprès de la MSA.
`23003`	Dossier allocataire absent CNAF Le dossier allocataire n'a pas été trouvé auprès de la CNAF.
`35003`	Allocataire non référencé L'allocataire n'est pas référencé auprès des caisses éligibles
`40003`	Dossier allocataire absent RNCPS Le dossier allocataire n'a pas été trouvé auprès du RNCPS.

502 — Erreur du fournisseur de données
Code	Signification
`36000`	Erreur interne du fournisseur de données La réponse retournée par le fournisseur de données est invalide et a été identifié comme étant une erreur interne. Si le problème persiste, consultez la page de status ou contactez nous sur le support.
`36001`	Service non disponible Service du fournisseur de données temporairement indisponible ou en maintenance.
`36004`	Erreur de résolution DNS Problème de résolution DNS de l'adresse du serveur
`36008`	Erreur auprès du fournisseur de données : trop de requêtes Erreur de fournisseur de donnée : Trop de requêtes effectuées, veuillez réessayer plus tard.
`36009`	Erreur de connexion sécurisée (TLS) avec le fournisseur de données La connexion sécurisée avec le fournisseur de données n'a pas pu être établie : certificat invalide ou expiré, ou échec de la négociation TLS. L'équipe technique a été notifiée de cette erreur pour investigation.
`36011`	Erreur temporaire du fournisseur de données Merci de réessayer dans quelques instants
`36999`	Erreur inconnue du fournisseur de données La réponse retournée par le fournisseur de données est invalide et inconnue de notre service. L'équipe technique a été notifiée de cette erreur pour investigation.

503 — Service non disponible
Code	Signification
`36020`	Maintenance du fournisseur de données Le fournisseur de données semble être en maintenance

504 — Intermédiaire hors délai
Code	Signification
`36002`	Intermédiaire hors-délai Temps d’attente d’une réponse du fournisseur de données écoulé.

Modalité FranceConnect

En appelant cet endpoint avec un jeton FranceConnect, les erreurs suivantes s'ajoutent aux précédentes.

422 — Entité non traitable
Code	Signification
`51564`	Identité inexploitable renvoyée par le fournisseur de données L'identité renvoyée par le fournisseur de données est incomplète ou invalide.

502 — Erreur du fournisseur de données
Code	Signification
`51000`	Erreur interne du fournisseur de données La réponse retournée par le fournisseur de données est invalide et a été identifié comme étant une erreur interne. Si le problème persiste, consultez la page de status ou contactez nous sur le support.
`51001`	Service non disponible Service du fournisseur de données temporairement indisponible ou en maintenance.
`51004`	Erreur de résolution DNS Problème de résolution DNS de l'adresse du serveur
`51008`	Erreur auprès du fournisseur de données : trop de requêtes Erreur de fournisseur de donnée : Trop de requêtes effectuées, veuillez réessayer plus tard.
`51009`	Erreur de connexion sécurisée (TLS) avec le fournisseur de données La connexion sécurisée avec le fournisseur de données n'a pas pu être établie : certificat invalide ou expiré, ou échec de la négociation TLS. L'équipe technique a été notifiée de cette erreur pour investigation.
`51011`	Erreur temporaire du fournisseur de données Merci de réessayer dans quelques instants
`51999`	Erreur inconnue du fournisseur de données La réponse retournée par le fournisseur de données est invalide et inconnue de notre service. L'équipe technique a été notifiée de cette erreur pour investigation.

401 — Non autorisé
Code	Signification
`51501`	Accès non autorisé Le jeton d'accès est mal formaté.
`51502`	Accès non autorisé Le jeton d'accès n'a pas été trouvé ou est expiré.
`51504`	Accès non autorisé Le jeton d'accès FranceConnect est manquant. Cet endpoint requiert un jeton d'accès FranceConnect transmis via l'en-tête Authorization: Bearer.

503 — Service non disponible
Code	Signification
`51020`	Maintenance du fournisseur de données Le fournisseur de données semble être en maintenance

504 — Intermédiaire hors délai
Code	Signification
`51002`	Intermédiaire hors-délai Temps d’attente d’une réponse du fournisseur de données écoulé.

Questions & réponses

L’algorithme d’identification du fournisseur de données s’appuie sur l’ensemble des paramètres d’entrée, mais certains ont un poids plus important :

Nom de naissance ;
Année de naissance ;
Lieu de naissance.

Si ces trois informations sont correctement fournies, le particulier peut être identifié même si les autres paramètres comportent des erreurs. En revanche, si ces informations ne sont pas renseignées ou sont erronées, le risque de recevoir une réponse 404 (dossier allocataire absent) augmente significativement.

Il est donc fortement recommandé de renseigner le lieu de naissance afin de maximiser les chances d’identification du particulier.

Lorsque l’API est appelée avec l’identité pivot, le lieu de naissance est fortement recommandé pour identifier correctement le particulier.

Pour les particuliers nés en France: le code COG pays 99100 doit être renseigné. La commune de naissance peut être renseignée via deux options différentes :
- Option 1 : L’API est appelée avec le code COG commune lui-même. Pour aider les usagers à renseigner leur code COG, consultez la publication suivante :
  ✒️ Aider les usagers à renseigner leur lieu de naissance par code COG - Lire la publication du 08/11/2023
- Option 2 : L’API est appelée avec le nom de la commune de naissance et le code du département de naissance. La date de naissance est obligatoire car c’est elle qui permettra à l’API de faire la correspondance avec le bon code COG.
Pour les particuliers nés à l’étranger: le code COG pays doit être renseigné.

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 particulier renseigne les informations de sa commune de naissance (forcément en France).

Historique

Ce que change le passage à la V.3 d’API Particulier:

Suppression de la date de fin car cette donnée était calculée et présentait le risque de ne pas être juste dans toutes les situations ;
Tous les changements sont décrits dans la table de correspondance du guide migration

Documentations des anciennes API :

cnav/v2/prime_activite

Plus d'informations sur la gestion de version API Particulier dans cette documentation.

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 sont soumises 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

Cas d'usages

Fiches pratiques et cas d'usages pour lesquels l'API est utile :

Spécifications de l'API

Format de l'information

Donnée structurée JSON

Modalités d'appel

Identité pivot
FranceConnect

Détails des modalités

Disponibilité

Page de statut des API

Disponible 24h/24 et 7j/7

Limite d'appels

20 requêtes / seconde
(partagé entre API du groupe)

Spécifications techniques :

Consulter le swagger Cas de tests

Statut prime d'activité

Périmètre

Particuliers concernés :

Périmètre géographique :

Actualisation de la donnée :

Cas d'usages

Spécifications de l'API

Format de l'information

Modalités d'appel

Disponibilité

Limite d'appels

Spécifications techniques :

Modalités d'appel

Les données

Informations renvoyées en JSON :

Les scopes

Erreurs

Modalité FranceConnect

Questions & réponses

Quels paramètres ont le plus de poids dans l'algorithme d'identification ?

Appel avec l'identité pivot, comment renseigner le lieu de naissance ?

Historique

Conditions d'utilisation des données

Ouverture de la donnée :

Conditions générales :

Cas d'usages

Spécifications de l'API

Format de l'information

Modalités d'appel

Disponibilité

Limite d'appels

Spécifications techniques :

Abonnez-vous à nos lettres d’information