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

OAuth 2.0 provides secure, token-based access to the Sphere 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.
Sample 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/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