Kartra Documentation TECHNICAL DOCUMENTATION

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:

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

 

* 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

 

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

  1. America/Los_Angeles
  2. America/Boise
  3. America/Chicago
  4. America/New_York
  5. Europe/London
  6. Europe/Brussels
  7. Etc/GMT+12
  8. Pacific/Midway
  9. Pacific/Honolulu
  10. America/Juneau
  11. America/Chihuahua
  12. America/Phoenix
  13. America/Regina
  14. America/Mexico_City
  15. America/Belize
  16. America/Indiana/Indianapolis
  17. America/Bogota
  18. America/Glace_Bay
  19. America/Caracas
  20. America/Santiago
  21. America/St_Johns
  22. America/Sao_Paulo
  23. America/Argentina/Buenos_Aires
  24. America/Nuuk
  25. Etc/GMT+2
  26. Atlantic/Azores
  27. Atlantic/Cape_Verde
  28. Africa/Casablanca
  29. Atlantic/Canary
  30. Europe/Belgrade
  31. Europe/Sarajevo
  32. Europe/Amsterdam
  33. Africa/Algiers
  34. Europe/Bucharest
  35. Africa/Cairo
  36. Europe/Helsinki
  37. Europe/Athens
  38. Asia/Jerusalem
  39. Africa/Harare
  40. Europe/Moscow
  41. Asia/Kuwait
  42. Africa/Nairobi
  43. Asia/Baghdad
  44. Asia/Tehran
  45. Asia/Dubai
  46. Asia/Baku
  47. Asia/Kabul
  48. Asia/Yekaterinburg
  49. Asia/Karachi
  50. Asia/Kolkata
  51. Asia/Kathmandu
  52. Asia/Dhaka
  53. Asia/Colombo
  54. Asia/Almaty
  55. Asia/Rangoon
  56. Asia/Bangkok
  57. Asia/Krasnoyarsk
  58. Asia/Shanghai
  59. Asia/Kuala_Lumpur
  60. Asia/Taipei
  61. Australia/Perth
  62. Asia/Irkutsk
  63. Asia/Seoul
  64. Asia/Tokyo
  65. Asia/Yakutsk
  66. Australia/Darwin
  67. Australia/Adelaide
  68. Australia/Sydney
  69. Australia/Brisbane
  70. Australia/Hobart
  71. Asia/Vladivostok
  72. Pacific/Guam
  73. Asia/Magadan
  74. Pacific/Fiji
  75. Pacific/Auckland
  76. 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"
}

© 2021 Kartra All Rights Reserved