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:

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:

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.

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:

* 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:

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-21T01:32:40-05:00",
        "expires_at": "2024-12-21"
    }
                                

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-21T01:32:40-05:00",
        "expires_at": "2024-12-21"
    }
                                

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-21T01:32:40-05:00",
        "expires_at": "2024-12-21"
    }
                                

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:

These errors are possible, and likely indicate a bug in your implementation. The error_description value will provide specifics in each case.

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). 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.