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    

Response Format

Every API response contains the response code and response details respective to the result of the request. Within this response will be a data node which contains the request-specific response.

The following response codes are used by the API:

  • 200 OK: The request was successful. See response body for additional data.
  • 400 BAD REQUEST: The parameters provided were invalid. See response body for error messages.
  • 401 UNAUTHORIZED: The account name and API key are not valid credentials or an improper request was made.
  • 404 NOT FOUND: The call you are trying to make does not exist. Check call structure.
  • 500 SERVER ERROR: Our bad. Try sending your request again and contact us if the problem persists.

To receive a JSON response, use json in your request URLs e.g. https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/json/event/record.

To receive XML use xml e.g. https://getambassador.com/api/v2/[[app:username]]/[[app:key]]/xml/event/record.

API responses come from the following set of stable IPs:

"23.235.32.0/20",
"43.249.72.0/22",
"103.244.50.0/24",
"103.245.222.0/23",
"103.245.224.0/24",
"104.156.80.0/20",
"151.101.0.0/16",
"157.52.64.0/18",
"172.111.64.0/18",
"185.31.16.0/22",
"199.27.72.0/21",
"199.232.0.0/16",
"202.21.128.11/32",
"202.21.128.12/32",
"203.57.145.11/32",
"203.57.145.12/32"

Updates to this list are posted on our status page.

Example responses of our API methods are given for various response formats. Feel free to test more using the API explorer in each method!

Example Success Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <code>200</code>
  <message>OK: The request was successful. See response body for additional data.</message>
  <data>
    <ambassadors>
      <ambassador>
        <first_name>Jane</first_name>
        <last_name>Doe</last_name>
        <email>jane@example.com</email>
        <uid>142</uid>
        <balance_money>0.00</balance_money>
        <balance_points>0</balance_points>
        <memorable_url>http://mbsy.co/Developers/djane</memorable_url>
        <unique_referrals>0</unique_referrals>
        <sandbox>0</sandbox>
      </ambassador>
      <ambassador>
        <first_name>John</first_name>
        <last_name>Doe</last_name>
        <email>john@example.com</email>
        <uid>143</uid>
        <balance_money>0.00</balance_money>
        <balance_points>0</balance_points>
        <memorable_url>http://mbsy.co/Developers/djohn</memorable_url>
        <unique_referrals>0</unique_referrals>
        <sandbox>0</sandbox>
      </ambassador>
      <ambassador>
        <first_name>Bob</first_name>
        <last_name>Doe</last_name>
        <email>bob@example.com</email>
        <uid>144</uid>
        <balance_money>0.00</balance_money>
        <balance_points>0</balance_points>
        <memorable_url>http://mbsy.co/Developers/dbob</memorable_url>
        <unique_referrals>0</unique_referrals>
        <sandbox>0</sandbox>
      </ambassador>
    </ambassadors>
  </data>
</response>
{
  "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",
          "memorable_url": "http://mbsy.co/Developers/djane",
          "unique_referrals": "0",
          "sandbox": "0"
        },
        {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@example.com",
          "uid": "143",
          "balance_money": "0.00",
          "balance_points": "0",
          "memorable_url": "http://mbsy.co/Developers/djohn",
          "unique_referrals": "0",
          "sandbox": "0"
        },
        {
          "first_name": "Bob",
          "last_name": "Doe",
          "email": "bob@example.com",
          "uid": "144",
          "balance_money": "0.00",
          "balance_points": "0",
          "memorable_url": "http://mbsy.co/Developers/dbob",
          "unique_referrals": "0",
          "sandbox": "0"
        }
      ]
    }
  }
}

Example Error Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <code>400</code>
  <message>BAD REQUEST: The parameters provided were invalid. See response body for error messages.</message>
  <data>
    <error>The following POST parameters are required. "campaign_uid" and "email".</error>
  </data>
</response>
{
  "response": {
    "code": "400",
    "message": "BAD REQUEST: The parameters provided were invalid. See response body for error messages.",
    "errors": {
      "error": [
        "The following POST parameters are required. \"campaign_uid\" and \"email\"."
      ]
    }
  }
}