# Ambassador

Ambassador is a referral marketing platform that automates customer referral, affiliate, influencer, and partner marketing programs with comprehensive tracking.

## Overview

Ambassador is a platform that automates and scales all your customer referral, affiliate, influencer, and partner marketing programs.

## \*\*API Information \*\*

The Base URL used for the Ambassador connector is **`https://getambassador.com/api/v2/{username}/token/json`**. More information can be found on their main API documentation (v1) - [API Documentation](https://docs.getambassador.com/reference/) site.

## Authentication

Within the builder, click on the Ambassador connector to display the connector properties panel. Select the 'Authentication' tab and click on the 'New authentication' button.
In the Tray.io authentication pop-up modal, name the authentication in a way that will quickly identify it within a potentially large list. For example, whether it is a Sandbox or Production auth, etc.
Consider who/ how many people will need access to this authentication when choosing where to create this authentication ('Personal' or 'Organisational').
The second page asks you for your 'API Token', 'Username', and 'Domain' credentials.
![Ambassador - authentication popup](https://tray.ai/documentation/images/connectors/service/ambassador/7nsLdalOuj2DzvVTBA4Bj7_Screenshot%202022-07-15%20at%2011.56.22.png)
To get these fields, head to the Ambassador dashboard. Click on the left panel and click on settings
![AUTH STEP 1](https://tray.ai/documentation/images/connectors/service/ambassador/1F3dfcreWRWxmdDc9OWOC9_Group%2012.png)
To get the API Token and username, head to Account Information and then scroll down to API credentials
![AUTH STEP 2](https://tray.ai/documentation/images/connectors/service/ambassador/43Ym19QqoIQu2k2nGvxCQ_Group%2013.png)
Once you have added these fields to your Tray.io authentication pop-up window, click the 'Create authentication' button. 
Your connector authentication setup should now be complete.

## Ambassador Trigger

The Ambassador trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.

### Trigger Operations available:

* Webhook

### Webhook Setup

Select the Ambassador trigger. This can be done at the create new workflow stage or updated within the workflow builder itself.
Follow the instructions above to authenticate your trigger. Select 'Webhook' as the event you wish your trigger to listen to in order to set off the workflow itself.
![Ambassador - webhook](https://tray.ai/documentation/images/connectors/service/ambassador/2FpIQAdxsWLi4MXUaVlFnl_Screenshot%202022-07-29%20at%2015.04.16.png)
Ensure that you enter values in the format that the API is expecting, especially for fields with string inputs, such as 'Event type' and 'Notification type'.

## Available Operations

The examples below show one or two of the available connector operations in use.
Please see the [Full Operations Reference](#operationsFull) at the end of this page for details on all available operations for this connector.

## Using the Raw HTTP Request ('Universal Operation')

As of **version 1.0**, you can effectively create your own operations.
This is a powerful feature that you can use when there is an endpoint in Ambassador that is not used by any of our operations.
To use this, you will first of all need to research the endpoint in the Ambassador - [API documentation](https://docs.getambassador.com/reference/) v2 to **find the exact format** that Ambassador will be expecting the endpoint to be passed in.
For example, say that the List Group operation did not exist in our Ambassador connector, and you wanted to use this endpoint. You would use the
Ambassador API docs to find the relevant endpoint - ***which in this case is a `GET` request called: `/group/all`.***
More details about this endpoint can be found [here](https://docs.getambassador.com/reference/groupall).
![API CALL](https://tray.ai/documentation/images/connectors/service/ambassador/2mPDJeUuexFIGHFrPiUkVx_Screenshot%202022-06-28%20at%2016.28%201.png)
Based on the information provided in the above API call doc, you need to configure the following attributes on your Tray platform:

* **Method:** GET
* \*\*URL: \*\*
  * \*\*Endpoint : \*\*`/group/all`
    ![RAW HTTP operation on Tray platform](https://tray.ai/documentation/images/connectors/service/ambassador/43WawFIx7bBzjC9TitWqWg_Group%2022.png)
    Once the API call is executed successfully,  you should get the following results:
    ![RAW HTTP operation output on Tray platform](https://tray.ai/documentation/images/connectors/service/ambassador/4423PJYW8dJOnJDqyB3QeD_Group%2015.png)

## Example Usage

> **Info:** **TRAY POTENTIAL:** Tray is extremely flexible. By design there is no fixed way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors.

Below is an example of a way in which you could potentially use the Ambassador connector, to get information about a specific Ambassador
The overall logic of the workflow is:

1. Setup using a manual trigger and use the RawHTTP operation to list Ambassadors in your account.
2. Add the Loop collection connector to iterate over each individual Ambassador.
3. Gather the information available for each Ambassador.
   Your completed workflow should look similar to this:
   ![COMPLETED WORKFLOW](https://tray.ai/documentation/images/connectors/service/ambassador/5BzJme1LX4JYvtKj5tsi1L_Screenshot%202022-07-03%20at%2011.09%201.png)

### Step-by-step Explanation

### Manual Trigger

Once you have clicked 'Create new workflow' from your main Tray.io dashboard named it, select the Manual trigger from the trigger options available:
![Manual Trigger](https://tray.ai/documentation/images/connectors/service/ambassador/5RS1zxHf0sSp0YVbjmfNKb_Group%2017.png)

### RawHttp - List All Ambassador

After you have been redirected to the Tray.io workflow dashboard, from the connectors library on the left, add an Ambassador connector to your second step. Set the operation to `Raw HTTP Request`.
In this example, we are using the `Raw HTTP Request` operation because we currently do not have the `List ambassadors` operation in the connector.
Set the endpoint to `/ambassador/all`
![RawHttp List ](https://tray.ai/documentation/images/connectors/service/ambassador/6cLK7fzWVaBUhfJSJWy86E_Group%2023.png)
Feel free to re-name your steps as you go along to make things clearer for yourself and other users.
Now when this workflow is run, it will retrieve a list of contacts from the Ambassador API.

### Loop collection

Next, search for the 'Loop collection' connector within your connector panel, and drag it into your workflow as your next step. Set your operations to 'Loop list'.
The Loop Collection connector allows you to iterate through a list of results. In this example, we will use it to iterate through the data found within the previous Ambassador connector step.
In order to specify the list, you want to loop through, start by using the 'List' mapping icon (found next to the list input field, within the properties panel) to generate the connector-snake.
While hovering over the 'RawHttp - List All Ambassador' step (with the tail end of the connector-snake), select `ambassadors` from the list of output properties displayed. This will auto-populate a jsonpath within your 'List' input field, and update the type selector to jsonpath. The jsonpath should look like this `$.steps.ambassador-1.response.body.response.data.ambassadors`

> **Info:** **JSONPATHS:** For more information on what jsonpaths are and how to use jsonpaths with Tray, please see our pages on [Basic data concepts](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/basic-data-concepts) and [Mapping data between steps](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/mapping-data-between-steps)

> **Info:** \*\*CONNECTOR-SNAKE: \*\*The simplest and easiest way to generate your jsonpaths is to use our feature called the [Connector-snake](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/mapping-data-between-steps/#the-connector-snake). Please see the main page for more details.

![Loop collection](https://tray.ai/documentation/images/connectors/service/ambassador/3ZHJt6b8MHFLPg8X3emBVL_Group%2024.png)
This will enable us to iterate over the list of ambassadors, and perform operations for each one, during each loop cycle.

### Get Ambassador

The last step is to drag an Ambassador connector **inside** of the Loop Collection step itself. Set the operation to `Get ambassador`. As you can see, the `Customer email` field is required. Use the same connector-snake method for generating the JSON path to get the `email`.
![Get Ambassador](https://tray.ai/documentation/images/connectors/service/ambassador/6w6Mgr5H54uVED3tFKGDQk_Group%2025.png)
Now when this workflow is run, you will be able to gather the information available for each ambassador. This means you will be able to view the ambassador's details when you click through your debug panel and expand the output.
![Final output](https://tray.ai/documentation/images/connectors/service/ambassador/7nVSYpsRKD7xz0rJGyPWR4_Group%2021.png)

> **Info:** \*\*BEST PRACTICES: \*\*Whenever you do decide to create your own workflow, be sure to check out some of our key articles such as:- [Using callable workflows](https://tray.ai/documentation/platform/automation-integration/building-workflows/composable-workflows/calling-other-workflows)
> - [Pagination](https://tray.ai/documentation/platform/automation-integration/advanced-use-cases/batching-queueing/pagination)
> - [Data transformation guide](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/data-transformation-guide)