# Quick Start

These pages detail the processes to launch Keyfax and to obtain the diagnostic results. Both the **launching** of Keyfax and **returning** the results are processed through the **KeyfaxWS** web service. This is the preferred/recommended solution for all future integrations, be those with host Housing Management Systems or online portals.

{% hint style="info" %}
**NOTE** We recommend use of the Keyfax SOAP based web services under the **HTTPS** protocol. You may also wish to consider using the Keyfax [rest-api](https://docs.keyfax.biz/integrations/apis/rest-api "mention") instead.
{% endhint %}

In essence, this is the sequence of events...

<figure><img src="https://2882349412-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MARm6St_qFGM52R3pBa%2Fuploads%2FmHAoGmRjR3a3NAetgZH1%2Fkeyfaxws3.png?alt=media&#x26;token=70e9522c-e965-45a2-b451-34e4b899be25" alt=""><figcaption><p>The SOAP based web services flow.</p></figcaption></figure>

### Startup

**Parameters**

* startupXml=string

The Startup web method is a SOAP call which takes a **single string\* parameter** containing the appropriate start-up data in XML format.

\*Although we try to adhere to a standard generic XML schema, there have, and will continue to be, exceptions and by passing **a string** this avoids the need for separate webservice descriptors (WSDL).

#### ReturnUrl Query String Parameters

The start-up xml **ReturnUrl** value can have up to 4 query string parameters included to help the host system/portal retrieve the results. These can be included directly in the ReturnUrl value with placeholders "{n}" as follows:

* {0} replaced with the ResultStatus
* {1} replaced with the company config code
* {2} replaced with the GUID
* {3} replaced with the userId

E.g. a ReturnUrl could be sent in the start-up xml with parameters as follows:

* **status={0}\&co={1}\&guid={2}**

If a ReturnUrl is sent in the start-up xml with no placeholders specified, the following parameters will automatically be added:

* **status={0}\&guid={2}**

### Startup Response

The Startup web service returns a **LaunchUrl** and **GUID**. The launchUrl already contains the GUID as a query string parameter and can be used unmodified to launch Keyfax. The GUID is provided separately as it may be of use in future extensions to the integration.

In case of an error, a single ErrorText element is returned with an appropriate error description. Further details will be recorded in the Keyfax error log for further investigation if required.

**Startup Return Xml:**

```
<?xml version="1.0" encoding="utf-8"?>  
<WSStartupGuid xmlns="http://keyfax.touch-base.com/">  
  <Guid>string</Guid>  
  <LaunchUrl>string</LaunchUrl>  
</WSStartupGuid>    
```

**Error Return Xml:**

```
<?xml version="1.0" encoding="utf-8"?>  
<WSStartupGuid xmlns="http://keyfax.touch-base.com/">  
  <ErrorText>string</ErrorText>  
</WSStartupGuid>
```

### GetResults

#### Parameters

* company=string
* guid=string

The GetResults web method requires a **Company** and a **GUID** parameter to retrieve the results. The Company must match the Company value passed in the original start-up xml and the GUID value must match the GUID passed as a query string parameter on the return url (as provided in the original start-up xml).

GetResults returns a **ResultStatus** and **ResultXml** string containing the diagnostic result xml. As with Startup, in case of an error a single **ErrorText** element is returned with an appropriate error description.

### **GetResults Response**

```
<?xml version="1.0" encoding="utf-8"?>  
<WSGetResult xmlns="http://keyfax.touch-base.com/">  
  <ResultStatus>string</ResultStatus>  
  <ResultXml>string</ResultXml>  
</WSGetResult>  
```

### **GetResults Error Response**

```
<?xml version="1.0" encoding="utf-8"?>  
<WSGetResult xmlns="http://keyfax.touch-base.com/">  
  <ErrorText>string</ErrorText>  
</WSGetResult>  
```

The **ResultStatus** = "1" indicates **completed** and "2" indicates a **cancelled** script. A sample for each status is given in the following sections.

A completed script sample as returned in the ResultXml string can be found within the XML Schemas section.

**Notes:**

Multiple Repair, Advice, Action and SubAction elements can be returned.

**Examples:**

* Cancelled script sample as returned in the ResultXml string can be viewed within the XML Schemas section.
* An enquiry which has generated a Note task can be viewed within the [xml-schemas](https://docs.keyfax.biz/integrations/apis/soap/xml-schemas "mention") section.