# Partner API Quick Start Guide **BondBricks Partner API v1.0** Get started with the Partner API in 15 minutes --- ## Overview The BondBricks Partner API allows bond servicers and financial institutions to: - ✅ Retrieve real-time investment data - ✅ Confirm bond allocations programmatically - ✅ Receive webhook notifications for new investments - ✅ Upload bulk confirmations via CSV **Base URL**: `https://www.bondbricks.com/api/v1` **Authentication**: Bearer token (API Key) **Rate Limit**: 100 requests/minute --- ## Step 1: Get Your API Key (2 minutes) Contact our partner team to receive your API credentials: 📧 **Email**: partners@bondbricks.com 📋 **Include**: - Your institution name - Contact person and role - Integration use case - Expected request volume **Response Time**: 1 business day --- ## Step 2: Test Authentication (2 minutes) Test your API key with a simple health check: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://www.bondbricks.com/api/v1/investments?limit=1" ``` **Expected Response** (200 OK): ```json { "data": [...], "pagination": { "total": 150, "page": 1, "limit": 1 } } ``` **Common Errors**: - `401 Unauthorized`: Invalid or missing API key - `429 Too Many Requests`: Rate limit exceeded (wait 60 seconds) --- ## Step 3: Fetch Pending Investments (3 minutes) Retrieve investments awaiting confirmation: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://www.bondbricks.com/api/v1/investments?status=COMPLETED&partner_status=PENDING" ``` **Response**: ```json { "data": [ { "id": "inv_123abc", "investorId": "usr_456def", "propertyId": "prop_789ghi", "amount": 50000, "units": 50, "status": "COMPLETED", "partnerStatus": "PENDING", "createdAt": "2026-04-01T10:30:00Z" } ], "pagination": { "total": 25, "page": 1, "limit": 50 } } ``` **Key Fields**: - `id`: Investment identifier (use for confirmations) - `partnerStatus`: `PENDING`, `CONFIRMED`, or `REJECTED` - `amount`: Investment amount in USD cents (50000 = $500.00) --- ## Step 4: Confirm an Investment (3 minutes) ### Single Investment Confirmation ```bash curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "investmentId": "inv_123abc", "partnerBondRef": "BOND-2026-001", "status": "CONFIRMED", "confirmationDate": "2026-04-02", "notes": "Bond allocated successfully" }' \ "https://www.bondbricks.com/api/v1/confirmations" ``` **Required Fields**: - `investmentId`: The investment ID from Step 3 - `partnerBondRef`: Your internal bond reference (max 100 chars) - `status`: Either `CONFIRMED` or `REJECTED` - `confirmationDate`: Date in YYYY-MM-DD format (not future) **Response** (201 Created): ```json { "id": "conf_xyz789", "investmentId": "inv_123abc", "status": "CONFIRMED", "partnerBondRef": "BOND-2026-001", "confirmedAt": "2026-04-02T14:25:00Z" } ``` --- ## Step 5: Bulk Confirmations (5 minutes) ### Option A: JSON Bulk Endpoint (Recommended for < 100 records) ```bash curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "confirmations": [ { "investmentId": "inv_123abc", "partnerBondRef": "BOND-2026-001", "status": "CONFIRMED", "confirmationDate": "2026-04-02" }, { "investmentId": "inv_456def", "partnerBondRef": "BOND-2026-002", "status": "CONFIRMED", "confirmationDate": "2026-04-02" } ] }' \ "https://www.bondbricks.com/api/v1/confirmations/bulk" ``` **Response**: ```json { "total": 2, "successful": 2, "failed": 0, "results": [ { "investmentId": "inv_123abc", "status": "success", "confirmationId": "conf_xyz789" }, { "investmentId": "inv_456def", "status": "success", "confirmationId": "conf_xyz790" } ] } ``` ### Option B: CSV Upload (Recommended for > 100 records) **Create CSV file** (`confirmations.csv`): ```csv investment_id,partner_bond_ref,status,confirmation_date,notes inv_123abc,BOND-2026-001,CONFIRMED,2026-04-02,Allocated successfully inv_456def,BOND-2026-002,CONFIRMED,2026-04-02,Allocated successfully inv_789ghi,,REJECTED,2026-04-02,Insufficient collateral ``` **Upload CSV**: ```bash curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@confirmations.csv" \ "https://www.bondbricks.com/api/v1/uploads/confirmations" ``` **CSV Requirements**: - Maximum file size: 10MB - Maximum rows: 10,000 (recommended < 1,000 per file) - Encoding: UTF-8 - Required columns: `investment_id`, `partner_bond_ref`, `status`, `confirmation_date` - Optional columns: `notes` (max 500 characters) --- ## Webhooks (Optional) Subscribe to real-time notifications when new investments are created. **Configure in Partner Portal** or contact partners@bondbricks.com **Webhook Events**: - `investment.created` - New investment received - `investment.confirmed` - Investment confirmed by partner - `investment.rejected` - Investment rejected by partner **Webhook Payload Example**: ```json { "event": "investment.created", "data": { "id": "inv_123abc", "investorId": "usr_456def", "propertyId": "prop_789ghi", "amount": 50000, "units": 50, "createdAt": "2026-04-01T10:30:00Z" }, "timestamp": "2026-04-01T10:30:01Z" } ``` **Webhook Retry Policy**: - 3 retry attempts with exponential backoff (1min, 5min, 15min) - Must respond with 2xx status code within 10 seconds --- ## Rate Limits | Endpoint Type | Limit | Window | |--------------|-------|--------| | Standard API | 100 requests | per minute | | Bulk JSON | 20 requests | per minute | | CSV Upload | 10 requests | per minute | **Exceeded Limit Response** (429): ```json { "error": "Rate limit exceeded", "retryAfter": 60 } ``` **Best Practice**: Implement exponential backoff for 429 responses --- ## Error Handling **Standard Error Response**: ```json { "error": "Invalid request", "code": "VALIDATION_ERROR", "details": { "field": "confirmationDate", "message": "Date cannot be in the future" } } ``` **Common HTTP Status Codes**: - `400 Bad Request`: Invalid parameters or request body - `401 Unauthorized`: Missing or invalid API key - `403 Forbidden`: API key lacks required permissions - `404 Not Found`: Resource (investment) not found - `422 Unprocessable Entity`: Business rule validation failed - `429 Too Many Requests`: Rate limit exceeded - `500 Internal Server Error`: Server error (contact support) --- ## Testing in Sandbox **Sandbox Base URL**: `https://sandbox.bondbricks.com/api/v1` Use your sandbox API key to test without affecting production data. **Test Investment IDs** (always available in sandbox): - `inv_test_pending_001` - `inv_test_pending_002` - `inv_test_pending_003` **Test CSV Download**: ```bash curl -H "Authorization: Bearer YOUR_SANDBOX_KEY" \ "https://sandbox.bondbricks.com/api/v1/investments?format=csv" \ -o investments.csv ``` --- ## Next Steps ✅ **Quick Start Complete!** **Now you can**: 1. 📖 [Read the Full Integration Guide](./PARTNER_INTEGRATION_GUIDE.md) for advanced features 2. ✅ [Complete the Onboarding Checklist](./PARTNER_ONBOARDING_CHECKLIST.md) before going live 3. 🔒 [Review Security Best Practices](https://www.bondbricks.com/bond-partners/security) 4. 📚 [Explore the Full API Documentation](https://www.bondbricks.com/api-docs) --- ## Support **Technical Support**: api-support@bondbricks.com **Partner Team**: partners@bondbricks.com **Response Time**: 4 business hours (1 hour SLA for Enterprise) **Include in Support Requests**: - Request ID (from `X-Request-ID` response header) - Timestamp of the error - Full request/response (remove sensitive data) - Expected vs actual behavior --- **Last Updated**: April 2026 **API Version**: 1.0 **Document Version**: 1.0