Leads – Kartra Documentation

Lead: Retrieving data

This will allow you to retrieve the profile info of one specific lead from your contacts database. In order to do so, we will search the lead’s email with the function get_lead.

Type	Parameters	Values
POST	get_lead*	string

* Required: the lead’s email is required to identify the lead.

Here is an example:

'get_lead' => [
   'email' => 'JoeSmith@domain.com',
]

Here are the results returned by the request:

Parameters	Values
lead_details	String (JSON encoded object containing the lead details)

JSON parameters

Values

string The Lead’s unique identifier id.

first_name

string The Lead’s first name.

middle_name

string The Lead’s middle name.

last_name

string The Lead’s last name.

string The Lead’s email.

date_joined

string The date when the lead was registered, in EST timezone with the format: ‘YYYY-MM-DD HH:MM:SS’

phone_country_code

string The Lead’s phone country code.

phone

string The Lead’s phone.

string The Lead’s ip.

address

string The Lead’s address.

zip

string The Lead’s zip.

city

string The Lead’s city.

state

string The Lead’s state.

country

string The Lead’s country.

lead_picture

string URL to Lead’s thumbnail image.

score

integer Lead score in points.

source

string The source where the Lead came from, possible values are:

‘single-optin’ – if the Lead was created by filling a single optin form.
‘double-optin’ – if the Lead was created by filling a double confirm optin form.
‘helpdesk’ – if the Lead was created by submitting a helpdesk ticket or starting a live chat.
‘affiliate-signup’ – if the Lead was created when by signing up as an affiliate to promote any of your products.
‘checkout’ – if the Lead was created upon ordering any of your product.
‘import’ – if the Lead was created via the import system.
‘api’ – if the Lead was created through the API.
‘manual’ – if the Lead was created manually from within your Kartra account interface.

source_id

string only for internal purposes (you can ignore)

ip_country

string The country where the lead ip is located.

website

string URL to Lead’s website

facebook

string URL to Lead’s facebook page

twitter

string URL to Lead’s twitter page

string URL to Lead’s linkedin page

lead_preferred_time_zone

string The lead’s preferred time zone

notes

string The Lead notes.

blacklisted

integer If the Lead is blacklisted, possible values are:

0 – Lead is not blacklisted
1 – Lead is blacklisted

custom_fields **

array of objects containing the values that the Lead has on each custom field, with the following structure:

{
    "field_id":integer, // the unique id reference
    "field_identifier":string, // the unique identifier chosen when it was created
    "field_type":string, // the field type (values: input_field, text_area, drop_down,
 radio_button, checkbox)
    // the value saved for the particular lead. In the case of input_field and text_area
 this will be string, if not it will be an array with the below structure
    // in the case of checkboxes the values can be multiple
    "field_value":[
        {
            "option_id":integer, // the unique id reference
            "option_value":string, // option value
        },
        {
            "option_id":integer,
            "option_value":string,
        }
    ]
  }

gdpr_lead_status

integer The GDPR status for the Lead, possible values are:

0 – For GDPR status off – Your account has GDPR deactivated
1 – For GDPR status not subject – The lead’s IP is from a country not subject to GDPR
2 – For GDPR status accepted – The lead has accepted the GDPR terms
3 – For GDPR status not accepted – The lead hasn’t accepted the GDPR terms
4 – For GDPR status unknown – The lead’s location could not be determined
5 – For GDPR status pending

gdpr_lead_status_date

string The date when the GDPR status was registered, in EST timezone, with the format: ‘YYYY-MM-DD HH:MM:SS’.

gdpr_lead_status_ip

string The IP where the Lead GDPR status was registered.

gdpr_lead_communications

integer The status of the communication approval, possible values are:

0 – Lead hasn’t agreed to be contacted
1 – Lead has agreed to be contacted

tags

tag_name

string The tag name.

lists

list_name

string The list name.

active

integer Possible values are:

0 – Lead is not subscribed to list.
1 – Lead is subscribed to list.

sequences

sequence_name

string The sequence name.

step

string The sequence step number

status

string The status of the lead in the sequence. Possible values are:

‘active’
‘unsubscribed’

memberships

name

string The membership name.

level_name

string The level name.

active

integer The status for the Lead subscription to the membership level. Possible values are:

0 – Lead is not subscribed to membership level.
1 – Lead is subscribed to membership level.

transactions

integer The transaction unique identifier.

product_name

string The product internal name.

price_point

string The price point number.

transaction_type

string Possible values are:

‘Sale’
‘Refund’
‘Cancellation’
‘Rebill’
‘Chargeback’
‘Failed’
‘Partial_refund’

transaction_amount

float The amount charged for the transaction.

transaction_date

string The date when the transaction was registered in the format: ‘YYYY-MM-DD HH:MM:SS’.

calendars

calendar_id

integer The calendar id.

calendar_name

string The calendar name.

class_id

integer The calendar class id.

class_name

string The calendar class name.

subscription_id

integer The id of the Lead subscription to the calendar.

calendar_subscription_status

string The status of the Lead subscription to class. Possible values are :

‘Active’
‘Pending’
‘Completed’
‘Declined’
‘Cancelled’

vendor_id

integer Account id of the calendar owner.

vendor_timezone

string The vendor timezone.

hosts

array of objects containing each host details, with the following structure:

{
    "host_first_name":"host",
    "host_last_name":"host",
    "host_email_address":"hostemail@gmail.com"
}

events

array of objects containing the date(in EST timezone) and duration, with the following structure:

{
    "event_date":"YYYY-MM-DD HH:MM",
    "event_duration":"MM"
}

ics_calendar_link

string The url for the calendar ics file.

surveys

survey_id

integer The survey id.

survey_name

string The survey name.

survey_type

integer The survey type. Posible values are:

‘1 – Survey’
‘2 – Quiz’

survey_score

string The survey score.

survey_completion_time

integer The time the lead completed the survey.

survey_completion_date

string The date when the survey was completed, in EST timezone, with the format: ‘YYYY-MM-DD HH:MM:SS’.

questions

array of objects containing each question details, with the following structure:

{
    "question_id":integer The question ID,
    "question_title":string The question title,
    "question_correct":integer (0 - Not subject to score, 1 - correct, 2 - incorrect),
    "answers":array The lead answers to this question, with the following structure:
    {
        "option_id":integer The option ID,
        "option_value":string The option value (lead response),
    }
}

** All custom fields recorded for that particular lead will be returned, even if they are empty.

Here’s an example of success message when retrieving a lead’s data:

{
    "status":"Success",
    "lead_details":{
        "id":"1234",
        "first_name":"test",
        "middle_name":"test",
        "last_name":"test",
        "last_name2":"test",
        "company":"test",
        "sales_tax_id":"test",
        "email":"test@test.co",
        "username":"test123",
        "date_joined":"2019-03-26 06:35:31",
        "phone_country_code":"+40",
        "phone":"123456",
        "ip":"1.1.1.1",
        "address":"test",
        "zip":"test",
        "city":"test",
        "state":"CA",
        "country":"US",
        "lead_picture":"https:\/\/s3.amazonaws.com\/kartra\/internal\/default_user.png",
        "score":"0",
        "source":"checkout",
        "source_id":"1234",
        "ip_country":"United States",
        "website":"https:\/\/google.com",
        "facebook":"test",
        "twitter":"test",
        "linkedin":"test",
        "lead_preferred_time_zone":"America/New_York",
        "referring_id":"1234",
        "blacklisted":"0",
        "gdpr_lead_status":"2",
        "gdpr_lead_status_date":"2019-03-26 06:35:31",
        "gdpr_lead_communications":"1",
        "gdpr_lead_status_ip":"1.1.1.1",
        "tags":[
            {
                "tag_name":"test"
            }
        ],
        "lists":[
            {
                "list_name":"test",
                "active":"1"
            }
        ],
        "sequences":[
            {
                "tree_name":"test",
                "step":"2",
                "status":"active"
            }
        ],
        "transactions":[
            {
                "transaction_id":"1234",
                "product_name":"test product",
                "product_price_point":"1",
                "transaction_type":"Sale",
                "transaction_amount":"300.00",
                "transaction_date":"2019-03-26 06:35:33"
            }
        ],
        "memberships":[
            {
                "name":"test",
                "level_name":"standard",
                "active":"1"
            }
        ],
	"custom_fields":[
	    {
		"field_id":"323",
		"field_identifier":"color",
		"field_type":"checkbox",
		"field_value":[
	           {
			"option_id":"1",
			"option_value":"red",
		   },
		   {
			"option_id":"2",
			"option_value":"blue",
		   }
		]
	    },
	    {
		"field_id":"324",
		"field_identifier":"gender",
		"field_type":"drop_down",
		"field_value":[
	            {
			"option_id":"1",
			"option_value":"male",
		    }
		]
	   },
	   {
		"field_id":"325",
		"field_identifier":"favorite_dish",
		"field_type":"input_field",
		"field_value":"beef lasagna",
	   }
	],
        "calendars":[
           {
                "calendar_name":"first calendar",
                "calendar_id":"123",
                "class_name":"first class",
                "class_id":"22",
                "subscription_id":"1885",
                "calendar_subscription_status":"Cancelled",
                "vendor_id":"321",
                "vendor_timezone":"America/New_York",
                "hosts":[
                    {
                         "host_first_name":"host",
                         "host_last_name":"host",
                         "host_email_address":"hostemail@gmail.com"
                    },
                    {
                         "host_first_name":"co-host",
                         "host_last_name":"co-host",
                         "host_email_address":"cohostemail@gmail.com"
                    }
                ],
                "events":[
                    {
                        "event_date":"2020-12-09 09:00",
                        "event_duration":60
                    },
                    {
                        "event_date":"2020-12-10 09:00",
                        "event_duration":40
                    }
                ]
           },
           {
                "calendar_name":"second calendar",
                "calendar_id":"33",
                "class_name":"second class",
                "class_id":"11",
                "subscription_id":"245",
                "calendar_subscription_status":"Active",
                "vendor_id":"321",
                "vendor_timezone":"America/Detroit",
                "hosts":[
                    {
                         "host_first_name":"host",
                         "host_last_name":"host",
                         "host_email_address":"hostemail@gmail.com"
                    },
                    {
                         "host_first_name":"co-host",
                         "host_last_name":"co-host",
                         "host_email_address":"cohostemail@gmail.com"
                    }
                ],
                "events":[
                    {
                        "event_date":"2020-12-14 09:00",
                        "event_duration":60
                    },
                    {
                        "event_date":"2020-12-19 09:00",
                        "event_duration":40
                    }
                ],
                "ics_calendar_link":"https://app.kartra.com/calendar/ics/"
           }
        ],
        "surveys":[
            {
                "survey_id":"123",
                "survey_name":"My Survey",
                "survey_type":"1",
                "survey_score":"N/A",
                "survey_completion_time":"65",
                "survey_completion_date":"2021-07-01 06:35:33",
                "questions":[
                    {
                         "question_id":"146",
                         "question_title":"Age",
                         "question_correct":"0",
                         "answers":[
                             {
                                 "option_id":"105",
                                 "option_value":"Between 18 and 30"
                             }
                         ]
                    },
                    {
                         "question_id":"147",
                         "question_title":"What pets do you like",
                         "question_correct":"0",
                         "answers":[
                             {
                                 "option_id":"109",
                                 "option_value":"Cats"
                             },
                             {
                                 "option_id":"110",
                                 "option_value":"Dogs"
                             }
                         ]
                    }
                ]
            },
            {
                "survey_id":"127",
                "survey_name":"My Quiz",
                "survey_type":"2",
                "survey_score":"50",
                "survey_completion_time":"75",
                "survey_completion_date":"2021-07-02 06:35:33",
                "questions":[
                    {
                         "question_id":"150",
                         "question_title":"5+5",
                         "question_correct":"1",
                         "answers":[
                             {
                                 "option_id":"125",
                                 "option_value":"10"
                             }
                         ]
                    },
                    {
                         "question_id":"151",
                         "question_title":"Question",
                         "question_correct":"2",
                         "answers":[
                             {
                                 "option_id":"131",
                                 "option_value":"Cats"
                             },
                             {
                                 "option_id":"132",
                                 "option_value":"Dogs"
                             }
                         ]
                    }
                ]
            }
        ]
    }
}

Error Cases:

Type Number	Message	Cause
234	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": "No lead found",
  "type": "234"
}

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:

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

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

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

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