Developers > API on Kartra's side), which itself requires
* an active Kartra subscription to create and get approved. This plugin
* does not ship with its own pre-approved app_id — instead, each user with
* an active Kartra subscription registers their OWN app in their OWN
* account, gets it approved by Kartra, and enters the resulting App ID
* here alongside their API Key/Password. This avoids depending on a
* single shared app_id owned by the plugin author (which would require the
* author to maintain an active Kartra subscription indefinitely just to
* keep everyone else's integration working).
*
* Confirmed against Kartra's current API docs (support.kartra.com — see
* "Connecting to the API", "Connecting a custom App with Kartra API",
* "Lead: Searching, Creating, Editing", "Action: Subscribe a lead to a
* list", "Action: Retrieve all the lists in your account", "PHP sample:
* creating a lead"):
* - Endpoint is still POST https://app.kartra.com/api, no OAuth/versioning.
* - `retrieve_account_lists`, `create_lead`, `subscribe_lead_to_list`
* (param `list_name` — a name string, not a numeric id) are current.
* - The `lead` payload key is a flat object, e.g. `{"email":"...", ...}` —
* NOT an array of one object. The previous (pre-2026) version of this
* file sent `'lead' => array( array( 'email' => ... ) )`, i.e. an
* array-wrapped lead, which doesn't match the documented shape.
* - `custom_fields` is a real, separate array of
* `{"field_identifier":"...", "field_value":"..."}` pairs — see the Pro
* tier for that.
* - New apps start in "Test Mode", which Kartra's docs say is "fully
* functional for the developer" — since each user here registers their
* own app against their own account, Test Mode alone may already be
* enough without waiting on Kartra's live-review queue. Worth trying
* before submitting for full approval.
*
* @link https://support.kartra.com/support/solutions/articles/153000169502-connecting-to-the-api
* @link https://support.kartra.com/support/solutions/articles/153000169500-lead-searching-creating-editing
*/
add_filter( 'adfoin_action_providers', 'adfoin_kartra_actions', 10, 1 );
function adfoin_kartra_actions( $actions ) {
$actions['kartra'] = array(
'title' => __( 'Kartra', 'advanced-form-integration' ),
'tasks' => array(
'subscribe' => __( 'Add Lead To List', 'advanced-form-integration' ),
),
);
return $actions;
}
add_filter( 'adfoin_settings_tabs', 'adfoin_kartra_settings_tab', 10, 1 );
function adfoin_kartra_settings_tab( $providers ) {
$providers['kartra'] = __( 'Kartra', 'advanced-form-integration' );
return $providers;
}
add_action( 'adfoin_settings_view', 'adfoin_kartra_settings_view', 10, 1 );
function adfoin_kartra_settings_view( $current_tab ) {
if ( 'kartra' !== $current_tab ) {
return;
}
if ( ! class_exists( 'ADFOIN_Account_Manager' ) ) {
require_once plugin_dir_path( __FILE__ ) . '../../includes/class-adfoin-account-manager.php';
}
$fields = array(
array(
'name' => 'appId',
'label' => __( 'App ID', 'advanced-form-integration' ),
'type' => 'text',
'required' => true,
'show_in_table' => true,
),
array(
'name' => 'apiKey',
'label' => __( 'API Key', 'advanced-form-integration' ),
'type' => 'text',
'required' => true,
'mask' => true,
'show_in_table' => true,
),
array(
'name' => 'apiPassword',
'label' => __( 'API Password', 'advanced-form-integration' ),
'type' => 'text',
'required' => true,
'mask' => true,
),
);
$instructions = sprintf(
'
%s
%s
%s
',
sprintf(
/* translators: %s — Kartra developer API link. */
esc_html__( 'Requires an active Kartra subscription. Go to %s and register a new app of your own — this issues you an App ID. New apps start in "Test Mode," which Kartra says is fully functional for the developer\'s own account, so try it as-is first; if a call fails as unauthorized, submit the app for Kartra\'s live review/approval from the same page.', 'advanced-form-integration' ),
'My Integrations » Developers » API'
),
sprintf(
/* translators: %s — Kartra API key link. */
esc_html__( 'Get your API Key and API Password from %s.', 'advanced-form-integration' ),
'My Integrations » Developers » API'
),
esc_html__( 'Paste the App ID, API Key, and API Password below and save — then pick a Kartra list when mapping fields on your form action.', 'advanced-form-integration' )
);
ADFOIN_Account_Manager::render_settings_view( 'kartra', __( 'Kartra', 'advanced-form-integration' ), $fields, $instructions );
}
add_action( 'wp_ajax_adfoin_get_kartra_credentials', 'adfoin_get_kartra_credentials', 10, 0 );
function adfoin_get_kartra_credentials() {
if ( ! class_exists( 'ADFOIN_Account_Manager' ) ) {
require_once plugin_dir_path( __FILE__ ) . '../../includes/class-adfoin-account-manager.php';
}
ADFOIN_Account_Manager::ajax_get_credentials_list( 'kartra' );
}
add_action( 'wp_ajax_adfoin_save_kartra_credentials', 'adfoin_save_kartra_credentials', 10, 0 );
function adfoin_save_kartra_credentials() {
if ( ! class_exists( 'ADFOIN_Account_Manager' ) ) {
require_once plugin_dir_path( __FILE__ ) . '../../includes/class-adfoin-account-manager.php';
}
ADFOIN_Account_Manager::ajax_save_credentials( 'kartra', array( 'appId', 'apiKey', 'apiPassword' ) );
}
function adfoin_kartra_credentials_list() {
foreach ( adfoin_read_credentials( 'kartra' ) as $option ) {
printf( '', esc_attr( $option['id'] ), esc_html( $option['title'] ) );
}
}
add_action( 'adfoin_action_fields', 'adfoin_kartra_action_fields' );
function adfoin_kartra_action_fields() {
?>
'retrieve_account_lists' ),
), $cred_id );
if ( is_wp_error( $response ) ) {
wp_send_json_success( array() );
}
$body = json_decode( wp_remote_retrieve_body( $response ), true );
$lists = ( is_array( $body ) && ! empty( $body['account_lists'] ) && is_array( $body['account_lists'] ) )
? array_values( $body['account_lists'] )
: array();
wp_send_json_success( $lists );
}
add_action( 'wp_ajax_adfoin_get_kartra_fields', 'adfoin_get_kartra_fields' );
function adfoin_get_kartra_fields() {
adfoin_verify_nonce();
$fields = array(
array( 'key' => 'email', 'value' => __( 'Email', 'advanced-form-integration' ), 'required' => true ),
array( 'key' => 'firstName', 'value' => __( 'First Name', 'advanced-form-integration' ) ),
array( 'key' => 'middleName', 'value' => __( 'Middle Name', 'advanced-form-integration' ) ),
array( 'key' => 'lastName', 'value' => __( 'Last Name', 'advanced-form-integration' ) ),
array( 'key' => 'lastName2', 'value' => __( 'Last Name 2', 'advanced-form-integration' ) ),
array( 'key' => 'phoneCountryCode', 'value' => __( 'Phone Country Code', 'advanced-form-integration' ) ),
array( 'key' => 'phone', 'value' => __( 'Phone', 'advanced-form-integration' ) ),
array( 'key' => 'ip', 'value' => __( 'IP', 'advanced-form-integration' ) ),
array( 'key' => 'address', 'value' => __( 'Address', 'advanced-form-integration' ) ),
array( 'key' => 'zip', 'value' => __( 'ZIP', 'advanced-form-integration' ) ),
array( 'key' => 'city', 'value' => __( 'City', 'advanced-form-integration' ) ),
array( 'key' => 'state', 'value' => __( 'State', 'advanced-form-integration' ) ),
array( 'key' => 'country', 'value' => __( 'Country', 'advanced-form-integration' ) ),
array( 'key' => 'company', 'value' => __( 'Company', 'advanced-form-integration' ) ),
array( 'key' => 'website', 'value' => __( 'Website', 'advanced-form-integration' ) ),
array( 'key' => 'facebook', 'value' => __( 'Facebook', 'advanced-form-integration' ) ),
array( 'key' => 'twitter', 'value' => __( 'Twitter', 'advanced-form-integration' ) ),
array( 'key' => 'linkedin', 'value' => __( 'LinkedIn', 'advanced-form-integration' ) ),
);
wp_send_json_success( $fields );
}
/**
* Build the flat `lead` object from parsed field values. Shared with the
* Pro tier so both stay in sync with the confirmed API schema.
*/
function adfoin_kartra_build_lead( $fields ) {
$map = array(
'email' => 'email',
'firstName' => 'first_name',
'middleName' => 'middle_name',
'lastName' => 'last_name',
'lastName2' => 'last_name2',
'phoneCountryCode' => 'phone_country_code',
'phone' => 'phone',
'ip' => 'ip',
'address' => 'address',
'zip' => 'zip',
'city' => 'city',
'state' => 'state',
'country' => 'country',
'company' => 'company',
'website' => 'website',
'facebook' => 'facebook',
'twitter' => 'twitter',
'linkedin' => 'linkedin',
);
$lead = array();
foreach ( $map as $local => $remote ) {
if ( ! empty( $fields[ $local ] ) ) {
$lead[ $remote ] = $fields[ $local ];
}
}
return $lead;
}
add_action( 'adfoin_kartra_job_queue', 'adfoin_kartra_job_queue', 10, 1 );
function adfoin_kartra_job_queue( $data ) {
adfoin_kartra_send_data( $data['record'], $data['posted_data'] );
}
function adfoin_kartra_send_data( $record, $posted_data ) {
if ( 'subscribe' !== ( $record['task'] ?? '' ) ) {
return;
}
$record_data = json_decode( $record['data'], true );
if ( adfoin_check_conditional_logic( $record_data['action_data']['cl'] ?? array(), $posted_data ) ) {
return;
}
$field_data = isset( $record_data['field_data'] ) ? $record_data['field_data'] : array();
$cred_id = isset( $field_data['credId'] ) ? $field_data['credId'] : '';
$list_id = isset( $field_data['listId'] ) ? trim( (string) $field_data['listId'] ) : '';
if ( ! $cred_id || ! $list_id ) {
return;
}
$fields = array();
foreach ( $field_data as $key => $value ) {
if ( in_array( $key, array( 'credId', 'listId' ), true ) ) {
continue;
}
$parsed = adfoin_get_parsed_values( $value, $posted_data );
if ( '' !== $parsed && null !== $parsed ) {
$fields[ $key ] = $parsed;
}
}
$lead = adfoin_kartra_build_lead( $fields );
if ( empty( $lead['email'] ) ) {
return;
}
$actions = array(
array( 'cmd' => 'create_lead' ),
array( 'cmd' => 'subscribe_lead_to_list', 'list_name' => $list_id ),
);
adfoin_kartra_request( $actions, $cred_id, $lead, $record );
}
if ( ! function_exists( 'adfoin_kartra_request' ) ) :
/**
* Call the Kartra API. Every call sends `app_id`/`api_key`/`api_password`
* both as URL query params (the shape this integration has used since it
* was first built, confirmed still working) and inside the JSON body
* (the shape Kartra's own docs describe — "every API call must include an
* array with the following parameters") so the request succeeds regardless
* of which one Kartra's endpoint actually reads.
*
* @param array $actions Kartra "actions" cmd array.
* @param string $cred_id Saved credential id.
* @param array $lead Optional flat lead object (NOT array-wrapped).
* @param array $record Submission record for logging.
*
* @return array|WP_Error
*/
function adfoin_kartra_request( $actions, $cred_id, $lead = array(), $record = array() ) {
$credentials = adfoin_get_credentials_by_id( 'kartra', $cred_id );
if ( ! is_array( $credentials ) || empty( $credentials['appId'] ) || empty( $credentials['apiKey'] ) || empty( $credentials['apiPassword'] ) ) {
return new WP_Error( 'kartra_missing_credentials', __( 'Kartra App ID / API Key / API Password not configured.', 'advanced-form-integration' ) );
}
$app_id = $credentials['appId'];
$api_key = $credentials['apiKey'];
$api_password = $credentials['apiPassword'];
$body = array(
'app_id' => $app_id,
'api_key' => $api_key,
'api_password' => $api_password,
'actions' => $actions,
);
if ( ! empty( $lead ) ) {
$body['lead'] = $lead;
}
$url = add_query_arg( array(
'app_id' => $app_id,
'api_key' => $api_key,
'api_password' => $api_password,
), 'https://app.kartra.com/api' );
$args = array(
'timeout' => 30,
'method' => 'POST',
'headers' => array( 'Content-Type' => 'application/json' ),
'body' => wp_json_encode( $body ),
);
$response = wp_remote_post( esc_url_raw( $url ), $args );
if ( $record ) {
adfoin_add_to_log( $response, $url, $args, $record );
}
return $response;
}
endif;