# FFIEC Webservice Python Connector
## Purpose
The FFIEC Data Connect Python library allows researchers, analysts, and financial institutions to efficiently access and analyze regulatory banking data from the Federal Financial Institution Examination Council (FFIEC). This library eliminates the complexity of working directly with FFIEC's Webservice APIs by providing a unified, Pythonic interface that handles authentication, data normalization, and protocol differences automatically.
## Overview
The FFIEC Data Connect Python library (`ffiec_data_connect`) downloads data from the FFIEC (Federal Financial Institution Examination Council) via both SOAP and REST APIs.
>**`ffiec-data-connect` is not affiliated with the Federal Financial Institution Examination Council (FFIEC) or any other US Government Agency.**
> **Authentication Migration Notice (Effective August 25, 2025)**
>
> The FFIEC CDR is transitioning to Microsoft Entra ID authentication with optional multifactor authentication (MFA). All users must complete a registration process to migrate their accounts to the new authentication protocol.
>
> - Legacy SOAP API will remain available until **February 28, 2026**
> - All legacy security tokens will expire on **February 28, 2026**
> - Users must transition to the REST API before this date
## Key Features
- **Dual Protocol Support**: Supports both SOAP (legacy) and REST (new) APIs
- **Automatic Protocol Selection**: Automatically selects the appropriate protocol based on credential type
- **OAuth2 Authentication**: REST API support with 90-day bearer tokens
- **Higher Rate Limits**: REST API allows 2500 requests/hour vs 1000 for SOAP
- **Data Normalization**: Ensures consistency between SOAP and REST responses
- **Multiple Output Formats**: Returns data as Python lists, Pandas DataFrames, or Polars DataFrames
- **Field Name Compatibility**: Provides both `rssd` and `id_rssd` field names to support existing code
### Disclaimer
- __Please review the license and disclaimer before using this package.__
## Overview
The FFIEC Data Connect library provides a Python interface to both the SOAP-based and REST-based FFIEC APIs. As of version 2.0, the library supports:
- **SOAP API**: Traditional webservice interface (uses `WebserviceCredentials`)
- **REST API**: Modern RESTful interface with OAuth2 (uses `OAuth2Credentials`)
The library automatically selects the appropriate protocol based on the credentials you provide.
## Field Name Compatibility
**Important**: Property names were inconsistent in earlier versions of this library. To reduce the need to refactor existing user code, all functions that return RSSD data now provide **both field names** with identical data:
- `"rssd"`: Institution RSSD ID
- `"id_rssd"`: Institution RSSD ID (same data, different field name)
### Usage Examples
```python
# Both of these work identically:
rssd_id = filer.get("rssd")
rssd_id = filer.get("id_rssd")
# Defensive programming (recommended for production):
rssd_id = filer.get("rssd") or filer.get("id_rssd")
```
### Affected Functions
This dual field name support applies to:
- `collect_filers_on_reporting_period()`
- `collect_filers_submission_date_time()`
- All REST and SOAP implementations
- All output formats (list, pandas, polars)
## Installation
### Requirements
- Python 3.10 or higher
- pip package manager
> **Note**: This library requires modern Python versions. For best compatibility, use Python 3.11+ on macOS/Linux. Windows users may experience SSL certificate issues and should consider using Google Colab, WSL, or a Linux environment.
### Install from PyPI
```bash
pip install ffiec-data-connect
```
## Quickstart
### Setting up Credentials
1. **Create an account** at https://cdr.ffiec.gov/public/PWS/CreateAccount.aspx?PWS=true
- **No separate Microsoft account required!** The FFIEC registration process creates the necessary Microsoft Entra ID authentication for you
- You'll receive an invitation email from `invites@microsoft.com`
2. **Complete Microsoft Entra ID registration**
- Accept the invitation and complete the registration process
- If the callback link fails (common issue), manually navigate to: https://cdr.ffiec.gov/public/PWS/PublicLogin.aspx
3. **Generate credentials**:
- For **REST API** (Recommended): Generate a 90-day JWT bearer token from the Account Details tab
- For **SOAP API** (Deprecated): Use your username and Security Token
> **JWT Token Requirements**: Valid tokens must start with `ey` and end with `.` (e.g., `eyJhbGci...ifQ.`). Tokens expire after **90 days**, and must be manually regenerated via the FFIEC portal. This software does not automatically refresh tokens, and JWT refresh tokens are not supported by FFIEC.
### Using the REST API (Recommended)
```python
from ffiec_data_connect import OAuth2Credentials, collect_data, collect_reporting_periods
# Setup REST API credentials
from datetime import datetime, timedelta
creds = OAuth2Credentials(
username="your_username",
bearer_token="eyJhbGci...", # JWT token (NOT your password!)
token_expires=datetime.now() + timedelta(days=90)
)
# Check if token is expired
if creds.is_expired:
print("Token is expired - generate a new one!")
# Get reporting periods
periods = collect_reporting_periods(
session=None, # REST doesn't need session
creds=creds,
series="call",
output_type="list"
)
# Get individual bank data
data = collect_data(
session=None,
creds=creds,
reporting_period="12/31/2023", # Both APIs use MM/DD/YYYY format
rssd_id="480228", # JPMorgan Chase
series="call",
output_type="pandas", # Returns DataFrame
force_null_types="pandas" # Better integer display (optional)
)
```
### Using the SOAP API (Legacy)
```python
from ffiec_data_connect import WebserviceCredentials, FFIECConnection, collect_data
# Setup SOAP API credentials
creds = WebserviceCredentials(
username="your_username",
password="your_security_token" # Note: This is the Security Token, not your password
)
# Create connection
conn = FFIECConnection()
# Get data
data = collect_data(
session=conn,
creds=creds,
reporting_period="12/31/2023", # SOAP also uses MM/DD/YYYY format
rssd_id="480228",
series="call",
output_type="pandas"
)
```
## REST API Endpoints
The library supports all 7 FFIEC REST API endpoints (per CDR-PDD-SIS-611 v1.10):
1. **RetrieveReportingPeriods** - Get available reporting periods
2. **RetrievePanelOfReporters** - Get institutions that filed
3. **RetrieveFilersSinceDate** - Get filers since specific date
4. **RetrieveFilersSubmissionDateTime** - Get submission timestamps
5. **RetrieveFacsimile** - Get individual bank data (XBRL/PDF/SDF)
6. **RetrieveUBPRReportingPeriods** - Get UBPR reporting periods
7. **RetrieveUBPRXBRLFacsimile** - Get UBPR XBRL data
## Key Differences Between SOAP and REST
| Feature | SOAP API | REST API |
|---------|----------|----------|
| Authentication | Username + Security Token | OAuth2 Bearer Token (JWT) |
| Token Lifecycle | No expiration | 90 days |
| Token Format | Any string | Must start with `ey` and end with `.` |
| Rate Limit | 1000 requests/hour | 2500 requests/hour |
| Date Format | MM/DD/YYYY | MM/DD/YYYY |
| Protocol | SOAP/XML | REST/JSON |
| Headers | Standard SOAP | Non-standard (`UserID`, `Authentication`) |
| Library Used | zeep + requests | httpx |
| Status | ⚠️ **Deprecated Feb 28, 2026** | ✅ **Recommended** |
## Error Handling
The library provides specific exception types for better debugging:
```python
from ffiec_data_connect import (
CredentialError, # Authentication issues
ValidationError, # Invalid parameters
RateLimitError, # Rate limit exceeded
NoDataError, # No data found
ConnectionError, # Network issues
FFIECError # General FFIEC errors
)
try:
data = collect_data(...)
except CredentialError as e:
print(f"Authentication failed: {e}")
# Common causes: expired token, wrong password, invalid JWT format
except RateLimitError as e:
print(f"Rate limited. Retry after: {e.retry_after} seconds")
except NoDataError as e:
print(f"No data available: {e}")
except ValidationError as e:
print(f"Invalid parameters: {e}")
# Common causes: wrong RSSD ID, invalid date format, wrong series
```
### Legacy Error Mode
For backward compatibility, legacy error mode (raising `ValueError` for all errors) is enabled by default but deprecated. To use new exception types:
```python
import ffiec_data_connect
# Disable legacy mode for better error handling
ffiec_data_connect.disable_legacy_mode()
```
## Data Formats and Type Handling
The library preserves data integrity and provides flexible null handling:
### Data Preservation
- **ZIP codes**: Preserved as strings with leading zeros
- **RSSD IDs**: Normalized as strings across both APIs
- **Dates**: Consistent datetime format (MM/DD/YYYY input, configurable output)
### Null Value Handling
The library supports different null value strategies:
```python
# Default: numpy nulls (SOAP) or pandas nulls (REST)
data = collect_data(...)
# Force pandas nulls (better integer display)
data = collect_data(..., force_null_types="pandas")
# Force numpy nulls (legacy compatibility)
data = collect_data(..., force_null_types="numpy")
```
**Why this matters**:
- **numpy nulls** (`np.nan`) convert integers to floats (displays as `100.0`)
- **pandas nulls** (`pd.NA`) preserve integer types (displays as `100`)
- REST API defaults to pandas nulls for better data fidelity
- SOAP API defaults to numpy nulls for backward compatibility
## Rate Limiting
Both APIs have rate limits:
- **SOAP**: ~1000 requests/hour
- **REST**: ~2500 requests/hour
The library includes automatic rate limiting to help stay within these limits.
## Interactive Examples & Jupyter Notebooks
### 📓 Jupyter Notebook Demos
The library includes comprehensive Jupyter notebook tutorials with executable examples:
**🚀 REST API Demo** (`ffiec_data_connect_rest_demo.ipynb`)
- OAuth2 credential setup and token management
- Complete REST API walkthrough with real data
- Performance optimization techniques
- Error handling and troubleshooting
- Advanced features: rate limiting, batch operations
**🔧 SOAP API Demo** (`ffiec_data_connect_soap_demo.ipynb`)
- Legacy SOAP API implementation
- Credential management for WebserviceCredentials
- Session handling and connection management
- Data collection examples with real banking data
- Migration guidance to REST API
### 🎯 Quick Start Examples
**REST API (Recommended)**
```python
from ffiec_data_connect import OAuth2Credentials, collect_data
from datetime import datetime, timedelta
# Setup
creds = OAuth2Credentials(
username="your_username",
bearer_token="eyJhbGci...", # 90-day JWT token
token_expires=datetime.now() + timedelta(days=90)
)
# Get data
data = collect_data(
session=None, creds=creds,
reporting_period="12/31/2023", rssd_id="480228",
series="call", output_type="pandas"
)
```
**SOAP API (Legacy)**
```python
from ffiec_data_connect import WebserviceCredentials, FFIECConnection, collect_data
# Setup
creds = WebserviceCredentials(username="your_username", password="your_token")
conn = FFIECConnection()
# Get data
data = collect_data(
session=conn, creds=creds,
reporting_period="12/31/2023", rssd_id="480228",
series="call", output_type="pandas"
)
```
### 📚 Additional Examples
For more examples, see:
- **Jupyter Notebooks**: Included with the package for hands-on learning
- **Documentation Examples**: Complete code snippets in the [full documentation](https://ffiec-data-connect.readthedocs.io/)
## Common Issues and Troubleshooting
### Authentication Issues
**"Invalid bearer token" or Authentication Failed**
- ❌ Using website password instead of JWT token
- ❌ Token expired (check with `creds.is_expired`)
- ❌ Invalid token format (must start with `ey` and end with `.`)
**Solution**: Generate a new JWT token from your PWS portal
### Migration Issues
**Microsoft Callback Problems**
- After completing Microsoft verification, callback link may fail
- **Solution**: Manually navigate to https://cdr.ffiec.gov/public/PWS/PublicLogin.aspx
**Post-Migration Token Issues**
- Old tokens become invalid immediately after migration
- **Solution**: Generate new JWT token from migrated account
### Data Issues
**Integer Values Show as Decimals (100.0 instead of 100)**
```python
# Solution: Use pandas null handling
data = collect_data(..., force_null_types="pandas")
```
**Empty Datasets**
- Check if institution filed for that period: `collect_filers_on_reporting_period()`
- Verify RSSD ID exists and is active
- Ensure correct date format: MM/DD/YYYY for both APIs
### Technical Issues
**Windows SSL Certificate Issues**
- Use Google Colab, WSL, or Linux environment
- Ensure you're using Python 3.11+
**REST API Header Issues** (handled automatically by library)
- Uses non-standard headers: `UserID` (not `UserId`), `Authentication` (not `Authorization`)
For comprehensive troubleshooting, see the full documentation.
## Support
> **Important**: The FFIEC does NOT provide technical support for this library. FFIEC support is only available for CDR account matters.
**Library Support (Technical Issues)**
- **GitHub Issues**: https://github.com/call-report/ffiec-data-connect/issues
- **Direct Email**: michael@civicforge.solutions
**FFIEC Support (Account Issues Only)**
- **Email**: cdr.help@cdr.ffiec.gov
- **Scope**: CDR account setup, migration, token generation, Microsoft Entra ID issues
**Commercial Support**
Enhanced support available for commercial entities requiring priority technical support, custom modifications, or integration consulting.
This library is provided by Civic Forge Solutions LLC under the Mozilla Public License 2.0.
## Additional Resources
- **Full Documentation**: https://ffiec-data-connect.readthedocs.io/
- **Examples**: Jupyter notebooks included with package
- **Version History**: See CHANGELOG.md
- **REST API Reference**: Comprehensive OpenAPI specification in documentation
Raw data
{
"_id": null,
"home_page": null,
"name": "ffiec-data-connect",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ffiec, banking, financial, regulatory, call-report, ubpr, fdic, async, pandas, polars",
"author": null,
"author_email": "Civic Forge Solutions LLC <michael@civicforge.solutions>",
"download_url": "https://files.pythonhosted.org/packages/6d/b4/8bd616a156d194582ace22d7d48a1ca418c9a16ac98bfa75ca5c0a527de4/ffiec_data_connect-2.0.5.tar.gz",
"platform": null,
"description": "# FFIEC Webservice Python Connector\n\n## Purpose\n\nThe FFIEC Data Connect Python library allows researchers, analysts, and financial institutions to efficiently access and analyze regulatory banking data from the Federal Financial Institution Examination Council (FFIEC). This library eliminates the complexity of working directly with FFIEC's Webservice APIs by providing a unified, Pythonic interface that handles authentication, data normalization, and protocol differences automatically.\n\n## Overview\n\nThe FFIEC Data Connect Python library (`ffiec_data_connect`) downloads data from the FFIEC (Federal Financial Institution Examination Council) via both SOAP and REST APIs.\n\n>**`ffiec-data-connect` is not affiliated with the Federal Financial Institution Examination Council (FFIEC) or any other US Government Agency.**\n\n> **Authentication Migration Notice (Effective August 25, 2025)**\n> \n> The FFIEC CDR is transitioning to Microsoft Entra ID authentication with optional multifactor authentication (MFA). All users must complete a registration process to migrate their accounts to the new authentication protocol.\n> \n> - Legacy SOAP API will remain available until **February 28, 2026**\n> - All legacy security tokens will expire on **February 28, 2026**\n> - Users must transition to the REST API before this date\n\n## Key Features\n\n- **Dual Protocol Support**: Supports both SOAP (legacy) and REST (new) APIs\n- **Automatic Protocol Selection**: Automatically selects the appropriate protocol based on credential type\n- **OAuth2 Authentication**: REST API support with 90-day bearer tokens\n- **Higher Rate Limits**: REST API allows 2500 requests/hour vs 1000 for SOAP\n- **Data Normalization**: Ensures consistency between SOAP and REST responses\n- **Multiple Output Formats**: Returns data as Python lists, Pandas DataFrames, or Polars DataFrames\n- **Field Name Compatibility**: Provides both `rssd` and `id_rssd` field names to support existing code\n\n### Disclaimer\n\n- __Please review the license and disclaimer before using this package.__\n\n## Overview\n\nThe FFIEC Data Connect library provides a Python interface to both the SOAP-based and REST-based FFIEC APIs. As of version 2.0, the library supports:\n\n- **SOAP API**: Traditional webservice interface (uses `WebserviceCredentials`)\n- **REST API**: Modern RESTful interface with OAuth2 (uses `OAuth2Credentials`)\n\nThe library automatically selects the appropriate protocol based on the credentials you provide.\n\n## Field Name Compatibility\n\n**Important**: Property names were inconsistent in earlier versions of this library. To reduce the need to refactor existing user code, all functions that return RSSD data now provide **both field names** with identical data:\n\n- `\"rssd\"`: Institution RSSD ID \n- `\"id_rssd\"`: Institution RSSD ID (same data, different field name)\n\n### Usage Examples\n\n```python\n# Both of these work identically:\nrssd_id = filer.get(\"rssd\") \nrssd_id = filer.get(\"id_rssd\") \n\n# Defensive programming (recommended for production):\nrssd_id = filer.get(\"rssd\") or filer.get(\"id_rssd\")\n```\n\n### Affected Functions\n\nThis dual field name support applies to:\n- `collect_filers_on_reporting_period()`\n- `collect_filers_submission_date_time()` \n- All REST and SOAP implementations\n- All output formats (list, pandas, polars)\n\n## Installation\n\n### Requirements\n\n- Python 3.10 or higher\n- pip package manager\n\n> **Note**: This library requires modern Python versions. For best compatibility, use Python 3.11+ on macOS/Linux. Windows users may experience SSL certificate issues and should consider using Google Colab, WSL, or a Linux environment.\n\n### Install from PyPI\n\n```bash\npip install ffiec-data-connect\n```\n\n## Quickstart\n\n### Setting up Credentials\n\n1. **Create an account** at https://cdr.ffiec.gov/public/PWS/CreateAccount.aspx?PWS=true\n - **No separate Microsoft account required!** The FFIEC registration process creates the necessary Microsoft Entra ID authentication for you\n - You'll receive an invitation email from `invites@microsoft.com`\n \n2. **Complete Microsoft Entra ID registration**\n - Accept the invitation and complete the registration process\n - If the callback link fails (common issue), manually navigate to: https://cdr.ffiec.gov/public/PWS/PublicLogin.aspx\n\n3. **Generate credentials**:\n - For **REST API** (Recommended): Generate a 90-day JWT bearer token from the Account Details tab\n - For **SOAP API** (Deprecated): Use your username and Security Token\n\n> **JWT Token Requirements**: Valid tokens must start with `ey` and end with `.` (e.g., `eyJhbGci...ifQ.`). Tokens expire after **90 days**, and must be manually regenerated via the FFIEC portal. This software does not automatically refresh tokens, and JWT refresh tokens are not supported by FFIEC.\n\n### Using the REST API (Recommended)\n\n```python\nfrom ffiec_data_connect import OAuth2Credentials, collect_data, collect_reporting_periods\n\n# Setup REST API credentials\nfrom datetime import datetime, timedelta\n\ncreds = OAuth2Credentials(\n username=\"your_username\",\n bearer_token=\"eyJhbGci...\", # JWT token (NOT your password!)\n token_expires=datetime.now() + timedelta(days=90)\n)\n\n# Check if token is expired\nif creds.is_expired:\n print(\"Token is expired - generate a new one!\")\n\n# Get reporting periods\nperiods = collect_reporting_periods(\n session=None, # REST doesn't need session\n creds=creds,\n series=\"call\",\n output_type=\"list\"\n)\n\n# Get individual bank data\ndata = collect_data(\n session=None,\n creds=creds,\n reporting_period=\"12/31/2023\", # Both APIs use MM/DD/YYYY format\n rssd_id=\"480228\", # JPMorgan Chase\n series=\"call\",\n output_type=\"pandas\", # Returns DataFrame\n force_null_types=\"pandas\" # Better integer display (optional)\n)\n```\n\n### Using the SOAP API (Legacy)\n\n```python\nfrom ffiec_data_connect import WebserviceCredentials, FFIECConnection, collect_data\n\n# Setup SOAP API credentials\ncreds = WebserviceCredentials(\n username=\"your_username\",\n password=\"your_security_token\" # Note: This is the Security Token, not your password\n)\n\n# Create connection\nconn = FFIECConnection()\n\n# Get data\ndata = collect_data(\n session=conn,\n creds=creds,\n reporting_period=\"12/31/2023\", # SOAP also uses MM/DD/YYYY format\n rssd_id=\"480228\",\n series=\"call\",\n output_type=\"pandas\"\n)\n```\n\n## REST API Endpoints\n\nThe library supports all 7 FFIEC REST API endpoints (per CDR-PDD-SIS-611 v1.10):\n\n1. **RetrieveReportingPeriods** - Get available reporting periods\n2. **RetrievePanelOfReporters** - Get institutions that filed\n3. **RetrieveFilersSinceDate** - Get filers since specific date\n4. **RetrieveFilersSubmissionDateTime** - Get submission timestamps\n5. **RetrieveFacsimile** - Get individual bank data (XBRL/PDF/SDF)\n6. **RetrieveUBPRReportingPeriods** - Get UBPR reporting periods\n7. **RetrieveUBPRXBRLFacsimile** - Get UBPR XBRL data\n\n## Key Differences Between SOAP and REST\n\n| Feature | SOAP API | REST API |\n|---------|----------|----------|\n| Authentication | Username + Security Token | OAuth2 Bearer Token (JWT) |\n| Token Lifecycle | No expiration | 90 days |\n| Token Format | Any string | Must start with `ey` and end with `.` |\n| Rate Limit | 1000 requests/hour | 2500 requests/hour |\n| Date Format | MM/DD/YYYY | MM/DD/YYYY |\n| Protocol | SOAP/XML | REST/JSON |\n| Headers | Standard SOAP | Non-standard (`UserID`, `Authentication`) |\n| Library Used | zeep + requests | httpx |\n| Status | \u26a0\ufe0f **Deprecated Feb 28, 2026** | \u2705 **Recommended** |\n\n## Error Handling\n\nThe library provides specific exception types for better debugging:\n\n```python\nfrom ffiec_data_connect import (\n CredentialError, # Authentication issues\n ValidationError, # Invalid parameters\n RateLimitError, # Rate limit exceeded\n NoDataError, # No data found\n ConnectionError, # Network issues\n FFIECError # General FFIEC errors\n)\n\ntry:\n data = collect_data(...)\nexcept CredentialError as e:\n print(f\"Authentication failed: {e}\")\n # Common causes: expired token, wrong password, invalid JWT format\nexcept RateLimitError as e:\n print(f\"Rate limited. Retry after: {e.retry_after} seconds\")\nexcept NoDataError as e:\n print(f\"No data available: {e}\")\nexcept ValidationError as e:\n print(f\"Invalid parameters: {e}\")\n # Common causes: wrong RSSD ID, invalid date format, wrong series\n```\n\n### Legacy Error Mode\n\nFor backward compatibility, legacy error mode (raising `ValueError` for all errors) is enabled by default but deprecated. To use new exception types:\n\n```python\nimport ffiec_data_connect\n\n# Disable legacy mode for better error handling\nffiec_data_connect.disable_legacy_mode()\n```\n\n## Data Formats and Type Handling\n\nThe library preserves data integrity and provides flexible null handling:\n\n### Data Preservation\n- **ZIP codes**: Preserved as strings with leading zeros\n- **RSSD IDs**: Normalized as strings across both APIs\n- **Dates**: Consistent datetime format (MM/DD/YYYY input, configurable output)\n\n### Null Value Handling\nThe library supports different null value strategies:\n\n```python\n# Default: numpy nulls (SOAP) or pandas nulls (REST)\ndata = collect_data(...)\n\n# Force pandas nulls (better integer display)\ndata = collect_data(..., force_null_types=\"pandas\")\n\n# Force numpy nulls (legacy compatibility)\ndata = collect_data(..., force_null_types=\"numpy\")\n```\n\n**Why this matters**: \n- **numpy nulls** (`np.nan`) convert integers to floats (displays as `100.0`)\n- **pandas nulls** (`pd.NA`) preserve integer types (displays as `100`)\n- REST API defaults to pandas nulls for better data fidelity\n- SOAP API defaults to numpy nulls for backward compatibility\n\n## Rate Limiting\n\nBoth APIs have rate limits:\n- **SOAP**: ~1000 requests/hour\n- **REST**: ~2500 requests/hour\n\nThe library includes automatic rate limiting to help stay within these limits.\n\n## Interactive Examples & Jupyter Notebooks\n\n### \ud83d\udcd3 Jupyter Notebook Demos\n\nThe library includes comprehensive Jupyter notebook tutorials with executable examples:\n\n**\ud83d\ude80 REST API Demo** (`ffiec_data_connect_rest_demo.ipynb`)\n- OAuth2 credential setup and token management\n- Complete REST API walkthrough with real data\n- Performance optimization techniques\n- Error handling and troubleshooting\n- Advanced features: rate limiting, batch operations\n\n**\ud83d\udd27 SOAP API Demo** (`ffiec_data_connect_soap_demo.ipynb`) \n- Legacy SOAP API implementation\n- Credential management for WebserviceCredentials\n- Session handling and connection management\n- Data collection examples with real banking data\n- Migration guidance to REST API\n\n### \ud83c\udfaf Quick Start Examples\n\n**REST API (Recommended)**\n```python\nfrom ffiec_data_connect import OAuth2Credentials, collect_data\nfrom datetime import datetime, timedelta\n\n# Setup\ncreds = OAuth2Credentials(\n username=\"your_username\",\n bearer_token=\"eyJhbGci...\", # 90-day JWT token\n token_expires=datetime.now() + timedelta(days=90)\n)\n\n# Get data\ndata = collect_data(\n session=None, creds=creds, \n reporting_period=\"12/31/2023\", rssd_id=\"480228\",\n series=\"call\", output_type=\"pandas\"\n)\n```\n\n**SOAP API (Legacy)**\n```python\nfrom ffiec_data_connect import WebserviceCredentials, FFIECConnection, collect_data\n\n# Setup \ncreds = WebserviceCredentials(username=\"your_username\", password=\"your_token\")\nconn = FFIECConnection()\n\n# Get data\ndata = collect_data(\n session=conn, creds=creds,\n reporting_period=\"12/31/2023\", rssd_id=\"480228\", \n series=\"call\", output_type=\"pandas\"\n)\n```\n\n### \ud83d\udcda Additional Examples\n\nFor more examples, see:\n- **Jupyter Notebooks**: Included with the package for hands-on learning\n- **Documentation Examples**: Complete code snippets in the [full documentation](https://ffiec-data-connect.readthedocs.io/)\n\n## Common Issues and Troubleshooting\n\n### Authentication Issues\n\n**\"Invalid bearer token\" or Authentication Failed**\n- \u274c Using website password instead of JWT token\n- \u274c Token expired (check with `creds.is_expired`) \n- \u274c Invalid token format (must start with `ey` and end with `.`)\n\n**Solution**: Generate a new JWT token from your PWS portal\n\n### Migration Issues\n\n**Microsoft Callback Problems**\n- After completing Microsoft verification, callback link may fail\n- **Solution**: Manually navigate to https://cdr.ffiec.gov/public/PWS/PublicLogin.aspx\n\n**Post-Migration Token Issues**\n- Old tokens become invalid immediately after migration\n- **Solution**: Generate new JWT token from migrated account\n\n### Data Issues\n\n**Integer Values Show as Decimals (100.0 instead of 100)**\n```python\n# Solution: Use pandas null handling\ndata = collect_data(..., force_null_types=\"pandas\")\n```\n\n**Empty Datasets**\n- Check if institution filed for that period: `collect_filers_on_reporting_period()`\n- Verify RSSD ID exists and is active\n- Ensure correct date format: MM/DD/YYYY for both APIs\n\n### Technical Issues\n\n**Windows SSL Certificate Issues**\n- Use Google Colab, WSL, or Linux environment\n- Ensure you're using Python 3.11+\n\n**REST API Header Issues** (handled automatically by library)\n- Uses non-standard headers: `UserID` (not `UserId`), `Authentication` (not `Authorization`)\n\nFor comprehensive troubleshooting, see the full documentation.\n\n## Support\n\n> **Important**: The FFIEC does NOT provide technical support for this library. FFIEC support is only available for CDR account matters.\n\n**Library Support (Technical Issues)**\n- **GitHub Issues**: https://github.com/call-report/ffiec-data-connect/issues\n- **Direct Email**: michael@civicforge.solutions \n\n**FFIEC Support (Account Issues Only)**\n- **Email**: cdr.help@cdr.ffiec.gov\n- **Scope**: CDR account setup, migration, token generation, Microsoft Entra ID issues\n\n**Commercial Support**\nEnhanced support available for commercial entities requiring priority technical support, custom modifications, or integration consulting.\n\nThis library is provided by Civic Forge Solutions LLC under the Mozilla Public License 2.0.\n\n## Additional Resources\n\n- **Full Documentation**: https://ffiec-data-connect.readthedocs.io/\n- **Examples**: Jupyter notebooks included with package\n- **Version History**: See CHANGELOG.md\n- **REST API Reference**: Comprehensive OpenAPI specification in documentation\n",
"bugtrack_url": null,
"license": null,
"summary": "Secure, thread-safe Python wrapper for FFIEC webservice API with async support",
"version": "2.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/call-report/ffiec-data-connect/issues",
"Changelog": "https://github.com/call-report/ffiec-data-connect/blob/main/CHANGELOG.md",
"Documentation": "https://ffiec-data-connect.readthedocs.io/",
"Homepage": "https://github.com/call-report/ffiec-data-connect",
"Repository": "https://github.com/call-report/ffiec-data-connect"
},
"split_keywords": [
"ffiec",
" banking",
" financial",
" regulatory",
" call-report",
" ubpr",
" fdic",
" async",
" pandas",
" polars"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb50127676ad84dbc5678f3e49311809aae2600d382eb0d851a2e49805064ee0",
"md5": "48a74df0b7b5d026eb5175ef6b70442b",
"sha256": "4c07adeeaede801a63025a4feeb8d5a1c32a122d5e749c4f2c5bf64034cfeacc"
},
"downloads": -1,
"filename": "ffiec_data_connect-2.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "48a74df0b7b5d026eb5175ef6b70442b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 65597,
"upload_time": "2025-09-07T15:21:37",
"upload_time_iso_8601": "2025-09-07T15:21:37.464751Z",
"url": "https://files.pythonhosted.org/packages/eb/50/127676ad84dbc5678f3e49311809aae2600d382eb0d851a2e49805064ee0/ffiec_data_connect-2.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6db48bd616a156d194582ace22d7d48a1ca418c9a16ac98bfa75ca5c0a527de4",
"md5": "57f1fd9b3f21a7ddbc8ff827de010247",
"sha256": "9c9ed4a023b49bdf4070f9021262523e2838adcf9e08f0f0a4c69f0775dee16f"
},
"downloads": -1,
"filename": "ffiec_data_connect-2.0.5.tar.gz",
"has_sig": false,
"md5_digest": "57f1fd9b3f21a7ddbc8ff827de010247",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 401456,
"upload_time": "2025-09-07T15:21:38",
"upload_time_iso_8601": "2025-09-07T15:21:38.751983Z",
"url": "https://files.pythonhosted.org/packages/6d/b4/8bd616a156d194582ace22d7d48a1ca418c9a16ac98bfa75ca5c0a527de4/ffiec_data_connect-2.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 15:21:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "call-report",
"github_project": "ffiec-data-connect",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ffiec-data-connect"
}
JSON
