# Start-Up Data

{% hint style="warning" %}
The `mode`, `company` & `scriptSet` attributes provided within the examples below would need to be updated & configured correctly to match your Keyfax configuration. Please contact Omfax Systems for assistance preparing your Keyfax start-up data.
{% endhint %}

The minimal start-up data required in order for Keyfax to return launch data is shown below. These examples are only provided for demonstration purposes and start-up data should be tailored to suit your environment & integration. 

You would pass start-up data into `POST /api/v1/startup` to obtain Keyfax launch data allowing you to launch a Keyfax session. Example minimal start-up data in both JSON & XML is provided below.

**JSON**

```
var startUpData = {     
    mode: { value: "RD" },
    userName: { value: "administrator" },
    password: { value: "" },
    company: { value: "RDFL_Dev" },            
    scriptSet: { value: "RD" }               
};
```

**XML**

```
<?xml version="1.0" encoding="UTF-8"?>
<StartUpData>
   <Mode>
      <Value>RD</Value>
   </Mode>
   <UserName>
      <Value>administrator</Value>
   </UserName>
   <Password>
      <Value>Global</Value>
   </Password>
   <Company>
      <Value>RDFL_Dev</Value>
   </Company>
   <ScriptSet>
      <Value>RD</Value>
   </ScriptSet>
</StartUpData>
```

### **Posting Start-Up Data**

Whilst you will always need to provide a minimal set of start-up data it's also possible to post custom start-up data into Keyfax. This custom start-up data can be used within Keyfax to provide dynamic or intelligent scripting. Any supplied custom start-up data can also be flowed through Keyfax and made available again within the final results produced by Keyfax when calling `POST /api/v1/results`.

The example start-up JSON below demonstrates how to include custom data within the request to `POST /api/v1/startup` via the Keyfax Web API [JavaScript SDK](/integrations/apis/rest-api/api-sdks/javascript-sdk.md)...

```
{
   "mode":{
      "value":"RD"
   },
   "userName":{
      "value":"administrator"
   },
   "password":{
      "value":"Global"
   },
   "company":{
      "value":"RDFL_Dev"
   },
   "scriptSet":{
      "value":"RD"
   },
   "customData":{
      "key":"CustomData",
      "children":[
         {
            "key":"CustomFields1",         
            "children":[
               {
                  "key":"CustomField1",                
                  "value":"Example Value 1"             
               },
               {
                  "key":"CustomField2",              
                  "value":"Example Value 2"              
               }
            ]
         },
         {
            "key":"CustomFields2",    
            "children":[
               {
                  "key":"CustomField1",              
                  "value":"Example Value 1"                
               },
               {
                  "key":"CustomField2",             
                  "value":"Example Value 2"              
               }
            ]
         }
      ]
   }
}
```

The example C# code below shows how to build this same custom start-up data using the strongly typed Keyfax Web API [.NET SDK](/integrations/apis/rest-api/api-sdks/.net-sdk.md)...

```
// Build a sample JSON payload, values are hard coded as this is for demonstration purposes only
var startUpData = new StartUpData()
{
    Mode = new StartUpDataItem()
    {
        Value = "RD"
    },
    UserName = new StartUpDataItem()
    {
        Value = "administrator"
    },
    Password = new StartUpDataItem()
    {
        Value = "Global"
    },
    Company = new StartUpDataItem()
    {
        Value = "RDFL_Dev"
    },
    ScriptSet = new StartUpDataItem()
    {
        Value = "RD"
    },
    CustomData = new StartUpDataItem()
    {
        Key = "CustomData",
        Children = new List<StartUpDataItem>()
        {
            new StartUpDataItem()
            {
                Key = "CustomFields1",
                Children = new List<StartUpDataItem>()
                {
                    new StartUpDataItem()
                    {
                        Key = "CustomField1",
                        Value = "Child Example Value 1"
                    },
                    new StartUpDataItem()
                    {
                        Key = "CustomField2",
                        Value = "Child Example Value 2"
                    }
                }
            },
            new StartUpDataItem()
            {
                Key = "CustomFields2",
                Children = new List<StartUpDataItem>()
                {
                    new StartUpDataItem()
                    {
                        Key = "CustomField1",
                        Value = "Child Example Value 1"
                    },
                    new StartUpDataItem()
                    {
                        Key = "CustomField2",
                        Value = "Child Example Value 2"
                    }
                }
            },
        }
    },
};
```

### **Start Up Data Examples**

Below we've provided several examples showing the start-up data you would typically supply to Keyfax. These are just examples to help demonsteate what's possible. The start-up data you provide to Keyfax would typically be customized based on your integration.&#x20;

#### Minimal Start-Up Data Examples

**Staff (RD / FL)**

```
{
    "originatingSystem": {     
        "value": "https://yourdomain.com/"
    },
    "company": {
        "value": "Staff_Live"
    },
    "mode": {
         "value": "RD"
    },
    "userName": {
        "value": "operator"
    },
    "password": {
        "value": "Global"
    },
    "scriptSet": {   
        "id": "scriptSetCode",
        "value": "RD"
    }
}
```

**Online (ROL / EOL)**

```
{
    "originatingSystem": {     
        "value": "https://yourdomain.com"
    },
    "company": {
        "value": "Online_Live"
    },
    "mode": {
         "value": "ROL"
    },
    "userName": {
        "value": "KFROL_User"
    },
    "password": {
        "value": ""
    },
    "scriptSet": {   
        "id": "scriptSetCode",
        "value": "ROL"
    }
}
```

#### Full Start- Up Data Examples

The below illustrates some realistic start-up data you would typically post to Keyfax via `/api/v1/startup`. This is only to serve as an example and to show what's possible. Host systems would typically work with Omfax Systems to craft this start-up data based on your specific requirements & configuration.

**Staff (RD/FL)**

```
{
	"originatingSystem": {
		"value": "https://yourdomain.com"
	},
	"company": {
		"value": "Staff_Live"
	},
	"mode": {
		"value": "RD"
	},
	"scriptSet": {
		"value": "RD"
	},
	"userName": {
		"value": "operator"
	},
	"password": {
		"value": "Global"
	},
	"returnUrl": {
		"value": "https://yourdomain.com/keyfax-completed?status={0}&co={1}&guid={2}&user={3}"
	},
	"tenant": {
		"value": "James Sopher, 12 Teal Road, Parkstone, Poole, Dorset, BH14 8UB"
	},
	"assetId": {
		"value": "T20"
	},
	"callerDetails": {
		"children": [
			{
				"key": "CallerID",
				"value": "CE21A"
			},
			{
				"key": "FirstName",
				"value": "James"
			},
			{
				"key": "LastName",
				"value": " Sopher"
			},
			{
				"key": "CallerEmail",
				"value": "jsopher1987@gmail.com"
			},
			{
				"key": "Mobile",
				"value": "07555 499877"
			},
			{
				"key": "DOB",
				"value": "1987-05-24T00:00:00.000Z"
			},
			{
				"key": "Vulnerable",
				"value": "N"
			},
			{
				"key": "MobilityIssues",
				"value": "N"
			},
			{
				"key": "Vulnerability",
				"value": ""
			},
			{
				"key": "GenderPronoun",
				"value": "he/him"
			},
			{
				"key": "Financials",
				"children": [
					{
						"key": "Rent",
						"value": 145
					},
					{
						"key": "CurrentBalance",
						"value": 345
					}
				]
			}
		]
	},
	"tenancyDetails": {
		"children": [
			{
				"key": "TenureType",
				"value": "Assured"
			},
			{
				"key": "HousingOfficer",
				"value": "Tina Jones"
			}
		]
	},
	"property": {
		"children": [
			{
				"key": "AddressLine1",
				"value": "12 Teal Road"
			},
			{
				"key": "AddressLine2",
				"value": "Parkstone"
			},
			{
				"key": "AddressLine3",
				"value": "Poole"
			},
			{
				"key": "AddressLine4",
				"value": "Dorset"
			},
			{
				"key": "AddressLine5",
				"value": "BH14 8UB"
			},
			{
				"key": "HeatingType",
				"value": "Gas"
			},
			{
				"key": "ComponentData",
				"children": [
					{
						"key": "Component",
						"children": [
							{
								"key": "Type",
								"value": "Gas Boiler"
							},
							{
								"key": "Make",
								"value": "Worcester"
							},
							{
								"key": "Model",
								"value": "Greenstar 30"
							},
							{
								"key": "InstallDate",
								"value": "2020-03-24T00:00:00.000Z"
							},
							{
								"key": "WarrantyPeriod",
								"value": "24"
							},
							{
								"key": "WarrantyExpiryDate",
								"value": "2022-03-24T00:00:00.000Z"
							},
							{
								"key": "NextServiceDate",
								"value": "2035-03-24T00:00:00.000Z"
							}
						]
					}
				]
			},
			{
				"key": "PlannedMaintenance",
				"children": [
					{
						"key": "PMJob",
						"children": [
							{
								"key": "ProgrammeDescription",
								"value": "Windows"
							},
							{
								"key": "NextPlannedDate",
								"value": "03/01"
							}
						]
					}
				]
			}
		]
	}
}
```

**Online (ROL/EOL)**

```
{
   "originatingSystem":{
      "value":"https://yourdomain.com"
   },
   "company":{
      "value":"Online_Live"
   },
   "mode":{
      "value":"ROL"
   },
   "scriptSet":{
      "value":"ROL"
   },
   "userName":{
      "value":"KFROL_User"
   },
   "password":{
      "value":""
   },
   "returnUrl":{
      "value":"https://yourdomain.com/keyfax-completed?status={0}&co={1}&guid={2}&user={3}"
   },
   "tenant":{
      "value":"James Sopher, 12 Teal Road, Parkstone, Poole, Dorset, BH14 8UB"
   },
   "assetId":{
      "value":"T20"
   },
   "callerDetails":{
      "children":[
         {
            "key":"CallerID",
            "value":"CE21A"
         },
         {
            "key":"FirstName",
            "value":"James"
         },
         {
            "key":"LastName",
            "value":" Sopher"
         },
         {
            "key":"CallerEmail",
            "value":"jsopher1987@gmail.com"
         },
         {
            "key":"Mobile",
            "value":"07555 499877"
         },
         {
            "key":"DOB",
            "value":"1987-05-24T00:00:00.000Z"
         },
         {
            "key":"Vulnerable",
            "value":"N"
         },
         {
            "key":"MobilityIssues",
            "value":"N"
         },
         {
            "key":"Vulnerability",
            "value":""
         },
         {
            "key":"GenderPronoun",
            "value":"he/him"
         },
         {
            "key":"Financials",
            "children":[
               {
                  "key":"Rent",
                  "value":145
               },
               {
                  "key":"CurrentBalance",
                  "value":345
               }
            ]
         }
      ]
   },
   "tenancyDetails":{
      "children":[
         {
            "key":"TenureType",
            "value":"Assured"
         },
         {
            "key":"HousingOfficer",
            "value":"Tina Jones"
         }
      ]
   },
   "property":{
      "children":[
         {
            "key":"AddressLine1",
            "value":"12 Teal Road"
         },
         {
            "key":"AddressLine2",
            "value":"Parkstone"
         },
         {
            "key":"AddressLine3",
            "value":"Poole"
         },
         {
            "key":"AddressLine4",
            "value":"Dorset"
         },
         {
            "key":"AddressLine5",
            "value":"BH14 8UB"
         },
         {
            "key":"HeatingType",
            "value":"Gas"
         },
         {
            "key":"ComponentData",
            "children":[
               {
                  "key":"Component",
                  "children":[
                     {
                        "key":"Type",
                        "value":"Gas Boiler"
                     },
                     {
                        "key":"Make",
                        "value":"Worcester"
                     },
                     {
                        "key":"Model",
                        "value":"Greenstar 30"
                     },
                     {
                        "key":"InstallDate",
                        "value":"2020-03-24T00:00:00.000Z"
                     },
                     {
                        "key":"WarrantyPeriod",
                        "value":"24"
                     },
                     {
                        "key":"WarrantyExpiryDate",
                        "value":"2022-03-24T00:00:00.000Z"
                     },
                     {
                        "key":"NextServiceDate",
                        "value":"2035-03-24T00:00:00.000Z"
                     }
                  ]
               }
            ]
         },
         {
            "key":"PlannedMaintenance",
            "children":[
               {
                  "key":"PMJob",
                  "children":[
                     {
                        "key":"ProgrammeDescription",
                        "value":"Windows"
                     },
                     {
                        "key":"NextPlannedDate",
                        "value":"03/01"
                     }
                  ]
               }
            ]
         }
      ]
   }
}
```

### Custom Start-Up Data

You can supply custom / non-standard fields within the Keyfax start-up JSON using the `customData` property as shown below\...

```
"customData": {
	"key": "CustomRoot1", 
	"children": [
		{
			"key": "CustomRoot1_Child1", 
			"value": "Child 1 Value", 
		},
		{
			"key": "CustomRoot1_Child2", 
			"value": "Child 2 Value", 
		}
	]
}
```

This will be converted to the following start-up XML...

```
<CustomRoot1>
	<CustomRoot1_Child1>Child 1 Value</CustomRoot1_Child1>
	<CustomRoot2_Child1>Child 2 Value</CustomRoot1_Child1>
</CustomRoot1>
```

This would then be accessible within Keyfax via import data boxes (i.e.e `//CustomData/CustomRoot1/CustomRoot1_Child1/@text()`)

You can also nest custom properties as demonstrated below\...

```
"customData": {
	"key": "CustomProperty", 
	"children": [
		{
			"key": "Children", 
			"children": [
				{
					"key": "Child1", 
					"value": "Child 1 Value", 
				},
                                {
					"key": "Child2", 
					"value": "Child 2 Value", 
				}
			]
		}
	]
}
```

This will produce the following start-up XML...

```
<CustomProperty>
	<Children>
		<Child1>Child 1 Value</Child1>
		<Child2>Child 2 Value</Child2>
	</Children>
</CustomProperty>
```

#### **Custom Start Up Data Example**

Consider the following start-up JSON...

```
{
        "originatingSystem": {
            "value": "LaunchExample"
        },
        "company": {
            "value": "LiveWest_Online_Test" 
        },
        "mode": {
             "value": "ROL"
        },
        "userName": {
            "value": "KFROL_User"
        },
        "password": {
            "value": ""
        }, 
        "returnUrl": {
            "value": "http://keyfaxtest.com:8011/Completed.html?status={0}&co={1}&guid={2}&user={3}"
        },     
        "assetId": { 
            "value": "0" 
        },
        "clientId": { 
            "value": "0" 
        },
        "customData": {
	        "key": "CustomData", 
	        "children": [    
		        {
			        "key": "TenancyTypeDescription", 
			        "value": "Example tenancy type description"
		        },
                {
			        "key": "CategoryTypeDescription", 
			        "value": "Example category type description"
		        },
		        {
			        "key": "ActualHandoverDate", 
			        "value": "2023-06-01"
		        }
	        ]
        }
    }
```

This would actually be supplied to Keyfax as XML in the form...

```
<KeyfaxData>
	<Startup>
		<OriginatingSystem>LaunchExample</OriginatingSystem>
		<Mode>ROL</Mode>
		<UserName>KFROL_User</UserName>
		<Password />
		<Company>LiveWest_Online_Test</Company>
		<ClientId>0</ClientId>
		<ReturnURL>
			<![CDATA[http://keyfaxtest.com:8011/Completed.html?status={0}&co={1}&guid={2}&user={3}]]>
		</ReturnURL>
		<AssetID>0</AssetID>
		<CustomData>
			<TenancyTypeDescription>Example tenancy type description</TenancyTypeDescription>
			<CategoryTypeDescription>Example category type description</CategoryTypeDescription>
			<ActualHandoverDate>2023-06-01</ActualHandoverDate>
		</CustomData>
		<GUID>
			<![CDATA[9f360185-82a1-4121-aa5b-ca3d0f4e1452]]>
		</GUID>
		<ScriptSet>
			<![CDATA[ROL]]>
		</ScriptSet>
		<ROLDetail>
			<![CDATA[]]>
		</ROLDetail>
	</Startup>
</KeyfaxData>
```

So to access values within the `<CustomData/>` element you can use XPath expressions within existing Import data boxes as shown below\...

<figure><img src="/files/rDZA5kNr4wcw0nErfcKu" alt=""><figcaption><p>Using Start-Up Data Within a Keyfax Script via Import Databoxes</p></figcaption></figure>

#### **Exporting Custom Start-Up Data**

If you supply custom start-up data and wish to expose this within results produced by Keyfax the export template used by Keyfax will need to be updated to include any custom start-up data.

We would always suggest contacting Omfax Systems to better understand your requirements. We will work with you to tailor your start-up & export data to suit your integration and ensure you get the most from Keyfax.


---

# Agent Instructions: 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:

```
GET https://docs.keyfax.biz/integrations/apis/rest-api/api-sdks/start-up-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.