TitleSphere API 04-23-26

The TitleSphere API enables you to upload people and transaction data to your TitleSphere account.

Servers: https://www.usesphere.com

Generating an API key & passcode

Before calling any endpoint below, create credentials under Settings > Account > API console: usesphere.com/admin/settings/api-console

  1. Click “Create API Key”.
  2. Copy the generated API key and passcode to a secure location as soon as they’re created.
  3. You can regenerate a new key/passcode at any time — but once you do, the old key stops working immediately.
⚠️ You will not be able to view the passcode again after this dialog closes — store it before navigating away.

Authentication

Exchange your API key & passcode for an access token, and refresh it when it expires. ▾
POST /sphere_api/web/v1/users/exchange-token Generate exchange token ▾
First step in authentication. Exchanges your API key and passcode for a server authorization token, which must be passed with each API request.
Parameters
Name Description
api_keyrequired
string
 API key which is a mandatory field.
api_secretrequired
string
 Secret key which is a mandatory field.
Responses
Code Description
200 Returns user_id and an access token to be sent with each subsequent API request.
Server response
200 Success 
{
  "user_id": "user id",
  "token": "<<ACCESS TOKEN>>"
}
POST /sphere_api/web/v1/users/refresh-token Refresh an expired token ▾
When a previously issued token expires, call this endpoint to obtain a refreshed token.
Parameters
Name Description
old_tokenrequired
string
 Expired old refresh token which is a mandatory field.
secret_keyrequired
string
 Secret key which is a mandatory field.
Responses
Code Description
200 Returns a new access token on success.
Server response
200 Success 
{
  "status": true,
  "code": 200,
  "token": "<<NEW ACCESS TOKEN>>"
}

Transactions

Create or update transaction records. Requires a valid authorization token. ▾
POST /sphere_api/web/v1/transactions/create-transaction Add / push a transaction to TitleSphere ▾
file_no and either email or phone are mandatory fields. Other fields are optional.
Parameters
Name Description
type
string
 Type of transaction: Refinance, Resale, or Prelim. Default value is Resale. Refer below Type mapping.
owner_email
string
 Email ID of the transaction owner who is a TitleSphere team member.
owner_name
string
 Name of the transaction owner who is a TitleSphere team member.
sales_rep_email
string
 Sales rep email. If owner details are not available, this is considered as owner_email. If a valid owner is present, the matching sales rep is added as an assignee.
sales_rep
string
 Sales rep name. If owner details and sales_rep_email are not available, this is considered as the owner name. If a valid owner is present, the matching sales rep is added as an assignee.
status
string
 Status of the transaction: open, closed, or got away. Default value is open.
unit_no
string
 Unit number of the address.
address
string
 Address of the transaction.
city
string
 City.
state
string
 State.
zipcode
string
 Zip code of the address.
created_on
date
 Created date.Format: mm/dd/yyyy
file_norequired
string
 File number.
client
string
 Single or comma-separated customer names.
email
string
 Email address of the directing customer.
phone
string
 Phone number of the directing customer.
company_name
string
 Company name.
list_price
number
 List price.
sales_price
number
 Sales price.
closing_date
date
 Closing date.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
open_date
date
 Transaction open date.Format: mm/dd/yyyy
client_employee
string
 Client employee field.
title_officer
string
 Title officer of the transaction.
sent_to_accounting
string
 Sent to external accounting field.
transactee
string
 Transactee of the transaction.
estimated_closing_date
date
 Estimated closing date.Format: mm/dd/yyyy
disbursement_date
date
 Disbursement date.Format: mm/dd/yyyy
lending_agency_name
string
 Lender.
interest_rate
number
 Interest rate.
loan_amount
number
 Loan amount.
title_premium
number
 Title premium.
escrow_premium
number
 Escrow premium.
listing_agent_company
string
 Listing agent company.
selling_agent_company
string
 Selling agent company.
buyer_name
string
 Buyer name.
buyer_email
string
 Buyer email.
seller_name
string
 Seller name.
seller_email
string
 Seller email.
total_fee
integer or decimal number
 Total fee, usually the sum of title and escrow premium.
commission
number
 Commission.
additional_notes
string
 Additional notes.
directing_customer
object
 Directing customer JSON data.e.g. {"directing_customer":[{"first_name":"John","last_name":"Smith","company":"abc company","email":"abc@xyz.com","phone":"9876543210"}]}
selling_agent
object
 Selling agent JSON data.e.g. {"selling_agent":[{"first_name":"John","last_name":"Smith","company":"abc company","email":"abc@xyz.com","phone":"9876543210"}]}
listing_agent
object
 Listing agent JSON data.e.g. {"listing_agent":[{"first_name":"John","last_name":"Smith","company":"abc company","email":"abc@xyz.com","phone":"9876543210"}]}
loan_officer
object
 Loan officer JSON data.e.g. {"loan_officer":[{"first_name":"John","last_name":"Smith","company":"abc company","email":"abc@xyz.com","phone":"9876543210"}]}
seller_attorney
object
 Seller attorney JSON data.e.g. {"seller_attorney":[{"first_name":"John","last_name":"Smith","email":"abc@xyz.com","phone":"9876543210"}]}
buyer_attorney
object
 Buyer attorney JSON data.e.g. {"buyer_attorney":[{"first_name":"John","last_name":"Smith","email":"abc@xyz.com","phone":"9876543210"}]}
Type mapping
Input Maps to
Resale purchaseMoneyMortgage, cashTransaction, landContract, businessLoan, commercialLoan, Report of Search, Miscellaneous
Refinance refinance, reverseMortgage, homeEquity, subordinateMortgage
Prelim residentialprelim
Responses
Code Description
200 Transaction created. Returns a trans_id and success message.
Server response
200 Success 
{
  "status": true,
  "code": 200,
  "message": "Transaction created successfully.",
  "trans_id": "<id>"
}
POST /sphere_api/web/v1/transactions/save-transaction Create / update a transaction ▾
file_no and directing_customer details are mandatory fields. Every other field is optional.
Parameters
Name Description
type
string
 Type of transaction: Refinance, Resale, or Prelim. Default value is Resale. Refer below Type mapping
status
string
 Status of the transaction.
open_date
date
 Transaction open date.Format: mm/dd/yyyy
file_norequired
string
 File number.
closing_date
date
 Closing date.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
list_price
number
 List price.
estimated_closing_date
date
 Estimated closing date.Format: mm/dd/yyyy
disbursement_date
date
 Disbursement date.Format: mm/dd/yyyy
lending_agency_name
string
 Lender.
sales_price
number
 Sales price.
loan_amount
number
 Loan amount.
interest_rate
number
 Interest rate.
unit_no
string
 Unit number of the address.
address
string
 Address of the transaction.
city
string
 City.
state
string
 State.
zipcode
string
 Zip code of the address.
country
string
 Country.
total_fee
number
 Total fee.
commission
number
 Commission.
title_premium
number
 Title premium.
escrow_premium
number
 Escrow premium.
listing_agent_company
string
 Listing agent company.
selling_agent_company
string
 Selling agent company.
buyer_name
string
 Buyer name.
buyer_email
string
 Buyer email.
seller_name
string
 Seller name.
seller_email
string
 Seller email.
additional_notes
string
 Additional notes.
directing_customerrequired
object
 Directing customer JSON data. If not present, the record is added as No name.e.g. {"directing_customer":[{"first_name":"John","last_name":"Smith","company":"abc company","email":"abc@xyz.com","phone":"9876543210"}]}
selling_agent
object
 Selling agent JSON data.e.g. {"selling_agent":[{"first_name":"John","last_name":"Smith","company":"abc company","email":"abc@xyz.com","phone":"9876543210"}]}
listing_agent
object
 Listing agent JSON data.e.g. {"listing_agent":[{"first_name":"John","last_name":"Smith","company":"abc company","email":"abc@xyz.com","phone":"9876543210"}]}
loan_officer
object
 Loan officer JSON data.e.g. {"loan_officer":[{"first_name":"John","last_name":"Smith","company":"abc company","email":"abc@xyz.com","phone":"9876543210"}]}
seller_attorney
object
 Seller attorney JSON data.e.g. {"seller_attorney":[{"first_name":"John","last_name":"Smith","email":"abc@xyz.com","phone":"9876543210"}]}
buyer_attorney
object
 Buyer attorney JSON data.e.g. {"buyer_attorney":[{"first_name":"John","last_name":"Smith","email":"abc@xyz.com","phone":"9876543210"}]}
Type mapping
Input Maps to
Resale purchaseMoneyMortgage, cashTransaction, landContract, businessLoan, commercialLoan, Report of Search, Miscellaneous
Refinance refinance, reverseMortgage, homeEquity, subordinateMortgage
Prelim residentialprelim
Responses
Code Description
200 Transaction saved. Returns a trans_id and a status message indicating whether the record was created or updated.
Server response
200 Success 
// Update case
{
  "status": true,
  "code": 200,
  "message": "Transaction updated successfully",
  "trans_id": "<id>"
}

// Create case
{
  "status": true,
  "code": 200,
  "message": "Transaction created successfully",
  "trans_id": "<id>"
}

People

Add or push a contact into TitleSphere. Requires a valid authorization token. ▾
POST /sphere_api/web/v1/leads/add-people Add / push a client to TitleSphere ▾
first_name is the only mandatory field. Every other field is optional.
Parameters
Name Description
first_namerequired
string
 First name which is a mandatory field.
middle_name
string
 Middle name.
last_name
string
 Last name.
title
string
 Title.
dob
date
 Date of birth.Format: yyyy/mm/dd
letter_salutation
string
 Letter salutation.
email
string
 Email address.
primary_phone
string
 Primary phone number.
web_page
string
 Customer web page.
facebook_link
string
 Customer Facebook link.
linkedin_link
string
 Customer LinkedIn link.
twitter_link
string
 Customer Twitter link.
instagram_link
string
 Customer Instagram link.
amazon_wishlist
string
 Amazon wishlist link.
home_address
string
 Street address.
unit_no
string
 Unit number.
city
string
 City.
state
string
 State.
country
string
 Country.
zipcode
string
 Zip code.
work_anniversary
date
 Work anniversary date.Format: mm/dd/yyyy
wedding_anniversary
date
 Wedding anniversary date.Format: mm/dd/yyyy
fav_food
string
 Favorite food.
fav_movies
string
 Favorite movie.
fav_book
string
 Favorite book.
gift_ideas
string
 Gift ideas.
company_name
string
 Company name.
office_address
string
 Office street address.
office_city
string
 Office city.
office_state
string
 Office state.
office_country
string
 Office country.
office_zip
string
 Office zip code.
owner_email_id
string
 Email id of a team member. If a valid team-member email is sent, people are added to that team member's TitleSphere account.
Responses
Code Description
200 Person saved. Returns user_id with the success message.
Server response
200 Success 
{
  "status": true,
  "code": 200,
  "message": "Saved Successfully.",
  "user_id": 16
}

Schemas

Reusable object shapes referenced by the endpoints above. ▾
ContactRole{ first_name, last_name, company, email, phone }▾
first_name string
last_name string
company string
email string
phone string
TransactionType{ Resale, Refinance, Prelim }▾
Resale purchaseMoneyMortgage, cashTransaction, landContract, businessLoan, commercialLoan, Report of Search, Miscellaneous
Refinance refinance, reverseMortgage, homeEquity, subordinateMortgage
Prelim residentialprelim