Please enter the contact information and intended API usage for review by our engineers. 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.
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=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyYou 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
URL for utility api is: /utility_api/v1
Sample Request:
POST https://start.realvolve.com/oauth/token?grant_type=client_credentials&client_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&client_secret=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyTo 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)
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 /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:
{
"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 /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 /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 /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 /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 /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"
}
]
}
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
}
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=5ZsCAjsi7xa3jV1ZpbdheYuJd1Fp3vYNnSwNZEzr&contact%5Bprimary%5D%5Bfirst_name%5D=Zooth&contact%5Bprimary%5D%5Bworkflow_id%5D=2843&contact%5Bprimary%5D%5Blast_name%5D=Ziggs&contact%5Bprimary%5D%5Bcreator_id%5D=615&contact%5Bdetails%5D%5Baddress%5D%5Bwork_address%5D=3568%20Front%20St%2C%20San%20Diego%2C%20CA&contact%5Bdetails%5D%5Bemail_address%5D%5Bwork_email%5D=zeeth%40gmail.com&contact%5Bdetails%5D%5Btags%5D=mobile-app
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
}
}
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 /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!",
...
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"
}
}
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 /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": "<p>Dear [[Greeting]], <br>\n<br>\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.<br>\n<br>\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.<br>\n<br>\nPlease contact us any time you have a question or concern.<br>\n<br>\nSincerely,<br>\n<br>\n<br>\n[[Signature]] <br>\n</p>",
"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"
}
]
}
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
}
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"
}
]
}
POST /utility_api/v1/showings
params:
utility_api_key with value of utility_api_key_of_this_user (string)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"
}
}
© 2011-2016 Realvolve, LLC.