Kartra Documentation TECHNICAL DOCUMENTATION

API Integration

Here you will find the information needed to connect and interact with Kartra via our secure API.

Before we start, there are some house cleaning notes to consider:

1. Please note that APIs are for advanced users with programming skills only. In fact, the API system relies on your platform as much as it does on ours, so the depth of help our Support Team will be able to provide is very limited.

2. As you know, via the API you can automatically subscribe users to your Kartra account without their manual input. Well, due to the GDPR and user data privacy best practices, it’s your responsibility to make sure that those users have granted you permission to handle their personal data, they have agreed to be registered to your contacts list, and they have granted you permission to communicate with them in the future. If you do not have their actual consent, please do not use the API to register leads into your Kartra account.

3. You will need to maintain your own Kartra account as a app developer to ensure your application remains approved and valid.  Your customers should never be submitting your app for you on their Kartra account, doing so will lead to a declined app and a confused mutual customer.

Table of contents

1. Activating the App
2. Connecting to the API
3. Lead: Editing, Searching or Creating a lead
4. Lead: Retrieving data
5. Action: Subscribe a lead to a list
6. Action: Unsubscribe a lead to a list
7. Action: Assign Tag to A Lead
8. Action: Unassign tag from a lead
9. Action: Give points to lead
10. Action: Remove points from a lead
11. Action: Subscribe lead to a sequence
12. Action: Unsubscribe lead from a sequence
13. Action: Refund a Kartra transaction
14. Action: Cancel a Kartra subscription
15. Action: Subscribe a lead to a katra calendar
16. Action: Cancel subscription to a katra calendar
17. Action: Create custom fields
18. Action: Search Transaction
19. Action: Search Subscription
20. Action: Get Subscriptions From Lead
21. Action: Get Transactions From Lead
22. Action: Retrieve all the tags in your account
23. Action: Retrieve all the lists in your account
24. Action: Retrieve all the sequences in your account
25. Action: Retrieve all the pages in your account
26. Action: Retrieve all the custom fields in your account
27. Success and error confirmation messages
28. PHP sample: execute actions to a specific lead
29. PHP sample: retrieving data for a specific lead
30. PHP sample: creating a lead
31. PHP sample: editing a lead
32. PHP sample: searching for a specific lead
33. API limits

Section 1: Activating your App

Before Kartra can accept any inbound API call, you (the developer) must create a Kartra App and submit it for review. To get started, navigate to My Integrations > Developers > API (located at https://app.kartra.com/integrations/api/developers).

 

Test vs Live Mode

Immediately upon creation, your App will be automatically activated on Test Mode. While on Test Mode, the App is 100% operational and can indeed execute all commands from our API system. There are only two limitations while in Test Mode:

  • Kartra will not send out any email to any lead registered while on Test Mode.
  • Any lead registered while on test mode will have its domain name replaced by @kartra.com. For example, executing the Lead_Create API instruction for lead johnsmith@gmail.com will subscribe that user to your Kartra account under email johnsmith@kartra.com instead.

In order to activate the mailing system, you will need to submit your App for live activation. Our admins will manually review your application and respond within a matter of days.

 

The App ID and API keys

Every App comes with a unique App ID, which you must include in every API call you send to Kartra. Therefore, and for security reasons, Kartra will not accept any API call that doesn’t include a valid App ID.

11

Remember that there are two roles in this process:

  1. The App developer:​ most likely you, the creator of the 3rd party software looking to create an integration with Kartra. Yours will be the App ID.
  2. The App user:​ most likely your customers, but it could also be yourself in case you’re using your own App. Either way, the App user must also have an active Kartra account, since the API will be expecting the user’s API Key and API Password.

The actions commanded by the API call (ie: subscribe a lead to a list) will be executed in the App user’s Kartra account, not in the App developer’s Kartra account.

Look at it this way: the App is just the conductor that executes an action on behalf of the App User.

Section 2: Connecting to the API

You must connect to the Kartra API by sending a POST request to our secure API url at: https://app.kartra.com/api . Note that you must connect using http​s​ (not http) as our API requires SSL encryption for a request to be accepted.

Additionally, every API call must include an array with the following parameters:

  1. User’s API Key: api_key
  2. User’s API Password: api_password
  3. Developer’s APP ID: app_id

Both you (the App developer) and your App’s end users will find your respective API Key and API Password by navigating to My Integrations > API > Your API key (https://app.kartra.com/integrations/api/key). However, only you (the App developer) will know the App ID since you will need to hard code it into your App’s API calls to Kartra. Furthermore, each of your App’s end users will need to insert their respective Kartra API Key and API Password, so you might also need to prepare some type of interface for them type them in. Needless to say, that means that all your end users must own an active Kartra account in order to have a valid API Key and API Password.

12

Finally, you need to be aware of Kartra API’s hardcoded limits. Make sure to account for those limits in your code.

Section 3: 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 google_plus string
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' 
    ] 
]

 

Example of error message:

{
  "status": "Error",
  "message": "Lead already exists",
  "type": "244"
}

 

Example of success message:

{
  "status": "Success",
  "actions": [
    {
      "create_lead": {
        "status": "Success",
        "lead_details": {
          "id": "1234"
        }
      }
    }
  ]
}

 

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 google_plus string
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'
    ]
]

 

Example of error message when no lead is found:

{
  "status": "Error",
  "message": "No lead found",
  "type": 234
}

 

Example of error message when new_email parameter is passed and the email is already used by another lead:

{
  "status": "Error",
  "message": "Lead already exists",
  "type": 244
}

 

Example of success message:

{
  "status": "Success",
  "actions": [
    {
      "edit_lead": {
        "status": "Success",
        "lead_details": {
          "id": "1234"
        }
      }
    }
  ]
}

 


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** number
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'
        ]
]

 

Example of error message when no lead is found:

{
  "status": "Error",
  "message": "No lead found",
  "type": 234
}

 

Example of success message:

{
  "status":"Success",
  "message":"Lead found",
  "lead_details":
    {
      "id":"39260"
    }
}

Section 4: 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 Array, email is a 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 get_lead:

Parameters Values
id string
first_name string
middle_name string
last_name string
email string
date_joined string (YYYY-MM-DD HH:MM:SS)
phone_country_code string
phone string
ip string
address string
zip string
city string
state string
country string
lead_picture string (URL to lead’s thumbnail image)
score integer (lead score in points)
source string, 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 United States
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)
google_plus string (URL to lead’s google+ page)
notes string
blacklisted integer, possible values

  • 0 – Lead is not blacklisted
  • 1 – Lead is blacklisted
lead_deleted integer, possible values

  • 0 – Lead is not deleted
  • 1 – Lead is deleted
lead_deleted_date string (YYYY-MM-DD HH:MM:SS)
custom_fields * array of objects 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, possible values:

  • 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 (YYYY-MM-DD HH:MM:SS)
gdpr_lead_status_ip string
gdpr_lead_communications
integer, possible values:

  • 0 – Lead hasn’t agreed to be contacted
  • 1 – Lead has agreed to be contacted
tags tag_name
string
lists list_name
string
active
integer (0 or 1)
sequences sequence_name
string
step
string
status
string (“active” or “unsubscribed”)
memberships name
string
level_name
string
active
integer (0 or 1)
transactions id
string
product_name
string
price_point
string
transaction_type
string (“Sale”, “Refund”, “Cancelation”, “Rebill” or “Chargeback”)
transaction_amount
string
transaction_date
string (YYYY-MM-DD HH:MM:SS)

 

* 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",
        "google_plus":"test",
        "referring_id":"1234",
        "blacklisted":"0",
        "lead_deleted":"0",
        "lead_deleted_date":"0000-00-00 00:00:00",
        "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",
	   }
	]
    }

}

Section 5: Action: Subscribe a lead to a list

This will allow you to subscribe a lead to any specific mailing list. Note that you must have previously created your list within your Kartra account (https://app.kartra.com/communication/lists).

The API call will fail if it doesn’t find the specified list within your Kartra account.

 

Type Parameters Values
POST cmd* subscribe_lead_to_list
POST list_name* string

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'subscribe_lead_to_list',
        'list_name' => 'List name'
    ]
]

Section 6: Action: Unsubscribe a lead to a list

This will allow you to unsubscribe a lead from any specific mailing list. Note that you must have previously created your list within your Kartra account (https://app.kartra.com/communication/lists).

The API will fail if it doesn’t find the list within your Kartra account. Moreover, if the lead had not been previously subscribed to that list, the API will take no action.

 

Type Parameters Values
POST cmd* unsubscribe_lead_from_list
POST list_name* string

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'unsubscribe_lead_from_list',
        'list_name' => 'List name'
    ]
]

Section 7: Action: Assign tag to a lead

Assigns a tag to a specified lead. Note that you must have previously created the tag in your Kartra account (https://app.kartra.com/communication/tags).

 

Type Parameters Values
POST cmd* assign_tag
POST tag_name* string

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'assign_tag',
        'tag_name' => 'tag name'
    ]
]

Section 8: Action: Unassign tag from a lead

Deletes a tag from the specified lead. Note that…

  1. The tag must have been already created from within your Kartra account (https://app.kartra.com/communication/tags).
  2. The lead must have been previously tagged with that tag. Otherwise, the command will be ignored.

 

Type Parameters Values
POST cmd* unassign_tag
POST tag_name* string

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'unassign_tag',
        'tag_name' => 'tag name'
    ]
]

Section 9: Action: Give points to lead

You can add points to a lead’s profile, along with the expiration deadline in days. Once the expiration is reached, these exact points will be automatically deducted again.

Note that the lead must have been previously added to your account.

Parameters Values
cmd* give_points_to_lead
points* integer
expiration integer (default is 0 – no expire)

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'give_points_to_lead',
        'points' => 1
    ]
]

 

Section 10: Action: Remove points from lead

The API system will search in your account for the lead subscribed under that specific email, and it will deduct the specified points from his or her profile.

 

Type Parameters Values
POST cmd* remove_points_from_lead
POST points* integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'remove_points_from_lead',
        'points' => 1
    ]
]

Section 11: Action: Subscribe lead to a sequence

Subscribes a lead to a specified sequence, at a particular step within the sequence. That step is defined by the step’s box number.

Note that the sequence and the step number must be already created in your account (https://app.kartra.com/communication/sequences).

 

Type Parameters Values
POST cmd* subscribe_lead_to_sequence_at_step
POST sequence_name* string
POST step* string

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'subscribe_lead_to_sequence_at_step',
        'sequence_name' => 'Sequence name',
        'step' => '1'
    ]
]

Section 12: Action: Unsubscribe lead from a sequence

Unsubscribes lead to a specified sequence. Note that…

  1. The sequence must be already created in your account (https://app.kartra.com/communication/sequences).
  2. The lead must have been previously subscribed to that sequence. Otherwise, the command will be ignored.

 

Type Parameters Values
POST cmd* unsubscribe_lead_from_sequence
POST sequence_name* string

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'unsubscribe_lead_from_sequence',
        'sequence_name' => 'Sequence name'
    ]
]

Section 13: Action: Refund a Transaction

This will allow you to refund a transaction inside Kartra, within the refund period.

Type Parameters Values
POST cmd* refund_transaction
POST transaction_id* integer
POST refund_amount float

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'refund_transaction',
        'transaction_id' => 1,
        'refund_amount' => 2
    ]
]

Section 14: Action: Cancel subscription

This will allow you to cancel a subscription inside Kartra. You can pass either the Kartra Transaction ID or the Kartra Subscription ID.

Type Parameters Values
POST cmd* cancel_transaction
POST transaction_id** integer
POST transaction_subscription_id** string

* Required: the CMD parameter must be included in the API call.
** Either the transaction_id or the transaction_subscription_id are required in order for a subscription to be correctly identified and canceled.

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'cancel_transaction',
        'transaction_id' => 1
    ]
]

Section 15: Action: Subscribe lead to calendar

The API system will search in your account for the lead subscribed under that specific email, and it will subscribe the lead to the calendar.

 

Type Parameters Values
POST cmd* calendar_subscribe
POST calendar_name* string
POST class_name* string
POST starting_date string (DD Mmm YYYY)
POST starting_hour string (HH:MM)

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'calendar_subscribe',
        'calendar_name' => 'First calendar',
        'class_name' => 'First class',
        'starting_date' => '16 Jan 2019',
        'starting_hour' => '15:00',
    ]
]

Section 16: Action: Cancel subscription to calendar

The API system will search in your account for the lead subscribed under that specific email, and it will cancel the subscription from the calendar.

 

Type Parameters Values
POST cmd* calendar_cancel
POST calendar_name* string
POST class_name* string

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'calendar_cancel',
        'calendar_name' => 'First calendar',
        'class_name' => 'First class'
    ]
]

Section 17: Action: Create custom fields

The API system will create a custom field for the lead details.

Note: the custom field created here through the API will be of the input field type, and therefore it can only register one single value. Multi-choice fields like dropdowns, radio buttons or check boxes cannot be created through the API, only through the web interface.

Type Parameters Values
POST cmd* create_custom_field
POST custom_field_identifier * string
POST custom_field_type* string with values: input_field, text_area, drop_down, radio_button, checkbox
POST custom_field_options ** array ***

* Required fields
** Required for drop_down, radio_button, checkbox
*** The array will consist of arrays with one parameter: option_name (string containing the name of the option)

 

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'create_custom_field',
        'custom_field_identifier' => 'Custom field name',
        'custom_field_type' => 'drop_down',
        'custom_field_options' => [
            '0' => ['option_name' => 'blue'],
            '1' => ['option_name' => 'brown']
        ]
    ]
]

Section 18: Action: Search Transaction

This will allow you to search for a transaction inside Kartra, to see if the transaction exists, or not.

Type Parameters Values
POST cmd* search_transaction
POST transaction_id* integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'search_transaction',
        'transaction_id' => 1
    ]
]

Section 19: Action: Search Subscription

This will allow you to search for a subscription inside Kartra, to see if the subscription exists, or not.

Type Parameters Values
POST cmd* search_subscription
POST transaction_subscription_id* integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'search_subscription',
        'transaction_subscription_id' => 1
    ]
]

Section 20: Action: Get Subscriptions From Lead

This will allow you to get all the Subscriptions that the lead has done in Kartra.

POSTid **number

Type Parameters Values
POST cmd* get_subscriptions_from_lead
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' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'get_subscriptions_from_lead'
    ],
]

Section 21: Action: Get Transactions From Lead

This will allow you to get all the transactions that the lead has done in Kartra.

POSTid **number

Type Parameters Values
POST cmd* get_transactions_from_lead
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' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'get_transactions_from_lead'
    ],
]

Section 22: Action: Retrieve all the tags in your account

Type Parameters Values
POST cmd* retrieve_account_tags

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'retrieve_account_tags'
    ]
]

Here are the results returned by the request:

Parameters Values
account_tags String (JSON encoded array containing the names of all the tags in your account, empty array if no tags)

Section 23: Action: Retrieve all the lists in your account

Type Parameters Values
POST cmd* retrieve_account_lists

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'retrieve_account_lists'
    ]
]

Here are the results returned by the request:

Parameters Values
account_lists String (JSON encoded array containing the names of all the lists in your account, empty array if no lists)

Section 24: Action: Retrieve all the sequences in your account

Type Parameters Values
POST cmd* retrieve_account_sequences

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'retrieve_account_sequences'
    ]
]

Here are the results returned by the request:

Parameters Values
account_sequences String (JSON encoded array containing the names of all the sequences in your account, empty array if no sequences)

Section 25: Action: Retrieve all the pages in your account

Type Parameters Values
POST cmd* retrieve_account_pages

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'retrieve_account_pages'
    ]
]

Here are the results returned by the request:

Parameters Values
account_pages String (JSON encoded array containing the names of all the pages in your account, empty array if no pages)

Section 26: Action: Retrieve all the custom fields in your account

Type Parameters Values
POST cmd* retrieve_custom_fields

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'retrieve_custom_fields'
    ]
]

Here are the results returned by the request:

Parameters Values
custom_fields String (JSON encoded array containing the details of all the custom fields in your account, empty array if no custom fields)

Example of the returned array:

"custom_fields": [
        {
            "field_id": "1",
            "field_identifier": "gender",
            "field_type": "radio_button",
	    "field_value":[
		{
		    "option_id":"1",
		    "option_value":"male",
		},
		{
		    "option_id":"2",
		    "option_value":"female",
		}
	    ]
        },
        {
            "field_id": "2",
            "field_identifier": "fruits",
            "field_type": "checkbox",
	    "field_value":[
		{
		    "option_id":"1",
		    "option_value":"apple",
		},
		{
		    "option_id":"2",
		    "option_value":"pear",
		}
	    ]
        },
        {
            "field_id": "3",
            "field_identifier": "field_3",
            "field_type": "input_field"
        },
        {
            "field_id": "4",
            "field_identifier": "field_4",
            "field_type": "drop_down"
	    "field_value":[
		{
		    "option_id":"1",
		    "option_value":"male",
		},
		{
		    "option_id":"2",
		    "option_value":"female",
		}
	    ]            
        },
        {
            "field_id": "5",
            "field_identifier": "field_5",
            "field_type": "text_area"
        }
]

Section 27: Success and error confirmation messages

After receiving your API call, Kartra should ping-back a confirmation message upon request: either a success or an error message.

Most of these confirmation messages are usually composed of 3 pieces of information:

  1. Status of your API call: success or error.
  2. Short description text message.
  3. The message type (message ID number) for easy identification.

 

Below is the full list of errors if your API call fails to establish the connection with our API server:

{
  "status": "Error",
  "message": "Connection not secure",
  "type": "201"
}

{
  "status": "Error",
  "message": "API key cannot be empty. Please get an API key first",
  "type": "202"
}

{
  "status": "Error",
  "message": "API key not valid. Please get an API key first",
  "type": "203"
}

{
  "status": "Error",
  "message": "API password not valid. Please get an API password first",
  "type": "233"
}

{
  "status": "Error",
  "message": "API Account inactive",
  "type": "204"
}

{
  "status": "Error",
  "message": "API Account banned",
  "type": "205"
}

{
  "status": "Error",
  "message": "'cmd' is required",
  "type": "254"
}

{
  "status": "Error",
  "message": "email or lead id is required. Nothing done",
  "type": "206"
}

{
  "status": "Error",
  "message": "'lead' not an array",
  "type": "223"
}

{
  "status": "Error",
  "message": "'get_lead' not an array",
  "type": "236"
}

{
  "status": "Error",
  "message": "'actions' not an array",
  "type": "224"
}

 

Here are the error messages related to the App itself:

{
  "status": "Error",
  "message": "App Id cannot be empty. Please get an App Id first",
  "type": "238"
}

{
  "status": "Error",
  "message": "App Id is not valid. The app does not exists or is inactive",
  "type": "239"
}

{
  "status": "Error",
  "message": "App Account inactive",
  "type": "240"
}

{
  "status": "Error",
  "message": "App Account banned",
  "type": "241"
}

{
  "status": "Error",
  "message": "This API call was sent from an unauthorized IP",
  "type": "242"
}

{
  "status": "Error",
  "message": "App does not have permission to execute this CMD",
  "type": "262"
}

 

Here are the confirmation messages related to action subscribe_lead_to_list :

{
  "status": "Error",
  "message": "list_name cannot be empty. Nothing done",
  "type": "207"
}

{
  "status": "Error",
  "message": "list does not exist. Nothing done",
  "type": "237"
}

{
  "status": "Success",
  "message": "Lead subscribed in list {list_name}",
  "type": "101"
}

{
  "status": "Error",
  "message": "Lead already subscribed to list",
  "type": "235"
}

 

Here are the confirmation messages related to action unsubscribe_lead_from_list :

{
  "status": "Error",
  "message": "list_name cannot be empty. Nothing done",
  "type": "208"
}

{
  "status": "Error",
  "message": "list does not exist. Nothing done",
  "type": "209"
}

{
  "status": "Error",
  "message": "Lead already unsubscribed or not in list {list_name}",
  "type": "210"
}

{
  "status": "Success",
  "message": "Lead unsubscribed from list {list_name}",
  "type": "102"
}

 

Here are the confirmation messages related to action assign_tag :

{
  "status": "Error",
  "message": "tag_name cannot be empty. Nothing done",
  "type": "211"
}

{
  "status": "Error",
  "message": "tag does not exist. Nothing done",
  "type": "212"
}

{
  "status": "Success",
  "message": "Tag {tag_name} added to lead",
  "type": "103"
}

 

Here are the confirmation messages related to action unassign_tag :

{
  "status": "Error",
  "message": "tag_name cannot be empty. Nothing done",
  "type": "213"
}

{
  "status": "Error",
  "message": "Invalid tag. Nothing done",
  "type": "214"
}

{
  "status": "Success",
  "message": "Tag {tag_name} removed from lead",
  "type": "104"
}

 

Here are the confirmation messages related to action give_points_to_lead :

{
  "status": "Error",
  "message": "points is not a number. Nothing done",
  "type": "227"
}

{
  "status": "Error",
  "message": "points cannot be empty. Nothing done",
  "type": "215"
}

{
  "status": "Success",
  "message": "{points} points were added to lead",
  "type": "105"
}

 

Here are the confirmation messages related to action remove_points_from_lead :

{
  "status": "Error",
  "message": "points is not a number. Nothing done",
  "type": "228"
}

{
  "status": "Error",
  "message": "points cannot be empty. Nothing done",
  "type": "217"
}

{
  "status": "Success",
  "message": "{points} points were removed from lead",
  "type": "106"
}

 

Here are the confirmation messages related to action subscribe_lead_to_sequence_at_step:

{
  "status": "Error",
  "message": "sequence_name cannot be empty. Nothing done",
  "type": "224"
}

{
  "status": "Error",
  "message": "step cannot be empty. Nothing done",
  "type": "225"
}

{
  "status": "Error",
  "message": "step has to be alphanumeric. Nothing done",
  "type": "229"
}

{
  "status": "Error",
  "message": "Invalid sequence. Nothing done",
  "type": "219"
}

{
  "status": "Error",
  "message": "step does not exist. Nothing done",
  "type": "230"
}

{
  "status": "Success",
  "message": "Lead added to sequence {sequence_name} at step {current_step}",
  "type": "107"
}

{
  "status": "Error",
  "message": "Lead already subscribed to this sequence",
  "type": "231"
}

 

Here are the confirmation messages related to action unsubscribe_lead_from_sequence :

{
  "status": "Error",
  "message": "sequence_name cannot be empty. Nothing done",
  "type": "226"
}

{
  "status": "Error",
  "message": "Invalid sequence. Nothing done",
  "type": "220"
}

{
  "status": "Error",
  "message": "Lead is not subscribed to this sequence",
  "type": "232"
}

{
  "status": "Success",
  "message": "Lead removed from sequence {sequence_name}",
  "type": "108"
}

 

Here are the confirmation messages related to action refund_transaction:

{
  "status": "Error",
  "message": "Transaction doesn't exist",
  "type": "247"
}

{
  "status": "Error",
  "message": "Transaction outside refund period",
  "type": "250"
}

{
  "status": "Error",
  "message": "Transaction already refunded",
  "type": "251"
}

{
  "status": "Error",
  "message": "This type of transaction cannot be refunded or cancelled",
  "type": "253"
}

{ 
  "status": "Error", 
  "message": "Refund has failed", 
  "type": "266" 
}

{
  "status": "Success",
  "actions": [
    {
      "refund_transaction": {
        "transaction_id": "1234"
      }
    }
  ]
}

 

Here are the confirmation messages related to action cancel_transaction:

{
  "status": "Error",
  "message": "Subscription doesn't exist",
  "type": "248"
}

{
  "status": "Error",
  "message": "Transaction not linked to any recurring subscription",
  "type": "249"
}

{
  "status": "Error",
  "message": "Subscription already cancelled",
  "type": "252"
}

{
  "status": "Error",
  "message": "This type of transaction cannot be refunded or cancelled",
  "type": "253"
}

{ 
  "status": "Error", 
  "message": "Cancellation has failed", 
  "type": "267" 
}

{
  "status": "Success",
  "actions": [
    {
      "cancel_transaction": {
        "transaction_id": "1234"
      }
    }
  ]
}

 

Here are the confirmation messages related to action calendar_subscribe:

{
  "status": "Error",
  "message": "calendar_name cannot be empty. Nothing done",
  "type": "255"
}

{
  "status": "Error",
  "message": "class_name cannot be empty. Nothing done",
  "type": "256"
}

{
  "status": "Error",
  "message": "Invalid calendar. Nothing done",
  "type": "257"
}

{
  "status": "Error",
  "message": "Invalid calendar class. Nothing done",
  "type": "258"
}

{
  "status": "Error",
  "message": "Invalid date format. Nothing done",
  "type": "260"
}

{
  "status": "Error",
  "message": "Date is in the past. Nothing done",
  "type": "261"
}
{
  "status": "Success",
  "message": "The lead will be subscribed to calendar {calendar_name}, class {class_name}",
  "type": "112"
}

 

Here are the confirmation messages related to action calendar_cancel:

{
  "status": "Error",
  "message": "calendar_name cannot be empty. Nothing done",
  "type": "255"
}

{
  "status": "Error",
  "message": "class_name cannot be empty. Nothing done",
  "type": "256"
}

{
  "status": "Error",
  "message": "Invalid calendar. Nothing done",
  "type": "257"
}

{
  "status": "Error",
  "message": "Invalid calendar class. Nothing done",
  "type": "258"
}

{
  "status": "Error",
  "message": "There is no active/pending calendar subscription for this lead. Nothing done",
  "type": "259"
}

{
  "status": "Success",
  "message": "The lead will be unsubscribed from calendar {calendar_name}",
  "type": "113"
}

 

Here are the confirmation messages related to action create_custom_field:

{
  "status": "Error",
  "message": "Custom Field name can only contain letters, numbers, dashes or underscores",
  "type": "263"
}

{ 
  "status": "Error",
  "message": "Custom Field already exists or not allowed",
  "type": "264" 
}

{ 
  "status": "Error",
  "message": "'custom_field_identifier' cannot be empty",
  "type": "265" 
} 

{ 
  "status": "Error",
  "message": "'custom_field_type' not valid",
  "type": "269" 
} 

{ 
  "status": "Error",
  "message": "'custom_field_options' not an array",
  "type": "270" 
} 

{ 
  "status": "Error",
  "message": "'option_name' missing or empty",
  "type": "272" 
} 

{ 
  "status": "Error",
  "message": "'custom_field_options' must have two or more elements",
  "type": "273" 
} 

{
  "status": "Success",
  "message": "Custom Field created",
  "type: "114"
}

 

Here are the confirmation messages related to action search_transaction:

{
  "status": "Error",
  "message": "Transaction doesn't exist",
  "type": "247"
}

{
  "status": "Success",
  "message": "Transaction exists"
}

 

Here are the confirmation messages related to action search_subscription:

{
  "status": "Error",
  "message": "Subscription doesn't exist",
  "type": "248"
}

{
  "status": "Success",
  "message": "Subscription exists"
}

 

Here are the confirmation messages related to action get_transactions_from_lead:

{
  "status": "Error",
  "message": "No lead found",
  "type": 234
}

{
  "status": "Success",
  "actions": [
    {
      "get_transactions_from_lead": {
        "transaction_list": [
          {
            "transaction_id": "123456",
            "buyer_first_name": "Test",
            "buyer_last_name": "Test",
            "buyer_email": "test@test.com",
            "buyer_username": "test123",
            "buyer_id": "1234",
            "product_name": "Test Product",
            "product_id": "1234",
            "product_price_point": "1",
            "transaction_amount": "20.99",
            "transaction_full_amount": "20.99",
            "transaction_base_amount": "20.99",
            "transaction_affiliate": "N/A",
            "transaction_jv": "N/A",
            "transaction_date": "2018-07-06 00:00:00",
            "transaction_type": "sale",
            "transaction_parent_id": "0",
            "transaction_subscription_id": "7608",
            "transaction_subscription_pay_number": "1",
            "original_id": "123456",
            "buyer_billing_country": "United States",
            "buyer_billing_country_code_2": "US",
            "buyer_billing_country_code_3": "USA",
            "buyer_billing_state": "New York",
            "buyer_billing_phone_country_code": "55",
            "buyer_billing_phone_number": "555555",
            "buyer_billing_address": "test",
            "buyer_billing_city": "test",
            "buyer_billing_zip": "test",
            "transaction_discount": "N/A",
            "transaction_tax": "N/A",
            "vendor_tracking_id_1": "N/A",
            "vendor_tracking_id_2": "N/A",
            "price": "20.99",
            "rebill_circle": "1",
            "payments_left": "9999",
            "shipping_first_name": "test",
            "shipping_last_name": "test",
            "shipping_address": "test",
            "shipping_city": "test",
            "shipping_zip": "test",
            "shipping_country": "United States",
            "shipping_state": "New York",
            "transaction_shipping": "0.00",
            "payment_processor_type": "Stripe"
          }
        ]
      }
    }
  ]
}

 

Here are the confirmation messages related to action get_subscriptions_from_lead:

{
  "status": "Error",
  "message": "No lead found",
  "type": 234
}

{
  "status": "Success",
  "actions": [
    {
      "get_subscriptions_from_lead": {
        "status": "Success",
        "subscription_list": [
          {
            "transaction_subscription_id": "1234",
            "transaction_subscription_status": "Active",
            "buyer_id": "123456",
            "buyer_email": "test@test.com"
          }
        ]
      }
    }
  ]
}

 

Here are the confirmation messages related to creating a lead:

{
  "status": "Error",
  "message": "Lead already exists",
  "type": "244"
}

{
  "status": "Error",
  "message": "Wrong custom field format",
  "type": "271"
}

{
  "status": "Success",
  "actions": [
    {
      "create_lead": {
        "status": "Success",
        "lead_details": {
          "id": "1234"
        }
      }
    }
  ]
}

 

Here are the confirmation messages related to editing a lead:

{
  "status": "Error",
  "message": "No lead found",
  "type": "243"
}

{
  "status": "Error",
  "message": "Lead already exists",
  "type": "244"
}

{
  "status": "Error",
  "message": "Wrong custom field format",
  "type": "271"
}

{
  "status": "Success",
  "actions": [
    {
      "edit_lead": {
        "status": "Success",
        "lead_details": {
          "id": "1234"
        }
      }
    }
  ]
}

 

Here are the confirmation messages related to searching for a lead:

{
  "status": "Error",
  "message": "No lead found",
  "type": "243"
}

{
  "status": "Error",
  "message": "Lead is deleted",
  "type": "245"
}

{
  "status": "Success",
  "actions": [
    {
      "edit_lead": {
        "status": "Success",
        "lead_details": {
          "id": "1234"
        }
      }
    }
  ]
}

 

Here is the confirmation message when get_lead successfully finds an existing lead:

{
  "status": "Success",
  "lead_details": {
    "first_name": "Joe",
    "middle_name": "",
    "last_name": "Smith",
    "last_name2": "",
    "email": "JoeSmith@domain.com",
    "date_joined": "10 Sep 2015 02:00:24",
    "phone_country_code": "+1",
    "phone": "312521352",
    "ip": "24.255.224.9",
    "ip_country": "United States",
    "address": "Apple avenue 35",
    "zip": "90034",
    "city": "San Diego",
    "state": "California",
    "country": "United States",
    "lead_picture": "https://kartrausers.s3.amazonaws.com/kartra_user/69ffc9dee2e378bbeaf1d67f69ace176.jpg",
    "score": "12",
    "website": "http://domain.com",
    "facebook": "https://www.facebook.com/joe.smith.134",
    "twitter": "",
    "linkedin": "",
    "google_plus": "",
    "notes": "This is a test note.\n\nTest note.",
    "tags": [
      {
        "tag_name": "My customers"
      },
      {
        "tag_name": "VIP customer"
      }
    ],
    "lists": [
      {
        "list_name": "My customers newsletter",
        "active": "1"
      },
      {
        "list_name": "Free updates",
        "active": "0"
      }
    ],
    "sequences": [
      {
        "sequence_name": "My customers sequence",
        "step": "4",
        "status": "active"
      }
    ],
    "transactions": [
      {
        "transaction_id": "32550",
        "product_name": " My product",
        "product_price_point": "1",
        "transaction_type": "Sale",
        "transaction_amount": "2.00",
        "date": "18 Aug 2015 02:24:40"
      },
      {
        "transaction_id": "32551",
        "product_name": "My product",
        "product_price_point": "1",
        "transaction_type": "Refund",
        "transaction_amount": "2.00",
        "date": "19 Aug 2015 05:14:40"
      }
    ],
    "memberships": [
      {
        "name": "My customers membership",
        "level_name": "All access",
        "active": "1"
      }
    ]
  }
}

 

Here is the confirmation message when get_lead does not find any lead under the specified email:

{
  "status": "Error",
  "message": "No lead found",
  "type": "234"
}

Section 28: PHP sample: execute actions to a specific lead

Here’s a very simple PHP sample to execute multiple actions to one specific lead. First, let’s study the flow in the code:

  1. First, we ping Kartra API’s secure URL
  2. Then, we connect via to our Kartra App ID (AIm863DwsOW), injecting our customer’s unique Kartra API key (QG9GPLW8G) and Kartra API password (kdwFAfwrfVS). Obviously, you will have a different key and password.
  3. Then, we identify the lead this API call is for ( JoeSmith@domain.com ), whose full name is “Joe Smith”. If the system finds a lead with this email in our contacts database, it will overwrite the lead’s details in the lead’s profile with the new data we’re passing over. Alternatively, if the lead is not found, it will create it as a brand new contact.
  4. Then, we pass 3 actions for that lead: subscribe him or her to list “My customers newsletter”, assign him or her the tag “My customer”, and add +12 points to his or her score. Note how each action is wrapped around its own array!
  5. After all that, we request a confirmation response from the API
  6. Finally, we apply an “IF” conditional for further instructions depending on whether the command was successful or not. Note how we use the “Type” parameter to identify the message type.
<?php
$ch = curl_init();
// CONNECT TO THE API SYSTEM VIA THE APP ID, AND VERIFY MY API KEY AND PASSWORD, IDENTIFY THE LEAD, AND SEND THE ACTIONS…
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
http_build_query(
array(
'app_id' => 'AIm863DwsOW',
'api_key' => 'QG9GPLW8G',
'api_password' => 'kdwFAfwrfVS',
'lead' => array(
'email' => 'JoeSmith@domain.com',
),
'actions' => array(
'0' =>array(
'cmd' => 'subscribe_lead_to_list',
'list_name' => 'My customers newsletter'
),
'1' =>array(
'cmd' => 'assign_tag',
'tag_name' => 'My customer'
),
'2' =>array(
'cmd' => 'give_points_to_lead',
'points' => '12'
),
)
)
)
);
// REQUEST CONFIRMATION MESSAGE FROM API…
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);
$server_json = json_decode($server_output);

/* JSON SAMPLE ERROR MESSAGES:
{
"status":"Error",
,"message":"API key cannot be empty. Please get an API key first",
,"type":"202"
}
JSON SAMPLE SUCCESS MESSAGES:

{
"status":"Success"
,"lead":{"Status":"Found"}
,"actions":[
{
"subscribe_lead_to_list":
{
"status":"Success"
,"message":"Lead subscribed in list My customers
list"
,"type":"101"
}
}
,{
"assign_tag":
{
"status":"Error"
,"message":"tag does not exist. Nothing done"
,"type":"212"
}
}
,{
"give_points_to_lead":
{
"status":"Error"
,"message":"points is not a number. Nothing done"
,"type":"227"
}
}
]
}
*/

// CONDITIONAL FOR FURTHER INSTRUCTIONS…
if ($server_json->status == "Error") {
echo "Sorry, the following error has occurred: ".$server_json->message.",
type:".$server_json->type;
} elseif ($server_json->status == "Success") {
echo "lead status: ".$server_json->status."<br>";
echo "Status: ".$server_json->actions[0]->subscribe_lead_to_list->status.",

Message: ".$server_json->actions[0]->subscribe_lead_to_list->message.",
Type:".$server_json->actions[0]->subscribe_lead_to_list->type."<br>";
echo "Status: ".$server_json->actions[1]->assign_tag->status.", Message:
".$server_json->actions[1]->assign_tag->message.",
Type:".$server_json->actions[1]->assign_tag->type."<br>";
echo "Status: ".$server_json->actions[2]->give_points_to_lead->status.",
Message: ".$server_json->actions[2]->give_points_to_lead->message.",
Type:".$server_json->actions[2]->give_points_to_lead->type."<br>";
}
?>

Section 29: PHP sample: retrieving data for a specific lead

Here’s a very simple PHP sample to retrieve data from a specific lead’s profile from your contacts database.

<?php

$ch = curl_init();
// CONNECT TO API, VERIFY MY API KEY AND PASSWORD AND GET THE LEAD DATA
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'app_id' => 'AIm863DwsOW',
            'api_key' => 'QG9GPLW8G',
            'api_password' => 'kdwFAfwrfVS',
            'get_lead' => array(
                'email' => 'JoeSmith@domain.com',
            ),
        )
    )
);

// REQUEST CONFIRMATION MESSAGE FROM API…
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);
$server_json = json_decode($server_output);
switch ($server_json->status) {
    case "Error" :
        // process what error was about
        break;
    case "Success" :
        // after this you can use the info passed from kartra in your own scripts. 
        // Ex: $server_json->lead_details contains the lead details
        break;
}

?>

Section 30: PHP sample: creating a lead

Here’s a very simple PHP sample to CREATE a lead plus, in the same API call, we will also assign a tag (yes, you can chain two or more actions inside the same API call):

<?php

$ch = curl_init();
// CONNECT TO API, VERIFY MY API KEY AND PASSWORD AND GET THE LEAD DATA
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'app_id' => 'AIm863DwsOW',
            'api_key' => 'QG9GPLW8G',
            'api_password' => 'kdwFAfwrfVS',
            'lead' => array(
                'email' => 'JoeSmith@domain.com',
                'first_name' => 'Joe',
                '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', '621']
                           ],
                ]  // Please read Note (1) below 
            ),
            'actions' => array(
                '0' => array(
                       'cmd' => 'create_lead',
                ),
                '1' => array(
                       'cmd' => 'assign_tag',
                       'tag_name' => 'My customer'
                )
            )
      )
   )
);

// REQUEST CONFIRMATION MESSAGE FROM API…
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);
$server_json = json_decode($server_output);
switch ($server_json->status) {
    case "Error" :
        // process what error was about
        break;
    case "Success" :
        // after this you can use the info passed from kartra in your own scripts. 
        // Ex: $server_json->lead_details contains the lead details
        break;
}

?>

Note (1): Custom field names must already exist in your Kartra account. Otherwise, if the system cannot find the corresponding custom name, it will ignore it.

Section 31: PHP sample: editing a specific lead

Here’s a very simple PHP sample to EDIT a lead’s details plus, in the same API call, we will also assign a tag (yes, you can chain two or more actions inside the same API call):

<?php

$ch = curl_init();
// CONNECT TO API, VERIFY MY API KEY AND PASSWORD AND GET THE LEAD DATA
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'app_id' => 'AIm863DwsOW',
            'api_key' => 'QG9GPLW8G',
            'api_password' => 'kdwFAfwrfVS',
            'lead' => array(
                'id' => '3232323223', //you may pass either ID or EMAIL. If both, the system will pick ID
                'email' => 'JoeSmith@domain.com',
                'first_name' => 'Joe New',
                'last_name' => 'Smith New',
                'custom_fields' => [
                    '0' => [
                               'field_identifier' => 'text1',
                               'field_value' => 'text message'
                           ],
                    '1' => [
                               'field_identifier' => 'dropdown1',
                               'field_value' => '612'
                           ],
                    '2' => [
                               'field_identifier' => 'checkbox1',
                               'field_value' => ['620', '621']
                           ],
                ], // Please read Note (1) below 
                'new_email' => 'JoeSmith+new@domain.com' 
            ), 
            'actions' => array( 
                '0' => array( 
                    'cmd' => 'edit_lead'
                ), 
                '1' => array( 
                    'cmd' => 'assign_tag', 
                    'tag_name' => 'My customer' 
                ) 
            ) 
        ) 
     ) 
  ); // REQUEST CONFIRMATION MESSAGE FROM API… curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $server_output = curl_exec ($ch); curl_close ($ch); $server_json = json_decode($server_output); switch ($server_json->status) { case "Error" : // process what error was about break; case "Success" : // after this you can use the info passed from kartra in your own scripts. // Ex: $server_json->lead_details contains the lead details break; } ?>

 

Note (1): Custom field names must already exist in your Kartra account. Otherwise, if the system cannot find the corresponding custom name, it will ignore it.

Section 32: PHP sample: searching for a specific lead

Here’s a very simple PHP sample to SEARCH for an existing lead:

<?php

$ch = curl_init();
// CONNECT TO API, VERIFY MY API KEY AND PASSWORD AND GET THE LEAD DATA
curl_setopt($ch, CURLOPT_URL,"https://app.kartra.com/api");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'app_id' => 'AIm863DwsOW',
            'api_key' => 'QG9GPLW8G',
            'api_password' => 'kdwFAfwrfVS',
            'lead' => array(
                'id' => '3232323223', //you may pass either ID or EMAIL. If both, the system will pick ID
                'email' => 'JoeSmith@domain.com',     
            ),
            'actions' => array(
                '0' => array(
                       'cmd' => 'search_lead',
                 ),
            )
      )
   )
);

// REQUEST CONFIRMATION MESSAGE FROM API…
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
curl_close ($ch);
$server_json = json_decode($server_output);
switch ($server_json->status) {
    case "Error" :
        // process what error was about
        break;
    case "Success" :
        // after this you can use the info passed from kartra in your own scripts. 
        // Ex: $server_json->lead_details contains the lead details.
        break;
}

?>

Section 33: API limits

Our inbound API system has a hardcoded limit of 20 API calls per second per App. That means none of the individual Apps within your Kartra account should send more than 20 API calls per second to Kartra. If that limit is exceeded, the system will return a “Too many requests” error message (429 error), upon which you should wait 1 second and re-try the instruction again.

We strongly recommend to implement in your Apps a queue system that throttles your outbound API calls to a maximum rate of 20 calls per second. That way, if your App goes through a burst of activity, it will pro-actively queue up the outbound calls and process them in a first-in-first-out sequential order, so they never go beyond the limit. It’s better to hold them back for a second or two than to get them error’ed out!

© 2020 Kartra All Rights Reserved