Authentication Steps

1. Signup for API Access

Please enter the contact information and intended API usage for review by our engineers on this link: [CLICK HERE]

An email containing credential information will be sent after approval.

If you have questions about our API, please contact Mark Stepp at mark@realvolve.com.

2. Request Access Token

POST to /oauth/token with the following params:
grant_type with a value of client_credentials
client_id with a value of the application id you got when you created your application in previous step
client_secret with a value of the application secret you get when creating your application in previous step

Note: Base URL is “https://start.realvolve.com” and is used on all API calls, documentation only shows URL after base.

Sample Request:

POST https://start.realvolve.com/oauth/token?grant_type=client_credentials&client_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&client_secret=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

You should receive a json response like this:

{ “access_token”: “xxxxxxxxxxx”, “token_type”: “bearer”, “expires_in”: 7200, “created_at”: 1455665559 }

Tokens EXPIRE every two hours. You will receive a status 401 Unauthorized if the token has expired. Simply make the call above again to get a new token.

For most API calls you will also need the user’s utility_api_key. They can find this on their settings > integrations screen

3. Authenticate every request to Utility API

URL for utility api is: /utility_api/v1

Sample Request:

To authenticate your calls you must include a header consisting of: name: Authorization value: Bearer access_token_from_previous_step

If you receive a status 401, you have taken a wrong turn.

Most calls require a utility_api_key as a required param. This key is unique to each RV user and can be found by the user at settings > integrations (at the bottom of the page). It can also be retrieved in the response of the call below (User Login)

Contacts

Get Contacts

GET /utility_api/v1/contacts

params:

utility_api_key with value of utility_api_key_of_this_user (string)
page with value of page number of results (pages are limited to 1000 results) (integer)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “pages”: 1, “data”: [ { “first_name”: “Cary”, “id”: 904144, “last_name”: “Siegler”, “profile_pic_url”: { “url”: null, “large”: { “url”: null }, “thumb”: { “url”: null }, “small_thumb”: { “url”: null }, “package_image_thumb”: { “url”: null } } } ] }

Get Recently Updated Contacts

GET /utility_api/v1/contacts/recent_contacts

params:

utility_api_key with value of utility_api_key_of_this_user (string)
updated_time with value of time you want to start searching for updated_at (datetime)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

Get Contact Details

GET /utility_api/v1/contacts/contact_detail

params:

utility_api_key with value of utility_api_key_of_this_user (string)
contact_id with value of id_of_contact_you_want_details_of (integer)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “email_addresses”: [ { “category_id”: 1, “email_address”: “zeeth@gmail.com”, “entity_id”: 904134, “entity_type”: “Contact”, “google_type”: “work”, “id”: 537838, “import_session_uuid”: null, “matching_import_uuid”: null, “pairing_import_uuid”: null } ], “addresses”: [ { “address”: “3568 Front St, San Diego, CA”, “address_line”: “Front St”, “backfill_required”: false, “category_id”: 1, “country”: “US”, “county”: null, “courier_route”: null, “created_at”: “2016-03-23T22:13:39Z”, “direction_prefix”: null, “entity_id”: 904134, “entity_type”: “Contact”, “geo_city”: “San Diego”, “geo_state”: “CA”, “google_type”: “work”, “id”: 1009157, “import_session_uuid”: null, “imported_address_id”: null, “latitude”: 32.74273, “longitude”: -117.165281, “matching_import_uuid”: null, “name”: null, “pairing_import_uuid”: null, “street_number”: “3568”, “updated_at”: “2016-03-23T22:13:39Z”, “zipcode”: “92103” } ], “phone_numbers”: [ { “category_id”: 1, “created_at”: “2016-03-23T22:13:39Z”, “entity_id”: 904134, “entity_type”: “Contact”, “google_type”: “work”, “id”: 487491, “import_session_uuid”: null, “matching_import_uuid”: null, “pairing_import_uuid”: null, “phone_number”: “843-697-3932”, “phone_type”: “phone”, “plain_phone_number”: “+18436973932”, “updated_at”: “2016-03-23T22:13:39Z” } ], “tags”: [ { “cached_slug”: “hot-buyer-0sx2n7jsp3”, “id”: 4468, “name”: “hot-buyer”, “rendered_at”: “2016-03-08T21:40:07Z” }, { “cached_slug”: “mobile-app-371ftsa6s”, “id”: 4467, “name”: “mobile-app”, “rendered_at”: “2016-03-08T01:04:44Z” } ], “notes”: [] }

Get Contact Sources

GET /utility_api/v1/contacts/contact_sources

params:

utility_api_key with value of utility_api_key_of_this_user (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: [ { “account_id”: 143, “created_at”: “2015-06-10T09:56:32Z”, “id”: 160, “is_custom”: true, “name”: “Dev”, “updated_at”: “2015-06-10T09:56:32Z” }, { “account_id”: 143, “created_at”: “2015-08-17T06:31:30Z”, “id”: 194, “is_custom”: false, “name”: “Events”, “updated_at”: “2015-08-17T06:31:30Z” }, { “account_id”: 143, “created_at”: “2015-08-14T08:09:53Z”, “id”: 186, “is_custom”: true, “name”: “Gmail”, “updated_at”: “2015-08-14T08:17:58Z” }] }

Get Contact Statuses

GET /utility_api/v1/contacts/contact_statuses

Use this endpoint to get the available readable names for the contact_status_id in a Contact record

params:

utility_api_key with value of utility_api_key_of_this_user (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: [ { “created_at”: “2015-06-26T07:15:21Z”, “id”: 1, “name”: “Suspect”, “updated_at”: “2015-06-26T07:15:21Z” }, { “created_at”: “2015-06-26T07:15:21Z”, “id”: 2, “name”: “Prospect”, “updated_at”: “2015-06-26T07:15:21Z” }, { “created_at”: “2015-06-26T07:15:21Z”, “id”: 3, “name”: “Lead”, “updated_at”: “2015-06-26T07:15:21Z” }, { “created_at”: “2015-06-26T07:15:21Z”, “id”: 4, “name”: “Client”, “updated_at”: “2015-06-26T07:15:21Z” }, { “created_at”: “2015-06-26T07:15:21Z”, “id”: 5, “name”: “Past Client”, “updated_at”: “2015-06-26T07:15:21Z” } ] }

Get Account Tags

GET /utility_api/v1/contacts/account_tags

Use this endpoint to get the full list of account_tags for the user’s account

params:

utility_api_key with value of utility_api_key_of_this_user (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: [ { “cached_slug”: “cpt-2bj3yb64dod42”, “id”: 4444, “name”: “cpt”, “rendered_at”: “2016-02-28T00:26:31Z” }, { “cached_slug”: “7-years”, “id”: 2110, “name”: “7 Years”, “rendered_at”: “2016-02-28T00:33:31Z” } ] }

Get Available Workflows

GET /utility_api/v1/contacts/workflows

params:

utility_api_key with value of utility_api_key_of_this_user (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: [ { “alternate_workflow_id”: null, “cached_slug”: “3939-beson-7-years”, “created_at”: “2016-03-30T22:17:39Z”, “creator_id”: 615, “deleted_at”: null, “description”: null, “downloaded”: true, “id”: 3939, “import_session_uuid”: null, “import_status_id”: null, “instance”: false, “is_active_instance”: false, “mark_for_deletion”: false, “matching_import_uuid”: null, “pairing_import_uuid”: null, “progenitor_id”: null, “rendered_at”: “2015-03-19T10:30:08Z”, “title”: “Beson: 7 Years”, “updated_at”: “2016-03-30T22:17:39Z”, “use_with”: “Contact” } ] }

Start Contact Workflow

POST /utility_api/v1/contacts/:id/assign_workflow

params:

utility_api_key with value of utility_api_key_of_this_user (string)
workflow_id with value of id_of_the_workflow (integer)
contact_id with value of id_of_the_contact (integer)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true }

Create Contact

POST /utility_api/v1/contacts

params:

utility_api_key with value of utility_api_key_of_this_user (string)
contact[primary][first_name] with value of first_name_of_contact (string)
contact[primary][last_name] with value of last_name_of_contact (string)
contact[details][address][work_address] with value of work_address_of_contact (string)
contact[details][address][home_address] with value of home_address_of_contact (string) (example: 3568 Front St, San Diego, CA)
contact[details][email_address][work_email] with value of work_email_of_contact (string)
contact[details][email_address][home_email] with value of home_email_of_contact (string)
contact[details][phone_number][home_mobile] with value of home_mobile_phone_of_contact (string)
contact[details][phone_number][home_phone] with value of home_phone_of_contact (string)
contact[details][tags] with value of tag (string)
contact[primary][contact_source] with value of name-of-source (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Request:

POST https://start.realvolve.com/utility_api/v1/contacts?utility_api_key=

Sample Response:

{ “success”: true, “msg”: “Contact created successfully.”, “contact”: { “animoto_link”: null, “annual_income”: null, “birth_date”: null, “blog_link”: null, “cached_slug”: “904125-zooth-ziggs”, “category”: null, “client_id”: null, “company”: null, “contact_score”: 2, “contact_source_link”: null, “contact_source_type_id”: null, “contact_status_id”: null, “created_at”: “2016-03-08T01:04:40Z”, “creator_id”: 615, “deleted_at”: null, “dropbox_link”: null, “email_folder_link”: null, “enhanced_google_map_link”: null, “evernote_link”: null, “facebook_invalid”: false, “facebook_profile_link”: null, “fb_uid”: null, “first_name”: “Zooth”, “google_drive_link”: null, “google_plus_link”: null, “has_synced”: false, “home_purchase_anniversary”: null, “id”: 904125, “import_engine”: null, “import_id”: null, “import_session_uuid”: null, “import_status_id”: null, “imported_at”: null, “imported_contact_id”: null, “imported_referred_by_id”: null, “inactive”: false, “instagram_link”: null, “is_special_contact”: false, “known_since”: 2016, “last_call_date”: null, “last_google_synced_at”: null, “last_name”: “Ziggs”, “last_personal_note_date”: null, “last_personal_visit_date”: null, “last_updated_at”: “2016-03-08T01:04:43Z”, “lifetime_value”: null, “linkedin_invalid”: false, “linkedin_link”: null, “mark_for_deletion”: false, “matching_import_uuid”: null, “pairing_import_uuid”: null, “pinterest_link”: null, “prefix”: null, “profile_pic_url”: { “url”: null, “large”: { “url”: null }, “thumb”: { “url”: null }, “small_thumb”: { “url”: null }, “package_image_thumb”: { “url”: null } }, “propinquity_points”: null, “record_type”: 0, “referred_date”: null, “referrer_id”: null, “rendered_at”: null, “rent_own”: “”, “rss_link”: null, “savvycard_link”: null, “sex”: null, “source”: null, “source_id”: null, “stage”: null, “suffix”: null, “sync_in_progress”: false, “title”: null, “twitter_handle”: null, “twitter_invalid”: false, “updated_at”: “2016-03-08T01:04:43Z”, “viewed_at”: null, “year_moved”: null, “youtube_link”: null } }

Edit Contact

POST /utility_api/v1/contacts/update_contact

params:

utility_api_key with value of utility_api_key for this user (string)(REQUIRED)
contact_id with value of id of the contact (integer)(REQUIRED)
contact[primary][first_name] with value of first_name_of_contact (string)
contact[primary][last_name] with value of last_name_of_contact (string)
contact[primary][creator_id] with value of id_of_user_of_app (integer) (Plus any available field that appears in the GET /contacts calls)
contact[details][address][work_address] with value of work_address_of_contact (string)
contact[details][address][home_address] with value of home_address_of_contact (string) (example: 3568 Front St, San Diego, CA)
contact[details][email_address][work_email] with value of work_email_of_contact (string)
contact[details][email_address][home_email] with value of home_email_of_contact (string)
contact[details][phone_number][work_phone] with value of work_phone_of_contact (integer)
contact[details][phone_number][home_phone] with value of home_phone_of_contact (integer)
contact[details][tags] with value of tag_name (string) NOTE: this will add tags to list of existing tags. If you wish to remove tags and submit new ones, you can do so by submitting this param: contact[details][tag_list] with a value of overwrite. In this format, you can submit a comma separated list of tags which will replace the list of tags currently saved to this contact.

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Request:

POST https://start.realvolve.com/utility_api/v1/contacts/update_contact?utility_api_key=5ZsCAjsi7xa3jV1ZpbdheYuJd1Fp3vYNnSwNZEzr&contact%5Bdetails%5D%5Baddress%5D%5Bhome_address%5D=3568%20Front%20St%2C%20San%20Diego%2C%20CA&contact%5Bdetails%5D%5Bemail_address%5D%5Bhome_email%5D=usaseth%40gmail.comm&contact%5Bdetails%5D%5Btags%5D=mobile-app%2C%20hot-buyer&contact%5Bprimary%5D%5Bcontact_source%5D=realvolve-app&contact%5Bdetails%5D%5Bphone_number%5D%5Bhome_phone%5D=8436973932&contact%5Bprimary%5D%5Bcompany%5D=Hoverboard%20Labs%2C%20Inc&contact%5Bprimary%5D%5Btitle%5D=CEO&contact%5Bdetails%5D%5Baddress%5D%5Bwork_address%5D=2372%20First%20Ave%2C%20San%20Diego%2C%20CA&contact%5Bdetails%5D%5Bemail_address%5D%5Bwork_email%5D=seth%40hoverboardlabs.comm&contact%5Bdetails%5D%5Bphone_number%5D%5Bwork_phone%5D=8585555555&contact_id=1045454

Sample Response:

{ “success”: true, “data”: { “animoto_link”: null, “annual_income”: null, “birth_date”: null, “blog_link”: null, “cached_slug”: “904145-cary-siegler”, “category”: null, …

Get Contact Showings

GET /utility_api/v1/contacts/showings

params:

utility_api_key with value of utility_api_key_of_this_user (string)
contact_id with value of id_of_the_contact (integer)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: [ { “activity_state_id”: null, “agent_note”: “Yo agent!”, “contact_id”: 904139, “created_at”: “2016-04-28T01:42:49Z”, “date”: “2016-04-28”, “date_sent”: “2016-04-30”, “feedback”: “Good but could be better”, “id”: 366, “message_to_seller”: “Not a bad place!”, “other_property_address”: “”, “property_id”: 43529, “property_listing_type”: false, “rating”: 9, “seller_report_id”: 2991, “time”: “1:00pm”, “updated_at”: “2016-04-28T01:42:49Z”, “user_name”: “Rasika Tambitkar” }, { “activity_state_id”: null, “agent_note”: “Yo agent!”, …

Add Contact Note

POST /utility_api/v1/contacts/add_note

params:

utility_api_key with value of utility_api_key_of_this_user (string)
contact_id with value of id_of_the_contact (integer)
note_content with value of content_of_the_note (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: { “bcc_email_address_with_ids”: null, “body”: null, “cc_email_address_with_ids”: null, “content”: “New note from the API”, “created_at”: “2016-05-07T01:03:16Z”, “creator_id”: 615, “delivered”: true, “delivery_message”: null, “email_address_with_ids”: null, “entity_id”: 904139, “entity_type”: “Contact”, “feed_id”: null, “feed_timestamp”: 1462582996, “from”: “realvolve”, “guid”: null, “id”: 1578367, “import_session_uuid”: null, “mark_for_deletion”: false, “matching_import_uuid”: null, “note_type”: null, “pairing_import_uuid”: null, “pinned”: false, “rendered_at”: null, “title”: null, “to”: null, “transitory”: false, “updated_at”: “2016-05-07T01:03:16Z” } }

Emails

Send Contact Email

POST utility_api/v1/emails

params:

utility_api_key with value of utility_api_key_of_this_user (string)
to with value of id_of_the_contact (integer)
body with value of body of the email (string)
html with value of html content of the email (string)
plain with value of plain text version of the html part (string)
subject with value of subject for the email (string)
message with value of message for the email (string)
courier_type with value of 1 (integer)
current_user_id with value of id of the current user (integer)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true }

Get Email Templates

GET /utility_api/v1/emails/get_templates

params:

utility_api_key with value of utility_api_key_of_this_user (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: [ { “body”: “Dear [[Greeting]], \n \nThank you for your confidence in hiring us as your Buyer Broker to help you in finding the perfect home. We will contact you shortly to firm up our game plan and timetable. \n \nAs we move forward together, we will be in touch frequently to keep you aware of progress on every step of the process; pre-approval, property lists, property showings, contracting, inspections, appraisal, negotations, etc., until we can present you with the keys to your new home. Rest assured we will do everything in our power, based on our many years of combined experience to make your journey to your new home as painless and pleasurable as possible. \n \nPlease contact us any time you have a question or concern. \n \nSincerely, \n \n \n[[Signature]] \n”, “cached_slug”: “message-templatetransaction-0pxq”, “courier_type_id”: 1, “created_at”: “2016-03-30T22:17:39Z”, “creator_id”: 615, “default_template”: false, “deleted_at”: null, “downloaded”: true, “id”: 6935, “import_session_uuid”: null, “import_status_id”: null, “mark_for_deletion”: false, “matching_import_uuid”: null, “pairing_import_uuid”: null, “rendered_at”: “2015-03-19T10:30:58Z”, “subject”: “Thanks For Hiring Us”, “title”: “Message Template(Transaction)”, “updated_at”: “2016-03-30T22:17:39Z”, “use_with”: “Escrow” } ] }

SMS

Send Contact SMS

POST /utility_api/v1/text_messages

params:

utility_api_key with value of utility_api_key_of_this_user (string)
to with value of phone number of a RV contact (integer)
content with value of content of the SMS (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true }

Properties

Get All Properties

GET /utility_api/v1/properties

params:

utility_api_key with value of utility_api_key_of_this_user (string)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: [ { “acreage”: null, “address_line”: null, “agent_marketing_narrative”: null, “alarm_code”: null, “animoto_link”: null, “annual_property_tax”: null, “area_in_sq_feet”: null, “assessor_parcel_number”: null, “association_details”: null, “average_monthly_utility_cost”: null, “bedrooms”: null, “blog_link”: null, “brochure_delivery_date”: null, “broker_open_date”: null, “broker_open_time”: null, “buy_side_commission”: null, … “youtube_link”: null, “zillow_link”: null, “zipcode”: “17055” } ] }

Showings

Add Property Seller Report (Showing)

POST /utility_api/v1/showings

params:

utility_api_key with value of utility_api_key_of_this_user (string)
‘property_id’ (integer)
seller_report_id (integer)
contact_id (integer)
message_to_seller (string)
time (string)
rating (integer)
feedback (string)
agent_note (string)
other_property_address (string) (optional)

Headers: Name: Authorization value: Bearer access_token_from_step_two_of_authentication

Sample Response:

{ “success”: true, “data”: { “activity_state_id”: null, “agent_note”: “Here’s an agent note”, “contact_id”: null, “created_at”: “2016-06-17T20:09:59Z”, “date”: “2016-06-17”, “date_sent”: “2016-06-17”, “feedback”: “Here’s some feedback for you”, “id”: 367, “message_to_seller”: “Yo seller, here’s a message”, “other_property_address”: null, “property_id”: 5, “property_listing_type”: false, “rating”: 6, “seller_report_id”: 2991, “time”: “11:00am”, “updated_at”: “2016-06-17T20:09:59Z”, “user_name”: “Rasika Tambitkar” } }