Dotsignal Web Services API

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:

  1. Property methods
  2. Client methods
  3. Property Code methods
  4. Alert Record methods
  5. Lead methods
  6. Company methods
  7. 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)

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

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)

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.

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.

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.

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.

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.

CodeDescription
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
Have more questions? Submit a request