Developer API Integration - Back On Market Docs

Developer API Integration

Welcome to the BOMDocs Developer Center. Integrate our property report marketplace into your applications; see also Privacy for data practices when handling user or report data.

Why Integrate with BOMDocs?

Our API allows you to search, purchase, and retrieve professional property reports (home inspections, appraisals, sewer scopes, and more) directly from your own software. Whether you’re building a real estate portal, CRM, or mobile app, BOMDocs powers a transparent, commission‐friendly marketplace behind the scenes.

Getting Started

1. Create a Developer Account
   To access the BOMDocs API, you must first have a Developer Account. If you don’t already have one, sign up here and select the “Developer” role.
2. Generate an API Key
   API keys are granted only via admin/support approval (not self-serve). After a key is issued, view and copy your full key at API Keys.
3. Review the Documentation
   Browse our full API reference at /dev/docs. You’ll find a list of endpoints, required parameters, response schemas, and code samples (cURL, C#, JavaScript, etc.).
4. Usage & Reports
   Track billing-related usage at API Usage and your listed reports at My API Reports (when logged in as an approved Developer).
5. Make Test Calls
   Use your API Key in the request header to try out endpoints. For example, to search for “Home Inspection” reports in cURL:

   curl -X GET "https://your-domain.com/api/reports?search=Home%20Inspection" \
     -H "Authorization: Bearer BOMD-your-api-key-here" \
     -H "Accept: application/json"

Authentication & Security

Every request must include your API Key in the Authorization header. Use Authorization: Bearer BOMD-... (recommended), or HTTP Basic Auth with password = your API key for legacy clients. Do not embed your key in client-side code or expose it publicly. Each key is tied to your Developer Account and can be revoked at any time from API Keys.

Server-to-server: The same Bearer token works for server-to-server requests; no cookie or session is required. Send only the Authorization: Bearer BOMD-... header and the API identifies the caller from the key.

Example Header:
Authorization: Bearer <YOUR_API_KEY>

Available Endpoints

For full request/response details, see the API reference.

• GET /api/reports — List published reports. Optional: ?type=, ?search=, ?includeAccess=true.
• GET /api/reports/{id} — Get report metadata and license info. Optional ?token= for token-based access check.
• GET /api/reports/{id}/download — Download report PDF (requires valid license). Optional ?token= for license token.
• GET /api/billing/summary, GET /api/billing/transactions, GET /api/billing/commissions — Billing and commission data for the authenticated user.
• GET /api/reviews/report/{reportId}, POST /api/reviews, POST /api/reviews/{id}/helpful — Read and create reviews (create/helpful require authentication).
• GET /api/accounts/me — Returns your account profile (id, email, displayName, role, isDeveloperApproved). Use to verify your API key.

Billing & Commission Rates

As a Developer, you can integrate BOMDocs into your applications and earn commissions on report purchases made through your integration. Here's how it works:

Commission Structure

Earn a percentage of every report purchase made through your integration. Tiers are based on API-driven purchases per month (resets monthly).

• Tier 1 (0–100 API purchases/month): 10% commission.
• Tier 2 (101–500 API purchases/month): 12% commission.
• Tier 3 (501+ API purchases/month): 15% commission.
• Package deals & enterprise: Volume commitments, bundled support, white-label, or higher rate limits can qualify for negotiated rates. Contact Sales for custom terms.
• Payouts: Commissions are tracked in your dashboard; request a payout once you reach the minimum threshold (typically $50).

Example projected earnings (avg. report $45)

API Usage & Billing

• API Usage Tracking: All API calls are logged and tracked in your Developer dashboard, providing detailed analytics on endpoint usage, response times, and errors.
• Billing Transparency: View your API usage, commission earnings, and payout history at any time through your account dashboard.
• Rate Limits: Each API Key is limited to 100 requests per minute. Exceeding this will result in HTTP 429 (Too Many Requests). Enterprise accounts may negotiate higher rate limits.

Negotiate Your Rates

High-volume integrations, annual commitments, white-label deals, or bundled support may qualify for preferred rates, higher rate limits, or custom terms. Contact our sales team to discuss package deals and enterprise options.

Contact Sales About Rates & Package Deals

Developer Account Process

1. Sign Up: Create an account and select the "Developer" role during registration.
2. Approval: Developer accounts require admin approval. Once approved, you'll receive email notification and full access to the API.
3. API Keys: After account approval, request a key via support/admin. View issued keys at API Keys (prefix/metadata; full secret only at issuance).
4. Review Documentation: Explore our comprehensive API documentation at /dev/docs.
5. Start Building: Integrate BOMDocs into your applications and start earning commissions.

Rate Limits & Best Practices

• API traffic is rate-limited (see server responses); heavy endpoints such as report analysis may use a stricter per-client budget. Expect HTTP 429 when exceeded.
• Always cache search results for at least 60 seconds to reduce load.
• Handle errors gracefully and implement retry logic with exponential backoff.
• Monitor your API usage through the Developer dashboard to optimize performance.

Support & Contact

If you run into any issues, email our Developer Support at [email protected] or contact us through our support form. We're here to help you ship quickly and securely.