Insurance/API v2

Search insurance intermediaries

GET/api/v2/insurance/intermediaries

Good to know. ACAPS directory snapshot: agents, brokers and direct management offices. Check coverage and retrieval date; current authorization is not verified. Redistribution permission has not been obtained.

Read the response

data: The requested results, as an object or an array.

meta: Dataset sources, license and dates. null means unknown or unavailable.

meta.pagination: Lists: 100 results by default, 500 maximum. Use limit and offset; meta.pagination.next_offset is null on the last page.

Illustrative example: With limit=10 and offset=0, the first page holds at most 10 results. If next_offset is 10, request the next page with offset=10 and the same filters. Stop when next_offset is null.

API v2 is the canonical path. Older /api/v1 paths remain compatibility aliases for the currently published behavior, including pagination; no removal date is scheduled.

Response fields 6

[] means each item in a list. null means unknown or unavailable, never zero. The guide language does not translate source values.

dataobject[]

Requested result: a single object or a list.

data[].acaps_codestring

Source ACAPS code, preserving zeros and branch suffixes. Multiple records may share a code.

data[].namestring | null

Business name or professional representative; may identify a person. Null when absent.

data[].categorystring

agent: agent; broker: broker; direct-office: direct management office.

Accepted values: "agent" "broker" "direct-office"

data[].insurerstring | null

Mandating insurer listed by the source; null when absent. Does not establish exclusivity.

data[].citystring | null

Locality label retained from the source; may include a district or parent city.

Data structure

{
  "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 and pagination 25

metaobject

Result context: sources, dates, license and pagination where applicable.

meta.datasetstring

Name of the dataset for this result or source.

Accepted values: "acaps-insurance-intermediaries"

meta.totalinteger

Number of matching records before pagination; not the size of this page.

meta.licensenull

null: no open license identified for this ACAPS directory.

Accepted values: null

meta.terms_urlstring

Legal terms of the ACAPS website.

meta.redistribution_statusstring

permission-not-obtained: redistribution permission has not been obtained.

Accepted values: "permission-not-obtained"

meta.retrieved_atstring

Date the project retrieved the source file; not the observation date.

meta.source_updated_atnull

Last update reported by the source; not the retrieval date.

Accepted values: null

meta.transformation_versionstring

Version of the dataset conversion rules; separate from the API version.

meta.source_record_countinteger

Number of source records before any API filters.

meta.coverageobject

Geographic and time coverage actually available.

meta.coverage.recordsinteger

Number of distinct records in the snapshot before filtering.

meta.coverage.completeboolean

Whether the capture covers all rows reported by the directory; does not guarantee complete market coverage.

meta.real_timeboolean

false means observations are historical, without live updates.

Accepted values: false

meta.limitationsstring[]

Known source or coverage limitations; read before using the data.

meta.sourcesobject[]

Sources used for this result, with their publishers and licenses.

meta.sources[].datasetstring

Name of the dataset for this result or source.

meta.sources[].producerstring

Organization publishing the original data.

meta.sources[].source_urlstring

Source publication or dataset landing page.

meta.paginationobject

Information for reading a collection one page at a time.

meta.pagination.limitinteger

Requested maximum records per page: default 100, maximum 500.

meta.pagination.offsetinteger

Matching records skipped before this page, after filtering. The first page starts at 0.

meta.pagination.countinteger

Number of records actually returned on this page.

meta.pagination.has_moreboolean

true when another page of records remains.

meta.pagination.next_offsetinteger | null

Use as offset for the next page; null at the end. Keep the same filters.

Errors

400: Invalid or missing parameter.

Errors return error.code, error.message and error.request_id.

errorobject: Details of a failed request; replaces data and meta.
error.codestring: Stable error code, such as RESOURCE_NOT_FOUND; use it in application logic.
error.messagestring: Human-readable error explanation; use code for application logic.
error.request_idstring: Identifier for this request, useful when reporting a problem.

Search insurance intermediaries

Parameters

Your request