API - Interface for developers

CleverCampain's REST API let's developers quickly build applications which enable access to the data in your CleverCampaign account via HTTP and XML/JSON. This allows you to integrate online and desktop applications (3rd party systems) seamlessly into your CleverCampaign account. Almost every object in CleverCampaign (whether it is a contact, newsletter, etc) can be manipulated using the API.

REST Basics

When you make a request to the CleverCampain's REST API you need to address each ressource by a unique URI. The operations which can be done with the resources can be defined using the HTTP verbs. Our API uses all four REST commands - GET, POST, PUT, DELETE.

  • GET: read resources

  • POST: create resources

  • PUT: edit resources

  • DELETE: delete resources

Authentication

The standard API URL to be used is "https://clevercampaign.com/api/{resource}"

In every request you must carry with it an API key (you find this key in the account settings), a signature and a randomly generated salt string. To generate the signature:

  • Generate a random string to get a new salt

  • Generate the signature by hashing the salt using SHA256 with the secret key as the key

  • base64 encode the signature

  • URL encode the output

Below you can find an example request written in C# that creates a new contact.

      var apiKey = "85B0C3C5-BE9B-4684-9DF7-FF3ADB7D35F1";
      var secretKey = "your-secret-key-never-share-it";

      // Generate a new globally unique identifier for the salt
      var salt = System.Guid.NewGuid().ToString();

      // Initialize the keyed hash object using the secret key as the key
      HMACSHA256 hashObject = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));

      // Computes the signature by hashing the salt with the secret key as the key
      var signature = hashObject.ComputeHash(Encoding.UTF8.GetBytes(salt));

      // Base 64 Encode
      string encodedSignature = Convert.ToBase64String(signature);

      // URLEncode
      encodedSignature = System.Web.HttpUtility.UrlEncode(encodedSignature);

      using (WebClient client = new WebClient())
      {
        client.Headers.Add("publickey", apiKey);
        client.Headers.Add("salt", salt);
        client.Headers.Add("signature", encodedSignature);

        byte[] response = client.UploadValues("https://clevercampaign.com/api/contact", "POST", new NameValueCollection()
        {
          { "email", "email@example.com" },
          { "firstname", "Peter" },
          { "lastname", "Example" },
        });

        string result = System.Text.Encoding.UTF8.GetString(response);
      }