Partner API Documentation

Page Contents

Endpoints

Error Responses

Endpoints

Overview

The Partner API has the following endpoints:

POST /api/agent
POST /api/agent/listings
POST /api/agent/locations
POST /api/agent/stats
POST /api/leads
GET /api/leads_status
GET /api/leads_progress

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:


# Python
import requests

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

response = requests.post(url, headers=headers, json=data)

print(response.json())


# 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.9.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:


# Python
import requests

url = 'https://trubase-api.rg-infra.com/api/agent/listings'
headers = {
    'Authorization': 'Token 1234567890123456789012345678901234567890',
    '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"

    }
 ]
}

response = requests.post(url, headers=headers, json=data)

print(response.json())


# 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.9.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:


# Python
import requests

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

response = requests.post(url, headers=headers, json=data)

print(response.json())


# 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.9.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:


# Python
import requests

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

response = requests.post(url, headers=headers, json=data)

print(response.json())


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.9.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 id string provided by caller/client.
lead_firstname (string, required): The first name of the lead.
lead_lastname (string, required): The first 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. Use only numerics. The number needs to be "actual existing" numbers.

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.
- 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.

Leads API Request Example:


    # Python
    import requests

    url = 'https://trubase-api.rg-infra.com/api/leads'
    headers = {
        'Authorization': 'Token 1234567890123456789012345678901234567890',
        'Content-Type': 'application/json'
    }
    data = {
        "leadslist": [
        {
            "lead_id": "a0123456-b012-c012-d012-e0123456789a",
            "lead_firstname": "Joe",
            "lead_lastname": "Vyden",
            "lead_email": "joevyden@someemail.com",
            "lead_phone": "5124134567",
            "tb_agent_id": "01234567-89ab-cdef-0123-456789000555",
            "lead_type": "seller",
            "lead_address": {
                "street_number": "123",
                "street_dir": "NW",
                "street_name": "Main",
                "street_post_dir": "NE",
                "street_type": "Ave",
                "unit": "A",
                "unit_type": "Apt",
                "city": "Austin",
                "county": "Travis",
                "state": "TX",
                "zip": "78701"
            },
            "source_of_business": "web link from Facebook"
        }

    ...  additional leads dictionaries can be added here
]
    }

    response = requests.post(url, headers=headers, json=data)

    print(response.json())


    # 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": "1234567890123456789012345678901234",
            "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": "Apt 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.9.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


# Python
import requests

url = 'https://trubase-api.rg-infra.com/api/leads_status'
headers = {
    'Authorization': 'Token 1234567890123456789012345678901234567890',
    'Content-Type': 'application/json'
}
params = {"transaction_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeffff1234"}

response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())


# 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'
--data ''

Leads Status API Response Example


{
    "timestamp": "2024-04-26T05:43:41.389238+00:00Z",
    "response_version": "0.9.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.

Request parameters:

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

Leads Progress API Request Example:


# Python
import requests

url = 'http://0.0.0.0:8000/api/leads_progress'
headers = {
    'Authorization': 'Token 1234567890123456789012345678901234567890',
    'Content-Type': 'application/json'
}
params = {'TB_Agent_Id': '01234567-89ab-cdef-0123-456789000666'}

response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())


# Bash
#!/bin/bash

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

Leads Progress API Response Example

match_rate ranges between 0.0-1.0


{
    "timestamp": "2024-04-25T21:49:49.650791+00:00Z",
    "response_version": "0.9.0",
    "query_status": "success",
    "body": [
        {
            "lead": "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",
            "owner1_first": "Bill",
            "ownder1_middle": "",
            "owner1_last": "Grinton",
            "owner2_first": "Hillary",
            "owner2_middle": "",
            "owner2_last": "Grinton",
            "match_rate": 1
        }
    ]
}

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