Builder Backed V2 API Documentation

Comprehensive tools and APIs for seamless home builder integration with validated location hierarchy

📘

Builder Integration Guide

Step-by-step guide to integrate with Builder Backed APIs. Learn how to set up location hierarchies and create homes.

🏘️

Location Hierarchy

Manage regions, divisions, master communities, and neighborhoods with full validation support.

🏠

Home Management

Create, update, and manage home records with automatic location hierarchy validation.

👥

User Operations

Add and manage homeowners with support for profile images and organization users.

📋

Data Models

Comprehensive data structures and field documentation for all API requests and responses.

⚙️

Interactive Testing

Test API endpoints in real-time with our interactive Swagger UI interface.

Quick Start

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.

Open Builder Integration Guide

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

Homes API (V2)

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

Base URL: https://api-stage.builderbacked.com/api/v2/homes

Get Home by External ID

GET Get Home

/api/v2/homes/{externalId}

Retrieves a single home by its external ID.

Parameters:
  • externalId (path) - Your external ID for the home
Example Request:
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']}")
Success Response (200 OK):
{
  "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"
}
Try in Swagger UI

Create Home

POST Create Home

/api/v2/homes

Creates a new home with automatic location hierarchy validation. The system validates the entire chain from neighborhood to region.

Automatic Validation: When you provide a neighborhoodExternalId, the system automatically:
  • Validates the neighborhood exists and is active
  • Validates the master community (parent) is active
  • Validates the division (grandparent) is active
  • Validates the region (great-grandparent) is active
Required Fields:
Field Type Description
externalId string Your unique ID for this home
addressLine1 string Street address
city string City name
state string State code (2 letters)
postalCode string ZIP code
type enum "Single Family" or "Multi Family"
neighborhoodExternalId string External ID of the neighborhood
Optional Fields:
  • addressLine2 - Apartment/unit number
  • marketHome - Boolean flag (default: false)
  • jobId - Job identifier
  • productCollection - Product line
  • model - Home model name
  • closingDate - Actual closing date (ISO 8601)
  • scheduledClosingDate - Scheduled closing date (ISO 8601)
  • homeowners - Array of homeowner objects
  • homeDetails - Additional key-value pairs (e.g., {"AgreementApprovalDate": "2025-02-24T00:00:00-05:00", "SurveyHomeType": "SF"}). Keys must be previously configured by the Builder Backed Tech Team or via the Builder Admin UI.
Note: If you subscribe to Builder Backed Homeowner Journey capabilities, homes are assigned to Journeys at creation time based on home details matching. All relevant information, including homeDetails key-value pairs, must be sent when the home is first created to ensure correct Journey matching.
Example Request:
{
  "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"
    }
  ],
  "homeDetails": {
    "AgreementApprovalDate": "2025-02-24T00:00:00-05:00",
    "SurveyHomeType": "SF"
  }
}
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"
  }'
Try in Swagger UI

Update Home

PUT Update Home

/api/v2/homes

Updates an existing home. Note: Homeowners cannot be updated via this endpoint - use the dedicated homeowner endpoints below.

Example Request:
{
  "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}")
Try in Swagger UI

Add Homeowner to Home

POST Add Homeowner

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

Adds one or more homeowners to an existing home.

Homeowner Fields:
  • email (required) - Email address
  • firstName - First name
  • lastName - Last name
  • middleName - Middle name
  • prefix - Prefix (e.g., "Mr.", "Mrs.")
  • suffix - Suffix (e.g., "Jr.", "Sr.")
Example Request:
{
  "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}")
Try in Swagger UI

Remove Homeowner from Home

DELETE Remove Homeowner

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

Removes a homeowner from a home by their email address.

Example Request:
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}")
Try in Swagger UI

Users API (V2)

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

Base URL: https://api-stage.builderbacked.com/api/v2/users

Check if User Exists

GET Check User

/api/v2/users/{email}

Checks if a user exists by email address.

Example Request:
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")
Try in Swagger UI

Create Organization User

POST Create User

/api/v2/users

Creates a new organization user (employee) with optional profile image support.

Content-Type: multipart/form-data
Profile Image Requirements:
  • Maximum file size: 10MB
  • Supported formats: JPEG, PNG, GIF, BMP, WebP, SVG
Required Fields:
Field Type Description
externalId string Your external ID (e.g., employee ID)
firstName string First name
lastName string Last name
roleName string User role (e.g., "Field Manager")
Optional Fields:
  • prefix - Name prefix (e.g., "Mr.")
  • middleName - Middle name or initial
  • suffix - Name suffix (e.g., "Jr.")
  • phoneNumber - Phone number
  • email - Email address
  • defaultTimezone - Timezone (EASTERN, CENTRAL, MOUNTAIN, etc.)
  • profileImage - Profile image file
Example Request (Python with file):
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']}")
Try in Swagger UI

Location Hierarchy API

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

Base URL: https://api-stage.builderbacked.com/api/v2/locations
Hierarchy Structure: 
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.

GET Get All Regions

/api/v2/locations/regions

Retrieves all active regions for your builder account.

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

Divisions

Divisions are the first level you create under regions.

POST Create Division

/api/v2/locations/divisions

Creates a new division under a region.

Required Fields:
  • externalId - Your unique ID
  • name - Division name
  • regionName - Name of parent region
Optional Fields:
  • displayName - Alternative display name
  • abbreviatedName - Short code
Example Request:
{
  "externalId": "DIV_001",
  "name": "Cincinnati Division",
  "regionName": "Cincinnati"
}
Try in Swagger UI

GET Get All Divisions

/api/v2/locations/divisions

PUT Update Division

/api/v2/locations/divisions

Master Communities

Master Communities are created under divisions and group related neighborhoods.

POST Create Master Community

/api/v2/locations/master-communities

Required Fields:
  • externalId - Your unique ID
  • name - Master Community name
  • divisionExternalId - External ID of parent division
Example Request:
{
  "externalId": "MC_001",
  "name": "Shaker Run",
  "divisionExternalId": "DIV_001"
}
Try in Swagger UI

Neighborhoods

Neighborhoods are the lowest level and directly contain homes.

POST Create Neighborhood

/api/v2/locations/neighborhoods

Required Fields:
  • externalId - Your unique ID
  • name - Neighborhood name
  • masterCommunityExternalId - External ID of parent master community
Example Request:
{
  "externalId": "NH_001",
  "name": "Lakeside",
  "masterCommunityExternalId": "MC_001"
}
Try in Swagger UI

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

Documents API (V2)

The V2 Documents API provides document management capabilities for homes. Attach documents such as blueprints, warranties, manuals, and other files to homes for homeowner access. All endpoints require OAuth2 authentication with the document.write scope.

Base URL: https://api-stage.builderbacked.com/api/v2/documents
Prerequisite: Document Access Configuration

Before using the Documents API, you must provide Builder Backed with the necessary configuration to access your document storage location. Depending on your document type, this may include:

  • AWS S3: Bucket name, region, and access credentials (IAM role or access keys)
  • External URLs: Any required authentication headers or API keys if your documents are behind authentication
  • Other storage: Connection details and credentials for your document storage system

Contact your Builder Backed representative (support@builderbacked.com) to configure document access before integrating with this API.

Get Documents by External Home ID

GET Get Documents

/api/v2/documents/externalHome/{externalHomeId}

Retrieves all documents associated with a home by its external ID.

Parameters:
  • externalHomeId (path) - Your external ID for the home
Example Request:
curl -X GET "https://api-stage.builderbacked.com/api/v2/documents/externalHome/HOME_12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
import requests

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

response = requests.get(url, headers=headers)
documents = response.json()
for doc in documents:
    print(f"Document: {doc['name']} ({doc['category']})")
Success Response (200 OK):
[
  {
    "id": 12345,
    "externalId": "DOC_001",
    "category": "Warranty",
    "name": "HVAC Warranty",
    "url": "https://example.com/documents/hvac-warranty.pdf",
    "displayStart": "2025-01-01 00:00:00.000",
    "displayEnd": "2035-01-01 00:00:00.000",
    "shareable": true,
    "type": "EXTERNAL_URL",
    "lastModifiedDate": "2025-01-15 10:30:00.000"
  }
]
Try in Swagger UI

Add Documents

POST Add Documents

/api/v2/documents

Adds one or more documents to a home. Documents are grouped by the home's external ID.

Request Body:
Field Type Required Description
externalHomeId string Yes Your external ID for the home
documents array Yes Array of document objects (see Document Model below)
Document Object Fields:
Field Type Required Description
externalId string No Your unique ID for the document (e.g., "DOC_1234")
category string Yes Document category (e.g., "Warranty", "Home", "Manual")
name string Yes Display name of the document (e.g., "HVAC Warranty")
url string Yes URL to the document resource
type enum Yes Document type: EXTERNAL_URL, AWS, SAPPHIRE, or BUILDERBACKED
shareable boolean Yes Whether the document can be shared with service providers
displayStart timestamp No When to start showing the document (format: "YYYY-MM-DD HH:MM:SS.SSS")
displayEnd timestamp No When to stop showing the document (format: "YYYY-MM-DD HH:MM:SS.SSS")
bucket string No S3 bucket name (typically for AWS type documents)
Example Request:
{
  "externalHomeId": "HOME_12345",
  "documents": [
    {
      "externalId": "DOC_001",
      "category": "Warranty",
      "name": "HVAC Warranty",
      "url": "https://example.com/documents/hvac-warranty.pdf",
      "type": "EXTERNAL_URL",
      "shareable": true,
      "displayStart": "2025-01-01 00:00:00.000",
      "displayEnd": "2035-01-01 00:00:00.000"
    },
    {
      "externalId": "DOC_002",
      "category": "Home",
      "name": "Floor Plan",
      "url": "https://example.com/documents/floor-plan.pdf",
      "type": "EXTERNAL_URL",
      "shareable": false
    }
  ]
}
import requests

url = "https://api-stage.builderbacked.com/api/v2/documents"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "externalHomeId": "HOME_12345",
    "documents": [
        {
            "externalId": "DOC_001",
            "category": "Warranty",
            "name": "HVAC Warranty",
            "url": "https://example.com/documents/hvac-warranty.pdf",
            "type": "EXTERNAL_URL",
            "shareable": True
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
documents = response.json()
print(f"Created {len(documents)} document(s)")
curl -X POST "https://api-stage.builderbacked.com/api/v2/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalHomeId": "HOME_12345",
    "documents": [
      {
        "externalId": "DOC_001",
        "category": "Warranty",
        "name": "HVAC Warranty",
        "url": "https://example.com/documents/hvac-warranty.pdf",
        "type": "EXTERNAL_URL",
        "shareable": true
      }
    ]
  }'
Try in Swagger UI

Update Document

PUT Update Document

/api/v2/documents

Updates an existing document by its external ID.

Example Request:
{
  "externalId": "DOC_001",
  "category": "Warranty",
  "name": "HVAC Extended Warranty",
  "url": "https://example.com/documents/hvac-warranty-extended.pdf",
  "type": "EXTERNAL_URL",
  "shareable": true,
  "displayEnd": "2040-01-01 00:00:00.000"
}
curl -X PUT "https://api-stage.builderbacked.com/api/v2/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "DOC_001",
    "category": "Warranty",
    "name": "HVAC Extended Warranty",
    "url": "https://example.com/documents/hvac-warranty-extended.pdf",
    "type": "EXTERNAL_URL",
    "shareable": true
  }'
Try in Swagger UI

Delete Document by External ID

DELETE Delete Document

/api/v2/documents/{externalId}

Deletes a single document by its external ID.

Parameters:
  • externalId (path) - The external ID of the document to delete
Example Request:
curl -X DELETE "https://api-stage.builderbacked.com/api/v2/documents/DOC_001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
import requests

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

response = requests.delete(url, headers=headers)
if response.status_code == 204:
    print("Document deleted successfully")
Success Response:

204 No Content - Document was successfully deleted.

Try in Swagger UI

Delete All Documents for a Home

DELETE Delete by Home

/api/v2/documents/externalHome/{externalHomeId}

Deletes all documents associated with a home.

Parameters:
  • externalHomeId (path) - Your external ID for the home
Example Request:
curl -X DELETE "https://api-stage.builderbacked.com/api/v2/documents/externalHome/HOME_12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Success Response:

204 No Content - All documents for the home were successfully deleted.

Try in Swagger UI

Delete Documents by Category

DELETE Delete by Category

/api/v2/documents/externalHome/{externalHomeId}/category/{category}

Deletes all documents with a specific category for a home.

Parameters:
  • externalHomeId (path) - Your external ID for the home
  • category (path) - The category of documents to delete (e.g., "Warranty")
Example Request:
curl -X DELETE "https://api-stage.builderbacked.com/api/v2/documents/externalHome/HOME_12345/category/Warranty" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Success Response:

204 No Content - All documents in the specified category were successfully deleted.

Try in Swagger UI

Delete Documents by Name

DELETE Delete by Name

/api/v2/documents/externalHome/{externalHomeId}/name/{name}

Deletes all documents with a specific name for a home.

Parameters:
  • externalHomeId (path) - Your external ID for the home
  • name (path) - The name of documents to delete (e.g., "HVAC Warranty")
Example Request:
curl -X DELETE "https://api-stage.builderbacked.com/api/v2/documents/externalHome/HOME_12345/name/HVAC%20Warranty" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Success Response:

204 No Content - All documents with the specified name were successfully deleted.

Try in Swagger UI

Document Types

The type field determines how the document URL is accessed:

  • EXTERNAL_URL - Direct link to an external resource (most common)
  • AWS - Document stored in AWS S3 (requires bucket field)
  • SAPPHIRE - Document stored in Sapphire system
  • BUILDERBACKED - Document stored in Builder Backed system

Common Document Categories

While you can use any category name, here are some common examples:

  • Warranty - Appliance and system warranties
  • Home - General home documents (blueprints, floor plans)
  • Manual - Appliance and system manuals
  • Contract - Purchase agreements and contracts
  • Inspection - Inspection reports
  • HOA - HOA documents and guidelines

Data Models

Home Models

ExternalHomeRequestV3 (Create/Update)

Request model for creating or updating homes.

Field Type Required Description
externalId string ✓ Your external ID for the home
addressLine1 string ✓ Street address line 1
addressLine2 string Street address line 2
city string ✓ City
state string ✓ State code (2 letters)
postalCode string ✓ Postal code
type enum ✓ "Single Family" or "Multi Family"
neighborhoodExternalId string ✓ External ID of neighborhood
marketHome boolean Whether this is a market home
jobId string Job ID
productCollection string Product collection
model string Home model
closingDate datetime Actual closing date (ISO 8601)
scheduledClosingDate datetime Scheduled closing date (ISO 8601)
homeowners array Array of homeowner objects

ExternalHomeResponseV3 (Response)

Response model returned from home operations. Includes all request fields plus:

Field Type Description
id number Internal home ID
fullAddress string Auto-generated full address
regionExternalId string Auto-populated from hierarchy
divisionExternalId string Auto-populated from hierarchy
masterCommunityExternalId string Auto-populated from hierarchy
homeSource enum "BuilderRegistration" or "TargetedRegistration"
status enum "Inactive", "Active", or "Pending"

User/Homeowner Models

HomeUserRequestV2

Model for homeowner information.

Field Type Required Description
email string ✓ Email address (validated)
fullName string Auto-generated full name (response only)
prefix string Name prefix (e.g., "Mr.", "Mrs.")
firstName string First name
middleName string Middle name or initial
lastName string Last name
suffix string Name suffix (e.g., "Jr.", "Sr.")
homeownerType enum Type of homeowner. Allowed values: PRIMARY, SECONDARY, OTHER
defaultHome boolean Whether this is the homeowner's default home

ExternalUserRequest

Model for creating organization users.

Field Type Required Description
externalId string ✓ Your external ID (e.g., employee ID)
firstName string ✓ First name
lastName string ✓ Last name
roleName string ✓ User role
email string Email address
phoneNumber string Phone number
defaultTimezone enum EASTERN, CENTRAL, MOUNTAIN, ARIZONA, PACIFIC, ALASKA, HAWAII

Location Models

Location Request Models

All location requests (Division, Master Community, Neighborhood) share similar fields:

Field Type Required Description
externalId string ✓ Your unique ID
name string ✓ Location name
displayName string Alternative display name
abbreviatedName string Short code
Parent Reference string ✓ Division: regionName
Master Community: divisionExternalId
Neighborhood: masterCommunityExternalId

Document Models

ExternalDocumentRequestV2 (Create Documents)

Request model for adding documents to a home.

Field Type Required Description
externalHomeId string ✓ Your external ID for the home
documents array ✓ Array of Document objects

Document

Model representing a document attached to a home.

Field Type Required Description
externalId string Your unique ID for the document (e.g., "DOC_1234")
category string ✓ Document category (e.g., "Warranty", "Home", "Manual")
name string ✓ Display name of the document (e.g., "HVAC Warranty")
url string ✓ URL to the document resource
type enum ✓ EXTERNAL_URL, AWS, SAPPHIRE, or BUILDERBACKED
shareable boolean ✓ Whether document can be shared with service providers
displayStart timestamp When to start showing the document (format: "YYYY-MM-DD HH:MM:SS.SSS")
displayEnd timestamp When to stop showing the document
bucket string S3 bucket name (required for AWS type)

Document Response

Response model returned from document operations. Includes all request fields plus:

Field Type Description
id number Internal document ID
lastModifiedBy string User who last modified the document
lastModifiedDate timestamp When the document was last modified

DocumentType Enum

Determines how the document URL is accessed:

Value Description
EXTERNAL_URL Direct link to an external resource (most common)
AWS Document stored in AWS S3 (requires bucket field and access configuration)
SAPPHIRE Document stored in Sapphire system
BUILDERBACKED Document stored in Builder Backed system

Error Handling

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

200 OK

Request successful. Response body contains the requested data.

400 Bad Request

Cause: Invalid request body, missing required fields, or validation errors.

Solution: Check the error message for specific field validation issues. Verify all required fields are present and correctly formatted.

401 Unauthorized

Cause: Missing or invalid authentication token.

Solution: Ensure the Authorization header includes a valid Bearer token: Authorization: Bearer YOUR_ACCESS_TOKEN

403 Forbidden

Cause: Token does not have required scopes.

Solution: Verify your access token includes the necessary scopes (e.g., home.write, location.write, user.write, document.write).

404 Not Found

Cause: Resource not found (e.g., home with specified externalId doesn't exist, or referenced parent location doesn't exist).

Solution: Verify the externalId or path parameter is correct. For location hierarchy errors, ensure all parent locations exist and are active.

409 Conflict

Cause: Resource already exists with the given externalId.

Solution: Use a unique externalId, or use PUT endpoint to update the existing resource.

500 Internal Server Error

Cause: Unexpected server error.

Solution: Contact Builder Backed support at support@builderbacked.com with the error details.

API-Specific Errors

Invalid Home Type

Error: "Invalid value for 'type' field"

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

Solution: Use the exact enum values (case-sensitive, with space).

Location Hierarchy Validation Failed

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

Cause: The neighborhood doesn't exist, or one of its parent locations (master community, division, or region) is missing or inactive.

Solution: Verify the complete location hierarchy exists and all levels are active.

Region Not Activated

Error: "Region 'Cincinnati' not found"

Cause: Regions have not been activated by Builder Backed.

Solution: Contact Builder Backed support to activate regions for your account.

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

Builder Integration Guide

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

What's Included

  • Prerequisites: OAuth2 authentication and region activation
  • Step 1: Creating location hierarchies (divisions, master communities, neighborhoods)
  • Step 2: Creating homes and adding homeowners
  • Complete Examples: End-to-end Python code examples
  • Common Errors: Troubleshooting guide with solutions
  • Testing Guide: Swagger UI walkthrough
Open Builder Integration Guide (Opens in new tab)

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

Interactive API Testing

Swagger UI

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

Open Swagger UI

How to Use Swagger UI

Step 1: Authenticate
  1. Click the "Authorize" button at the top right
  2. Select the required scopes: location.write, home.write, user.write, document.write
  3. Enter your OAuth2 client credentials
  4. Click "Authorize" then "Close"
Step 2: Navigate to an Endpoint
  1. Find the API category (Homes, Locations, Users, Documents)
  2. Click on the endpoint you want to test
  3. Click "Try it out"
Step 3: Execute the Request
  1. Fill in the request parameters or body
  2. Click "Execute"
  3. View the response below, including status code and response body

Swagger URL Structure

You can link directly to specific API sections:

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 support@builderbacked.com