API Interface Specification
Revision date: 28-Feb-2014
API URL & Resources
The URL for all APIs is: https://vault.energyperiscope.com/api/index.php/
API "Resources":
- GetJobList
- GetJob
- GetLeadList
- GetLead
- PostLead
- GetWidgetUsers
For example: If you want to get a list of all Jobs for your account you would use the Resource "GetJobList" and its associated parameters: https://vault.energyperiscope.com/api/index.php/GetJobList/?parameter_variables
Authentication
API Key Sets (ID & Key) are generated from within the software User's Administrator account ("My Account" >> API tab). When calling an API Resource a valid API ID and API Key must be submitted together with other parameter variables, as applicable:
Request Get Variable Parameter Formats:
- "dates and times stamps" (if provided; not blank) must be in the format "YYYY-MM-DD HH:mm:ss" where "HH" is the hour in 00-24 hour format. Example: 1:14 PM and 7 seconds on January 19, 2016 would be in the format 2016-01-19 13:14:07
- Our servers reside in the United States in the Pacific Time Zone. All date and time stamps should be in reference to this time zone. For example, if you are in the Eastern time zone, the time stamps stored on our server will be 3 hours prior to the Eastern Time stamp.
- "UserEmail" (if provided) must be a valid email address assigned to the account.
- "externalid" (if provided) must not contain any of the following characters: ' + ? ; &
Response (XML)
The API will respond in XML format:
If the Request was successful:
If "Successful" but the software had to auto-correct errors, the XML response will include each auto-corrected error returned as a message:
If the Request was not successful, the XML response will be as follows, with each error returned as a message:
If the API Request URI Resource contains a "Get____" the XML document will also include the data response fields (XML-tagged variables) as further defined herein. For example, detailed Job data for the Job requested.
Revision date: 05-Feb-2015: added Storage
GetJobList
Returns a List of Jobs for the entire Company or a specific User of the company account. Data request may also be refined by the dates ranges for when a Job was Created and/or Last Updated. The Job list is ordered by Date Created.
API Request Parameter Variables | |
---|---|
Get Variable Name | Value |
The following parameter variables may be submitted to the API URL after the Resource "GetJobList". Required variables are red. | |
apiID | API ID |
apiKey | Key assigned to the API ID |
You may specify a User Login Email (associated with an Account Login). If specified only Jobs assigned to that User will be pulled. If blank all Jobs from the Company account will be pulled. | |
UserEmail | email address for a specific account User login (used to find Jobs, if provided) |
You may specify Dates for when a Job was Created and/or last Updated:
|
|
Created_From | YYYY-MM-DD HH:mm:ss |
Created_To | YYYY-MM-DD hh:mm:ss |
Updated_From | YYYY-MM-DD HH:mm:ss |
Updated_To | YYYY-MM-DD hh:mm:ss |
XMl Document: API Response
XML Document: API Response | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
XML Name Space | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
status | Successful or Unsuccessful | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
messages and/or errors | API messages: each with a name space tag <message> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
UserEmail | email address for a specific account User login (used to find Jobs, if provided) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Created_From | Date Jobs created from (used to find Jobs, if provided) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Created_To | Date Jobs created to (used to find Jobs, if provided) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Updated_From | Date Jobs updated from (used to find Jobs, if provided) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Updated_To | Date Jobs updated to (used to find Jobs, if provided) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total_jobs | Number of Jobs found | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
job | Data for this Job: Parent name space tag >> Children: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Revision date: 18-May-2017: Added "heating_fuel_post" and "heating_units_post" to differentiate energy source for space heating after the project (post-project)
Revision date: 05-Feb-2015 - Added Energy Storage
GetJob
Returns data for a specified Job.
You may pull Job data by its jobid or by the externalid. "externalid" is a unique ID associated with the Job, as assigned by you (for example an ID that comes from your CRM system for this Job/customer record). The externalid must be unique (can not be assigned to more than one (1) Job. If you submit an jobid and an externalid the software will store the externalid to that jobid (associate it to the jobid in our database) for future reference.
API Request Parameter Variables | |
---|---|
Get Variable Name | Value |
The following parameter variables may be submitted to the API URL after the Resource "GetJob". Required variables are red. | |
apiID | API ID |
jobid* | Job ID |
externalid* | ExternalID |
* - "jobid" or its associated "externalid" is required |
XML Document: API Response | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
XML Name Space | Value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
status | Successful or Unsuccessful | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
messages and/or errors | API messages: each with a name space tag <message> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
job | Parent name space tag >> Children | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
job >> Children |
|
Original Release date: 28-Feb-2014
Revised 06-May-2014 added variables: fed_tax_rate, state_tax_rate, ctype, pwrrel, pwrmgmt
Revised 13-Jun-2014 added variable: lead_status
Revised 28-Dec-2015 added namespace: jobs
GetLeadList
Returns a List of Sales leads for the entire Company or a specific User of the company account. Data request may also be refined by the dates ranges for when a Lead was Created. All Leads will be pulled if no date, or dates, are specified. For example if the Created_From is defined by the Created_To is blank, all Leads from the Created_From date onward will be pulled The Lead list is ordered by Date Created.
API Request Parameter Variables | |
---|---|
Get Variable Name | Value |
The following parameter variables may be submitted to the API URL after the Resource "GetLeadList". Required variables are red. | |
apiID | API ID |
apiKey | Key assigned to the API ID |
You may specify a User Login Email (associated with an Account Login). If specified only Leads assigned to that User will be pulled. If blank all Leads from Company account will be pulled. | |
UserEmail | email address for a specific account User login (used to find Leads, if provided) |
You may specify Dates for when a Lead was Created and/or last Updated:
|
|
Created_From | YYYY-MM-DD HH:mm:ss |
Created_To | YYYY-MM-DD hh:mm:ss |
Updated_From | YYYY-MM-DD HH:mm:ss |
Updated_To | YYYY-MM-DD hh:mm:ss |
API Response Parameter | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Data for each Lead will be enclosed in |
|||||||||||
Lead Question | XML Name Space | Format | Values | ||||||||
ID of the Lead | leadid | int(11) | Lead ID | ||||||||
Lead External ID | externalid | varchar(30) | an External ID for this Lead | ||||||||
Lead Source | source | varchar(30) | Source for this Lead | ||||||||
Lead Status | lead_status | tinyint(2) | 0: New, 1: Cold, 2: Warm, 3: Hot | ||||||||
User Email this Lead is assigned to (blank if not assigned) | assignedto | varchar(50) | Source for this Lead | ||||||||
JobID if Lead was converted to a Job | jobid | int(11) | JobID if Lead was converted to a Job | ||||||||
External JobID if Lead was converted to a Job | jobid_externalid | varchar(30) | External JobID if Lead was converted to a Job | ||||||||
If more than 1 Job is associated with the Lead then data is provided as: | |||||||||||
jobs (parent) | jobid (child) | jobid_externalid (child) | |||||||||
Date Lead was Entered | whensubmit | YYYY-MM-DD HH:mm:ss | Date Lead was Entered | ||||||||
Date Lead was Last Updated | date_updated | YYYY-MM-DD HH:mm:ss | Date Lead was Last Updated | ||||||||
Lead Archived | archived | tinyint(1) | 1 if lead was Archived, else 0 | ||||||||
Latitude of Customer Location | latitude | decimal(10,2) | Latitude of Customer Location | ||||||||
Longitude of Customer Location | longitude | decimal(10,2) | Longitude of Customer Location | ||||||||
Lead Contact Information | |||||||||||
First Name | first_name | varchar(100) | first name | ||||||||
Last Name | last_name | varchar(100) | last name | ||||||||
Email Address | varchar(100) | email address | |||||||||
Company Name | company | varchar(100) | company | ||||||||
Mobile (cell) Number | mobile | varchar(50) | mobile phone number | ||||||||
Telephone Number | phone | varchar(50) | phone number | ||||||||
Fax Number | fax | varchar(50) | fax number | ||||||||
Street Address | street | varchar(100) | street address | ||||||||
City | city | varchar(100) | city | ||||||||
State | state | varchar(2) | state | ||||||||
Zip or Post Code | zip | varchar(10) | USA XXXXX, or XXXX-YYYY Canada XXX-YYY or XXX YYY |
||||||||
Federal Tax Rate | fed_tax_rate | decimal(5,2) | Federal tax rate like xx.xx (%) | ||||||||
State Tax Rate | state_tax_rate | decimal(5,2)) | State tax rate like xx.xx (%) | ||||||||
Customer type | ctype | tinyint(4) | 1=Residential, 2=Business, 3=Nonprofit, 4=Govt/Muni | ||||||||
Contact When | contactwhen | tinyint(1) | 1=Morning, 2=Afternoon, 3=Evening | ||||||||
Contact How | contacthow | tinyint(1) | 1=Cell phone, 2=Home phone, 3=Email | ||||||||
Energy Efficiency Improvements Previously Performed on Building | |||||||||||
Enery Audit Performed? | energyaudit | tinyint(1) | 1=Yes, 0=No | ||||||||
Insulation Improved? | insulation | tinyint(1) | 1=Yes, 0=No | ||||||||
Windows Upgraded? | windows | tinyint(1) | 1=Yes, 0=No | ||||||||
Space Heater Efficiency Improved? | heating | tinyint(1) | 1=Yes, 0=No | ||||||||
Air Conditioner (Cooling) Efficiency Improved? | cooling | tinyint(1) | 1=Yes, 0=No | ||||||||
Water Heater Efficiency Improved? | waterheat | tinyint(1) | 1=Yes, 0=No | ||||||||
Lighting Efficiency Improved? | lighting | tinyint(1) | 1=Yes, 0=No | ||||||||
Appliance Efficiency Improved? | appliances | tinyint(1) | 1=Yes, 0=No | ||||||||
Interested In | |||||||||||
Want Solar Electric (PV)? | pv | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Water Heating? | solarwater | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Pool/Spa Heating? | solarpool | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Wind Turbine? | wind | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Geothermal Heatpump? | geothermal | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Space Heating? | solarspace | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Wood/Biomass Heating? | wood | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Energy Efficiency Improvements? | efficiency | tinyint(1) | 1=Yes, 0=No | ||||||||
Want/Need Financing? | finance | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Financial Analysis? | financialanalysis | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Incentive Analysis? | incentives | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Power Reliability (Backup)? | pwrrel | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Power Management (Demand Reduction)? | pwrmgmt | tinyint(1) | 1=Yes, 0=No | ||||||||
Current Energy Use | |||||||||||
Average Monthly Electric Bill | electricbill | int(11) | $ per month | ||||||||
Average Monthly Natural Gas Bill | gasbill | int(11) | $ per month | ||||||||
Average Monthly Fuel Oil Bill | oilbill | int(11) | $ per month | ||||||||
Name of Electric Utility | electricutility | varchar(100) | name of electric utility | ||||||||
Name of Natural Gas Utility | gasutility | varchar(100) | name of natural gas utility | ||||||||
Percent Energy Use Customer Wants Displace | percentsolar | smallint(3) | 0 - 100 percent | ||||||||
Building Information | |||||||||||
Type of Building | buildingtype | tinyint(1) | 0=Undefined 1=Single Family Home (new construction) 2=Single family home (older) 3=Semi-detached or town house 4=Condo 5=Commercial Building |
||||||||
Ownership of Building | ownertype | tinyint(1) | 0=Undefined 1=Owned 2=Rented/Leased |
||||||||
Building Size (sq-ft) | bldgsize | int(8) | Sq-Ft | ||||||||
How Building is Heated | heattype | tinyint(1) | 0=Undefined 1=Natural Gas 2=Electric 3=Fuel Oil 4=Propane 5=Wood Burning |
||||||||
How Water is Heated | watertype | tinyint(1) | 0=Undefined 1=Natural Gas 2=Electric 3=Fuel Oil 4=Propane 5=Wood Burning |
||||||||
Type of Water Heater (currently) | waterheater | tinyint(1) | 0=Undefined 1=Standard 2=Tankless 3=On-demand |
||||||||
Project Information | |||||||||||
State Where Work is to be Performed | projectstate | varchar(2) | State | ||||||||
Description of Work/Project Requested | description | text | project description | ||||||||
When do they want work started | timing | tinyint(1) | 0=Undefined 1=Immediately 2=3-6 months 3=1 year 4=2 years or more |
||||||||
Budget for Project | budget | int(11) | budget | ||||||||
Method of Financing Project | needfinance | tinyint(1) | 0=I am not sure about financing 1=Need Financing 2=Have financing 3=Cash (no finance req'd) |
||||||||
Mounting Location for Collectors | mount | tinyint(1) | 0=Roof 1=Ground 2=Roof and Ground 3=Not Sure |
||||||||
Sun Exposure for Collectors | exposure | tinyint(1) | 0=Undefined 1=North 2=South 3=East 4=West 5=Other |
||||||||
Shading Conditions for Collectors | shading | tinyint(1) | 0=Undefined 1=Full Sun 2=Partial 3=Low Sun |
||||||||
Description of any Obstructions to Collectors | obstructions | text | description of any obstructions | ||||||||
Area (sq-ft) Available for Collector Installation | area | int(11) | Sq-Ft of installation area available | ||||||||
Type of Roofing Material | rooftype | tinyint(2) | 0=Undefined 1=Asphalt Shingle 2=Ceramic 3=Clay Tile 4=Wood Shingle 5=Metal 6=Engineered Rubber 7=Plastic 8=Other |
||||||||
Description of Roofing Material (if Other) | roofother | varchar(100) | description of roof type (if other) | ||||||||
Age of Roofing Material (years) | roofage | int(6) | years - age of roof | ||||||||
Pitch of Roof | rooftilt | tinyint(1) | 0=Undefined 1=Conventional Pitch 2=Low Pitch 3=Flat Roof |
||||||||
Style of Roof | roofstyle | tinyint(1) |
|
||||||||
FICO (credit) Score of Customer | fico_score | smallint(3) | FICO score | ||||||||
Value of Property/Building | prop_value | mediumint(8) | Value ($) of property | ||||||||
County of Job Location | county | varchar(50) | County of Job Location | ||||||||
Country of Job Location | country | varchar(2) | Country of Job Location | ||||||||
Zipcode of Job Location | jzip | varchar(10) | USA XXXXX, or XXXX-YYYY Canada XXX-YYY or XXX YYY |
Original Release date: 28-Feb-2014
Revised 06-May-2014 added variables: fed_tax_rate, state_tax_rate, ctype, pwrrel, pwrmgmt
Revised 13-Jun-2014 added variable: lead_status
Revised 28-Dec-2015 added namespace: jobs
GetLead
Returns data for a specified Lead.
You may pull Lead data by its leadid or by the externalid. "externalid" is a unique ID associated with the Lead, as assigned by you (for example an ID that comes from your CRM system for this customer record). The externalid must be unique (can not be assigned to more than one (1) Lead. If you submit an leadid and an externalid the software will store the externalid to that leadid (associate it to the leadid in our database) for future reference.
API Request Parameter Variables | |
---|---|
Get Variable Name | Value |
The following parameter variables may be submitted to the API URL after the Resource "GetLead". Required variables are red. | |
apiID | API ID |
leadid* | Lead ID |
externalid* | ExternalID |
* - "leadid" or its associated "externalid" is required |
API Response Parameter | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Lead Question | XML Name Space | Format | Values | ||||||||
ID of the Lead | leadid | int(11) | Lead ID | ||||||||
Lead External ID | externalid | varchar(30) | an External ID for this Lead | ||||||||
Lead Source | source | varchar(30) | Source for this Lead | ||||||||
Lead Status | lead_status | tinyint(2) | 0: New, 1: Cold, 2: Warm, 3: Hot | ||||||||
User Email this Lead is assigned to (blank if not assigned) | assignedto | varchar(50) | Source for this Lead | ||||||||
JobID if Lead was converted to a Job | jobid | int(11) | JobID if Lead was converted to a Job | ||||||||
External JobID if Lead was converted to a Job | jobid_externalid | varchar(30) | External JobID if Lead was converted to a Job | ||||||||
If more than 1 Job is associated with the Lead then data is provided as: | |||||||||||
jobs (parent) | jobid (child) | jobid_externalid (child) | |||||||||
Date Lead was Entered | whensubmit | YYYY-MM-DD HH:mm:ss | Date Lead was Entered | ||||||||
Date Lead was Last Updated | date_updated | YYYY-MM-DD HH:mm:ss | Date Lead was Last Updated | ||||||||
Lead Archived | archived | tinyint(1) | 1 if lead was Archived, else 0 | ||||||||
Latitude of Customer Location | latitude | decimal(10,2) | Latitude of Customer Location | ||||||||
Longitude of Customer Location | longitude | decimal(10,2) | Longitude of Customer Location | ||||||||
Lead Contact Information | |||||||||||
First Name | first_name | varchar(100) | first name | ||||||||
Last Name | last_name | varchar(100) | last name | ||||||||
Email Address | varchar(100) | email address | |||||||||
Company Name | company | varchar(100) | company | ||||||||
Mobile (cell) Number | mobile | varchar(50) | mobile phone number | ||||||||
Telephone Number | phone | varchar(50) | phone number | ||||||||
Fax Number | fax | varchar(50) | fax number | ||||||||
Street Address | street | varchar(100) | street address | ||||||||
City | city | varchar(100) | city | ||||||||
State | state | varchar(2) | state | ||||||||
Zip or Post Code | zip | varchar(10) | USA XXXXX, or XXXX-YYYY Canada XXX-YYY or XXX YYY |
||||||||
Federal Tax Rate | fed_tax_rate | decimal(5,2) | Federal tax rate like xx.xx (%) | ||||||||
State Tax Rate | state_tax_rate | decimal(5,2)) | State tax rate like xx.xx (%) | ||||||||
Customer type | ctype | tinyint(4) | 1=Residential, 2=Business, 3=Nonprofit, 4=Govt/Muni | ||||||||
Energy Efficiency Improvements Previously Performed on Building | |||||||||||
Enery Audit Performed? | energyaudit | tinyint(1) | 1=Yes, 0=No | ||||||||
Insulation Improved? | insulation | tinyint(1) | 1=Yes, 0=No | ||||||||
Windows Upgraded? | windows | tinyint(1) | 1=Yes, 0=No | ||||||||
Space Heater Efficiency Improved? | heating | tinyint(1) | 1=Yes, 0=No | ||||||||
Air Conditioner (Cooling) Efficiency Improved? | cooling | tinyint(1) | 1=Yes, 0=No | ||||||||
Water Heater Efficiency Improved? | waterheat | tinyint(1) | 1=Yes, 0=No | ||||||||
Lighting Efficiency Improved? | lighting | tinyint(1) | 1=Yes, 0=No | ||||||||
Appliance Efficiency Improved? | appliances | tinyint(1) | 1=Yes, 0=No | ||||||||
Interested In | |||||||||||
Want Solar Electric (PV)? | pv | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Water Heating? | solarwater | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Pool/Spa Heating? | solarpool | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Wind Turbine? | wind | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Geothermal Heatpump? | geothermal | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Space Heating? | solarspace | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Wood/Biomass Heating? | wood | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Energy Efficiency Improvements? | efficiency | tinyint(1) | 1=Yes, 0=No | ||||||||
Want/Need Financing? | finance | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Financial Analysis? | financialanalysis | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Incentive Analysis? | incentives | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Power Reliability (Backup)? | pwrrel | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Power Management (Demand Reduction)? | pwrmgmt | tinyint(1) | 1=Yes, 0=No | ||||||||
Current Energy Use | |||||||||||
Average Monthly Electric Bill | electricbill | int(11) | $ per month | ||||||||
Average Monthly Natural Gas Bill | gasbill | int(11) | $ per month | ||||||||
Average Monthly Fuel Oil Bill | oilbill | int(11) | $ per month | ||||||||
Name of Electric Utility | electricutility | varchar(100) | name of electric utility | ||||||||
Name of Natural Gas Utility | gasutility | varchar(100) | name of natural gas utility | ||||||||
Percent Energy Use Customer Wants Displace | percentsolar | smallint(3) | 0 - 100 percent | ||||||||
Building Information | |||||||||||
Type of Building | buildingtype | tinyint(1) | 0=Undefined 1=Single Family Home (new construction) 2=Single family home (older) 3=Semi-detached or town house 4=Condo 5=Commercial Building |
||||||||
Ownership of Building | ownertype | tinyint(1) | 0=Undefined 1=Owned 2=Rented/Leased |
||||||||
Building Size (sq-ft) | bldgsize | int(8) | Sq-Ft | ||||||||
How Building is Heated | heattype | tinyint(1) | 0=Undefined 1=Natural Gas 2=Electric 3=Fuel Oil 4=Propane 5=Wood Burning |
||||||||
How Water is Heated | watertype | tinyint(1) | 0=Undefined 1=Natural Gas 2=Electric 3=Fuel Oil 4=Propane 5=Wood Burning |
||||||||
Type of Water Heater (currently) | waterheater | tinyint(1) | 0=Undefined 1=Standard 2=Tankless 3=On-demand |
||||||||
Project Information | |||||||||||
State Where Work is to be Performed | projectstate | varchar(2) | State | ||||||||
Description of Work/Project Requested | description | text | project description | ||||||||
When do they want work started | timing | tinyint(1) | 0=Undefined 1=Immediately 2=3-6 months 3=1 year 4=2 years or more |
||||||||
Budget for Project | budget | int(11) | budget | ||||||||
Method of Financing Project | needfinance | tinyint(1) | 0=I am not sure about financing 1=Need Financing 2=Have financing 3=Cash (no finance req'd) |
||||||||
Mounting Location for Collectors | mount | tinyint(1) | 0=Roof 1=Ground 2=Roof and Ground 3=Not Sure |
||||||||
Sun Exposure for Collectors | exposure | tinyint(1) | 0=Undefined 1=North 2=South 3=East 4=West 5=Other |
||||||||
Shading Conditions for Collectors | shading | tinyint(1) | 0=Undefined 1=Full Sun 2=Partial 3=Low Sun |
||||||||
Description of any Obstructions to Collectors | obstructions | text | description of any obstructions | ||||||||
Area (sq-ft) Available for Collector Installation | area | int(11) | Sq-Ft of installation area available | ||||||||
Type of Roofing Material | rooftype | tinyint(2) | 0=Undefined 1=Asphalt Shingle 2=Ceramic 3=Clay Tile 4=Wood Shingle 5=Metal 6=Engineered Rubber 7=Plastic 8=Other |
||||||||
Description of Roofing Material (if Other) | roofother | varchar(100) | description of roof type (if other) | ||||||||
Age of Roofing Material (years) | roofage | int(6) | years - age of roof | ||||||||
Pitch of Roof | rooftilt | tinyint(1) | 0=Undefined 1=Conventional Pitch 2=Low Pitch 3=Flat Roof |
||||||||
Style of Roof | roofstyle | tinyint(1) |
|
||||||||
FICO (credit) Score of Customer | fico_score | smallint(3) | FICO score | ||||||||
Value of Property/Building | prop_value | mediumint(8) | Value ($) of property | ||||||||
County of Job Location | county | varchar(50) | County of Job Location | ||||||||
Country of Job Location | country | varchar(2) | Country of Job Location | ||||||||
Zipcode of Job Location | jzip | varchar(10) | USA XXXXX, or XXXX-YYYY Canada XXX-YYY or XXX YYY |
Original Release date: 28-Feb-2014
Revised 06-May-2014 added variables: source, fed_tax_rate, state_tax_rate, ctype, pwrrel, pwrmgmt
Legacy API: The Lead Source API Interface Document (used prior to 28-Feb-2014)
PostLead
Inserts a new Sales leads into the Company account.
API Request Parameter Variables
The following Parameter variables may be submitted to the API URL after the Resource "PostLead". Required variables are red.
"externalid" is a unique ID associated with the Lead, as assigned by you (for example an ID that comes from your CRM system for this Lead/customer record). The externalid must be unique (can not be assigned to more than one (1) Lead. If you submit an externalid the software will associate the externalid to the leadid in our database for future reference.
Lead Question | Get Variable Name | Format | Values | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
API Key Set | |||||||||||
API Validation | apiID | int(11) | API ID | ||||||||
API Validation | apiKey | varchar(200) | API Key | ||||||||
External ID for this Lead | |||||||||||
External ID | externalid | varchar(30) | an External ID for this Lead | ||||||||
Source of this Lead | |||||||||||
Lead Source | source | varchar(30) | Source of this Lead (If blank API name is used). | ||||||||
Lead Contact Information | |||||||||||
First Name | first_name | varchar(100) | first name | ||||||||
Last Name | last_name | varchar(100) | last name | ||||||||
email or mobile or phone is required | |||||||||||
Email Address | varchar(100) | email address | |||||||||
Company Name | company | varchar(100) | company | ||||||||
Mobile (cell) Number | mobile | varchar(50) | mobile phone number | ||||||||
Telephone Number | phone | varchar(50) | phone number | ||||||||
Fax Number | fax | varchar(50) | fax number | ||||||||
Street Address | street | varchar(100) | street address | ||||||||
City | city | varchar(100) | city | ||||||||
State | state | varchar(2) | state | ||||||||
Zip or Post Code | zip | varchar(10) | USA XXXXX, or XXXX-YYYY Canada XXX-YYY or XXX YYY |
||||||||
Federal Tax Rate | fed_tax_rate | decimal(5,2) | Federal tax rate like xx.xx (%) | ||||||||
State Tax Rate | state_tax_rate | decimal(5,2)) | State tax rate like xx.xx (%) | ||||||||
Customer type | ctype | tinyint(4) | 1=Residential, 2=Business, 3=Nonprofit, 4=Govt/Muni | ||||||||
Energy Efficiency Improvements Previously Performed on Building | |||||||||||
Energy Audit Performed? | energyaudit | tinyint(1) | 1=Yes, 0=No | ||||||||
Insulation Improved? | insulation | tinyint(1) | 1=Yes, 0=No | ||||||||
Windows Upgraded? | windows | tinyint(1) | 1=Yes, 0=No | ||||||||
Space Heater Efficiency Improved? | heating | tinyint(1) | 1=Yes, 0=No | ||||||||
Air Conditioner (Cooling) Efficiency Improved? | cooling | tinyint(1) | 1=Yes, 0=No | ||||||||
Water Heater Efficiency Improved? | waterheat | tinyint(1) | 1=Yes, 0=No | ||||||||
Lighting Efficiency Improved? | lighting | tinyint(1) | 1=Yes, 0=No | ||||||||
Appliance Efficiency Improved? | appliances | tinyint(1) | 1=Yes, 0=No | ||||||||
Interested In | |||||||||||
Want Solar Electric (PV)? | pv | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Water Heating? | solarwater | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Pool/Spa Heating? | solarpool | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Wind Turbine? | wind | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Geothermal Heatpump? | geothermal | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Solar Space Heating? | solarspace | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Wood/Biomass Heating? | wood | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Energy Efficiency Improvements? | efficiency | tinyint(1) | 1=Yes, 0=No | ||||||||
Want/Need Financing? | finance | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Financial Analysis? | financialanalysis | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Incentive Analysis? | incentives | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Power Reliability (Backup)? | pwrrel | tinyint(1) | 1=Yes, 0=No | ||||||||
Want Power Management (Demand Reduction)? | pwrmgmt | tinyint(1) | 1=Yes, 0=No | ||||||||
Current Energy Use | |||||||||||
Average Monthly Electric Bill | electricbill | int(11) | $ per month | ||||||||
Average Monthly Natural Gas Bill | gasbill | int(11) | $ per month | ||||||||
Average Monthly Fuel Oil Bill | oilbill | int(11) | $ per month | ||||||||
Name of Electric Utility | electricutility | varchar(100) | name of electric utility | ||||||||
Name of Natural Gas Utility | gasutility | varchar(100) | name of natural gas utility | ||||||||
Percent Energy Use Customer Wants to Displace | percentsolar | smallint(3) | 0 - 100 percent | ||||||||
Building Information | |||||||||||
Type of Building | buildingtype | tinyint(1) | 0=Undefined 1=Single Family Home (new construction) 2=Single family home (older) 3=Semi-detached or town house 4=Condo 5=Commercial Building |
||||||||
Ownership of Building | ownertype | tinyint(1) | 0=Undefined 1=Owned 2=Rented/Leased |
||||||||
Building Size (sq-ft) | bldgsize | int(8) | Sq-Ft | ||||||||
How Building is Heated | heattype | tinyint(1) | 0=Undefined 1=Natural Gas 2=Electric 3=Fuel Oil 4=Propane 5=Wood Burning |
||||||||
How Water is Heated | watertype | tinyint(1) | 0=Undefined 1=Natural Gas 2=Electric 3=Fuel Oil 4=Propane 5=Wood Burning |
||||||||
Type of Water Heater (currently) | waterheater | tinyint(1) | 0=Undefined 1=Standard 2=Tankless 3=On-demand |
||||||||
Project Information | |||||||||||
State Where Work is to be Performed | projectstate | varchar(2) | State | ||||||||
Description of Work/Project Requested | description | text | project description | ||||||||
When do they want work started | timing | tinyint(1) | 0=Undefined 1=Immediately 2=3-6 months 3=1 year 4=2 years or more |
||||||||
Budget for Project | budget | int(11) | budget | ||||||||
Method of Financing Project | needfinance | tinyint(1) | 0=I am not sure about financing 1=Need Financing 2=Have financing 3=Cash (no finance req'd) |
||||||||
Mounting Location for Collectors | mount | tinyint(1) | 0=Roof 1=Ground 2=Roof and Ground 3=Not Sure |
||||||||
Sun Exposure for Collectors | exposure | tinyint(1) | 0=Undefined 1=North 2=South 3=East 4=West 5=Other |
||||||||
Shading Conditions for Collectors | shading | tinyint(1) | 0=Undefined 1=Full Sun 2=Partial 3=Low Sun |
||||||||
Description of any Obstructions to Collectors | obstructions | text | description of any obstructions | ||||||||
Area (sq-ft) Available for Collector Installation | area | int(11) | Sq-Ft of installation area available | ||||||||
Type of Roofing Material | rooftype | tinyint(2) | 0=Undefined 1=Asphalt Shingle 2=Ceramic 3=Clay Tile 4=Wood Shingle 5=Metal 6=Engineered Rubber 7=Plastic 8=Other |
||||||||
Description of Roofing Material (if Other) | roofother | varchar(100) | description of roof type (if other) | ||||||||
Age of Roofing Material (years) | roofage | int(6) | years - age of roof | ||||||||
Pitch of Roof | rooftilt | tinyint(1) | 0=Undefined 1=Conventional Pitch 2=Low Pitch 3=Flat Roof |
||||||||
Style of Roof | roofstyle | tinyint(1) |
|
||||||||
FICO (credit) Score of Customer | fico_score | smallint(3) | FICO score | ||||||||
Value of Property/Building | prop_value | mediumint(8) | Value ($) of property |
Revision date: 28-Feb-2014
GetWidgetUsers
Returns a List of Sales Lead Widget Users for the entire Company. Note: Widget user data is only stored for the past 90 days.
API Request Parameter Variables | |
---|---|
Get Variable Name | Value |
The following parameter variables may be submitted to the API URL after the Resource "GetWidgetUsers". Required variables are red. | |
apiID | API ID |
apiKey | Key assigned to the API ID |
You may specify Dates for when a Widget User record was Created. Note: Widget user data is only stored for the past 90 days.
|
|
Created_From | YYYY-MM-DD HH:mm:ss |
Created_To | YYYY-MM-DD hh:mm:ss |
API Response Parameter Variables | |
---|---|
XML Name Space | Value |
status | Successful or Unsuccessful |
messages and/or errors | API messages: each with a tag <message> |
Created_From | Date Widget use created from (used to find Widget Users, if provided) |
Created_To | Date Widget use created to (used to find Widget Users, if provided) |
total_users | Total number of Widget Users reported |
user | A Widget User record: data as follows: |
date_created | YYYY-MM-DD HH:mm:ss |
cfirstname | First name |
clastname | Last name |
cphone | Phone |
cemail | |
czip | Zipcode |
USE RESTRICTION: Any foreign or other unauthorized access to our APIs or software will be blocked. If you are Developer accessing our software from outside the USA or Canada please send an email to help@energyperiscope.com specifying the customer for which you were hired for API development. |