Platform API

Overview

With the Agendize Platform API, you can manage several aspects of your Agendize account:
  • Create/modify buttons
  • Create/modify campaigns
  • Create/modify user accounts

Request

Authentication

To use the Data API you must authenticate yourself using your Agendize email and password. See the authentication documentation for details on the authentication mechanisms available and how to use them.

POST and GET Methods

You can use the Data API with both HTTP GET and HTTP POST methods. GETs can be used to read data from user accounts and POSTs can be used to add and modify data. Throughout this document, each API method is prefixed [GET] or [POST] depending on the type of use necessary.

Data API Methods

Checking Account Credit

URL Format:
[GET] https://www.agendize.com/api/1.0/data?key=XXXXXXX&scope=credit
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
scope Data scope Y credit
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	
		<entry:value name="amount" type="string" value="30.15"/>

Get Existing Account Details

URL Format:
[GET] https://www.agendize.com/api/1.0/data?key=XXXXXXX&scope=account
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
scope Data scope Y account
email Account email address Y
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	
		<entry:value name="email" type="string" value="john@acme.com"/>
		<entry:value name="firstname" type="string" value="John"/>
		<entry:value name="lastname" type="string" value="Smith"/>
		<entry:value name="token" type="string" value="5a5261cefe0033a5acdreef1575483fb9e1"/>

Get Button Details

URL Format:
[GET] https://www.agendize.com/api/1.0/data?key=XXXXXXX&scope=buttons&id=XXXXXXX
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
scope Data scope Y buttons
id Specific button ID N  
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	
		<entry:value name="button-id" type="string" value="XXXXXXX"/>
		<entry:value name="name" type="string" value="My Button"/>
		<entry:value name="icon" type="string" value="https://www.agendize.com/shared/img/sms.png"/>
		<entry:value name="type" type="string" value="contact"/>
		<entry:value name="media" type="string" value="sms"/>
		<entry:value name="company" type="string" value="My Company"/>
		<entry:value name="company-phone" type="string" value="+155578452"/>
		<entry:value name="company-email" type="string" value="info@mycompany.com"/>

Get Campaign Details

URL Format:
[GET] https://www.agendize.com/api/1.0/data?key=XXXXXXX&scope=campaigns&id=XXXXXXX
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
scope Data scope Y campaigns
id Specific campaign ID N  
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	
		<entry:value name="campaign-id" type="string" value="XXXXXXX"/>
		<entry:value name="name" type="string" value="My Campaign"/>
		<entry:value name="color" type="string" value="#FF0000"/>
		<entry:value name="budget" type="number" value="50"/>		
	
	
		<entry:value name="campaign-id" type="string" value="XXXXXXX"/>
		<entry:value name="name" type="string" value="My Second Campaign"/>
		<entry:value name="color" type="string" value="#000FF"/>
		<entry:value name="budget" type="number" value="25"/>

List Custom Analytics Reports

URL Format:
[GET] https://www.agendize.com/api/1.0/data?key=XXXXXXX&scope=reportList
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
scope Data scope Y reportList
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	
		<entry:value name="report-id" type="string" value="XXXXXXX"/>
		<entry:value name="name" type="string" value="My Report Name"/>				
	</entry>

Add / Modify a Campaign

URL Format:
[POST] https://www.agendize.com/api/1.0/data
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
xml XML content Y  
XML Content

To create or modify a campaign, use the XML node <campaign> with the following sub-nodes:

Name Description Required Values
id Campaign ID N (if modifying existing campaign only)
name Campaign name Y  
color Campaign color code N  
description Campaign description N  

Example

<?xml version="1.0" encoding="UTF-8"?>

	
		
			My Campaign
			#FF00FB
			My Campaign Description
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	200
Code Example
Java 
import java.net.*;
import java.io.*;
import javax.xml.parsers.*; 
import org.w3c.dom.*; 
import org.xml.sax.*; 

public class AddCampaign
{
	public static void main(String[] args) throws Exception
	{    
		URL url = new URL("http://www.agendize.com/api/1.0/data");
        
		String myUsername = "john.smith@acme.com";
		String myPassword = "password";
        
		String userPassword = myUsername + ":" + myPassword;
		String encoding = new sun.misc.BASE64Encoder().encode (userPassword.getBytes());

		URLConnection urlConnection = url.openConnection();
		urlConnection.setRequestProperty("Authorization", "Basic " + encoding);

		String xml = "< ?xml version=\"1.0\" encoding=\"UTF-8\"? >" +
				"My Campaign#FF00FB" + 
				"My Campaign Description" +	                 
				"";
		
		String params = URLEncoder.encode("key", "UTF-8") + "=" + URLEncoder.encode("ef85ab4589e5623844", "UTF-8");
		params += "&" + URLEncoder.encode("xml", "UTF-8") + "=" + URLEncoder.encode(xml, "UTF-8");
		
		OutputStreamWriter writer = new OutputStreamWriter(urlConnection.getOutputStream());
		writer.write(params);
		writer.flush();
		
		DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();			
		DocumentBuilder build = factory.newDocumentBuilder();
						
		Document doc = build.parse(urlConnection.getInputStream());
			
		NodeList nodeList = doc.getElementsByTagName("result");
			
		if (nodeList.getLength() > 0)
		{
			int code = Integer.parseInt(nodeList.item(0).getFirstChild().getNodeValue());
				
			System.out.println("return code: " + code);
		}
			
		writer.close();
	}
}
Get Code
PHP 
<?php
	// the xml data to send
	$chaineXML = 'Campagne0#EC50FFThis is a campaign uploaded by php';
	// Encode the parameters in order to build a suitable query
	$query_string = 'key=' . urlencode('3ac024abf8c72460764b965199f81808f4cb08') . '&xml=' . urlencode($chaineXML);		  
	
	// Set the authentication and the http request in POST method
	$context = stream_context_create(array( 
		'http' => array( 
		  'method'  => 'POST', 
		  'header'  => sprintf("Authorization: Basic %s\r\n", base64_encode('myusername:mypassword')). 
					   "Content-type: application/x-www-form-urlencoded\r\n", 
		  'content' => $query_string,
		  'timeout' => 5, 
		), 
	  )); 
	  
	// Make the connection
	$xmlResult = file_get_contents('http://localhost/selfservice/api/1.0/data', false, $context);
	// Retrieve AgendiZe response code obtained by searching in the parsed xml content
	$dom = new DomDocument();
	$dom->loadXML($xmlResult);
	$result = $dom->getElementsByTagName('result')->item(0);
	echo $result->nodeValue;
?>
Get Code
Python 
import urllib.request
import urllib.error
import urllib.parse
import xml.dom.minidom
from xml.dom.minidom import parse, parseString

key = "3ac024abf8c72460764b965199f81808f4cb08"
xml = "Campagne1#EC50FFThis is a campaign uploaded by python"
theurl = "http://localhost/selfservice/api/1.0/data"

# Build password manager by setting th parameter "realm" as default
password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()
# Encode the parameters in order to build a suitable query
queryEncoded = urllib.parse.urlencode({'key': key, 'xml': xml})
# Add a passwword to our password manager
password_mgr.add_password(None, theurl, "myusername", "mypassword")
# Create our HTML request manager by activing authentication
handler = urllib.request.HTTPBasicAuthHandler(password_mgr)
# Build the opener using our request manager
opener = urllib.request.build_opener(handler)
# Install the opener to be efficient
urllib.request.install_opener(opener)
req = urllib.request.Request(url=theurl,data=str.encode(queryEncoded))
# Make the connection 
handle = urllib.request.urlopen(req)
# Convert in string
chaineResultat = bytes.decode(handle.read())

# Retrieve AgendiZe response code obtained by searching in the parsed xml content
dom = parseString(chaineResultat)
element = dom.getElementsByTagName("result")[0]
print(element.childNodes[0].data)
Get Code
Ruby 
#!/usr/bin/env ruby
require 'net/http'
require 'uri'
require 'rexml/document'
require 'cgi'
include REXML

xmlCampaign = 'Campagne0#EC50FFThis is a campaign uploaded by ruby'
#Authenticate and send data to url by HTTP POST method
url = URI.parse('http://localhost/selfservice/api/1.0/data')
req = Net::HTTP::Post.new(url.path)
req.basic_auth("myusername","mypassword")
req.set_form_data({'key'=>'3ac024abf8c72460764b965199f81808f5dc19','xml'=>xmlCampaign})
res = Net::HTTP.new(url.host, url.port).start {|http| http.request(req) }
xmlContent =  res.body
#Analyzes the xml content and return the response code
doc = Document.new(xmlContent)
root = doc.root
puts root.elements[1].text
Get Code
C# 
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml;
using System.Net;
using System.IO;
using System.Web;

namespace AddCampaign
{
    class AddCampaign
    {
        static void Main(string[] args)
        {
            // Establish the request
            WebRequest webRequest = WebRequest.Create ("http://localhost/selfservice/api/1.0/data");
            // the xml data to send
            String xmlData = "Campagne0#EC50FFThis is a campaign uploaded by c#";
            // Set the authentication
            string authInfo = "myusername:mypassword";
            authInfo = Convert.ToBase64String(Encoding.Default.GetBytes(authInfo));
            webRequest.Headers["Authorization"] = "Basic " + authInfo;
            // Set the http request in POST method
            webRequest.ContentType = "application/x-www-form-urlencoded";
            webRequest.Method = "POST";
            // Build the query string
            String queryString = "key=3ac024abf8c72460764b965199f81808f4cb08&xml="+urlEncode(xmlData);
            byte[] bytes = Encoding.ASCII.GetBytes (queryString);
            Stream os = null;

            webRequest.ContentLength = bytes.Length;   //Count bytes to send
            os = webRequest.GetRequestStream();
            os.Write (bytes, 0, bytes.Length);         //Send it
 
            // get the response
            HttpWebResponse webResponse = (HttpWebResponse)webRequest.GetResponse();
            Encoding enc = Encoding.GetEncoding(1252);  // Windows default Code Page
            StreamReader responseStream = new StreamReader(webResponse.GetResponseStream(), enc);
            string xmlContent = responseStream.ReadToEnd();

            webResponse.Close();
            responseStream.Close();

            // Retrieve AgendiZe response code obtained by searching in the parsed xml content
            XmlDocument xmlDoc = new XmlDocument();
            xmlDoc.LoadXml(xmlContent);
            XmlNodeList nodes = xmlDoc.GetElementsByTagName("result");
            // Display the response code
            Console.WriteLine(nodes.Item(0).InnerText);
          
        }

        // Sometimes Visual Strudio can't get the HttpUtility class that's why we provide you our own urlEncode() method
        static String urlEncode(string toEncode)
        {
            char[] toEncodeCharacters = {'$','&','+',',','/',':',';','=','?','@',' ','\"','<','>','#','%'};
            String[] hexCodedChar = { "24", "26", "2B", "2C", "2F", "3A", "3B", "3D", "3F", "40" ,"20","22","3C","3E","23","25"};
            String encoded = "";
            for (int i = 0; i < toEncode.Length; i++)
            {
                char currentChar = toEncode.ElementAt<char>(i);
                int indice = -1;
                for(int j = 0; j < toEncodeCharacters.Length;j++) 
                    if (currentChar == toEncodeCharacters.ElementAt<char>(j))
                        indice = j;
                if (indice == -1)
                    encoded += currentChar;
                else
                    encoded += "%" + hexCodedChar.ElementAt<string>(indice);
            }
            return encoded;
        }
    }
}
Get Code
C++/CLI 
#include "stdafx.h"
using namespace System::Xml;
using namespace System::Text;
using namespace System;

String^ urlEncode(String^ toEncode)
{
	cli::array<wchar_t^>^ toEncodeCharacters = {L'$', L'&', L'+', L',', L'/', L':', L';', L'=', L'?', L'@', L' ', L'\"', L'<', L'>', L'#', L'%'};
    cli::array<String^>^ hexCodedChar = { "24", "26", "2B", "2C", "2F", "3A", "3B", "3D", "3F", "40", "20", "22", "3C", "3E", "23", "25"};

	String ^ encoded;

	for (int i = 0; i < toEncode->Length; i++)
	{
		wchar_t^ currentChar = toEncode[i];
		int indice = -1;
		for (int j = 0; j < toEncodeCharacters->Length; j++)
			if (currentChar->Equals(toEncodeCharacters[j])) // Detect the reserved character...
				indice = j;
		if (indice == -1)
			encoded += currentChar;
		else
			encoded += "%" + hexCodedChar[indice]; // ... and replace it by its hexadecimal code
	}

	return encoded;
}

int main(array<System::String ^> ^args)
{
	String^ xmlCampaign = "Campagne0#EC50FFThis is a campaign uploaded by c++";
	
	//authentication
	System::Net::NetworkCredential^ myCred = gcnew System::Net::NetworkCredential("myusername","mypassword");
	System::Net::CredentialCache^ myCache = gcnew System::Net::CredentialCache;
	myCache->Add( gcnew Uri( "http://localhost/selfservice/api/1.0/data" ), "Basic", myCred );

	// Create a request for the URL.   
	// Set the 'Method' property of the 'Webrequest' to 'POST'.
	System::Net::HttpWebRequest ^myHttpWebRequest = safe_cast<System::Net::HttpWebRequest^>(System::Net::HttpWebRequest::Create("http://localhost/selfservice/api/1.0/data"));
	myHttpWebRequest->Credentials = myCache;
	myHttpWebRequest->Method = "POST";
	
	String^ queryString = String::Concat( "key=", "3ac024abf8c72460764b965199f81808f4cb08", "&xml=",urlEncode(xmlCampaign) );
	ASCIIEncoding^ encoding = gcnew ASCIIEncoding;
	array<Byte>^ queryByte = encoding->GetBytes( queryString );

	// Set the content type of the data being posted.
	myHttpWebRequest->ContentType = "application/x-www-form-urlencoded";

	// Set the content length of the String* being posted.
	myHttpWebRequest->ContentLength = queryByte->Length;

	System::IO::Stream^ newStream = myHttpWebRequest->GetRequestStream();

	newStream->Write( queryByte, 0, queryByte->Length );
	
	System::Net::WebResponse ^_WebResponse = myHttpWebRequest->GetResponse();
	// Open data stream:
	System::IO::Stream ^_WebStream = _WebResponse->GetResponseStream();
	// Read the data stream
	System::IO::StreamReader ^sreader = gcnew System::IO::StreamReader(_WebStream);
	String ^xmlContent = sreader->ReadToEnd();
	
	// Cleanup
	_WebStream->Close();
	_WebResponse->Close();

	// Close the Stream Object*.
	newStream->Close();
    #Analyzes the xml content and return the response code
	XmlDocument ^ xmlDoc = gcnew XmlDocument();
	xmlDoc->LoadXml(xmlContent);
	XmlNodeList ^ listeNoeud = xmlDoc->GetElementsByTagName("result");
    Console::WriteLine(listeNoeud->Item(0)->InnerText);
    return 0;
}
Get Code
Visual Basic .NET 
Imports System.Net
Imports System.IO
Imports WinHttp

Module Module1

    Sub Main()

        Dim xmlCampaign = "Campagne0#EC50FFThis is a second campaign uploaded by vb.net"

        ' Assemble an HTTP request.
        Dim WinHttpReq = New WinHttpRequest
        WinHttpReq.Open("POST", "http://localhost/selfservice/api/1.0/data", False)
        ' Set the user name and password.
        WinHttpReq.SetCredentials("myusername", "mypassword", 0)
        ' Send the HTTP Request.
        WinHttpReq.setRequestHeader("Content-Type", "application/x-www-form-urlencoded")
        WinHttpReq.Send("key=3ac024abf8c72460764b965199f81808f4cb08&xml=" & urlEncode(xmlCampaign))
        ' Return the response.
        Dim xmlContent = WinHttpReq.ResponseText
        Dim domDoc As Xml.XmlDocument
        domDoc = New Xml.XmlDocument
        domDoc.LoadXml(xmlContent)
        Console.WriteLine(domDoc.GetElementsByTagName("result").Item(0).InnerText)

    End Sub

    Public Function urlEncode(ByVal toEncode As String)
        Dim encoded = ""
        Dim charArray(16) As String
        Dim charArray2(16) As String
        Dim temp As String
        Dim temp2 As String
        temp = "$.&.+.,./.:.;.=.?.@. ."".<.>.#.%"
        temp2 = "24,26,2B,2C,2F,3A,3B,3D,3F,40,20,22,3C,3E,23,25"
        charArray = Split(temp, ".")
        charArray2 = Split(temp2, ",")
        For i = 0 To toEncode.Length - 1
            Dim currentChar = toEncode(i)
            Dim indice = -1
            For j = LBound(charArray) To UBound(charArray)
                If currentChar = charArray(j) Then
                    indice = j
                End If
            Next
            If indice = -1 Then
                encoded = encoded & currentChar
            Else
                encoded = encoded & "%" & charArray2(indice)
            End If
        Next
        Return encoded
    End Function
End Module
Get Code

Create a New User Account

URL Format:
[POST] https://www.agendize.com/api/1.0/data
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
xml XML content Y  
XML Content

To create a new account, use the XML node <account> with the following attributes:

Name Description Required Values
email Email address Y  
password Password Y  
firstname First name Y  
lastname Last name Y  

Example

<?xml version="1.0" encoding="UTF-8"?>

	<account email="me@acne.com" password="agendize" firstname="John" lastname="Smith"/>
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	200
	A15489965BF8454C

Create or Modify a Click to Call Button

URL Format:
[POST] https://www.agendize.com/api/1.0/data
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
xml XML content Y  
XML Content

To create or modify a button, use the XML node <button> with the following attributes:

Name Description Required Values
id Button ID N (if modifying existing button only)
media Click to Call method Y call

The button details should be defined in the following sub-nodes:

Name Description Required Values
name Button name Y  
phone Phone number Y In international format (+XXXXXXXXXX)
style.color.background Box background color N HTML Code color (ex: #F00)
style.color.border Box border color N HTML Code color (ex: #F00)
style.color.panel.title Box title color N HTML Code color (ex: #F00)
style.color.panel.border Box panel box color N HTML Code color (ex: #F00)

Example

<?xml version="1.0" encoding="UTF-8"?>
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	200

Create or Modify a Click to Chat Button

URL Format:
[POST] https://www.agendize.com/api/1.0/data
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
xml XML content Y  
XML Content

To create or modify a button, use the XML node <button> with the following attributes:

Name Description Required Values
id Button ID N (if modifying existing button only)
media Click to Chat method Y chat

The button details should be defined in the following sub-nodes:

Name Description Required Values
name Button name Y  
style.color.background Box background color N HTML Code color (ex: #F00)
style.color.border Box border color N HTML Code color (ex: #F00)
style.color.panel.title Box title color N HTML Code color (ex: #F00)
style.color.panel.border Box panel box color N HTML Code color (ex: #F00)

Example

<?xml version="1.0" encoding="UTF-8"?>
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	200

Create or Modify a Scheduling Button

URL Format:
[POST] https://www.agendize.com/api/1.0/data
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
xml XML content Y  
XML Content

To create or modify a button, use the XML node <button> with the following attributes:

Name Description Required Values
id Button ID N (if modifying existing button only)
media Scheduling method Y scheduling

The button details should be defined in the following sub-nodes:

Name Description Required Values
name Button name Y  
style.color.background Box background color N HTML Code color (ex: #F00)
style.color.border Box border color N HTML Code color (ex: #F00)
style.color.panel.title Box title color N HTML Code color (ex: #F00)
style.color.panel.border Box panel box color N HTML Code color (ex: #F00)

Example

<?xml version="1.0" encoding="UTF-8"?>
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	200

Create or Modify a SMS, Share, Address Book, Calendar, Email, Desktop, or Instant Messenger Button

URL Format:
[POST] https://www.agendize.com/api/1.0/data
Parameters:
Name Description Required Values
key API key Y No API key? Get one here
xml XML content Y  
XML Content

To create or modify a button, use the XML node <button> with the following attributes:

Name Description Required Values
id Button ID N  
media Action method Y sms, online, pim, email, desktop, messengers
type Data type Y contact or event or none

The button details should be defined in the following sub-nodes:

For a Contact boutton:

Name Description Required Values
name Button name Y  
description Button description N  
firstname Contact first name N  
lastname Contact last name N  
company.name Contact company name N  
company.address Contact company address N  
company.phone Contact company phone number N  
company.fax Contact company fax number N  
company.email Contact company email/td> N  
company.city Contact company city N  
company.state Contact company state N  
company.zip Contact company zip code N  
company.country Contact company country N  
job.title Contact job title N  
website Contact website N  
company.address Contact personal address N  
personal.phone Contact personal phone number N  
personal.email Contact personal email/td> N  
personal.city Contact personal city N  
personal.state Contact personal state N  
personal.zip Contact personal zip code N  

For a "None" boutton (button width only a name and a description, for sharing your Web Page URL):

Name Description Required Values
name Button name Y  
description Button description N  

Example

<?xml version="1.0" encoding="UTF-8"?>
Response

Example

<?xml version="1.0" encoding="UTF-8"?>

	200