Assurances/API v2

Fiches par code ACAPS

GET/api/v2/insurance/intermediaries/{code}

À savoir. Snapshot de l’annuaire ACAPS : agents, courtiers et bureaux de gestion directe. Consultez la couverture et la date de collecte ; aucun agrément n’est vérifié en temps réel. Autorisation de redistribution non obtenue.

Comprendre la réponse

data: Les résultats demandés, sous forme d’objet ou de liste.

meta: Sources, licence et dates du jeu de données. null signifie une valeur inconnue ou indisponible.

meta.pagination: Listes : 100 résultats par défaut, 500 maximum. Utilisez limit et offset ; meta.pagination.next_offset vaut null à la dernière page.

Exemple illustratif: Avec limit=10 et offset=0, la première page contient au plus 10 résultats. Si next_offset vaut 10, demandez la suivante avec offset=10 et les mêmes filtres. Arrêtez quand next_offset vaut null.

API v2 est le chemin de référence. Les anciens chemins /api/v1 restent des alias de compatibilité du comportement actuellement publié, pagination comprise ; aucune date de suppression n’est fixée.

Champs renvoyés 6

[] désigne chaque élément d’une liste. null signifie inconnu ou indisponible, jamais zéro. La langue du guide ne traduit pas les valeurs des sources.

dataobject[]

Résultat demandé : objet unique ou liste.

data[].acaps_codestring

Code ACAPS source, avec zéros et suffixes conservés. Plusieurs fiches peuvent partager ce code.

data[].namestring | null

Raison sociale ou représentant professionnel ; peut identifier une personne. null si absent.

data[].categorystring

agent : agent ; broker : courtier ; direct-office : bureau de gestion directe.

Valeurs acceptées: "agent" "broker" "direct-office"

data[].insurerstring | null

Mandante indiquée par la source ; null si absente. Ne prouve pas l’exclusivité.

data[].citystring | null

Libellé de localité conservé depuis la source ; peut inclure un quartier ou une ville de rattachement.

Structure des données

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "acaps_code",
          "name",
          "category",
          "insurer",
          "city"
        ],
        "properties": {
          "acaps_code": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$",
            "description": "ACAPS code as published; retained as text, including leading zeros and branch suffixes."
          },
          "name": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "string",
                "nullable": true,
                "enum": [
                  null
                ]
              }
            ],
            "description": "Source business name or professional representative; may identify an individual. Null when blank in the source."
          },
          "category": {
            "type": "string",
            "enum": [
              "agent",
              "broker",
              "direct-office"
            ]
          },
          "insurer": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "string",
                "nullable": true,
                "enum": [
                  null
                ]
              }
            ],
            "description": "Source mandante, or null when absent. Does not establish exclusivity."
          },
          "city": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "string",
                "nullable": true,
                "enum": [
                  null
                ]
              }
            ],
            "description": "Unmodified source locality label; may include a district or parent city."
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "dataset",
        "total",
        "license",
        "terms_url",
        "redistribution_status",
        "retrieved_at",
        "source_updated_at",
        "transformation_version",
        "source_record_count",
        "coverage",
        "real_time",
        "limitations",
        "sources",
        "pagination"
      ],
      "properties": {
        "dataset": {
          "enum": [
            "acaps-insurance-intermediaries"
          ]
        },
        "total": {
          "type": "integer",
          "minimum": 0
        },
        "license": {
          "type": "string",
          "nullable": true,
          "enum": [
            null
          ]
        },
        "terms_url": {
          "type": "string",
          "format": "uri"
        },
        "redistribution_status": {
          "enum": [
            "permission-not-obtained"
          ]
        },
        "retrieved_at": {
          "type": "string",
          "format": "date"
        },
        "source_updated_at": {
          "type": "string",
          "nullable": true,
          "enum": [
            null
          ]
        },
        "transformation_version": {
          "type": "string",
          "minLength": 1
        },
        "source_record_count": {
          "type": "integer",
          "minimum": 1
        },
        "coverage": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "records",
            "complete"
          ],
          "properties": {
            "records": {
              "type": "integer",
              "minimum": 1
            },
            "complete": {
              "type": "boolean"
            }
          }
        },
        "real_time": {
          "enum": [
            false
          ]
        },
        "limitations": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "sources": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "dataset",
              "producer",
              "source_url"
            ],
            "properties": {
              "dataset": {
                "type": "string",
                "minLength": 1
              },
              "producer": {
                "type": "string",
                "minLength": 1
              },
              "source_url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        },
        "pagination": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "limit",
            "offset",
            "count",
            "has_more",
            "next_offset"
          ],
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            },
            "offset": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            "count": {
              "type": "integer",
              "minimum": 0,
              "maximum": 500
            },
            "has_more": {
              "type": "boolean"
            },
            "next_offset": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 2147483647
                },
                {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    null
                  ]
                }
              ]
            }
          }
        }
      }
    }
  }
}

Sources et pagination 25

metaobject

Contexte du résultat : sources, dates, licence et pagination si applicable.

meta.datasetstring

Nom du jeu de données auquel appartient le résultat ou la source.

Valeurs acceptées: "acaps-insurance-intermediaries"

meta.totalinteger

Nombre de résultats correspondant aux filtres, avant pagination ; pas la taille de cette page.

meta.licensenull

null : aucune licence ouverte identifiée pour cet annuaire ACAPS.

Valeurs acceptées: null

meta.terms_urlstring

Mentions légales du site ACAPS.

meta.redistribution_statusstring

permission-not-obtained : autorisation de redistribution non obtenue.

Valeurs acceptées: "permission-not-obtained"

meta.retrieved_atstring

Date de récupération du fichier source par le projet ; pas la date des observations.

meta.source_updated_atnull

Dernière mise à jour annoncée par la source ; pas la date de récupération.

Valeurs acceptées: null

meta.transformation_versionstring

Version des règles de conversion du jeu de données ; distincte de l’API.

meta.source_record_countinteger

Nombre de lignes dans la source, avant les éventuels filtres de l’API.

meta.coverageobject

Périmètre géographique et temporel effectivement disponible.

meta.coverage.recordsinteger

Nombre de fiches distinctes dans le snapshot, avant filtrage.

meta.coverage.completeboolean

Indique si la collecte couvre toutes les lignes annoncées par l’annuaire ; ne garantit pas l’exhaustivité du marché.

meta.real_timeboolean

false : les observations sont historiques, sans mise à jour en direct.

Valeurs acceptées: false

meta.limitationsstring[]

Limites connues de la source ou de la couverture ; à lire avant d’utiliser les données.

meta.sourcesobject[]

Sources utilisées pour ce résultat, avec leurs producteurs et licences.

meta.sources[].datasetstring

Nom du jeu de données auquel appartient le résultat ou la source.

meta.sources[].producerstring

Organisme qui publie la donnée originale.

meta.sources[].source_urlstring

Page de présentation ou de publication de la source.

meta.paginationobject

Informations pour parcourir une collection page par page.

meta.pagination.limitinteger

Nombre maximal demandé par page : 100 par défaut, 500 au maximum.

meta.pagination.offsetinteger

Nombre de résultats ignorés avant cette page, après filtrage. La première page commence à 0.

meta.pagination.countinteger

Nombre de résultats effectivement présents dans cette page.

meta.pagination.has_moreboolean

true s’il reste une autre page de résultats.

meta.pagination.next_offsetinteger | null

Valeur de offset pour la page suivante ; null à la fin. Gardez les mêmes filtres.

Erreurs

400: Paramètre invalide ou manquant.
404: Ressource introuvable.

Les erreurs renvoient error.code, error.message et error.request_id.

errorobject: Détails d’une requête échouée ; remplace data et meta.
error.codestring: Code stable de l’erreur, par exemple RESOURCE_NOT_FOUND ; à utiliser dans votre logique.
error.messagestring: Explication lisible de l’erreur ; utilisez code pour la logique de votre application.
error.request_idstring: Identifiant du traitement de cette requête, utile pour retrouver un problème.

Fiches par code ACAPS

Paramètres

Votre requête