# Follow Up Boss API Client
A comprehensive Python client library for the Follow Up Boss API, providing easy access to all Follow Up Boss endpoints with full type safety and thorough documentation.
## Features
- **Complete API Coverage**: Support for all Follow Up Boss API endpoints
- **Type Safety**: Full type hints throughout the library
- **Easy to Use**: Simple, intuitive interface
- **Well Documented**: Comprehensive docstrings and examples
- **Async Support**: Built with modern Python async/await patterns
- **Error Handling**: Robust error handling and validation
- **Extensible**: Easy to extend for custom use cases
## Installation
```bash
pip install follow-up-boss
```
## Quick Start
```python
from follow_up_boss import FollowUpBossApiClient
# Initialize the client
client = FollowUpBossApiClient(
api_key="your_api_key",
x_system="Your-System-Name",
x_system_key="your_system_key"
)
# Get all people
people = client.people.get_all()
# Create a new person
new_person = client.people.create({
"name": "John Doe",
"email": "john@example.com",
"phone": "555-123-4567"
})
# Update a person
updated_person = client.people.update(person_id, {
"name": "John Smith"
})
# Delete a person
client.people.delete(person_id)
```
## Environment Variables
You can also configure the client using environment variables:
```bash
FOLLOW_UP_BOSS_API_KEY=your_api_key
X_SYSTEM=Your-System-Name
X_SYSTEM_KEY=your_system_key
```
```python
from follow_up_boss import FollowUpBossApiClient
# Client will automatically use environment variables
client = FollowUpBossApiClient()
```
## API Resources
The client provides access to all Follow Up Boss API resources:
### Core Resources
- **People**: Manage contacts and leads
- **Deals**: Track real estate transactions ([Commission Field Guide](DEALS_COMMISSION_GUIDE.md))
- **Events**: Handle activities and interactions
- **Tasks**: Manage todo items and follow-ups
- **Notes**: Add and retrieve notes
- **Appointments**: Schedule and manage appointments
### Communication
- **Text Messages**: Send and receive SMS
- **Email Templates**: Manage email templates
- **Text Message Templates**: Manage SMS templates
- **Webhooks**: Configure webhook endpoints
- **Reactions**: Handle message reactions
### Organization
- **Teams**: Manage team structures
- **Users**: Handle user accounts
- **Groups**: Organize contacts into groups
- **Pipelines**: Manage sales pipelines
- **Stages**: Configure pipeline stages
- **Smart Lists**: Dynamic contact lists
### Configuration
- **Custom Fields**: Define custom data fields
- **Action Plans**: Automated workflow templates
- **Appointment Types**: Configure appointment categories
- **Appointment Outcomes**: Track appointment results
### Attachments & Files
- **Person Attachments**: File attachments for contacts
- **Deal Attachments**: File attachments for deals
## Deals API - Commission Fields
The Deals API includes special handling for commission fields. **Important**: Commission fields must be passed as top-level parameters, not in `custom_fields`.
```python
from follow_up_boss import Deals, DealsValidationError
deals_api = Deals(client)
# ✅ Correct - Commission fields as top-level parameters
deal = deals_api.create_deal(
name="123 Main Street",
stage_id=26,
price=450000,
commissionValue=13500.0,
agentCommission=9450.0,
teamCommission=4050.0
)
# ❌ Incorrect - This will raise DealsValidationError
try:
deal = deals_api.create_deal(
name="Deal Name",
stage_id=26,
custom_fields={'commissionValue': 13500} # This fails
)
except DealsValidationError as e:
print(f"Validation error: {e}")
```
### Commission Helper Methods
```python
# Set commission using helper method
commission_data = {
'total': 15000.0,
'agent': 10500.0,
'team': 4500.0
}
updated_deal = deals_api.set_deal_commission(deal_id, commission_data)
```
For complete commission field documentation, see the [Commission Field Guide](DEALS_COMMISSION_GUIDE.md).
## Advanced Usage
### Error Handling
```python
from follow_up_boss import FollowUpBossApiClient
from follow_up_boss.exceptions import ApiError, AuthenticationError
try:
client = FollowUpBossApiClient(api_key="invalid_key")
people = client.people.get_all()
except AuthenticationError:
print("Invalid API credentials")
except ApiError as e:
print(f"API Error: {e}")
```
### Pagination
```python
# Get all people with pagination
all_people = []
page = 1
while True:
response = client.people.get_all(page=page, limit=100)
people = response.get('people', [])
if not people:
break
all_people.extend(people)
page += 1
```
### Custom Headers
```python
# Add custom headers to requests
client = FollowUpBossApiClient(
api_key="your_key",
custom_headers={
"X-Custom-Header": "custom_value"
}
)
```
## Development
### Setup
```bash
git clone https://github.com/theperrygroup/follow-up-boss.git
cd follow-up-boss
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black follow_up_boss tests
isort follow_up_boss tests
```
### Type Checking
```bash
mypy follow_up_boss
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass (`pytest`)
6. Format your code (`black` and `isort`)
7. Commit your changes (`git commit -m 'Add amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For questions, issues, or feature requests, please:
1. Check the [documentation](https://github.com/theperrygroup/follow-up-boss#readme)
2. Search [existing issues](https://github.com/theperrygroup/follow-up-boss/issues)
3. Create a [new issue](https://github.com/theperrygroup/follow-up-boss/issues/new) if needed
## Changelog
### Version 0.2.0
- **Major Commission Field Improvements**: Added comprehensive commission field handling with validation
- **Enhanced Error Messages**: Context-specific error guidance for common mistakes
- **New Validation System**: `DealsValidationError` for deals-specific validation
- **Commission Helper Methods**: `set_deal_commission()` for easier commission management
- **Field Name Normalization**: Consistent field naming between requests and responses
- **Comprehensive Documentation**: New commission field guide with examples and troubleshooting
- **Enhanced Testing**: Complete test coverage for all commission field scenarios
- **Improved Developer Experience**: Better error messages, helper properties, and validation
### Version 0.1.2
- Removed appointment test log file logging
### Version 0.1.1
- Updated website URL to https://theperry.group
### Version 0.1.0
- Initial release
- Complete API coverage for all Follow Up Boss endpoints
- Full type safety with comprehensive type hints
- Comprehensive test suite
- Documentation and examples
## Related Projects
- [Follow Up Boss API Documentation](https://followupboss.com/api/)
- [Follow Up Boss](https://followupboss.com/) - The official Follow Up Boss platform
---
Made with ❤️ by [The Perry Group](https://theperry.group)
Raw data
{
"_id": null,
"home_page": null,
"name": "follow-up-boss",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "followupboss, api, client, real-estate, crm",
"author": null,
"author_email": "The Perry Group <contact@theperry.group>",
"download_url": "https://files.pythonhosted.org/packages/41/04/2833df67048317bb21a316f7581ea9bb1387769e4c6d2749538dfed9ae36/follow_up_boss-0.2.0.tar.gz",
"platform": null,
"description": "# Follow Up Boss API Client\n\nA comprehensive Python client library for the Follow Up Boss API, providing easy access to all Follow Up Boss endpoints with full type safety and thorough documentation.\n\n## Features\n\n- **Complete API Coverage**: Support for all Follow Up Boss API endpoints\n- **Type Safety**: Full type hints throughout the library\n- **Easy to Use**: Simple, intuitive interface\n- **Well Documented**: Comprehensive docstrings and examples\n- **Async Support**: Built with modern Python async/await patterns\n- **Error Handling**: Robust error handling and validation\n- **Extensible**: Easy to extend for custom use cases\n\n## Installation\n\n```bash\npip install follow-up-boss\n```\n\n## Quick Start\n\n```python\nfrom follow_up_boss import FollowUpBossApiClient\n\n# Initialize the client\nclient = FollowUpBossApiClient(\n api_key=\"your_api_key\",\n x_system=\"Your-System-Name\",\n x_system_key=\"your_system_key\"\n)\n\n# Get all people\npeople = client.people.get_all()\n\n# Create a new person\nnew_person = client.people.create({\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"phone\": \"555-123-4567\"\n})\n\n# Update a person\nupdated_person = client.people.update(person_id, {\n \"name\": \"John Smith\"\n})\n\n# Delete a person\nclient.people.delete(person_id)\n```\n\n## Environment Variables\n\nYou can also configure the client using environment variables:\n\n```bash\nFOLLOW_UP_BOSS_API_KEY=your_api_key\nX_SYSTEM=Your-System-Name\nX_SYSTEM_KEY=your_system_key\n```\n\n```python\nfrom follow_up_boss import FollowUpBossApiClient\n\n# Client will automatically use environment variables\nclient = FollowUpBossApiClient()\n```\n\n## API Resources\n\nThe client provides access to all Follow Up Boss API resources:\n\n### Core Resources\n- **People**: Manage contacts and leads\n- **Deals**: Track real estate transactions ([Commission Field Guide](DEALS_COMMISSION_GUIDE.md))\n- **Events**: Handle activities and interactions\n- **Tasks**: Manage todo items and follow-ups\n- **Notes**: Add and retrieve notes\n- **Appointments**: Schedule and manage appointments\n\n### Communication\n- **Text Messages**: Send and receive SMS\n- **Email Templates**: Manage email templates\n- **Text Message Templates**: Manage SMS templates\n- **Webhooks**: Configure webhook endpoints\n- **Reactions**: Handle message reactions\n\n### Organization\n- **Teams**: Manage team structures\n- **Users**: Handle user accounts\n- **Groups**: Organize contacts into groups\n- **Pipelines**: Manage sales pipelines\n- **Stages**: Configure pipeline stages\n- **Smart Lists**: Dynamic contact lists\n\n### Configuration\n- **Custom Fields**: Define custom data fields\n- **Action Plans**: Automated workflow templates\n- **Appointment Types**: Configure appointment categories\n- **Appointment Outcomes**: Track appointment results\n\n### Attachments & Files\n- **Person Attachments**: File attachments for contacts\n- **Deal Attachments**: File attachments for deals\n\n## Deals API - Commission Fields\n\nThe Deals API includes special handling for commission fields. **Important**: Commission fields must be passed as top-level parameters, not in `custom_fields`.\n\n```python\nfrom follow_up_boss import Deals, DealsValidationError\n\ndeals_api = Deals(client)\n\n# \u2705 Correct - Commission fields as top-level parameters\ndeal = deals_api.create_deal(\n name=\"123 Main Street\",\n stage_id=26,\n price=450000,\n commissionValue=13500.0,\n agentCommission=9450.0,\n teamCommission=4050.0\n)\n\n# \u274c Incorrect - This will raise DealsValidationError\ntry:\n deal = deals_api.create_deal(\n name=\"Deal Name\",\n stage_id=26,\n custom_fields={'commissionValue': 13500} # This fails\n )\nexcept DealsValidationError as e:\n print(f\"Validation error: {e}\")\n```\n\n### Commission Helper Methods\n\n```python\n# Set commission using helper method\ncommission_data = {\n 'total': 15000.0,\n 'agent': 10500.0,\n 'team': 4500.0\n}\n\nupdated_deal = deals_api.set_deal_commission(deal_id, commission_data)\n```\n\nFor complete commission field documentation, see the [Commission Field Guide](DEALS_COMMISSION_GUIDE.md).\n\n## Advanced Usage\n\n### Error Handling\n\n```python\nfrom follow_up_boss import FollowUpBossApiClient\nfrom follow_up_boss.exceptions import ApiError, AuthenticationError\n\ntry:\n client = FollowUpBossApiClient(api_key=\"invalid_key\")\n people = client.people.get_all()\nexcept AuthenticationError:\n print(\"Invalid API credentials\")\nexcept ApiError as e:\n print(f\"API Error: {e}\")\n```\n\n### Pagination\n\n```python\n# Get all people with pagination\nall_people = []\npage = 1\n\nwhile True:\n response = client.people.get_all(page=page, limit=100)\n people = response.get('people', [])\n \n if not people:\n break\n \n all_people.extend(people)\n page += 1\n```\n\n### Custom Headers\n\n```python\n# Add custom headers to requests\nclient = FollowUpBossApiClient(\n api_key=\"your_key\",\n custom_headers={\n \"X-Custom-Header\": \"custom_value\"\n }\n)\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/theperrygroup/follow-up-boss.git\ncd follow-up-boss\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack follow_up_boss tests\nisort follow_up_boss tests\n```\n\n### Type Checking\n\n```bash\nmypy follow_up_boss\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for your changes\n5. Ensure all tests pass (`pytest`)\n6. Format your code (`black` and `isort`)\n7. Commit your changes (`git commit -m 'Add amazing feature'`)\n8. Push to the branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor questions, issues, or feature requests, please:\n\n1. Check the [documentation](https://github.com/theperrygroup/follow-up-boss#readme)\n2. Search [existing issues](https://github.com/theperrygroup/follow-up-boss/issues)\n3. Create a [new issue](https://github.com/theperrygroup/follow-up-boss/issues/new) if needed\n\n## Changelog\n\n### Version 0.2.0\n- **Major Commission Field Improvements**: Added comprehensive commission field handling with validation\n- **Enhanced Error Messages**: Context-specific error guidance for common mistakes\n- **New Validation System**: `DealsValidationError` for deals-specific validation\n- **Commission Helper Methods**: `set_deal_commission()` for easier commission management\n- **Field Name Normalization**: Consistent field naming between requests and responses\n- **Comprehensive Documentation**: New commission field guide with examples and troubleshooting\n- **Enhanced Testing**: Complete test coverage for all commission field scenarios\n- **Improved Developer Experience**: Better error messages, helper properties, and validation\n\n### Version 0.1.2\n- Removed appointment test log file logging\n\n### Version 0.1.1\n- Updated website URL to https://theperry.group\n\n### Version 0.1.0\n- Initial release\n- Complete API coverage for all Follow Up Boss endpoints\n- Full type safety with comprehensive type hints\n- Comprehensive test suite\n- Documentation and examples\n\n## Related Projects\n\n- [Follow Up Boss API Documentation](https://followupboss.com/api/)\n- [Follow Up Boss](https://followupboss.com/) - The official Follow Up Boss platform\n\n---\n\nMade with \u2764\ufe0f by [The Perry Group](https://theperry.group) \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client library for the Follow Up Boss API",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/theperrygroup/follow-up-boss/issues",
"Documentation": "https://github.com/theperrygroup/follow-up-boss#readme",
"Homepage": "https://github.com/theperrygroup/follow-up-boss",
"Repository": "https://github.com/theperrygroup/follow-up-boss"
},
"split_keywords": [
"followupboss",
" api",
" client",
" real-estate",
" crm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0b765fd69844c1e5efed3cc745fb7d14e20db8bb3efbbe00f4247b8743d4e3ab",
"md5": "7b8c98490f2e3c7bf0b0f5cd4dade38b",
"sha256": "e8d62af26cf0e23aaad8a5b8401a03d7ede89cbed550bc74855c2799e284ff6b"
},
"downloads": -1,
"filename": "follow_up_boss-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b8c98490f2e3c7bf0b0f5cd4dade38b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 62364,
"upload_time": "2025-07-12T01:04:16",
"upload_time_iso_8601": "2025-07-12T01:04:16.904999Z",
"url": "https://files.pythonhosted.org/packages/0b/76/5fd69844c1e5efed3cc745fb7d14e20db8bb3efbbe00f4247b8743d4e3ab/follow_up_boss-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "41042833df67048317bb21a316f7581ea9bb1387769e4c6d2749538dfed9ae36",
"md5": "fc6b1ec15341dcf53feb94a0f770080d",
"sha256": "22586ddb9401b4dbdc5cdb4384fc8db6226be6e1c5bf6344dd65da803128be8a"
},
"downloads": -1,
"filename": "follow_up_boss-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "fc6b1ec15341dcf53feb94a0f770080d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42754,
"upload_time": "2025-07-12T01:04:18",
"upload_time_iso_8601": "2025-07-12T01:04:18.126154Z",
"url": "https://files.pythonhosted.org/packages/41/04/2833df67048317bb21a316f7581ea9bb1387769e4c6d2749538dfed9ae36/follow_up_boss-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 01:04:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "theperrygroup",
"github_project": "follow-up-boss",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "python-dotenv",
"specs": []
}
],
"lcname": "follow-up-boss"
}
JSON
