fca_api.async_api#

High-level Financial Services Register API client.

This module provides the main user-facing interface for interacting with the FCA Financial Services Register API. It wraps the low-level raw client to provide:

  • Automatic data validation using Pydantic models

  • Explicit cursor-based pagination — each call returns a page of results and an opaque next_page token you pass back to retrieve the next batch

  • Type safety with comprehensive type hints

  • Error handling with meaningful exceptions

  • Optional token encryption via a pluggable PageTokenSerializer

The Client class is the primary entry point for most users, offering methods for searching firms, individuals, and funds, as well as retrieving detailed information about specific entities.

Pagination model:

# Fetch the first page (one underlying API call by default)
page = await client.search_frn("Barclays")

# Iterate through all pages explicitly
while True:
    for firm in page.data:
        print(f"{firm.name} (FRN: {firm.frn})")
    if not page.pagination.has_next:
        break
    page = await client.search_frn(
        "Barclays",
        next_page=page.pagination.next_page,
    )

Example

Basic client usage:

import fca_api.async_api

async with fca_api.async_api.Client(
    credentials=("email@example.com", "api_key")
) as client:
    # Search for firms by name
    page = await client.search_frn("revolution")

    for firm in page.data:
        print(f"{firm.name} (FRN: {firm.frn})")
class fca_api.async_api.Client(credentials: Tuple[str, str] | AsyncClient, api_limiter: Callable[[], AsyncContextManager[None, bool | None]] | None = None, page_token_serializer: PageTokenSerializer | None = None)[source]#

High-level Financial Services Register API client.

This client wraps the low-level raw client to provide data validation, type safety, and cursor-based pagination for the FCA Financial Services Register API.

Pagination works as follows:

  • Every paginated endpoint accepts an optional next_page token and a result_count minimum. Omit both for a single API page of results.

  • The returned MultipageList.pagination structure contains has_next and next_page. Pass next_page back to the same method to advance.

  • Pass result_count=N to have the client transparently issue multiple underlying API calls until at least N items are collected.

Optional token encryption:

client = Client(
    credentials=("email", "key"),
    page_token_serializer=my_serializer,  # implements PageTokenSerializer
)

When configured, next_page values returned to callers are passed through serializer.serialize(), and values received from callers are passed through serializer.deserialize() before internal decoding.

Example

Using as an async context manager:

async with Client(
    credentials=("email@example.com", "api_key")
) as client:
    page = await client.search_frn("barclays")
    for firm in page.data:
        print(firm.name)

Manual session management:

client = Client(credentials=("email@example.com", "api_key"))
try:
    page = await client.search_frn("barclays")
    # Process page.data...
finally:
    await client.aclose()
__init__(credentials: Tuple[str, str] | AsyncClient, api_limiter: Callable[[], AsyncContextManager[None, bool | None]] | None = None, page_token_serializer: PageTokenSerializer | None = None) → None[source]#

Initialize the high-level FCA API client.

Parameters:

  • credentials – Authentication credentials. Either: - Tuple of (email, api_key) for automatic session creation - Pre-configured httpx.AsyncClient with auth headers set

  • api_limiter – Optional async context manager for rate limiting. Should be a callable returning an async context manager.

  • page_token_serializer – Optional serializer for encrypting and decrypting pagination tokens. When provided, next_page tokens returned to callers are encrypted via serializer.serialize(), and tokens received from callers are decrypted via serializer.deserialize() before use.

Example

With email/key tuple:

client = Client(
    credentials=("your.email@example.com", "your_api_key")
)

With pre-configured session:

session = httpx.AsyncClient(headers={
    "X-AUTH-EMAIL": "your.email@example.com",
    "X-AUTH-KEY": "your_api_key"
})
client = Client(credentials=session)

With rate limiting and token encryption:

from asyncio_throttle import Throttler
throttler = Throttler(rate_limit=10)

client = Client(
    credentials=("email", "key"),
    api_limiter=throttler,
    page_token_serializer=MyHmacSerializer(),
)
async aclose() → None[source]#

Close the underlying HTTP session.

property raw_client: RawClient#

The underlying raw API client.

property api_version: str#

The API version string.

async search_frn(firm_name: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmSearchResult][source]#

Search for firms by name.

Parameters:

  • firm_name – Firm name to search for (partial matches, case-insensitive).

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return. The client will issue multiple underlying API calls if needed. Defaults to 1 (one API page).

Returns:

A page of firm search results with pagination metadata.

Example:

page = await client.search_frn("Barclays", result_count=50)
print(f"Got {len(page.data)} of ~{page.pagination.size} total")

if page.pagination.has_next:
    next_page = await client.search_frn(
        "Barclays",
        next_page=page.pagination.next_page,
        result_count=50,
    )
async search_irn(individual_name: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[IndividualSearchResult][source]#

Search for individuals by name.

Parameters:

  • individual_name – Individual name to search for.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of individual search results with pagination metadata.

async search_prn(fund_name: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FundSearchResult][source]#

Search for funds by name.

Parameters:

  • fund_name – Fund name to search for.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of fund search results with pagination metadata.

async get_firm(frn: str) → FirmDetails[source]#

Get comprehensive firm details by FRN.

Parameters:

frn – The Firm Reference Number (FRN).

Returns:

Complete firm details.

async get_firm_names(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmNameAlias][source]#

Get firm names (current and previous) by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm name aliases with pagination metadata.

async get_firm_addresses(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmAddress][source]#

Get firm addresses by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm addresses with pagination metadata.

async get_firm_controlled_functions(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmControlledFunction][source]#

Get firm controlled functions by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm controlled functions with pagination metadata.

async get_firm_individuals(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmIndividual][source]#

Get individuals associated with a firm by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm individuals with pagination metadata.

async get_firm_permissions(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmPermission][source]#

Get firm permissions by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm permissions with pagination metadata.

async get_firm_requirements(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmRequirement][source]#

Get firm requirements by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm requirements with pagination metadata.

async get_firm_requirement_investment_types(frn: str, req_ref: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmRequirementInvestmentType][source]#

Get investment types for a specific firm requirement.

Parameters:

  • frn – The Firm Reference Number (FRN) of the firm.

  • req_ref – The requirement reference identifier.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of investment types with pagination metadata.

async get_firm_regulators(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmRegulator][source]#

Get firm regulators by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm regulators with pagination metadata.

async get_firm_passports(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmPassport][source]#

Get firm passports by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm passports with pagination metadata.

async get_firm_passport_permissions(frn: str, country: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmPassportPermission][source]#

Get firm passport permissions by FRN and country.

Parameters:

  • frn – The firm’s FRN.

  • country – The country code.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm passport permissions with pagination metadata.

async get_firm_waivers(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmWaiver][source]#

Get firm waivers by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm waivers with pagination metadata.

async get_firm_exclusions(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmExclusion][source]#

Get firm exclusions by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm exclusions with pagination metadata.

async get_firm_disciplinary_history(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmDisciplinaryRecord][source]#

Get disciplinary history records for a firm.

Parameters:

  • frn – The Firm Reference Number (FRN) of the firm.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of disciplinary records with pagination metadata.

async get_firm_appointed_representatives(frn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[FirmAppointedRepresentative][source]#

Get firm appointed representatives by FRN.

Parameters:

  • frn – The firm’s FRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of firm appointed representatives with pagination metadata.

async get_individual(irn: str) → Individual[source]#

Get individual details by IRN.

Parameters:

irn – The individual’s IRN.

Returns:

The individual’s details.

async get_individual_controlled_functions(irn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[IndividualControlledFunction][source]#

Get controlled functions for an individual.

Parameters:

  • irn – The Individual Reference Number (IRN).

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of controlled functions with pagination metadata.

async get_individual_disciplinary_history(irn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[IndividualDisciplinaryRecord][source]#

Get disciplinary history records for an individual.

Parameters:

  • irn – The Individual Reference Number (IRN).

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of disciplinary records with pagination metadata.

__weakref__#

list of weak references to the object

async get_fund(prn: str) → ProductDetails[source]#

Get fund details by PRN.

Parameters:

prn – The fund’s PRN.

Returns:

The fund’s details.

async get_fund_names(prn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[ProductNameAlias][source]#

Get fund names by PRN.

Parameters:

  • prn – The fund’s PRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of fund name aliases with pagination metadata.

async get_fund_subfunds(prn: str, next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[SubFundDetails][source]#

Get fund sub-funds by PRN.

Parameters:

  • prn – The fund’s PRN.

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of sub-fund details with pagination metadata.

async get_regulated_markets(next_page: Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Opaque pagination cursor. Pass this value unchanged to the same endpoint to retrieve the next page of results. Treat it as an opaque string — do not construct, parse, or modify it.')] | None = None, result_count: int = 1) → MultipageList[RegulatedMarket][source]#

Get regulated markets.

Parameters:

  • next_page – Cursor from a previous call to continue pagination.

  • result_count – Minimum number of results to return.

Returns:

A page of regulated markets with pagination metadata.