Sphere API 06.26.26

The Sphere API enables you to upload people and transactions data to your Sphere 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 secret for a server access token, which must be passed with every subsequent 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.
Sample 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 new one.
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/save-transaction Create / update a transaction ▾
Creates a new transaction, or updates an existing one. type and client details (seller_client / buyer_client) are mandatory — all other fields are optional. Must be called with a valid authorization token.
Parameters
Name Description
typerequired
string
 Type of transaction: buyer, seller or referral income.
seller_client
/ buyer_clientrequired
array<object>
 Client details. buyer_client is used for buyer / referral income transactions.e.g. [{"first_name":"abc","last_name":"xyz","company":"comp_1,abc1","email":"abc@xyz.com","phone":"2222200000"}]
status
string
 Status of the transaction. Default value is potential.
list_date
date
 Transaction list date.Format: mm/dd/yyyy
mls_no
string
 MLS number.
owner_email
string
 Email id of the transaction lead.
owner_name
string
 Name of the transaction lead.
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 on.Format: mm/dd/yyyy, e.g. 12/30/2025
list_price
number
 List price.
sales_price
number
 Sales price.
seller_contribution
/ buyer_contribution
number
 Seller / buyer contribution.e.g. $500 or 5%
closing_date
date
 Closing date.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
possession_date
date
 Possession date.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
contract_no
string
 Contract number.
date_written
date
 Date written.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
mutual_acceptance
date
 Mutual acceptance date.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
timeline_begins
date
 Timeline begins date.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
earnest_money
number
 Earnest money.e.g. 5000
earnest_money_deadline
date
 Earnest money deadline.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
inspection_period_ends
date
 Inspection period ends.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
disclosure_deadline
date
 Disclosure deadline.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
seller_paid_close
number
 Seller paid close.e.g. 5000
hoa_docs_received
date
 HOA docs received.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
appraisal_ordered
date
 Appraisal ordered.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
repairs_due
date
 Repairs due.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
personal_property
date
 Personal property.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
general_inspection
date
 General inspection.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
sewer_inspection
date
 Sewer inspection.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
radon_drop_off
date
 Radon drop off.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
radon_pickup
date
 Radon pickup.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
roof_inspection
date
 Roof inspection.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
soil_inspection
date
 Soil inspection.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
photography
date
 Photography.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
underground_tank_inspection
date
 Underground tank inspection.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
staging
date
 Staging.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
cleaners
date
 Cleaners.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
sign_install
date
 Sign install.Format: mm/dd/yyyy or mm/dd/yyyy h:i a, e.g. 12/24/2025 10:00 pm
buyer_s_agent_s_commission
number
 Buyer’s agent’s commission, for a Seller transaction.e.g. 5000
seller_s_agent_s_commission
number
 Seller’s agent’s commission, for a Buyer transaction.e.g. 5000
additional_notes
string
 Additional notes.
assignee
array<object>
 Assignee details.e.g. [{"name":"John Smith","email":"john@mail.com"}]
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": 23567
}

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

People

Add or push a contact into Sphere. Requires a valid authorization token. ▾
POST /sphere_api/web/v1/leads/add-people Add / push a client to Sphere ▾
first_name is the only mandatory field — every other field is optional.
Parameters
Name Description
first_namerequired
string
 First name — the only 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
 Facebook link.
linkedin_link
string
 LinkedIn link.
twitter_link
string
 Twitter link.
instagram_link
string
 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, the person is added to that team member’s Sphere account.
Responses
Code Description
200 Person saved. Returns user_id and the new people_id.
Server response
200 Success 
{
  "status": true,
  "code": 200,
  "message": "Saved Successfully.",
  "user_id": 2,
  "people_id": 123
}

Schemas

Reusable object shapes referenced by the endpoints above. ▾
Client{ first_name, last_name, company, email, phone }▾
first_name string
last_name string
company string
email string
phone string
Assignee{ name, email }▾
name string
email string