REST API

Rejoiner's REST API provides clients an additional method for sending order data to our servers. 

CONTENTS

Authentication

Each Rejoiner user is assigned a pair of keys: API KEY and API SECRET. Both keys are available under the Site ID in the  Implementation panel. In the future users will be able to reset those keys on demand, invalidating the existing ones.

In addition to specifying the API KEY, each request must also be signed using the API SECRET key. Signature is calculated with HMAC-SHA1 (raw binary data) and encoded with Base64, as described below.

# Header structure
Authorization: Rejoiner API_KEY:base64encode(hmac_sha1(API_SECRET, $http_verb + '\n' +
$request_path + '\n' + $request_body))
# Notes:
- $http_verb should be uppercase, eg. "POST"
- $request_path is relative and should always start with /, eg.
"/api/1.0/site/53b144ad346e713c1b2ed0d9/lead/convert"
- $request_body should be encoded in UTF-8, for GET requests use empty string
# Header example
Authorization: Rejoiner 770d3bfee9c540c4a2ba854444c1059a:Cvx3ONcsY7hf3q9gwb4Kf15xg8c=
Calculating Signature Example in Python
import hmac
import base64
from hashlib import sha1
def sign(api_secret, http_verb, request_path, request_body):
	content = '\n'.join((http_verb, request_path, request_body))
	hashed = hmac.new(api_secret.encode('utf-8'), content.encode('utf-8'), sha1)
	return base64.b64encode(hashed.digest() )
Calculating Signature Example in PHP
function sign($api_secret, $http_verb, $request_path, $request_body) {
    $content = "{$http_verb}\n{$request_path}\n{$request_body}";
    $hash = hash_hmac('sha1', $content, $api_secret, true);
    return base64_encode($hash);
}
Calculating Signature Example in C#
using System;
using System.Security.Cryptography;
using System.Text;
 
public class RejoinerAPI {
    public static String Sign(String secret, String verb, String path, String body) {
        String message = verb + "\n" + path + "\n" + body;
        byte[] secretBytes = Encoding.ASCII.GetBytes(secret);
        byte[] messageBytes = Encoding.ASCII.GetBytes(message);
        HMACSHA1 hmac = new HMACSHA1(secretBytes);
        return Convert.ToBase64String(hmac.ComputeHash(messageBytes));
    }
}

Guidelines

  • Remember to set Content-Type header to application/json.
  • All params in POST requests should be sent in JSON. Responses, where applicable, will also be in JSON.
  • API version is part of the endpoint path: when we introduce backward incompatible changes to existing endpoints, we will increment the API version accordingly.
  • Status codes will be used as meaningful responses in all endpoints:

RESPONSE STATUS MEANING
200 Request was successful
400 Required params were not specified and/or the body was malformed
403 Failed authentication and/or incorrect signature
500 Internal error, contact us for details

Endpoints

Base URL: https://app.rejoiner.com

CONVERT LEAD

POST /api/1.0/site/SITE ID/lead/convert

PARAM NAME   REQUIRED TYPE DESCRIPTION
email Yes String Lead's email address
campaign_id

deprecated

No String | array ID or list of Campaign IDs that should be converted
campaign_type

deprecated

No String Type of the campaign that should be converted ("abandonment" or "conversion")
cart_data   No Object Information about the converted cart (same params as in sendConversion JS endpoint)
cart_value No Integer Value of the cart  in cents.
cart_item_count No Integer Total number of items in cart.
ie: The number of all items in the cart, not just the number of distinct products.
customer_order_number No Integer External ID of this order.
promo No
Integer Promotional code for this order.
return_url No String General link to order-related page, like review request, order summary page, order invoice page, etc.
cart_items   No Array of Objects Stores data about cart items of the current session (Array of the same objects as in setCartItem endpoint)
product_id Yes String Unique ID of the product.
name No String Name of the item in cart.
description No String Full description of the item in cart.
category Yes Array of Strings Categories the cart item belongs to.
price No Integer The unit price of the cart item  in cents.
item_qty No Integer The quantity of an item in the cart.
qty_price No  
Integer The unit price X quantity of an item  in cents.
product_url No String An absolute product URL for the cart item.
image_url No String An absolute image URL for the cart item.
Any additional arguments (in cart_items) will be stored as custom fields (string values).

Converts all orders (that have not yet been converted) associated with specified lead email.

Additionally, one of the optional parameters may be specified to target one or multiple campaigns (for example, when a post-conversion campaign has a different goal than the an abandonment campaign). For post-conversion campaigns, the conversion will only occur if the campaign was already in process.

Example Request
# Assumes the following values:
# SITE_ID=4e456e8d6a137b4fd1000000
# API_KEY=78a5ab99fdff43e0aef4550429afea40
# API_SECRET=a758c2ab472941bb96851f3a77cb358d
POST /api/1.0/site/4e456e8d6a137b4fd1000000/lead/convert
Authorization: Rejoiner 78a5ab99fdff43e0aef4550429afea40:pinskhzQW2/QBXbHhLX7h+bDrSo=
Content-Type: application/json
{"email": "foo@bar.com"}
Note: Response body will always be empty, use the response status code to determine whether the request was successful.
Example of Extended Conversion Call - Recommended
# Assumes the following values:
# SITE_ID=53b53e65346e712ffe5756f2
# API_KEY=60d870b9d5b6497e9f55689c4ab1f54b
# API_SECRET=4158524bba7a4e5cb88a725c334da24c
 
POST /api/1.0/site/53b53e65346e712ffe5756f2/lead/convert
Authorization: Rejoiner 60d870b9d5b6497e9f55689c4ab1f54b:NzSvOuDyLnwM8VoDaCo1iVaxUtk=
Content-Type: application/json
 
{
  'email': 'foo2@bar.com',
  'campaign_id': '1',
  'campaign_type': 'abandonment',
  'cart_data': {
    'cart_value': 79996,
    'cart_item_count': 2
  },
  'cart_items': [{
    'name': 'Item Name',
    'product_id': 'ITM1',
    'price': 19999,
    'product_url': 'http://yoursite.com/productpage',
    'category': ['televisions', 'smart_tv'],
    'item_qty': 2,
    'qty_price': 39998,
    'image_url': 'http://yoursite.com/path/to/image.jpg'
  }, {
    'name': 'Item Name2',
    'product_id': 'ITM2',
    'price': 19999,
    'product_url': 'http://yoursite.com/productpage2',
    'category': ['televisions'],
    'item_qty': 2,
    'qty_price': 39998,
    'image_url': 'http://yoursite.com/path/to/image2.jpg'
  }]
}
CANCELLATION

This endpoint will look for any active recovery efforts for a specific email address and cancel all recovery efforts. This endpoint is very useful for order cancellations or any other events where you want to stop a recovery effort without converting an order.

POST /api/1.0/site/SITE ID/lead/cancel

PARAM NAME REQUIRED TYPE DESCRIPTION
email Yes String Lead's email address
Example Request
# Assumes the following values:
# SITE_ID=4e456e8d6a137b4fd1000000
# API_KEY=78a5ab99fdff43e0aef4550429afea40
# API_SECRET=a758c2ab472941bb96851f3a77cb358d
POST /api/1.0/site/4e456e8d6a137b4fd1000000/lead/cancel
Authorization: Rejoiner 78a5ab99fdff43e0aef4550429afea40:pinskhzQW2/QBXbHhLX7h+bDrSo=
Content-Type: application/json
{"email": "foo@bar.com"}
Note: Response body will always be empty, use the response status code to determine whether the request was successful.
ADDING CONTACT TO LIST

This will allow you to add emails to an existing list in your Rejoiner account via our REST API.

You can also send up to 5 custom fields with the other data needed for your campaigns. All custom fields are optional, but please remember to use the field consistently. e.g. if custom_1 is to be used as a coupon code for your customers, then don't use that field to store other data.

POST /api/1.0/site/SITE ID/contact_add

PARAM NAME TYPE REQUIRED DESCRIPTION
email string, case-sensitive Yes Lead's email address
list_id string Yes ID of the list to which add a contact
(See how to get List ID)
first_name string, case-sensitive No Lead's first name
custom_1 string, case-sensitive No Custom data - 1
custom_2 string, case-sensitive No Custom data - 2
custom_3 string, case-sensitive No Custom data - 3
custom_4 string, case-sensitive No Custom data - 4
custom_5 string, case-sensitive No Custom data - 5
custom_6 string, case-sensitive No Custom data - 6
Example Request
# Assumes the following values:
# SITE_ID=56f13ff6e6ec520d7fb30861
# API_KEY=d8e89cc07a0c489d9719b1380d162006
# API_SECRET=31f00bc02e37401c92f49eda1ca96800
 
POST /api/1.0/site/56f13ff6e6ec520d7fb30861/contact_add
Authorization: Rejoiner d8e89cc07a0c489d9719b1380d162006:C9vJttriEN7cikdx4Wej3zcI594=
Content-Type: application/json
 
{
    "list_id": "5706374ae6ec520d3370e368",
    "first_name": "Tom",
    "email": "foo@bar.com",
    "custom_1": "PROMCODE1",
    "custom_2": "http://exampleshop.com/landing-page"
}

Example Response

{
"status": "inserted"
}

If the email exists in the list, the first name will be updated:

{
"status": "updated"
}
UNSUBSCRIBE CONTACT

This will allow you to globally unsubscribe a customer/contact's email from all marketing efforts in your Rejoiner account.

POST /api/1.0/site/SITE ID/lead/unsubscribe

PARAM NAME TYPE REQUIRED DESCRIPTION
email string, case-sensitive Yes Lead's email address
Example Request
# Assumes the following values: 
# SITE_ID=56f13ff6e6ec520d7fb30861
# API_KEY=d8e89cc07a0c489d9719b1380d162006
# API_SECRET=31f00bc02e37401c92f49eda1ca96800
 
POST /api/1.0/site/56f13ff6e6ec520d7fb30861/lead/unsubscribe
Authorization: Rejoiner d8e89cc07a0c489d9719b1380d162006:C9vJttriEN7cikdx4Wej3zcI594=
Content-Type: application/json
 
{
    "email": "foo@bar.com",
}
RETRIEVE LISTS

This will allow you to retrieve all the lists in your Rejoiner account.

Example Request
# Assumes the following values:
# SITE_ID=56f13ff6e6ec520d7fb30861
# API_KEY=d8e89cc07a0c489d9719b1380d162006
# API_SECRET=31f00bc02e37401c92f49eda1ca96800
 
GET /api/1.0/site/56f13ff6e6ec520d7fb30861/lists
Authorization: Rejoiner d8e89cc07a0c489d9719b1380d162006:j/FQz56ySXApjycNIWEbpoYrfp0=

Example Response

[ 
   { 
      "id":"5706374ae6ec520d3370e368",
      "name":"List 1"
   },
   { 
      "id":"5763cfa6e6ec521463834ca7",
      "name":"List 2"
   },
   { 
      "id":"5763cfa6e6ec521463834cb1",
      "name":"List 3"
   }
]
Note: The response body will contain a list of objects with the properties of id and name

Still need help? Contact Us Contact Us