Let's Talk APIs
Are you a service provider for the Real Estate or Mortgage Industry? Then the CityBlast API might be right for you.
The CityBlast API allows you to sync your database with CityBlast for easier or automated management. Automatically create new listings, add a CityBlast feed to your website, access your Dashboard statistics, link campaign stats to your database, remotely add new members or adjust your Experts' posting instructions, and more.
Our API offers in-depth documentation and "how-to" documents, and a great deal of the data and functionality within our web application is accessible, so the integration possibilities are limitless.
Need Help?
Not a programmer? Not a problem. We can help you develop custom integrations for your company or website. Simply email us at info@cityblast.com with your request, and someone from our professional services team will contact you.
API: Documentation
CityBlast offers simple, standard OAuth2 services for user-friendly authorization of third-party operations. Your users will need to go through the OAuth2 flow before your site can publish listings via CityBlast.
Before you can begin, you will need to have CityBlast support provide you with a unique API key and secret. Once you receive those, you'll be able to implement the CityBlast API in your website.
API keys
In this documentation, we'll use the following test account:
API Key: | 0cbc6611f5540bd0809a388dc95a615b |
API Secret: | 1e6947ac7fb3a9529a9726eb692c8cc5 |
Note: These keys are not valid and cannot be used in your code.
Note: You should protect your key and secret like you would a password, particularly the API secret.
OAuth2 endpoints:
Authorization: | https://www.cityblast.com/rest/authorize |
Access token: | https://www.cityblast.com/rest/token |
OAuth2 Implementation Overview
To provide a general understanding of how OAuth2 works, here's an outline of how your site and the CityBlast API interact together to authorize your site to post listings on behalf of your user:
Your site generates a random "state" string and redirects the user to the CityBlast authorization endpoint, with client_id (your API key) and state (random generated string) as GET arguments. Your site should also store the state string in the current session.
Example authorization request URL:
https://www.cityblast.com/rest/authorize?client_id=0cbc6611f5540bd0809a388dc95a615b&state=0ed8eb67d887c67f953359d7cb2ac6a0
CityBlast asks the user if they want to allow your site to access their CityBlast account. User clicks yes or no.
CityBlast redirects the user back to your site's preconfigured redirect URL with an authorization token appended (in a 'code' GET parameter) and the state string (in a 'state' GET argument).
Example redirect URL:
http://www.yoursite.com/oauth_callback?code=0ed3f45743dfebb64cdca6c15011e391701e9340&state=0ed8eb67d887c67f953359d7cb2ac6a0
In this example, the authorization token is:
0ed3f45743dfebb64cdca6c15011e391701e9340
.
Your server checks that the 'state' GET argument matches the string stored in the session (in step 1).
Your server then makes an HTTP-authenticated POST request to the CityBlast access token endpoint, posting the authorization token.
Example POST request:
URL: | https://www.cityblast.com/rest/token |
Username: | 0cbc6611f5540bd0809a388dc95a615b |
Password: | 1e6947ac7fb3a9529a9726eb692c8cc5 |
POST field grant_type : |
authorization_code |
POST field code : |
0ed3f45743dfebb64cdca6c15011e391701e9340 (authorization token from URL in step 3) |
CityBlast responds with a JSON-encoded string containing an access token, an access token expiration, and a refresh token. All three of these items should be persisted in your site's database for future use. Each of your users who authorize you to access their CityBlast account will have their own unique tokens, so you should be sure to include a reference to the current user (generally a user_id column). The state and authorization token are no longer useful and do not need to be stored.
Example JSON response:
{ "access_token": "e62f1900c6b12c875fc64fa915309b09c2517530", "expires_in": 315576000, "token_type":"Bearer", "scope":"listing account_info", "is_live":1 "refresh_token": "977b97fec11b71360f2fc08e69bac1899568e4c9", }
You might also receive an error, and your application should be prepared to handle it gracefully.
Example error JSON response:
{ "error": "invalid_grant", "error_description": "Authorization code doesn't exist or is invalid for the client" }
Note: the expires_in value is the number of seconds until the access token expires. To get a date and time of expiry, add the expires_in value to the current UNIX timestamp.
Note: your API account may be in test mode or live mode. The is_live
parameter indicates the mode the token was issued in. Tokens issued in test mode are not valid for making changes in production.
OAuth2 Tokens
Tokens are semi-random strings of characters that function as unique identifiers. Each type of token has a different function:
Access token
The access token is your key to the user's CityBlast account. You will need to provide this key each time you take an action (e.g. publish a listing) to the user's account. Access tokens are currently long-lived: they're good for 10 years. It's still a good idea to store the access token expiration though, as this may change in the future.
Access tokens should be protected and never displayed or otherwise exposed on your website.
Authorization token
This temporary token (issued in step 3 above) is short-lived and single-use. Its only purpose is to retrieve an access token. Once it's used, it expires. Your site should use it to request the access token immediately (in step 5 above) as they expire in 10 seconds.
Refresh token
Once an access token expires, your site can use the refresh token to obtain a new one. Refresh tokens expire a year after access tokens expire.
URL: | https://www.cityblast.com/rest/token |
Username: | 0cbc6611f5540bd0809a388dc95a615b |
Password: | 1e6947ac7fb3a9529a9726eb692c8cc5 |
POST field grant_type : |
refresh_token |
POST field code : |
977b97fec11b71360f2fc08e69bac1899568e4c9 (refresh token provided with access token) |
Important: refresh tokens become invalid after use. A new refresh token is issued with the new access token.
Access token scope required: account_info
Once you have obtained a valid access token for a CityBlast member, either through our OAuth2 authentication or provisioning a new CityBlast account, your site can manage settings on that user's account via the CityBlast API.
Changing settings on a CityBlast account is just a matter of making a request to the correct endpoint.
Endpoint: https://www.cityblast.com/rest/member/[:id]
This endpoint conforms to REST standards: it accepts GET requests for read operations and POST requests for write operations.
User account parameters available at this endpoint:
Field name | Data type | Valid values | Default | Description | Required? |
---|---|---|---|---|---|
first_name
|
string
|
<= 100 characters | Value provided by Facebook | The user's first name | Optional |
last_name
|
string
|
<= 100 characters | Value provided by Facebook | The user's last name | Optional |
email
|
string
|
<= 256 characters | Value provided by Facebook | The user's email address | Optional |
publishing_enabled
|
boolean
|
true or false
|
true
|
The member's publishing “master switch.” When publishing_enabled is set to true , publishing to individual social media networks is controlled by the facebook_enabled , twitter_enabled and linkedin_enabled parameters. When publishing_enabled is set to false , all publishing is disabled.
|
Optional |
facebook_access_valid
|
boolean
|
true or false
|
Whether or not our connection to Facebook for this user is valid. If this value is false , the user must authenticate or reauthenticate against Facebook to continue publishing.
|
Read only | |
twitter_access_valid
|
boolean
|
true or false
|
Whether or not our connection to Twitter for this user is valid. If this value is false , the user must authenticate or reauthenticate against Twitter to continue publishing.
|
Read only | |
twitter_enabled
|
boolean
|
true or false
|
false
|
Whether or not Twitter publishing is enabled for this member. We may set this value to false if the user's Twitter publishing fails. You should check that twitter_access_valid is true prior to setting this value. If it is false , you should require the user to authenticate or reauthenticate against Twitter before attempting to set it to true .
|
Optional |
linkedin_access_valid
|
boolean
|
true or false
|
Whether or not our connection to LinkedIn for this user is valid. If this value is false , the user must authenticate or reauthenticate against LinkedIn to continue publishing.
|
Read only | |
linkedin_enabled
|
boolean
|
true or false
|
false
|
Whether or not LinkedIn publishing is enabled for this member. We may set this value to false if the user's LinkedIn publishing fails. You should check that linkedin_access_valid is true prior to setting this value. If it is false , you should require the user to authenticate or reauthenticate against LinkedIn before attempting to set it to true
|
Optional |
listings_enabled
|
boolean
|
true or false
|
true
|
Whether or not local listings will be published for this member, when available. | Optional |
auto_like
|
boolean
|
true or false
|
true
|
Whether or not to automatically “like” posts on Facebook. | Optional |
click_tracking
|
boolean
|
true or false
|
true
|
Whether or not to automatically “like’ posts on Facebook. | Optional |
branded_content
|
boolean
|
true or false
|
true
|
Whether or not to show a bar with the user's name and contact information at the top of the content shown when clicking links we post to the user's social media accounts. | Optional |
post_hashtags
|
boolean
|
true or false
|
false
|
Whether or not to use hashtags in posts to the user's social media accounts. | Optional |
brokerage
|
string
|
The user's brokerage. | Optional * | ||
broker_address
|
string
|
The user's brokerage address. | Optional * | ||
phone
|
string
|
Valid 9-digit phone number. | The user's phone number. | Optional * | |
tags
|
array , members must be integer
|
[] | Valid tag IDs | Array of one or more publishing tags. If no tags are set, no publishing will occur. | Optional |
publish_days
|
array , members must be integer
|
[] |
0 - 6
|
Array of one or more days of the week to publish. Days of the week are represented numerically (0 = Sunday, 6 = Saturday). | Optional |
primary_market
|
string
|
City and state of primary publishing market. | Read only | ||
secondary_market
|
string
|
City and state of primary publishing market. | Read only | ||
primary_market_place_id
|
string
|
The Google Place ID of the primary publishing market for this account. |
Write only. Use primary_market to read the secondary market set on this account. You must use this parameter to change the primary_market value.
|
||
secondary_market_place_id
|
string
|
The Google Place ID of the secondary publishing market for this account. |
Write only. Use secondary_market to read the secondary market set on this account. You must use this parameter to change the secondary_market value.
|
* Optional in API, but API account holders should require this information from their end users. CityBlast publishes it in various places to encourage potential leads to contact them.
CityBlast will return JSON-encoded data in response to your request.
Example JSON response to GET request, or to a POST request that was successful:
{ "id": "123456", "first_name": "Joe", "last_name": "Agent", "email": "joe@realestatebrokerage.com", "publishing_enabled": true, "facebook_enabled": true, "twitter_enabled": false, "linkedin_enabled": false, "listings_enabled": true, "auto_like": true, "click_tracking": true, "branded_content": true, "brokerage": "Real Estate Brokerage, Inc.", "broker_address": "123 First St., Toronto, ON", "phone" : "555-443-2124", "publish_days" : [1,3,5], "tags" : [10680,10682,10683,10686,10690,10692,10696], "primary_market" : "Toronto, ON", "secondary_market" : "London, ON" }
Example JSON response when an error has occurred in response to a POST request:
{ "updated": "false", "error": "invalid_member_settings", "error_description": "Invalid value for parameter 'email'" }
When an account is not found, CityBlast will return a 404 HTTP response code, along with error JSON:
{ "updated": "false", "error": "invalid_member", "error_description": "Member not found" }
Access token scope required: listing
Once you have obtained a valid access token for a user, your site can publish listings to that user's account via the CityBlast API.
Listings may be created, ready, updated or deleted via RESTful calls to the listings endpoint. A GET request will return existing listing data. A POST request will create a listing (when no ID is present in the URL) or update a listing (when an ID is present in the URL). A DELETE request
Endpoint: https://www.cityblast.com/rest/listing/[:id]?access_token=[your_access_token]
Create a listing: make a POST request to the listings endpoint above. No ID should be present in the URL. The POST parameters must conform to the below requirements.
Read a listing: make a GET request to the listings endpoint above, making sure to pass the ID in the URL.
Update a listing: make a POST request to the listings endpoint above. And ID must be present in the URL. The POST parameters must conform to the below requirements.
Delete a listing: make a DELETE request to the listings endpoint above. And ID must be present in the URL.
Listing parameters:
Field name | Data type | Description | Required? |
---|---|---|---|
access_token
|
string
|
The access token obtained through the OAuth2 process for CityBlast user you want to post a listing on behalf of. Must be provided as a GET parameter in the endpoint URL, not a POST parameter. | Required |
id
|
integer
|
The listing ID. | Read-only |
message
|
string
|
The message text that will appear with this listing. | Required |
street_number
|
string
|
The numeric portion of the property address (123 Main St) | Required |
street
|
string
|
The street or highway portion of the property address (123 Main St) | Required |
apartment
|
string
|
The apartment or unit number of the property address. | Optional |
city
|
string
|
The city where the property is located. Must be in the form "New York, NY" or "New York, New York". | Required |
postal_code
|
string
|
The postal code where the property is located. | Required |
price
|
decimal
|
The price of the property. | Required |
mls
|
string
|
The MLS number of the property. | Optional |
square_footage
|
integer
|
The size of the property in square feet. | Optional |
bedrooms
|
integer
|
The property's number of bedrooms. | Optional |
extra_bedrooms
|
integer
|
The property's number of extra bedrooms. | Optional |
bathrooms
|
decimal
|
The property's number of bathrooms. | Optional |
parking_spaces
|
integer
|
The property's number of parking spaces. | Optional |
maintenance_fee
|
string
|
The property's maintenance fees, if any. | Optional |
photos[]
|
binary data
|
Array of photo data. Each photo be posted in one or multiple fields, all named "photos[]". | Required |
property_type
|
integer
|
The property type, one of:
|
Required |
property_status
|
string
|
May be NEW, SOLD, EXPIRED, or PRICE_REDUCED. Setting this to SOLD or EXPIRED automatically stops publishing of the listing. | Optional |
approval_status
|
string
|
May be PENDING, PUBLISHED or REJECTED. When PUBLISHED, listing will be published on social media accounts of other members in the member's city over time. When REJECTED, the listing does not meet the criteria for listings we accept. Note that listings are immediately published to the access token's member's own social media accounts regardless of review status. | Read-only |
coordinates
|
string
|
Must be a comma-separated latitude and longitude (e.g. "43.6532,79.3832") | Optional. Omit or pass an empty value for this to be automatically geocoded by the listing's address. |
created_at ISO8601 format
|
string
|
The date this listing was created. | Read-only |
expires_at Y-m-d
|
string
|
The date this listing expires. If the listing has not already been disabled by setting status to SOLD or EXPIRED, we will automatically stop publishing it on this date.
|
Required |
CityBlast will always return a JSON response to your request.
Example JSON response when listing is read:
{ "id": "123456", "message": "", "street_number": "333", "street": "First St", "apartment": "", "city": "Anytown, CA", "postal_code": 65432, "price": "249000", "mls": "413273569", "square_footage": 1850, "bedrooms": "2", "extra_bedrooms": "0", "bathrooms": "1.5", "parking_spaces": "2", "maintenance_fee": "", "photos" : [ { "original":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image.jpg", "1200x0":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_1200x0.jpg", "658x0":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_658x0.jpg", "280x250":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_280x250.jpg", "276x182":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_276x182.jpg", "76x76":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_76x76.jpg" } ], "property_type": 1, "property_status": "NEW", "approval_status": "PUBLISHED", "coordinates": "43.6532,79.3832", "created_at": "2024-11-06T21:45:21-05:00", "expires_at": "2024-12-06" }
Example JSON response when listing has been created:
{ "created": "true", "id": "123456", "message": "", "street_number": "333", "street": "First St", "apartment": "", "city": "Anytown, CA", "postal_code": 65432, "price": "249000", "mls": "413273569", "square_footage": 1850, "bedrooms": "2", "extra_bedrooms": "0", "bathrooms": "1.5", "parking_spaces": "2", "maintenance_fee": "", "photos" : [ { "original":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image.jpg", "1200x0":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_1200x0.jpg", "658x0":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_658x0.jpg", "280x250":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_280x250.jpg", "276x182":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_276x182.jpg", "76x76":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_76x76.jpg" } ], "property_type": 1, "property_status": "NEW", "approval_status": "PENDING", "coordinates": "43.6532,79.3832", "created_at": "2024-11-06T21:45:21-05:00", "expires_at": "2024-12-06" }
Example JSON response when listing has been updated:
{ "updated": "true", "id": "123456", "message": "", "street_number": "333", "street": "First St", "apartment": "", "city": "Anytown, CA", "postal_code": 65432, "price": "249000", "mls": "413273569", "square_footage": 1850, "bedrooms": "2", "extra_bedrooms": "0", "bathrooms": "1.5", "parking_spaces": "2", "maintenance_fee": "", "photos" : [ { "original":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image.jpg", "1200x0":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_1200x0.jpg", "658x0":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_658x0.jpg", "280x250":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_280x250.jpg", "276x182":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_276x182.jpg", "76x76":"http:\/\/assets-static-cityblast.s3-website-us-west-2.amazonaws.com/path/to/image_76x76.jpg" } ], "property_type": 1, "property_status": "NEW", "coordinates": "43.6532,79.3832", "created_at": "2024-11-06T21:45:21-05:00", "expires_at": "2024-12-06" }
Example JSON response when an error has occurred:
{ "created": "false", "error": "invalid_listing", "error_description": "A listing with this information already exists." }
Errors are returned in the following JSON format:
{ "error": "invalid_listing", "error_description": "A listing with this information already exists." }
Possible error
values
Your code should be capable of handling these errors gracefully:
Error | Description |
---|---|
invalid_listing
|
Incorrect or missing listing information |
invalid_listing_image
|
One or more listing images could not be accepted (due to incorrect format, invalid file data or interrupted upload) |
invalid_listing_location
|
Valid listing city and state was not provided or invalid. |
invalid_token
|
The access token provided has expired or been revoked (possibly due to a lapsed CityBlast account) |
malformed_token
|
The string provided does not appear to be an access token. |
insufficient_scope
|
The member has declined (during OAuth authorization) or revoked the permission required to take the requested action. |
insufficient_scope
|
The member has declined (during OAuth authorization) or revoked the permission required to take the requested action. |
These errors are possible, and likely indicate a bug in your implementation. The error_description
value will provide specifics in each case.
Error |
---|
invalid_grant
|
invalid_request
|
invalid_client
|
invalid_uri
|
redirect_uri_mismatch
|
unsupported_response_type
|
unauthorized_client
|
invalid_scope
|
Normally, members must first sign up with CityBlast to create an account, then authorize any third-party operations via OAuth authentication.
API accounts who have been given permission to create members may use the /rest/member/create
endpoint to create member accounts with a pre-provisioned OAuth access token. No member parameters can be posted to this endpoint—its only functionality is to initialize a member account.
After sending a POST
request to /rest/member/create
, you will receive back data similar to the example below. To do anything further with this account, you must next have the user authenticate against Facebook through our Pass-through OAuth mechanism.
Example JSON response when member has been created:
{ "created": "true", "id": "123456" "access_token": "e62f1900c6b12c875fc64fa915309b09c2517530" }
Pass-Through OAuth allows your end users to connect their social media accounts to CityBlast without needing to interact with our site (in most cases).
The cornerstone of CityBlast's ability to publish to our members' social media accounts is the OAuth authentication functionality provided by social media networks. OAuth provides a means of authorizing CityBlast to publish to those accounts and gather statistics.
Normally, your end users would need to separately log into CityBlast and provide this authorization, but when you provision CityBlast accounts through our API you can use Pass-Through OAuth to offer this functionality directly on your own site, without requiring your end users to take any action on the CityBlast site in most cases.
Pass-Through OAuth works much the same way that regular OAuth2 authentication works at Facebook, Twitter and LinkedIn, with an additional redirect at the beginning and end of the process. To use it, you link your users to a URL in the following format:
https://www.cityblast.com/auth/login?access_token=e62f1[...]&redirect=http://yoursite.com/settings
Both the access_token
and redirect
URL parameters are required.
Sending your user to this URL will do the following:
1. Silently redirect the user to Facebook to authorize the CityBlast Facebook app. The user must proceed with this step to allow CityBlast to post to his or her Facebook account.
2. Return the user to the CityBlast site, where our servers can then request and store basic information (name and email address) from Facebook.
3. In most cases, we won't show your user anything (they will only see the pages that Facebook, Twitter or LinkedIn display in the authentication process). However, if we determine that they already have a pre-existing CityBlast account, we'll show them a page asking them to grant you access to it.
4. Finally, we'll redirect the user to the URL specified in the redirect
parameter specified above. We will append an authentication_status
parameter to your redirect URL with a value of success
when authentication has succeeded. In the example above, we would redirect the user to http://yoursite.com/settings?authentication_status=success
.
This documentation covers Facebook only. Twitter and LinkedIn authentication must be done in similar ways. Documentation for these is forthcoming.
Get Started.
You'll need an API key and an API secret, something our professional services team would be happy to help with!
Seamlessly integrate all of the great functions of CityBlast. Get Involved.