PHP samples – Kartra Documentation

PHP sample: searching for a specific lead

Here’s a very simple PHP sample to SEARCH for an existing lead:

<?php

$ch = curl_init();
// CONNECT TO API, VERIFY MY API KEY AND PASSWORD AND GET THE LEAD DATA
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'app_id' => 'AIm863DwsOW',
            'api_key' => 'QG9GPLW8G',
            'api_password' => 'kdwFAfwrfVS',
            'lead' => array(
                'id' => '3232323223', //you may pass either ID or EMAIL. If both, the system will pick ID
                'email' => 'JoeSmith@domain.com',     
            ),
            'actions' => array(
                '0' => array(
                       'cmd' => 'search_lead',
                 ),
            )
      )
   )
);

// REQUEST CONFIRMATION MESSAGE FROM API…
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);
$server_json = json_decode($server_output);
switch ($server_json->status) {
    case "Error" :
        // process what error was about
        break;
    case "Success" :
        // after this you can use the info passed from kartra in your own scripts. 
        // Ex: $server_json->lead_details contains the lead details.
        break;
}

?>

PHP sample: editing a specific lead

Here’s a very simple PHP sample to EDIT a lead’s details plus, in the same API call, we will also assign a tag (yes, you can chain two or more actions inside the same API call):

<?php

$ch = curl_init();
// CONNECT TO API, VERIFY MY API KEY AND PASSWORD AND GET THE LEAD DATA
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'app_id' => 'AIm863DwsOW',
            'api_key' => 'QG9GPLW8G',
            'api_password' => 'kdwFAfwrfVS',
            'lead' => array(
                'id' => '3232323223', //you may pass either ID or EMAIL. If both, the system will pick ID
                'email' => 'JoeSmith@domain.com',
                'first_name' => 'Joe New',
                'last_name' => 'Smith New',
                'custom_fields' => [
                    '0' => [
                               'field_identifier' => 'text1',
                               'field_value' => 'text message'
                           ],
                    '1' => [
                               'field_identifier' => 'dropdown1',
                               'field_value' => '612'
                           ],
                    '2' => [
                               'field_identifier' => 'checkbox1',
                               'field_value' => ['620', '621']
                           ],
                ], // Please read Note (1) below 
                'new_email' => 'JoeSmith+new@domain.com' 
            ), 
            'actions' => array( 
                '0' => array( 
                    'cmd' => 'edit_lead'
                ), 
                '1' => array( 
                    'cmd' => 'assign_tag', 
                    'tag_name' => 'My customer' 
                ) 
            ) 
        ) 
     ) 
  ); // REQUEST CONFIRMATION MESSAGE FROM API… curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $server_output = curl_exec ($ch); curl_close ($ch); $server_json = json_decode($server_output); switch ($server_json->status) { case "Error" : // process what error was about break; case "Success" : // after this you can use the info passed from kartra in your own scripts. // Ex: $server_json->lead_details contains the lead details break; } ?>

Note (1): Custom field names must already exist in your Kartra account. Otherwise, if the system cannot find the corresponding custom name, it will ignore it.

PHP sample: creating a lead

Here’s a very simple PHP sample to CREATE a lead plus, in the same API call, we will also assign a tag (yes, you can chain two or more actions inside the same API call):

<?php

$ch = curl_init();
// CONNECT TO API, VERIFY MY API KEY AND PASSWORD AND GET THE LEAD DATA
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'app_id' => 'AIm863DwsOW',
            'api_key' => 'QG9GPLW8G',
            'api_password' => 'kdwFAfwrfVS',
            'lead' => array(
                'email' => 'JoeSmith@domain.com',
                'first_name' => 'Joe',
                'last_name' => 'Smith',           
                'custom_fields' => [
                    '0' => [
                               'field_identifier' => 'text1',
                               'field_value' => 'text message'
                           ],
                    '1' => [
                               'field_identifier' => 'dropdown1',
                               'field_value' => '612'
                           ],
                    '2' => [
                               'field_identifier' => 'checkbox1',
                               'field_value' => ['620', '621']
                           ],
                ]  // Please read Note (1) below 
            ),
            'actions' => array(
                '0' => array(
                       'cmd' => 'create_lead',
                ),
                '1' => array(
                       'cmd' => 'assign_tag',
                       'tag_name' => 'My customer'
                )
            )
      )
   )
);

// REQUEST CONFIRMATION MESSAGE FROM API…
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);
$server_json = json_decode($server_output);
switch ($server_json->status) {
    case "Error" :
        // process what error was about
        break;
    case "Success" :
        // after this you can use the info passed from kartra in your own scripts. 
        // Ex: $server_json->lead_details contains the lead details
        break;
}

?>

Note (1): Custom field names must already exist in your Kartra account. Otherwise, if the system cannot find the corresponding custom name, it will ignore it.

PHP sample: retrieving data for a specific lead

Here’s a very simple PHP sample to retrieve data from a specific lead’s profile from your contacts database.

<?php

$ch = curl_init();
// CONNECT TO API, VERIFY MY API KEY AND PASSWORD AND GET THE LEAD DATA
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'app_id' => 'AIm863DwsOW',
            'api_key' => 'QG9GPLW8G',
            'api_password' => 'kdwFAfwrfVS',
            'get_lead' => array(
                'email' => 'JoeSmith@domain.com',
            ),
        )
    )
);

// REQUEST CONFIRMATION MESSAGE FROM API…
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);
$server_json = json_decode($server_output);
switch ($server_json->status) {
    case "Error" :
        // process what error was about
        break;
    case "Success" :
        // after this you can use the info passed from kartra in your own scripts. 
        // Ex: $server_json->lead_details contains the lead details
        break;
}

?>

PHP sample: execute actions to a specific lead

Here’s a very simple PHP sample to execute multiple actions to one specific lead. First, let’s study the flow in the code:

First, we ping Kartra API’s secure URL
Then, we connect via to our Kartra App ID (AIm863DwsOW), injecting our customer’s unique Kartra API key (QG9GPLW8G) and Kartra API password (kdwFAfwrfVS). Obviously, you will have a different key and password.
Then, we identify the lead this API call is for ( JoeSmith@domain.com ), whose full name is “Joe Smith”. If the system finds a lead with this email in our contacts database, it will overwrite the lead’s details in the lead’s profile with the new data we’re passing over. Alternatively, if the lead is not found, it will create it as a brand new contact.
Then, we pass 3 actions for that lead: subscribe him or her to list “My customers newsletter”, assign him or her the tag “My customer”, and add +12 points to his or her score. Note how each action is wrapped around its own array!
After all that, we request a confirmation response from the API
Finally, we apply an “IF” conditional for further instructions depending on whether the command was successful or not. Note how we use the “Type” parameter to identify the message type.

<?php
$ch = curl_init();
// CONNECT TO THE API SYSTEM VIA THE APP ID, AND VERIFY MY API KEY AND PASSWORD, IDENTIFY THE LEAD, AND SEND THE ACTIONS…
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
http_build_query(
array(
'app_id' => 'AIm863DwsOW',
'api_key' => 'QG9GPLW8G',
'api_password' => 'kdwFAfwrfVS',
'lead' => array(
'email' => 'JoeSmith@domain.com',
),
'actions' => array(
'0' =>array(
'cmd' => 'subscribe_lead_to_list',
'list_name' => 'My customers newsletter'
),
'1' =>array(
'cmd' => 'assign_tag',
'tag_name' => 'My customer'
),
'2' =>array(
'cmd' => 'give_points_to_lead',
'points' => '12'
),
)
)
)
);
// REQUEST CONFIRMATION MESSAGE FROM API…
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);
$server_json = json_decode($server_output);

/* JSON SAMPLE ERROR MESSAGES:
{
"status":"Error",
,"message":"API key cannot be empty. Please get an API key first",
,"type":"202"
}
JSON SAMPLE SUCCESS MESSAGES:

{
"status":"Success"
,"lead":{"Status":"Found"}
,"actions":[
{
"subscribe_lead_to_list":
{
"status":"Success"
,"message":"Lead subscribed in list My customers
list"
,"type":"101"
}
}
,{
"assign_tag":
{
"status":"Error"
,"message":"tag does not exist. Nothing done"
,"type":"212"
}
}
,{
"give_points_to_lead":
{
"status":"Error"
,"message":"points is not a number. Nothing done"
,"type":"227"
}
}
]
}
*/

// CONDITIONAL FOR FURTHER INSTRUCTIONS…
if ($server_json->status == "Error") {
echo "Sorry, the following error has occurred: ".$server_json->message.",
type:".$server_json->type;
} elseif ($server_json->status == "Success") {
echo "lead status: ".$server_json->status."<br>";
echo "Status: ".$server_json->actions[0]->subscribe_lead_to_list->status.",

Message: ".$server_json->actions[0]->subscribe_lead_to_list->message.",
Type:".$server_json->actions[0]->subscribe_lead_to_list->type."<br>";
echo "Status: ".$server_json->actions[1]->assign_tag->status.", Message:
".$server_json->actions[1]->assign_tag->message.",
Type:".$server_json->actions[1]->assign_tag->type."<br>";
echo "Status: ".$server_json->actions[2]->give_points_to_lead->status.",
Message: ".$server_json->actions[2]->give_points_to_lead->message.",
Type:".$server_json->actions[2]->give_points_to_lead->type."<br>";
}
?>