Actions: Communications – Kartra Documentation

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 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 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: Unsubscribe lead from a sequence

Unsubscribes lead to a specified sequence. Note that…

The sequence must be already created in your account (https://app.kartra.com/communication/sequences).
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 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: 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: 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: Unassign tag from a lead

Deletes a tag from the specified lead. Note that…

The tag must have been already created from within your Kartra account (https://app.kartra.com/communication/tags).
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: 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: 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: 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"
}