API Fundamentals

Overview

The InvestorBase API provides programmatic access to our comprehensive real estate data and investor matching capabilities. It enables developers to integrate powerful market intelligence, property valuations, and buyer discovery features directly into their applications.

Whether you are building a CRM for real estate professional, a property analysis tool, or a lead generation platform, our API gives you the data you need to serve your users.

Base URL: https://api.investorbase.com/functions/v1/

Authentication

Authentication is required for all API requests. You must include your unique API key and a user identifier in the HTTP headers of every request.

Rate Limiting

The API enforces two layers of rate limiting to ensure fair usage and protect service quality.

Per-Minute Rate Limit

A global per-minute limit applies to your entire API key across all endpoints and all users. Every request counts toward this limit regardless of whether it succeeds or fails.

Your per-minute limit is visible in the rate_limit_per_minute field returned by the GET /api-credentials endpoint.

Monthly Usage Limits

Each user under your API key has a monthly request allowance per endpoint, determined by the plans you assign to them via Subscription Management. Key details:

• Per-endpoint: Each endpoint (Autocomplete, Retail Comps, Analytics Search, Analytics Summary, Buyer Search, Investor Comps, Linked Deals) has its own independent monthly limit.
• Stacking: If a user has multiple active subscriptions, their limits are added together.
• Successful requests only: Only requests that return HTTP 200 count toward the monthly limit. Failed requests (4xx, 5xx) do not consume quota.
• Retail Comps & Linked Deals exception: For the Retail Comps and Linked Deals endpoints, only requests that return at least one result count toward the limit. Searches that return zero results are not counted.
• Analytics Search & Analytics Summary: These two endpoints share the same analytics_search_limit value from your plan, but their usage is counted independently. For example, if your plan has an analytics_search_limit of 500, each user gets 500 Analytics Search requests and 500 Analytics Summary requests per month.

Rate Limit Response Headers

All successful responses from the core endpoints include headers to help you track your usage:

Rate Limit Errors

When a rate limit is exceeded, the API returns the appropriate HTTP status code:

Example 429 Response:

{
  "error": "Rate limit exceeded"
}

{
  "error": "Monthly request limit exceeded"
}

API Endpoints

1. Autocomplete

The Autocomplete endpoint is designed to improve address entry and validation. It takes a partial address string and returns a list of matching full addresses along with their geographical coordinates (latitude and longitude).

Use Case: Use this endpoint to implement a "type-ahead" address search bar in your application, ensuring you capture accurate address data before initiating other searches.

Endpoint: POST /autocomplete

Request Body Parameters:

• search_string (string, required): The partial address or location string to search for. Must be at least 3 characters long.

Example Request:

{
  "search_string": "123 Main"
}

Example Response:

Returns an array of matching location objects.

[
  {
    "address": "123 Main St, Charleston, SC 29407",
    "latitude": 33.67,
    "longitude": -81.76
  }
]

2. Retail Comps

The Retail Comps endpoint provides comparable sales data for a specific subject property. It returns details about the subject property itself, a list of comparable recently sold properties ("comps"), and an automated valuation estimate.

Use Case: Essential for determining the After Repair Value (ARV) of a property. Use this to show your users what similar properties in the immediate vicinity are selling for.

Endpoint: POST /retail-comps

Request Body Parameters:

• address (string, required): The full address of the subject property.
• max_radius_miles (number, optional): The maximum distance to search for comps.
• max_days_back (number, optional): How many days back to search for sales history (e.g., 90, 180, 365).
• bedrooms_min / bedrooms_max (number, optional): Filter comps by bedroom count.
• bathrooms_min / bathrooms_max (number, optional): Filter comps by bathroom count.
• living_square_feet_min / living_square_feet_max (number, optional): Filter by square footage.

Example Request:

{
  "address": "6806 19th Rd N, Arlington, VA 22205",
  "max_radius_miles": 2,
  "max_days_back": 90,
  "bedrooms_min": 2,
  "bathrooms_min": 1
}

Example Response:

The response includes the subject property details adn an array of comps.

{
  "subject": {
    "address": "6806 19th Rd N, Arlington, VA 22205",
    "city": "Arlington",
    "state": "VA",
    "zip": "22205",
    "bedrooms": 3,
    "bathrooms": 2,
    "year_built": 1950,
    "living_square_feet": 1500,
    "lot_square_feet": 5000,
    "property_type": "Single Family Residence",
    "last_sale_date": "2020-01-15",
    "last_sale_price": 500000,
    "latitude": 38.88,
    "longitude": -77.14,
    "owner_names": [
      "John Owner",
      "Jane Owner"
    ]
  },
  "comps": [
    {
      "address": "6810 19th Rd N, Arlington, VA 22205",
      "city": "Arlington",
      "state": "VA",
      "zip": "22205",
      "distance": 0.05,
      "last_sale_amount": 510000,
      "last_sale_date": "2023-05-20",
      "bedrooms": 3,
      "bathrooms": 2,
      "year_built": 1952,
      "living_square_feet": 1480,
      "lot_square_feet": 4900,
      "property_type": "Single Family Residence",
      "latitude": 38.881,
      "longitude": -77.141
    }
  ]
}

3. Analytics Search

The Analytics Search endpoint allows you to discover investor activity in a specific area. It returns data about recent flip and rental transactions, distinguishing between "Flippers" and "Landlords".

Use Case: Use this endpoint to identify (investor) buyer activity in a given vicinity for lead underwriting and market insights.

Endpoint: POST /analytics-search

Request Body Parameters:

• latitude (number, required): The latitude of the search center.
• longitude (number, required): The longitude of the search center.
• property_types (array of strings, optional): Filter by property type. Allowed values: ['SFR', 'MFR', 'CONDO', 'MOBILE', 'LAND', 'OTHER']. Defaults to ['SFR'].
• flipper_weight (number, optional): Controls the ratio of flippers to landlords in the results. Accepts a value between 0 and 1. A value of 1 returns only flippers, 0 returns only landlords, and 0.5 (the default) returns an even split.

Example Request:

{
  "latitude": 34.000,
  "longitude": -81.000,
  "property_types": ["SFR"],
  "flipper_weight": 0.7
}

Example Response:

Returns a list of transaction objects.

[
  {
    "buyer_type": "flipper",
    "address": "Investor Way, Columbia, SC 29201",
    "bedrooms": 3,
    "bathrooms": 2,
    "livingsquarefeet": 1500,
    "lotsquarefeet": 6000,
    "propertytype": "Single Family Residence",
    "latitude": 34.012,
    "longitude": -81.008,
    "flip_sale_transaction_date": "2023-06-01",
    "flip_sale_transaction_price": 250000,
    "flip_purchase_transaction_date": "2022-12-01",
    "flip_purchase_transaction_price": 150000,
    "flip_purchase_method": "Cash Purchase",
    "miles_from_subject": 1.2
  },
  {
    "buyer_type": "landlord",
    "address": "Rental Ln, Columbia, SC 29205",
    "bedrooms": 3,
    "bathrooms": 2,
    "livingsquarefeet": 1400,
    "lotsquarefeet": 5500,
    "propertytype": "Single Family Residence",
    "latitude": 34.018,
    "longitude": -81.023,
    "rental_purchase_transaction_date": "2023-03-15",
    "rental_purchase_transaction_price": 180000,
    "rental_purchase_method": "Financed",
    "miles_from_subject": 2.5
  }
]

4. Analytics Summary

The Analytics Summary endpoint returns pre-aggregated market metrics for a given location. It provides flip and rental transaction counts at multiple radii, as well as detailed pricing, price-per-square-foot, ARV, and landlord aggressiveness statistics computed from nearby transactions.

Use Case: Use this endpoint to power lead-grading automations, market snapshot widgets, heatmaps, or quick-glance dashboards that show investor activity density and pricing trends without needing to process individual transaction records.

Endpoint: POST /analytics-summary

Request Body Parameters:

• latitude (number, required): The latitude of the search center.
• longitude (number, required): The longitude of the search center.
• property_types (array of strings, optional): Filter by property type. Allowed values: ['SFR', 'MFR', 'CONDO', 'MOBILE', 'LAND', 'OTHER']. Defaults to ['SFR'].
• lookback_months (integer, optional): Number of months of history to include. Accepts 1 to 60. Defaults to 24.
• metrics_radius_mi (number, optional): Radius in miles used for the detailed buyer metrics. Accepts 0 to 10. Defaults to 2.

Example Request:

{
  "latitude": 34.000,
  "longitude": -81.000,
  "property_types": ["SFR"],
  "lookback_months": 24,
  "metrics_radius_mi": 2
}

Example Response:

Returns a single object with three sections: radius counts, flipper metrics, and landlord metrics.

{
  "radius_counts": {
    "1mi":  { "flips": 5,  "rentals": 8 },
    "2mi":  { "flips": 12, "rentals": 20 },
    "5mi":  { "flips": 45, "rentals": 60 },
    "10mi": { "flips": 100, "rentals": 150 }
  },
  "flipper_metrics": {
    "count": 12,
    "price_avg": 185000,
    "price_low": 155000,
    "price_high": 210000,
    "ppsft_avg": 125,
    "ppsft_low": 105,
    "ppsft_high": 140,
    "arv_pct_avg": 72,
    "arv_pct_low": 65,
    "arv_pct_high": 80
  },
  "landlord_metrics": {
    "count": 20,
    "price_avg": 165000,
    "price_low": 140000,
    "price_high": 195000,
    "ppsft_avg": 110,
    "ppsft_low": 90,
    "ppsft_high": 130,
    "aggressive_purchase_count": 8,
    "moderate_purchase_count": 7,
    "conservative_purchase_count": 5
  }
}

Response Fields:

• radius_counts: Transaction counts within 1, 2, 5, and 10 mile radii. flips = flip transactions, rentals = rental acquisitions.
• flipper_metrics: Aggregated stats from flip transactions within metrics_radius_mi. price_low/price_high represent the middle-third range. arv_pct_* is the percentage of After-Repair Value paid by flippers.
• landlord_metrics: Aggregated stats from rental acquisitions within metrics_radius_mi. The *_purchase_count fields reflect the 1% Rule meter—aggressive means landlords paid higher prices relative to expected rental revenue, conservative means lower prices.

5. Buyer Search

The Buyer Search endpoint is the core of our investor matching capability. It functions similarly to the Analytics Search but includes detailed contact information and identity for the buyers found.

Use Case: Use this to provide your users with actionable leads—investors who are actively buying in their target area.

Endpoint: POST /buyer-search

Request Body Parameters:

• latitude (number, required): The latitude of the search center.
• longitude (number, required): The longitude of the search center.
• property_types (array of strings, optional): Filter by property type. Allowed values: ['SFR', 'MFR', 'CONDO', 'MOBILE', 'LAND', 'OTHER']. Defaults to ['SFR'].
• flipper_weight (number, optional): Controls the ratio of flippers to landlords in the results. Accepts a value between 0 and 1. A value of 1 returns only flippers, 0 returns only landlords, and 0.5 (the default) returns an even split.
• async (boolean, optional): If true, the request returns immediately with a search_id and processes in the background. Defaults to false (synchronous).
• webhook_url (string, optional): A URL to receive a POST request when the search completes. Works in both sync and async modes.
• webhook_secret (string, optional): A secret value that will be included as an x-webhook-secret header on webhook notifications. Use this to verify that incoming webhooks originated from InvestorBase.
• results_in_webhook (boolean, optional): If true, the webhook payload will include the full array of results. Defaults to false.

Example Request (Synchronous):

{
  "latitude": 34.000,
  "longitude": -81.000
}

Example Response (Synchronous):

Returns an array of buyer profiles with contact details.

[
  {
    "buyer_first_name": "John",
    "buyer_last_name": "Doe",
    "buyer_entity_name": "JD Properties LLC",
    "buyer_phone_number": 8435550123,
    "buyer_email": "john@example.com",
    "buyer_type": "flipper",
    "address": "123 Investor Way",
    "bedrooms": 3,
    "bathrooms": 2,
    "livingsquarefeet": 1500,
    "lotsquarefeet": 6000,
    "propertytype": "Single Family Residence",
    "latitude": 34.01,
    "longitude": -81.01,
    "flip_sale_transaction_date": "2023-06-01",
    "flip_sale_transaction_price": 250000,
    "flip_purchase_transaction_date": "2022-12-01",
    "flip_purchase_transaction_price": 150000,
    "flip_purchase_method": "Financed",
    "miles_from_subject": 1.2
  }
]

Example Request (Asynchronous):

{
  "latitude": 34.000,
  "longitude": -81.000,
  "async": true,
  "webhook_url": "https://your-api.com/webhooks/investorbase",
  "webhook_secret": "your-secret-value"
}

Example Response (Asynchronous):

Returns HTTP 202 Accepted.

{
  "search_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}

5a. Retrieve Search Results

If you use the async option, you can poll this endpoint to check the status and retrieve results.

Endpoint: GET /buyer-search

Query Parameters:

• search_id (string, required): The UUID returned from the async POST request.

Example Response:

[
  {
    "buyer_first_name": "John",
    "buyer_last_name": "Doe",
    "buyer_entity_name": "JD Properties LLC",
    "buyer_phone_number": 8435550123,
    "buyer_email": "john@example.com",
    "buyer_type": "flipper",
    "address": "123 Investor Way",
    "bedrooms": 3,
    "bathrooms": 2,
    "livingsquarefeet": 1500,
    "lotsquarefeet": 6000,
    "propertytype": "Single Family Residence",
    "latitude": 34.01,
    "longitude": -81.01,
    "flip_sale_transaction_date": "2023-06-01",
    "flip_sale_transaction_price": 250000,
    "flip_purchase_transaction_date": "2022-12-01",
    "flip_purchase_transaction_price": 150000,
    "flip_purchase_method": "Cash Purchase",
    "miles_from_subject": 1.2
  }
]

5b. Webhook Notification

If you provide a webhook_url, we will send a POST request to that URL when the search completes (or fails).

Headers:

• Content-Type: application/json
• x-webhook-secret: Your webhook_secret value, if one was provided in the original request. Use this to verify the authenticity of incoming webhooks.

Payload:

{
  "search_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "results": [ ... ] // Only included if results_in_webhook is true
}

6. Investor Comps

The Investor Comps endpoint searches for "investor-grade" comparable transactions—specifically flips and rental acquisitions—and ranks them based on their similarity to a subject property.

Use Case: This helps users determine what investors specifically are paying for properties in the area, which often differs from retail market value. The ranking algorithm prioritizes properties that are most similar in size, location, and utility.

Endpoint: POST /investor-comps

Request Body Parameters:

• latitude (number, required): Center point for the search.
• longitude (number, required): Center point for the search.
• property_types (array of strings, optional): Filter by property type. Allowed values: ['SFR', 'MFR', 'CONDO', 'MOBILE', 'LAND', 'OTHER']. Defaults to ['SFR'].
• subject_property_details (object, optional): details used for the ranking algorithm.
  • bedrooms (number)
  • bathrooms (number)
  • square_feet (number)

Example Request:

{
  "latitude": 34.0522, 
  "longitude": -81.0437,
  "property_types": ["SFR"],
  "subject_property_details": {
    "bedrooms": 3,
    "bathrooms": 2,
    "square_feet": 1500,
  }
}

Example Response:

Returns a ranked list of investor transactions.

[
  {
    "rank": 1,
    "pricePerSqFt": 150,
    "buyer_type": "flipper",
    "address": "789 Flip St",
    "bedrooms": 3,
    "bathrooms": 2,
    "livingsquarefeet": 1450,
    "lotsquarefeet": 5000,
    "propertytype": "Single Family Residence",
    "latitude": 34.06,
    "longitude": -81.05,
    "flip_purchase_transaction_date": "2023-01-15",
    "flip_purchase_transaction_price": 217500,
    "miles_from_subject": 0.5
  },
  {
    "rank": 2,
    "pricePerSqFt": 145,
    "buyer_type": "landlord",
    "address": "101 Rental Ave",
    "bedrooms": 3,
    "bathrooms": 1.5,
    "livingsquarefeet": 1400,
    "lotsquarefeet": 4800,
    "propertytype": "Single Family Residence",
    "latitude": 34.07,
    "longitude": -81.06,
    "rental_purchase_transaction_date": "2023-02-20",
    "rental_purchase_transaction_price": 203000,
    "miles_from_subject": 0.8
  }
]

7. Linked Deals

The Linked Deals endpoint returns a summary of all transactions (flips and rentals) and up to 250 detailed property records linked to a specific buyer, identified by either their entity name or mailing address. It provides aggregated portfolio statistics alongside the individual deal records.

Use Case: Use this endpoint to build buyer profile pages, underwrite a specific investor's track record, or power "see all deals by this buyer" drill-downs in your application.

Endpoint: POST /linked-deals

Request Body Parameters:

• search_string (string, required): The buyer's entity name (e.g., "JD Properties, LLC") or their full mailing address as a single string (e.g., "123 Main St, Miami, FL 33101").
• search_state (string, conditionally required): A two-letter US state code (e.g., "FL"). Required when is_entity_name is true or omitted.
• is_entity_name (boolean, optional): Set to true (default) if search_string is an entity/owner name, or false if it is a mailing address.
• strict_matches_only (boolean, optional): When true (default), only matches on the provided search dimension. When false, the API expands search scope to return a broader set of linked deals, with the tradeoff being higher risk of false positives.

Example Request (Entity Name):

{
  "search_string": "JD Properties, LLC",
  "search_state": "FL",
  "is_entity_name": true,
  "strict_matches_only": false
}

Example Request (Mailing Address):

{
  "search_string": "123 Main St, Miami, FL 33101",
  "is_entity_name": false,
  "strict_matches_only": true
}

Example Response:

Returns an object with aggregated metadata and a results array of up to 250 deal records, sorted by most recent sale date.

{
  "metadata": {
    "rental_count": 8,
    "flip_count": 3,
    "total_deals": 11,
    "main_property_type": "Single Family Residence",
    "estimated_portfolio_value": 1850000,
    "average_flip_duration": 142,
    "average_purchase_arv_percent": 72,
    "average_purchase_price": 195000,
    "average_flip_gross_profit": 55000
  },
  "results": [
    {
      "id": 123456,
      "buyernames": "JD Properties LLC",
      "sellernames": "Jane Smith",
      "address": {
        "street": "456 Oak Ave",
        "city": "Miami",
        "state": "FL",
        "zip": "33101"
      },
      "latitude": 25.76,
      "longitude": -80.19,
      "bedrooms": 3,
      "bathrooms": 2,
      "livingsquarefeet": 1500,
      "lotsquarefeet": 6000,
      "unitscount": 1,
      "yearbuilt": 1985,
      "propertytype": "Single Family Residence",
      "estimatedvalue": 320000,
      "equitypercent": 45.5,
      "deal_type": "rental"
    }
  ]
}

Response Fields:

• metadata: Aggregated statistics across all linked deals.
  • rental_count / flip_count / total_deals: Deal counts by type.
  • main_property_type: Most common property type across the buyer's deals.
  • estimated_portfolio_value: Sum of estimated values for all rental properties.
  • average_flip_duration: Average number of days between purchase and sale for flips.
  • average_purchase_arv_percent: Average percentage of ARV paid by the buyer on flips.
  • average_purchase_price: Average purchase price across all deals.
  • average_flip_gross_profit: Average gross profit (sale price minus purchase price) on flips.
• results: Array of individual deal records (max 250). Each includes property details, transaction history, and a deal_type of either "rental" or "flip".

Account Management

These endpoints allow you to programmatically manage users and subscriptions within your InvestorBase account. This is particularly useful for platforms that need to provision access for their own customers.

8. API Account Info

The Credentials endpoint allows you to retrieve information about your API account, including your rate limits and the plans available for you to assign to your users.

Endpoint: GET /api-credentials

Example Response:

{
  "account_name": "Acme Corp",
  "account_contact_email": "admin@acmecorp.com",
  "active": true,
  "rate_limit_per_minute": 1000,
  "authorized_endpoints": ["autocomplete", "retail_comps", "analytics_search", "analytics_summary", "buyer_search", "investor_comps", "linked_deals"],
  "available_plans": [
    {
      "plan_id": "plan_123",
      "plan_name": "Pro Plan",
      "monthly_price_usd": 99,
      "autocomplete_limit": 1000,
      "analytics_search_limit": 500,
      "buyer_search_limit": 100,
      "investor_comps_limit": 200,
      "retail_comps_limit": 200,
      "linked_deals_limit": 200
    }
  ]
}

Plan Fields:

• analytics_search_limit applies to both the Analytics Search and Analytics Summary endpoints (counted independently per endpoint).
• All other limit fields apply to their respective endpoint.

9. User Management

The Users endpoint allows you to create, manage, and monitor the end-users of your application who are consuming InvestorBase data.

Endpoint: /api-users

Create User

Method: POST

Request Body Parameters:

• user_id (string, required): Your unique identifier for the user.
• active (boolean, optional): Whether the user is active. Defaults to true.

Example Request:

{
  "user_id": "user_555"
}

Update User Status

Method: PATCH

Request Body Parameters:

• user_id (string, required): The unique identifier of the user.
• active (boolean, required): Set to false to deactivate the user. Note: Deactivating a user will automatically deactivate all their subscriptions.

Example Request:

{
  "user_id": "user_555",
  "active": false
}

Get User Details & Usage

Method: GET

Query Parameters:

• user_id (string, required): The unique identifier of the user.

Example Response:

Returns the user's status, active subscriptions, and usage counts for the current period.

{
  "user_id": "user_555",
  "created_at": "2023-01-01T12:00:00Z",
  "active": true,
  "subscriptions": [
    {
      "id": "sub_789",
      "plan_id": "plan_123",
      "active": true,
      "created_at": "2023-01-01T12:00:00Z"
    }
  ],
  "current_period_usage": {
    "buyer_search": 45,
    "retail_comps": 12
  }
}

10. Subscription Management

The Subscriptions endpoint allows you to assign plans to your users and manage their access.

Endpoint: /api-user-subscriptions

Create Subscription

Method: POST

Request Body Parameters:

• user_id (string, required): The unique identifier of the user.
• plan_id (string, required): The ID of the plan to assign (retrieved from /api-credentials).

Example Request:

{
  "user_id": "user_555",
  "plan_id": "plan_123"
}

Update Subscription Status

Method: PATCH

Request Body Parameters:

• subscription_id (string, required): The ID of the subscription to update.
• active (boolean, required): true to reactivate, false to deactivate.

Example Request:

{
  "subscription_id": "sub_789",
  "active": false
}

Best Practices

1. Validate Addresses First: Always use the /autocomplete endpoint to get precise coordinates before calling search endpoints. This ensures you are searching the correct location.
2. Monitor Rate Limits: Check the X-RateLimit-Remaining and X-Monthly-Remaining response headers to track your usage. Implement client-side throttling or backoff logic to avoid 429 responses during bursts of activity.
3. Handle 429 Responses Gracefully: If you receive a 429 Too Many Requests response, wait before retrying. For per-minute limits, waiting 60 seconds is sufficient. For monthly limits, check the user's remaining quota via GET /api-users.
4. Security: Proxy your API requests through your own backend server. Never embed your x-api-key directly in a frontend application.

Data Dictionary

Below is a reference for common fields found in our response objects.

Buyer & Transaction Information

Property Details

Property Type Mappings

The following table provides examples of how detailed property types map to the simplified property_type codes used in the Search endpoints.