Buyer Search API

Overview

The InvestorBase API provides programmatic access to our buyer search pipeline and results, allowing developers to integrate powerful investor matching capabilities into their applications. This guide provides everything you need to start using the InvestorBase API to perform buyer searches, retrieve search results, and manage your integration with our platform.

The root URL for the API is https://api.investorbase.com/v1/.

Note: Always use HTTPS when connecting to the InvestorBase API. HTTP requests will be rejected.

Authentication

To use the InvestorBase API, you need an API key. Include this key in the x-api-key header for all API requests.

Keep your API key secure and never share it publicly. If you believe your key has been compromised, contact us immediately for a replacement.

API Structure

The InvestorBase API follows REST conventions:

Resources are represented by nouns like search and results.
Actions are represented by HTTP methods (POST, GET).
Responses use the JSON content type.

API Endpoints

1. Initiate Buyer Search

Initiates a buyer search based on the provided address and parameters.

POST /v1/search

Headers:

x-api-key: Your API key
Content-Type: application/json

Request Body:

{
  "address": "123 Main St, Anytown, US 12345",
  "userId": "user123",
  "notifyUrl": "https://your-webhook-endpoint.com/notify",
  "targetResultCount": 30,
  "flipperWeight": 0.5
}

address: The property address to search for buyers
userId: Your internal user identifier
notifyUrl (optional): Webhook URL for receiving search completion notifications
targetResultCount (optional): Desired number of results (default: 30, max: 500)
flipperWeight (optional): Proportion of the results that are desired to be flippers (with the rest being landlords). For example: set this to 1 if you only want flippers. Set this to 0 if you only want landlords. (default: 0.5, range: [0, 1])

Note: The number of buyers returned can be less than targetResultCount.

Response:

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "parsedAddress": "123 Main St, Anytown, US 12345",
  "latitude": 40.7128,
  "longitude": -74.0060
}

searchId: Unique identifier for the search, used to retrieve results later
parsedAddress: The standardized address parsed from your input
latitude and longitude: Coordinates of the searched property

2. Retrieve Search Results

Fetches the results of a buyer search associated with a specific search ID.

GET /v1/results

Headers:

x-api-key: Your API key
search-id: The search ID returned from the initial search request

Response:

Returns an array of buyer results, including details such as:

{
  "data": [
    {
      "buyer_id": "b12345",
      "buyer_first_name": "John",
      "buyer_last_name": "Doe",
      "buyer_address": "456 Elm St",
      "buyer_city": "Othertown",
      "buyer_state": "ST",
      "buyer_zip": "67890",
      "full_address": "123 Main St, Anytown, US 12345",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "miles_from_subject": 1.5,
      "estimated_value": 250000,
      "buyer_type": "flipper",
      "smart_match_rank": 1
      // Additional buyer and property details...
    },
    // More buyers...
  ]
}

Error Responses:

400 Bad Request: If apiKey or searchId is missing
404 Not Found: If no completed search is found for the given searchId or if no buyers are found for that search

Always fetch the latest data from this endpoint when displaying buyer information. Search results must not be stored externally.

Webhook Notifications

If you provide a notifyUrl when initiating a search, you'll receive a POST request to that URL when the search is complete. The payload will include the searchId and a status indicating if buyers were successfully found:

{
  "searchId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "complete" or "no buyers found"
}

Best Practices

Use HTTPS: Always use HTTPS for all API requests to ensure data security.
Handle rate limits: Implement proper rate limiting in your application to avoid exceeding our API limits.
Data freshness: Always fetch the latest data from our API when displaying buyer information to ensure compliance and data accuracy.

API Limits

Rate limit: 100 requests per second
Monthly limit: 100,000 requests per month

If you need adjusted limits, please contact us at developer@investorbase.com.

Data Dictionary

Below is detailed information about the fields returned by the InvestorBase API. Empty/falsy fields are returned as null.

Buyer Information

Field Name	Type	Description
`buyer_id`	Integer	Unique identifier for the buyer that is also tied to their rental or flipped property
`buyer_first_name`	String	First name of the buyer
`buyer_last_name`	String	Last name of the buyer
`buyer_address`	String	Mailing address of the buyer
`buyer_city`	String	City of the buyer's mailing address
`buyer_state`	String	State of the buyer's mailing address
`buyer_zip`	String	ZIP code of the buyer's mailing address
`buyer_type`	String	Type of buyer (e.g., 'flipper' or 'landlord')
`linked_deal_count`	Integer	Number of related deals (flip or rental purchase transactions) that were linked to that buyer from the search

Details of the Rental or Flipped Property

Field Name	Type	Description
`full_address`	String	Complete address of the property
`address`	String	Street address of the property
`city`	String	City where the property is located
`state`	String	State where the property is located
`zip`	String	ZIP code of the property
`county`	String	County where the property is located
`fips`	Integer	Federal Information Processing Standard (FIPS) code for the property's location
`latitude`	Float	Latitude coordinate of the property
`longitude`	Float	Longitude coordinate of the property
`subdivision`	String	Subdivision name, if applicable
`property_use`	String	Current use of the property
`apn`	String	Assessor's Parcel Number
`lot_acres`	Float	Size of the lot in acres
`land_use`	String	Zoning or land use classification
`flood_zone`	String	Flood zone designation
`year_built`	Integer	Year the property was built
`living_square_feet`	Integer	Living area of the property in square feet
`bedrooms`	Integer	Number of bedrooms
`bathrooms`	Float	Number of bathrooms

Valuation and Financial Information

Field Name	Type	Description
`assessed_improvement_value`	Float	Assessed value of the building and improvements on the property
`assessed_land_value`	Float	Assessed value of the land
`estimated_equity`	Float	Estimated current owner's equity in the property
`estimated_value`	Float	Estimated current owner's total value of the property
`cash_buyer`	Boolean	Indicates if the buyer made this purchase without financing

Transaction History

Field Name	Type	Description
`sale_date1`	Date	Date of the most recent sale (YYYY-MM-DD format)
`sale_price1`	Float	Price of the most recent sale
`buyer_names1`	String	Names of buyers in the most recent sale
`transaction_type1`	String	Type of the most recent transaction
`sale_date2`	Date	Date of the second most recent sale (YYYY-MM-DD format)
`sale_price2`	Float	Price of the second most recent sale
`buyer_names2`	String	Names of buyers in the second most recent sale
`seller_names2`	String	Names of sellers in the second most recent sale
`transaction_type2`	String	Type of the second most recent transaction

Contact Information

Field Name	Type	Description
`wireless_1`	String	Primary wireless phone number
`wireless_2`	String	Secondary wireless phone number
`wireless_3`	String	Tertiary wireless phone number
`wireless_4`	String	Quaternary wireless phone number
`landline_1`	String	Primary landline phone number
`landline_2`	String	Secondary landline phone number
`skiptrace_result_first_name`	String	First name of the skiptrace match
`skiptrace_result_last_name`	String	Last name of the skiptrace match
`email_1`	String	Primary email address
`email_2`	String	Secondary email address
`email_3`	String	Tertiary email address

SmartMatch Information

Field Name	Type	Description
`smart_match`	Boolean	Indicates if this is considered a smart match
`miles_from_subject`	Float	Distance from the searched property in miles (rounded to 2 decimal places)
`smart_match_rank`	Integer	Ranking of the match in the smart match algorithm (1 being best match)

Additional Features

For any questions, feature requests, or to discuss custom solutions, please don't hesitate to reach out to our developer support team at developer@investorbase.com.

Usage of the InvestorBase API falls under our Terms of Use and Privacy Policy.