Builder Integration Guide

A step-by-step guide to integrating your builder management system with Builder Backed

What You'll Build

This guide walks you through setting up the foundational data structure required for Builder Backed integration:

  • Location hierarchy (Divisions, Master Communities, Neighborhoods)
  • Home records with validated location references
  • Homeowner associations (optional during home creation)
Time Required: 30-60 minutes
Prerequisites: API credentials with location.write and home.write scopes
Outcome: Complete location hierarchy with at least one home record

Integration Workflow

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

Integration Steps:

  1. Verify regions are activated (Builder Backed responsibility)
  2. Create location hierarchy (Division → Master Community → Neighborhood)
  3. Create home records with neighborhood references
  4. Test and validate using Swagger UI

Prerequisites

1. API Authentication

You'll need OAuth2 client credentials with the following scopes:

  • location.write - For creating location hierarchy
  • home.write - For creating home records
Authentication Format: 
Authorization: Bearer YOUR_ACCESS_TOKEN

Obtain your access token using OAuth2 Client Credentials flow. Contact your Builder Backed representative for credentials.

2. Region Activation (CRITICAL REQUIREMENT)

⚠️ CRITICAL REQUIREMENT:

Before you can create any location hierarchy, Builder Backed must activate regions for your builder account. This is a one-time setup performed by Builder Backed staff.

Contact your Builder Backed representative (eric@bebuilderbacked.com) to confirm regions are activated before proceeding.

Verify Region Activation

Use this endpoint to confirm regions are available:

GET Get Regions

/api/v2/locations/regions

Try in Swagger UI
Example Request:
curl -X GET "https://api-stage.builderbacked.com/api/v2/locations/regions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
import requests

response = requests.get(
    "https://api-stage.builderbacked.com/api/v2/locations/regions",
    headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
)
regions = response.json()
print(f"Found {len(regions)} regions:", [r['name'] for r in regions])
Expected Response (200 OK):
[
  {
    "id": 123,
    "name": "Cincinnati",
    "builderId": 456,
    "active": true
  }
]

3. Data Requirements

Gather the following information from your builder management system:

  • Division names and external IDs
  • Master Community names and their parent divisions
  • Neighborhood names and their parent master communities
  • Home addresses with neighborhood associations

Step 1: Create Location Hierarchy

Hierarchy Structure: 
Region (activated by Builder Backed)
  └── Division (you create)
      └── Master Community (you create)
          └── Neighborhood (you create)
              └── Homes (Step 2)

1.1 Create Divisions

Divisions are the top-level organizational unit under regions. Create one or more divisions for your builder organization.

POST Create Division

/api/v2/locations/divisions

Try in Swagger UI
Required Fields:
Field Type Description Example
externalId string Your unique ID for this division "DIV_001"
name string Display name of the division "Cincinnati"
regionName string Name of the parent region (from GET /regions) "Cincinnati"
Optional Fields:
  • displayName - Alternative display name
  • abbreviatedName - Short code (e.g., "CI")
Example Request:
{
  "externalId": "DIV_001",
  "name": "Cincinnati Division",
  "displayName": "Cincinnati",
  "abbreviatedName": "CI",
  "regionName": "Cincinnati"
}
import requests

url = "https://api-stage.builderbacked.com/api/v2/locations/divisions"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
division_data = {
    "externalId": "DIV_001",
    "name": "Cincinnati Division",
    "regionName": "Cincinnati"
}

response = requests.post(url, headers=headers, json=division_data)
if response.status_code == 200:
    division = response.json()
    print(f"✓ Created division: {division['name']} (ID: {division['id']})")
else:
    print(f"✗ Error: {response.json()}")
curl -X POST "https://api-stage.builderbacked.com/api/v2/locations/divisions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "DIV_001",
    "name": "Cincinnati Division",
    "regionName": "Cincinnati"
  }'
Success Response (200 OK):
{
  "id": 789,
  "externalId": "DIV_001",
  "name": "Cincinnati Division",
  "displayName": "Cincinnati",
  "abbreviatedName": "CI",
  "builderId": 456,
  "active": true
}

1.2 Create Master Communities

Master Communities sit under divisions and group related neighborhoods together.

POST Create Master Community

/api/v2/locations/master-communities

Try in Swagger UI
Required Fields:
Field Type Description Example
externalId string Your unique ID for this master community "MC_001"
name string Display name of the master community "Shaker Run"
divisionExternalId string External ID of the parent division "DIV_001"
Example Request:
{
  "externalId": "MC_001",
  "name": "Shaker Run",
  "displayName": "Shaker Run Community",
  "abbreviatedName": "SR",
  "divisionExternalId": "DIV_001"
}
url = "https://api-stage.builderbacked.com/api/v2/locations/master-communities"
mc_data = {
    "externalId": "MC_001",
    "name": "Shaker Run",
    "divisionExternalId": "DIV_001"  # References division from step 1.1
}

response = requests.post(url, headers=headers, json=mc_data)
if response.status_code == 200:
    mc = response.json()
    print(f"✓ Created master community: {mc['name']}")
    print(f"  └─ Under division: {mc['divisionExternalId']}")

1.3 Create Neighborhoods

Neighborhoods are the lowest level in the hierarchy and directly contain homes.

POST Create Neighborhood

/api/v2/locations/neighborhoods

Try in Swagger UI
Required Fields:
Field Type Description Example
externalId string Your unique ID for this neighborhood "NH_001"
name string Display name of the neighborhood "Lakeside"
masterCommunityExternalId string External ID of the parent master community "MC_001"
Example Request:
{
  "externalId": "NH_001",
  "name": "Lakeside",
  "displayName": "Lakeside Neighborhood",
  "abbreviatedName": "LS",
  "masterCommunityExternalId": "MC_001"
}
url = "https://api-stage.builderbacked.com/api/v2/locations/neighborhoods"
neighborhood_data = {
    "externalId": "NH_001",
    "name": "Lakeside",
    "masterCommunityExternalId": "MC_001"  # References MC from step 1.2
}

response = requests.post(url, headers=headers, json=neighborhood_data)
if response.status_code == 200:
    nh = response.json()
    print(f"✓ Created neighborhood: {nh['name']}")
    print(f"  └─ Under master community: {nh['masterCommunityExternalId']}")

Verification Checklist

Before proceeding to Step 2, verify you have:

  • ✓ At least one Division created with valid regionName
  • ✓ At least one Master Community linked to a Division
  • ✓ At least one Neighborhood linked to a Master Community
  • ✓ Saved all externalId values for the next step

Step 2: Create Homes & Homeowners

Overview

With your location hierarchy in place, you can now create home records. The system will automatically validate the entire location chain from neighborhood up through division and region.

Automatic Validation:

When you create a home with a neighborhoodExternalId, the API automatically validates:

  • Neighborhood exists and is active
  • Master Community (parent of neighborhood) exists and is active
  • Division (parent of master community) exists and is active
  • Region (parent of division) exists and is active

If any level is missing or inactive, the request will fail with a 404 error.

Create Home

POST Create Home

/api/v2/homes

Try in Swagger UI
Required Fields:
Field Type Description Example
externalId string Your unique ID for this home "HOME_12345"
addressLine1 string Street address "123 Main St"
city string City name "Columbus"
state string State code (2 letters) "OH"
postalCode string ZIP code "43215"
type enum Home type "Single Family" or "Multi Family"
neighborhoodExternalId string External ID of the neighborhood (from Step 1.3) "NH_001"
Optional Fields:
  • addressLine2 - Apartment/unit number
  • marketHome - Boolean flag for market homes (default: false)
  • jobId - Job identifier
  • productCollection - Product line (e.g., "Designer")
  • model - Home model name (e.g., "Preston")
  • closingDate - Actual closing date (ISO 8601 format)
  • scheduledClosingDate - Scheduled closing date (ISO 8601 format)
  • homeowners - Array of homeowner objects (see below)
Example Request (Home Only):
{
  "externalId": "HOME_12345",
  "addressLine1": "123 Main St",
  "city": "Columbus",
  "state": "OH",
  "postalCode": "43215",
  "type": "Single Family",
  "model": "Preston",
  "neighborhoodExternalId": "NH_001"
}
url = "https://api-stage.builderbacked.com/api/v2/homes"
home_data = {
    "externalId": "HOME_12345",
    "addressLine1": "123 Main St",
    "city": "Columbus",
    "state": "OH",
    "postalCode": "43215",
    "type": "Single Family",
    "model": "Preston",
    "neighborhoodExternalId": "NH_001"  # From Step 1.3
}

response = requests.post(url, headers=headers, json=home_data)
if response.status_code == 200:
    home = response.json()
    print(f"✓ Created home: {home['addressLine1']}")
    print(f"  ID: {home['id']}")
    print(f"  External ID: {home['externalId']}")
else:
    print(f"✗ Error: {response.json()}")
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"
  }'

Adding Homeowners (Optional)

You can optionally include homeowners when creating a home by adding a homeowners array to the request.

Homeowner Fields:
Field Type Required Example
email string ✓ Yes "john.smith@email.com"
firstName string Optional "John"
lastName string Optional "Smith"
middleName string Optional "James"
prefix string Optional "Mr."
suffix string Optional "Jr."
Example Request (Home with Homeowners):
{
  "externalId": "HOME_12345",
  "addressLine1": "123 Main St",
  "city": "Columbus",
  "state": "OH",
  "postalCode": "43215",
  "type": "Single Family",
  "neighborhoodExternalId": "NH_001",
  "homeowners": [
    {
      "email": "john.smith@email.com",
      "firstName": "John",
      "lastName": "Smith"
    },
    {
      "email": "jane.smith@email.com",
      "firstName": "Jane",
      "lastName": "Smith"
    }
  ]
}
home_data = {
    "externalId": "HOME_12345",
    "addressLine1": "123 Main St",
    "city": "Columbus",
    "state": "OH",
    "postalCode": "43215",
    "type": "Single Family",
    "neighborhoodExternalId": "NH_001",
    "homeowners": [
        {
            "email": "john.smith@email.com",
            "firstName": "John",
            "lastName": "Smith"
        },
        {
            "email": "jane.smith@email.com",
            "firstName": "Jane",
            "lastName": "Smith"
        }
    ]
}

response = requests.post(url, headers=headers, json=home_data)
if response.status_code == 200:
    home = response.json()
    print(f"✓ Created home with {len(home_data['homeowners'])} homeowners")
Alternative Approach:

You can also add homeowners after creating a home using:

POST /api/v2/homes/{externalHomeId}/users

See the Swagger documentation for details.

Complete Integration Examples

End-to-end examples showing the full integration workflow from region verification to home creation.

Python Complete Example

import requests
from typing import Dict, Any

# Configuration
BASE_URL = "https://api-stage.builderbacked.com"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
HEADERS = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}

def check_regions() -> str:
    """Step 0: Verify regions are activated"""
    response = requests.get(f"{BASE_URL}/api/v2/locations/regions", headers=HEADERS)
    regions = response.json()

    if not regions:
        raise Exception("No regions found! Contact Builder Backed to activate regions.")

    print(f"✓ Found {len(regions)} active region(s)")
    for region in regions:
        print(f"  - {region['name']} (ID: {region['id']})")

    return regions[0]['name']  # Use first region

def create_division(region_name: str) -> Dict[str, Any]:
    """Step 1.1: Create Division"""
    division_data = {
        "externalId": "DIV_DEMO_001",
        "name": "Demo Division",
        "regionName": region_name
    }

    response = requests.post(
        f"{BASE_URL}/api/v2/locations/divisions",
        headers=HEADERS,
        json=division_data
    )

    if response.status_code == 200:
        division = response.json()
        print(f"✓ Created division: {division['name']} (External ID: {division['externalId']})")
        return division
    else:
        raise Exception(f"Failed to create division: {response.json()}")

def create_master_community(division_external_id: str) -> Dict[str, Any]:
    """Step 1.2: Create Master Community"""
    mc_data = {
        "externalId": "MC_DEMO_001",
        "name": "Demo Master Community",
        "divisionExternalId": division_external_id
    }

    response = requests.post(
        f"{BASE_URL}/api/v2/locations/master-communities",
        headers=HEADERS,
        json=mc_data
    )

    if response.status_code == 200:
        mc = response.json()
        print(f"✓ Created master community: {mc['name']} (External ID: {mc['externalId']})")
        return mc
    else:
        raise Exception(f"Failed to create master community: {response.json()}")

def create_neighborhood(mc_external_id: str) -> Dict[str, Any]:
    """Step 1.3: Create Neighborhood"""
    nh_data = {
        "externalId": "NH_DEMO_001",
        "name": "Demo Neighborhood",
        "masterCommunityExternalId": mc_external_id
    }

    response = requests.post(
        f"{BASE_URL}/api/v2/locations/neighborhoods",
        headers=HEADERS,
        json=nh_data
    )

    if response.status_code == 200:
        nh = response.json()
        print(f"✓ Created neighborhood: {nh['name']} (External ID: {nh['externalId']})")
        return nh
    else:
        raise Exception(f"Failed to create neighborhood: {response.json()}")

def create_home(neighborhood_external_id: str) -> Dict[str, Any]:
    """Step 2: Create Home with Homeowners"""
    home_data = {
        "externalId": "HOME_DEMO_001",
        "addressLine1": "456 Demo Street",
        "city": "Columbus",
        "state": "OH",
        "postalCode": "43215",
        "type": "Single Family",
        "model": "Preston",
        "neighborhoodExternalId": neighborhood_external_id,
        "homeowners": [
            {
                "email": "demo.homeowner@example.com",
                "firstName": "Demo",
                "lastName": "Homeowner"
            }
        ]
    }

    response = requests.post(
        f"{BASE_URL}/api/v2/homes",
        headers=HEADERS,
        json=home_data
    )

    if response.status_code == 200:
        home = response.json()
        print(f"✓ Created home: {home['addressLine1']}")
        print(f"  External ID: {home['externalId']}")
        print(f"  Internal ID: {home['id']}")
        return home
    else:
        raise Exception(f"Failed to create home: {response.json()}")

def main():
    """Complete integration workflow"""
    print("=== Builder Backed Integration Demo ===\n")

    try:
        # Step 0: Check regions
        print("Step 0: Checking regions...")
        region_name = check_regions()
        print()

        # Step 1.1: Create Division
        print("Step 1.1: Creating division...")
        division = create_division(region_name)
        print()

        # Step 1.2: Create Master Community
        print("Step 1.2: Creating master community...")
        mc = create_master_community(division['externalId'])
        print()

        # Step 1.3: Create Neighborhood
        print("Step 1.3: Creating neighborhood...")
        nh = create_neighborhood(mc['externalId'])
        print()

        # Step 2: Create Home
        print("Step 2: Creating home...")
        home = create_home(nh['externalId'])
        print()

        print("=== Integration Complete! ===")
        print(f"\nCreated full location hierarchy:")
        print(f"  Region: {region_name}")
        print(f"  └─ Division: {division['name']} ({division['externalId']})")
        print(f"     └─ Master Community: {mc['name']} ({mc['externalId']})")
        print(f"        └─ Neighborhood: {nh['name']} ({nh['externalId']})")
        print(f"           └─ Home: {home['addressLine1']} ({home['externalId']})")

    except Exception as e:
        print(f"\n✗ Error: {e}")
        raise

if __name__ == "__main__":
    main()

Common Errors & Troubleshooting

Location Hierarchy Errors

404 Region Not Found

Error when creating Division: "Region 'Cincinnati' not found"

Cause:

Regions have not been activated by Builder Backed, or the region name is misspelled.

Solution:
  1. Contact Builder Backed support (eric@bebuilderbacked.com) to activate regions for your account
  2. Verify exact region names using GET /api/v2/locations/regions
  3. Ensure region name matches exactly (case-sensitive)
Example Fix: 
// Check available regions first
GET /api/v2/locations/regions

// Use exact region name from response
{
  "regionName": "Cincinnati"  // Must match exactly
}

404 Parent Location Not Found

Error when creating Master Community or Neighborhood: "Division with external ID 'DIV_001' not found"

Cause:

Referenced parent location does not exist or externalId is incorrect.

Solution:
  1. Verify the parent location was created successfully in the previous step
  2. Check the externalId matches exactly (case-sensitive)
  3. Use GET endpoints to list existing locations:
    • GET /api/v2/locations/divisions
    • GET /api/v2/locations/master-communities

409 Duplicate External ID

Error: "A location with external ID 'DIV_001' already exists"

Cause:

You're trying to create a location with an externalId that already exists for your builder.

Solution:
  1. Use a unique externalId for each new location
  2. If updating an existing location, use PUT endpoint instead:
    • PUT /api/v2/locations/divisions
    • PUT /api/v2/locations/master-communities
    • PUT /api/v2/locations/neighborhoods
  3. Query existing locations to check for duplicates

Home Creation Errors

404 Neighborhood Not Found

Error: "Neighborhood with external ID 'NH_001' not found"

Cause:

The neighborhood referenced in neighborhoodExternalId does not exist or is inactive.

Solution:
  1. Verify the neighborhood exists: GET /api/v2/locations/neighborhoods/{externalId}
  2. Check the entire location hierarchy is active (division, master community, neighborhood)
  3. Ensure externalId matches exactly (case-sensitive)

400 Invalid Home Type

Error: "Invalid value for 'type' field"

Cause:

The type field must be exactly "Single Family" or "Multi Family".

Solution: 
{
  "type": "Single Family"  // ✓ Correct
  // "type": "SingleFamily"  ✗ Wrong - no space
  // "type": "single family"  ✗ Wrong - must be capitalized
}

400 Missing Required Fields

Error: "Field 'addressLine1' is required"

Cause:

One or more required fields are missing from the request.

Required Fields for Home:
  • externalId
  • addressLine1
  • city
  • state
  • postalCode
  • type
  • neighborhoodExternalId

400 Invalid Email Format

Error when adding homeowners: "Email address is invalid"

Cause:

Homeowner email does not match valid email format.

Solution: 
{
  "homeowners": [
    {
      "email": "valid@example.com"  // ✓ Correct
      // "email": "invalid-email"  ✗ Wrong
    }
  ]
}

Authentication Errors

401 Unauthorized

Error: "Invalid or missing authentication token"

Cause:

Missing or invalid Authorization header.

Solution: 
// ✓ Correct format
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

// ✗ Common mistakes
Authorization: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...  // Missing "Bearer "
Authorization: Bearer                                      // Missing token

403 Insufficient Permissions

Error: "Token does not have required scope: location.write"

Cause:

Your access token does not include the required OAuth2 scopes.

Required Scopes:
  • location.write - For location hierarchy operations
  • home.write - For home operations
Solution:

Request a new access token with the correct scopes when authenticating via OAuth2 client credentials flow.

Testing Your Integration

Using Swagger UI for Interactive Testing

The Builder Backed Swagger UI provides a hands-on testing environment where you can execute real API calls without writing code.

Open Swagger UI

Step-by-Step Testing Process

1. Authenticate Your Session
  1. Open Swagger UI using the link above
  2. Click the "Authorize" button at the top right
  3. In the OAuth2 authorization dialog:
    • Select the required scopes: location.write and home.write
    • Click "Authorize"
    • Enter your OAuth2 client credentials
  4. Click "Close" when authorized
2. Test Location Hierarchy Creation
  1. Verify Regions:
    • Navigate to Locations → GET /api/v2/locations/regions
    • Click "Try it out" then "Execute"
    • Save the region name from the response
  2. Create Division:
    • Navigate to Locations → POST /api/v2/locations/divisions
    • Click "Try it out"
    • Fill in the request body with your data
    • Click "Execute"
    • Verify response status is 200 and save the externalId
  3. Create Master Community:
    • Navigate to Locations → POST /api/v2/locations/master-communities
    • Use the division's externalId in divisionExternalId
    • Execute and save the master community's externalId
  4. Create Neighborhood:
    • Navigate to Locations → POST /api/v2/locations/neighborhoods
    • Use the master community's externalId in masterCommunityExternalId
    • Execute and save the neighborhood's externalId
3. Test Home Creation
  1. Navigate to Homes → POST /api/v2/homes
  2. Click "Try it out"
  3. Fill in the request body with the required fields
  4. Use the neighborhood's externalId from the previous step
  5. Click "Execute"
  6. Verify the response includes the complete location hierarchy

Validation Checklist

Before Going to Production:

  • ✓ Successfully created at least one complete location hierarchy (region → division → master community → neighborhood)
  • ✓ Successfully created at least one home with valid neighborhoodExternalId
  • ✓ Verified home response includes complete location data (neighborhood, master community, division, region)
  • ✓ Tested with homeowners array (optional but recommended)
  • ✓ Tested error scenarios (invalid IDs, missing fields, etc.)
  • ✓ Verified GET endpoints return created data
  • ✓ Confirmed externalId uniqueness across your system

Sample Test Data

Use this sample data for testing purposes:

Level External ID Name Parent Reference
Division DIV_TEST_001 Test Division regionName: "Cincinnati"
Master Community MC_TEST_001 Test Community divisionExternalId: "DIV_TEST_001"
Neighborhood NH_TEST_001 Test Neighborhood masterCommunityExternalId: "MC_TEST_001"
Home HOME_TEST_001 123 Test Street, Columbus, OH 43215 neighborhoodExternalId: "NH_TEST_001"

Next Steps

Once you've successfully completed testing:

  • Switch to production API endpoints (https://api.builderbacked.com)
  • Update OAuth2 credentials to production credentials
  • Begin bulk import of your actual location and home data
  • Set up error monitoring and logging in your integration
  • Explore additional APIs for documents, builder events, and HOA contacts
Need Help?

Contact Builder Backed support: