Kartra Documentation Technical Documentation for Kartra

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!

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.

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.

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 a couple business days up to two weeks at most.

*Please Note: You cannot casually turn on live mode to test your content with live emails. When you switch to live mode your content/application will be reviewed by our review team and it will need to be complete. Otherwise you will be reset back to test mode until your content is done.

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.

API Inbound 01

 

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.

*Please Note: The App is just the conductor that executes an action on behalf of the App User.

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

Before you begin

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.

*Please note: Leads input via our API will not have GDPR terms agreed to under any scenario. This means leads will have restricted communication based on your GDPR settings. Only if they agreed to GDPR terms via a Kartra based opt-in form or you complete a mass import of leads where you confirm they have agreed to GDPR can you communicate normally with them. This is important to note that you cannot avoid GDPR consent via this feature and may still want to use a Kartra based opt-in form to ensure the consent is obtained.

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.

*Please note: In some rare situations a third party will ask you to submit a API request on their behalf. This is not how our API is intended to be used and you will need to inform that third party that you cannot submit the request on their behalf. Feel free to reference this documentation in any communication you have with a third party.

4. Just to be clear, you cannot submit an API request on behalf of a third party. If you are a user of a third party software you wish to integrate with Kartra, then you will need to submit a feature request to the third party or Kartra’s support to create such an integration.

*Please note: You may still be able to use our API as long as your own code/content is the primary user of the API (and not the third party). Lets say you want to have a third party application interact with Kartra through your own external software, you can have your external software get approved for API use and then be a middle man in the communication process.

 

I Just submitted my application and I was Denied because I cannot submit a third party application:

When you utilize our API, this feature expects you to be the developer of the software being integrated with Kartra. You cannot just be a user of a third party software. If you want a third party software to integrate with Kartra you can submit it as a feature request with the support team of either software (preferably the third party), but you cannot integrate that third party with Kartra on their behalf.

*Please note: Feature requests are not a quick process and can often take months or years to implement, if implemented at all. Do not expect a quick turn around when requesting a new feature.

The only thing you can do from your end is to develop your own software that acts as a middle man in the process. Since you would be the developer of that application you can link that to Kartra and you can then link your own application to the third party application you want to link to Kartra.

(Kartra) -> (Your Software) -> (Third Party you want to link to Kartra)

*Please note: Whether or not this can work will depend on your ability to link to the third party application via your own software. We can provide support on how to link your application to Kartra, but the integration of your external software to a third party is strictly between you and that third party.

© 2024 Kartra All Rights Reserved