Fenestratio Integration

Updated January 15, 2020

Fenestratio page ".../api.jsp" is designed to process requests from other software. All methods on api.jsp must be invoked by https requests.

Fenestratio's active login server can be located by reading the file:

https://www.fenestratio.com/appfind.htm

...which will contain something like sv10.fenestratio.com

findCustomers

findCustomers will search Fenestratio customers in the name and phone fields for the passed string.
example (some url encoding omitted):


    https://.../api.jsp?fn=findCustomers&sv=Smith&mr=20
    
or

    https://.../api.jsp?fn=findCustomers&sv=555-555-1212&mr=20

Https Parameters:

fn : function name - always findCustomers - mandatory
apiuid : caller's Fenestratio login id - mandatory
apipwd : caller's Fenestratio password - mandatory
sv : search value - minimum 3 characters - mandatory
mr : maximum results ≥ 20 ≤ 300

Return JSON:

samples:
- {ok:1,fn:"findCustomers",sv:"Smith",rc:395,
  rr:[
  {Customer:9373, Name:"Ackerson, Charles & Mary", Address:"123 some street", City:"Chicago", Phone:"555-555-1212", Phone2:"555-555-1313", Phone3:"", OtherSystemCode:"ae39239ds832ff"},
  {...}
- {security:1,fn:"findCustomers",sv:"Smith"}
- {exc:"Unexpected error....",fn:"findCustomers",sv:"Smith"}
- {ee:["Request logic error 1","Request Logic error 2"],fn:"findCustomers",sv:"Smith"}
Return elements:
- ok : either 1 on success, or absent or 0 on failure
- security : login failed
- fn : always findCustomers
- sv : caller's search value passed
- rc : full count of qualifying customers
- rr : array of customer search results, limited by mr request parameter - elements:
  - see selectCustomer record return element below

Rules:

search value must be at least 3 characters

listContacts

..will return the contacts for a customer.

example (some url encoding omitted):
https://.../api.jsp?fn=listContacts&Customer=11

Https Parameters:

fn : function name - always createCustomer - mandatory
apiuid : caller's Fenestratio login id - mandatory
apipwd : caller's Fenestratio password - mandatory
Customer : Fenestratio customer id - optional integer
OtherSystemCode : how calling system identifies customer - 50 characters

Return JSON:

samples:
- {ok:1,fn:"listContacts",OtherSystemCode:"ae39239ds832ff",Customer:9238, rr:[
  {Name:"Bob Jones", Mail:"bob@nospam.org", PhoneCell:"1234567890", PhoneWork:"5589324858", Inactive:false},
  {...}, ]}
- {security:1,fn:"createCustomer",OtherSystemCode:"ae39239ds832ff"}
- {dup:1,fn:"createCustomer",OtherSystemCode:"ae39239ds832ff"}
- {exc:"Unexpected error....",fn:"createCustomer",OtherSystemCode:"ae39239ds832ff"}
- {ee:["Request logic error 1","Request Logic error 2"]",fn:"createCustomer",OtherSystemCode:"ae39239ds832ff"}
Return elements:
- ok : either 1 on success, or absent or 0 on failure
- security : login failed
- fn : always listContacts
- OtherSystemCode : caller's customer identifier passed
- Customer : Fenestratio customer number on success, or absent

Rules:

either Customer or OtherSystemCode must be provided.

listUsers

listUsers will list all internal Fenestratio users. Dealers and contractors will not be listed.
example (some url encoding omitted):


    https://.../api.jsp?fn=listUsers

Https Parameters:

fn : function name - always listUsers - mandatory
apiuid : caller's Fenestratio login id - mandatory
apipwd : caller's Fenestratio password - mandatory

Return JSON:

samples:
- {ok:1,fn:"listUsers"
  rr:[
  {UserRow:2, UserName:"Terry Jones", EMail:"fred@fenestratio.com", Branch:1, Inactive:false, Service:true, Sales:true, CanMeasure:true, CanDeliver:true, OtherSystemCode:"239s8e93sw33"},
  {...} ]}
- {security:1,fn:"listUsers"}
- {exc:"Unexpected error....",fn:"listUsers"}
Return elements:
- ok : either 1 on success, or absent or 0 on failure
- security : login failed
- fn : always listUsers
- rr : array of results - elements:
  - UserRow : Fenestratio user identifier
  - UserName
  - EMail
  - Branch
  - Install : user can be scheduled to do installations
  - Service : user can be scheduled to do service calls
  - Sales : user can do sales
  - CanMeasure : user can be scheduled to do measurements
  - CanDeliver : user can be scheduled to do deliveries
  - OtherSystemCode : other system code

selectCustomer

selectCustomer will retrieve a customer by its Fenestratio id or OtherSystemCode.
example (some url encoding omitted):


    https://.../api.jsp?fn=selectCustomer&Customer=10
    
or

    https://.../api.jsp?fn=selectCustomer&OtherSystemCode=abc128

Https Parameters:

fn : function name - always selectCustomer - mandatory
apiuid : caller's Fenestratio login id - mandatory
apipwd : caller's Fenestratio password - mandatory
Customer : optional integer
OtherSystemCode : optional 50 characters

Return JSON:

samples:
- {ok:1,fn:"findCustomers",Customer:9373,OtherSystemCode:"",
  rec:{Customer:9373, Name:"Ackerson, Charles & Mary", Address:"123 some street", City:"Chicago", Phone:"555-555-1212", Phone2:"555-555-1313", Phone3:"", OtherSystemCode:"ae39239ds832ff", CreatedAtLocal:"2018-11-04 16:12:00", CreatedAtUTC:"2018-11-04 22:12:00", UpdatedAtLocal:"2019-04-17 11:09:00", UpdatedAtUTC:"2019-04-17 17:09:00", contacts:[
  {Name:"Charles", Mail:"charles@bigco.com", PhoneCell:"7055551212", PhoneWork:"7055554444 ext 5530"} ,{...} ] }
  }
- {security:1,fn:"selectCustomer",Customer:9373,OtherSystemCode:""}
- {exc:"Unexpected error....",fn:"selectCustomer",Customer:9373}
- {ee:["Request logic error 1","Request Logic error 2"],fn:"selectCustomer",Customer:9373}
Return elements:
- ok : either 1 on success, or absent or 0 on failure
- security : login failed
- fn : always selectCustomer
- Customer : caller's Customer value passed
- OtherSystemCode : caller's OtherSystemCode value passed
- rec: Customer Record
  - Customer : Fenestratio customer identifier
  - Name
  - Address
  - City
  - State
  - Country
  - Phone
  - Phone2
  - Phone3
  - Fax
  - Tax Group
  - Lead Source
  - OtherSystemCode
  - CreatedAtLocal - yyyy-mm-dd hh:mm:ss
  - CreatedAtUTC - yyyy-mm-dd hh:mm:ss
  - UpdatedAtLocal - yyyy-mm-dd hh:mm:ss
  - UpdatedAtUTC - yyyy-mm-dd hh:mm:ss
  - contacts - array

upsertContact

upsertContact will create or update a contact in Fenestratio for the passed customer other system code or Fenestratio customer id

example (some url encoding omitted):
https://.../api.jsp?fn=upsertContact&co=Mary&cc=5555551213&em=mary@nospam.org&os=ae39239ds832ff
or
https://.../api.jsp?fn=upsertContact&co=Mary&cc=5555551213&em=mary@nospam.org&ro=11

If the name or email or cell phone passed matches an existing contact for the customer, Fenestratio will update the other values, otherwise Fenestratio will create a new contact. Https Parameters:

fn : function name - always upsertContact - mandatory
apiuid : caller's Fenestratio login id - mandatory
apipwd : caller's Fenestratio password - mandatory
Name : name - mandatory 80 characters
Mail : email: 255 characters
PhoneCell : cell phone - 10 characters AAAXXXNNNN NOT including country code
PhoneWork : work phone - 10 characters AAAXXXNNNN NOT including country code
OtherSystemCode : how calling system identifies contact - 50 characters
Customer : Fenestratio customer id

Return JSON:

samples:
- {ok:1,fn:"upsertContact",OtherSystemCode:"ae39239ds832ff",Contact:9238,OtherSystemCode:"ae39239ds832ff"}
- {security:1,fn:"upsertContact",OtherSystemCode:"ae39239ds832ff"}
- {exc:"Unexpected error....",fn:"upsertContact",OtherSystemCode:"ae39239ds832ff"}
- {ee:["Request logic error 1","Request Logic error 2"]",fn:" upsertContact",OtherSystemCode:"ae39239ds832ff"}
Return elements:
- ok : either 1 on success, or absent or 0 on failure
- security : login failed
- fn : always upsertContact
- OtherSystemCode : caller's contact identifier
- Contact : Fenestratio contact number on success

Rules:

optional values not passed will not be updated

upsertCustomer

..will create or update a customer in Fenestratio for the passed other system code, and return the Fenestratio customer id.

example (some url encoding omitted):
https://.../api.jsp?fn=createCustomer&nm=Smith, Mary %26 John&ad=123 some street&ct=Chicago &st=IL&cn=USA&pc=22456&p1=555-555-1252&fx=555-555-1213&em=mary@nospam.org &tc=HST&ls=Yellow Pages&os=ae39239ds832ff

Https Parameters:

fn : function name - always createCustomer - mandatory
apiuid : caller's Fenestratio login id - mandatory
apipwd : caller's Fenestratio password - mandatory
Customer : Fenestratio customer id - optional integer
Name : mandatory on insert - "Last, First1 & First2" best for Fenestratio - 255 characters - MUST BE UNIQUE
Address : street address - 50 characters
City : city - 35 characters
State : must map to abbreviations defined in Administration→States (ISO)
Country : 50 characters
Postal : postal/zip code - 10 characters
Phone : phone 1 - 50 characters
Phone2 : phone 2 - 50 characters
Phone3 : phone 3 - 50 characters
Fax : fax number - 50 characters
TaxGroup : must map to Administration→Tax Group, will default from company settings if not found
LeadSource : mapped to Maintenance→Lead Sources - new entries will create new lead source - 45 characters
OtherSystemCode : how calling system identifies customer - 50 characters
ContactName : primary contact name - only used on insert - 80 characters
ContactMail : primary contact email - only used on insert - 255 characters
ContactCell : primary contact cell phone - only used on insert - 10 characters AAAXXXNNNN NOT including country code
ContactOtherSystemCode : how calling system identifies contact - 50 characters

Return JSON:

samples:
- {ok:1,fn:"createCustomer",OtherSystemCode:"ae39239ds832ff",Customer:9238}
- {security:1,fn:"createCustomer",OtherSystemCode:"ae39239ds832ff"}
- {dup:1,fn:"createCustomer",OtherSystemCode:"ae39239ds832ff"}
- {exc:"Unexpected error....",fn:"createCustomer",OtherSystemCode:"ae39239ds832ff"}
- {ee:["Request logic error 1","Request Logic error 2"]",fn:"createCustomer",OtherSystemCode:"ae39239ds832ff"}
Return elements:
- ok : either 1 on success, or absent or 0 on failure
- security : login failed
- dup: a customer with the exact name passed already exists
- fn : always createCustomer
- OtherSystemCode : caller's customer identifier passed
- Customer : Fenestratio customer number on success, or absent

Rules:

optional values not passed will not be updated
if exact customer name already exists and neither Customer nor OtherSystemCode is found, response will include dup:1 element.