Birch & Co. Brokerage Zapier API Documentation
The Birch & Co. Brokerage Zapier API enables seamless integration between Birch & Co. Brokerage and Zapier's automation platform. This RESTful API uses OAuth 2.0 for authentication and provides triggers for real-time lead management automation.
Authentication
OAuth 2.0 Authorization Code Flow
Endpoint: GET /api/oauth/zapier/authorize
Redirect users to authorize Zapier access to their Birch & Co. Brokerage account.
Parameters:
client_id(required): Your Zapier OAuth client IDredirect_uri(required): Zapier's callback URLresponse_type(required): Must be "code"state(optional): Random string for security
GET /api/oauth/zapier/authorize?client_id=your_client_id& redirect_uri=https://zapier.com/dashboard/auth/oauth/return/App223984CLIAPI/& response_type=code&state=random_string
Endpoint: POST /api/oauth/zapier/token
Exchange authorization code for access token.
Request Body:
{ "grant_type": "authorization_code", "client_id": "your_client_id", "client_secret": "your_client_secret", "code": "authorization_code_from_step_1", "redirect_uri": "https://zapier.com/dashboard/auth/oauth/return/App223984CLIAPI/" }
Success Response (200):
{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "def502004a1b2c3d4e5f...", "scope": "read:leads write:leads" }
Endpoint: POST /api/oauth/zapier/token
Refresh expired access tokens.
Request Body:
{ "grant_type": "refresh_token", "refresh_token": "def502004a1b2c3d4e5f...", "client_id": "your_client_id", "client_secret": "your_client_secret" }
API Endpoints
New Lead Trigger
/api/v1/zapier/triggers/new_leadRetrieve new leads for Zapier trigger automation.
Query Parameters / Request Body:
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by lead status (e.g., "new", "contacted", "qualified") |
source | string | Filter by lead source (e.g., "website", "referral", "social") |
date_after | string | ISO 8601 datetime to get leads created after this date |
user_id | string | Specific user ID (defaults to authenticated user) |
page | number | Page number for pagination (default: 0) |
Success Response (200):
[ { "id": "01590a68-0c4f-a131-3d32-55d935341c11", "created_at": "2024-01-15T10:30:00Z", "full_name": "John Doe", "email": "john@example.com", "phone": "+1234567890", "assigned_agent_id": "agent-123", "lead_id": "lead-456", "team_id": "team-789", "lead_status": "new", "lead_source": "website", "intention": "buy", "property_type": "house", "location": "New York", "min_budget": "300000", "max_budget": "500000", "bedrooms": "3", "bathrooms": "2", "timeline": "3-6 months", "pre_approved": "true", "notes": "Looking for family home", "follow_up_date": "2024-01-20T10:00:00Z", "buyer_type": "first-time" } ]
User Information
/api/v1/zapier/userRetrieve authenticated user information for account validation.
Error Handling
HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid or expired token |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
Error Response Format
{ "error": "error_code", "error_description": "Human-readable error description", "code": "SPECIFIC_ERROR_CODE" }
Common Error Codes
| Error Code | Description | Solution |
|---|---|---|
invalid_token | Access token is invalid or malformed | Refresh token or re-authenticate |
TOKEN_EXPIRED | Access token has expired | Use refresh token to get new access token |
invalid_client | Client ID or secret is incorrect | Verify OAuth credentials |
invalid_grant | Authorization code or refresh token invalid | Re-authenticate user |
access_denied | User denied authorization | User must approve Zapier access |
Rate Limiting
- Rate Limit: 100 requests per minute per user
- Burst Limit: 10 requests per second
Headers Included:
X-RateLimit-Limit: Request limit per windowX-RateLimit-Remaining: Requests remaining in current windowX-RateLimit-Reset: Time when rate limit resets (Unix timestamp)
Rate Limit Exceeded Response (429):
{ "error": "rate_limit_exceeded", "error_description": "Too many requests. Try again later.", "retry_after": 60 }
Token Validation
/api/oauth/zapier/validateValidate the current access token and return user information.
Success Response (200):
{ "valid": true, "user_id": "user-123", "email": "user@birchandcobrokerage.com", "scopes": ["read:leads", "write:leads"], "expires_at": "2024-01-15T11:30:00Z" }
Webhooks & Real-time Updates
Birch & Co. Brokerage supports webhook notifications for real-time lead updates.
Configuration:
- Webhook URL: Set in Zapier app settings
- Content-Type: application/json
- Authentication: HMAC-SHA256 signature verification
Webhook Payload:
{ "event_type": "lead.created", "timestamp": "2024-01-15T10:30:00Z", "data": { // Lead object (same format as API response) } }
Testing & Development
Test Endpoints
Base URL: https://hub.birchandcobrokerage.com/api/v1/zapier
Test Credentials
Client ID: zapier_test_client_123 Client Secret: zapier_test_secret_456 Test User Email: zapier-test@birchandcobrokerage.com Test User Password: TestPassword123!
Sample cURL Commands
Get Access Token:
curl -X POST https://hub.birchandcobrokerage.com/api/oauth/zapier/token \ -H "Content-Type: application/json" \ -d '{ "grant_type": "authorization_code", "client_id": "your_client_id", "client_secret": "your_client_secret", "code": "auth_code_here", "redirect_uri": "https://zapier.com/dashboard/auth/oauth/return/App223984CLIAPI/" }'
Get New Leads:
curl -X GET "https://hub.birchandcobrokerage.com/api/v1/zapier/triggers/new_lead?status=new" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Support & Resources
Technical Support:
support@birchandcobrokerage.com
Developer Portal:
https://hub.birchandcobrokerage.com/developers
Status Page:
https://status.birchandcobrokerage.com
Zapier Integration:
https://zapier.com/apps/Birch & Co.crm
SDKs & Libraries
- JavaScript/Node.js:
npm install @Birch & Co./zapier-sdk - Python:
pip install Birch & Co.-zapier - PHP:
composer require Birch & Co./zapier-client
Changelog
v1.0.0 (Current)
- Initial API release
- OAuth 2.0 authentication
- New Lead trigger
- Real-time webhook support
- Rate limiting implementation
Security
- OAuth 2.0 with PKCE support
- HTTPS only - All endpoints require SSL/TLS
- Token expiration - Access tokens expire in 1 hour
- Scope-based permissions - Granular access control
- Request signing - HMAC-SHA256 webhook verification
- Rate limiting - Protection against abuse
Security Issues
For security issues, contact: security@birchandcobrokerage.com
Lead Object Field Descriptions
| Field | Type | Description |
|---|---|---|
id | string | Unique lead identifier |
created_at | string (ISO 8601) | Lead creation timestamp |
full_name | string | Lead's full name |
email | string | Lead's email address |
phone | string | Lead's phone number |
assigned_agent_id | string | ID of assigned real estate agent |
lead_id | string | Human-readable lead ID |
team_id | string | Associated team identifier |
lead_status | string | Current lead status |
lead_source | string | How the lead was acquired |
intention | string | Lead's intention (buy/sell/rent) |
property_type | string | Type of property interest |
location | string | Preferred location |
min_budget | string | Minimum budget (converted to string) |
max_budget | string | Maximum budget (converted to string) |
bedrooms | string | Number of bedrooms (converted to string) |
bathrooms | string | Number of bathrooms (converted to string) |
timeline | string | Purchase timeline |
pre_approved | string | Pre-approval status (converted to string) |
notes | string | Additional notes |
follow_up_date | string (ISO 8601) | Scheduled follow-up date |
buyer_type | string | Type of buyer |
API Documentation v1.0.0