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

Activating the App
Connecting to the API
Lead: Editing, Searching or Creating a lead
Lead: Retrieving data
Action: Subscribe a lead to a list
Action: Unsubscribe a lead to a list
Action: Assign tag to a lead
Action: Unassign tag from a lead
Action: Give points to lead
Action: Remove points from a lead
Action: Subscribe lead to a sequence
Action: Unsubscribe lead from a sequence
Action: Subscribe a lead to a katra calendar
Action: Cancel subscription to a katra calendar
Action: Create custom fields
Action: Search payment transaction
Action: Refund a payment transaction
Action: Edit recurring payment subscription settings
Action: Cancel a recurring payment subscription
Action: Edit recurring payment subscription status
Action: Search recurring payment subscription
Action: Get recurring payment subscription details
Action: Get payment transaction details
Action: Retrieve payment transactions from lead
Action: Retrieve payment transactions from lead
Action: Retrieve all the tags in your account
Action: Retrieve all the lists in your account
Action: Retrieve all the sequences in your account
Action: Retrieve all the pages in your account
Action: Retrieve all the custom fields in your account
Success and error confirmation messages
PHP sample: execute actions to a specific lead
PHP sample: retrieving data for a specific lead
PHP sample: creating a lead
PHP sample: editing a lead
 PHP sample: searching for a specific lead
API limits

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.

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.

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"
}

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"
}

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:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'subscribe_lead_to_list',
        'list_name' => 'List name'
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
207 List cannot be empty
  • ‘list_name’ parameter it is mandatory and cannot be empty.
231 List does not exist
  • The list is not in our database.

An example of an error message:

{
  "status": "Error",
  "message": "List cannot be empty",
  "type": "207"
}

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:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'unsubscribe_lead_from_list',
        'list_name' => 'List name'
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
208 List cannot be empty
  • ‘list_name’ parameter it is mandatory and cannot be empty.
209 List does not exist
  • The list is not in our database.

An example of an error message:

{
  "status": "Error",
  "message": "List does not exist",
  "type": "209"
}

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:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'assign_tag',
        'tag_name' => 'tag name'
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
211 Tag cannot be empty
  • ‘tag_name’ parameter it is mandatory and cannot be empty.
212 Tag does not exist
  • The tag is not in our database.

An example of an error message:

{
  "status": "Error",
  "message": "Tag cannot be empty",
  "type": "211"
}

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:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'unassign_tag',
        'tag_name' => 'tag name'
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
213 Tag cannot be empty
  • ‘tag_name’ parameter it is mandatory and cannot be empty.
214 Tag does not exist
  • The tag is not in our database.

An example of an error message:

{
  "status": "Error",
  "message": "Tag does not exist",
  "type": "214"
}

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

* Required fields

** 0 or not sending the parameter at all will mean that the points have no expiration date.

Here is an example:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'give_points_to_lead',
        'points' => 1
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
227 Points is not a number
  • ‘points’ parameter needs to be a numeric value.
215 Points cannot be empty
  • ‘points’ parameter it is mandatory and cannot be empty.

An example of an error message:

{
  "status": "Error",
  "message": "Points cannot be empty",
  "type": "215"
}

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:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'remove_points_from_lead',
        'points' => 1
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
228 Points is not a number
  • ‘points’ parameter needs to be a numeric value.
217 Points cannot be empty
  • ‘points’ parameter it is mandatory and cannot be empty.

An example of an error message:

{
  "status": "Error",
  "message": "Points cannot be empty",
  "type": "217"
}

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:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'subscribe_lead_to_sequence_at_step',
        'sequence_name' => 'Sequence name',
        'step' => '1'
    ]
]

Success message:

{
  "status": "Success",
  "message": "Lead added to sequence",
  "type": "107"
}

Error Cases:

Type Number Message Cause
226 Sequence cannot be empty
  • sequence_name parameter is mandatory and cannot be empty.
225 Step cannot be empty
  • step parameter is mandatory and cannot be empty.
219 Sequence does not exist
  • The sequence is not in our database.
229 Step has to be alphanumeric
  • step parameter needs to have alphanumeric characters.
230 Step does not exist
  • The sequence step was not found in our database.

An example of an error message:

{
  "status": "Error",
  "message": "Sequence cannot be empty",
  "type": "226"
}

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:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'unsubscribe_lead_from_sequence',
        'sequence_name' => 'Sequence name'
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
226 Sequence cannot be empty
  • ‘sequence_name’ parameter is mandatory and cannot be empty
220 Sequence does not exist
  • The sequence is not in our database.

An example of an error message:

{
  "status": "Error",
  "message": "Sequence cannot be empty",
  "type": "226"
}

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) Timezone EST
POST starting_hour string (HH:MM) Timezone EST

* Required fields

Here is an example:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'calendar_subscribe',
        'calendar_name' => 'First calendar',
        'class_name' => 'First class',
        'starting_date' => '16 Jan 2019',
        'starting_hour' => '15:00',
    ]
]

Success message:

{
  "status": "Success",
  "message": "Lead subscribed to class",
  "type": "112"
}

Error Cases:

Type Number Message Cause
255 Calendar cannot be empty
  • The ‘calendar_name’ parameter is mandatory and needs to contain data
256 Class cannot be empty
  • The ‘class_name’ parameter is mandatory and needs to contain data.
257 Calendar does not exist
  • The calendar does not exist in the database or is not completed.
258 Class does not exist
  • The class does not exist in the database or does not belong to the calendar.
260 Invalid date format
  • starting_date does not have the correct ‘DD Mmm YYYY’ format or starting_hour does not have the correct ‘HH:MM’ format
261 Date is in the past
  • starting_date with starting_hour is in the past based on EST timezone.

An example of an error message:

{
  "status": "Error",
  "message": "Class does not exist",
  "type": "258"
}

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:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'calendar_cancel',
        'calendar_name' => 'First calendar',
        'class_name' => 'First class'
    ]
]

Success message:

{
  "status": "Success",
  "message": "Lead unsubscribed from class",
  "type": "113"
}

Error Cases:

Type Number Message Cause
255 Calendar cannot be empty
  • The ‘calendar_name’ parameter is mandatory and needs to contain data
256 Class cannot be empty
  • The ‘class_name’ parameter is mandatory and needs to contain data.
257 Calendar does not exist
  • The calendar does not exist in the database or is not completed.
258 Class does not exist
  • The class does not exist in the database or does not belong to the calendar.
259 No active/pending calendar subscription for this lead
  • There is no lead subscribed to the class, so there is nothing to cancel.

An example of an error message:

{
  "status": "Error",
  "message": "Class does not exist",
  "type": "258"
}

Action: Create custom fields

This will allow you to create a custom field that can be used to gather custom info related to a Lead.

Type Parameters Values
POST cmd* create_custom_field
POST custom_field_identifier * string
POST custom_field_type* Posible values are ‘input_field’, ‘text_area’, ‘drop_down’, ‘radio_button’, ‘checkbox’
POST custom_field_options ** array of arrays with one parameter: option_name (string containing the name of the option)

* Required fields
** Required for drop_down, radio_button, checkbox field types.

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

Success message:

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

Error Cases:

Type Number Message Cause
263 Custom Field name can only contain letters, numbers, dashes or underscores
  • custom_field_identifier can only contain letters, numbers, dashes or underscores.
264 Custom Field already exists or not allowed
  • custom_field_identifier value already exists in the database or is not allowed.
265 Custom Field cannot be empty
  • custom_field_identifier must not be an empty string.
269 Custom Field type not valid
  • custom_field_type value is not one of ‘input_field’, ‘text_area’, ‘drop_down’, ‘radio_button’, ‘checkbox’.
270 Options not an array
  • custom_field_options needs to be an array.
272 Option cannot be empty
  • option_name must not be empty.
273 Options must have two or more elements
  • custom_field_options has to be an array with at least two elements for the options.

An example of an error message:

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

Action: Search payment transaction

This will allow you to search for a payment transaction inside Kartra, and to verify whether 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
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
247 Transaction doesn’t exist
  • The transaction you are trying to find does not exist in our database.

An example of an error message:

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

Action: Refund a payment transaction

This will allow you to refund an individual payment transaction within the refund period.

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

* Required field
** If refund_amount is left empty, the entire transaction amount will be refunded. No need to state the currency, as it will be executed in whatever currency the original transaction was processed in.

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'refund_transaction',
        'transaction_id' => 738474,
        'refund_amount' => 19.95
    ]
]

Success message:

{
    "refund_transaction":{
        "status":"Success",
        "transaction_refunded":"792354"
    }
}

Result parameters:

Parameters Values
transaction_refunded integer The unique identifier that is the transaction id.

 
Error Cases:

Type Number Message Cause
247 Transaction doesn’t exist
  • The transaction you are trying to refund does not exist in our database.
250 Transaction outside refund period
  • The transaction refund period has expired.
251 Transaction already refunded
  • The transaction you are trying to refund is already refunded.
253 This type of transaction cannot be refunded or cancelled
  • The transaction is not a sale or a rebill type, or is a test transaction.
266 Refund has failed
  • The refund process encountered an unexpected issue.
268 Invalid amount
  • If refund_amount is present, but the format is not float.

An example of an error message:

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

Action: Edit recurring payment subscription settings

This will allow you to change various parameters related to a particular recurring payment subscription from one particular lead.

A few limitations to keep in mind

  • PayPal subscriptions cannot be edited, since Paypal manages the subscriptions in-house and they do not allow modifications from external sources.
  • Payment subscriptions with status Cancelled or Terminated (meaning payment plans where all scheduled payments have already been paid) cannot be changed since they are not technically active anymore.

 

Type Parameters Values
POST cmd* edit_subscription
POST subscription_id* integer
POST subscription_product_id** *** integer
POST subscription_price_point** *** integer
POST subscription_next_payment_date *** ‘yyyy-mm-dd hh:mm’ format Timezone EST
POST subscription_amount *** decimal
POST subscription_recurrence ***
recurring_period_1
  • price point type ‘Recurring’ and ‘Installments’ (‘monthly’, ‘every 2 months’, ‘quarterly’,’yearly’, ‘every 2 years’, ‘weekly’, ‘every 2 weeks’)
  • price point type ‘Recurring installments’ (‘monthly’, ‘every 2 months’, ‘ ‘weekly’, ‘every 2 weeks’)
recurring_period_2
  • price point type ‘Recurring installments’ only (‘yearly’, ‘every 2 years’)
POST subscription_product_quantity *** integer
POST subscription_installments_left *** integer or ‘until cancelled’

* Required fields.

** In case of changing the product id, both subscription_product_id and subscription_price_point need to be present.

*** At least one of the parameters need to be sent to the API.

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'edit_subscription',
        'subscription_id' => 32451,
        'subscription_product_id' => 223,
        'subscription_price_point' => 2,
        'subscription_next_payment_date' => '2021-01-18 05:46:00',
        'subscription_amount' => 22.00,
        'subscription_recurrence' => [
            'recurring_period_1' => 'monthly',
            'recurring_period_2' => 'yearly'
        ],
        'subscription_product_quantity' => 2,
        'subscription_installments_left' => 3
    ]
]

Success message:

{
    "status":"Success",
    "actions":[
        {
            "edit_subscription":{
                "status":"Success",
                "message":"Subscription modified",
                "type":"115"
            }
        }
    ]
}

Error Cases:

Type Number Message Cause
248 Subscription doesn’t exist
  • The subscription you are trying to modify does not exist in our database.
284 Paypal transactions cannot be modified
  • Paypal subscriptions can only be cancelled, no other modifications are allowed.
275 Subscriptions cancelled or terminated cannot be updated
  • The subscription you are trying to modify is either cancelled or terminated. These type subscriptions cannot be modified anymore.
276 Quantity must be between 1 and 9,999
  • The quantity number must exceed the interval between 1 and 9,999.
277 Price must be between 1.00 and 9,999.99
  • The amount allowed is between 1.00 and 9,999.99 in the currency the subscription is setup with.
283 Wrong product id or price point
  • subscription_product_id or subscription_price_point do not exist or they were deleted.
281 Recurrence cannot be changed
  • Price point type ‘One time’ payment configuration cannot be applied to the subscription.
  • Type ‘Recurring installments’ can only be modified with the same type and vice-versa.
  • Subscriptions with ‘One time’ with trial payment configuration cannot have the recurrence modified.
278 Invalid number
  • The subscription_installments_left is not a valid positive number or ‘until cancelled’.
260 Invalid date format
  • subscription_next_payment_date does not have the correct ‘yyyy-mm-dd hh:mm’ format.
261 Date is in the past
  • subscription_next_payment_date is a date from the past based on EST timezone.
280 Invalid recurring period
  • recurring_period_1 or recurring_period_2 does not have the correct format stated above.
  • recurring_period_2 is sent but recurring_period_1 does not have the correct value.
282 Incorrect number of installments
  • In the case of ‘Recurring installments’ type of recurrence, the number of installments already set cannot be bigger than the total number of installments for recurring_period_1 over the recurring_period_2 interval.
268 Invalid amount
  • subscription_amount is not in the positive numeric format or numeric with two decimals.
285 No editable parameters for subscription
  • No parameters to edit were sent.

An example of an error message:

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

Action: Cancel a recurring payment 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_internal_subscription_id** integer

* Required fields
** Required either the transaction_id OR transaction_internal_subscription_id in order for a subscription to be correctly identified and canceled.

Here is an example:

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

Success message:

{
    "cancel_transaction":{
        "status":"Success",
        "transaction_subscription_id":"I-EV375R0H61SM",
        "transaction_internal_subscription_id":"14833"
    }
}

Result parameters:

Parameters Values
transaction_subscription_id string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id).
transaction_internal_subscription_id integer A unique numeric identifier for the subscription id.

Error Cases:

Type Number Message Cause
248 Subscription doesn’t exist
  • The subscription you are trying to cancel does not exist in our database.
249 Transaction not linked to any recurring subscription
  • The transaction is not part of a payment subscription.
252 Subscription already cancelled
  • The subscription you are trying to cancel is already cancelled.
253 This type of transaction cannot be refunded or cancelled
  • The transaction is not a sale or a rebill type, or is a test transaction.
267 Cancellation has failed
  • The cancellation process encountered an unexpected issue.

An example of an error message:

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

Action: Edit recurring payment subscription status

This will allow you to change the status of a particular recurring payment subscription from one particular lead. The possible statuses are…

  • Active
  • Cancelled
  • Terminated: meaning payment plans where all scheduled payments have already been paid
  • Paused: the subscription is technically active but no further payment will be processed until you “unpause” it back to Active (see below)

A few limitations to keep in mind

  • PayPal subscriptions cannot be edited, since Paypal manages the subscriptions in-house and they do not allow modifications from external sources.
  • Payment subscriptions with status Cancelled or Terminated cannot be changed since they are not technically active anymore.

 

Type Parameters Values
POST cmd* modify_subscription_status
POST subscription_id* integer
POST subscription_status_modification* Posible values are “cancel”, “unpause”, “pause”

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'modify_subscription_status',
        'subscription_id' => 7373847,
        'subscription_status_modification' => 'pause',
    ]
]

Success message:

{
    "status":"Success",
    "actions":[
        {
            "modify_subscription_status":{
                "status":"Success",
                "message":"Subscription modified",
                "type":"115"
            }
        }
    ]
}

Error Cases:

Type Number Message Cause
248 Subscription doesn’t exist
  • The subscription you are trying to modify does not exist in our database.
274 Wrong status
  • subscription_status_modification is not sent.
  • subscription_status_modification value does not have one of the values “cancel”, “unpause”, “pause”.
284 Paypal transactions cannot be modified
  • Paypal subscriptions can only be cancelled, no other modifications are allowed.
275 Subscriptions cancelled or terminated cannot be updated
  • The subscription you are trying to modify is either cancelled or terminated. These type subscriptions cannot be modified anymore.
252 Subscription already cancelled
  • The subscription you are trying to cancel is already cancelled.
267 Cancellation has failed
  • The cancellation process encountered an unexpected issue.

An example of an error message:

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

Action: Search recurring payment subscription

This will allow you to search for a recurring payment subscription inside Kartra, and to verify whether it exists or not.

Type Parameters Values
POST cmd* search_subscription
POST transaction_internal_subscription_id* integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'search_subscription',
        'transaction_internal_subscription_id' => 94314
    ]
]

Success message:

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

Error Cases:

Type Number Message Cause
248 Subscription doesn’t exist
  • The subscription you are trying to find does not exist in our database.

An example of an error message:

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

Action: Get recurring payment subscription details

This will allow you to retrieve the information related to a particular recurring payment subscription in Kartra.

Type Parameters Values
POST cmd* get_subscription_details
POST subscription_id* integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'get_subscription_details',
        'subscription_id' => 993037
    ]
]

Here are the results returned by the request:

Parameters Values
subscription_details String (JSON encoded string containing the details of the recurring payment subscription)

 

JSON parameters Values
subscription_id integer A unique numeric identifier for the subscription id.
subscription_product_id integer Product id of the subscription.
subscription_price_point integer Product price point number of the subscription.
subscription_lead_id integer Id for the lead linked to the subscription.
subscription_start_date yyyy-mm-dd hh:mm:ss Subscription start date EST.
subscription_end_date yyyy-mm-dd hh:mm:ss Subscription end date EST (0000-00-00 00:00:00 if subscription is not cancelled or terminated).
subscription_current_installment integer Number of the current installment.
subscription_installments_left integer How many installments are left / string “Until cancelled”
subscription_recurring_period string (“monthly”, “every 2 months”, “quarterly”,”yearly”, “every 2 years”, “weekly”, “every 2 weeks”) The type of recurring for the subscription.
subscription_status string (“Active”, “Paused”, “Cancelled”, “Terminated”) Subscription status.
subscription_next_payment_date yyyy-mm-dd hh:mm:ss Subscription next payment date EST.
subscription_next_scheduled_payment_amount float The amount of the next scheduled payment. “N/A” if none.
subscription_affiliate string Username of the affiliate, “N/A” if none.
subscription_jv string Username of the jv, “N/A” if none.

 

Example of the returned JSON array:

{
    "get_subscription_details":{
        "subscription_details":{
            "subscription_id":"993037",
            "subscription_product_id":"213",
            "subscription_price_point":"2",
            "subscription_lead_id":"321",
            "subscription_start_date":"2021-01-07 11:14:00",
            "subscription_end_date":"0000-00-00 00:00:00",
            "subscription_current_installment":"1",
            "subscription_installments_left":"Until cancelled",
            "subscription_recurring_period":"monthly",
            "subscription_status":"Active",
            "subscription_next_payment_date":"2021-02-07 11:14:00",
            "subscription_next_scheduled_payment_amount":"22.19",
            "subscription_affiliate":"affiliate_username",
            "subscription_jv":"N/A"
        }
    }
}

Error Cases:

Type Number Message Cause
248 Subscription doesn’t exist
  • The subscription you are trying to find does not exist in our database.

An example of an error message:

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

Action: Get payment transaction details

This will allow you to retrieve the information related to a particular payment transaction in Kartra.

Type Parameters Values
POST cmd* get_transaction_details
POST transaction_id* integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'get_transaction_details',
        'transaction_id' => 99432
    ]
]

Here are the results returned by the request:

Parameters Values
transaction_details String (JSON encoded string containing the details of the payment transaction)

 

JSON parameters:

For sale transactions Values
transaction_id integer A unique numeric identifier for the transaction id.
lead_first_name string The lead first name at the moment of purchase.
lead_last_name string The lead last name at the moment of purchase.
lead_email string The lead email at the moment of purchase.
lead_id integer A unique numeric identifier for the lead id.
lead_username string The lead username.
lead_country string The lead country at the moment of purchase.
lead_country_code_2 string The lead two letter country code at the moment of purchase.
lead_country_code_3 string The lead three letter country code at the moment of purchase.
lead_state string The lead state at the moment of purchase.
lead_phone_country_code string The lead phone country code at the moment of purchase.
lead_phone_number string The lead phone number at the moment of purchase.
lead_address string The lead address at the moment of purchase.
lead_city string The lead city at the moment of purchase.
lead_zip string The lead zip at the moment of purchase.
lead_zip string The lead zip at the moment of purchase.
product_name string The product name at the moment of purchase.
product_id integer The product id linked to the transaction.
product_price_point integer The product price point linked to the transaction.
transaction_full_amount float The final paid amount on this specific transaction.
transaction_quantity
integer The product quantity.
transaction_affiliate string Username of the affiliate, “N/A” if none.
transaction_jv string Username of the jv, “N/A” if none.
transaction_date yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type string The transaction type. Possible values: ‘sale’
transaction_parent_id integer The id of the parent transaction (in the case of sale it is 0)
transaction_subscription_id string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be “N/A”).
transaction_internal_subscription_id integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be “N/A”).
transaction_subscription_pay_number  integer The payment number of the subscription related to the transaction, if any. If not the value will be “N/A”
transaction_discount float If any discount coupon was applied, the amount in dollars deducted from the original price. “N/A” if none.
transaction_tax float The amount of sales tax or VAT. “N/A” if none.
transaction_base_amount float The base price for the transaction (for trial this will be the base price of the initial transaction).
transaction_shipping float The shipping cost.
transaction_last_4_card_digits integer The last 4 digits of the used card (‘N/A’ if PayPal)
original_id integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1 string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2 string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link
string Vendor’s tracking link name.
trial integer 1 or 0, depending on whether trial is activated or not.
trial_period
integer The trial period in days.
trial_amount
float The trial amount.
rebill_circle integer Days left for the next payment. Present only for recurring subscription payments.
installments integer The number of installments for the subscription. Present only for recurring subscription payments with finite number of installments.
frequency
string The frequency of recurrence. Possible values (‘every_year’, ‘every_2_years’). Present only for recurring subscription payments with price point type recurrent.
payments_left integer Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”. Present only for recurring subscription payments.
shipping_first_name string Lead’s shipping first name. “N/A” if none.
shipping_last_name string Lead’s shipping last name. “N/A” if none.
shipping_address string Lead’s shipping address. “N/A” if none.
shipping_city string Lead’s shipping city. “N/A” if none.
shipping_zip string Lead’s shipping zip. “N/A” if none.
shipping_country string Lead’s shipping country. “N/A” if none.
shipping_state string Lead’s shipping state. “N/A” if none.
payment_processor_type
string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”

 

JSON parameters:

For refund/chargeback/partial refund transactions Values
transaction_id integer A unique numeric identifier for the transaction id.
lead_first_name string The lead first name at the moment of purchase.
lead_last_name string The lead last name at the moment of purchase.
lead_email string The lead email at the moment of purchase.
lead_id integer A unique numeric identifier for the lead id.
lead_username string The lead username.
lead_country string The lead country at the moment of purchase.
lead_country_code_2 string The lead two letter country code at the moment of purchase.
lead_country_code_3 string The lead three letter country code at the moment of purchase.
lead_state string The lead state at the moment of purchase.
lead_phone_country_code string The lead phone country code at the moment of purchase.
lead_phone_number string The lead phone number at the moment of purchase.
lead_address string The lead address at the moment of purchase.
lead_city string The lead city at the moment of purchase.
lead_zip string The lead zip at the moment of purchase.
product_name string The product name at the moment of purchase.
product_id integer The product id linked to the transaction.
product_price_point integer The product price point linked to the transaction.
transaction_full_amount float The final paid amount on this specific transaction.
transaction_quantity
integer The product quantity. Not present in cancellations.
transaction_affiliate string Username of the affiliate, “N/A” if none.
transaction_jv string Username of the jv, “N/A” if none.
transaction_date yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type string The transaction type. Possible values: ‘refund’, ‘chargeback’, ‘partial_refund’
transaction_parent_id integer The id of the parent transaction
transaction_subscription_id string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be 0).
transaction_internal_subscription_id integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be 0).
transaction_subscription_pay_number  integer The payment number of the subscription related to the transaction, if any.
transaction_discount float If any discount coupon was applied, the amount in dollars deducted from the original price. “N/A” if none.
transaction_tax float The amount of sales tax or VAT. “N/A” if none.
transaction_base_amount float The base price for the transaction (for trial this will be the base price of the initial transaction).
transaction_shipping float The shipping cost.
original_id integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1 string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2 string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link
string Vendor’s tracking link name.
shipping_first_name string Lead’s shipping first name. “N/A” if none.
shipping_last_name string Lead’s shipping last name. “N/A” if none.
shipping_address string Lead’s shipping address. “N/A” if none.
shipping_city string Lead’s shipping city. “N/A” if none.
shipping_zip string Lead’s shipping zip. “N/A” if none.
shipping_country string Lead’s shipping country. “N/A” if none.
shipping_state string Lead’s shipping state. “N/A” if none.
payment_processor_type
string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”

 

JSON parameters:

For rebill transactions Values
transaction_id integer A unique numeric identifier for the transaction id.
lead_first_name string The lead first name at the moment of purchase.
lead_last_name string The lead last name at the moment of purchase.
lead_email string The lead email at the moment of purchase.
lead_id integer A unique numeric identifier for the lead id.
lead_username string The lead username.
lead_country string The lead country at the moment of purchase.
lead_country_code_2 string The lead two letter country code at the moment of purchase.
lead_country_code_3 string The lead three letter country code at the moment of purchase.
lead_state string The lead state at the moment of purchase.
lead_phone_country_code string The lead phone country code at the moment of purchase.
lead_phone_number string The lead phone number at the moment of purchase.
lead_address string The lead address at the moment of purchase.
lead_city string The lead city at the moment of purchase.
lead_zip string The lead zip at the moment of purchase.
product_name string The product name at the moment of purchase.
product_id integer The product id linked to the transaction.
product_price_point integer The product price point linked to the transaction.
transaction_full_amount float The final paid amount on this specific transaction.
transaction_quantity
integer The product quantity. Not present in cancellations.
transaction_affiliate string Username of the affiliate, “N/A” if none.
transaction_jv string Username of the jv, “N/A” if none.
transaction_date yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type string The transaction type. Possible values: ‘rebill’
transaction_parent_id integer The id of the parent transaction (in the case of refunds/chargebacks)
transaction_subscription_id string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be 0).
transaction_internal_subscription_id integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be 0).
transaction_subscription_pay_number  integer The payment number of the subscription related to the transaction.
transaction_discount float If any discount coupon was applied, the amount in dollars deducted from the original price. “N/A” if none.
transaction_tax float The amount of sales tax or VAT. “N/A” if none.
transaction_base_amount float The base price for the transaction (for trial this will be the base price of the initial transaction).
transaction_shipping float The shipping cost.
original_id integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1 string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2 string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link
string Vendor’s tracking link name.
shipping_first_name string Lead’s shipping first name. “N/A” if none.
shipping_last_name string Lead’s shipping last name. “N/A” if none.
shipping_address string Lead’s shipping address. “N/A” if none.
shipping_city string Lead’s shipping city. “N/A” if none.
shipping_zip string Lead’s shipping zip. “N/A” if none.
shipping_country string Lead’s shipping country. “N/A” if none.
shipping_state string Lead’s shipping state. “N/A” if none.
rebill_circle integer Days left for the next payment.
installments integer The number of installments for the subscription. Present only for recurring subscription payments with finite number of installments.
frequency string The frequency of recurrence. Possible values (‘every_year’, ‘every_2_years’). Present only for recurring subscription payments with price point type recurrent.
payments_left integer Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”.
payment_processor_type
string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”
failed_reattempt_number
integer If this is a reattempt of a failed transaction, the retry number

 

JSON parameters:

For failed transactions Values
transaction_id integer A unique numeric identifier for the transaction id.
lead_first_name string The lead first name at the moment of purchase.
lead_last_name string The lead last name at the moment of purchase.
lead_email string The lead email at the moment of purchase.
lead_id integer A unique numeric identifier for the lead id.
lead_username string The lead username.
lead_country string The lead country at the moment of purchase.
lead_country_code_2 string The lead two letter country code at the moment of purchase.
lead_country_code_3 string The lead three letter country code at the moment of purchase.
lead_state string The lead state at the moment of purchase.
lead_phone_country_code string The lead phone country code at the moment of purchase.
lead_phone_number string The lead phone number at the moment of purchase.
lead_address string The lead address at the moment of purchase.
lead_city string The lead city at the moment of purchase.
lead_zip string The lead zip at the moment of purchase.
product_name string The product name at the moment of purchase.
product_id integer The product id linked to the transaction.
product_price_point integer The product price point linked to the transaction.
transaction_full_amount float The final paid amount on this specific transaction.
transaction_quantity
integer The product quantity.
transaction_affiliate string Username of the affiliate, “N/A” if none.
transaction_jv string Username of the jv, “N/A” if none.
transaction_date yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type string The transaction type. Possible values: ‘failed’
transaction_parent_id integer The id of the parent transaction (in the case of refunds/chargebacks)
transaction_subscription_id string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be 0).
transaction_internal_subscription_id integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be 0).
transaction_subscription_pay_number  integer The payment number of the subscription related to the transaction.
transaction_discount float If any discount coupon was applied, the amount in dollars deducted from the original price. “N/A” if none.
transaction_tax float The amount of sales tax or VAT. “N/A” if none.
transaction_base_amount float The base price for the transaction (for trial this will be the base price of the initial transaction).
transaction_shipping float The shipping cost.
original_id integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1 string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2 string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link
string Vendor’s tracking link name.
shipping_first_name string Lead’s shipping first name. “N/A” if none.
shipping_last_name string Lead’s shipping last name. “N/A” if none.
shipping_address string Lead’s shipping address. “N/A” if none.
shipping_city string Lead’s shipping city. “N/A” if none.
shipping_zip string Lead’s shipping zip. “N/A” if none.
shipping_country string Lead’s shipping country. “N/A” if none.
shipping_state string Lead’s shipping state. “N/A” if none.
payment_processor_type
string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”
failed_reattempt_number
integer If this is a reattempt of a failed transaction, the retry number

 

JSON parameters:

For cancellation transactions Values
transaction_id integer A unique numeric identifier for the transaction id.
lead_first_name string The lead first name at the moment of purchase.
lead_last_name string The lead last name at the moment of purchase.
lead_email string The lead email at the moment of purchase.
lead_id integer A unique numeric identifier for the lead id.
lead_username string The lead username.
lead_country string The lead country at the moment of purchase.
lead_country_code_2 string The lead two letter country code at the moment of purchase.
lead_country_code_3 string The lead three letter country code at the moment of purchase.
lead_state string The lead state at the moment of purchase.
lead_phone_country_code string The lead phone country code at the moment of purchase.
lead_phone_number string The lead phone number at the moment of purchase.
lead_address string The lead address at the moment of purchase.
lead_city string The lead city at the moment of purchase.
lead_zip string The lead zip at the moment of purchase.
lead_ip string The lead ip at the moment of purchase.
product_name string The product name at the moment of purchase.
product_id integer The product id linked to the transaction.
product_price_point integer The product price point linked to the transaction.
transaction_date yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type string The transaction type. Possible values: ‘cancellation’
transaction_parent_id integer The id of the parent transaction (in the case of refunds/chargebacks)
transaction_subscription_id string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be 0).
transaction_internal_subscription_id integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be 0).
transaction_last_4_card_digits integer The last 4 digits of the used card (‘N/A’ if PayPal)
original_id integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1 string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2 string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link
string Vendor’s tracking link name.
payment_processor_type
string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”

 

Example of the returned JSON array:

{
    "get_transaction_details":{
        "transaction_details":{
            "transaction_id":"99432",
            "lead_first_name":"Joe",
            "lead_last_name":"Smith",
            "lead_email":"joe.smith@domain.com",
            "lead_id":"4174086",
            "lead_username":"emailtest5e9476c0",
            "product_name":"Product kartra",
            "product_id":"5425",
            "product_price_point":"2",
            "transaction_full_amount":"4.00",
            "transaction_quantity":"1",
            "transaction_affiliate":"N/A",
            "transaction_jv":"N/A",
            "transaction_date":"2020-12-23 06:22:03",
            "transaction_type":"sale",
            "transaction_parent_id":"0",
            "transaction_subscription_id":"1670",
            "transaction_internal_subscription_id":"13670",
            "transaction_subscription_pay_number":"1",
            "transaction_last_4_card_digits":"1234",
            "original_id":"48111",
            "lead_country":"United States",
            "lead_country_code_2":"US",
            "lead_country_code_3":"USA",
            "lead_state":"New York",
            "lead_phone_country_code":"1",
            "lead_phone_number":"555-43556",
            "lead_address":"1st street",
            "lead_city":"New York",
            "lead_zip":"430022",
            "lead_ip":"127.0.0.1",
            "transaction_discount":"N/A",
            "transaction_tax":"N/A",
            "vendor_tracking_id_1":"N/A",
            "vendor_tracking_id_2":"N/A",
            "trial":"0",
            "trial_period":"N/A",
            "trial_amount":"N/A"
            "rebill_circle":"66",
            "installments":21,
            "payments_left":21,
            "shipping_first_name":"N/A",
            "shipping_last_name":"N/A",
            "shipping_address":"N/A",
            "shipping_city":"N/A",
            "shipping_zip":"N/A",
            "shipping_country":"N/A",
            "shipping_state":"N/A",
            "transaction_shipping":"0.00",
            "transaction_base_amount":"4.00",
            "vendor_tracking_link":"",
            "payment_processor_type":"Stripe"
        }
    }
}

Error Cases:

Type Number Message Cause
247 Transaction doesn’t exist
  • The transaction you are trying to find does not exist in our database.

An example of an error message:

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

Action: Retrieve payment transactions from lead

This will allow you to retrieve all payment transaction for a lead.

Type Parameters Values
POST cmd* retrieve_transactions_from_lead

* Required field
Here is an example:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'retrieve_transactions_from_lead'
    ]
]

 

Here are the results returned by the request:

Parameters Values
transaction_list String (JSON encoded array containing the transactions for the lead, empty array if no transactions)

 

JSON parameters Values
transaction_id integer A unique numeric identifier for the transaction id.
lead_id integer Id for the lead linked to the transaction.
lead_email string Email of the lead at the moment of the transaction.
transaction_type string The transaction type. Possible values: ‘sale’, ‘refund’, ‘failed’, ‘rebill’, ‘cancellation’, ‘chargeback’, ‘partial_refund’

Example of the returned JSON array:

{
    "retrieve_transactions_from_lead":{
        "transaction_list":[
            {
                "transaction_id":"48110",
                "lead_id":"4174086",
                "lead_email":"example@email.com",
                "transaction_type":"sale"
            },
            {
                "transaction_id":"48112",
                "lead_id":"4174086",
                "lead_email":"example@email.com",
                "transaction_type":"refund"
            },
        },
    }
}

Action: Retrieve recurring payment subscriptions from lead

This will allow retrieve all payment subscriptions within the refund period.

Type Parameters Values
POST cmd* retrieve_subscriptions_from_lead

* Required field
Here is an example:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'retrieve_subscriptions_from_lead'
    ]
]

 

Here are the results returned by the request:

Parameters Values
subscriptions_list String (JSON encoded array containing the payment subscriptions for the lead, empty array if no payment subscriptions)

 

JSON parameters Values
subscription_id integer A unique numeric identifier for the subscription id.
lead_id integer Id for the lead linked to the transaction.
lead_email string Email of the lead linked to the subscription.
subscription_status string The subscription status. Possible values: ‘Active’, ‘Terminated’, ‘Cancelled’, ‘Paused’

Example of the returned JSON array:

{
    "retrieve_subscriptions_from_lead":{
        "subscriptions_list":[
            {
                "subscription_id":"48110",
                "lead_id":"4174086",
                "lead_email":"example@email.com",
                "subscription_status":"Active"
            },
            {
                "subscription_id":"48112",
                "lead_id":"4174086",
                "lead_email":"example@email.com",
                "subscription_status":"Paused"
            },
        },
    }
}

Action: Retrieve all the tags in your account

This will allow you to get all the tags from the 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)

Example of the returned message:

{
    "status":"Success",
    "account_tags":[
        "Tag name 1",
        "Tag name 2"
    ]
}

Action: Retrieve all the lists in your account

This will allow you to get all the lists from the 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)

 
Example of the returned message:

{
    "status":"Success",
    "account_lists":[
        "List name 1",
        "List name 2"
    ]
}

Action: Retrieve all the sequences in your account

This will allow you to get all the sequences from the 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)

 
Example of the returned message:

{
    "status":"Success",
    "account_sequences":[
        "Sequence name 1",
        "Sequence name 2"
    ]
}

Action: Retrieve all the pages in your account

This will allow you to get all the pages from the 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)

 
Example of the returned message:

{
    "status":"Success",
    "account_pages":[
        "Page name 1",
        "Page name 2"
    ]
}

Action: Retrieve all the custom fields in your account

This will allow you to retrieve all custom fields set in your Kartra 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 there are no custom fields)

 

JSON parameters Values
field_id integer A unique identifier for the custom field.
field_identifier string The identifier string set when the field was created
field_type string The field type with possible values: ‘input_field’, ‘text_area’, ‘drop_down’, ‘radio_button’, ‘checkbox’.
field_value array Objects containing the option id and the option value. This applies only for multiple selection field types like ‘drop_down’, ‘radio_button’ and ‘checkbox’.

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"
    }
]

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.

All error or success messages are sent with HTTP response status code 200.

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": "'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": "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"
}

The specific actions success and error messages are detailed inside each of the action page itself.

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>";
}
?>

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;
}

?>

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.

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.

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;
}

?>

API limits

Our inbound API system has a hardcoded limit of 20 API calls per second per App. That means that 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!

© 2021 Kartra All Rights Reserved