Kartra Documentation TECHNICAL DOCUMENTATION

Section 3: Lead: Searching, Creating, Editing

Some basic notes about Kartra’s API

1. Our API is mostly focus on managing the leads in your contacts database. Therefore, the first step in the API call is to identify which particular lead the API call is aimed for. Every API call must be based around one (and only one) specific lead. That basically means that you can execute multiple actions upon one particular lead within the same API call, but you cannot execute an action upon multiple leads. If you’re looking to add/edit multiple leads, you will need to send an individual API call for each of them.

2. When you pass a lead’s data within your API call, the API system will firstly query your contacts database to locate that particular lead. In the API call parameters, you need to pass the ID or the EMAIL of the lead. If both the ID and the EMAIL are present the search, the system will prioritize the ID. In short: a lead is identified either by their ID or EMAIL address, since no two leads can share the same ID or the same Email.

3. Here’s the overall flow to Edit or Create a lead:

  1. First, when you send an API call, the API will query your Kartra contacts database searching for an existing match based on ID or EMAIL. If a lead is found, the system will execute your desired action for that existing lead.
  2. On the other hand, if no lead is found for the specified ID or EMAIL, the system will ping back a “Lead Not Found” error. In this case, you will need to firstly use a Create Lead API call, followed by another API call with the desired action to be executed for that new lead. Alternatively, if you want to make your calls more efficient, you could also chain two (or more) commands within the same API call: in this case, the CREATE + desired action. See our sample code for more details.

 


Creating the lead

The following parameters are required to create the lead:

Type Parameters Values
POST cmd* create_lead
POST email** string
POST phone string
POST phone_country_code string
POST first_name string
POST middle_name string
POST last_name string
POST last_name2 string
POST ip string
POST address string
POST zip string
POST city string
POST state string
POST country string
POST company string
POST lead_picture string (URL to lead’s thumbnail image)
POST website string
POST facebook string
POST twitter string
POST linkedin string
POST google_plus string
POST custom_fields *** array

 

* Required: the CMD parameter must be included in the API call.
** Required: the lead’s EMAIL is required to identify the lead.
*** The custom field identifier must have previously been created in your Kartra account. Otherwise, if the API call doesn’t find the corresponding custom field name, the instruction will be ignored.
The array will consist of arrays with two parameters:

  • field_identifier (string) – the unique identifier chosen when it was created
  • field_value (array/string/integer) – the values will be strings for input_field and text_area, integers with the option id for drop_down and radio_button, array containing the option ids for checkboxes. To clear the values, you need to send an empty string.

This API call will return an error if a lead with the email address sent thru the API call already exits. Otherwise, it will return a success message containing the newly created lead’s ID. As stated above, you can use this Lead ID for future API calls, or you can simply continue using the Lead EMAIL. Both identification methods are accepted.

 

Here is an example of sending parameters:

'lead' => [
    'email' => 'John@kartra.com',
    'first_name' => 'John',
    '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]
        ],
    ],
], 
'actions' => [ 
    '0' => [ 
        'cmd' => 'create_lead' 
    ] 
]

 

Example of error message:

{
  "status": "Error",
  "message": "Lead already exists",
  "type": "244"
}

 

Example of success message:

{
  "status": "Success",
  "actions": [
    {
      "create_lead": {
        "status": "Success",
        "lead_details": {
          "id": "1234"
        }
      }
    }
  ]
}

 

IMPORTANT: If you’re submitting a Lead Create, Lead Edit or Lead Search instruction in your API calls, and since you can chain multiple CMD instructions within the “actions” array, remember that the very first CMD in the array (key “0”) must be the actual Create, Edit or Search instruction itself. After that, you’re free to include as many other CMDs as you wish. Otherwise, the system would not know what lead in particular to execute the secondary instructions for.

See example below:

'actions' => array(
'0' => array( 'cmd' => 'create_lead', ),
'1' => array( 'cmd' => 'assign_tag', ),
'2' => array( 'cmd' => 'subscribe_lead_to_list', )
)

 


Editing a lead

In order to edit a lead, the following API call needs to be made:

Type Parameters Values
POST cmd* edit_lead
POST id** number
POST email** string
POST phone string
POST phone_country_code string
POST first_name string
POST middle_name string
POST last_name string
POST last_name2 string
POST ip string
POST address string
POST zip string
POST city string
POST state string
POST country string
POST company string
POST lead_picture string (URL to lead’s thumbnail image)
POST website string
POST facebook string
POST twitter string
POST linkedin string
POST google_plus string
POST custom_fields *** array
POST new_email **** string

 

* Required: the CMD parameter must be included in the API call.
** Either the ID or the EMAIL are required in order for a lead to be correctly identified and updated.
*** The custom field identifier must have previously been created in your Kartra account. Otherwise, if the API call doesn’t find the corresponding custom field name, the instruction will be ignored.
The array will consist of arrays with two parameters:

  • field_identifier (string) – the unique identifier chosen when it was created
  • field_value (array/string/integer) – the values will be strings for input_field and text_area, integers with the option id for drop_down and radio_button, array containing the option ids for checkboxes. To clear the values, you need to send an empty string.

**** If you wish to edit the current email for a lead, the new email address must be passed in the new_email field.

 

The system will firstly conduct a search for an existing lead with the provided ID or EMAIL. If the lead is found, it will be updated according to the data being passed in the API call. Conversely, if no lead is found, the system will throw an error (see below).

If the call contains the parameter new_email, this will be validated against your current database to make sure no other existing lead is already registered under that email address. If a lead is found an error message will be thrown.

Here is an example of sending parameters:

'lead' => [
    'email' => 'john@kartra.com',
    'first_name' => 'John',
    'last_name' => 'Smith',
    'new_email' => 'john@email.com',
    'custom_fields' => [
        '0' => [
            'field_identifier' => 'text1',
            'field_value' => 'text message'
        ],
        '1' => [
            'field_identifier' => 'dropdown1',
            'field_value' => '612'
        ],
        '2' => [
            'field_identifier' => 'checkbox1',
            'field_value' => [620]
        ],
    ],
],
'actions' => [
    '0' => [
        'cmd' => 'edit_lead'
    ]
]

 

Example of error message when no lead is found:

{
  "status": "Error",
  "message": "No lead found",
  "type": 234
}

 

Example of error message when new_email parameter is passed and the email is already used by another lead:

{
  "status": "Error",
  "message": "Lead already exists",
  "type": 244
}

 

Example of success message:

{
  "status": "Success",
  "actions": [
    {
      "edit_lead": {
        "status": "Success",
        "lead_details": {
          "id": "1234"
        }
      }
    }
  ]
}

 


Searching for a lead

In order to search for a lead in your contacts database, the following API call needs to be done:

Type Parameters Values
POST cmd* search_lead
POST id** number
POST email** string

 

* Required: the CMD parameter must be included in the API call.
** Either the ID or the EMAIL must be passed in order to locate the lead

 

Here is an example:

'lead' => [
    'email' => 'test@kartra.com'
],
    'actions' => [
        '0' => [
            'cmd' => 'search_lead'
        ]
]

 

Example of error message when no lead is found:

{
  "status": "Error",
  "message": "No lead found",
  "type": 234
}

 

Example of success message:

{
  "status":"Success",
  "message":"Lead found",
  "lead_details":
    {
      "id":"39260"
    }
}

© 2020 Kartra All Rights Reserved