API Particulier

Les données des particuliers pour les administrations

Nouvelle API quotient familial CAF & MSA : Bureau ouvert en visio le 03/12/2024 à 10 heures.

Mercredi 8 novembre 2023 - Publication

Aider les usagers à renseigner leur lieu de naissance par code COG

Image de présentation de l'article sur le numéro de TVA intracommunautaire

Qu’est que le code COG ?
Le code COG (Code Officiel Géographique) est un code permettant de repérer notamment les communes et les territoires étrangers. Ce code est différent du code postal et peut évoluer dans le temps. C’est pourquoi, le code COG demandé pour identifier un particulier est le code COG du pays de naissance et de la commune de naissance si le particulier est né à en France.
Pour en savoir plus : Code COG - Insee.fr et Codification des pays et territoires étrangers - Insee.fr.


Inconnu des usagers, le code COG démandé par plusieurs API

Contrairement aux personnes gravitant dans la sphère administrative, les usagers ne connaissent pas leur code COG de naissance. Ils sont d’ailleurs susceptibles de le confondre avec leur code postal qui est complètement différent.

Pourtant, une majorité des API du bouquet API Particulier nécessitent la saisie du code COG en paramètre d’appel pour identifier le particulier :

L’utilisation du code COG comme référence pour appeler les API est peu susceptible d’évoluer. En intégrant ces API dans vos démarches, il est donc nécessaire de bien concevoir le parcours d’un usager ne passant pas par FranceConnect afin que la saisie de son code COG de naissance ne pose pas de problème.

❌ Ne pas faire : un champ “Code COG” sans explication

Il faut éviter de proposer un champ “Code COG” brut, sans explication. Ce champ pourrait être incompris par l’usager et donc être mal complété.

Ce n’est pas anodin pour votre démarche car cela peut avoir les conséquences suivantes :

Dans ce guide, nous vous proposons donc deux parcours différents conçus pour faciliter le renseignement de ce paramètre d’appel :

✅ Option 1 : Saisie du code COG par l’usager, accompagné d’un tutoriel

Le code COG, une partie du numéro de sécurité sociale :

Le code COG est compris dans le numéro d’inscription au répertoire (NIR), dît “numéro de sécurité sociale” dont voici un exemple : 1 85 05 78 006 084 36. Ce numéro est référencé dans le répertoire national d’identification des personnes physiques (RNIPP). Il concerne toutes les personnes nées sur le territoire français, ainsi que « en tant que de besoin […] les personnes nées à l’étranger » tel qu’explicité dans ce décret.
Le code COG correspond aux 6, 7, 8, 9 et 10èmes chiffres du numéro de sécurité sociale, soit dans ce même exemple : 78 006.

⚠️ Certains particuliers n’ont pas de numéro de sécurité sociale :

Cependant, pour la majorité des cas, le numéro de sécurité sociale figure sur :

Et pour les personnes nées à l’étranger, le code COG est trouvable dans cette liste de l’Insee.

Exemple d’interface recommandée

Le parcours 1 propose donc de s’appuyer sur le numéro de sécurité sociale pour permettre aux usagers de retrouver par eux-même leur code COG de naissance et de le renseigner.

💡 Caractéristiques :

  • Proposer un champ “Code COG de votre lieu de naissance” et montrer un exemple du format attendu.
  • Rendre accessible, à côté du champ de saisie, un tutoriel pour que l’usager retrouve son code COG.
  • Dans le cas d’un particulier né en France et pour appeler les API de CAF&MSA, veillez à bien paramètrer en plus le code COG de la France 99100, car le paramètre du code COG pays est obligatoire pour appeler les API. Vous n’avez pas besoin de demander à l’usager s’il est né en France et encore moins ce code COG pays, car vous pouvez le déduire à partir du code COG de la commune qu’il aura renseigné. Si celui-ci ne débute pas par 99, cela signifie qu’il a renseigné le code COG d’une commune française et donc vous pouvez renseigner automatiquement le paramètre code COG pays avec 99100.

[Maquette du champ COG à partir de la carte vitale]

[Maquette du tutoriel pour récupérer le code COG à partir de la carte Vitale]

Comment retrouver mon code COG ?

Le code COG de votre lieu de naissance est un identifiant géographique administratif. ⚠️ Ce code est différent du code postal.

  • Si vous êtes né en France, il s’agit du code COG de votre commune de naissance : les deux premiers chiffres correspondent à votre département de naissance. Les trois suivants codifient votre commune de naissance.
  • Si vous êtes né à l’étranger, il s’agit du code COG de votre pays de naissance : les deux premiers chiffres sont 99, les trois suivants codifient votre pays de naissance.

À partir de votre numéro de sécurité sociale, sur votre carte Vitale : Votre code COG de naissance correspond aux 6, 7, 8, 9 et 10ème chiffres de votre numéro de sécurité sociale. Exemple : Pour ce numéro de sécurité sociale fictif 1 85 05 78 006 084 36, le code COG est 78 006.

Vous n’avez pas de carte Vitale ? Si vous êtes assuré à la sécurité sociale française, votre numéro de sécurité sociale figure sur votre attestation de droit disponible sur ameli.fr https://assure.ameli.fr. Si vous êtes salarié, il figure également sur vos bulletins de salaires.
Si vous êtes né à l’étranger, vous pouvez trouver le code COG de votre pays de naissance dans cette liste de l’Insee : https://www.insee.fr/fr/information/2028273.

Pour reproduire le tutoriel : télécharger l’image de la carte Vitale et du code COG PNG – 16 ko


✅ Option 2 : Année et lieu de naissance saisis par l’usager, code COG déduit en arrière-plan

Dans cette seconde option, le renseignement du code COG pour appeler l’API est totalement transparent pour l’usager, qui n’aura qu’à compléter sa date et son lieu de naissance.

Exemple d’interface recommandée :

[Maquette saisie date et lieu de naissance]

[Maquette saisie date et lieu de naissance, autocompléteur ouvert]

💡 Caractéristiques :

  • Retrouver les codes COG en arrière-plan, à partir des informations saisies par l’usager : une fois que l’année et le lieu de naissance ont été complétés par l’usager et que celui-ci clique pour passer à l’étape suivante, les informations obtenues (nom de la commune & code département de naissance ou pays de naissance ; année de naissance) sont traitées en arrière-plan pour être converties en code COG. Pour les API CAF & MSA, dans le cas d’un particulier né en France, veillez à bien ajouter en paramètre d’appel de l’API le code COG de la France 99100, car le paramètre du code COG pays est obligatoire.
  • Rendre l’année de naissance obligatoire, car elle est indispensable pour retrouver le code COG. En revanche, le jour et le mois de naissance restent facultatifs.
  • Séparer les champs “lieu de naissance” des particuliers nés en France et ceux nés à l’étranger. En effet, un champ commun risque de mettre en difficulté les usagers nés à l’étranger qui vont peut-être saisir leur commune de naissance à l’étranger. L’auto-compléteur ne pourra pas gérer une telle complexité.
  • Proposer un auto-compléteur, pour permettre à l’usager de saisir son code postal ou sa commune en toutes lettres. Afficher systématiquement le code postal, le nom de la commune et le département pour s’assurer que l’usager sélectionnera la bonne commune de naissance.


Certaines difficultés à considérer :

Le Code COG et le nom d’une commune peut varier dans le temps pour cause de fusion, migration ou autre opération intervenant à l’échelle territoriale. Voici une liste d’exemples de cas singuliers où le code COG peut-être difficile à déduire.

Ces difficultés sont quasi inexistantes pour :

Des outils déjà disponibles pour vous aider à intégrer cette solution :