Kartra API: Inbound > Leads. This article is for developers.
You can retrieve the profile info of one specific lead from your contacts database. To do so, we will search the lead’s email with the function get_lead.
| Type | Parameters | Data type |
| POST | get_lead* | string |
* Required: the lead’s email is required to identify the lead.
Example
'get_lead' => [ 'email' => 'JoeSmith@domain.com', ]
Request results
| Parameters | Data type | Values |
| lead_details | string | JSON-encoded object containing the lead details |
| JSON parameters | Data type | Values |
| id | string | Lead's unique identifier id |
| first_name | string | Lead's first name |
| middle_name | string | Lead's middle name |
| last_name | string | Lead's last name |
| string | Lead's email address | |
| date_joined | string | Date the lead was registered, in EST timezone with the format: 'YYYY-MM-DD HH:MM:SS' |
| phone_country_code | string | Lead's phone country code |
| phone | string | Lead's phone |
| ip | string | Lead's IP address |
| address | string | Lead's mailing address |
| zip | string | Lead's zip / postal code |
| city | string | Lead's city |
| state | string | Lead's state |
| country | string | Lead's country |
| lead_picture | string | URL to Lead’s thumbnail image |
| score | integer | Lead score in points |
| source | string | The source of the Lead. Possible values are:
|
| source_id | string | For internal purposes (you can ignore) |
| ip_country | string | The country where the lead ip is located |
| website | string | URL to Lead’s website |
| string | URL to Lead’s Facebook page | |
| string | URL to Lead’s Twitter page | |
| string | URL to Lead’s LinkedIn page | |
| lead_preferred_time_zone | string | Lead's preferred time zone |
| notes | string | Notes in the lead profile |
| blacklisted | integer | Lead's email delivery status. Possible values are:
|
| custom_fields ** | array | Data contained in each custom field, in the following format:{
"field_id": integer,
"field_identifier": string,
"field_type": string,
"field_value": [
{
"option_id": integer,
"option_value": string,
},
{
"option_id": integer,
"option_value": string,
}
]
}field_id: Unique field ID reference field_identifier: Unique text identifier chosen when the field was created field_type: Field type (Possible values: input_field, text_area, drop_down, radio_button, checkbox) field_value: The contents of the field saved for the particular lead. In the case of input_field and text_area this will be text (string). For all other fields, the value will be an array that includes the ID and description of the lead's selection.
When the field type is a checkbox, the values can be multiple. |
| gdpr_lead_status | integer | GDPR status for the lead. Possible values are:
|
| gdpr_lead_status_date | string | The date when the GDPR status was captured, 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 captured. |
gdpr_lead_communications | integer | Status of the lead's communication consent. Possible values are:
|
** All custom fields will be returned, even if they are empty for a specific lead.
Tags and lists. All the lead's assigned tags and list subscriptions are retrieved.
| tag_name | string | Tag name |
| list_name | string | List name |
| active | integer | Lead's list subscription status. Possible values are:
|
Sequences. Details of all the lead's sequence subscriptions are retrieved.
| sequence_name | string | Sequence name |
| step | string | Sequence step number |
| status | string | Status of the lead in the sequence. Possible values are:
|
| name | string | Membership name |
| level_name | string | Membership access level name |
| active | integer | Status of the Lead's access to a membership level. Possible values are:
|
Transactions. Details for all transaction events for the lead are retrieved.
| id | integer | Transaction unique identifier. |
| product_name | string | Purchased product internal name. |
| price_point | string | Price point number. |
| transaction_type | string | Type of transaction event. Possible values are:
|
| transaction_amount | float | Amount charged, attempted, or returned for the transaction. |
| transaction_date | string | Date the transaction was processed in the format: 'YYYY-MM-DD HH:MM:SS'. |
Calendars. Details for all the lead's calendar appointments are retrieved.
| 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:
|
| vendor_id | integer | Account id of the calendar owner. |
| vendor_timezone | string | Vendor timezone. |
| hosts | array | Host details for a calendar appointment, in the following format:{
"host_first_name": "host",
"host_last_name": "host",
"host_email_address": "hostemail@gmail.com"
} |
| events | array | Date (in EST timezone) and duration of a calendar appointment, in the following format:{
"event_date": "YYYY-MM-DD HH:MM",
"event_duration": "MM"
} |
| ics_calendar_link | string | URL of the calendar ICS file |
Surveys. Details for all the lead's completed surveys are retrieved.
| survey_id | integer | Survey identifier |
| survey_name | string | Survey name |
| survey_type | integer | Survey type. Possible values are:
|
| survey_score | string | Survey score |
| survey_completion_time | integer | Time the lead completed the survey |
| survey_completion_date | string | Date each survey was completed, in EST timezone, with the format: ‘YYYY-MM-DD HH:MM:SS’. |
| questions | array | The details of each survey question, in the following format:{
"question_id": integer,
"question_title": string,
"question_correct": integer,
"answers": array,
{
"option_id": integer,
"option_value": string,
}
}question_id: Question ID question_title: Question title question_correct: (0 - Not subject to score, 1 - correct, 2 - incorrect) answers: The lead's answers
|
Success message example
{
"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": "123456789",
"ip": "1.1.1.1",
"address": "test",
"zip": "test",
"city": "test",
"state": "CA",
"country": "US",
"lead_picture": "https:\/\/s3.amaz[...]nal\/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": "Your Product Name",
"product_price_point": "1",
"transaction_type": "Sale",
"transaction_amount": "300.00",
"transaction_date": "2019-03-26 06:35:33"
}
],
"memberships": [
{
"name": "Your Course Name",
"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": "Your First Calendar",
"calendar_id": "123",
"class_name": "Master Class",
"class_id": "22",
"subscription_id": "1885",
"calendar_subscription_status": "Cancelled",
"vendor_id": "321",
"vendor_timezone": "America/New_York",
"hosts": [
{
"host_first_name": "John",
"host_last_name": "Doe",
"host_email_address": "johndoe@sample.com"
},
{
"host_first_name": "Janet",
"host_last_name": "Smith",
"host_email_address":"janetsmith@sample.com"
}
],
"events": [
{
"event_date": "2020-12-09 09:00",
"event_duration": 60
},
{
"event_date": "2020-12-10 09:00",
"event_duration": 40
}
]
},
{
"calendar_name": "Your Second Calendar",
"calendar_id": "33",
"class_name": "Beginner's Class",
"class_id": "11",
"subscription_id": "245",
"calendar_subscription_status": "Active",
"vendor_id": "321",
"vendor_timezone": "America/Detroit",
"hosts":[
{
"host_first_name": "John",
"host_last_name": "Doe",
"host_email_address":"johndoe@sample.com"
},
{
"host_first_name": "Janet",
"host_last_name": "Smith",
"host_email_address":"janetsmith@sample.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": "Your 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": "Your 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"
}
]
}
]
}
]
}
}Errors
| 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. |
Error message example:
{
"status": "Error",
"message": "No lead found",
"type": "234"
}