How to Integrate with Pilot the Simplest Way
We’ll show you in a very simple way how you can submit a Lead or a Survey into our platform. If you need a more advanced integration, you can access our full API documentation for deeper implementations, just request access through our support page
Pilot CRM allows two different integration methods:
Leads
Easily connect the leads that come from your website or landing page. You can choose between two methods: Webhook: Recommended for speed and efficiency - Email: Use this method if you have no programming experience.
Surveys
Integrate contacts to create surveys, with the possibility of using dynamic data from other Pilot operations through a webhook.
Structure of a Lead
Each Lead entered into Pilot Solution® must comply with a specific parameter structure. Not all of them are required.
| Name | It is retrieved from the account that sends the email whenever possible. | |
|---|---|---|
| Last name | Lead's last name. | |
| Second Last Name | Applicable for second last names or maternal surnames. | |
| Telephone | Lead's telephone number. | |
| Mobile | Lead's mobile number. | |
| Contact Type | The method through which the person was contacted, for example: 1 - Electronic | 2 - Phone | 3 - In-person interview (Values may vary depending on the instance configuration.) | |
| Business Type | Code used to identify the business type the Lead comes from. For example: (1) New Vehicles / 0km | (2) Used | (3) Savings Plan. (Values vary depending on instance configuration). | |
| Notes | Comments or observations left by the lead on the pages where it gets. In case of e-commerce sites like Autotrader, cars.com, craiglist, etc. they send in this parameter the interest of the person (vehicle, finnancing, etc.) | |
| Origin | It is a identifier grouper from where the lead is obtained. It is only used on the graphic interface of Pilot, and its use is deprecated in the automatic interfaces. | |
| Subsource | Identify the lead primary source. It is obtain from subsources list of each client instance. It can be looked up in the system tables report called “data source”. | |
| Assigned seller | Indicate the seller to whom the lead will be assigned directly. For now, this parameter is only used in the graphic interface of Pilot. | |
| Brand | Vehicle Brand. | |
| Model | Vehicle Model. | |
| Service provider | Service name which provides the lead. It is a description of the source. It allows you to identify the service provider or the routing pattern in case you need dynamics assignements to different catch groups. | |
| Vehicle of interest | Vehicle from which the lead sent the query. In case this field is empty, it will be completed with the brand and the model of the indicated vehicle. | |
| Notifications Opt in | Indicate if the Lead agrees to receive notifications through any means of contact. | |
| Advertising Opt in | Indicate if the Lead agrees to receive advertising material through any means of contact. | |
| Address | Lead address street name. | |
| Number | Lead street numbering. | |
| Floor | Lead apartment floor. | |
| Apartment | Lead apartment. | |
| Zip code | Lead zip code. | |
| Birth date | Lead date of birth. | |
| Gender | Lead gender code. | |
| mandatory parameters |
First Steps
Our documentation explains the basic use of Web/HTTP and Pilot® calls. If you are not familiar with these techniques or you did not work with Web/HTTP before, please take a moment to do it before starting the job.
API Restful starting point
https://api.pilotsolution.net/webhooks/welcome.phpIMPORTANT: any answer that is not status 200 HTTP is an error.
Parameters Description
Every Lead submitted into Pilot Solution® must comply with a defined parameter structure. Not all of them are required.
action |
Fixed value "create" | |
|---|---|---|
appkey |
Alphanumeric value, e.g. 9715fc4b-17a8-4e56-ac7a-6deb5fd46u71, which can be requested from Pilot’s support team or retrieved from the Pilot configuration. | |
debug |
Numeric code (flag) used to test the service without sending the Lead into Pilot Solution®. Possible values are: 0 = no debug, the service runs normally. 1 = debug mode, the Lead is not submitted to Pilot Solution®. Example: 0 (no debug). | |
notification_email |
Email account used to receive a copy of the submitted data. | |
pilot_firstname |
Lead's name. | |
pilot_lastname |
Lead's last name. | |
pilot_second_lastname |
Lead's second last name. | |
pilot_phone |
Lead's telephone number. | |
pilot_cellphone |
Lead's mobile number. | |
pilot_email |
Lead's email. | |
pilot_contact_type_id (1) |
Medium by which the person is contacted. Numeric value. For example: 1. | |
pilot_contact_type_code (1) |
Medium by which the person is contacted. Text value. For example: "electronic". | |
pilot_business_type_id (2) |
Business type. Numeric value. For example: 1. | |
pilot_business_type_code (2) |
Business type. Text value. For example: "New". | |
pilot_notes |
Comments, interesting observations that the “actor” add when entes the lead. In case of a e-commerce site as Autotrader, cars.com, Cargurus, and so on, it is suggested to fulfill it with the person information of interest (ex: vehicle, finnancing, ...) | |
pilot_origin_id |
Grouper which identify from where the lead is obtained. It is only used in Pilot Solution graphic interface, and its use is deprecated in the automatic interfaces. | |
pilot_suborigin_id |
It is a code which identify the primary source of the lead. It is obtained by the subsource list of each client instance and can be looked up in the system tables report called “Leads Source” on the administration module. Ex: 1 (landing). | |
pilot_assigned_user |
Pilot user account to which you want to assign the lead. In this case, the manual assignment of the lead takes precedence over the lead capture groups. E.g., cuentausuario@dominio.com | |
pilot_car_brand |
Brand of the vehicle of interest. E.g., Ford | |
pilot_car_modelo |
Model of the vehicle of interest. E.g., Fiesta | |
pilot_city |
City of location. E.g., Capital Federal | |
pilot_province |
Province of location. E.g., Buenos Aires | |
pilot_country |
Country of location E.g., Argentina | |
pilot_vendor_name |
Name of the lead vendor or provider | |
pilot_vendor_email |
Email of the lead vendor or provider | |
pilot_vendor_phone |
Phone of the lead vendor or provider | |
pilot_provider_service |
Name of the service which provide the lead. It is a description of the source. It allows you to identify the service provider or the routing pattern in case you need dynamics assignements to different catch groups. | |
pilot_provider_url |
URL of service who collect the lead. | |
pilot_client_company |
Company name. | |
pilot_client_identity_document |
Lead identity document. | |
pilot_tracking_id |
Código de seguimiento: GUID o ID único que identifica al Lead en el origen. | |
pilot_client_ip |
IP del Lead al momento de la captura. | |
pilot_best_contact_time |
Best lead contact time. | |
pilot_product_code |
Product code according to Pilot’s price list. This causes the system to automatically generate a quotation for the lead. Products list can be obtained from the backend Products and codes may vary from month to month as brands and agencies are added or removed. |
|
pilot_product_of_interest |
Make and Model of the vehicle of interest to the Lead. | |
pilot_notificacions_opt_in_consent_flag |
Indicates if the Lead accepts to receive notifications through any means of contact. (1) Agree (0) Disagree | |
pilot_publicity_opt_in_consent_flag |
Indicates whether the Lead agrees to receive advertising material through any means of contact. (1) Agree (0) Disagree | |
pilot_address_street |
Street name of the lead address. | |
pilot_addresss_number |
Lead street numbering. | |
pilot_address_floor |
Lead apartment floor. | |
pilot_address_department |
Lead apartment. | |
pilot_address_postal_code |
Lead zip code. | |
pilot_birth_date |
Lead date of birth. It have to be expresed in this way: DD/MM/YY. | |
pilot_gender_code |
Lead gender code. This value is entered in the gender master. | |
| Mandatory | ||
| (1) |
(1) To receive webhooks, it is mandatory to provide at least one of the two fields. If both fields are completed, the lead will be created using the ID field as the primary source, not the CODE field. Both values are obtained by consulting the "Contact Type" master (welcome_contact_type). |
|
| (2) |
(2) To receive webhooks, it is mandatory to provide at least one of the two fields. If both fields are completed, the lead will be created using the ID field as the primary source, not the CODE field. Both values are obtained by consulting the "Business Type" master (business_type). |
|
Output format
Each API invocation returns a message in JSON format with information about the API execution.
Returning Values:
{
"success": Indicates if the integration was successful. Its possible values are: True - False,
"message": Text message which indicates if the lead was added successfully or not. Ex.: upload success: 'The data loading service was successfully executed' / wrong upload:'The required parameter appkey was not seted' ,
"data": Successfull integration: Displays each of the integrated data / Wrong integration; Describe error.
}
Response for an invalid request - Example:
{
"success":false,
"message":"Error",
"data":"The appkey required parameter was not configured"
}
Response for an invalid request - Example:
{
"success":boolean value - true o false,
"message":result message,
"data":{
"message": result message,
"assigned_user_id": id of the assigned Pilot user. If it is not assigned tag is not sent.
"success":boolean value - true o false indicates that it was inserted in the base correctl,
"id": Identifier of the registered lead. It is a numerical data.
}
}
Example:
{
"success":true,
"message":"Success",
"data":{
"message":"(3.2) The data upload service ran successfully.",
"assigned_user_id":80,
"success":true,
"id":8855
}
}
PHP Code example
Copy and paste the following code in a PHP file.
Then modify the configuration parameters and test with a form that has this page as an action.
You can also download an example of form code to add creativity here.
<?php //VARIABLES DE CONFIGURACION $serviceURL = "https://api.pilotsolution.net/webhooks/welcome.php"; $appKey = "aqui la key de la instancia correspondiente"; $tipoNegocio = "1"; $origendeldato = "7A2E4184"; $landing_link = "Landing Promo Mes"; //CAPTURA DE PARÁMETROS que pueden venir de un formulario $encoded = ""; $encoded .= urlencode('action').'=create&'; $encoded .= urlencode('appkey').'='.urlencode($appKey).'&'; $encoded .= urlencode('pilot_firstname').'='.urlencode(request("nombre",false,"n/a")).'&'; $encoded .= urlencode('pilot_lastname').'='.urlencode(request("apellido",false,"")).'&';$encoded .= urlencode('pilot_phone').'='.urlencode(request("telefono",false,"n/a")).'&'; $encoded .= urlencode('pilot_cellphone').'='.urlencode(request("celular",false,"")).'&'; $encoded .= urlencode('pilot_email').'='.urlencode(request("email",false,"")).'&'; $encoded .= urlencode('pilot_contact_type_id').'='.urlencode('1').'&'; //electronico $encoded .= urlencode('pilot_business_type_id').'='.urlencode($tipoNegocio).'&'; $encoded .= urlencode('pilot_business_type_code').'='.urlencode($tipoNegocio).'&'; $encoded .= urlencode('pilot_notes').'='.urlencode(request("comentarios",false,"Sin comentarios");).'&'; $encoded .= urlencode('pilot_suborigin_id').'='.urlencode($origendeldato).'&'; $encoded .= urlencode('pilot_provider_url').'='.urlencode($landing_link).'&'; $ch = curl_init($serviceURL); curl_setopt($ch, CURLOPT_FAILONERROR, true); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $encoded); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $output = curl_exec($ch); curl_close($ch); echo $output; die() ; // Levanta los parámetros por post o get function request($param, $required=true, $default="") { $result = $default; //veo si esta seteado el parámetro POST if (isset($_POST[$param])) { if($_POST[$param]!="") { $result = $_POST[$param]; } else { if ($required) { throw new Exception("Required parameter".$param." was not set"); } } } else if(isset($_GET[$param])) { if($_GET[$param]!="") { $result = $_GET[$param]; } else { if ($required) { throw new Exception("Required parameter".$param." was not set"); } } } else { if ($required) { throw new Exception("Required parameter".$param." was not set"); } } return $result; } ?>
Download example code
Download codeEmail integration
Format Parameters PHP example codeFormat
The format of the email is an ADF (xml information) that has the following content. In this case, the information that can be sent in the mail is more extensive and with more information.
Email format: preferably plain text.
Parameters
The lead provided is by way of example so that the content is understood.
<?xml version="1.0" encoding="UTF-8"?> <?adf version="1.0"?> <adf> <prospect> <requestdate>2013-06-27 11:26:24</requestdate> <vehicle> <brand>PEUGEOT</brand> <model>207</model> </vehicle> <customer> <contact> <name part="full">nombre completo del prospecto</name> <name part="first">nombre</name> <name part="last">apellido</name> <email>mail@domionio.com</email> <phone>1147899000</phone> <cellphone>1160403456</cellphone> <address> <city>Cuidad Autónoma de Buenos Aires</city> <province>Buenos Aires</province> <country>Argentina</country> </address> </contact> <comments> <![CDATA["I’m interest in buying a Ford Fiesta"]]> </comments> </customer> <vendor> <contact> <name part="full"></name> <email></email> <phone></phone> </contact> </vendor> <provider> <name>proveedor de datos</name> <service>Landing Venta Ford Fiesta</service> <notification_email></notification_email> <debug>0</debug> </provider> </prospect> <format> <formtype>pilot</formtype> <formversion>1</formversion> <key></key> </format> </adf>
Parameters shown in blue are constant and should not be changed.
Parameters shown in green are optional and serve to expand the information for the salesmen.
Parameters shown in red are the basics are the basics of the message and required.
If any data is not sent, the tag must be reported blank. So, the message must be complete.
Eg:
PHP example code
<?php
enviar_a_Pilot();
die();
function enviar_a_Pilot()
{
$REQUERIDO = true;
$NO_REQUERIDO = false;
$nombre = request("nombre",$REQUERIDO);
$apellido = request("apellido", $NO_REQUERIDO);
$telefono = request("telefono", $NO_REQUERIDO);
$celular = request("celular", $NO_REQUERIDO);
$email = request("email",$REQUERIDO);
$modeloAuto = request("modelo",$NO_REQUERIDO);
$comentarios = "Comment:".request("comentarios", $NO_REQUERIDO);
$provider = "Name of lead provider";
$landing = "Contact Form Type";
$linkLanding = "www.misitio.com/landing.php";
$provincia = request("region",$NO_REQUERIDO);
$to = "..."; //this account is set in PILOT CRM
$subject = "New contact of ".$nombre;
$cuerpoDelMail = armarCuerpoDelMail($nombre, $apellido, $telefono, $celular, $email, $modeloAuto, $comentarios, $landing, $linkLanding, $provincia, $provider);
//aqui se puede usar
if (enviarElMail("mi_cuenta@mail.com", $to, $subject, $cuerpoDelMail)) {
echo "Your request was sent succesfully.";
}
else {
echo "We could not process your request. Try later please.";
}
return true;
}
// Levanta los parámetros por post o get
function request($param, $required=true, $default="") {
$result = $default;
//veo si esta seteado el parametro POST
if (isset($_POST[$param])) {
if($_POST[$param]!="") {
$result = $_POST[$param];
}
else{
if ($required) {
throw new Exception("Required parameter".$param." was not set");
}
}
}
else if(isset($_GET[$param])) {
if($_GET[$param]!="") {
$result = $_GET[$param];
}
else {
if ($required) {
throw new Exception("Required parameter".$param." was not set");
}
}
}
else{
if ($required) {
throw new Exception("Required parameter".$param." was not set");
}
}
return $result;
}
//Function for sending emails
function enviarElMail($de, $para, $asunto, $cuerpodelmail) {
//Here implement the email sending function that is available on the server.
}
//This function returns the content of the body of the mail with the values already replaced
function armarCuerpoDelMail($nombre, $apellido, $telefono, $celular, $email, $modeloAuto, $comentarios, $landing, $linkLanding, $provincia, $provider) {
$result = '
<?xml version="1.0" encoding="UTF-8"?>
<?adf version="1.0"?>
<adf>
<prospect>
<requestdate>'.date("Y-d-m H:i:s").'</requestdate>
<vehicle>
<id></id>
<year></year>
<make>RENAULT</make>
<model>'.$modeloAuto.'</model>
<vin></vin>
<stock></stock>
<trim></trim>
<price type="asking"></price>
</vehicle>
<customer>
<contact>
<name part="full"></name>
<name part="first">'.$nombre.'</name>
<name part="last">'.$apellido.'</name>
<email>'.$email.'</email>
<phone>'.$telefono.'</phone>
<cellphone>'.$celular.'</cellphone>
<international_phone></international_phone>
<address>
<street></street>
<city>'.$provincia.'</city>
<regioncode></regioncode>
<postalcode></postalcode>
<country>Argentina</country>
</address>
</contact>
<comments>
<![CDATA["'.$comentarios.'"]]>
</comments>
</customer>
<vendor>
<vendorname></vendorname>
<contact>
<name part="full"></name>
<email></email>
<phone></phone>
</contact>
</vendor>
<provider>
<name>'.$provider.'</name>
<service>'.$landing.'</service>
<notification_email></notification_email>
<debug>0</debug >
<url><![CDATA["'.$linkLanding.']]></url>
</provider>
</prospect>
<format>
<formtype>pilot</formtype>
<formversion>1</formversion>
<key></key>
</format>
</adf>';
return $result;
}
?>
Survey Integration via Webhook
Survey Structure Getting Started RESTful API Starting Point Parameter Description Output FormatSurvey Structure.
Each Survey entered into Pilot Solution® must follow a specific parameter structure. Not all fields are required. Dynamic data may be used.
| Survey Type | Survey Type code. Defined by the Client. | Contact Name | Name of the customer who will receive the survey. |
|---|---|---|
| Contact Last Name | Last name of the customer who will receive the survey. | |
| Contact Telephone | Landline number of the customer to be surveyed. Must include at least one contact phone number. | |
| Branch | Sales branch, delivery location, or service workshop associated with the survey. | |
| Vehicle | Make, model, and version of the customer’s vehicle. | |
| License Plate | Vehicle license plate number of the customer to be surveyed. | |
| Contact Mobile | Mobile phone number of the customer to be surveyed. Must include at least one contact phone number. | |
| Contact Email | Email address of the customer to be surveyed. | |
| Event Date | For Sales: vehicle delivery date. For Aftersales: workshop release date. | |
| Internal Reference | Internal code. Internal reference for the operation. Example: receipt number, repair order, etc. | |
| Salesperson | Name of the salesperson. | |
| Sale Type | Type of operation that triggers the survey. Example: Used/New/etc. | |
| Administrative 1 | Name of the administrative person who handled the customer. | |
| Advisor | Name of the advisor who assisted the customer. | |
| Workshop Mechanic | Mechanic assigned to the main aftersales repair. | |
| Vehicle Position | Vehicle identifier in the source system. | |
| Generic 1 | Additional survey information field. | |
| Generic 2 | Additional survey information field. | |
| Generic 3 | Additional survey information field. | |
| Generic 4 | Additional survey information field. | |
| Generic 5 | Additional survey information field. | |
| Survey Start Date | Date of the first contact attempt. The date when survey management should begin. | |
| Vehicle VIN | Vehicle Identification Number. Contains 17 alphanumeric characters. | |
| Survey User | Email of the Pilot user to whom the survey will be assigned. | |
| mandatory parameters |
Getting Started
Our documentation explains the basic concepts for using Web/HTTP requests and Pilot Solution® in particular. If you are not familiar with these techniques or have not previously worked with Web/HTTP requests, please take a moment to review them before getting started.
Starting point of the RESTful API:
https://api.pilotsolution.net/webhooks/survey.phpIMPORTANT: any response other than HTTP status 200 is considered an error.
Parameter description
Each Survey submitted into Pilot Solution® must follow a specific parameter structure. Not all of them are required.action |
Fixed value: "create" | |
|---|---|---|
appkey |
Alphanumeric value, e.g. 9715fc4b-17a8-4e56-ac7a-6deb5fd46u71. Instance identifier, which can be requested from Pilot support or obtained from your Pilot configuration for the instance where the survey will be created. | |
surveytype |
Survey Type code. Defined by the Client. | |
checkrepited |
Numeric code, flag to indicate behavior with repeated surveys. Possible values: 0 = does not check for repeated surveys and creates all; 1 = checks for repeats and creates only one. Example: 0 (do not check repeats). | |
identificador_lote_carga |
Unique ID used to identify batch survey uploads from external systems. Typically encoded using: YYYYMMDDHHMMSS. External systems integrate in batches, e.g. workshop records to survey customers from the previous day. | |
nombre_contacto |
First name of the client who will be surveyed. | apellido_contacto |
Last name of the client who will be surveyed. |
telefono_contacto |
Landline phone number of the client to be surveyed. At least one contact phone is required. | |
sucursal |
Delivery location/Sales branch/Workshop. Retrieved from the instance’s branch list (see "Data Source" table report). | |
vehiculo |
Vehicle make, model and version of the client to survey. | |
dominio |
License plate/vehicle registration number of the surveyed client. | |
celular_contacto |
Mobile phone number of the client to survey. At least one contact number is required. | |
email_contacto |
Email of the person to be surveyed. | |
fecha_evento |
In Sales, this may be the delivery date of the vehicle; in Post-sale, the workshop departure date. | |
comprobante_interno |
Internal Code. Internal operation reference. E.g. ticket/worksheet/order number. | |
vendedor |
Sales representative name. | |
tipo_venta |
Operation type that triggered the survey (e.g. Used cars / Standard / etc.). | |
Administrativo1 |
Name of the administrative staff who assisted the client. | |
asesor |
Name of the advisor who assisted the client. | |
mecanico_taller |
Mechanic assigned to the main post-sale repair. | |
posicion_vehiculo |
Vehicle identifier in the source system. | |
generico_1 |
Additional survey information field. | |
generico_2 |
Additional survey information field. | |
generico_3 |
Additional survey information field. | |
generico_4 |
Additional survey information field. | |
generico_5 |
Additional survey information field. | |
fecha_inicio_gestion |
Date on which the survey management should begin. | |
vin_vehiculo |
Vehicle Identification Number (VIN). 17 alphanumeric characters. | |
id_venta_pilot |
Numeric ID. INTERNAL PILOT use only. | |
user_name_encuestador |
Email of the Pilot user to whom the survey will be assigned. | |
| required parameters |
Output Format
Each API invocation returns a JSON-formatted message with execution details.
Return Values:
{
"success":Indicates whether the integration was successful or not. Possible values: True - False,
"message":Text message indicating if the survey creation was successful or not. Example: successful request: 'The survey was created successfully' / failed request: 'Parameter sucursal not set',
"data":Successful integration: Displays each integrated data item / Failed integration: Describes the error.
}