Ambassador

The Ambassador Developer Hub

Welcome to the Ambassador developer hub. You'll find comprehensive guides and documentation to help you start working with Ambassador as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

/event/record/

Records an instance of a campaign referral event.

If you want to call events for multiple campaigns in one request, use the 'event/multi_record' method.

 
posthttps://getambassador.com/api/v2/username/token/json/event/record/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

email
string
required

Your customer's email address

campaign_uid
int32

Your campaign's ID; required if product_id is not used

product_id
int32

Your product id which is assigned to one of your campaigns; can be used instead of campaign_uid; required if campaign_uid is not used

short_code
string

Referrer's "mbsy" shortcode; required for initial commissions

revenue
double

Revenue amount of the event

transaction_uid
string

Unique transaction ID for the event

ip_address
string

Your customer's IP address

uid
string

Your customer's internal unique ID

first_name
string

Your customer's first name

last_name
string

Your customer's last name

custom1
string

Custom field - related to ambassador

custom2
string

Custom field - related to ambassador

custom3
string

Custom field - related to ambassador

email_new_ambassador
string

Email login credentials to new ambassadors (1 - yes, 0 - no)

deactivate_new_ambassador
string

New ambassadors created are deactivated (1 - yes, 0 - no)

auto_create
string

If the customer is not an ambassador, create them (1 - yes, 0 - no)

add_to_group_id
string

Define which group(s) new ambassadors will be created in. Using this parameter will override default group settings. Group IDs should be separated by commas If add_to_group_id=-1, then ambassador will not be added to any group

event_data1
string

Custom field - related to the event

event_data2
string

Custom field - related to the event

event_data3
string

Custom field - related to the event

is_approved
string

Commission status (1 - approved, 0 - pending). Entering a value will override the campaign's auto approve setting. Otherwise, the campaign's setting will be used if not provided.

street
string

Your customer's street

city
string

Your customer's city

state
string

Your customer's state

zip
string

Your customer's zip

country
string

Your customer's country

phone
string

Your customer's phone number

Note: If you want to call events for multiple campaigns in one request, use the /event/multi_record/ method.

curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/event/record/ \
-H "Content-Type: application/json" \
-d '{"email":"johndoe@example.com", "campaign_uid": 25}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'johndoe@example.com',
                'campaign_uid' => '25');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/event/record/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output share links
            if(isset($response['response']['data']['ambassador']['campaign_links']))
            {
                foreach($response['response']['data']['ambassador']['campaign_links'] as $ary => $response_row)
                {
                    echo "Campaign Link: ".$response_row['url']."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
"""
This example assumes you've installed the popular Requests library
http://docs.python-requests.org
"""
import json, requests

username = '[[app:username]]'
api_key = '[[app:key]]'
response_type = 'json'
base_url = 'https://getambassador.com/api/v2/{0}/{1}/{2}'.format(
    username, api_key, response_type)

email = 'johndoe@example.com'
short_code = 'abc'
campaign = 25

data = {'email': email, 'short_code': short_code, 'campaign_uid': campaign}
request = requests.post(base_url+'/event/record/', data=data)

try:
    response = json.loads(request.text)
except (TypeError, ValueError), e:
    print "Error: {0}. Response: {1}.".format(e,request.text)
else:
    response = response.get('response')
    if response and int(response.get('code',0)) == 200:
        for campaign in response['data']['ambassador']['campaign_links']:
            print "Campaign link: {0}".format(campaign['url'])
    else:
        print request.text
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "referring_ambassador": {
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "uid": null,
        "commission": 2,
        "balance_money": 2,
        "balance_points": "0",
        "memorable_url": "http://mbsy.co/USERNAME/djane",
        "unique_referrals": "1",
        "sandbox": "0",
        "custom1": null,
        "custom2": null,
        "custom3": null
      },
      "ambassador": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "uid": null,
        "balance_money": 0,
        "balance_points": 0,
        "memorable_url": "http://mbsy.co/USERNAME/djohn",
        "unique_referrals": 0,
        "sandbox": "0",
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "street": "",
        "city": "",
        "state": "",
        "zip": "",
        "country": "",
        "phone": "",
        "groups": "2",
        "campaign_links": [
          {
            "campaign_uid": "25",
            "campaign_name": "Refer a Company",
            "sandbox": "0",
            "private": "0",
            "facebook_enabled": "0",
            "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
            "url": "http:\/\/mbsy.co\/8l",
            "total_money_earned": "0",
            "total_points_earned": "0"
          }
        ]
      }
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following POST parameter is required: \"email\"."
      ]
    }
  }
}
 
Suggest Edits

/event/multi_record/

Records an instance of a campaign referral event for multiple campaigns.

 
posthttps://getambassador.com/api/v2/username/token/json/event/multi_record/

Path Params

username
string
required

Your API username

token
string
required

You API token

Body Params

email
string
required

Your customer's email address

campaign_uid
string
required

Your campaigns' IDs (comma-separated)

short_code
string

Referrer's "mbsy" shortcode; required for initial commissions

revenue
double

Revenue amount of the event

transaction_uid
string

Unique transaction ID for the event

ip_address
string

Your customer's IP address

uid
string

Your customer's internal unique ID

first_name
string

Your customer's first name

last_name
string

Your customer's last name

custom1
string

Custom field - related to ambassador

custom2
string

Custom field - related to ambassador

custom3
string

Custom field - related to ambassador

email_new_ambassador
string

Email login credentials to new ambassadors (1 - approved, 0 - pending)

deactivate_new_ambassador
string

New ambassadors created are deactivated (1 - approved, 0 - pending)

auto_create
string

If the customer is not an ambassador, create them (1 - approved, 0 - pending)

add_to_group_id
string

Define which group(s) new ambassadors will be created in. Using this parameter will override default group settings. Group IDs should be separated by commas If add_to_group_id=-1, then ambassador will not be added to any group

event_data1
string

Custom field - related to the event

event_data2
string

Custom field - related to the event

event_data3
string

Custom field - related to the event

is_approved
string

Commission status (1 - approved, 0 - pending)

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/event/multi_record/ \
-H "Content-Type: application/json" \
-d '{"email":"johndoe@example.com", "campaign_uid": "25"}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'johndoe@example.com',
                'campaign_uid' => '82,333');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/event/multi_record/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output share links
            if(isset($response['response']['data']['item']))
            {
                foreach($response['response']['data']['item'] as $ary => $response_row)
                {
                    echo "Campaign Data: ".$response_row['data']."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "item": {
        "campaign_82": {
          "code": "200",
          "type": "OK",
          "message": "OK: The request was successful. See response body for additional data.",
          "data": {
            "referring_ambassador": {
              "first_name": "Jane",
              "last_name": "Doe",
              "email": "jane@example.com",
              "uid": null,
              "commission": 2,
              "balance_money": 2,
              "balance_points": "0",
              "memorable_url": "http://mbsy.co/Developers/djane",
              "unique_referrals": "1",
              "sandbox": "0",
              "custom1": null,
              "custom2": null,
              "custom3": null
            },
            "ambassador": {
              "first_name": "John",
              "last_name": "Doe",
              "email": "john@example.com",
              "uid": null,
              "balance_money": 0,
              "balance_points": 0,
              "memorable_url": "http://mbsy.co/Developers/djohn",
              "unique_referrals": 0,
              "sandbox": "0",
              "custom1": null,
              "custom2": null,
              "custom3": null,
              "campaign_links": [
                {
                  "campaign_uid": "25",
                  "campaign_name": "Refer a Company",
                  "sandbox": "0",
                  "private": "0",
                  "facebook_enabled": "0",
                  "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
                  "url": "http:\/\/mbsy.co\/8l",
                  "total_money_earned": "0",
                  "total_points_earned": "0"
                }
              ]
            },
            "company": {
              "company_name": "Example Company",
              "company_url": "http:\/\/example.com",
              "company_email": "John@example.com",
              "point_name": "Month(s)",
              "outgoing_email": "email@example.com",
              "avatar_url": "https:\/\/s3.amazonaws.com\/example\/avatars\/sample.jpg"
           }
         }
        },
        "campaign_333": {
          "code": "200",
          "type": "OK",
          "message": "OK: The request was successful. See response body for additional data.",
          "data": {
            "referring_ambassador": {
              "first_name": "Jane",
              "last_name": "Doe",
              "email": "jane@example.com",
              "uid": null,
              "commission": 2,
              "balance_money": 2,
              "balance_points": "0",
              "memorable_url": "http://mbsy.co/Developers/djane",
              "unique_referrals": "1",
              "sandbox": "0",
              "custom1": null,
              "custom2": null,
              "custom3": null
            },
            "ambassador": {
              "first_name": "John",
              "last_name": "Doe",
              "email": "john@example.com",
              "uid": null,
              "balance_money": 0,
              "balance_points": 0,
              "memorable_url": "http://mbsy.co/Developers/djohn",
              "unique_referrals": 0,
              "sandbox": "0",
              "custom1": null,
              "custom2": null,
              "custom3": null,
              "campaign_links": [
                {
                  "campaign_uid": "25",
                  "campaign_name": "Refer a Company",
                  "sandbox": "0",
                  "private": "0",
                  "facebook_enabled": "0",
                  "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
                  "url": "http:\/\/mbsy.co\/8l",
                  "total_money_earned": "0",
                  "total_points_earned": "0"
                }
              ]
            },
            "company": {
              "company_name": "Example Company",
              "company_url": "http:\/\/example.com",
              "company_email": "John@example.com",
              "point_name": "Month(s)",
              "outgoing_email": "email@example.com",
              "avatar_url": "https:\/\/s3.amazonaws.com\/example\/avatars\/sample.jpg"
            }
          }
        }
      }
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following POST parameter is required: \"email\"."
      ]
    }
  }
}
{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "item": {
        "campaign_180": {
          "code": "400",
          "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
          "errors": [
            "The provided campaign_uid has expired, doesn't exist, or doesn't belong to your company."
          ],
          "type": "BAD REQUEST"
        },
        "campaign_82": {
          "code": "200",
          "type": "OK",
          "message": "OK: The request was successful. See response body for additional data.",
          "data": {
            "referring_ambassador": {
              "first_name": "Jane",
              "last_name": "Doe",
              "email": "jane@example.com",
              "uid": null,
              "commission": 2,
              "balance_money": 2,
              "balance_points": "0",
              "memorable_url": "http://mbsy.co/Developers/djane",
              "unique_referrals": "1",
              "sandbox": "0",
              "custom1": null,
              "custom2": null,
              "custom3": null
            },
            "ambassador": {
              "first_name": "John",
              "last_name": "Doe",
              "email": "john@example.com",
              "uid": null,
              "balance_money": 0,
              "balance_points": 0,
              "memorable_url": "http://mbsy.co/Developers/djohn",
              "unique_referrals": 0,
              "sandbox": "0",
              "custom1": null,
              "custom2": null,
              "custom3": null,
              "campaign_links": [
                {
                  "campaign_uid": "25",
                  "campaign_name": "Refer a Company",
                  "sandbox": "0",
                  "private": "0",
                  "facebook_enabled": "0",
                  "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
                  "url": "http:\/\/mbsy.co\/8l",
                  "total_money_earned": "0",
                  "total_points_earned": "0"
                }
              ]
            },
            "company": {
              "company_name": "Example Company",
              "company_url": "http:\/\/example.com",
              "company_email": "John@example.com",
              "point_name": "Month(s)",
              "outgoing_email": "email@example.com",
              "avatar_url": "https:\/\/s3.amazonaws.com\/example\/avatars\/sample.jpg"
            }
          }
        }
      }
    }
  }
}
 
Suggest Edits

/ambassador/get/

Retrieves details about a given ambassador including their active share links. Can automatically create the requested ambassador if they do not exist yet.

 
gethttps://getambassador.com/api/v2/username/token/json/ambassador/get/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Query Params

email
string
required

Your customer's email address

uid
string

Your customer's internal unique ID

first_name
string

Your customer's first name

last_name
string

Your customer's last name

custom1
string

Custom field - related to ambassador

custom2
string

Custom field - related to ambassador

custom3
string

Custom field - related to ambassador

custom4
date

Custom date field - related to ambassador

email_new_ambassador
string

Email login credentials to new ambassadors (1 - yes, 0 - no)

sandbox
string

New ambassadors created for testing (1 - yes, 0 - no) Note: If the auto_create parameter is set to 1 and sandbox is not passed, you will receive a true/false value in the sandbox field in the response

deactivate_new_ambassador
string

New ambassadors created are deactivated (1 - yes, 0 - no)

auto_create
string

If the customer is not an ambassador, create them (1 - yes, 0 - no)

add_to_group_id
string

Define which group(s) new ambassadors will be created in. Using this parameter will override default group settings. Group IDs should be separated by commas If add_to_group_id=-1, then ambassador will not be added to any group

set_groups
string

Define which group(s) existing ambassadors will be put in. Using this parameter will override default group settings and an ambassador's current groups. Group IDs should be separated by commas

street
string

Your customer's street

city
string

Your customer's city

state
string

Your customer's state

zip
string

Your customer's zip

country
string

Your customer's country

phone
string

Your customer's phone

paypal_email
string

Your customer's PayPal email address

company
string

Your customer's Company name

status
string

Your customer's status if you have opted to create a new ambassador if the customer is not found (auto_create = 1). Valid values are enrolled, prospect, banned and unsubscribed.

 
# retrieve an ambassador
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/ambassador/get/ \
-H "Content-Type: application/json" \
-d '{"email":"johndoe@example.com"}' \
-X GET
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'johndoe@example.com',
                'sandbox' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/ambassador/get/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output share links
            if(isset($response['response']['data']['ambassador']['campaign_links']))
            {
                foreach($response['response']['data']['ambassador']['campaign_links'] as $ary => $response_row)
                {
                    echo "Campaign Link: ".$response_row['url']."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
# create a new ambassador
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/ambassador/get/ \
-H "Content-Type: application/json" \
-d '{"email":"johndoe@example.com","auto_create": "1","uid": "0000123"}'\
-X GET
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "referring_ambassador": {
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "uid": null,
        "commission": null,
        "balance_money": "2.40",
        "balance_points": "0",
        "memorable_url": "http://mbsy.co/Developers/djane",
        "unique_referrals": "1",
        "sandbox": "0",
        "custom1": null,
        "custom2": null,
        "custom3": null
      },
      "ambassador": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com",
        "uid": null,
        "balance_money": "0.00",
        "balance_points": "0",
        "money_paid": "9.00",
        "points_paid": "0.00",
        "memorable_url": "http://mbsy.co/Developers/djohn",
        "unique_referrals": "0",
        "sandbox": "0",
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "custom4": "2018-03-07",
        "groups": "1,2,3",
        "street": null,
        "city": null,
        "state": null,
        "zip": null,
        "country": null,
        "phone": "",
        "company": "Builder Co.",
        "paypal_email": "john@example.com",
        "campaign_links": [
          {
            "campaign_uid": "25",
            "campaign_name": "Refer a Company",
            "sandbox": "0",
            "private": "0",
            "facebook_enabled": "0",
            "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
            "url": "http:\/\/mbsy.co\/8l",
            "total_money_earned": "0",
            "total_points_earned": "0"
          }
        ]
      }
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following POST parameter is required: \"email\"."
      ]
    }
  }
}
{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "referring_ambassador": {
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "uid": null,
        "commission": null,
        "balance_money": "2.40",
        "balance_points": "0",
        "memorable_url": "http://mbsy.co/Developers/djane",
        "unique_referrals": "1",
        "sandbox": "0",
        "custom1": null,
        "custom2": null,
        "custom3": null
      },
      "ambassador": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com",
        "uid": null,
        "balance_money": "0.00",
        "balance_points": "0",
        "money_paid": "9.00",
        "points_paid": "0.00",
        "memorable_url": "http://mbsy.co/Developers/djohn",
        "unique_referrals": "0",
        "sandbox": false,
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "custom4": "2018-03-07",
        "groups": "1,2,3",
        "street": null,
        "city": null,
        "state": null,
        "zip": null,
        "country": null,
        "phone": "",
        "company": "Builder Co.",
        "paypal_email": "john@example.com",
        "campaign_links": [
          {
            "campaign_uid": "25",
            "campaign_name": "Refer a Company",
            "sandbox": "0",
            "private": "0",
            "facebook_enabled": "0",
            "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
            "url": "http:\/\/mbsy.co\/8l",
            "total_money_earned": "0",
            "total_points_earned": "0"
          }
        ]
      }
    }
  }
}
 
Suggest Edits

/ambassador/stats/

Retrieves statistics about a given ambassador including a summary and per-campaign report of their earned commissions, generated revenue, shares, share clicks and unique referrals as well as shares, share clicks, and unique referrals per social channel. Can automatically create the requested ambassador if they do not exist yet.

 
gethttps://getambassador.com/api/v2/username/token/json/ambassador/stats/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Query Params

email
string
required

Your customer's email address

uid
string

Your customer's internal unique ID

first_name
string

Your customer's first name

last_name
string

Your customer's last name

custom1
string

Custom field - related to ambassador

custom2
string

Custom field - related to ambassador

custom3
string

Custom field - related to ambassador

email_new_ambassador
string

Email login credentials to new ambassadors (1 - yes, 0 - no)

sandbox
string

New ambassadors created for testing (1 - yes, 0 - no)

deactivate_new_ambassador
string

New ambassadors created are deactivated (1 - yes, 0 - no)

auto_create
string

If the customer is not an ambassador, create them

start_date
date

Retrieve stats starting at this date (inclusive)

end_date
date

Retrieve stats ending at this date (inclusive)

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/ambassador/stats/ \
-H "Content-Type: application/json" \
-d '{"email":"johndoe@example.com"}' \
-X GET
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'johndoe@example.com');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/ambassador/stats/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output share links
            if(isset($response['response']['data']['ambassador']['stats_summary']))
            {
                echo "Stats Summary Array";
                print_r($response['response']['data']['ambassador']['stats_summary']);
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response":{
    "code":"200",
    "message":"OK: The request was successful. See response body for additional data.",
    "data":{
      "referring_ambassador":{
        "first_name":null,
        "last_name":null,
        "email":"jane@example.com",
        "uid":null,
        "commission":null,
        "balance_money":"0.00",
        "balance_points":"0.00",
        "memorable_url":"http:\/\/mbsy.co\/Developers\/djane",
        "unique_referrals":"8",
        "sandbox":"0",
        "custom1": null,
        "custom2": null,
        "custom3": null
      },
      "ambassador":{
        "first_name":null,
        "last_name":null,
        "email":"john@example.com",
        "uid":null,
        "balance_money":"0.00",
        "balance_points":"0.00",
        "memorable_url":"http:\/\/mbsy.co\/Developers\/djohn",
        "unique_referrals":"0",
        "sandbox":"0",
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "stats_summary":{
          "start_date":"2012-04-10",
          "end_date":"2012-06-22",
          "commissions":{
            "pending_count":"0",
            "approved_count":"0",
            "denied_count":"0",
            "pending_sum":"0",
            "approved_sum":"0",
            "denied_sum":"0"
          },
          "revenue":{
            "pending_sum":"0",
            "approved_sum":"0",
            "denied_sum":"0"
          },
          "count_clicks":"0",
          "count_shares":"0",
          "unique_referrals":"0",
          "channels":{
            "email":{
              "count_shares":"0",
              "count_clicks":"N\/A",
              "unique_referrals":"0",
              "commissions":{
                "pending_count":"0",
                "approved_count":"0",
                "denied_count":"0",
                "pending_sum":"0",
                "approved_sum":"0",
                "denied_sum":"0"
              },
              "revenue":{
                "pending_sum":"0",
                "approved_sum":"0",
                "denied_sum":"0"
              }
            },
            "facebook":{
              "count_shares":"0",
              "count_clicks":"0",
              "unique_referrals":"0",
              "commissions":{
                "pending_count":"0",
                "approved_count":"0",
                "denied_count":"0",
                "pending_sum":"0",
                "approved_sum":"0",
                "denied_sum":"0"
              },
              "revenue":{
                "pending_sum":"0",
                "approved_sum":"0",
                "denied_sum":"0"
              }
            }
          }
        },
        "campaign_links":[
          {
            "campaign_uid":"82",
            "campaign_name":"Campaign One",
            "campaign_description":"This is an example campaign description",
            "sandbox":"0",
            "private":"0",
            "facebook_enabled":"1",
            "url":"http:\/\/mbsy.co\/bJj",
            "total_money_earned":"0.00",
            "total_points_earned":"0.00",
            "unique_referrals":"0",
            "stats":{
              "commissions":{
                "pending_count":"0",
                "approved_count":"0",
                "denied_count":"0",
                "pending_sum":"0",
                "approved_sum":"0",
                "denied_sum":"0"
              },
              "revenue":{
                "pending_sum":"0",
                "approved_sum":"0",
                "denied_sum":"0"
              },
              "count_clicks":"0",
              "count_shares":"0",
              "unique_referrals":"0",
              "channels":{
                "email":{
                  "count_shares":"0",
                  "count_clicks":"N\/A",
                  "unique_referrals":"0",
                  "commissions":{
                    "pending_count":"0",
                    "approved_count":"0",
                    "denied_count":"0",
                    "pending_sum":"0",
                    "approved_sum":"0",
                    "denied_sum":"0"
                  },
                  "revenue":{
                    "pending_sum":"0",
                    "approved_sum":"0",
                    "denied_sum":"0"
                  }
                },
                "facebook":{
                  "count_shares":"0",
                  "count_clicks":"0",
                  "unique_referrals":"0",
                  "commissions":{
                    "pending_count":"0",
                    "approved_count":"0",
                    "denied_count":"0",
                    "pending_sum":"0",
                    "approved_sum":"0",
                    "denied_sum":"0"
                  },
                  "revenue":{
                    "pending_sum":"0",
                    "approved_sum":"0",
                    "denied_sum":"0"
                  }
                }
              }
            }
          }
        ]
      },
      "company":{
        "company_name":"Developers",
        "company_url":"",
        "company_email":"support@getambassador.com",
        "point_name":"Month(s)",
        "outgoing_email":null,
        "avatar_url":"https:\/\/s3.amazonaws.com\/ambassador\/avatars\/1088_1339785224.jpg"
      }
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following POST parameter is required: \"email\"."
      ]
    }
  }
}
 
Suggest Edits

/ambassador/all/

Retrieves a list of up to 100 ambassadors meeting the provided thresholds.

 
gethttps://getambassador.com/api/v2/username/token/json/ambassador/all/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Query Params

page
int32

Page number of paginated results

min_money
double

Minimum monetary balance (inclusive)

min_points
int32

Minimum point balance (inclusive)

min_referrals
int32

Minimum unique referrals (inclusive)

email
string

Filter by email address

uid
string

Filter by uid

is_active
string

1 - Returns only active ambassadors, 0 - Returns only deactivated ambassadors, when variable is not used all ambassadors are returned

created_at__lte
string

Filter by ambassadors created on or before the date provided

created_at__gte
string

Filter by ambassadors created or or after the given date

sandbox
int32

New ambassadors created for testing (1 - yes, 0 - no)

group
string

Filter by the group uid found in the URL of the segment details page

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/ambassador/all/ \
-H "Content-Type: application/json" \
-X GET
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/ambassador/all/ \
-H "Content-Type: application/json" \
-d '{"min_referrals": 100}' \
-X GET
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('page' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/ambassador/all/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output ambassadors
            if(isset($response['response']['data']['ambassadors']))
            {
                foreach($response['response']['data']['ambassadors'] as $ary => $response_row)
                {
                    echo "Ambassador: ".$response_row['email']."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "ambassadors": [
        {
          "first_name": "Jane",
          "last_name": "Doe",
          "email": "jane@example.com",
          "uid": "142",
          "balance_money": "0.00",
          "balance_points": "0",
          "money_paid": "0.00",
          "points_paid": "0.00",
          "memorable_url": "http://mbsy.co/Developers/djane",
          "unique_referrals": "0",
          "sandbox": "0",
          "created_at": "2012-04-10T16:15:19+0000",
          "fraud_score": 0,
          "fraud_score_human_readable": null,
          "fraud_score_percent_ui": 0,
          "fraud_reasons": {}
        },
        {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@example.com",
          "uid": "143",
          "balance_money": "0.00",
          "balance_points": "0",
          "money_paid": "0.00",
          "points_paid": "0.00",
          "memorable_url": "http://mbsy.co/Developers/djohn",
          "unique_referrals": "0",
          "sandbox": "0",
          "created_at": "2012-01-31T20:20:42+0000",
          "fraud_score": 0,
          "fraud_score_human_readable": null,
          "fraud_score_percent_ui": 0,
          "fraud_reasons": {}
        },
        {
          "first_name": "Bob",
          "last_name": "Doe",
          "email": "bob@example.com",
          "uid": "144",
          "balance_money": "0.00",
          "balance_points": "0",
          "money_paid": "0.00",
          "points_paid": "0.00",
          "memorable_url": "http://mbsy.co/Developers/dbob",
          "unique_referrals": "0",
          "sandbox": "0",
          "created_at": "2012-01-31T19:57:27+0000",
          "fraud_score": 0,
          "fraud_score_human_readable": null,
          "fraud_score_percent_ui": 0,
          "fraud_reasons": {}
        }
      ]
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following POST parameters are not numbers. \"page\", \"min_money\", \"min_points\", \"min_referrals\"."
      ]
    }
  }
}
 
Suggest Edits

/ambassador/update/

Updates existing ambassador data.

NOTE: To identify ambassador in our system you can choose either 'uid' or 'email'. If both are used then 'uid' takes precedence.

 
posthttps://getambassador.com/api/v2/username/token/json/ambassador/update

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

uid
string

Your ambassador's internal unique ID

email
string

Your ambassador's email address

new_email
string

New email

new_uid
string

New uid

first_name
string

New First name

last_name
string

New Last name

custom1
string

Custom field

custom2
string

Custom field

custom3
string

Custom3

is_deactivated
string

1 - deactivate ambassador. 0 - activate ambassador.

send_welcome_email
string

Send welcome email (1 - yes, 0 - no)

street
string

Your customer's street

city
string

Your customer's city

state
string

Your customer's state

zip
string

Your customer's zip

country
string

Your customer's country

phone
string

Your customer's phone number

paypal_email
string

Your customer's PayPal email address

company
string

Your customer's Company name

set_groups
string

Define which group(s) existing ambassadors will be put in. Using this parameter will override default group settings and an ambassador's current groups. Group IDs should be separated by commas

is_deactivated

Deactivation will change the ambassador's status to Banned.

curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/ambassador/update \
-H "Content-Type: application/json" \
-d '{"email": "johndoe@example.com", "first_name": "John", "last_name": "Doe" }' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'old_email@example.com',
        'new_email' => 'new_email@example.com');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/ambassador/update/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

         var_dump($response);
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "message": "Ambassador updated successfully."
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following GET/POST parameter is required: uid or email."
      ]
    }
  }
}
 
Suggest Edits

/balance/deduct/

Deducts from the running commission balance of an ambassador.

 
posthttps://getambassador.com/api/v2/username/token/json/balance/deduct/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

email
string
required

Your customer's email address

amount
double
required

Amount to deduct

uid
string

Your customer's internal unique ID

custom1
string

Custom field

custom2
string

Custom field

custom3
string

Custom field

type
string

"money" or "points"

email_new_ambassador
string

Email login credentials to new ambassadors (1 - yes, 0 - no)

sandbox
string

New ambassadors created for testing (1 - yes, 0 - no)

deactivate_new_ambassador
string

New ambassadors created are deactivated (1 - yes, 0 - no)

auto_create
string

If the customer is not an ambassador, create them (1 - yes, 0 - no)

Endpoint Deprecated

The /balance/deduct/ endpoint has been deprecated as of June 10, 2018.

curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/balance/deduct/ \
-H "Content-Type: application/json" \
-d '{"email": "johndoe@example.com", "amount": 1.00}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'johndoe@example.com',
                    'amount' => '1',
                    'sandbox' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/balance/deduct/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Output updated balance for the ambassador
            if(isset($response['response']['data']['balance']))
            {
                foreach($response['response']['data']['balance'] as $response_row)
                {
                    echo $response_row."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
 
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "ambassador": {
        "first_name": "",
        "last_name": "",
        "created_at": "2016-03-09T14:15:58.056+0000",
        "email": "johndoe@example.com",
        "uid": null,
        "platform_id": 46818,
        "balance_money": "0.00",
        "balance_points": "0.00",
        "memorable_url": "http://staging.mbsy.co/Developers/1996",
        "unique_referrals": null,
        "count_shares": "39",
        "sandbox": "0",
        "custom1": "",
        "custom2": "",
        "custom3": "",
        "groups": "177,229",
        "street": "",
        "city": "",
        "state": "",
        "zip": "",
        "country": "",
        "campaign_links": [
          {
            "campaign_uid": "25",
            "campaign_name": "Refer a Company",
            "sandbox": "0",
            "private": "0",
            "facebook_enabled": "0",
            "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
            "url": "http:\/\/mbsy.co\/8l",
            "total_money_earned": "0",
            "total_points_earned": "0"
          }
        ]
      },
      "company": {
        "company_name": "Example Company",
        "company_url": "http:\/\/example.com",
        "company_email": "John@example.com",
        "point_name": "Month(s)",
        "outgoing_email": "email@example.com",
        "avatar_url": "https:\/\/s3.amazonaws.com\/example\/avatars\/sample.jpg"
      },
      "balance": {
        "old": "2.00",
        "new": 1,
        "type": "money"
      }
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following GET/POST parameters are required: email, type, amount."
      ]
    }
  }
}
 
Suggest Edits

/balance/add/

Adds to the running commission balance of an ambassador.

 
posthttps://getambassador.com/api/v2/username/token/json/balance/add/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

email
string
required

Your customer's email address

amount
double
required

Amount to add

uid
string

Your customer's internal unique ID

custom1
string

Custom field

custom2
string

Custom field

custom3
string

Custom field

type
string

Balance type to add ("money" or "points")

email_new_ambassador
int32

Email login credentials to new ambassadors

sandbox
int32

New ambassadors created for testing (1 - yes, 0 - no)

deactivate_new_ambassador
int32

New ambassadors created are deactivated (1 - yes, 0 - no)

auto_create
int32

If the customer is not an ambassador, create them (1 - yes, 0 - no)

Endpoint Deprecated

The /balance/add/ endpoint has been deprecated as of June 10, 2018.

curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/balance/add/ \
-H "Content-Type: application/json" \
-d '{"email": "johndoe@example.com", "amount": 1.00}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'johndoe@example.com',
                    'amount' => '1',
                    'sandbox' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/balance/add/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Output updated balance for the ambassador
            if(isset($response['response']['data']['balance']))
            {
                foreach($response['response']['data']['balance'] as $response_row)
                {
                    echo $response_row."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "ambassador": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "uid": null,
        "balance_money": 0,
        "balance_points": 0,
        "memorable_url": "http://mbsy.co/USERNAME/djohn",
        "unique_referrals": 0,
        "sandbox": "0",
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "campaign_links": [
          {
            "campaign_uid": "25",
            "campaign_name": "Refer a Company",
            "sandbox": "0",
            "private": "0",
            "facebook_enabled": "0",
            "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
            "url": "http:\/\/mbsy.co\/8l",
            "total_money_earned": "0",
            "total_points_earned": "0"
          }
        ]
      },
      "company": {
      "company_name": "Example Company",
      "company_url": "http:\/\/example.com",
      "company_email": "John@example.com",
      "point_name": "Month(s)",
      "outgoing_email": "email@example.com",
      "avatar_url": "https:\/\/s3.amazonaws.com\/example\/avatars\/sample.jpg"
      },
      "balance": {
        "old": "1.00",
        "new": 2,
        "type": "money"
      }
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following GET/POST parameters are required: email, type, amount."
      ]
    }
  }
}
 
Suggest Edits

/shortcode/get/

Retrieves the referring ambassador and campaign information tied to an “mbsy” shortcode.

 
gethttps://getambassador.com/api/v2/username/token/json/shortcode/get/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Query Params

short_code
string
required

The "mbsy" variable passed via GET or POST

sandbox
string

Does the short code belong to a test campaign? (1 - yes, 0 - no)

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/shortcode/get/ \
-H "Content-Type: application/json" \
-d '{"short_code": "test"}' \
-X GET
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('short_code' => 'a',
                'sandbox' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/shortcode/get/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output shortcode data
            if(isset($response['response']['data']['shortcode']))
            {
                foreach($response['response']['data']['shortcode'] as $response_row)
                {
                    echo $response_row."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "shortcode": {
          "valid": 1,
          "sandbox": "0",
          "discount_value": "abc123",
          "first_name": "Jane",
          "last_name": "Doe",
          "email": "johndoe@example.com",
          "uid": "17296",
          "campaign_uid": "17",
          "campaign_name": "Username Reservations",
          "campaign_description": "Get 5 of your friends to reserve their Ambassador username and get an Ambassador t-shirt!",
          "custom1": "data1",
          "custom2": "data2",
          "custom3": "data3",
          "status": "enrolled"
      }
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following GET/POST parameter is required: short_code."
      ]
    }
  }
}
 
Suggest Edits

/social/addthis/

Retrieves an AddThis snippet for all active campaigns for one of your customers.

 
posthttps://getambassador.com/api/v2/username/token/json/social/addthis/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

email
string
required

Your customer's email address

uid
string

Your customers's internal unique ID

first_name
string

Your customer's first name

last_name
string

Your customer's last name

custom1
string

Custom field

custom2
string

Custom field

custom3
string

Custom field

message
string

Default share message

email_new_ambassador
string

Email login credentials to new ambassadors (1 - yes, 0 - no)

sandbox
string

New ambassadors created for testing (1 - yes, 0 - no)

deactivate_new_ambassador
string

New ambassadors are deactivated (1 - yea, 0 - no)

auto_create
string

If the customer is not an ambassador, create them (1 - yes, 0 - no)

Implementation of AddThis:

To facilitate the socialization of API-based implementations we also return an AddThis sharing snippet for each campaign link in the API response. If you decide to utilize this snippet, you will need to include some javascript lines to make AddThis work. You may read more about how to integrate AddThis into your website at the official AddThis website.

You may optionally allow us to track shares from your AddThis implementation by including the following JavaScript at the bottom of your AddThis-enabled page.

AddThis Listener:

<script type="text/javascript">
    function shareEventHandler(evt){
        if (evt.type == 'addthis.menu.share'){
            // set this variable equal to the campaign share URL being shared
            // setting this will be dependent on how you set up AddThis on your site
            var share_url = "SET_URL_BEING_SHARED_HERE";
            // ------------------------------------------------------------------
            var url_fragments = share_url.split("/");
            var short_code = url_fragments[url_fragments.length-1];
            var xmlhttp;
            if (window.XMLHttpRequest){
                // code for IE7+, Firefox, Chrome, Opera, Safari
                xmlhttp=new XMLHttpRequest();
            }else{
                // code for IE6, IE5
                xmlhttp=new ActiveXObject("Microsoft.XMLHTTP");
            }

            xmlhttp.open("GET","https://getambassador.com/share_tracker/track_share?short_code="+short_code+"&social_name="+evt.data.service+"",true);
            xmlhttp.send();
        }
    }
    // Attach the listener to AddThis
    addthis.addEventListener('addthis.menu.share', shareEventHandler);
</script>
 

You may optionally choose to disable address bar sharing analytics by including the following JavaScript at the bottom of your AddThis-enabled page.

Disable address bar tracking:

<script type="text/javascript">
    var addthis_config = addthis_config||{};
    addthis_config.data_track_addressbar = false;
</script>
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/social/addthis/ \
-H "Content-Type: application/json" \
-d '{"email": "jane@example.com"}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'johndoe@example.com',
                'sandbox' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/social/addthis/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output addthis data
            if(isset($response['response']['data']['ambassador']['addthis']))
            {
                foreach($response['response']['data']['ambassador']['addthis'] as $response_array)
                {
                    foreach($response_array as $response_row)
                    {
                        echo $response_row."\n\n";
                    }
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "referring_ambassador": {
        "first_name": null,
        "last_name": null,
        "email": null,
        "uid": null,
        "commission": null,
        "balance_money": 0,
        "balance_points": 0,
        "memorable_url": "http://mbsy.co",
        "unique_referrals": 0,
        "sandbox": 0,
        "custom1": null,
        "custom2": null,
        "custom3": null
      },
      "ambassador": {
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "uid": null,
        "balance_money": 0,
        "balance_points": 0,
        "memorable_url": "http://mbsy.co/Developers/djane",
        "unique_referrals": 0,
        "sandbox": "0",
        "custom1": null,
        "custom2": null,
        "custom3": null
        "addthis": [
          {
            "campaign_uid": "25",
            "campaign_name": "Refer a Company",
            "sandbox": "0",
            "private": "0",
            "facebook_enabled": "0",
            "campaign_description": "Refer a new company to Ambassador and get rewarded 50% of their first payment and 10% of each recurring payment!",
            "url": "http:\/\/mbsy.co\/8m",
            "total_money_earned": "0",
            "total_points_earned": "0",
            "snippet": "<center><div style=\"text-align:center;width:350px;\" class=\"addthis_toolbox addthis_default_style addthis_32x32_style\" addthis:url=\"http:\/\/mbsy.co\/8m\" addthis:title=\"I'm an Ambassador of Example\"><a class=\"addthis_button_facebook\"><\/a><a class=\"addthis_button_twitter\" tw:via=\"GetAmbassador\"><\/a><a class=\"addthis_button_stumbleupon\"><\/a><a class=\"addthis_button_linkedin\"><\/a><a class=\"addthis_button_tumblr\"><\/a><a class=\"addthis_button_email\"><\/a><a class=\"addthis_button_wordpress\"><\/a><a class=\"addthis_button_compact\"><\/a><a class=\"addthis_counter addthis_bubble_style\"><\/a><\/div><\/center>"
          }
        ]
      }
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following GET/POST parameter is required: email."
      ]
    }
  }
}
 
Suggest Edits

/company/get/

Retrieves details about your company and your active campaigns.

Reward types:

  • P - Percentage Monetary
  • F - Flat Monetary
  • N - Percentage Non-Monetary
  • M - Flat Non-Monetary
  • D - None
 
gethttps://getambassador.com/api/v2/username/token/json/company/get/

Path Params

username
string
required

Your API username

token
string
required

Your API token

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/company/get/ \
-H "Content-Type: application/json"
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/company/get/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, FALSE);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output company data
            if(isset($response['response']['data']['company']))
            {
                foreach($response['response']['data']['company'] as $response_row)
                {
                    echo $response_row."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
 
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "company": {
        "company_name": "Sample",
        "company_url": "",
        "company_email": "johndoe@example.com",
        "point_name": "points",
        "outgoing_email": "sample@example.com"
      },
      "campaigns": [
        {
          "campaign_uid": "17",
          "campaign_name": "Sample Campaign 1",
          "campaign_description": "Get 5 of your friends to reserve their username and get a t-shirt!",
          "campaign_description": "This is a sample description s",
          "initial_reward": {
            "type_text": "Flat Monetary",
            "type_code": "F",
            "amount": "10"
          },
          "recurring_reward": {
            "type_text": "None",
            "type_code": "D",
            "amount": "0"
          },
          "landing_page": "https:\/\/example.com\/reserve",
          "sandbox": "0",
          "private": "1",
          "facebook_enabled": "0",
          "auto_approve_commissions": "1",
          "discount_value": "df59df8",
          "start_date": "1314918000",
          "end_date": null,
          "user_message": "I thought you would like Ambassador -- it's simple, intuitive referral software for businesses.  To get 10% off, use my referral link:",
          "company_message": "Increase your Social Marketing ROI with Ambassador. Ambassador gives you the tools to turn your customers into Brand Ambassadors. Sign up for a free trial:",
          "subject": "Use this software to turn customers into Brand Ambassadors",
          "social_message": "Looking for Social Media ROI? Check out Ambassador and get 10% off for a limited time.. #ambassador"
        },
        {
          "campaign_uid": "25",
          "campaign_name": "Sample Campaign 2",
          "campaign_description": "Refer a new company to sample and get rewarded 50% of their first payment and 10% of each recurring payment!",
          "initial_reward": {
            "type_text": "Flat Monetary",
            "type_code": "F",
            "amount": "12"
          },
          "recurring_reward": {
            "type_text": "None",
            "type_code": "D",
            "amount": "0"
          },
          "landing_page": "http:\/\/example.com",
          "sandbox": "0",
          "private": "1",
          "facebook_enabled": "1",
          "auto_approve_commissions": "1",
          "discount_value": "0",
          "start_date": "1315954800",
          "end_date": null,
          "user_message": "I thought you would like Ambassador -- it's simple, intuitive referral software for businesses.  To get 10% off, use my referral link:",
          "company_message": "Increase your Social Marketing ROI with Ambassador. Ambassador gives you the tools to turn your customers into Brand Ambassadors. Sign up for a free trial:",
          "subject": "Use this software to turn customers into Brand Ambassadors",
          "social_message": "Looking for Social Media ROI? Check out Ambassador and get 10% off for a limited time.. #ambassador"
        }
      ]
    }
  }
}
 
Suggest Edits

/company/stats/

Retrieves high-level statistics about your company's referral program.

 
gethttps://getambassador.com/api/v2/username/token/json/company/stats/

Path Params

username
string
required

Your API username

token
string
required

Your API token

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/company/stats/ \
-H "Content-Type: application/json"
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/company/stats/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, FALSE);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output production commission stats
            if(isset($response['response']['data']['stats']['production']['commissions']))
            {
                foreach($response['response']['data']['stats']['production']['commissions'] as $response_field => $response_data)
                {
                    echo $response_field." = ".$response_data."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
 
A binary file was returned

You couldn't be authenticated

{
  "response":{
    "code":"200",
    "message":"OK: The request was successful. See response body for additional data.",
    "data":{
      "company":{
        "company_name":"Sample",
        "company_url":"",
        "company_email":"johndoe@example.com",
        "point_name":"points",
        "outgoing_email":null
      },
      "stats":{
        "production":{
          "ambassadors":{
            "activated_count":"82",
            "deactivated_count":"1"
          },
          "campaigns":{
            "active_count":"3"
          },
          "commissions":{
            "pending_count":"33",
            "approved_count":"3",
            "denied_count":"1",
            "pending_sum":"1044.5",
            "approved_sum":"112",
            "denied_sum":"25"
          },
          "revenue":{
            "pending_sum":"3787.18",
            "approved_sum":"15.28",
            "denied_sum":"0"
          },
          "payouts":{
            "pending_count":"0",
            "paid_count":"4",
            "denied_count":"0",
            "pending_sum":"0",
            "paid_sum":"5",
            "denied_sum":"0"
          },
          "clicks":{
            "count":"33"
          }
        },
        "sandbox":{
          "campaigns":{
            "active_count":"6"
          },
          "clicks":{
            "count":"2"
          }
        }
      }
    }
  }
}
 
Suggest Edits

/company/token/

Returns one-time token which is required for Single Sign-on.

 
gethttps://getambassador.com/api/v2/username/token/json/company/token/

Path Params

username
string
required

Your API username

token
string
required

Your API token

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/company/token/ \
-H "Content-Type: application/json"
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';
    $mbsy_token = '';

    // Build and make API call
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/company/token/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, FALSE);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Output token
            if(isset($response['response']['data']['token']))
            {
                $mbsy_token = $response['response']['data']['token'];
                var_dump($mbsy_token);
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }

?>
A binary file was returned

You couldn't be authenticated

{
  "response":{
    "code":"200",
    "message":"OK: The request was successful. See response body for additional data.",
    "data":{
      "token":"cfeab99f171a70a900887212e42d1320"
    }
  }
}
 
Suggest Edits

/company/emails/

Returns email statistics in total and by email types:

  • New Ambassador
  • Pending Commission
  • Approved Commission
  • Denied Commission
  • Fulfilled Payout

The data in the total field is the combined statistics for all email types. Each entry in total and email_types is split by date. To combine dates, use aggregate. If no date period is specified, the data returned is for the current day. If no date period is specified and aggregate is used the data is all-time totals.

 
gethttps://getambassador.com/api/v2/username/token/json/company/emails/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Query Params

start_date
date

The starting date to fetch email statistics. If used, must be used with end_date. (YYYY-MM-DD)

end_date
date

The ending date to fetch email statistics. If used, must be used with start_date. (YYYY-MM-DD)

aggregate
boolean

Combine email statistics based on date period (1 - yes, 0 - no)

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/company/emails/ \
-H "Content-Type: application/json" \
-d '{"start_date": "2015-03-10", "end_date": "2016-03-10"}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';
    $mbsy_token = '';

    // Build and make API call
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/company/emails';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, FALSE);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Output token
            if(isset($response['response']['data']['total']) && isset($response['response']['data']['email_types']
            {
                $total = $response['response']['data']['total'];
                $email_types = $response['response']['data']['email_types'];

                var_dump($total);
                var_dump($email_types);
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }

?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "total": [
        {
          "delivered": 8,
          "unsubscribes": 0,
          "invalid_email": 0,
          "bounces": 0,
          "repeat_unsubscribes": 0,
          "unique_clicks": 0,
          "blocked": 0,
          "spam_drop": 0,
          "repeat_bounces": 0,
          "repeat_spamreports": 0,
          "date": "2013-06-13",
          "requests": 8,
          "spamreports": 0,
          "clicks": 0,
          "opens": 15,
          "unique_opens": 6
        }
      ],
      "email_types": {
        "newAmbassador": [
          {
            "delivered": 4,
            "unsubscribes": 0,
            "invalid_email": 0,
            "bounces": 0,
            "repeat_unsubscribes": 0,
            "unique_clicks": 0,
            "blocked": 0,
            "spam_drop": 0,
            "repeat_bounces": 0,
            "repeat_spamreports": 0,
            "date": "2013-06-13",
            "requests": 4,
            "spamreports": 0,
            "clicks": 0,
            "opens": 9,
            "unique_opens": 3
          }
        ],
        "pendingCommission": [
          {
            "delivered": 3,
            "unsubscribes": 0,
            "invalid_email": 0,
            "bounces": 0,
            "repeat_unsubscribes": 0,
            "unique_clicks": 0,
            "blocked": 0,
            "spam_drop": 0,
            "repeat_bounces": 0,
            "repeat_spamreports": 0,
            "date": "2013-06-13",
            "requests": 3,
            "spamreports": 0,
            "clicks": 0,
            "opens": 6,
            "unique_opens": 3
          }
        ],
        "approvedCommission": [
          {
            "delivered": 1,
            "unsubscribes": 0,
            "invalid_email": 0,
            "bounces": 0,
            "repeat_unsubscribes": 0,
            "unique_clicks": 0,
            "blocked": 0,
            "spam_drop": 0,
            "repeat_bounces": 0,
            "repeat_spamreports": 0,
            "date": "2013-06-13",
            "requests": 1,
            "spamreports": 0,
            "clicks": 0,
            "opens": 0,
            "unique_opens": 0
          }
        ],
        "deniedCommission": [
          {
            "delivered": 0,
            "unsubscribes": 0,
            "invalid_email": 0,
            "bounces": 0,
            "repeat_unsubscribes": 0,
            "unique_clicks": 0,
            "blocked": 0,
            "spam_drop": 0,
            "repeat_bounces": 0,
            "repeat_spamreports": 0,
            "date": "2013-06-13",
            "requests": 0,
            "spamreports": 0,
            "clicks": 0,
            "opens": 0,
            "unique_opens": 0
          }
        ],
        "fulfilledPayout": [
          {
            "delivered": 0,
            "unsubscribes": 0,
            "invalid_email": 0,
            "bounces": 0,
            "repeat_unsubscribes": 0,
            "unique_clicks": 0,
            "blocked": 0,
            "spam_drop": 0,
            "repeat_bounces": 0,
            "repeat_spamreports": 0,
            "date": "2013-06-13",
            "requests": 0,
            "spamreports": 0,
            "clicks": 0,
            "opens": 0,
            "unique_opens": 0
          }
        ],
        "deniedPayout": [
          {
            "delivered": 0,
            "unsubscribes": 0,
            "invalid_email": 0,
            "bounces": 0,
            "repeat_unsubscribes": 0,
            "unique_clicks": 0,
            "blocked": 0,
            "spam_drop": 0,
            "repeat_bounces": 0,
            "repeat_spamreports": 0,
            "date": "2013-06-13",
            "requests": 0,
            "spamreports": 0,
            "clicks": 0,
            "opens": 0,
            "unique_opens": 0
          }
        ]
      }
    }
  }
}
 
Suggest Edits

/group/all/

Retrieves a list of and details about your company's groups.

 
gethttps://getambassador.com/api/v2/username/token/json/group/all/

Path Params

username
string
required

Your API username

token
string
required

Your API token

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/group/all/ \
-H "Content-Type: application/json"
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/group/all/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, FALSE);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output group ids
            if(isset($response['response']['data']['groups']))
            {
                foreach($response['response']['data']['groups'] as $ary => $response_row)
                {
                    echo "Group ID: ".$response_row['group_id']."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
 
A binary file was returned

You couldn't be authenticated

{
  "response":{
    "code":"200",
    "message":"OK: The request was successful. See response body for additional data.",
    "data":{
        "groups": [
          "group":{
            "group_id:"1"
            "name":"Sample",
            "description":"Sample group description",
            "default":"0",
            "total_ambassadors": 5
          },
          "group":{
            "group_id:"2"
            "name":"Test",
            "description":"Test group description",
            "default":"0",
          	"total_ambassadors": 100
          },
          "group":{
            "group_id:"3"
            "name":"New",
            "description":"New group description",
            "default":"0",
          	"total_ambassadors": 0
          }
        ]
    }
  }
}
 
Suggest Edits

/group/get/

Retrieves details about a given group and a list of up to 100 ambassadors.

 
posthttps://getambassador.com/api/v2/username/token/json/group/get/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

group_id
int32

Group Id listed on your groups page

page
int32

Page number of paginated results

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/group/get/ \
-H "Content-Type: application/json" \
-d '{"group_id": 1}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('group_id' => '1',
                'page' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/group/get/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output ambassadors belonging to group
            if(isset($response['response']['data']['ambassadors']))
            {
                foreach($response['response']['data']['ambassadors'] as $response_field => $response_data)
                {
                    echo $response_field." = ".$response_data."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
 
A binary file was returned

You couldn't be authenticated

{
  "response":{
    "code":"200",
    "message":"OK: The request was successful. See response body for additional data.",
    "data":{
      "group":{
        "group_id:"1"
        "name":"Sample",
        "description":"Sample group description",
        "default":"0",
      },
      "ambassadors": [
          {"email":"jane@example.com"},
          {"email":"joe@example.com"},
          {"email":"josh@example.com"},
          {"email":"jeff@example.com"},
          {"email":"jack@example.com"}
      ]
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following GET/POST parameters are not numbers. \"page\", \"group_id\"."
      ]
    }
  }
}
 
Suggest Edits

/commission/all/

Retrieves up to 100 commissions meeting the provided thresholds

 
posthttps://getambassador.com/api/v2/username/token/json/commission/all/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

page
int32

Page number of paginated results

email
string

Your customer's email address

uid
string

Your customer's internal unique ID

is_approved
string

When variable is not used all commissions are returned (0 - Returns only pending commissions, 1 - Returns only approved commissions, 2 - Returns only denied commissions )

sandbox
string

When variable is not used all commissions are returned (1 - Returns only sandbox commissions, 0 - Returns only production commissions)

is_welcome_bonus
string

When variable is not used all commissions are returned (1 - Returns only commissions that are welcome bonuses, 0 - Returns commissions that are not welcome bonuses)

created_at__lte
string

Filter by commissions created before the date provided. Note: The date provided is treated as midnight of the date provided.

created_at__gte
string

Filter by ambassadors created on or after the date provided. Note: The date provided is treated as midnight of the date provided.

Fraud Status

The Fraud Status is available for every commission in the response. Each commission is assigned a status, score, and reasons if any. The fraud score is the percent of suspiciousness out of 100.

The possible Fraud Status values in the response are:

  • Flagged - commission has been marked suspicious
  • Fraudulent - was flagged, and the company has denied the commission
  • Immune - has been unflagged and marked immune
  • Null
  • Passed - the commission passed fraud detection, it's not suspicious
  • Scanning - the commission is being analyzed for fraud
  • Unflagged - was flagged, but has been unflagged by the company
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/commission/all/ \
-H "Content-Type: application/json" \
-d '{"email": "johndoe@example.com"}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('page' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/commission/all/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        if(isset($response['response']) && $response['response']['code'] == '200')
        {
            // Loop through and output ambassadors
            if(isset($response['response']['data']['ambassadors']))
            {
                foreach($response['response']['data']['ambassadors'] as $ary => $response_row)
                {
                    echo "Ambassador: ".$response_row['email']."\n\n";
                }
            }
        } else {
            echo 'Error, see response dump above.';
        }
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "commissions": [
        {
          "commission_uid": "4813",
          "campaign_uid": "260",
          "affiliate_uid": "17080",
          "referring_uid": "15056",
          "remote_customer_email": "john@example.com",
          "remote_customer_id": "12345",
          "affiliate_email": "jane@example.com",
          "affiliate_first_name": "Jane",
          "affiliate_last_name": "Doe",
          "revenue_amount": "150.00",
          "commission_amount": "50.00",
          "created_at": "2013-04-08 13:51:44.731",
          "transaction_id": null,
          "is_approved": "1",
          "is_sandbox": "0",
          "is_trial": "0",
          "event_data1": null,
          "event_data2": null,
          "event_data3": null,
          "is_welcome_bonus": "0",
          "fraud": {
            "status": passed,
            "score": 0,
            "reasons": []
          }
        },
        {
          "commission_uid": "4814",
          "campaign_uid": "260",
          "affiliate_uid": "17080",
          "referring_uid": "15056",
          "remote_customer_email": "john@example.com",
          "remote_customer_id": "12345",
          "affiliate_email": "jane@example.com",
          "affiliate_first_name": "Jane",
          "affiliate_last_name": "Doe",
          "revenue_amount": "45.00",
          "commission_amount": "5.00",
          "created_at": "2013-04-08 16:51:44.842",
          "transaction_id": null,
          "is_approved": "0",
          "is_sandbox": "0",
          "is_trial": "0",
          "event_data1": null,
          "event_data2": null,
          "event_data3": null,
          "is_welcome_bonus": "1",
          "fraud": {
            "status": scanning,
            "score": 0,
            "reasons": []
          }
        },
        {
          "commission_uid": "821",
          "campaign_uid": "95",
          "affiliate_uid": "4364",
          "referring_uid": "4349",
          "remote_customer_email": "elmer@example.com",
          "remote_customer_id": null,
          "affiliate_email": "willie@example.com",
          "affiliate_first_name": "",
          "affiliate_last_name": "",
          "revenue_amount": "15.28",
          "commission_amount": "62.00",
          "created_at": "2012-04-10 17:43:19.522",
          "transaction_id": "324543",
          "is_approved": "0",
          "is_sandbox": "0",
          "is_trial": "0",
          "event_data1": "testingthisagain2",
          "event_data2": null,
          "event_data3": null,
          "is_welcome_bonus": "0",
          "fraud": {
            "status": "fraudulent",
            "score": 94.41,
            "reasons": [
            	"The referred ambassador has the same device as a currently banned ambassdor.",
              "The referring ambassador for this commission has 21 other denied commissions."
            ]
          }
        }
      ]
    }
  }
}
 
Suggest Edits

/commission/update/

Updates the commission status. If a commission is pending "0", it can be changed to approved "1" or denied "2". Approved and denied commissions cannot be updated via API.

NOTE: To identify a commission in our system you can choose either 'commission_uid' (you can get it using commission/all method) or 'transaction_uid'. If both are used then 'commission_uid' takes precedence. To make sure you will update just one commission with given transaction uid, you can send additional parameter: campaign_uid.

 
gethttps://getambassador.com/api/v2/username/token/json/commission/update/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Query Params

commission_uid
string

UID of commission (see note above)

transaction_uid
string

Unique transaction ID for the commission (see note above)

campaign_uid
string

You can use it when you identify commission by transaction_uid to make sure you will update just one commission with given transaction uid

is_approved
string

1 - approved commission, 2 - deny commission

event_data1
string

Custom field - related to event/commission

event_data2
string

Custom field - related to event/commission

event_data3
string

Custom field - related to event/commission

revenue
string

The revenue amount

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/commission/update/ \
-H "Content-Type: application\json"
-d '{"commission_uid":"400", "is_approved":"1"}' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('commission_uid' => '4813',
                'is_approved' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/commission/update/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        var_dump($response);
    }
?>
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "message": "Commission updated successfully."
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following GET/POST parameter is required: commission_uid or transaction_uid."
      ]
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "You can change state of pending commission only."
      ]
    }
  }
}
 
Suggest Edits

/commission/add/

Creates commission for given ambassador. Useful for commission events without referrers. For commissions with a referred party, use the event/record method.
NOTE: To identify ambassador in our system you can choose either 'uid' or 'email'. If both are used then 'uid' takes precedence.

 
posthttps://getambassador.com/api/v2/username/token/json/commission/add/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

uid
string
required

Your ambassador's internal unique ID (see note above)

email
string
required

Your ambassador's email address (see note above)

campaign_uid
string
required

Your campaign's ID

amount
double
required

Amount of commission

customer_email
string

Your customer's email address

first_name
string

Your customer's first name

last_name
string

Your customer's last name

revenue
double

Revenue amount of commission

transaction_uid
string

Unique transaction ID for commission

referrer_uid
string

Your referrer's internal unique ID

customer_uid
string

Your customer's internal unique ID

is_approved
string

1- approved commission, 0 - pending commission

email_new_ambassador
string

Email login credentials to new ambassadors (1 - yes, 0 - no)

deactivate_new_ambassador
string

New ambassadors create are deactivated (1 - yes, 0 - no)

event_data1
string

Custom field - related to event/commission

event_data2
string

Custom field - related to event/commission

event_data3
string

Custom field - related to event/commission

 
curl https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/commission/add/ \
-H "Content-Type: application/json" \
-d '{"email": "johndoe@example.com", "campaign_uid": "", "amount": 1.00 }' \
-X POST
<?php
    error_reporting(E_ALL);
    ini_set("display_errors", 1);

    $username = '[[app:username]]';
    $api_key = '[[app:key]]';
    $response_type = 'json';

    // Build and make API call
    $data = array('email' => 'email@example.com',
                'campaign_uid' => '260',
                'amount' => '15',
                'is_approved' => '1');
    $data = http_build_query($data);
    $url = 'https://getambassador.com/api/v2/'.$username.'/'.$api_key.'/'.$response_type.'/commission/add/';
    $curl_handle = curl_init();
    curl_setopt($curl_handle, CURLOPT_URL, $url);
    curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl_handle, CURLOPT_POST, TRUE);
    curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl_handle, CURLOPT_FAILONERROR, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, FALSE);
    $response = curl_exec($curl_handle);
    curl_close($curl_handle);

    echo($response);

    // Example parsing of JSON response
    if(strtolower($response_type) == 'json')
    {
        // Decode response to array
        $response = json_decode($response, TRUE);

        var_dump($response);
    }
?>
 
A binary file was returned

You couldn't be authenticated

{
  "response": {
    "code": "200",
    "message": "OK: The request was successful. See response body for additional data.",
    "data": {
      "message": "Commission added successfully.",
      "commission_uid": 1234
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following GET/POST parameter is required: uid or email."
      ]
    }
  }
}
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "Invalid campaign_uid."
      ]
    }
  }
}
 
Suggest Edits

/compliance/remove/

This endpoint allows for the removal of all associated personal data from the system for the provided individual to assist with compliance requests such as the GDPR's right to erasure.

 
posthttps://getambassador.com/api/v2/username/token/json/compliance/remove/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

email
string
required

email of the contact to remove

confirm
string
required

to confirm you want to remove this contact's data from the system, set this to "1"

Caution

When requesting for removal, please confirm that you want to remove this contact. All personal data connected to this email in the system will be removed permanently. Include confirm=1 in the request for confirmation.

curl --request POST \
  --url https://getambassador.com/api/v2/username/token/json/compliance/remove/
var request = require("request");

var options = { method: 'POST',
  url: 'https://getambassador.com/api/v2/username/token/json/compliance/remove/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://getambassador.com/api/v2/username/token/json/compliance/remove/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://getambassador.com/api/v2/username/token/json/compliance/remove/");

xhr.send(data);
import requests

url = "https://getambassador.com/api/v2/username/token/json/compliance/remove/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{  
   "response":{  
      "code":"200",
      "message":"OK: The request was successful. See response body for additional data.",
      "data":{  

      }
   }
}
{  
   "response":{  
      "code":"400",
      "message":"BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
      "errors":{  
         "error":[  
            "The following GET/POST parameter is required: email."
         ]
      }
   }
}
 
Suggest Edits

/compliance/export/

This endpoint allows for the export of all associated personal data from the system for the provided individual to assist with compliance requests such as the GDPR's right of access and/or right to data portability.

 
posthttps://getambassador.com/api/v2/username/token/json/compliance/export/

Path Params

username
string
required

Your API username

token
string
required

Your API token

Body Params

email
string
required

Note:

This endpoint is not intended to be used as a means of populating your platform with contact data. Instead, it is intended to be used for retrieving an individual's personal data for the purpose of satisfying compliance requests. As such, the endpoint only allows up to 6 requests per minute.

curl --request POST \
  --url https://getambassador.com/api/v2/username/token/json/compliance/export/
var request = require("request");

var options = { method: 'POST',
  url: 'https://getambassador.com/api/v2/username/token/json/compliance/export/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://getambassador.com/api/v2/username/token/json/compliance/export/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://getambassador.com/api/v2/username/token/json/compliance/export/");

xhr.send(data);
import requests

url = "https://getambassador.com/api/v2/username/token/json/compliance/export/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "profile": {
        "first_name": "",
        "last_name": "",
        "full_name": "",
        "email": "",
        "backup_email": "",
        "phone": "",
        "company": "",
        "job_title": "",
        "street": "",
        "city": "",
        "state": "",
        "zip": "",
        "country": "",
        "satisfaction_score": "",
        "paypal_email": "",
        "dwolla_email": "",
        "avatar_url": ""
    },
    "ip_addresses": [
        "",
    ],
    "satisfaction_surveys": [
        {
          "score": "",
          "reason": "",
          "sent_at": "",
          "first_viewed_at": "",
          "last_viewed_at": "", 
          "completed_at": ""
        },
    ],
    "fingerprints": [
        {
            "cuid": "",
            "created_at": "",
            "ip_addresses": [
                "",
            ],
            "devices": [
                {
                    "did": "",
                    "device_type": "",
                    "created_at": "",
                    "browser": "",
                    "os": "",
                    "mobile_type": "",
                    "clicks": [
                      "ip_address": "",
                      "click_date": "",
					            "country": "",
                      "region": "",
                      "city": "",
					            "latitude": "",
                      "longitude": "",
					            "agent": ""
                    ]
                }
            ]
        }
    ],
    "social_data": {
        "bio": null,
        "twitter_username": null,
        "twitter_url": null,
        "twitter_followers": null,
        "klout_score": null,
        "klout_last_update": null,
        "facebook_username": null,
        "facebook_friends": null,
        "facebook_url": null,
        "linkedin_username": null,
        "linkedin_contacts": null,
        "linkedin_url": null,
        "googleplus_username": null,
        "googleplus_url": null,
        "pinterest_username": null,
        "pinterest_url": null,
        "pinterest_followers": null,
        "tumblr_username": null,
        "tumblr_url": null,
        "stumbleupon_username": null,
        "stumbleupon_url": null,
        "blogger_username": null,
        "blogger_url": null,
        "delicious_username": null,
        "delicious_url": null,
        "digg_username": null,
        "digg_url": null,
        "diigo_username": null,
        "diigo_url": null,
        "friendfeed_username": null,
        "friendfeed_url": null,
        "hackernews_username": null,
        "hackernews_url": null,
        "myspace_username": null,
        "myspace_url": null,
        "myspace_followers": null,
        "reddit_username": null,
        "reddit_url": null,
        "yahoo_username": null,
        "yahoo_url": null,
        "youtube_username": null,
        "youtube_url": null,
        "fullcontact_data": null,
        "fullcontact_status": null
    },
    "emails": [
      {
        "recipient": "",
        "subject": "",
        "message": "",
        "date": ""
      },
    ]
}
{  
   "response":{  
      "code":"400",
      "message":"BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
      "errors":{  
         "error":[  
            "The following GET/POST parameter is required: email."
         ]
      }
   }
}
 
 

A webhook is a callback over HTTP that you can configure to be notified about certain events in your Ambassador account.

Using webhooks can open up many possibilities for more advanced integrations with Ambassador. For example, you can set up a webhook to hit your application whenever a contact is created and send them additional resources, add them to your data store, etc.

To set up a webhook, contact support@getambassador.com or your success coach.

To receive a webhook, you will need a publicly accessible URL. When a given event occurs, such as creating a new contact, we will make a POST request to the URL of your choice with JSON data.

The basic format of a webhook response is as follows:

{
    "webhook_version": 0.1,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "contact-created",
    "event_data": {
    	"contact": {
            "id": 100,
            "first_name": "First",
            "last_name": "Last",
            "email": "email@example.com",
            "test_mode": false,
            "created_at": "2012-01-19T18:55:10",
            "enrolled_at": "2015-09-16T21:30:49.710",
            "unenrolled_at": "2016-10-12T12:01:22.239",
            "status": "enrolled",
            "internal_id": "your-company-contact-id",
            "phone": "555.555.5555",
            "company": "Ambassador",
            "job_title": "Developer",
            "street": "1 Main Street",
            "city": "Springfield",
            "state": "Michigan",
            "zip": "48000",
            "country": "United States"
        }
    }
}

The event_data field contains different data based on the event_type. The following table outlines all of the event types available to you, what their event_type value will be, and when they occur.

Event
Event Type
Occurs When

Contact Created

contact-created

A new contact is created

Contact Status Updated

contact-status-updated

A contact's status is updated e.g. enrolled, banned, or unsubscribed

Commission Created

commission-created

A new commission is created

Commission Status Updated

commission-status-updated

A commission status is updated e.g. approved or denied

Payout Created

payout-created

A new payout is created

Share Tracked

share-tracked

A share is tracked

Click Tracked

click-tracked

A click is tracked

Referral created

referral-created

One contact refers another

Contact Added to Campaign

contact-added-to-campaign

Contact joins a campaign

Contact Added to Segment

contact-added-to-segment

Contact is added to a segment

 
 

Because you receive webhooks via a publicly accessible URL, it is important that you verify your webhooks are genuine. Each webhook you configure will receive its own secret token. This token should be stored in a secure location and never shared publicly.

In order to verify webhooks, you will need to check the value of the X-MBSY-HMAC-SHA256 HTTP header sent with every webhook request. This header is a sha256 base64-encoded hash of the request body and the secret token.

You can verify the request came from us and that its contents are valid by comparing the value of the X-MBSY-HMAC-SHA256 header with your own generated hash. See the sidebar for examples of how to do this. If you do not see an example for the language of your choice, let us know, and we'll be happy to help.

import base64
import hashlib
import hmac
import json

payload = json.dumps(WEBHOOK_REQUEST_BODY, sort_keys=True)
secret = str(WEBHOOK_REQUEST_BODY)

hm = hmac.new(secret, payload, hashlib.sha256)

# compare this to the `X-MBSY-HMAC-SHA256` header value; they should match
hm_digest_verify = base64.b64encode(hm.digest())
import javax.crypto.Mac; 
import javax.crypto.spec.SecretKeySpec; 
import org.apache.commons.codec.binary.Base64; 

class Main { 
  public static void main(String[] args) { 
    String secret = $WEBHOOK_SECRET_KEY; // This is your webhook token 
    
    // The payload will be pulled from the body of the request. 
    // It will be valid JSON. The text below is from the sample request. 
    String payload = WEBHOOK_REQUEST_BODY;

    // Generates hash 
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256"); 
    SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256"); 
    sha256_HMAC.init(secret_key); 

    String hash = Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes())); 

    // Compare this to the `X-MBSY-HMAC-SHA256` header value; they should match 
    System.out.println(hash); 
  } 
} 
$secret = $WEBHOOK_SECRET_KEY; // This is your webhook token
$data = $WEBHOOK_REQUEST_BODY; // The payload will be pulled from the body of the request.
 
$sig = base64_encode(hash_hmac('sha256', $data, $secret, true)); 

// Compare this to the `X-MBSY-HMAC-SHA256` header value; they should match
print $sig; 
 

HTTP Response Code

Make sure the url you provide to consume the webhook returns a 200 or 201 response code when requested. Your url must provide a response within 10 seconds or it will be treated as a failed response.

When Ambassador receives a non-200 HTTP response code or a response longer than the 10 seconds from your URL, it will retry sending the webhook after 5 minutes and again after 30 minutes. Every event receives an event_id in the webhook data. This is useful if you need to ensure you do not process the event more than once.

 
Suggest Edits

Contact Created

This event occurs whenever a contact is created.

 

Event Data Objects:

Object
Description

contact

The created contact's data

Contact Fields:

Field
Type
Description

id

integer

unique identifier of the contact within Ambassador

first_name

string

first name

last_name

string

last name

email

string

email address

internal_id

string

unique identifier of the contact supplied by you

test_mode

boolean

is this contact in test mode?

created_at

date

date contact was created

enrolled_at

date

date contact was enrolled

unenrolled_at

date

date contact was unenrolled

status

string

enrolled, banned, or unsubscribed

source

string

the method by which the contact was created

phone

string

phone number

company

string

company name

job_title

string

job title

street

string

street address

city

string

city

state

string

state

zip

string

zip / postal code

country

string

country

memorable url

string

the contact's memorable url

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "contact-created",
    "event_data": {
    	"contact": {
            "id": 100,
            "first_name": "First",
            "last_name": "Last",
            "email": "email@example.com",
            "test_mode": false,
            "created_at": "2012-01-19T18:55:10",
            "enrolled_at": "2015-09-16T21:30:49.710",
            "unenrolled_at": "2016-10-12T12:01:22.239",
            "source": "Portal Registration",
            "status": "enrolled",
            "internal_id": "your-company-contact-id",
            "phone": "555.555.5555",
            "company": "Ambassador",
            "job_title": "Developer",
            "street": "1 Main Street",
            "city": "Springfield",
            "state": "Michigan",
            "zip": "48000",
            "country": "United States",
            "memorable_url": "http://mbsy.co/Company/username/"
        }
    }
}
Suggest Edits

Contact Status Updated

This event occurs whenever a contact's status is changed e.g. contact is enrolled

 

Event Data Objects:

Field
Description

contact

The referring contact's data

Contact Fields:

Field
Type
Description

id

integer

unique identifier of the contact within Ambassador

first_name

string

first name of the contact

last_name

string

last name of the contact

email

string

email of the contact

internal_id

string

unique identifier of the contact within your system

test_mode

boolean

is the contact in test mode?

created_at

date

date contact was created

enrolled_at

date

date contact was enrolled

unenrolled_at

date

date contact was unenrolled

status

string

status of contact

phone

string

phone number

company

string

company name of the contact

job_title

string

contact's job title

street

string

contact's street address

city

string

contact's city

state

string

contact's state

zip

string

contact's zip / postal code

country

string

contact's country

memorable_url

string

contact's memorable url

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "contact-status-updated",
    "event_data": {
    	"contact": {
            "id": 100,
            "first_name": "First",
            "last_name": "Last",
            "email": "email@example.com",
            "test_mode": false,
            "created_at": "2012-01-19T18:55:10",
            "enrolled_at": "2015-09-16T21:30:49.710",
            "unenrolled_at": "2016-10-12T12:01:22.239",
            "status": "enrolled",
            "internal_id": "your-company-contact-id",
            "phone": "555.555.5555",
            "company": "Ambassador",
            "job_title": "Developer",
            "street": "1 Main Street",
            "city": "Springfield",
            "state": "Michigan",
            "zip": "48000",
            "country": "United States",
            "memorable_url": "http://mbsy.co/Company/username/"
        }
    }
}
Suggest Edits

Share Tracked

This event occurs whenever a share is tracked.

 

Event Data Objects:

Field
Description

contact

The referring contact's data

share

The share event's data

url

The referring contact's url data

campaign

The campaign the share was tracked for

Contact Fields:

Field
Type
Description

id

integer

id of the contact

first_name

string

first name of the contact

last_name

string

last name of the contact

email

string

email of the contact

internal_id

string

unique identifier of the contact supplied by you

Share Fields:

Field
Type
Description

created_at

date

date shared

social_name

string

social name of share

URL Fields:

Field
Type
Description

short_code

string

short code of url

Campaign Fields:

Field
Type
Description

id

integer

campaign's ID

name

string

campaign's name

description

string

campaign's description

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "share-tracked",
    "event_data": {
    	"contact": {
        "id": 100,
        "first_name": "First",
        "last_name": "Last",
        "email": "email@example.com"
      },
      "share": {
        "created_at": "2012-01-19T18:55:10",
        "social_name": "email"
      },
      "url": {
        "short_code": "dq",
      },
  		"campaign": {
        "id": 123,
        "name": "Sample Campaign",
        "description": "This is a sample description."
      }
    }
}
Suggest Edits

Click Tracked

This event occurs whenever a click is tracked.

 

Event Data Objects:

Field
Description

contact

the referring contact's data

click

the click event's data

url

the url's data

campaign

the campaign's data

Contact Fields:

Field
Type
Description

id

integer

unique identifier of the contact within Ambassador

first_name

string

first name of the contact

last_name

string

last name of the contact

email

string

email of the contact

internal_id

string

unique identifier of the contact supplied by you

Click Fields:

Field
Type
Description

created_at

date

date clicked

social_name

string

social name of click

ip

string

ip address of click

referring_url

string

referring url of click (if exists)

URL Fields:

Field
Type
Description

short_code

string

short code of url

Campaign Fields:

Field
Type
Description

id

integer

campaign's ID

name

string

campaign's name

description

string

campaign's description

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "click-tracked",
    "event_data": {
    	"contact": {
        "id": 100,
        "first_name": "First",
        "last_name": "Last",
        "email": "email@example.com"
      },
      "click": {
        "created_at": "2012-01-19T18:55:10",
        "social_name": "email",
        "ip": "102.2.4.11",
        "referring_url": "m.facebook.com"
      },
      "url": {
        "short_code": "dq",
      },
  		"campaign": {
        "id": 123,
        "name": "Sample Campaign",
        "description": "This is a sample description."
      }
    }
}
Suggest Edits

Referral Created

This event occurs whenever a contact refers another contact.

 

Event Data Objects:

Field
Description

contact

The referring contact's data

referred_contact

The referred contact's data

Contact Fields:

Field
Type
Description

id

integer

unique identifier of the contact within Ambassador

first_name

string

first name

last_name

string

last name

email

string

email address

internal_id

string

unique identifier of the contact supplied by you

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "referral-created",
    "event_data": {
    	"contact": {
        "id": 100,
        "first_name": "First",
        "last_name": "Last",
        "email": "email@example.com"
      },
      "referred_contact": {
        "id": 101,
        "first_name": "First",
        "last_name": "Last",
        "email": "email2@example.com"
      }
    }
}
Suggest Edits

Commission Created

This event occurs whenever a new commission is created.

 

Event Data Objects:

Object
Description

contact

The referring contact's data

referred_contact

The referred contact's data

commission

The commission data

campaign

The campaign's data

Contact Fields:

Field
Type
Description

id

integer

unique identifier of the contact within Ambassador

first_name

string

first name

last_name

string

last name

email

string

email address

internal_id

string

unique identifier of the contact supplied by you

Campaign Fields:

Field
Type
Description

id

integer

campaign's ID

name

string

campaign's name

description

string

campaign's description

Commission Fields:

Field
Type
Description

id

integer

commission's ID

revenue

number

revenue amount of commission (ex. customer bought an item worth 20.00)

amount

number

amount earned by commission
(ex. contact earns 5.00 commission for referring)

created_at

date

date commission was created

approved_at

date

date commission was approved

status

string

commission's status

  • pending
  • approved
  • denied

transaction_id

string

commission's transaction id

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "commission-created",
    "event_data": {
    	"contact": {
        "id": 100,
        "first_name": "First",
        "last_name": "Last",
        "email": "email@example.com"
      },
      "referred_contact": {
        "id": 101,
        "first_name": "First",
        "last_name": "Last",
        "email": "email2@example.com"
      },
      "campaign": {
        "id": 123,
        "name": "Sample Campaign",
        "description": "This is a sample description."
      },
      "commission": {
        "id": 12345,
        "revenue": 20.00,
        "amount": 5.00,
        "created_at": "2012-04-10T16:15:19",
        "approved_at": "2012-04-10T16:15:19",
        "status": "approved",
        "transaction_id": "abc123"
      }
    }
}
Suggest Edits

Payout Created

This event occurs whenever a new payout is created.

 

Event Data Objects:

Field
Description

contact

The contact's data

payout

The payout data

Contact Fields:

Field
Type
Description

id

integer

unique identifier of the contact within Ambassador

first_name

string

first name

last_name

string

last name

email

string

email address

internal_id

string

unique identifier of the contact supplied by you

Payout Fields:

Field
Type
Description

id

integer

id of the payout

created_at

date

date payout was created

amount

number

amount of the payout

unit

string

type of payout (money, points)

payment_method

string

payment method of payout (manual, paypal, dwolla, magento, gift_card, voucher)

gift_card_sku

string

SKU of gift card (if gift card payout)

voucher_code

string

voucher code

transaction_id

string

transaction id of payout (if available)

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "payout-created",
    "event_data": {
      "payout": {
        "id": 123, 
        "unit": "money", 
        "amount": 0.01, 
        "created_at": "2016-11-30T20:22:17.322775", 
        "voucher_code": null, 
        "gift_card_sku": null, 
        "payment_method": "manual", 
        "transaction_id": null
      }, 
      "contact": {
        "id": 12345, 
        "first_name": "First",
        "last_name": "Last", 
        "email": "test@example.com",
        "internal_id": "contact-12345"
      }
    }
}
Suggest Edits

Commission Status Updated

This event occurs whenever a commission status is changed e.g. commission is approved or denied

 

Event Data Objects:

Field
Description

contact

The referring contact's data

referred_contact

The referred contact's data

commission

The commission data

campaign

The campaign's data

Contact / Customer Fields:

Field
Type
Description

id

integer

unique identifier of the contact within Ambassador

first_name

string

first name

last_name

string

last name

email

string

email address

internal_id

string

unique identifier of the contact within your system

Campaign Fields:

Field
Type
Description

id

integer

campaign's id

name

string

campaign's name

description

string

campaign's description

Commission Fields:

Field
Type
Description

id

integer

commission's ID

revenue

number

revenue amount of commission (ex. customer bought an item worth 20.00)

amount

number

amount earned by commission
(ex. contact earns 5.00 commission for referring)

created_at

date

date commission was created

approved_at

date

date commission was approved

status

string

commission's status

  • pending
  • approved
  • denied

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2012-01-19T18:55:10",
    "event_id": 123,
    "event_type": "commission-status-updated",
    "event_data": {
    	"contact": {
        "id": 100,
        "first_name": "First",
        "last_name": "Last",
        "email": "email@example.com"
      },
      "referred_contact": {
        "id": 101,
        "first_name": "First",
        "last_name": "Last",
        "email": "email2@example.com"
      },
      "campaign": {
        "id": 123,
        "name": "Sample Campaign",
        "description": "This is a sample description."
      },
      "commission": {
        "id": 12345,
        "revenue": 20.00,
        "amount": 5.00,
        "created_at": "2012-04-10T16:15:19",
        "approved_at": "2012-04-10T16:15:19",
        "status": "approved"
      }
    }
}
Suggest Edits

Contact Added to Campaign

This event occurs whenever a contact gains access to one of your campaigns

 

Event Data Objects:

Field
Description

contact

the contact's data

campaign

the campaign the contact is gaining access to

url

the contact's share link information

Contact Fields:

Field
Type
Description

id

integer

id of the contact

first_name

string

first name of the contact

last_name

string

last name of the contact

email

string

email of the contact

internal_id

string

your customer's id in your system

Campaign Fields:

Field
Type
Description

id

integer

id of the campaign

name

string

name of the campaign

description

string

name of the campaign

Url Fields:

Field
Type
Description

short_code

string

short code of the url

share_url

string

share link of the contact

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2017-01-19T10:35:10",
    "event_id": 123
    "event_type": "contact-added-to-campaign"
    "event_data": {
        "contact": {
            "id": 100,
            "first_name": "First",
            "last_name": "Last",
            "email": "example@email.com",
            "internal_id": "your-company-contact-id"
        },
        "campaign": {
            "id": 123,
            "name": "Campaign",
            "description": "Description"
        },
				"url": {
            "short_code": "abc",
            "share_url": "http://mbsy.co/abc123"
         }
    }
}
Suggest Edits

Contact Added to Segment

This event occurs whenever a contact is added to one your segments

 

Event Data Objects:

Field
Description

contact

the referring contact's data

segment

the segment the contact is falling into

Contact Fields:

Field
Type
Description

id

integer

id of the contact

first_name

string

first name of the contact

last_name

string

last name of the contact

email

string

email of the contact

internal_id

string

your customer's id in your system

Segment Fields:

Field
Type
Description

id

integer

id of the segment

name

string

name of the segment

legacy_id

string

the legacy id (previously known as the group_id)

description

string

the segment description

Webhook Result Format

{
    "webhook_version": 0.4,
    "created_at": "2017-01-19T10:35:10",
    "event_id": 123,
    "event_type": "contact-added-to-segment",
    "event_data": {
        "contact": {
            "id": 100,
            "first_name": "First",
            "last_name": "Last",
            "email": "email@example.com",
            "internal_id": "your-company-contact-id"
        },
        "segment": {
            "id": 101,
            "name": "Segment",
            "legacy_id": "1",
            "description": "Description"
        }
    }
}