Partner API Documentation

Page Contents

  • Endpoints
  • Error Responses

    • Endpoints

    Overview

    The Partner API has the following endpoints:

    All paths above should be appended to the url below.

    Base URL

    https://trubase-api.rg-infra.com/api

    This documentation is for developers looking to integrate with TruBase's Partner API.

    POST /api/agent

    Overview

    This endpoint processes various combinations of agent data, aiming to consolidate information that might come from different MLS Boards, potentially identifying the same agent.

    You can also use this endpoint to validate whether or not you have the correct tb_agent_id.

    Request parameters:

    • tb_agent_id (string, optional): The Agent's TB Agent IDentifier.
    • state (string, optional): The state where the agent is licensed.
    • agent_first_name (string, optional): The first name of the agent.
    • agent_last_name (string, optional): The last name of the agent.
    • agent_legal_name (string, optional): The legal name of the agent.
    • agent_email (string, optional): The email address of the agent.
    • agent_phone (string, optional): The 10-digit phone number of the agent. Use only numerics.
    • agent_mls_id (string, optional): An agent MLS ID for any MLS Board that they have a listing.
    • agent_license_number (string, optional): The agent's license number.

    Request options:

    There are 2 options for making the request. The more information you provide, the better your match will be:

    • Option 1:
      • tb_agent_id
    • Option 2:
      • state*
      • plus your selection of 3 or more of the following:
        • agent_first_name
        • agent_last_name
        • agent_legal_name
        • agent_email
        • agent_phone
        • agent_mls_id
        • agent_license_number

    Agent API Request Example: 

    
# Bash
#!/bin/bash

curl --location 'https://trubase-api.rg-infra.com/api/agent'
--header 'Authorization: Token 1234567890123456789012345678901234567890'
--header 'Content-Type: application/json'
--data '
    {
        "agent_license_number": "12354678",
        "state":  "NY"
    }
'

    Agent API Response Example: 

    
{
    "timestamp": "2024-04-17T07:42:29.696228+00:00Z",
    "response_form_version": "0.10.0",
    "query_status": "success",
    "message": ["Agent found"],
    "matched_fields": ["agent_email, agent_phone"],
    "score": "88",
    "body": {
        "agent_name": "Jane Ponda",
        "state": "NY",
        "tb_agent_id": "01234567-89ab-cdef-0123-456789000111",
        "agent_mls_ids": [
            "0541848JP",
        ],
        "agent_phones": ["212-111-3333"],
        "agent_emails": ["jponda1@kw.com"],
    }
}

    POST /api/agent/listings

    Overview

    This endpoint provides a facility to query for the successful transaction(s) by agents. The endpoint takes a list of request parameters with agents key, and will return the list of transaction(s) closed by the agent(s) for the last months.

    You can also use this endpoint to validate whether or not you have the correct tb_agent_id.

    Request parameters:

    • tb_agent_id (string, required): The Agent's TB Agent Identifier
    • state (string, required): The state for which you want to retrieve listings e.g., "SC."
    • time_period (string, required): The time period for which you wish to get closed listings, in months, 12, 24, or 36 months.
    • listing_side (string, not required): The side of the listing that the agent wishes to see stats for. Options: list, buy, all. If a side is not selected, then all listings will be returned.

    Agent Listings API Request Example: 

    
# Bash
#!/bin/bash

curl --location 'https://trubase-api.rg-infra.com/api/agent/listings'
--header 'Authorization: Token 1234567890123456789012345678901234567890'
--header 'Content-Type: application/json'
--data '
    {
        "agents":[
        {
           "tb_agent_id": "01234567-89ab-cdef-0123-456789000111",
           "state": "NY",
           "time_period": "36",
           "listing_side": "list"
        },
        {
           "tb_agent_id":"01234567-89ab-cdef-0123-456789000222",
           "state": "TX",
           "time_period": "36",
           "listing_side": "list"

        }
     ]
    }
'

    Agent Listings API Response Example: 

                
{
    "timestamp": "2024-04-17T07:42:29.696228+00:00Z",
    "response_form_version": "0.10.0",
    "query_status": "success",
    "message": ["Agent listings found"],
    "body": [
        {
        "tb_agent": "Jane Ponda",
        "tb_agent_id": "01234567-89ab-cdef-0123-456789000111",
        "state": "NY",
        "listings": {
            "listing_address": {
            "street_number": "100",
            "street_name": "Lonely St",
            "city": "Albany",
            "county": "Albany",
            "state": "NY",
            "zip_code": "12210"
            },
            "apn": "012-345-678",
            "fips": "36001",
            "list_side_agent_name": "Jane Ponda",
            "co_list_side_agent_name": "Donald Beagan",
            "buy_side_agent_name": "Richard Bixon",
            "list_side_agent_mls_id": "456456",
            "co_list_side_agent_mls_id": null,
            "buy_side_agent_mls_id": null,
            "close_date": "2022-07-15",
            "list_date": "2022-06-01",
            "pending_date": null,
            "list_price": 299999,
            "sold_price": 305000,
            "mls_listing_id": "ML12345678",
            "seller_name": "NICHAEL GEORGE TR",
            "buyer_name": "PARTON, POLLY"
        }
        },
        {
        "tb_agent": "Tina Simone",
        "tb_agent_id": "01234567-89ab-cdef-0123-456789000222",
        "state": "TX",
        "listings": {
            "listing_address": {
            "street_number": "123",
            "street_name": "Maple Ln",
            "city": "Austin",
            "county": "Travis",
            "state": "TX",
            "zip_code": "78702"
            },
            "apn": "234-456-678",
            "fips": "48453",
            "list_side_agent_name": "Tina Simone",
            "co_list_side_agent_name": "Sunday Odams",
            "buy_side_agent_name": "Flint Westwood",
            "list_side_agent_mls_id": "123456",
            "co_list_side_agent_mls_id": "789012",
            "buy_side_agent_mls_id": "345678",
            "close_date": "2023-10-30",
            "list_date": "2023-09-15",
            "pending_date": null,
            "list_price": 425000,
            "sold_price": 430000,
            "mls_listing_id": "T9876543",
            "seller_name": "WACKMAN JENE",
            "buyer_name": "FAMILL, MARK"
        }
        }
    ]

    }

    POST /api/agent/locations

    Overview

    This endpoint takes the agent's TB Agent ID and returns the locations such as zip codes, cities, and counties that the agent has closed listings in to help with the generation of agent stats.

    You can also use this endpoint to validate whether or not you have the correct tb_agent_id.

    Request parameters:

    • tb_agent_id (string): The Agent's TB Agent Identifier

    Agent Locations API Request Example: 

    
# Bash
#!/bin/bash

curl --location 'https://trubase-api.rg-infra.com/api/agent/locations'
--header 'Authorization: Token 1234567890123456789012345678901234567890'
--header 'Content-Type: application/json'
--data '
    {
        "tb_agent_id": "01234567-89ab-cdef-0123-456789000333"
    }
'

    Agent Locations API Response Example: 

    
{
    "timestamp": "2024-04-17T07:42:29.696228+00:00Z",
    "response_form_version": "0.10.0",
    "query_status": "success",
    "message": ["Agent locations found"],
    "body": {
        "agent_name": "Cary Brant",
        "tb_agent_id": "01234567-89ab-cdef-0123-456789000333,
        "state": "CA"
        "locations": {
        "cities": [
            "Fremont",
            "Sunnyvale",
            "San Jose",
            "Santa Clara",
            "Mountain View",
            "Palo Alto",
            "Los Altos",
            "Milpitas",
            "Cupertino",
            "Hayward"
        ],
        "counties": [
            "Santa Clara",
            "Alameda",
            "San Mateo",
            "Santa Cruz",
            "Marin",
            "San Francisco"
        ],
        "zip_codes": [
            "94025",
            "94306",
            "94061",
            "94901",
            "94541",
            "94022",
            "94402",
            "94607",
            "94030"
        ]
        }
    }

    }

    POST /api/agent/stats

    Overview

    This endpoint returns the stats that an agent has for a given time period and location.

    You can also use this endpoint to validate whether or not you have the correct tb_agent_id.

    Request parameters:

    • format_type (string, required): The format in which you want the data to be returned. Options are JSON, HTML.
    • state (string, required): The state for which the Agent wants to request data.
    • tb_agent_id (string, required): The Agent's TB Agent Identifier.
    • time_period (string, required): The time period for which you wish to get closed listings, in months, 12, 24, or 36 months.
    • listing_side (string, required): The side of the listing that the agent wishes to see stats for. Options: list, buy. One or the other is required.
    • location (string, required): The location for which the Agent wants to request data.
    • location_type (string, required): The type of location for which the Agent wants to request data. Examples include county, city, state.

    Agent Stats API Request Example: 

    
Bash
#!/bin/bash

curl --location 'https://trubase-api.rg-infra.com/api/agent/stats'
--header 'Authorization: Token 1234567890123456789012345678901234567890'
--header 'Content-Type: application/json'
--data '{
    "format_type": "JSON",
    "state": "TX",
    "tb_agent_id": "01234567-89ab-cdef-0123-456789000444",
    "time_period": "36",
    "listing_side": "list",
    "location_type": "city",
    "location": "Santa Clara"
}

    Agent Stats API Response Example: 

                
{
    "timestamp": "2024-04-17T07:42:29.696228+00:00Z",
    "response_form_version": "0.10.0",
    "query_status": "success",
    "message": ["Agent stats found"],
    "body": {
        "tb_agent": "Tom Banks",
        "tb_agent_id": "01234567-89ab-cdef-0123-456789000444",
        "state": "CA",
        "time_period": "36 months",
        "location": "Santa Clara",
        "location_type": "county",
        "listing_side": "list",
        "number_of_agents": 5,
        "total_closed_listings": 35,
        "stats": {
            "tb_agent_num_of_closed_listings": 5,
            "tb_agent_success_rate": 1.0,
            "tb_agent_days_on_market": 35,
            "tb_agent_avg_price_difference": 128420,
            "average_agent_num_of_closed_listings": 2,
            "average_agent_success_rate": 1.0,
            "average_agent_days_on_market": 50,
            "average_agent_avg_price_difference": 95000
        }
    }
}

    POST /api/leads

    Overview

    The Leads endpoint provides a facility for TruBase partners to submit leads-agent-pair information, which is to be monitored for successful sales transaction. The endpoint takes a list of request parameters with leadlists key, and will return the transaction_id for the leads submission process.

    You can also use this endpoint to validate whether or not you have the correct tb_agent_id.

    Request parameters [list]:

    • lead_id (string, required): The arbitrary id string provided by caller/client.
    • partner_created_date (string, optional, format: "YYYY-MM-DD"): The date the agent relationship is established with the home seller/buyer. (see "leads_progress: Match process types" section for more details)
    • lead_firstname (string, required): The first name of the lead.
    • lead_lastname (string, required): The last name of the lead.
    • At least one of lead_email OR lead_phone required
      • lead_email (string, required): The email of the lead.
      • lead_phone (string, required): The 10-digit phone number of the lead. The number needs to be "actual existing" numbers. See below for the detail.
    • tb_agent_id (uuid, required): Trubase unique agent id.
    • lead_type (string, required with choices ["seller", "buyer"]): The type of the lead.
    • lead_address (dict, optional): The address of the lead. street_number, street_name, city, state, zip are collectively required once any of those fields are filled.
      • street_number (string, required): The street number of the address.
      • street_dir (string, optional): The street direction of the address.
      • street_name (string, required): The street name of the address.
      • street_post_dir (string, optional): The street post direction of the address.
      • street_type (string, optional): The street type of the address.
      • unit (string, optional): The unit of the address.
      • unit_type (string, optional): The unit type of the address, such as "apt".
      • city (string, required): The city of the address.
      • county (string, optional): The county of the address.
      • state (string, required): The state code (abbreviation) of the address.
      • zip (string, required): The zip code of the address.
    • source_of_business (string, optional): The source of business with the lead.

    Phone numbers format:

      Phone numbers are validated with phonenumbers module (a python port of Google's libphonenumber lib), which the following general rules apply:
    • The validation generally assumes US/Canadian phone numbers so "+1" or "1" are optional for US and Canadian numbers.
    • Numbers after "+" is interpreted as country code so you should not use "+" without country code.
    • The phone number must contain country code with "+" prefix for international numbers outside US/Canada. (ex: +52 for Mexico)
    • The phone number can contain hyphens/dash, parentheses, and spaces.
    • The phone number should not contain any other characters, such as letters, special characters, etc.
    • The phone number should not contain any leading zeros.

    US/Canada specific rules:

    • The phone number must contain valid and existing 3 digits area code and 3 digits prefix.
      For example, "512" is a valid area code and "471" is a valid prefix. Both "5124717890" and "(512) 471-7890" are valid. Parenthesis, periods, forward-slash and spaces are accepted and simply dropped to form 10-digit "national" number format. Thus as an extreme example, ")512 (---) 471 ../ 7890" is also accepted and converted to "5124717890".
      Some of accepted formats are:
        5124717890
        512-471-7890
        512.471.7890
        512/471/7890
        (512)471-7890
        (512) 471 7890

    Testing phone number format:

      You can test the phone number format with following libs.
    • libphonenumber (https://github.com/google/libphonenumber for Java, C++, JavaScript)
    • python-phonenumbers (https://github.com/daviddrysdale/python-phonenumbers for Python)
      Following is an example code snippet for python-phonenumbers. 
    
            # Python
            import phonenumbers
            orig_phone_number = "(512)471-7890"
            parsed_phone_number =phonenumbers.parse(orig_phone_number, "US")
            print(parsed_phone_number, phonenumbers.is_valid_number(parsed_phone_number))

            # example output
            Country Code: 1 National Number: 5124717890 True

    Leads API Request Example: 

    
    # Bash
    #!/bin/bash

    curl --location 'https://trubase-api.rg-infra.com/api/leads'
    --header 'Authorization: Token 1234567890123456789012345678901234567890'
    --header 'Content-Type: application/json'
    --data '
    {
        "leadslist": [
        {
            "lead_id": "L_01154_Vyden",
            "partner_created_date": "2024-04-17",
            "lead_firstname": "Joe",
            "lead_lastname": "Vyden",
            "lead_email": "joevyden@example.com",
            "lead_phone": "5124134567",
            "tb_agent_id": "01234567-89ab-cdef-0123-456789000555",
            "lead_type": "buyer",
            "lead_address": {
                "street_number": "123",
                "street_dir": "N",
                "street_name": "Main",
                "street_post_dir": "E",
                "street_type": "St",
                "unit": "101",
                "unit_type": "Apt",
                "city": "Anytown",
                "county": "Anycounty",
                "state": "NY",
                "zip": "78701"
            },
            "source_of_business": "Online Advertisement"
        }

            ...  additional leads dictionaries can be added here
        ]
    }
    ' | jq '.'

    Leads API Response Example

    

{
    "timestamp": "2024-04-17T07:42:29.696228+00:00Z",
    "response_form_version": "0.10.0",
    "query_status": "success",
    "body": {
        "transaction_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeffff1234"
    }
}

    GET /api/leads_status

    Overview

    The Leads Status endpoint provides a facility to query for the status of process queue for the Leads endpoint. The GET endpoint takes a single transaction id as a request parameter. It returns a list of status for the leads endpoint submission process.

    Request parameter:

    • transaction_id (uuid, required): The transaction_id string returned from Leads endpoint request.

    Leads Status API Request Example 

    
# Bash
#!/bin/bash

curl --location 'https://trubase-api.rg-infra.com/api/leads_status?transaction_id=aaaaaaaa-bbbb-cccc-dddd-eeeeffff1234'
--header 'Authorization: Token 1234567890123456789012345678901234567890'
--header 'Content-Type: application/json'

    Leads Status API Response Example 

    
{
    "timestamp": "2024-04-26T05:43:41.389238+00:00Z",
    "response_version": "0.10.0",
    "query_status": "success",
    "body": {
        "transactionslist": [
            {
                "aaaaaaaa-bbbb-cccc-dddd-eeeeffff1234": {
                    "transaction_status": "SUCCEEDED"
                }
            }
        ]
    }
}

    GET /api/leads_progress

    Overview

    The Leads Progress endpoint provides a facility to query and confirm if any leads submitted through the Leads endpoint have been included on a closed transaction. The endpoint will return the list of transaction details that the lead has participated in.

    Log format can change over time. Please refer to Response Version Change Log.

    Match process types

      There are 2 types of matching results, address-based and name-based.
    • The address-based matching applied on the address of the seller only when the address is provided.
        • The address-based matching looks for the all historical transactions on the matching address. It determines the appropriate transaction based on the partner_created_date from lead submission. Since leads:partner_created_date field is optional, if it is not provided, the transaction is determined by lead submission timestamp.
    • The name-based matching applied on both buyer and seller leads name.
        • The name-based matching looks for the similarity between the first/middle/last name or the company name of the leads and seller names.
        Leads are matched with address-based matching first, then matched with name-based matching for items that was not matched with address-based matching.
        The match_rate field is a value that indicates the likelihood that the lead is the same person as the buyer or seller in name-based matching.
          This value is calculated based on the first/middle/last name or the company name of the lead.
          This field is provided only with name-based matching, not provided for address-based matching.

    Request parameters:

    • tb_agent_id (uuid, required): The tb_agent_id, which is unique to an agent.

    Response format:

      The response will have usual timestamp, response_form_version, and query_status fields, plus body block.
      The body block contains fields described in below "Response parameters" section.
      All fields are returned in the response with either valid string or empty ("") string.
      You can always expect the lead_id and side fields to be non-empty.
        The rest of the fields can be empty depending on the nature of the matching process.
        In reality, you should, at least, find first seller name, first buyer name, listing agent info, and selling agent info fields to have valid values.
      The process_type field is returned only when the query parameter is set, and returned value is expected to be one of pre-defined values.
      The match_rate field is returned only when the leads is matched with name-based matching process.

    Response parameters:

    Lead information:
    • lead_id: The same lead_id provided by caller/client at leads endpoint.
    • side (outcomes: [SELL, BUY]): Lead side.
    • match_rate (range: 0.0 - 1.0): The name similarity score of the submitted lead to the owner names in the record.
        Returned only with the leads matched by name-based matching process.
    Process information:
    • process_type (outcomes: [OWNER_NAME, BUYER_NAME, SELLER_NAME, LIST_ADDRESS]): The type of the matching process applied on the lead.
      • LIST_ADDRESS: The listing address is matched with address-based matching.
      • BUYER_NAME: One of buyers is matched with name-based matching.
      • SELLER_NAME: One of seller is matched with name-based matching.
      Returned only with query params process_type=true. (See the Bash/Python example below.)
    Property information:
    • listing_address: The address of the matched lead.
      • street_number: The street number of the address.
      • street_name: The street name of the address.
      • unit: The unit of the address.
      • city: The city of the address.
      • zip: The zip code of the address.
      • county: The county of the address.
      • state: The state code (2-charactor abbreviation) of the address.
    • listing_date: MLS listing date on the matched record.
    • close_date: MLS closed/sold date on the matched record.
    • sold_price: MLS sold price on the matched record.
    • est_gross_comm: Estimated (3% calculated) commission on the sold price.
    Seller information:
    • first_seller_first_name_middle_name: First seller first name (and middle name if there).
    • first_seller_last_name_or_corporation_name: First seller last name or corporation name.
    • second_seller_first_name_middle_name: Second seller first name (and middle name if there).
    • second_seller_last_name: Second seller last name or corporation name.
    Buyer information:
    • first_buyer_first_name_middle_name: First buyer first name (and middle name if there).
    • first_buyer_last_name: First buyer last name or corporation name.
    • second_buyer_first_name_middle_name: Second buyer first name (and middle name if there).
    • second_buyer_last_name: Second buyer last name or corporation name.
    Seller side agent information:
    • agt_list_tb_agent_id: Trubase unique agent id of the listing agent.
    • agt_list_agent_name: Listing agent name.
    • agt_list_coagt_tb_agent_id: Trubase unique agent id of the listing coagent.
    • agt_list_coagt_name: Listing coagent name.
    Buyer side agent information:
    • agt_sold_tb_agent_id: Trubase unique agent id of the selling agent.
    • agt_sold_agt_name: Selling agent name.

    Leads Progress API Request Example: 

    
# Bash
#!/bin/bash

curl --location 'https://trubase-api.rg-infra.com/api/leads_progress?process_type=true&TB_Agent_Id=01234567-89ab-cdef-0123-456789000666'
--header 'Authorization: Token 1234567890123456789012345678901234567890'
--header 'Content-Type: application/json'

    Leads Progress API Response Example 

    
{
    "timestamp": "2024-04-25T21:49:49.650791+00:00Z",
    "response_version": "0.10.0",
    "query_status": "success",
    "body": [
        {
            "lead_id": "L_01213_GRINTON",
            "listing_address": {
                "street_number": "123",
                "street_name": "Power Blvd",
                "unit": "",
                "city": "San Jose",
                "zip": "95135",
                "county": "Santa Clara",
                "state": "CA"
            },
            "listing_date": "2018-02-02T00:00:00-05:00",
            "close_date": "2018-03-12T00:00:00-04:00",
            "sold_price": 745000,
            "est_gross_comm": 22350,
            "side": "BUY",
            "first_seller_first_name_middle_name": "Joe",
            "first_seller_last_name_or_corporation_name": "Viden",
            "second_seller_first_name_middle_name": "Jill",
            "second_seller_last_name": "Viden",
            "first_buyer_first_name_middle_name": "Bill",
            "first_buyer_last_name": "Grinton",
            "second_buyer_first_name_middle_name": "Hillary",
            "second_buyer_last_name": "Grinton",
            "agt_list_tb_agent_id": "45670123-89ab-cdef-0123-400066656789",
            "agt_list_agent_name": "Diane Geaton",
            "agt_list_coagt_tb_agent_id": "",
            "agt_list_coagt_name": "",
            "agt_sold_tb_agent_id": "01234567-89ab-cdef-0123-456789000666",
            "agt_sold_agt_name": "Jane Ponda",
            "match_rate": "0.90",
            "process_type": "BUYER_NAME"
        }
    ]
}

    Error Responses

    Overview

    Here are the error responses that you can receive.

    Status When Body
    401 Not Authorized Authorization header is missing or incorrect, or the given credentials doesn't have permission for this site {"error":"description"}
    400 Bad Request Request body doesn’t contain a valid JSON document {"error":"description"}
    422 Unprocessable Entity Request body has valid JSON document but one of the fields did not validate {"error":"description"}
    500 Internal Server Error Unknown error Unspecified
    503 Service Unavailable API server is not responding Unspecified

    Request Field Change Log

    Overview

    Following is the list of historical field name/context changes for request fields.

    Date Description
    2025.02.18 "added fields": (leads) partner_created_date.

    Response Version Change Log

    Overview

    Following is the list of historical field name/context changes by response_version number.

    Date Version Description
    2025.02.10 0.10.0 "removed fields": (leads_progress) owner1_first, owner1_middle, owner1_last, owner2_first, owner2_middle, owner2_last
    2025.02.10 0.10.0 "added fields": (leads_progress) first_seller_first_name_middle_name, first_seller_last_name_or_corporation_name, second_seller_first_name_middle_name, second_seller_last_name, first_buyer_first_name_middle_name, first_buyer_last_name, second_buyer_first_name_middle_name, second_buyer_last_name, agt_list_tb_agent_id, agt_list_agent_name, agt_list_coagt_tb_agent_id, agt_list_coagt_name, agt_sold_tb_agent_id, agt_sold_agt_name
    2025.02.10 0.10.0 "updated fields": (leads_progress) "side": "buy" -> "side": "BUY" to indicate enum type
    2025.02.10 0.10.0 "added fields": (leads_progress) optional process_type field to determine match process type
    2025.02.10 0.10.0 "changed fields characteristics": (leads_progress) match_rate indicate the rating for name-based matching. The field not returned for address-based matching
    initial version 0.9.0 "action": (doc section) description

    Document Update / Error Change Log

    Overview

    Following is the list of historical document updates.

    Date Version Description
    2025.03.18 N/A "updated": (leads) adding descriptions for phone number format/validation.
    2025.02.18 N/A "updated": (leads_progress) adding descriptions for the significance of partner_created_date
    2025.02.18 N/A "request parameters description typo": (leads) first name -> last name
    2025.02.10 0.10.0 "updated": (leads_progress) adding descriptions for process type, response field format/context, and optional parameter
    2025.02.10 N/A "request example field value typo": (leads) "unit": "Apt 101" -> "unit": "101"
    2025.02.10 0.10.0 "response example field key typo": (leads_progress) lead -> lead_id
    2025.02.10 N/A "curl command example typo": (leads_status, leads_progress) removed "--data" to imply GET request