Starting your form

To begin with there are some mandatory items that need to be in your form, to help we have included an example form at the top of this guide.

The first step is to initialise your post variables, this includes the URL, or web address, that you need to post your values to and an array called fields to contain the values you wish to post. Below you can see that we have set two variables: $url and $fields to accomplish this. Within the fields array you will soon be adding your desired fields.

$url = 'https://SITENAME.ekeeperonline.co.uk/php/NewMortgageQuickDetails.php';
$fields = array();

Note

The 'question mark' that appear in the URL should be replaced with the one in your systems URL, and 'yoursitename' should be replaced with the relevant site name in your systems URL. To find out what values you should use simply login to your system and look at the web address that appears in the address bar, the example below shows 4 in place of the question mark and trial in place of the yoursitename.

Before we can add our desired post values we must make sure that we include some mandatory values in our fields array. These are as follows:

Mandatory Fields

The mortgage/commercial mode value needs to be included:

For MortgageKeeper:
MortgageMode => 1
For CommercialKeeper:
CommercialMode => 1

You must include a stage identifier, which determines which stage your referred case appears in:

Example: 'StagePK'=>1

You must include an advisor identifier:

Example: 'AdvisorPK'=>12

You must submit a surname value for applicant 1:

Example: 'Surname1'=>($_POST['Surname'])

Where '$_POST['surname']' is the value posted from a field in your webform.

You must include a submit field with its value set to true.

'submit' => true

Note

To find the values for advisorPK, StagePK as well as others please head to the Available fields guide. This guide will show you how to obtain the values that should be submitted for these fields as they will be different for every eKeeper system.

Below is a completed example of how your might look now. Note that we have chosen mortgage mode and that your advisor, stage and surname values may be different. Also note that each row is terminated with a comma rather than a semicolon, this is so that you can add more fields later on that you wish to submit into.

$url = 'https://SITENAME.ekeeperonline.co.uk/php/NewMortgageQuickDetails.php';
$fields = array(
	//Mandatory fields go here:
	'MortgageMode' => urlencode(1), // OR 'CommercialMode => urlendcode(1), for CommercialKeeper
	'StagePK' => urlencode(1),
	'AdvisorPK' => urlencode(12),
	'Surname1' => urlencode($_POST['Surname']),


	//Other fields to post into go here:
	
	//Submit is also mandatory and typically is placed at the end of your array
	'submit' => true
);

Adding your fields

Adding your fields is easy, all you need to do is add additional lines within the $fields array. These need to follow the format below:

e.g. 'DayPhone' => urlencode($_POST['Title']),

Where DayPhone is the eKeeper field being posted into and $_POST['Title'] is a value from your web form. A typical setup for a form is included at the bottom of the example form attached at the top of this guide.

As mentioned previously, there are many fields that you can post into, for guidance on this please see the available fields guide.

Completing your form

The next steps include compiling the $field array values into a single string that will be passed into the URL, Opening a cURL connection, setting cURL session options, executing your post, sending a confirmation or notification email and closing the curl connection.

Compiling the $fields values into a string

To compile the $fields array values into a string we need to use a foreach loop, this will cycle through the key-value pairs, where the key is the eKeeper field name and the value is the value you are posting in your form, and then adds them to a variable called $fields_string.

Example:

If when adding your fields in the previous section, you have included the following line the $fields array:

'DayPhone' => urlencode($_POST['Title']),

Then this will be added to the $fields_string variable as follows:

where Title is a value posted in from your web form. Any example of a compiled $fields_string with several values is below:

See below for a finished foreach block of code that will iterate through the $fields array and add them to the $fields_string variable. resulting in the $fields_string variable containing a string similar to the example above.

Opening a cURL connection

To open a connection use the curl_init function in PHP

Setting cURL session options

Next we need to set the following options for the cURL session:

The URL to post into
The number of fields that are going to be passed into the URL
The POST fields and their values as a string
The return transfer to true, so that it will return a string of the return value

Executing your post

Now that we have set the options and values that will be posted into eKeeper, we need to execute (confirm) our post. This is done using the php curl_exec() function. It is a good idea to apply the result of this function to a variable. In the example below we have set the result of this to the $result variable.

Closing the curl session

Finally once the curl session has been executed, it is important to close the session using the PHP curl_close() function. Note that $ch has been passed into this function as this is the session that was initialised earlier on.

Your completed code

Now that you have followed the steps above you should have something that looks very similar to the example below. Note that yours may contain many more values in the $fields array

Debugging your form

If your post to eKeeper fails e.g. the lead never appears. You will want to know what has happened. You can add two lines of code that will output information regarding the last cURL request.

You can include these lines permanently but comment them out to prevent them from running unless required

Responses

Success Response

A sample success response has been provided below. This lists the application that was created, and the customers and companies that were created.

Validation Error Response

When a validation error occurs e.g. you are sending alpha characters where an integer is expected or an invalid date is passed etc. Then a product is still created in the CRM, however a new section to the xml response will display as shown below.

An element for each validation error will be displayed in the response informing the post originator of the error and the fact that the value has been excluded from the the post.

Error code responses

400 - Missing required values from http post
403 - forbidden
501 - no product found (if product subtype is passed, and is not found in the system)
501 - duplicate submission

Glossary

In this article we have used various terms and referred to various PHP functions. See below for a list of the terms and functions used and some links to helpful reference information.

Term	Description	More information

Term	Description	More information
curl_init()	This is a PHP function used to initilise a cURL connection	http://php.net/manual/en/function.curl-init.php
urlencode()	This is a PHP function and is used to remove all non-alphanumeric characters from the value passed into it and replaces them with relevant symbols allowing the value to be posted as part of a URL query	http://php.net/manual/en/function.urlencode.php
array()	An array in PHP is an ordered collection	http://php.net/manual/en/language.types.array.php
c url_setopt()	This is a PHP function that is used to set an option for the current cURL session for example the URL to be used	http://us2.php.net/manual/ro/function.curl-setopt.php
curl_getinfo()	This is a PHP function that is used to get information about the last transfer.	http://php.net/manual/en/function.curl-getinfo.php
curl_close()	This is a PHP function that is used to close a cURL session	http://php.net/manual/en/function.curl-close.php

Service Desk

HTTP Posting - Getting Started