Builder Backed V2 API Documentation

New to Builder Backed APIs?

We recommend starting with our comprehensive Builder Integration Guide, which walks you through the complete setup process step by step.

What You'll Learn

• Prerequisites: Authentication, region activation, and data requirements
• Step 1: Creating location hierarchies (Divisions → Master Communities → Neighborhoods)
• Step 2: Creating homes with homeowners and automatic location validation
• Testing: Using Swagger UI for interactive API testing
• Troubleshooting: Common errors and solutions

Integration Workflow

Region (activated by Builder Backed)
  └── Division (you create)
      └── Master Community (you create)
          └── Neighborhood (you create)
              └── Homes (you create)

Key Features:

• Automatic location hierarchy validation
• V2 APIs with improved data structures
• Comprehensive error handling
• OAuth2 authentication
• Interactive Swagger UI for testing

Quick Links

• Builder Integration Guide - Complete step-by-step tutorial
• V2 Homes API - Create and manage homes
• Location Hierarchy API - Set up your locations
• Swagger UI - Interactive API testing

The V2 Homes API provides comprehensive home management with automatic location hierarchy validation. All endpoints require OAuth2 authentication with the home.write scope.

Get Home by External ID

curl -X GET "https://api-stage.builderbacked.com/api/v2/homes/HOME_12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

url = "https://api-stage.builderbacked.com/api/v2/homes/HOME_12345"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

response = requests.get(url, headers=headers)
home = response.json()
print(f"Home: {home['addressLine1']}, {home['city']}, {home['state']}")

{
  "id": 98765,
  "externalId": "HOME_12345",
  "addressLine1": "123 Main St",
  "city": "Columbus",
  "state": "OH",
  "postalCode": "43215",
  "type": "Single Family",
  "neighborhoodExternalId": "NH_001",
  "masterCommunityExternalId": "MC_001",
  "divisionExternalId": "DIV_001",
  "regionExternalId": "Cincinnati",
  "status": "ACTIVE",
  "homeSource": "BuilderRegistration"
}

Create Home

{
  "externalId": "HOME_12345",
  "addressLine1": "123 Main St",
  "city": "Columbus",
  "state": "OH",
  "postalCode": "43215",
  "type": "Single Family",
  "model": "Preston",
  "neighborhoodExternalId": "NH_001",
  "homeowners": [
    {
      "email": "john.smith@email.com",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
}

import requests

url = "https://api-stage.builderbacked.com/api/v2/homes"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
home_data = {
    "externalId": "HOME_12345",
    "addressLine1": "123 Main St",
    "city": "Columbus",
    "state": "OH",
    "postalCode": "43215",
    "type": "Single Family",
    "neighborhoodExternalId": "NH_001"
}

response = requests.post(url, headers=headers, json=home_data)
home = response.json()
print(f"Created home: {home['id']}")

curl -X POST "https://api-stage.builderbacked.com/api/v2/homes" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "HOME_12345",
    "addressLine1": "123 Main St",
    "city": "Columbus",
    "state": "OH",
    "postalCode": "43215",
    "type": "Single Family",
    "neighborhoodExternalId": "NH_001"
  }'

Update Home

{
  "externalId": "HOME_12345",
  "addressLine1": "123 Main St",
  "city": "Columbus",
  "state": "OH",
  "postalCode": "43215",
  "type": "Single Family",
  "model": "Preston Deluxe",
  "neighborhoodExternalId": "NH_001"
}

url = "https://api-stage.builderbacked.com/api/v2/homes"
home_data = {
    "externalId": "HOME_12345",
    "model": "Preston Deluxe"  # Update model
    # Include all required fields
}

response = requests.put(url, headers=headers, json=home_data)
print(f"Updated home: {response.status_code}")

Add Homeowner to Home

{
  "email": "jane.smith@email.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "prefix": "Mrs."
}

url = f"https://api-stage.builderbacked.com/api/v2/homes/HOME_12345/users"
homeowner = {
    "email": "jane.smith@email.com",
    "firstName": "Jane",
    "lastName": "Smith"
}

response = requests.post(url, headers=headers, json=homeowner)
print(f"Added homeowner: {response.status_code}")

Remove Homeowner from Home

curl -X DELETE "https://api-stage.builderbacked.com/api/v2/homes/HOME_12345/users/jane.smith@email.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

url = f"https://api-stage.builderbacked.com/api/v2/homes/HOME_12345/users/jane.smith@email.com"
response = requests.delete(url, headers=headers)
print(f"Removed homeowner: {response.status_code}")

The V2 Users API provides organization user management with support for profile images. All endpoints require OAuth2 authentication with the user.write scope.

Check if User Exists

curl -X GET "https://api-stage.builderbacked.com/api/v2/users/john.smith@email.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

url = "https://api-stage.builderbacked.com/api/v2/users/john.smith@email.com"
response = requests.get(url, headers=headers)
if response.status_code == 200:
    print("User exists")
elif response.status_code == 404:
    print("User not found")

Create Organization User

import requests

url = "https://api-stage.builderbacked.com/api/v2/users"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

user_data = {
    "externalId": "EMP_12345",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@builder.com",
    "roleName": "Field Manager",
    "phoneNumber": "(555) 555-5555"
}

files = {
    "user": (None, json.dumps(user_data), "application/json"),
    "profileImage": ("profile.jpg", open("profile.jpg", "rb"), "image/jpeg")
}

response = requests.post(url, headers=headers, files=files)
user = response.json()
print(f"Created user: {user['firstName']} {user['lastName']}")

The Location Hierarchy API manages the four-level hierarchy: Regions → Divisions → Master Communities → Neighborhoods. All endpoints require OAuth2 authentication with the location.write scope.

Region (activated by Builder Backed)
  └── Division (you create)
      └── Master Community (you create)
          └── Neighborhood (you create)

Regions

Regions are the top level of the hierarchy and must be activated by Builder Backed before you can create divisions.

curl -X GET "https://api-stage.builderbacked.com/api/v2/locations/regions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Divisions

Divisions are the first level you create under regions.

{
  "externalId": "DIV_001",
  "name": "Cincinnati Division",
  "regionName": "Cincinnati"
}

Master Communities

Master Communities are created under divisions and group related neighborhoods.

{
  "externalId": "MC_001",
  "name": "Shaker Run",
  "divisionExternalId": "DIV_001"
}

Neighborhoods

Neighborhoods are the lowest level and directly contain homes.

{
  "externalId": "NH_001",
  "name": "Lakeside",
  "masterCommunityExternalId": "MC_001"
}

For complete endpoint documentation including GET, UPDATE, ACTIVATE, and DEACTIVATE operations, see the Builder Integration Guide or Swagger UI.

Home Models

User/Homeowner Models

Location Models

Error Response Format

All errors follow a consistent format:

{
  "timestamp": "2025-01-03T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed for field 'externalId'",
  "path": "/api/v2/homes"
}

Common HTTP Status Codes

API-Specific Errors

For more detailed troubleshooting, see the Common Errors section in the Builder Integration Guide.

The Builder Integration Guide provides a comprehensive, step-by-step tutorial for integrating with Builder Backed APIs.

Quick Start Integration

If you're new to Builder Backed, we strongly recommend starting with the integration guide. It will walk you through:

1. Verifying your regions are activated
2. Creating your first division, master community, and neighborhood
3. Creating your first home with homeowners
4. Testing everything in Swagger UI

Estimated Time: 30-60 minutes for complete setup

Why Use the Integration Guide?

The integration guide provides:

• Step-by-step instructions with no steps skipped
• Copy-paste ready code that you can customize
• Common pitfalls and how to avoid them
• Visual aids showing the location hierarchy relationships
• Interactive testing tips using Swagger UI

Swagger UI

Builder Backed provides an interactive Swagger UI interface where you can test all API endpoints in real-time without writing code.

How to Use Swagger UI

Swagger URL Structure

You can link directly to specific API sections:

• Homes API - /swagger-ui.html#/Homes
• Locations API - /swagger-ui.html#/Locations
• Users API - /swagger-ui.html#/Users

API Documentation Endpoints

• Swagger UI: /swagger-ui.html
• OpenAPI JSON: /api-docs
• V2 API Group: /api-docs?group=v2-apis

Testing Best Practices

• Test in Order: Start with regions, then divisions, then master communities, then neighborhoods, then homes
• Save External IDs: Keep track of the externalId values you create for use in subsequent requests
• Verify Responses: Check that auto-populated fields (like location hierarchy) are correct
• Test Error Cases: Try invalid inputs to understand error responses
• Use GET Endpoints: Verify created resources using GET endpoints before proceeding

Need Help?

If you encounter any issues with the interactive testing environment or need assistance with API integration:

• Check our Models section for detailed schema information
• Review the Errors page for troubleshooting guidance
• Consult the Builder Integration Guide
• Contact our development team at eric@bebuilderbacked.com