La recherche de la population par critères d'identité

GET

/epargnants

curl --request GET \
  --url https://example.com/epargnants \
  --header 'Authorization: Bearer <token>'

L’énumération de la population, pour le back office — famille distincte de la consultation unitaire. Trois gardes au contrat : des CRITÈRES MINIMAUX obligatoires, un PLAFOND de résultats et le TRAÇAGE des appels.

Autorisations

• authentification
  epargnant:recherche

Paramètres

Paramètres (query)

nom

string

>= 1 characters

Le nom de famille (ou nom d’usage), critère de recherche.

prenoms

string

>= 1 characters

Les prénoms, critère de recherche.

date_naissance

string format: date

La date de naissance (AAAA-MM-JJ) — avec le code de commune de naissance, l’un des deux critères déterministes.

commune_naissance_code

string

>= 1 characters

Le code INSEE de la commune de naissance (code pays INSEE pour une naissance à l’étranger) — critère déterministe, avec la date de naissance.

nif

string

>= 1 characters

Le numéro fiscal déclaratif, critère de recherche.

Réponses

200

Les épargnants correspondant aux critères, en projection de liste. Une recherche sans correspondance sert une liste vide, jamais un 404.

Media typeapplication/json

La réponse de la recherche — la projection de liste et le drapeau de plafond.

object

resultats

required

Les épargnants correspondant aux critères, en projection de liste.

Array<object>

La projection de liste d’un épargnant — identifiant publié, état civil d’usage, statut de cycle. Jamais la fiche complète, jamais une qualification.

object

epargnant

required

L’identifiant publié.

string

>= 1 characters

nom_usage

Le nom d’usage — absent pour qui n’en déclare pas.

string

prenoms

required

string

>= 1 characters

statut_cycle

required

string

Allowed values: actif retraite decede

tronque

required

Vrai quand le plafond de résultats est atteint et que la liste est donc incomplète — l’appelant doit resserrer ses critères.

boolean

Example

{
  "resultats": [
    {
      "statut_cycle": "actif"
    }
  ]
}

400

La demande est irrecevable — notamment l’absence de critère minimal (aucune énumération sans discriminant) ; le motif nomme le champ en cause.

Media typeapplication/json

object

motif

required

Le motif, qui nomme le champ ou l’identifiant en cause.

string

Example^generated

{
  "motif": "example"
}

401

Aucune identité présentée.

403

L’identité présentée n’a pas la famille d’accès epargnant:recherche.

404

Le tenant du jeton n’est pas celui de l’installation — la muraille ne révèle jamais l’existence d’une population d’un autre teneur de compte (INV-EP-12).

Media typeapplication/json

object

motif

required

Le motif, qui nomme le champ ou l’identifiant en cause.

string

Example^generated

{
  "motif": "example"
}