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 |
id |
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. |
email |
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. |
ip |
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 |
linkedin |
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
|
|
string The tag name. |
|
string The list name. |
|
integer Possible values are:
- 0 – Lead is not subscribed to list.
- 1 – Lead is subscribed to list.
|
|
string The sequence name. |
|
string The sequence step number |
|
string The status of the lead in the sequence. Possible values are:
|
|
string The membership name. |
|
string The level name. |
|
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.
|
|
integer The transaction unique identifier. |
|
string The product internal name. |
|
string The price point number. |
|
string Possible values are:
- ‘Sale’
- ‘Refund’
- ‘Cancellation’
- ‘Rebill’
- ‘Chargeback’
- ‘Failed’
- ‘Partial_refund’
|
|
float The amount charged for the transaction. |
|
string The date when the transaction was registered in the format: ‘YYYY-MM-DD HH:MM:SS’. |
|
integer The calendar id. |
|
string The calendar name. |
|
integer The calendar class id. |
|
string The calendar class name. |
|
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’
|
|
integer Account id of the calendar owner. |
|
string The vendor timezone. |
|
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"
}
|
|
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"
}
|
|
string The url for the calendar ics file. |
|
integer The survey id. |
|
string The survey name. |
|
integer The survey type. Posible values are:
|
|
string The survey score. |
|
integer The time the lead completed the survey. |
|
string The date when the survey was completed, in EST timezone, with the format: ‘YYYY-MM-DD HH:MM:SS’. |
|
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"
}
]
}
]
}
]
}
}
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"
}