TitleSphere API 08.28.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. ▾

OAuth 2.0 provides secure, token-based access to the TitleSphere API. Exchange your API key and passcode for an access token, then include that token with each API request.

POST /sphere_api/web/v1/users/exchange-token Generate exchange token ▾
Use OAuth 2.0 Client Credentials to exchange your API key and passcode for a temporary access token. Include the returned token as a Bearer token when calling protected API endpoints.
Parameters
Name Description
Authorizationrequired
string
 Send the API key as the username and the API secret as the password using HTTP Basic Authentication. The resulting header uses the format: Basic Authentication:
Username: <API key>
Password: <API secret>
Responses
Code Description
200 Returns an OAuth access token, token type, and expiration time. Use the access token as a Bearer token for protected API requests.
Server response
200 Success 
{
  "token_type": "Bearer",
  "access_token": "<<ACCESS TOKEN>>",
  "expires_in": 3600
}
POST /sphere_api/web/v1/users/refresh-token Refresh an expired token ▾
When an OAuth access token expires, send the previous token to obtain a new access token.
Parameters
Name Description
old_tokenrequired
string
 Previously issued OAuth access token. This is a mandatory field.
Responses
Code Description
200 Returns a new OAuth access token, token type, and expiration time.
Server response
200 Success 
{
  "token_type": "Bearer",
  "access_token": "<<NEW ACCESS TOKEN>>",
  "expires_in": 3600
}

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