Before You Start
The ActiveTrail API is designed for developers, engineers, or anyone else who’s comfortable creating custom-coded solutions or integrating with RESTful APIs. The REST architectural style is an integral part of RESTful. If you’d like to learn more about REST before using the API, check out the introduction to representational state transfer (REST) .
Resources
Resources are typically nouns like ‘subscribers’ or ‘campaigns’ that you take actions on using supported HTTP verbs.
Each resource is typically separated into a resource/{id} format, with subresources following the same pattern. For example, if you’re looking for information about a group, make a GET request to https://webapi.mymarketing.co.il/api/groups. To access an individual group, such as group with id 1234, make a GET request to
https://webapi.mymarketing.co.il/api/groups/1234.
Authentication
There is a basic authentication method for the api just add a header to the request called authorization and as the value put the token that you got from the web interface (go to settings -> API apps) and create a new Token. You can restrict it to specific IPs and give it an expiry date. You can create as many tokens as you need.
HTTP Methods
The ActiveTrail API supports 4 HTTP methods for interacting with resources:
- GET Make a GET request to retrieve data. GET requests will never update or change your data because they’re safe and idempotent .
- POST Use a POST request to create new resources. For example, make a POST request to a collection endpoint (like /groups) where the body of your request contains the JSON structure of the new group.
- PUT Use a PUT request to update a resource. This is most useful for syncing subscriber data.
- DELETE Make a DELETE request to remove a resource by giving the entity’s id.
JSON
The ActiveTrail API only supports JSON & XML body. The API Reference includes complete examples for the data format.
Parameters
There are 4 main categories of parameters for each endpoint in the ActiveTrail API: path, query string, request body, and response body. The API Reference includes a list of all available parameters for each possible request, but these sections offer an overview of the 4 main categories and their subcategories.
Path parameters
In an API URL, we include resource names and unique identifiers to help you figure out how to structure your requests. Resource names are immutable, but resource identifiers are required, so you need to replace them with real values from your ActiveTrail account. Let’s look at an example:
https://webapi.mymarketing.co.il/groups/{group_id}/members/{email}
In that URL, there is 1 primary resource, group, and 1 subresource: members. There are also 2 different path parameters that you need to replace with real values from your ActiveTrail account:group_id and email.
Query string parameters
We use query string parameters for filtering, pagination, and partial responses in the ActiveTrail API. The format for query string parameters is the full resource URL followed by a question mark, and the optional parameters:
https://webapi.mymarketing.co.il/api/groups?Email={Email}&Page={Page}&Limit={Limit}
Pagination
Paginate your API requests to limit response results and make them easier to work with. We use page and limit in the URL query string to paginate because it provides greater control over how you view your data. page defaults to 0, so if you use page=1, you’ll miss the first element in the dataset. limit defaults to 100 and you cannot have a limit greater than 100. For example, this URL includes query string parameters for pagination:
https://webapi.mymarketing.co.il/api/groups? Page=0&Limit=100
This is the same as sending without any parameters :
https://webapi.mymarketing.co.il/api/groups
to get the next page make another request:
https://webapi.mymarketing.co.il/api/groups? Page=1&Limit=100
Request body parameters
For PUT, and POST requests, you may need to include a request body in JSON format. The API Reference shows you all the available request parameters for each endpoint, including required fields.
Response body parameters
GET and POST API call response includes headers and an optional json-formatted body.
Note
PUT and DELETE requests return only headers without a JSON body.
The API Reference includes all possible response body parameters.
Code Examples
Throughout the ActiveTrail API documentation, we include code examples so you know how to format your requests, and what kind of data to expect in return.
C# :
contact endpoint:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Net.Http;
using System.Net.Http.Headers;
namespace ActiveTrail.API.Client
{
class Contact
{
public int id { get; set; }
public string first_name { get; set; }
public string last_name { get; set; }
public string email { get; set; }
public string anniversary { get; set; }
public string birthday { get; set; }
public string city { get; set; }
public string encryptedext1 { get; set; }
public string encryptedext2 { get; set; }
public string encryptedext3 { get; set; }
public string encryptedext4 { get; set; }
public string ext1 { get; set; }
public string ext2 { get; set; }
public string ext3 { get; set; }
public string ext4 { get; set; }
public string ext5 { get; set; }
public string ext6 { get; set; }
public string fax { get; set; }
public string phone1 { get; set; }
public string phone2 { get; set; }
public string street { get; set; }
public string zip_code { get; set; }
public bool is_do_not_mail { get; set; }
}
partial class Program
{
static void Main(string[] args)
{
RunAsync().Wait();
}
static async Task RunAsync()
{
using (var client = new HttpClient())
{
client.BaseAddress = new Uri("http://webapi.mymarketing.co.il/");
client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Add("Authorization", "[API Token]");
// HTTP GET
HttpResponseMessage response = await client.GetAsync("api/contacts/{id}");
if (response.IsSuccessStatusCode)
{
Contact product = await response.Content.ReadAsAsync<contact>();
Console.WriteLine("{0}\t{1}\t{2}", product.first_name, product.last_name, product.email);
}
// HTTP POST
var gizmo = new Contact() { first_name = "First Name", last_name = "Last Name", email = "agent@example.com" };
response = await client.PostAsJsonAsync("api/contacts", gizmo);
if (response.IsSuccessStatusCode)
{
//Uri gizmoUrl = response.Headers.Location;
// HTTP PUT
gizmo.last_name = "sdsd"; // Update price
response = await client.PutAsJsonAsync("api/contacts/202950471", gizmo);
if (response.StatusCode == System.Net.HttpStatusCode.NoContent)
{
Console.WriteLine("{0}\t{1}\t{2}", gizmo.first_name, gizmo.last_name, gizmo.email);
}
// HTTP DELETE
response = await client.DeleteAsync("api/contacts/{id}");
}
}
}
}
}
PHP: Add contact to a given group :
<?php //Add contact to a given group //Put your group id here $groupId = "your group id; //Your authorization key (eg. 0x......) $authId = 'token'; $url = 'http://webapi.mymarketing.co.il/api/groups/' . $groupId . '/members'; //open connection $ch = curl_init(); //Preprate headers $headr = array(); $headr[] = 'Content-type: application/json'; $headr[] = 'Authorization: ' . $authId; //Prepare POST body $params =array( 'email''mail@mail', 'first_name' => "First Name", 'last_name' => "Last Name", ); //set the url, number of POST vars, POST data curl_setopt($ch,CURLOPT_URL, $url); curl_setopt($ch,CURLOPT_POSTFIELDS, json_encode($params)); curl_setopt($ch, CURLOPT_HTTPHEADER, $headr); //execute post $result = curl_exec($ch); //close connection curl_close($ch); ?>
How to make REST calls in PHP :
Example of calling GET request :
<?php
//next example will receive all messages for specific conversation
$service_url = 'http://example.com/api/conversations/[CONV_CODE]/messages&apikey=[API_KEY]';
$curl = curl_init($service_url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$curl_response = curl_exec($curl);
if ($curl_response === false) {
$info = curl_getinfo($curl);
curl_close($curl);
die('error occurred during curl exec. Additional info: ' . var_export($info));
}
curl_close($curl);
$decoded = json_decode($curl_response);
if (isset($decoded->response->status) && $decoded->response->status == 'ERROR') {
die('error occurred: ' . $decoded->response->errormessage);
}
echo 'response ok!';
var_export($decoded->response);
?>
Example of calling POST request :
<?php //Add contact to a given group //Put your group id here $groupId = 1; //Your authorization key (eg. 0x......) $authId = ''; $url = 'http://webapi.mymarketing.co.il/api/groups/' . $groupId . '/members'; //open connection $ch = curl_init(); //Prepare headers $headr = array(); $headr[] = 'Content-type: application/json'; $headr[] = 'Authorization: ' . $authId; //Prepare POST body $params =array( 'email'=>'agent@example.com', 'first_name' => "First Name", 'last_name' => "Last Name", ); //set the url, number of POST vars, POST data curl_setopt($ch,CURLOPT_URL, $url); curl_setopt($ch,CURLOPT_POSTFIELDS, json_encode($params)); curl_setopt($ch, CURLOPT_HTTPHEADER, $headr); //execute post $result = curl_exec($ch); //close connection curl_close($ch); ?>
Example of calling PUT request :
//next example will change status of specific conversation to resolve
$service_url = 'http://example.com/api/conversations/cid123/status';
$ch = curl_init($service_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
$data = array("status" => 'R');
curl_setopt($ch, CURLOPT_POSTFIELDS,http_build_query($data));
$response = curl_exec($ch);
if ($response === false) {
$info = curl_getinfo($ch);
curl_close($ch);
die('error occurred during curl exec. Additional info: ' . var_export($info));
}
curl_close($ch);
$decoded = json_decode($response);
if (isset($decoded->response->status) && $decoded->response->status == 'ERROR') {
die('error occurred: ' . $decoded->response->errormessage);
}
echo 'response ok!';
var_export($decoded->response);
Example of calling DELETE request :
$service_url = 'http://example.com/api/conversations/[CONVERSATION_ID]';
$ch = curl_init($service_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$curl_post_data = array(
'note' => 'this is spam!',
'useridentifier' => 'agent@example.com',
'apikey' => 'key001'
);
curl_setopt($curl, CURLOPT_POSTFIELDS, $curl_post_data);
$response = curl_exec($ch);
if ($curl_response === false) {
$info = curl_getinfo($curl);
curl_close($curl);
die('error occurred during curl exec. Additional info: ' . var_export($info));
}
curl_close($curl);
$decoded = json_decode($curl_response);
if (isset($decoded->response->status) && $decoded->response->status == 'ERROR') {
die('error occurred: ' . $decoded->response->errormessage);
}
echo 'response ok!';
var_export($decoded->response);
