API Inbound: Lead: Searching, Creating, Editing

Notes about Kartra's API

Our API is primarily designed for managing leads in your contacts database. Each API call must focus on one specific lead—you can perform multiple actions on that lead within a single call, but you cannot target multiple leads in one request. To add or edit multiple leads, you'll need to send an individual API call for each.

When passing a lead’s data in your API call, the system first searches your contacts database to find that lead. You must include either the ID or EMAIL of the lead in your API call parameters. If both are provided, the system will prioritize the ID. Since no two leads share the same ID or Email, a lead is identified by either field.

Flow for editing or creating a lead:

When you send an API call, the system will search for a matching lead based on the ID or EMAIL.
If a match is found, the system will perform the requested action on that existing lead.
If no match is found, you’ll receive a "Lead Not Found" error. In that case, you must first execute a "Create Lead" API call, followed by another call to perform your action on the new lead.

For efficiency, you can also chain multiple actions in a single API call—for example, CREATE + desired action. Check out 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	lead_preferred_time_zone*****	string (All options stated below)
POST	custom_fields ***	array
POST	sales_tax_id	string
POST	business_type	number

* 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.

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"
        }
      }
    }
  ]
}

Error Cases:

Type Number	Message	Cause
244	Lead already exists	A lead with the same email already exists in our database.
271	Wrong custom field format	'custom_fields' does not have the correct format in the request.

An example of an error message:

{
  "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:

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	lead_preferred_time_zone*****	string (All options stated below)
POST	custom_fields ***	array
POST	new_email ****	string
POST	sales_tax_id	string
POST	business_type	number

* 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_emailfield.

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"
        }
      }
    }
  ]
}

Error Cases:

Type Number	Message	Cause
243	No lead found	The lead was not found in our database.
244	Lead already exists	A lead with the same email as the 'new_email' parameter already exists in our database.
271	Wrong custom field format	'custom_fields' does not have the correct format in the request.
245	Lead is deleted	The lead has been deleted.

An example of an error message:

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

***** Timezone options:

America/Los_Angeles
America/Boise
America/Chicago
America/New_York
Europe/London
Europe/Brussels
Etc/GMT+12
Pacific/Midway
Pacific/Honolulu
America/Juneau
America/Chihuahua
America/Phoenix
America/Regina
America/Mexico_City
America/Belize
America/Indiana/Indianapolis
America/Bogota
America/Glace_Bay
America/Caracas
America/Santiago
America/St_Johns
America/Sao_Paulo
America/Argentina/Buenos_Aires
America/Nuuk
Etc/GMT+2
Atlantic/Azores
Atlantic/Cape_Verde
Africa/Casablanca
Atlantic/Canary
Europe/Belgrade
Europe/Sarajevo
Europe/Amsterdam
Africa/Algiers
Europe/Bucharest
Africa/Cairo
Europe/Helsinki
Europe/Athens
Asia/Jerusalem
Africa/Harare
Europe/Moscow
Asia/Kuwait
Africa/Nairobi
Asia/Baghdad
Asia/Tehran
Asia/Dubai
Asia/Baku
Asia/Kabul
Asia/Yekaterinburg
Asia/Karachi
Asia/Kolkata
Asia/Kathmandu
Asia/Dhaka
Asia/Colombo
Asia/Almaty
Asia/Rangoon
Asia/Bangkok
Asia/Krasnoyarsk
Asia/Shanghai
Asia/Kuala_Lumpur
Asia/Taipei
Australia/Perth
Asia/Irkutsk
Asia/Seoul
Asia/Tokyo
Asia/Yakutsk
Australia/Darwin
Australia/Adelaide
Australia/Sydney
Australia/Brisbane
Australia/Hobart
Asia/Vladivostok
Pacific/Guam
Asia/Magadan
Pacific/Fiji
Pacific/Auckland
Pacific/Tongatapu

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

Success message:

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

Error Cases:

Type Number	Message	Cause
243	No lead found	The lead was not found in our database.
245	Lead is deleted	The lead has been deleted.

An example of an error message:

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