Kartra Documentation Technical Documentation for Kartra

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
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
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 id
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"
}
Was this article helpful?
YesNo

© 2024 Kartra All Rights Reserved