NAV
shell

Introduction

Bienvenue sur API Particulier ! Cette API vous permet de simplifier les démarches administratives. Il est maintenant possible d'ajouter les informations à la source et donc de limiter les demandes de pièces justificatives

Nous fournissons des exemples de l'utilisation de l'API avec des commandes cURL. N'hésitez pas à contribuer pour ajouter des exemples dans les langages que vous utilisez.

Il existe aussi un fichier de spécification Swagger de l'API. Elle peut être consultée de manière interactive via l'onglet Technique de la fiche API Particulier sur api.gouv.fr.

Environnements

Il existe plusieurs environnements:

Domain API Key Stable
Production particulier.api.gouv.fr Secret Oui
Test particulier-sandbox.api.gouv.fr test-token Oui

Présentation

Acteurs

Il existe différents acteurs au sein d'API Particulier

API Particulier permet de faciliter la récupération d'information aurpès des fournisseurs de données. Ces informations appartiennent à des citoyens français qui utilisent un téléservice des fournisseurs de données. Une fois les informations récupérées, elles sont affichées aux agents assermentés des fournisseurs de service.

Autorisations

Fournisseurs de service

Pour vérifier votre jeton, vous pouvez utiliser ce code.

# Avec Curl, il suffit de passer le header HTTP: X-API-KEY
curl "https://particulier-sandbox.api.gouv.fr/api/impots/svair?numeroFiscal=12&referenceAvis=15" \
  -H "X-API-KEY: test-token"

Vous utilisez l'environement de test

API Particulier utilise un système de jeton pour identifier et authentifier les fournisseurs de service. Vous pouvez demander votre jeton d'authentification en envoyant un mail à contact@particulier.api.gouv.fr en précisant dans quel projet vous souhaitez intégrer l'API.

Il est nécessaire de s'identifier auprès de l'API avec le jeton lors de chaque requête HTTP en incluant le jeton dans les headers HTTP comme ceci:

X-API-KEY: myKey

Le citoyen ou l'agent

# Avec Curl, il suffit de passer le header HTTP: X-User
curl "https://particulier-sandbox.api.gouv.fr/api/impots/svair?numeroFiscal=12&referenceAvis=15" \
  -H "X-API-KEY: test-token" \
  -H "X-User: demo"

Il est aussi possible d'identifier (sans authentifier) les citoyens ou les agents ayant déclenchés un appel donné. En effet, en cas de problème ou de fraude, les fournisseurs de données doivent être en mesure de dire quels étaient les utilisateurs de l'API Particulier. C'est pourquoi il existe un header HTTP facultatif X-User qui permet d'identifier l'utilisateur : celui-ci peut être un identifiant interne du fournisseur de service.

France Connect

# Avec Curl, il suffit de passer le header HTTP: Authorization
curl "https://particulier-sandbox.api.gouv.fr/api/impots/svair?numeroFiscal=12&referenceAvis=15" \
  -H "Authorization: Bearer <ACCESS-TOKEN>"

Il est aussi possible de s'authentifier en tant que citoyen identifié via France Connect. Api Particulier étant un Fournisseur de Données, Il est possible pour un citoyen identifié auprès de France Connect d'accèder à ses données personnelles (et uniquement celles le concernant) en suivant le protocole OpenID Connect.

Impots

Récupérer les données fiscales d'un citoyen

curl "https://particulier-sandbox.api.gouv.fr/api/impots/svair?numeroFiscal=12&referenceAvis=15" \
  -H "X-API-KEY: test-token" \
  -H "accept: application/json" \
  -H "X-User: demo"

Cette commande retournera du json structuré comme ceci :

{
  "declarant1": {
    "nom": "Martin",
    "nomNaissance": "Martin",
    "prenoms": "Pierre",
    "dateNaissance": "22/03/1985"
  },
  "declarant2": {
    "nom": "Martin",
    "nomNaissance": "Honore",
    "prenoms": "Marie",
    "dateNaissance": "03/04/1986"
  },
  "foyerFiscal": {
    "annee": 2015,
    "adresse": "12 rue Balzac 75008 Paris"
  },
  "dateRecouvrement": "10/10/2015",
  "dateEtablissement": "08/07/2015",
  "nombreParts": 2,
  "situationFamille": "Marié(e)s",
  "nombrePersonnesCharge": 2,
  "revenuBrutGlobal": 29880,
  "revenuImposable": 29880,
  "impotRevenuNetAvantCorrections": 2165,
  "montantImpot": 2165,
  "revenuFiscalReference": 29880,
  "anneeImpots": "2015",
  "anneeRevenus": "2014"
}

Cette URL permet de récupérer les données présentes sur un avis d'imposition

HTTP Request

GET https://particulier.api.gouv.fr/api/impots/svair

Query Parameters

Paramètre Défault Obligatoire Description
numeroFiscal Non Oui Numéro fiscal propre à chaque citoyen (identifiant numérique de 13 chiffres)
referenceAvis Non Oui Référence de l'avis fiscal correspond à l'année de l'avis (identifiant alpha-numérique de 13 chiffres)

Récupérer l'adresse fiscale

curl "https://particulier-sandbox.api.gouv.fr/api/impots/adress?numeroFiscal=12&referenceAvis=15" \
  -H "X-API-KEY: test-token" \
  -H "Accept: application/xml" \
  -H "X-User: demo"

Cette commande retournera du xml structuré comme ceci :

<?xml version="1.0" encoding="UTF-8"?>
<result>
    <adresses>
        <adresse>
            <importance>0.3416</importance>
            <name>12 Rue Balzac</name>
            <postcode>75008</postcode>
            <housenumber>12</housenumber>
            <citycode>75108</citycode>
            <label>12 Rue Balzac 75008 Paris</label>
            <street>Rue Balzac</street>
            <context>75, Paris, Île-de-France</context>
            <type>housenumber</type>
            <city>Paris</city>
            <x>648716</x>
            <y>6863996.7</y>
            <score>0.9401454545454544</score>
        </adresse>
        <geometry>
            <type>Point</type>
            <coordinates>2.300816</coordinates>
            <coordinates>48.873951</coordinates>
        </geometry>
    </adresses>
    <declarant1>
        <nom>Martin</nom>
        <nomNaissance>Martin</nomNaissance>
        <prenoms>Pierre</prenoms>
        <dateNaissance>22/03/1985</dateNaissance>
    </declarant1>
    <declarant2>
        <nom>Martin</nom>
        <nomNaissance>Honore</nomNaissance>
        <prenoms>Marie</prenoms>
        <dateNaissance>03/04/1986</dateNaissance>
    </declarant2>
    <foyerFiscal>
        <annee>2015</annee>
        <adresse>12 rue Balzac 75008 Paris</adresse>
    </foyerFiscal>
</result>

Cette URL permet de géolocaliser l'adresse du foyer fiscale

HTTP Request

GET https://particulier.api.gouv.fr/api/impots/adress

Query Parameters

Paramètre Défault Obligatoire Description
numeroFiscal Non Oui Numéro fiscal propre à chaque citoyen (identifiant numérique de 13 chiffres)
referenceAvis Non Oui Référence de l'avis fiscal correspond à l'année de l'avis (identifiant alpha-numérique de 13 chiffres)

Caisse Allocations Familiales

Récupérer toutes les informations d'un allocataire CAF

curl "https://particulier-sandbox.api.gouv.fr/api/caf/famille?codePostal=99148&numeroAllocataire=0000354" \
  -H "X-API-KEY: test-token" \
  -H "accept: application/json" \
  -H "X-User: demo"

Cette commande retournera du json de ce type

{
  "allocataires": [
    {
      "nomPrenom": "MARIE DUPONT",
      "dateDeNaissance": "12111971",
      "sexe": "F"
    },
    {
      "nomPrenom": "JEAN DUPONT",
      "dateDeNaissance": "18101969",
      "sexe": "M"
    }
  ],
  "enfants": [
    {
      "nomPrenom": "LUCIE DUPONT",
      "dateDeNaissance": "11122016",
      "sexe": "F"
    }
  ],
  "adresse": {
    "identite": "Madame MARIE DUPONT",
    "complementIdentiteGeo": "ESCALIER B",
    "numeroRue": "123 RUE BIDON",
    "codePostalVille": "12345 CONDAT",
    "pays": "FRANCE"
  },
  "quotientFamilial": 1754,
  "mois": 4,
  "annee": 2017
}

Cette URL permet de récupérer plusieurs informations

HTTP Request

GET https://particulier.api.gouv.fr/api/caf/famille

Query Parameters

Paramètre Défault Obligatoire Description
codePostal Non Oui Code postal, identifiant numérique de 5 chiffres
numeroAllocataire Non Oui Numéro de l'allocataire CAF, Code postal, identifiant numérique de 7 chiffres

Errors

L'API Particulier utilise les codes retour suivants

Code Erreur Signification
400 Bad Request – Votre requête est mal formatée
401 Unauthorized – Votre jeton d'API n'est pas correct
403 Forbidden – Vous n'avez pas accès à cette API
404 Not Found – Les données demandées n'existe pas
405 Method Not Allowed – Vous n'avez pas utilisé la bonne méthode HTTP
406 Not Acceptable – Vous avez demandé un format qui n'est pas supporté
418 I’m a teapot
429 Too Many Requests – Le serveur ne tient pas la charge
500 Internal Server Error – Nous, ou un de nos fournisseurs, rencontrons un problème interne, merci de réessayer plus tard
503 Service Unavailable – Nous sommes en maintenance, merci de réessayer plus tard