Lead: Searching, Creating, Editing

Notes about Kartra's API

1. Our API is mostly focused 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:

* 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' 
    ] 
]

Success message:

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

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

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:

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'
    ]
]

Success message:

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

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

Searching for a lead

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

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

Success message:

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

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