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

User Authorization

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, uou'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.

Get Member Account Settings

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"
}
                        
Manage Listings

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:
  • 1 (Detached)
  • 2 (Semi-detached)
  • 3 (Freehold Townhouse)
  • 4 (Condo Townhouse)
  • 5 (Attached Townhouse)
  • 6 (Condo Apartment)
  • 7 (Coop/Common Elements)
  • 8 (Lot)
  • 9 (Business/Commercial)
  • 10 (Other)
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-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image.jpg",
    	"1200x0":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_1200x0.jpg",
    	"658x0":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_658x0.jpg",
    	"280x250":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_280x250.jpg",
    	"276x182":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_276x182.jpg",
    	"76x76":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_76x76.jpg"
    	}
    ],
    "property_type": 1,
    "property_status": "NEW",
    "approval_status": "PUBLISHED",
    "coordinates": "43.6532,79.3832",
    "created_at": "2017-09-22T23:38:27-04:00",
    "expires_at": "2017-10-22"
}
                            

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-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image.jpg",
    	"1200x0":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_1200x0.jpg",
    	"658x0":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_658x0.jpg",
    	"280x250":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_280x250.jpg",
    	"276x182":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_276x182.jpg",
    	"76x76":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_76x76.jpg"
    	}
    ],
    "property_type": 1,
    "property_status": "NEW",
    "approval_status": "PENDING",
    "coordinates": "43.6532,79.3832",
    "created_at": "2017-09-22T23:38:27-04:00",
    "expires_at": "2017-10-22"
}
                            

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-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image.jpg",
    	"1200x0":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_1200x0.jpg",
    	"658x0":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_658x0.jpg",
    	"280x250":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_280x250.jpg",
    	"276x182":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_276x182.jpg",
    	"76x76":"http:\/\/assets-cityblast.s3-website-us-east-1.amazonaws.com/path/to/image_76x76.jpg"
    	}
    ],
    "property_type": 1,
    "property_status": "NEW",
    "coordinates": "43.6532,79.3832",
    "created_at": "2017-09-22T23:38:27-04:00",
    "expires_at": "2017-10-22"
}
                            

Example JSON response when an error has occurred:

{
    "created": "false",
    "error": "invalid_listing",
    "error_description": "A listing with this information already exists."
}
                            
API error types

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
Pass-through OAuth: Create Member Account

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: Social Media Integration

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). It is not related to our OAuth user authentication, which allows your site to manage your end-users' CityBlast accounts and associated property listings.

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.