Dotsignal Web Services API

Matt Simons

Overview

By integrating the Virtual Agent Web Services API into your website, your users will have direct access to the features and processes driving the Virtual Agent technologies.

Benefits

Through the use of the API, your users can add and update properties, manage photos, retrieve lists of clients, assign property codes, create alert records for specific properties, and much more!

The Basics

The Virtual Agent API is built using PHP and the Zend SOAP framework. You may connect to the service using any of the many languages and frameworks that support the SOAP protocol.

There are five classes of methods built into the API:

Property methods
Client methods
Property Code methods
Alert Record methods
Lead methods
Company methods
SMS methods

Property methods

The property methods perform all operations relating to the properties the client manages. These include adding new properties, deleting properties, editing property details, retrieving property details, archiving a property, and adding, updating, and deleting photos.

Client methods

The client methods perform all operations relating to the client(s) the user administrates. These include getting the details on a specific client and retrieving a list of all clients managed by the user (such as all clients in the office).

Property Code methods

The property code methods are used when the user needs to assign a property code to a property, free a property code from a property, retrieve a list of all codes available to the client or company, and retrieve a list of all codes actively assigned to properties managed by the client or company.

Alert Record methods

The alert record methods allow the user to view all alerts on a specific client or property, create a new alert, and delete an alert or series of alerts.

Lead methods

The lead methods allow the user to pull lead counts for a company, region, or franchise.

Company methods

The company methods are used for retrieving lists of the franchises, regions, and offices within the Virtual Agent system.

SMS methods

For approved vendors only. The SMS methods are used for sending custom SMS messages to specified recipients.

Connecting to the API: The SOAP Client

The WSDL File

To set up your SOAP client to connect to the API, you will need to set the URI of the WSDL file as: http://api.virtualagentconnect.com/?wsdl

Calling the methods:

See the section “Working with the methods” for the names and parameters for all the available methods. Please note that all parameters must be entered in the correct order as listed in the argument tables. You may set any optional pararemter’s value as NULL if it is not applicable.

SOAP XML Request:

The SOAP client will encode the function call as XML using the SOAP Envelope and SOAP Encoding namespaces. Here is an example of the request sent when calling the getAlertRecord function:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
              xmlns:ns1="http://api.virtualagentconnect.com/" 
              xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
    <env:Body>
        <ns1:getAlertRecord env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
            <auth_username xsi:type="xsd:string">email@email.com</auth_username>
            <auth_passcode xsi:type="xsd:string">password</auth_passcode>
            <property_id xsi:nil="true"/>
            <client_id xsi:type="xsd:int">0</client_id>
            <vendor_id xsi:nil="true"/>
        </ns1:getAlertRecord>
    </env:Body>
</env:Envelope>

SOAP XML Response:

The server responds with XML which can be automatically parsed into a SOAP object by the SOAP client. Here is an example of the server response returned from the getAlertRecord function:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
              xmlns:ns1="http://api.virtualagentconnect.com/index.php" 
              xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xmlns:ns2="http://xml.apache.org/xml-soap" 
              xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
    <env:Body xmlns:rpc="http://www.w3.org/2003/05/soap-rpc">
        <ns1:getAlertRecordResponse env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
            <rpc:result>return</rpc:result>
            <return xsi:type="enc:Struct">
                <responseCode xsi:type="xsd:int">1</responseCode>
                <responseDescription xsi:type="xsd:string">Success</responseDescription>
                <alerts enc:itemType="ns2:Map" enc:arraySize="3" xsi:type="enc:Array">
                    <item xsi:type="ns2:Map">
                        <item>
                            <key xsi:type="xsd:string">alert_id</key>
                            <value xsi:type="xsd:string">1</value>
                        </item>
                        <item>
                            <key xsi:type="xsd:string">client_id</key>
                            <value xsi:type="xsd:string">0</value>
                        </item>
                        <item>
                            <key xsi:type="xsd:string">alert_type</key>
                            <value xsi:type="xsd:string">SMS</value>
                        </item>
                        <item>
                            <key xsi:type="xsd:string">alert_value</key>
                            <value xsi:type="xsd:string">8015551111</value>
                        </item>
                        <item>
                            <key xsi:type="xsd:string">alert_sponsor</key>
                            <value xsi:type="xsd:string">No</value>
                        </item>
                    </item>
                </alerts>
            </return>
        </ns1:getAlertRecordResponse>
    </env:Body>
</env:Envelope>

Working with the methods

Here is a list of all methods supported by the Virtual Agent API as of version 1.0.

Property
addProperty	Add a new property to the database
deleteProperty	Delete a property from the database
editProperty	Edit the details of an existing property
getProperty	Retrieve all details of an existing property
archiveProperty	Archive an existing property without deleting
setPhoto	Insert or update a property photo or photos
purgePhoto	Delete a specific photo or all photos of a property
getPhoto	Retrieve details on all photos of existing property
pushValidation	Checks to see if a property exists

Client
getClient	Get the details of a specific client account
getClientList	Get the details on all clients in a specified office, region, franchise, etc.
createClient	Create a new client account
editClient	Edit a client's details

Property Code
assignPropertyCode	Assign a property code to a specified property
freePropertyCode	Remove a property code from a property
getAvailableCodes	Retrieve all available codes for a client or office
getAssignedCodes	Retrieve all assigned codes for a client or office
assignClientCodes	Assign a specified number of new property codes to a client

Alert Record
getAlertRecord	Retrieve alert records based on a specified client or property
createAlertRecord	Create a new alert record for a client or property
purgeAlertRecord	Delete an alert record for a client or property

Lead
leadCount	Retrieve a lead count for a specified date range and company, region, or franchise
monthlyLeadBreakdown	Retrieve a monthly lead count for the last 12 months for a specified company, region, or franchise

Company
getFranchises	Retrieve a list of franchises within the Virtual Agent system
getRegions	Retrieve a list of regions under a specific franchise
getCompanies	Retrieve a list of offices under a specific region

addProperty

The addProperty method will allow an external application to easily create new property records for an existing account within the Virtual Agent Connect platform. In order to use the addProperty method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account.

Once the user has passed authentication, a new property will be created in the Virtual Agent Connect platform and the property ID will be returned.

addProperty Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID to associate with property
Y	mls_number	Integer(20)
Y	street_number	String(10)
Y	street_name	String(65)
Y	city	String(35)
Y	state	String(2)
Y	zip	String(12)
	vendor_id	Integer	Vendor ID who administrates client
	county	String(30)
	list_price	String(20)
	schools	String(30)
	year_built	Integer(4)
	acres	String(10)
	lot_size	String(25)
	square_feet	String(6)
	beds	String(5)
	baths	String(5)
	taxes	String(20)
	assoc_fee	String(20)
	comments	String
	architecture	String(50)
	garage_desc	String(255)
	basement_desc	String(255)
	list_date	Date(0000-00-00)
	sms_override	String
	ivr_override	String
	wap_override	String
	youtube_id	String(25)
	photos	array	Ex: $photos = array(url1, url2, …);

addProperty Response

Response: A Soap Object consisting of the response code, response description, and property details will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
property	object	List of property details

‘property’ object: The property object contains the following variable names:

property_id
client_id
street_number
street_name
city
state
zip
county
mls_number
list_price
listing_type
schools
year_built
acres
lot_size
square_feet
beds
baths
taxes
assoc_fee
comments
architecture
garage_desc
basement_desc
list_date
is_archived
tour_url
use_override
sms_override
ivr_override
wap_override
data_source
youtube_id
photos (array)

‘photos’ array: The photos array contains an object for each photo. Each object contains the following variable names:

url
spot

deleteProperty

The deleteProperty method will allow an external application to delete a property record from an account within the Virtual Agent Connect platform. In order to use the deleteProperty method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account.

Once the user has passed authentication, the property will be deleted from the Virtual Agent Connect platform.

deleteProperty Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID associated with property
Y	property_id	Integer	Property ID to delete from database
	vendor_id	Integer	Vendor ID who administrates client

deleteProperty Response

Response: A Soap Object consisting of the response code, response description, and details of records deleted will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
property	object	Details of records deleted

‘property’ object: The property object contains the following variable names:

property_id
photos_deleted
leads_deleted
lead_logs_deleted

editProperty

The editProperty method will allow an external application to easily edit the details of a property record within the Virtual Agent Connect platform. In order to use the editProperty method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account.

Once the user has passed authentication, the property record will be updated in the Virtual Agent Connect platform.

editProperty Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID associated with property
Y	property_id	Integer	Property ID to edit
	vendor_id	Integer	Vendor ID who administrates client
	Plus any other field the user wants to update (see addProperty for full list of editable property fields). NOTE: to delete a value, pass an empty string. To leave a value as is, set it as NULL.

editProperty Response

Response: A Soap Object consisting of the response code, response description, and property details will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
property	object	List of property details

‘property’ object: see “addProperty Response” for complete description of property object

getProperty

The getProperty method will allow an external application to retrieve the details of an existing property within the Virtual Agent Connect platform. In order to use the getProperty method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account. Once the user has passed authentication, all details of the property will be returned.

getProperty Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID associated with property
Y	property_id	Integer	Property ID or MLS number to retrieve from database (only one is required)
Y	mls_number	Integer(20)
	zip	Integer	Zip code of property. Only required when multiple results found with mls_number
	vendor_id	Integer	Vendor ID who administrates client

getProperty Response

Response: A Soap Object consisting of the response code, response description, and details of property will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
property	object	List of property details

‘property’ object: see “addProperty Response” for complete description of property object

archiveProperty

The archiveProperty method will allow an external application to archive a property within the Virtual Agent Connect platform. In order to use the archiveProperty method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account.

Once the user has passed authentication, the property will be archived in the Virtual Agent Connect platform.

archiveProperty Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID associated with property
Y	property_id	Integer	Property ID to archive in database
	vendor_id	Integer	Vendor ID who administrates client

archiveProperty Response

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
property	object	List of property details

‘property’ object: see “addProperty Response” for complete description of property object

setPhoto

The setPhoto method will allow an external application to easily add or modify a property photo for an existing property within the Virtual Agent Connect platform. In order to use the setPhoto method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account.

Once the user has passed authentication, a property photo will be created or modified in the Virtual Agent Connect platform.

setPhoto Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID associated with property
Y	property_id	Integer	Property ID containing photo to edit
Y	photo_url	String	URL of photo to add to property
	photo_spot	Integer(2)	The spot # to put photo in. Must be between 1 and 25. If not provided, photo will be placed in next available spot
	vendor_id	Integer	Vendor ID who administrates client

setPhoto Response

Response: A Soap Object consisting of the response code, response description, and details of all of the property’s photos will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
photos	array	List of matching photo details

‘photos’ array: The photos array contains an object for each of the property’s photos with the following variable names:

url
spot

purgePhoto

The purgePhoto method will allow an external application to easily delete a photo or all photos for an existing property within the Virtual Agent Connect platform. In order to use the purgePhoto method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account.

Once the user has passed authentication, the appropriate photo(s) will be deleted from the Virtual Agent Connect platform.

purgePhoto Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID associated with property
Y	property_id	Integer	Property ID containing photo to delete
	photo_spot	Integer(2)	The spot # of photo to delete. If not provided, all property photos will be deleted
	vendor_id	Integer	Vendor ID who administrates client

purgePhoto Response

Response: A Soap Object consisting of the response code, response description, and details of all of the property’s photos will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
photos	array	List of property's photos with details

‘photos’ array: The photos array contains an object for each of the property’s photos with the following variable names:

url
spot

getPhoto

The getPhoto method will allow an external application to retrieve all photos for an existing property within the Virtual Agent Connect platform. In order to use the getPhoto method, you will be required to authenticate with a valid username and password.

Once the user has passed authentication, details of all photos for the property will be retrieved from the Virtual Agent Connect platform.

getPhoto Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	property_id	Integer	Property ID containing photos to retrieve

getPhoto Response

Response: A Soap Object consisting of the response code, response description, and details of matching photos will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
photos	array	List of matching photo details

‘photos’ array: The photos array contains an object for each matching photo with the following variable names:

url
spot

createTour

The createTour method will allow an external application to generate a YouTube Virtual Tour from the photos of a property within the Virtual Agent platform. In order to use the createTour method, you will be required to authenticate with a valid username, password, and vendor ID.

Once the user has passed authentication, the property will be added to the queue of tours to generate.

createTour Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	Vendor’s e-mail address
Y	auth_passcode	String	Vendor’s password
Y	vendor_id	Integer	Vendor's ID
Y	property_id	Integer	Property ID of tour to generate

createTour Response

Response: A Soap Object consisting of the response code and response description will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response

pushValidation

The pushValidation method will allow an external application to check whether a valid property can be found for a specific property ID or MLS number. No authentication is required.

pushValidation Request

Required	Index name	Value (max chars)	Comments
Y	property_id	Integer	Property ID or MLS number of property to search for (only one is required).
Y	mls_number	Integer(20)
	zip	String(12)	Required if multiple properties found by mls_number

pushValidation Response

Response: A Soap Object consisting of a single true or false value will be returned:

Index Name	Type	Comments
valid_property	bool	TRUE if unique property found, FALSE if no property or multiple properties found

getClient

The getClient method will allow an external application to retrieve all details of an existing client within the Virtual Agent Connect platform. In order to use the getClient method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account.

Once the user has passed authentication, all details of the specified client will be returned.

getClient Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	The ID or e-mail address of client to pull details (only one is required)
Y	client_email	String(45)
	vendor_id	Integer	Vendor ID associated with Client

getClient Response

Response: A Soap Object consisting of the response code, response description, and the client’s details will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
clients	object	Details of matching client

‘clients’ object: The clients object contains the following variable names:

client_id
agent_id
external_id
company_id
region_id
franchise_id
bill_id
admin
region_admin
franchise_admin
bill_plan
first_name
last_name
address
city
state
zip
phone
client_email
password
fax
option_email
option_sms
account_status
date_created
date_inactive
promotion_id
rep_code
vendor_id
account_type

getClientList

The getClientList method will allow an external application to retrieve details on all clients managed by a vendor, company, region, or franchise within the Virtual Agent Connect platform. In order to use the getClientList method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the vendor or an administrator with the proper permissions to manage the client accounts.

Once the user has passed authentication, all details of the matching clients will be returned.

getClientList Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	The ID of the vendor, franchise, region, or company of which to pull a list of clients. Only one is required.
	franchise_id	Integer
	region_id	Integer
	company_id	Integer

getClientList Response

Response: A Soap Object consisting of the response code, response description, and the details of all matching clients will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
clients	array	Details of all matching clients

‘clients’ array: The clients array contains an object for each matching client. See “getClient Response” for a list of the objects’ variable names.

createClient

The createClient method will allow an external application to create a new client within the Virtual Agent Connect platform. In order to use the createClient method, you will be required to authenticate. The username and password combination must match the e-mail address and password of a vendor user associated with the vendor_id passed in.

Once the user has passed authentication, the account will be created and the client details will be returned.

createClient Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	Vendor ID associated with Client
Y	first_name	String (30)	First name of Client to create
Y	last_name	String (45)
Y	address	String (45)	Street address of Client to create
Y	city	String (45)
Y	state	String (2)	2-character state abbreviation
Y	zip	String (10)
Y	phone	String (11)	Will be stored in format: 12225551234
Y	email	String (100)	Email address of client, also used as Client’s login
Y	password	String (32)	Password client will use to log in
	franchise_id	Integer	Franchise ID to associate with Client
	region_id	Integer	Region ID to associate with Client
	company_id	Integer	Company ID to associate with Client
	agent_id	String (50)	ID used to correlate Client with agentID of property feed
	fax	String (11)	Will be stored in format: 12225551234
	account_type	String	Optional. Acceptable values "Full" (default) and "Lite"
	admin	String	Optional. If passed in, will grant specified level of admin rights to client. Acceptable values: "Office", "Region", "Franchise". Default is no admin rights
	external_id	String	Optional. ID of client in external system

createClient Response

Response: A Soap Object consisting of the response code, response description, and the client’s details will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
clients	object	Details of the created client

‘clients’ object: See “getClient Response” for a list of the objects’ variable names.

editClient

The editClient method will allow an external application to edit the details of a client within the Virtual Agent Connect platform. In order to use the editClient method, you will be required to authenticate. The username and password combination must match the e-mail address and password of a vendor user associated with the vendor_id passed in.

Once the user has passed authentication, the account will be updated and the client details will be returned.

editClient Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	Vendor ID associated with Client
Y	client_id	Integer	Client ID of client to edit
	Plus any other field to update (see “createClient” for full list of editable client fields). NOTE: to delete a value, pass an empty string. To leave a value as is, set it as NULL.

editClient Response

Response: A Soap Object consisting of the response code, response description, and the client’s details will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
clients	object	Details of the client

‘clients’ object: See “getClient Response” for a list of the objects’ variable names.

disableClient

The disableClient method will allow an external application to disable access to Virtual Agent Services for a client and archive all properties and codes. In order to use the disableClient method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the vendor with the proper permissions to manage the client account.

Once the user has passed authentication, all details of the specified client will be returned.

disableClient Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	The ID of vendor who manages client
Y	client_id	Integer	The ID of client to disable

disableClient Response

Response: A Soap Object consisting of the response code and response description will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response

enableClient

The enableClient method will allow an external application to re-enable access to Virtual Agent Services for a client that has previously been disabled. In order to use the enableClient method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the vendor with the proper permissions to manage the client account.

Once the user has passed authentication, all details of the specified client will be returned.

enableClient Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	The ID of vendor who manages client
Y	client_id	Integer	The ID of client to enable

enableClient Response

Response: A Soap Object consisting of the response code and response description will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response

getAssignedCodes

The getAssignedCodes method will allow an external application to retrieve a list of all of the client’s or company’s property codes that are actively assigned to a property within the Virtual Agent Connect platform. In order to use the getAssignedCodes method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client or company account.

Once the user has passed authentication, a list of all assigned codes and their details will be returned.

getAssignedCodes Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
	vendor_id	Integer	The ID of the vendor, for authentication
Y	client_id	Integer	The ID of the client or company of which to pull a list of assigned codes. Only one is required.
Y	company_id	Integer
	property_id	Integer	If passed in, will limit returned codes to those assigned to this property only. Note: if passing in property_id, client_id must be provided and must be the client associated with this property

getAssignedCodes Response

Response: A Soap Object consisting of the response code, response description, and the details of all matching assigned codes will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
codes	array	Details of all matching assigned codes

‘codes’ array: The codes array contains an object for each matching code, with variable names of:

code_id
property_code
client_id
company_id
code_expires
property_id
street_number
street_name
marketing_medium

assignPropertyCode

The assignPropertyCode method will allow an external application to easily assign a property code to a specific property within the Virtual Agent Connect platform. In order to use the assignPropertyCode method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the property code.

Once the user has passed authentication, a property code will be assigned to the specified property within the Virtual Agent Connect platform.

assignPropertyCode Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID associated with property code
Y	property_id	Integer	Property ID to associate with code
Y	property_code	Integer	The property code being assigned
	vendor_id	Integer	Vendor ID associated with Client

assignPropertyCode Response

Response: A Soap Object consisting of the response code, response description, and the details of the property code will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
codes	object	Details of assigned property code

‘codes’ object: See “getAssignedCodes Response” for a list of the object’s variables.

freePropertyCode

The freePropertyCode method will allow an external application to remove a property code’s assignment to a property within the Virtual Agent Connect platform. In order to use the freePropertyCode method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the property code.

Once the user has passed authentication, the property code association will be removed and the status of the code will be set to “Inactive.”

freePropertyCode Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	client_id	Integer	Client ID associated with property code
Y	property_code	Integer	The property code being freed
	vendor_id	Integer	Vendor ID associated with Client

freePropertyCode Response

Response: A Soap Object consisting of the response code and response description will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response

getAvailableCodes

The getAvailableCodes method will allow an external application to retrieve a list of all of the client’s or company’s property codes that are not actively assigned to a property within the Virtual Agent Connect platform. In order to use the getAvailableCodes method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client or company account.

Once the user has passed authentication, a list of all available codes and their details will be returned.

getAvailableCodes Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	The ID of the vendor, client, or company of which to pull a list of available codes. Only one is required.
	client_id	Integer
	company_id	Integer

getAvailableCodes Response

Response: A Soap Object consisting of the response code, response description, and the details of all matching available codes will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
codes	array	Details of all matching available codes

‘codes’ array: The codes array contains an object for each matching code, with variable names of:

code_id
property_code
client_id
company_id
code_expires
marketing_medium

assignClientCodes

The assignClientCodes method will allow an external application to assign a specified number of new property codes to a client within the Virtual Agent Connect platform. In order to use the assignClientCodes method, you will be required to authenticate. The username and password combination must match the e-mail address and password of a vendor user associated with the vendor_id passed in.

Once the user has passed authentication, the specified number of property codes (up to the maximum allowed) will be created and assigned to the client.

assignClientCodes Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	Vendor ID associated with Client
Y	client_id	Integer	Client ID to assign codes to
Y	num_codes	Integer	Number of codes to assign to Client

assignClientCodes Response

Response: A Soap Object consisting of the response code, response description, and the details of all created codes will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
codes	array	Details of all created codes

‘codes’ array: The codes array contains an object for each matching code. See getAvailableCodes Response for a list of the objects’ variables.

getAlertRecord

The getAlertRecord method will allow an external application to retrieve a list of all alert records set for a property or client within the Virtual Agent Connect platform. In order to use the getAlertRecord method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account.

Once the user has passed authentication, a list of all alert records for the client or property will be returned.

getAlertRecord Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	property_id	Integer	The ID of the property or client to retrieve alert records of. Only one is required.
Y	client_id	Integer
	vendor_id	Integer	Vendor ID associated with Client

getAlertRecord Response

Response: A Soap Object consisting of the response code, response description, and alert record details will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
alerts	array	List of matching alert records with details

‘alerts’ array: The alerts array contains an object for each matching alert record with variable names of:

alert_id
property_id
client_id
company_id
alert_type
alert_value
alert_sponsor
sponsor_id
sponsor_user_id

createAlertRecord

The createAlertRecord method will allow an external application to easily create a new alert record for a specific property or client within the Virtual Agent Connect platform. In order to use the createAlertRecord method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client account. If vendor_id is not provided, client_id must be provided.

Once the user has passed authentication, a new alert record will be created in the Virtual Agent Connect platform and all details of the alerts created will be returned.

createAlertRecord Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	property_id	Integer	The ID of the property or client to create alert record of. Only one is required. If both are provided, only a property alert record will be created.
Y	client_id	Integer
Y	email	String(50)	The email address or mobile number to send the alerts to. Only one is required. If both are provided, an alert record will be created for each.
Y	mobile_number	String(50)
	vendor_id	Integer	Vendor ID associated with Client

createAlertRecord Response

Response: A Soap Object consisting of the response code, response description, and alert record details will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
alerts	object	Details of new alert record

‘alerts’ object: See “getAlertRecord Response” for a list of the object’s variable names.

purgeAlertRecord

The purgeAlertRecord method will allow an external application to delete all alert records for a specific property, client, or company (and, optionally, only those sent to a specific email or mobile number) within the Virtual Agent Connect platform. In order to use the purgeAlertRecord method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the client, the vendor, or an administrator with the proper permissions to manage the client or company account. If vendor_id is not provided, client_id must be provided. If the property ID and the client or company ID are provided, only the property alert records will be deleted.

Once the user has passed authentication, all alert records for the specified property, client, or company will be deleted.

purgeAlertRecord Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	property_id	Integer	The ID of the property, client or company to delete all alert records of. Only one is required.
	client_id	Integer
	company_id	Integer
	email	String(50)	If provided, will narrow down purge to only those alerts sent to matching email or mobile number
	mobile_number	String(50)
	vendor_id	Integer	Vendor ID associated with Client

purgeAlertRecord Response

Response: A Soap Object consisting of the response code and response description will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response

leadCount

The leadCount method will allow an external application to retrieve a lead count for an authorized company, region, or franchise within the Virtual Agent Connect platform. In order to use the leadCount method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the vendor or an administrator with the proper permissions to manage the account.

Once the user has passed authentication, the total number of leads for the specified date range will be returned.

leadCount Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	franchise_id	Integer	The ID of the franchise, region, or company of which to pull a list of clients. Only one is required.
	region_id	Integer
	company_id	Integer
	vendor_id	Integer	The ID of the vendor, used for authentication.
	date_range	String	The date(s) to pull lead counts for. See below for acceptable values/formats

date_range acceptable values/formats:

"2010-01-31" (Jan 31st, 2010)

"20100131" (same as above)

"20091101-20100630" (range: Nov 1st, 2009 through Jun 30th, 2010)

"TODAY"

"YESTERDAY"

"THIS WEEK"

"THIS MONTH"

"LAST MONTH"

"THIS YEAR"

"ALL" (default value)

leadCount Response

Response: A Soap Object consisting of the response code, response description, and the lead count will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
leads	object	Lead count with search dates

‘leads’ object: The leads object contains the following variable names:

count
start_date
end_date

monthlyLeadBreakdown

The monthlyLeadBreakdown method will allow an external application to retrieve a monthly lead count over the last 12 months for an authorized company, region, or franchise within the Virtual Agent Connect platform. In order to use the monthlyLeadBreakdown method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the vendor or an administrator with the proper permissions to manage the account.

Once the user has passed authentication, the total number of leads for the specified date range will be returned.

monthlyLeadBreakdown Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	franchise_id	Integer	The ID of the franchise, region, or company of which to pull a list of clients. Only one is required.
	region_id	Integer
	company_id	Integer
	vendor_id	Integer	The ID of the vendor, used for authentication.

monthlyLeadBreakdown Response

Response: A Soap Object consisting of the response code, response description, and the lead count will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
leads	array	Lead counts separated by month

‘leads’ array: The leads array contains an object for each of the last 12 months with positive leads. See “leadCount Response” for a list of the object’s variable names.

getFranchises

The getFranchises method will allow an external application to retrieve a list of Franchises within the Virtual Agent Connect platform. This may be useful in finding the franchiseID required for other methods. In order to use the getFranchises method, you will be required to authenticate. The username and password combination must match the e-mail address and password of a vendor account.

Once the user has passed authentication, a list of franchises will be returned.

getFranchises Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password

getFranchises Response

Response: A Soap Object consisting of the response code, response description, and the franchises will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
franchises	array	an array of franchise objects

‘franchises’ array: The franchises array contains an object for each franchise with variable names of:

franchise_name
franchise_id

getRegions

The getRegions method will allow an external application to retrieve a list of regions within a specified franchise. This may be useful in finding the regionID required for other methods. In order to use the getRegions method, you will be required to authenticate. The username and password combination must match the e-mail address and password of a vendor account.

Once the user has passed authentication, a list of regions will be returned.

getRegions Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	franchise_id	Integer	ID of Franchise to pull a list of regions

getRegions Response

Response: A Soap Object consisting of the response code, response description, and the regions will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
regions	array	an array of region objects

‘regions’ array: The regions array contains an object for each region with variable names of:

region_name
region_id
franchise_id

createRegion

The createRegion method will allow an external application to create a new region. In order to use the createRegion method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the vendor account.

createRegion Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	ID of Vendor for authentication
Y	region_name	String	Name of the region to create
	franchise_id	Integer	ID of Franchise to associate region with

createRegion Response

Response: A Soap Object consisting of the response code, response description, and the region details:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
regions	object	details of the created region

‘regions’ object: The regions object contains variable names of:

region_name
region_id
franchise_id

getCompanies

The getCompanies method will allow an external application to retrieve a list of companies (offices) within a specified region. This may be useful in finding the companyID required for other methods. In order to use the getCompanies method, you will be required to authenticate. The username and password combination must match the e-mail address and password of a vendor account.

Once the user has passed authentication, a list of companies will be returned.

getCompanies Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	region_id	Integer	ID of Region to pull a list of companies

getCompanies Response

Response: A Soap Object consisting of the response code, response description, and the companies will be returned:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
companies	array	an array of company objects

‘companies’ array: The companies array contains an object for each company with variable names of:

company_name
company_id
region_id
franchise_id
address
city
state
zip
phone
fax
contact_name
data_aggregation
country

createCompany

The createCompany method will allow an external application to create a new office. In order to use the createCompany method, you will be required to authenticate. The username and password combination must match the e-mail address and password of a vendor account.

createCompany Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	ID of Vendor for authentication
Y	company_name	String	Name of the company/office to create
	region_id	Integer	ID of Region to associate company with
	franchise_id	Integer	ID of Franchise to associate company with
	dataAggregation	Integer	Whether company listings are provided in data feed (0 for no, 1 for yes)
	address	String	Office address
	city	String	City
	state	String	2-char state abbreviation
	zip	String	Zip Code
	phone	String	Office phone number
	fax	String	Office fax number
	contactName	String	Name of office contact
	country	String	Country of office. Acceptable values include "United States" (default) and "Canada"

createCompany Response

Response: A Soap Object consisting of the response code, response description, and the company details:

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response
companies	object	details of the created company

‘companies’ object: The companies object contains variable names of:

company_name
company_id
region_id
franchise_id
address
city
state
zip
phone
fax
contact_name
data_aggregation
country

sendSMS

The sendSMS method will allow an external application to send a custom text message to a specified recipient. In order to use the sendSMS method, you will be required to authenticate. The username and password combination must match the e-mail address and password of the vendor account. This method is provided only to approved vendors and monthly caps may apply.

The maximum message length is 193 characters, and the following text will be appended to each message for compliance purposes: "Rply STOP to quit, HELP 4 help. Msg&Data rates may apply". Messages will be split if necessary (maximum of 2 messages) to fit the maximum SMS length of the recipient's country (160 for United States, 136 for Canada. No other countries supported).

Messages will only be delivered between the hours of 10 AM and 10PM Eastern Standard Time. Requests outside of these hours will be queued for later delivery.

sendSMS Request

Required	Index name	Value (max chars)	Comments
Y	auth_username	String	User’s e-mail address
Y	auth_passcode	String	User’s password
Y	vendor_id	Integer	ID of Vendor for authentication
Y	phone	String	Phone Number of message recipient
Y	text	string	The message to be delivered.
	timestamp	Integer	An optional UNIX timestamp of when the message should be delivered.

sendSMS Response

Response: A Soap Object consisting of the response code and response description will be returned.

Index Name	Type	Comments
responseCode	int	Code indicating service response
responseDescription	string	Description of service response

Response Codes

Here is a list of all possible response codes returned with the object.

Code	Description
1	Success
10	Missing Required Parameters
11	Failed Vendor Authentication
12	Invalid Permissions
13	Failed Client Authentication
14	Invalid Client ID
15	Invalid Property ID
16	No Properties Found
17	Multiple Properties Found, Provide Zip or PropertyID
18	Multiple Properties Found, Contact Support
19	All 25 Photo Slots Filled, Choose Slot to Replace
20	Invalid Photo Slot
21	Multiple Clients Found, Supply Client ID
22	No Clients Found
23	Failed Admin Authentication
24	No Photos Found For Property
25	Code Already Assigned to Live Property
26	Property Already Has Code Associated
27	Invalid Property Code
28	No Available Property Codes
29	No Assigned Property Codes
30	No Matching Alert Records
31	No Matching Leads
32	No Matching Clients
33	Email address already exists
34	Password must be 4-32 characters
35	Invalid Email Address
36	Invalid Phone Number
37	Recipient in Opt Out list
38	Message exceeds maximum length
39	Not Enough Photos for Tour