> For the complete documentation index, see [llms.txt](https://docs.keyfax.biz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keyfax.biz/integrations/apis/soap/quick-start.md).

# 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](/integrations/apis/rest-api.md) instead.
{% endhint %}

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

<figure><img src="/files/n6YPjv6X1wyiLFIMQboI" 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](/integrations/apis/soap/xml-schemas.md) section.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.keyfax.biz/integrations/apis/soap/quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.