# impact.com Integrations Hub

The Integrations Hub offers technical context for the impact.com platform, fully optimized for the AI era. Use machine-readable docs, OpenAPI specs, and guided setup paths to build faster. Choose MCP, REST APIs, or Integration Guides based on how you plan to connect.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVbdCghMC6mw51rrphG6%2Fuploads%2FJLbhjPGtEbIEgm6u3QzF%2Fai-150-1.mp4?alt=media&token=7e826cf5-3afb-48b8-84ed-a6a3697c33b5>" %}

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><h4>MCP Server</h4></td><td>Start with MCP Quick Start if you use an AI tool.</td><td><a href="/pages/ZHOpWEHaknaj8nWohp3f">/pages/ZHOpWEHaknaj8nWohp3f</a></td><td><a href="/files/X3eZzPpZe5iRzsVUZNAS">/files/X3eZzPpZe5iRzsVUZNAS</a></td></tr><tr><td><h4>REST API Reference</h4></td><td>Select API Quick Start to make your first request.</td><td><a href="/pages/5fHRXFNPfxfwf7vWEuPi">/pages/5fHRXFNPfxfwf7vWEuPi</a></td><td><a href="/files/cZeblWAiuR2nH4LKy1fR">/files/cZeblWAiuR2nH4LKy1fR</a></td></tr><tr><td><h4>Integration Guides</h4></td><td>Use step-by-step guides to build and launch your integration.</td><td><a href="/pages/VjEahH3k7SqdUeBy9qL5">/pages/VjEahH3k7SqdUeBy9qL5</a></td><td><a href="/files/vZU3qnLmdkeA7CifQg7o">/files/vZU3qnLmdkeA7CifQg7o</a></td></tr></tbody></table>

{% tabs %}
{% tab title="MCP Server" %}
The impact.com MCP (Model Context Protocol) Server enables AI agents to interact directly with partnership data and workflows.

* Query partnership metrics and performance data.
* Manage contracts, tracking, and reporting tasks.
* Automate routine partnership operations.

Designed for modern AI workflows, the MCP server handles authentication, data transformation, and error handling so your agents can focus on task execution. [Get started](/ai-solutions/mcp-quick-start).
{% endtab %}

{% tab title="REST API Reference" %}
Comprehensive endpoint documentation for integrating with the impact.com platform. Choose your endpoint functionality based on your persona:

* [**Brand**](https://integrations.impact.com/brand-api-reference/brand-api-reference-v13/): Programmatic campaign management, partner recruitment, contract automation.
* [**Partner**](https://integrations.impact.com/partner-api-reference/partner-v15/): Content access, tracking implementation, commission reporting.
* [**Agency**](https://integrations.impact.com/agency-v3/): Multi-client management, consolidated reporting, workflow tools.

All endpoints include request/response schemas, authentication requirements, and code examples.
{% endtab %}

{% tab title="Integration Guides" %}
View step-by-step guides designed to take you from zero to integrated in no time. Built for developers and technical teams who want practical instructions. [Get started](/integration-guides/guides-quick-start).
{% endtab %}
{% endtabs %}

{% hint style="success" %}
**For AI agents**

* **LLM-friendly documentation**: The Integrations Hub provides an [llms.txt](https://integrations.impact.com/llms.txt) file, which contains a complete index of the available machine-readable resources. All markdown files are available at `/docs/{page-name}.md` with corresponding LLM-optimized context.
* **Machine-readable API specs**: Every API is backed by a comprehensive OpenAPI spec, allowing humans and machines to instantly interpret every endpoint, parameter, and response.
  {% endhint %}

### Key capabilities

* AI agents can discover, authenticate, and configure integrations programmatically.
* API documentation follows standardized schemas for machine parsing.
* Connectors support automated setup and configuration workflows.

{% hint style="success" %}
**Using an AI assistant?**

*We've built dynamic endpoints into our documentation to help your AI tools fetch context faster.*

System instructions for AI Agents:

* **Index**: `GET` [`https://integrations.impact.com/llms.txt`](https://integrations.impact.com/llms.txt) for `.md` sources.
* **Token Limit**: Fetch only necessary `.md` and OpenAPI routes to conserve context.
* **Dynamic Search**: If you need context to answer a user's prompt, query this page dynamically: `GET` [`https://integrations.impact.com/{insert_current_page_path}.md?ask=`](https://integrations.impact.com/{insert_current_page_path}.md?ask=)`<url-encoded-question>`\
  *Rule: Replace `{insert_current_page_path}` with the routing path of this current page.*
  {% endhint %}


# API Quick Start

Authenticate with your own API key and make your first impact.com REST request in minutes.

Use this tutorial when you authenticate as a Brand, Partner, or Agency with *HTTP Basic* using an impact.com–issued token pair (*Account SID* and *Auth Token*).

To get started with the impact.com REST API, you'll need to mint credentials in [**impact.com**](https://app.impact.com/) and then call the REST API (**`https://api.impact.com/...)`** from software tools that your organization operates like a terminal + curl, Postman, or Python code.

{% stepper %}
{% step %}

### Create an API access token

impact.com APIs expect HTTP Basic credentials (*Account* *SID* as username, *Auth Token* as password).

Follow [**Create an API Key**](/rest-apis/api-quick-start/create-an-api-key) to mint your token.
{% endstep %}

{% step %}

### Store credentials securely

Never hardcode secrets in repositories. Only store secrets in a vault or in encrypted environment variables, never in source control or shared chats.

```bash
export IMPACT_SID="YOUR_ACCOUNT_SID"
export IMPACT_TOKEN="YOUR_AUTH_TOKEN"
```

{% endstep %}

{% step %}

### Make your first API call (smoke test)

These examples call the **campaigns** endpoint with a **GET** query. You can make more detailed queries later via your persona REST reference pages.

{% tabs %}
{% tab title="Brand" %}

<pre class="language-bash"><code class="lang-bash"><strong>curl --get \
</strong>  "https://api.impact.com/Advertisers/{AccountSID}/Campaigns" \
  -u "{AccountSID}:{AuthToken}" \
  -H "Accept: application/json"
</code></pre>

```python
import os
import requests
from requests.auth import HTTPBasicAuth

sid = os.environ["AccountSID"]
tok = os.environ["AuthToken"]
url = f"https://api.impact.com/Advertisers/{sid}/Campaigns"
r = requests.get(url, auth=HTTPBasicAuth(sid, tok), headers={"Accept": "application/json"})
print(r.status_code)
```

{% endtab %}

{% tab title="Partner" %}

```bash
curl --get \
  "https://api.impact.com/Mediapartners/{AccountSID}/Campaigns" \
  -u "{AccountSID}:{AuthToken}" \
  -H "Accept: application/json"
```

```python
import os
import requests
from requests.auth import HTTPBasicAuth

sid = os.environ["AccountSID"]
tok = os.environ["AuthToken"]
url = f"https://api.impact.com/Mediapartners/{sid}/Campaigns"
r = requests.get(url, auth=HTTPBasicAuth(sid, tok), headers={"Accept": "application/json"})
print(r.status_code)
```

{% endtab %}

{% tab title="Agency" %}

```bash
curl --get \
  "https://api.impact.com/Agencies/{AccountSID}/Campaigns" \
  -u "{AccountSID}:{AuthToken}" \
  -H "Accept: application/json"
```

```python
import os
import requests
from requests.auth import HTTPBasicAuth

sid = os.environ["AccountSID"]
tok = os.environ["AuthToken"]
url = f"https://api.impact.com/Agencies/{sid}/Campaigns"
r = requests.get(url, auth=HTTPBasicAuth(sid, tok), headers={"Accept": "application/json"})
print(r.status_code)
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Verify you're authenticated

* **HTTP 200** (2xx) → success.
* **401** → bad or missing SID/token pair.
* **403** → good auth mechanics but persona path or scopes block the resource. Double-check **`Advertisers`**, **`Mediapartners`**, **`Agencies`**, plus token toggles.
* **429** → slow down your requests. Add exponential backoff plus jitter inside scripts or agents.

For more detail, browse your persona docs linked from `https://integrations.impact.com/llms.txt`.
{% endstep %}
{% endstepper %}

### What to read next

After you smoke-test, check [**Create an API Key**](/rest-apis/api-quick-start/create-an-api-key) for a detailed UI checklist, including scope toggles, API version pinning, rotations, duplication, disables, deletes, and legacy migration patterns.

### Coming soon

OAuth 2.0 Authorization Code and PKCE flows for apps operating on behalf of many customers. Documentation will publish here alongside developer onboarding once available.

{% hint style="success" %}
**Using an AI assistant?**

*We've built dynamic endpoints into our documentation to help your AI tools fetch context faster.*

System instructions for AI Agents:

* **Index**: `GET` [`https://integrations.impact.com/llms.txt`](https://integrations.impact.com/llms.txt) for `.md` sources.
* **Token Limit**: Fetch only necessary `.md` and OpenAPI routes to conserve context.
* **Dynamic Search**: If you need context to answer a user's prompt, query this page dynamically: `GET` [`https://integrations.impact.com/{insert_current_page_path}.md?ask=`](https://integrations.impact.com/{insert_current_page_path}.md?ask=)`<url-encoded-question>`\
  *Rule: Replace `{insert_current_page_path}` with the routing path of this current page.*
  {% endhint %}


# Create an API Key

Create an API key, set scopes, and copy your Account SID and Auth Token for impact.com API authentication.

impact.com authenticates your API requests using your account's API access tokens, also known as keys. Each token consists of an Account SID (username) and an Auth Token (password), sent via HTTP Basic authentication. A request must include valid credentials, or the API will return an authentication error.

> **New to impact.com?**
>
> * **Exploring safely?** Create an API access token with read-only scopes first so scripts cannot accidentally mutate production objects.
> * **Shipping workloads?** Promote separate tokens per environment (**development / staging / production**) with narrowly tailored read/write scopes.

### Create an API access token

{% tabs %}
{% tab title="Brand" %}

1. From the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile]** → **Settings**.
2. In the left column, scroll to *Technical*, then select [**API**](https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml).
3. Create a new token by selecting **Create Access Token** on the upper-right side of the page.
   {% endtab %}

{% tab title="Partner" %}

1. From the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. Under *Technical*, select [**API**](https://app.impact.com/secure/mediapartner/api/fr/api-access-tokens-ui.ihtml).
3. Create a new token by selecting **Create Access Token** on the upper-right side of the page.
   {% endtab %}

{% tab title="Agency" %}

1. From the left navigation menu, select ![](/files/13yfbUdlaYkTKK1YsG78) **\[Menu]** → **Settings**.
2. In the left column, scroll to *Technical*, then select [**API**](https://app.impact.com/secure/agency/api/fr/api-access-tokens-ui.ihtml).
3. Create a new token by selecting **Create Access Token** on the upper-right side of the page.
   {% endtab %}
   {% endtabs %}

#### Configure the token

1. Enter a Token Name and Description that describes the purpose of the token.
2. Select the API Version the token will be compatible with. Use the latest version (the default) unless you have a specific reason not to.
3. Select **Next**.
4. Optionally, add email addresses for developers who should receive updates about the token. Select a Primary Contact from the dropdown.
5. Select **Next**.
6. Toggle API categories on and select the access scopes you want to allow. Use **Clear All** to start from scratch.
7. Select **Create**.

Your new token's Account SID and Auth Token are now available on the token's detail page.

### Get your API credentials

1. From the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile]** → **Settings**.
2. Navigate to **Technical** → **API**.
3. Select your access token's card to see its details.
4. Select **API Credentials** from the left navigation.
5. Copy the `Account SID` and `Auth Token`.

Each access token provides two credential values:

<table><thead><tr><th width="145.16796875">Credential</th><th>Purpose</th><th>Equivalent</th></tr></thead><tbody><tr><td><code>Account SID</code></td><td>Uniquely identifies your token. Used as the HTTP Basic username.</td><td>Similar to a public API key</td></tr><tr><td><code>Auth Token</code></td><td>The secret credential. Used as the HTTP Basic password.</td><td>Similar to a secret API key</td></tr></tbody></table>

### How authentication works

impact.com uses [HTTP Basic authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme). Your Account SID is the username and your Auth Token is the password. Base64-encode the pair and send it in the `Authorization` header:

Authorization: Basic base64(AccountSID:AuthToken)

All API requests are scoped to your account type.

{% tabs %}
{% tab title="Brand" %}
As a Brand, your API base path is:

```html
https://api.impact.com/Advertisers/{AccountSID}/
```

{% endtab %}

{% tab title="Partner" %}
As a Partner, your API base path is:

```html
https://api.impact.com/Mediapartners/{AccountSID}/
```

{% endtab %}

{% tab title="Agency" %}
As an Agency, your API base path is:

```html
https://api.impact.com/Agencies/{AccountSID}/
```

{% endtab %}
{% endtabs %}

**Example:**

{% tabs %}
{% tab title="Brand" %}
**Make your first API call as a Brand**

```bash
curl -X GET "https://api.impact.com/Advertisers/{AccountSID}/Campaigns" \
  -u "YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN"
```

In Python:

```python
import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    "https://api.impact.com/Advertisers/{AccountSID}/Campaigns",
    auth=HTTPBasicAuth("YOUR_ACCOUNT_SID", "YOUR_AUTH_TOKEN"),
)
```

{% endtab %}

{% tab title="Partner" %}
**Make your first API call as a Partner**

```bash
curl -X GET "https://api.impact.com/Mediapartners/{AccountSID}/Campaigns" \
  -u "YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN"
```

In Python:

```python
import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    "https://api.impact.com/Mediapartners/{AccountSID}/Campaigns",
    auth=HTTPBasicAuth("YOUR_ACCOUNT_SID", "YOUR_AUTH_TOKEN"),
)
```

{% endtab %}

{% tab title="Agency" %}
**Make your first API call as an Agency**

```bash
curl -X GET "https://api.impact.com/Agencies/{AccountSID}/Campaigns" \
  -u "YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN"
```

In Python:

```python
import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    "https://api.impact.com/Agencies/{AccountSID}/Campaigns",
    auth=HTTPBasicAuth("YOUR_ACCOUNT_SID", "YOUR_AUTH_TOKEN"),
)
```

{% endtab %}
{% endtabs %}

#### Key types

impact.com offers two types of API tokens:

<table><thead><tr><th width="169.66015625">Type</th><th>Description</th></tr></thead><tbody><tr><td>Access tokens (current)</td><td>Created from April 2025 onwards. Each token has a custom name, description, API version, and individually configured access scopes. You can create multiple tokens with different permissions for different integrations.</td></tr><tr><td>Legacy tokens (pre-April 2025)</td><td>Older tokens that come in read/write and read-only pairs. These can be upgraded to the current token format. If you have legacy tokens, consider migrating to access tokens for finer-grained control.</td></tr></tbody></table>

> **Legacy tokens**
>
> Tokens created before April 2025 are considered legacy tokens. You can continue using them, but they only offer read/write and read-only permission levels. To get finer-grained scope control, upgrade your legacy token or create a new access token. See Manage legacy tokens below.

### Access scopes

impact.com access tokens support granular scope control. When creating a token, you toggle individual API categories on or off, then select specific read or write permissions within each category.

This means you can create a token that only has access to, say, Campaigns (read) and Conversions (read/write), while having no access to account settings, reports, or partner data.

Recommended approach: Create separate tokens for each integration or service, each with the minimum scopes required. This limits the blast radius if a token is compromised.

### Protect your keys

Anyone with your Auth Token can make API calls on behalf of your account, up to the scopes granted to that token. Protect your credentials by following these best practices:

* Use scoped tokens instead of full-access tokens. Create tokens with only the permissions your integration actually needs.
* Create separate tokens for each integration, service, or environment (development, staging, production). This way you can revoke one without affecting others.
* Store credentials in a secrets vault or encrypted environment variables. Never store tokens in source code, configuration files, or version control.
* Reset tokens when team members with access leave your organisation or change roles.
* Disable unused tokens rather than leaving them active. You can re-enable them later if needed.
* Don't share credentials over email, chat, or other unencrypted channels.

### Manage access tokens

You can manage your tokens as follows.

{% tabs %}
{% tab title="Brand" %}

1. From the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile]** → **Settings**.
2. In the left column, scroll to *Technical*, then select [**API**](https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml).
3. Create a new token by selecting **Create Access Token** on the upper-right side of the page.
   {% endtab %}

{% tab title="Partner" %}

1. From the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile]** → **Settings**.
2. Under *Technical*, select [**API**](https://app.impact.com/secure/mediapartner/api/fr/api-access-tokens-ui.ihtml).
3. Create a new token by selecting **Create Access Token** on the upper-right side of the page.
   {% endtab %}

{% tab title="Agency" %}

1. From the left navigation menu, select ![](/files/13yfbUdlaYkTKK1YsG78) **\[Menu]** → **Settings**.
2. In the left column, scroll to *Technical*, then select [**API**](https://app.impact.com/secure/agency/api/fr/api-access-tokens-ui.ihtml).
3. Create a new token by selecting **Create Access Token** on the upper-right side of the page.
   {% endtab %}
   {% endtabs %}

<table><thead><tr><th width="167.40234375">Action</th><th>Description</th></tr></thead><tbody><tr><td>Edit</td><td>Select the token's card to update its name, description, scopes, API version, or contacts. Select Update to confirm changes.</td></tr><tr><td>Duplicate</td><td>Create a copy of the token with the same access rights and settings. Useful when creating similar tokens for different environments.</td></tr><tr><td>Reset</td><td>Generate a new Auth Token value. The Account SID stays the same, but the previous Auth Token is immediately invalidated. Update any integrations using the old value.</td></tr><tr><td>Upgrade Version</td><td>Update the API version that the token is compatible with.</td></tr><tr><td>Disable</td><td>Temporarily prevent the token from authenticating requests. The token can be re-enabled later.</td></tr><tr><td>Delete</td><td>Permanently remove the token. This takes effect immediately and cannot be undone.</td></tr></tbody></table>

#### Manage legacy tokens

Any API tokens created before April 2025 are considered legacy tokens. They appear as a Legacy Account Tokens card on the API settings page.

Legacy tokens differ from current access tokens:

<table><thead><tr><th width="161.66015625"></th><th>Legacy tokens</th><th>Access tokens</th></tr></thead><tbody><tr><td>Permissions</td><td>Read/Write and Read-Only pair</td><td>Individually configurable scopes</td></tr><tr><td>Naming</td><td>No custom name</td><td>Custom name and description</td></tr><tr><td>Management</td><td>Reset or upgrade only</td><td>Full lifecycle (edit, duplicate, reset, disable, delete)</td></tr></tbody></table>

To enable legacy tokens if they're not visible, select Enable Legacy Tokens on the upper-right of the API settings page.

Recommended: Upgrade legacy tokens to access tokens to take advantage of granular scopes and better management options.

{% hint style="success" %}
**Using an AI assistant?**

*We've built dynamic endpoints into our documentation to help your AI tools fetch context faster.*

System instructions for AI Agents:

* **Index**: `GET` [`https://integrations.impact.com/llms.txt`](https://integrations.impact.com/llms.txt) for `.md` sources.
* **Token Limit**: Fetch only necessary `.md` and OpenAPI routes to conserve context.
* **Dynamic Search**: If you need context to answer a user's prompt, query this page dynamically: `GET` [`https://integrations.impact.com/{insert_current_page_path}.md?ask=`](https://integrations.impact.com/{insert_current_page_path}.md?ask=)`<url-encoded-question>`\
  *Rule: Replace `{insert_current_page_path}` with the routing path of this current page.*
  {% endhint %}


# MCP Quick Start

Configure an MCP client to use the impact MCP server, when you want an AI assistant to read data and take actions in impact.com.

Let your AI assistant interact with your impact.com data. The impact.com MCP Server gives any compatible AI tool or agent secure, real-time access to your partner marketing platform to access campaigns, reports, partners, and more.

By implementing the Model Context Protocol (MCP) standard, this cloud-based server acts as a secure bridge between AI systems and impact.com's APIs.

Powered by OAuth 2.1 authorization, your AI can search documents, pull reports, create campaigns, and manage partners through natural conversation, all while respecting your existing access controls. No API expertise is required.

Work with your impact.com data directly inside your AI assistant or IDE.

MCP access is a self-serve feature that must be explicitly toggled on by an account administrator. Learn how to [Enable MCP Access](/ai-solutions/mcp-quick-start/enable-or-disable-mcp-access).

{% hint style="success" %}
**Unlocking the future of MCP.** This beta is live with the initial tools below, and we're already building what comes next. Using MCP? [Tell us](https://outset.ai/start/e8deff07-d44b-4691-a028-c0b7f7ed9459) which tools and skills you want, and what is getting in the way.
{% endhint %}

### What You Can Do

With the impact.com MCP Server, you can:

* **Query your data**: Search and summarize information from your impact.com account using natural language.
* **Create and update**: Execute actions like creating campaigns, updating settings, or managing partners through simple commands.
* **Automate workflows**: Streamline repetitive tasks without leaving your development environment.

The impact.com MCP Server is built for developers automating workflows, analysts pulling reports, partnership managers updating campaigns, and any team that wants intelligent access to their impact.com data without leaving their tools. The server is available at `https://mcp.impact.com/mcp` and is ready to accept connections.

### How It Works

Getting started is simple:

* **Select authenticate**: Initiate the connection from your AI assistant or IDE.
* **Review and approve**: A consent screen displays the permissions being requested.
* **Secure token created:** Upon approval, an MCP usage token is installed in your impact.com account and securely returned to your AI assistant.

Your AI assistant now has access to interact with your impact.com data using your specific user permissions.

### Security & Authentication

The impact.com MCP Server uses OAuth 2.1 authorization to ensure all actions respect your existing access controls. Your credentials are never shared directly with the AI assistant. Only a secure, revocable token is used.

A separate MCP usage token is issued per LLM client, so connecting Claude, ChatGPT, Cursor, VS Code and others each produces its own token, scoped to your specific user permissions. A refresh token is also issued, so the AI assistant can renew access without prompting you to log in again on every session.

#### Account-Level Controls (Administrators)

An account administrator can disable MCP for the whole account at any time. This is an all-or-nothing setting and is not configurable per user.

1. Sign in to impact.com.
2. Navigate to ![](/files/14Id0ZaHhZaXJqnqrPMG) **\[User Profile] → Settings → Tools → MCP**.
3. Disable MCP for the account.

When MCP is disabled at the account level, no user on that account will be able to complete the consent step described below.

{% hint style="warning" %}
**Disabling MCP deletes existing tokens.**

When you disable MCP for an account that has one or more MCP usage tokens already minted, *all of those tokens will be deleted* and every connected AI assistant will lose access immediately.

To avoid accidents, impact.com asks you to tick a confirmation checkbox acknowledging this before the change is saved. If the account has no MCP usage tokens minted yet, the checkbox will not be shown and you can disable MCP directly.
{% endhint %}

Administrators can also revoke any individual MCP usage token at any time, using the same steps described in [Disconnect or Revoke Access](#disconnect-or-revoke-access). Revoking a token immediately invalidates that LLM's access; the user will need to consent again before the LLM can call any impact.com tools.

### Connect Your Account

Follow these steps to connect your impact.com account to an LLM for MCP integration:

{% stepper %}
{% step %}

### Configure impact.com MCP

Follow our setup guides for specific clients:

* [Cursor](/ai-solutions/mcp-quick-start/mcp-for-cursor)
* [Visual Studio Code](/ai-solutions/mcp-quick-start/mcp-for-vs-code)
* [Claude Code](/ai-solutions/mcp-quick-start/mcp-for-claude-desktop-and-claude-code)

For other supported clients, refer to your platform's MCP documentation or built-in assistant for connection instructions.
{% endstep %}

{% step %}

### Initiate Connection

Where necessary, grant the MCP access to your account, and review the permissions as they're requested.
{% endstep %}

{% step %}

### Grant Consent

Review the permissions being requested, then approve access through the consent screen.
{% endstep %}

{% step %}

### Token Installation

Upon approval, an MCP usage token is automatically created and stored in your impact.com account.

This token is securely returned to your AI assistant, enabling it to access impact.com data and perform actions on your behalf using your specific permissions.

The AI assistant has access to refresh the token which means that you don't have to authenticate each time. A separate token is issued for each LLM client you connect.
{% endstep %}
{% endstepper %}

### Disconnect or Revoke Access

You maintain full control over the connection. Because a separate token is issued per LLM client, you can disconnect one AI assistant without affecting any of the others. See [Enable or Disable MCP Access](/ai-solutions/mcp-quick-start/enable-or-disable-mcp-access) for more information.

{% hint style="success" %}
**Using an AI assistant?**

*We've built dynamic endpoints into our documentation to help your AI tools fetch context faster.*

System instructions for AI Agents:

* **Index**: `GET` [`https://integrations.impact.com/llms.txt`](https://integrations.impact.com/llms.txt) for `.md` sources.
* **Token Limit**: Fetch only necessary `.md` and OpenAPI routes to conserve context.
* **Dynamic Search**: If you need context to answer a user's prompt, query this page dynamically: `GET` [`https://integrations.impact.com/{insert_current_page_path}.md?ask=`](https://integrations.impact.com/{insert_current_page_path}.md?ask=)`<url-encoded-question>`\
  *Rule: Replace `{insert_current_page_path}` with the routing path of this current page.*
  {% endhint %}


# MCP for Cursor

Install impact.com MCP in Cursor.

The impact.com Model Context Protocol (MCP) Server integrates directly with Cursor, giving you AI-powered access to your partnership data without leaving your editor. Choose between a one-click install or manual configuration.

## One-click install

Select [this link](https://cursor.com/en/install-mcp?name=impact%20MCP\&config=eyJ1cmwiOiJodHRwczovL21jcC5pbXBhY3QuY29tL21jcCIsImF1dGgiOnsiQ0xJRU5UX0lEIjoibWNwLWltcGFjdC1jdXJzb3IiLCJzY29wZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJtY3A6cmVhZCIsIm1jcDp3cml0ZSJdfSwiaGVhZGVycyI6e319) to open Cursor and add the server automatically.

To learn more, see the [Cursor documentation](https://cursor.com/docs/mcp).

## Manual configuration

Add this to `~/.cursor/mcp.json`:

{% tabs %}
{% tab title="JSON" %}

```json
{
  "mcpServers": {
    "impact MCP": {
      "url": "https://mcp.impact.com/mcp",
      "auth": {
        "CLIENT_ID": "mcp-impact-cursor",
        "scopes": [
          "offline_access",
          "mcp:read",
          "mcp:write"
        ]
      },
      "headers": {}
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Manage tool permissions

<details>

<summary>How do I manage tool permissions in Cursor?</summary>

Connecting mcp.impact.com authorizes Cursor to call supported tools within your existing impact.com permissions. Separately, Cursor may ask you to approve each tool call, or remember that approval. Those prompts are controlled by Cursor, not by impact.com.

#### **Steps**

1. When the agent wants to use an impact.com MCP tool, review the prompt and approve or deny.
2. To change how often you are asked: open **Cursor Settings → Agents → Approvals & Execution** and choose a run mode (for example, **Auto-review** or **Allowlist**).
3. To let trusted MCP tools run without prompting, add them to the MCP allowlist from that settings area, or choose **Add to allowlist** when prompted.
4. Optionally, enable or disable an MCP server from the tools list in chat.
   1. Select **Customize**, then the tools list at the top of the chat panel.

Denying a prompt blocks that call in Cursor. It does not change your impact.com account permissions or the account-level MCP enablement setting.

</details>


# MCP for VS Code

Install impact.com MCP in VS Code.

The impact.com Model Context Protocol (MCP) Server integrates directly with Visual Studio Code, giving you AI-powered access to your partnership data without leaving your editor. Choose between a one-click install or manual configuration.

Follow these steps to configure and connect the impact Model Context Protocol (MCP) to your VS Code environment:

## One-click install

1. Use the [**quick link**](vscode:mcp/install?%7B%22name%22%3A%22impact%20MCP%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.impact.com%2Fmcp%22%2C%22oauth%22%3A%7B%22clientId%22%3A%22mcp-impact-vscode%22%2C%22scopes%22%3A%5B%22offline_access%22%2C%22mcp%3Aread%22%2C%22mcp%3Awrite%22%5D%7D%7D) to easily configure the impact MCP in VS Code.
2. After you select the link, you'll be redirected to VS Code.
3. Agree to install the impact.com MCP.
   * Recommended: installing it for your workspace.
4. From **VS Code Settings**, select **MCP Servers**.
5. Connect your impact.com account.
6. You will be redirected to the [impact.com](http://impact.com/) login page, where you need to authorize the impact MCP in VS Code to access your impact account.
7. Once authorized, it will redirect you back to VS Code.
   * Troubleshooting note: VS Code might prompt you to "try a different way." Select **yes**. It will redirect you back to [impact.com](http://impact.com/) but will not require you to log in again. You can expect to be redirected back to VS Code.
8. VS Code will then retrieve a list of tools.
9. You are now ready to use the MCP tools!

To learn more, see the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).

## Manual configuration

Add this to `.vscode/mcp.json` in your workspace:

{% tabs %}
{% tab title="JSON" %}

```json
{
	"servers": {
		"impact MCP": {
			"type": "http",
			"url": "https://mcp.impact.com/mcp",
			"oauth": {
				"clientId": "mcp-impact-vscode",
				"scopes": [
					"offline_access",
					"mcp:read",
					"mcp:write"
				]
			}
		}
	},
	"inputs": []
}
```

{% endtab %}
{% endtabs %}

### Manage tool permissions

<details>

<summary>How do I manage tool permissions in VS Code?</summary>

Connecting mcp.impact.com authorizes VS Code to call supported tools within your existing impact.com permissions. Separately, VS Code may ask you to approve each tool call, or remember that approval. Those prompts are controlled by VS Code, not by impact.com.

#### Steps

1. When Copilot Chat or the agent needs an MCP tool, review the confirmation dialog (tool name and parameters) and approve or deny.
2. To manage saved approvals: open the Command Palette and run **Chat: Manage Tool Approval**.&#x20;
   1. Tools are grouped by MCP server. Adjust per tool, or trust all tools from a specific server.
3. To change session autonomy: use the permissions dropdown in the chat input (**Default Approvals**, **Bypass Approvals**, or **Autopilot**).&#x20;
   1. Prefer **Default Approvals** for day-to-day use.
4. To clear saved approvals: open the Command Palette and run **Chat: Reset Tool Confirmations**.

Denying a prompt blocks that call in VS Code. It doesn't change your impact.com account permissions or the account-level MCP enablement setting.

</details>


# MCP for Claude Desktop & Claude Code

Install impact.com MCP in Claude Desktop and Claude Code.

This guide explains how to install and configure the impact.com MCP server in Claude Desktop and Claude Code.

### Overview

Claude Desktop offers either a built-in connector UI (recommended) or a JSON configuration file. Claude Code is configured via a CLI or the same JSON configuration used by Claude Desktop.

The impact.com MCP endpoint is `https://mcp.impact.com/mcp`. Authentication uses OAuth 2.1 with PKCE against `app.impact.com`.

### Installation Steps for Claude Desktop

Follow these steps to install in Claude Desktop (the graphical application). To install in Claude Code (CLI) instead, jump to the Claude Code section.

Claude Desktop offers two ways to add the impact.com MCP server. The first is a few clicks in the UI; the second is a JSON file for users who need finer control.

**Option 1: Add via the Claude Desktop UI (recommended)**

Recent versions of Claude Desktop have built-in support for remote OAuth MCP servers. No Node.js, no mcp-remote, no config file required.

{% stepper %}
{% step %}

### Open the connector settings

1. Open **Claude Desktop**.
2. Click **Customize** in the top-left navigation.
3. Click **Connectors**.
   {% endstep %}

{% step %}

#### Add the impact.com connector

1. Click the **+** button to add a connector.
2. Click **Add custom connector**.
3. Give the connector a **Name**, for example, `impact`.
4. Enter the **MCP URL**: `https://mcp.impact.com/mcp`.
5. Expand **Advanced settings**.
6. In **OAuth Client ID**, enter `mcp-impact-claude`.
7. Click **Add**.

{% hint style="info" %}
**Why the OAuth Client ID is required**

impact.com's authorization server doesn't currently support Dynamic Client Registration (RFC 7591), so Claude can't register itself on the fly. You need to provide a pre-registered `client_id`. `mcp-impact-claude` is the public client ID issued for the Claude integration.
{% endhint %}
{% endstep %}

{% step %}

### Authenticate with impact.com

1. Click **Connect** next to the `impact` connector. Your browser opens to `https://app.impact.com/oauth2/authorize?...`.
2. Log in to impact.com if you aren't already signed in.
3. Review the requested permissions (`profile`, `offline_access`) and click **Allow**.
4. Your browser is redirected back to Claude Desktop. The connector status should change to **Connected**.
   {% endstep %}

{% step %}

#### Try it in a chat

In a new conversation, ask something that uses the connector, for example:

> *"Use the impact MCP to get website metrics for ebay.com."*

Claude will discover the available tools, prompt you to approve the first call, and return the result.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**When to use this option**

This is the right path for almost everyone. It avoids the Node.js prerequisite and the OAuth-completion-vs-`initialize`-timeout issue that can affect the `mcp-remote` bridge on first-time setup.
{% endhint %}

**Option 2: JSON configuration via `mcp-remote` (advanced)**

Use this option if you need to pin a specific `client_id`, override scopes, share a single configuration across multiple machines, or are running an older Claude Desktop version that doesn't yet include the connector UI.

{% stepper %}
{% step %}

### Locate the config file

| Platform    | File Path                                                         |
| ----------- | ----------------------------------------------------------------- |
| **macOS**   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json`                     |

If the file doesn't exist, create it with the content shown in the next step.
{% endstep %}

{% step %}

### Edit the configuration

Add the impact.com server to the `mcpServers` object:

```json
{
  "mcpServers": {
    "impact MCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.impact.com/mcp",
        "--static-oauth-client-info",
        "{\"client_id\":\"mcp-impact-claude\"}",
        "--static-oauth-client-metadata",
        "{\"scope\":\"offline_access mcp:read mcp:write\",\"redirect_uris\":[\"http://localhost/oauth/callback\"],\"token_endpoint_auth_method\":\"none\"}"
      ]
    }
  }
}
```

{% hint style="warning" %}
**Prerequisite:** Claude Desktop relies on `npx` (from Node.js) to run `mcp-remote`. Install Node.js 18+ from [nodejs.org](https://nodejs.org) if it isn't already on your machine.
{% endhint %}

{% hint style="danger" %}
**Security:** The config file lives in your user directory, not your project directory. Don't commit it to version control. No credentials are stored in this file. Tokens are cached separately in `~/.mcp-auth/` after the OAuth flow.
{% endhint %}
{% endstep %}

{% step %}

### Restart Claude Desktop

1. Quit Claude Desktop completely. Don't just close the window. Exit the application fully.
2. Reopen Claude Desktop.
3. Go to **Settings → Developer → MCP Servers**.
4. Verify `impact` appears in the list with status `starting` or `running`.
   {% endstep %}

{% step %}

### Authenticate with impact.com

After Claude Desktop starts the server, authenticate with your impact.com account.

1. Select the `impact MCP` server in the MCP Servers list.
2. Select **Connect** or send a message that triggers a tool call — either action starts the OAuth flow.
3. Your browser opens to `https://app.impact.com/oauth2/authorize?...`.
4. Log in to impact.com if needed, then select **Allow** on the consent screen.
5. Return to Claude Desktop. The `impact MCP` server status should change to `connected`.
   {% endstep %}

{% step %}

### Verification

Open a new chat and ask:

> *"Using the impact connector, list available tools."*

Claude should respond with the MCP tools exposed by impact.com and be able to call them.
{% endstep %}
{% endstepper %}

### Installation Steps for Claude Code

Follow these steps for Claude Code (CLI) installation. To install in Claude Desktop instead, jump to the [Claude Desktop](#installation-steps-for-claude-desktop) section.

{% stepper %}
{% step %}

### Add the impact.com MCP Server

You can add the impact.com MCP server using the Claude Code command-line interface. Claude Code uses the `mcp-remote` bridge under the hood to connect Claude (a local app) to a remote HTTPS MCP server like impact.com.

Choose one of the following options.

**Option 1: Use the `claude mcp add` command (recommended)**

This command registers the server with default settings and uses `mcp-remote` automatically:

{% tabs %}
{% tab title="Shell" %}

```bash
claude mcp add --transport http \
  impact https://mcp.impact.com/mcp
```

{% endtab %}
{% endtabs %}

**Option 2: JSON configuration via `mcp-remote` (more control)**

If you need to set a specific `client_id`, override scopes, or pin the loopback callback path, edit `~/.claude.json` directly:

{% tabs %}
{% tab title="JSON" %}

```json
{
  "mcpServers": {
    "impact MCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.impact.com/mcp",
        "--static-oauth-client-info",
        "{\"client_id\":\"mcp-impact-claude\"}",
        "--static-oauth-client-metadata",
        "{\"scope\":\"offline_access mcp:read mcp:write\",\"redirect_uris\":[\"http://localhost/oauth/callback\"],\"token_endpoint_auth_method\":\"none\"}"
      ]
    }
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Why these flags are needed**

impact.com's authorization server doesn't currently support Dynamic Client Registration (RFC 7591), so `mcp-remote` cannot register a client on the fly.

* The `--static-oauth-client-info` flag tells `mcp-remote` to use the pre-registered `mcp-impact-claude` client.
* The `--static-oauth-client-metadata` flag scopes the request to `profile offline_access` (the scopes impact.com publishes) and pins the loopback callback to `http://localhost/oauth/callback`.
  {% endhint %}

{% hint style="warning" %}
**Use `localhost`, not `127.0.0.1`**

The callback uses `http://localhost/...` rather than `http://127.0.0.1/...`.

The `client_id` and PKCE proof are what actually secure the flow; `localhost` works the same, and is what `mcp-remote` will bind to.
{% endhint %}

**Project-scoped configuration**

If you want the MCP server available only within a specific project, put the same `mcpServers` block in `.mcp.json` at the project root instead of `~/.claude.json`.

***

{% endstep %}

{% step %}

### Authenticate with impact.com

After adding the server, authenticate with your impact.com account.

1. In Claude Code, type `/mcp` and press **Enter**.
2. Select `impact` from the list of available MCP servers.
3. Claude Code starts `mcp-remote`, which opens your browser to `https://app.impact.com/oauth2/authorize?...`.
4. If you're not already signed in, log in to your impact.com account.
5. Review the requested permissions (`offline_access`, `mcp:read`, `mcp:write`) and click **Allow**.
6. Your browser is redirected to `http://localhost:<port>/oauth/callback`, where `mcp-remote` captures the authorization code and exchanges it for tokens.
7. Tokens are cached in `~/.mcp-auth/` and refreshed automatically by `mcp-remote`.
   {% endstep %}

{% step %}

### Verification

Verify the impact.com MCP server is connected:

```bash
claude mcp list
```

You should see `impact MCP` with status `connected` and a non-zero tool count.

In a chat, you can also ask:

> *"List the tools available from the impact connector."*

Claude should enumerate the MCP tools exposed by impact.com, for example:

* `get_website_metrics`
* `list_partners`
  {% endstep %}
  {% endstepper %}

### What you can do

Once connected, you can ask Claude to:

* **Look up website metrics:** *"Get impact.com website metrics for youtube.com."*
* **Query company information:** *"Use the impact connector to fetch my company information."*
* **List media partners:** *"Show me my impact.com media partners."*
* **Inspect catalogs and invoices:** *"Pull my advertiser catalogs from impact.com."*

The exact tool set depends on which tools impact.com's MCP server exposes. Claude will discover them automatically on connect.

<details>

<summary>How do I manage tool permissions in Claude Code?</summary>

Connecting mcp.impact.com authorizes Claude Code to call supported tools within your existing impact.com permissions. Separately, Claude Code may ask you to approve each tool call, or remember that approval. Those prompts are controlled by Claude Code, not by impact.com.

#### **Steps**

1. When Claude Code prompts to use an impact.com MCP tool, approve once, or choose the option to remember the choice when offered.
2. To review or change rules: run `/permissions` and set **Allow**, **Ask**, or **Deny** for the relevant MCP tools.
3. To see connected MCP servers and tools: run `/mcp`.
4. Permission modes (for example, Manual, Auto, or Bypass) change how often you are prompted. Use bypass modes only in environments you trust.

Denying a prompt blocks that call in Claude Code. It does not change your impact.com account permissions or the account-level MCP enablement setting.

</details>

### Notes

* **OAuth Discovery:** Claude (via the connector UI or mcp-remote) follows the MCP authorization spec. It reads `WWW-Authenticate` from the initial 401, fetches `https://app.impact.com/.well-known/oauth-protected-resource`, then `https://app.impact.com/.well-known/oauth-authorization-server`, and constructs the authorize URL automatically.
* **Token lifetime:** Access tokens are short-lived (5 minutes). Refresh tokens (90-day lifetime) are used to refresh them silently, so you should only see the consent screen once per device.
* **Re-authenticating (Claude Desktop UI connector):** Open **Customize → Connectors**, click the `impact` connector, and choose **Disconnect** then **Connect** again.
* **Re-authenticating(Claude Code / Desktop JSON config):** To force a fresh login, delete the cached tokens: `rm -rf ~/.mcp-auth/` and restart Claude.

### Troubleshooting

<details>

<summary><strong>Server not appearing in the list</strong></summary>

| Client                           | Solution                                                                                                       |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Claude Desktop                   | Open **Customize → Connectors** and confirm the entry exists. If it doesn't, re-add it via *Option 1*.         |
| Claude Desktop (JSON / advanced) | Check JSON syntax with `jq . < claude_desktop_config.json` or paste into [jsonlint.com](https://jsonlint.com). |
| Claude Code                      | Run `claude mcp list` to verify the registration.                                                              |

For the JSON-based setup, also check Claude Desktop's MCP logs at `~/Library/Logs/Claude/mcp*.log` (macOS) for spawn errors, most commonly `npx not found`, meaning Node.js isn't installed or isn't on your `PATH`.

</details>

<details>

<summary><strong>Authentication fails after consent</strong></summary>

* Confirm that the `client_id` in your config (or in the UI's **Advanced settings**) is exactly `impact-mcp-claude` for Claude Desktop or Claude Code.
* Confirm that you can reach `https://app.impact.com` from your browser (some corporate networks block it).
* Delete cached tokens and retry: `rm -rf ~/.mcp-auth/`, then start a fresh flow. (For the Claude Desktop UI connector, use **Disconnect** → **Connect** instead.)
* Check Claude's MCP log for the actual error from `mcp-remote` (usually `invalid_redirect_uri`, `invalid_scope`, or `invalid_client`).

</details>

<details>

<summary><strong>"Incompatible auth server: does not support dynamic client registration"</strong></summary>

This message means you're using **Option 1: `claude mcp add`** without the static-client flags.

impact.com's authorization server doesn't support Dynamic Client Registration, so you must pass a pre-registered `client_id` via:

`--static-oauth-client-info`

Switch to the **Option 2: JSON configuration** snippet above and retry.

</details>

<details>

<summary><strong>Connection drops after a few minutes</strong></summary>

Access tokens last 5 minutes. If `mcp-remote` (or the Claude Desktop UI connector) can't refresh them silently, for example, because the refresh token was revoked or the network blocks `app.impact.com/oauth2/token` , the connection will fail mid-session. Restart the connection to trigger a new login.

</details>

***

## Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```http
GET https://integrations.impact.com/developer-portal/ai-solutions/mcp-quick-start/install-impact.com-mcp-in-claude-code.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.


# Enable or Disable MCP access

Account administrators can control whether users in their account are allowed to connect supported AI clients to the impact.com MCP. This article explains where to find the setting, how to turn it on or off, and what happens after you save the change.

{% hint style="success" %}
**Note:** MCP access is managed at the *account* level. When you change this setting, it affects all users on that account.
{% endhint %}

1. Sign in to [impact.com](http://app.impact.com) with an account administrator profile.
2. Navigate to ![](/files/14Id0ZaHhZaXJqnqrPMG) **\[User Profile]** **→ Settings → Tools →** [**impact ai**](https://app.impact.com/secure/advertiser/fr/genai-settings-ui.ihtml).
3. In the **MCP** section, find **MCP access** and select the checkbox to enable access for the account, or deselect it to disable access.
4. Save your changes.

## When MCP access is enabled

* Users in the account can authorize supported AI tools to connect to the impact.com MCP.
* Access still respects each user's existing impact.com permissions.
* Users can complete the supported OAuth authorization flow and use approved MCP tools available to their role.

## When MCP access is disabled

* Users in the account cannot authorize new MCP connections through supported AI tools.
* Requests using existing MCP authorization are blocked.

{% hint style="warning" %}
**Important:** If you disable MCP access for an account that already has existing MCP connections, you may see a confirmation message. After you confirm, removal of all access can take up to **24 hours**.
{% endhint %}

## Troubleshooting

* **You don't see the MCP setting:** Confirm that you are signed in as an account administrator.
* **A user cannot connect an AI client:** Verify that **MCP access** is enabled for the account.
* Read the [MCP FAQ](/ai-solutions/mcp-quick-start/mcp.impact.com-faq) for more information.


# Switch Between Accounts in the MCP Beta

This article explains how to switch which impact.com account your AI client connects to during the impact.com Model Context Protocol (MCP) beta. Use this process when you need your AI client to access a different impact.com account during the beta.

{% hint style="info" %}
**Note:** The impact.com MCP is in beta with a limited, curated set of tools. View the [Quick Start Guide](https://integrations.impact.com/ai-solutions/mcp-quick-start).
{% endhint %}

## Switch accounts for MCP

Account switching is not yet handled directly inside the MCP connection flow. You must switch the active account in app.impact.com, then disconnect and reconnect your impact.com MCP integration.

1. Disconnect your impact.com MCP connection in your AI client.
2. Log in to [app.impact.com](http://app.impact.com/).
3. In the top-left corner, switch to the account you want to use in MCP.
4. Reconnect your impact.com MCP connection. You'll be guided through an OAuth login flow. After you log in successfully, the MCP tools that are available for that account will appear in your AI client.

## What to expect

* The MCP connection uses the account that is active during the connection process.
* If you want to use a different account, you must repeat the disconnect, switch, and reconnect process.
* The tools shown in your AI client reflect the account you connected during OAuth.

{% hint style="warning" %}
**Important:** If you reconnect without switching to the correct account first in app.impact.com, your AI client will reconnect to the currently active account instead.
{% endhint %}

## FAQ

<details>

<summary>Do I need to disconnect before switching accounts?</summary>

Yes. In the beta, disconnecting and reconnecting is required for the AI client to establish a new MCP connection for a different account.

</details>

<details>

<summary>Where do I choose the account?</summary>

You choose it by switching to the correct active account in app.impact.com before reconnecting the MCP.

</details>

<details>

<summary>Will this process change later?</summary>

Yes. Future updates are expected to add a dedicated switching experience and improve the OAuth flow so account selection can happen during connection.

</details>


# mcp.impact.com FAQ

mcp.impact.com/mcp is impact.com's public Model Context Protocol (MCP) endpoint, now available in Open Beta. Connect a compatible AI client to your impact.com account to use a set of supported tools through conversational workflows. This FAQ answers common questions about what the beta includes, how setup and access work, and how security is handled.

## General

<details>

<summary>What is mcp.impact.com?</summary>

`mcp.impact.com` is impact.com's public MCP endpoint. It allows an MCP-compatible AI client to connect to an impact.com account so supported impact.com tools and data can be used through conversational workflows.

In practical terms, this helps customers work with selected impact.com capabilities through compatible AI tools without needing to build a custom integration from scratch.

</details>

<details>

<summary>Where can I get started?</summary>

The best starting point is [the MCP quick start guide](https://integrations.impact.com/ai-solutions/mcp-quick-start). That documentation explains how to enable MCP access, which clients are supported, which tools are available, and how to complete setup.

</details>

<details>

<summary>Does this replace the impact.com platform or user interface?</summary>

No. The MCP service extends access to selected impact.com capabilities through compatible AI tools. It does not replace the core impact.com platform or its standard workflows.

</details>

<details>

<summary>Which AI clients are supported?</summary>

The service is designed for MCP-compatible clients. Claude Code, Cursor, and VS Code are currently supported.

For setup guidance, see the [quick start documentation](https://integrations.impact.com/ai-solutions/mcp-quick-start).

</details>

<details>

<summary>Which tools are supported?</summary>

For the latest supported tool list, setup, and support information, visit [integrations.impact.com](https://integrations.impact.com).

</details>

<details>

<summary>What should I do if setup fails?</summary>

First, confirm that MCP access is enabled for your account and that you are following the documented setup flow for your chosen client.

If the issue continues, contact your normal impact.com support channel or customer contact for assistance.

</details>

<details>

<summary>Where is the MCP hosted?</summary>

The MCP endpoint is `https://mcp.impact.com/mcp`. Authentication via OAuth flows through `app.impact.com` issuing a scoped JWT to the AI client. Access is restricted to the MCP endpoint only.

</details>

## Beta

<details>

<summary>What does "Beta" mean?</summary>

Beta means the service is available for customer use, with an intentionally focused launch scope. The beta includes a curated set of supported tools, setup documentation, and an active feedback loop as the experience continues to improve.

The beta can be used for supported scenarios today, while some capabilities, documentation, and operational maturity continue to evolve over time.

</details>

<details>

<summary>Who is this beta for?</summary>

This beta is designed for customers who want to connect their own MCP-compatible client to impact.com and use supported tools in an AI-driven workflow.

It is especially useful for technical users, developers, solutions teams, and operational users who are comfortable following a guided setup process.

</details>

<details>

<summary>What can I do with the beta?</summary>

You can use a curated set of supported, customer-facing MCP tools that are available as part of the beta. These tools are intended to support practical workflows through an MCP-compatible client.

</details>

<details>

<summary>Will all MCP tools be available at launch?</summary>

No. The beta includes a curated set of supported tools rather than the full possible MCP tool set.

This focused approach helps ensure a better experience for the tools included in the initial release.

</details>

<details>

<summary>What are the main limitations of the beta?</summary>

The main limitations are a curated tool set, evolving documentation, and the normal changes that come with a beta-stage release. Some capabilities that may be valuable in the future are not included in the initial launch scope.

</details>

## MCP access

<details>

<summary>How do I get access?</summary>

Access is enabled through an account-level MCP setting. Once MCP access is turned on for the account, the setup instructions at [integrations.impact.com](https://integrations.impact.com) can be followed to connect a compatible client.

</details>

<details>

<summary>Are API keys required to use MCP?</summary>

No. The primary experience uses a one-time OAuth authorization flow. Users sign in with their existing impact.com credentials and grant consent to the supported AI client.

This makes setup simpler and removes the need to create and manage separate API keys.

</details>

<details>

<summary>Can the MCP access other impact.com endpoints?</summary>

The token issued during the OAuth authorization process is restricted to the MCP endpoint only.

</details>

<details>

<summary>How can I switch to a different account if I have multiple accounts?</summary>

For the beta, switching between accounts requires a manual workaround.

Steps:

1. Disconnect the impact.com MCP connection within the AI client.
2. Log into [app.impact.com](https://app.impact.com/).
3. Switch the account in [app.impact.com](https://app.impact.com) to the account to be connected in the MCP.
4. Reconnect the impact.com MCP connection.
   1. The user will be guided through an OAuth login flow.
   2. Once successfully logged in, the available MCP tools will be listed in the AI client.

In the future, an MCP tool will be created to help facilitate the account switch. The OAuth login flow will also be enhanced to enable switching to a chosen account at the time of connecting the MCP.

</details>

<details>

<summary>Does enabling MCP give every user the same level of access?</summary>

No. MCP access is enabled at the account level, but each user can only access what their existing [impact.com](http://www.impact.com/) permissions allow.

</details>

<details>

<summary>Does disabling MCP affect the whole account?</summary>

Yes. This setting applies to the entire account, not to individual users.

</details>

<details>

<summary>What I do if users still cannot connect after MCP access is enabled?</summary>

Confirm the setting was saved successfully, then ask the user to try the connection again using the documented setup flow for the supported AI client. If the issue continues, follow the normal [impact.com](http://impact.com) support process.

</details>

## Manage tool permissions

<details>

<summary>How do I manage tool permissions in Cursor?</summary>

Connecting mcp.impact.com authorizes Cursor to call supported tools within your existing impact.com permissions. Separately, Cursor may ask you to approve each tool call, or remember that approval. Those prompts are controlled by Cursor, not by impact.com.

#### **Steps**

1. When the agent wants to use an impact.com MCP tool, review the prompt and approve or deny.
2. To change how often you are asked: open **Cursor Settings → Agents → Approvals & Execution** and choose a run mode (for example, **Auto-review** or **Allowlist**).
3. To let trusted MCP tools run without prompting, add them to the MCP allowlist from that settings area, or choose **Add to allowlist** when prompted.
4. Optionally, enable or disable an MCP server from the tools list in chat.
   1. Select **Customize**, then the tools list at the top of the chat panel.

Denying a prompt blocks that call in Cursor. It does not change your impact.com account permissions or the account-level MCP enablement setting.

</details>

<details>

<summary>How do I manage tool permissions in VS Code?</summary>

Connecting mcp.impact.com authorizes VS Code to call supported tools within your existing impact.com permissions. Separately, VS Code may ask you to approve each tool call, or remember that approval. Those prompts are controlled by VS Code, not by impact.com.

#### Steps

1. When Copilot Chat or the agent needs an MCP tool, review the confirmation dialog (tool name and parameters) and approve or deny.
2. To manage saved approvals: open the Command Palette and run **Chat: Manage Tool Approval**.&#x20;
   1. Tools are grouped by MCP server. Adjust per tool, or trust all tools from a specific server.
3. To change session autonomy: use the permissions dropdown in the chat input (**Default Approvals**, **Bypass Approvals**, or **Autopilot**).&#x20;
   1. Prefer **Default Approvals** for day-to-day use.
4. To clear saved approvals: open the Command Palette and run **Chat: Reset Tool Confirmations**.

Denying a prompt blocks that call in VS Code. It doesn't change your impact.com account permissions or the account-level MCP enablement setting.

</details>

<details>

<summary>How do I manage tool permissions in Claude Code?</summary>

Connecting mcp.impact.com authorizes Claude Code to call supported tools within your existing impact.com permissions. Separately, Claude Code may ask you to approve each tool call, or remember that approval. Those prompts are controlled by Claude Code, not by impact.com.

#### **Steps**

1. When Claude Code prompts to use an impact.com MCP tool, approve once, or choose the option to remember the choice when offered.
2. To review or change rules: run `/permissions` and set **Allow**, **Ask**, or **Deny** for the relevant MCP tools.
3. To see connected MCP servers and tools: run `/mcp`.
4. Permission modes (for example, Manual, Auto, or Bypass) change how often you are prompted. Use bypass modes only in environments you trust.

Denying a prompt blocks that call in Claude Code. It does not change your impact.com account permissions or the account-level MCP enablement setting.

</details>

<details>

<summary>Why does my AI client keep asking me to approve impact.com tools?</summary>

Your AI client controls whether tool calls require approval. If you are prompted every time, check the client’s permission or run mode settings and, where available, add trusted impact.com MCP tools to an allowlist or choose “always allow” / “don’t ask again” when offered.

Use the client-specific steps above for Cursor, VS Code, or Claude Code.

These prompts are separate from your impact.com permissions. Approving a tool in your AI client does not grant access beyond what your impact.com role already allows.

</details>

## Security

<details>

<summary>How does authentication work?</summary>

The beta uses OAuth with a standard authorization flow for compatible MCP clients. When a client connects, the user is redirected to sign in with their existing impact.com account and approve access.

Once that step is complete, the client can make authenticated requests on the user's behalf within the supported scope.

</details>

<details>

<summary>Is my data secure?</summary>

Yes. The beta uses OAuth-based authentication and explicit user consent. The MCP service is designed as a controlled layer in front of existing impact.com capabilities rather than providing unrestricted access.

As with any beta, we recommend using the service within the documented scope and supported setup paths.

</details>

## Troubleshooting

<details>

<summary>Why is my Cursor tools list out of date after I reconnect?</summary>

Cursor can cache the MCP tools list, so it may not show the latest tools after you reconnect.

**Fix:** Quit Cursor completely and reopen it. When you view the tools in the MCP list, the list should refresh automatically.

This is a known Cursor client behavior, not an impact.com MCP issue.

</details>

<details>

<summary>Why does my Claude MCP connection drop after a few minutes?</summary>

impact.com MCP access tokens are short-lived (about 5 minutes). Claude normally refreshes them silently using a longer-lived refresh token.

If a refresh fails, for example because the refresh token was revoked, or your network blocks `app.impact.com/oauth2/token` , the connection can drop mid-session.

**Fix:** Restart the Claude MCP connection (or **Disconnect** → **Connect** for the Claude Desktop connector) and complete the login again if prompted. If drops keep happening, check that your network can reach `https://app.impact.com` , including the token endpoint.

</details>

<details>

<summary>How do I re-authenticate Claude with the impact.com MCP?</summary>

Use the path that matches how you connected:

* **Claude Desktop connector UI:**&#x20;
  * Open **Customize → Connectors**, select the impact connector, then **Disconnect** and **Connect** again.
* **Claude Code or Claude Desktop JSON /** `mcp-remote` **config:**&#x20;
  * Delete the cached tokens with `rm -rf ~/.mcp-auth/`, then restart Claude and run the OAuth flow again (for Claude Code, use `/mcp` and select `impact`).

After config changes in the JSON path, quit Claude completely. Fully exit the app, don't just close the window, then reopen it.

If the server does not appear when using the JSON / `mcp-remote` path, confirm Node.js 18+ is installed and `npx` is on your `PATH` . Claude uses `npx` to start `mcp-remote`.

</details>

<details>

<summary>Why does Claude say “Incompatible auth server: does not support dynamic client registration”?</summary>

impact.com MCP doesn't support Dynamic Client Registration (DCR) as part of the open beta. Claude must use a pre-registered client configuration rather than registering a client on the fly.

If you see this error, follow the Claude setup steps in [MCP for Claude Desktop & Claude Code](https://integrations.impact.com/ai-solutions/mcp-quick-start/mcp-for-claude-desktop-and-claude-code). Use the path that provides the published impact.com OAuth Client ID (Claude Desktop connector UI, or the JSON / static-client configuration).

For Claude Desktop, prefer the built-in connector UI when available. This is the simplest supported path during the open beta.

</details>

<details>

<summary>I got an authorization error when connecting, but no sign-in window appeared. What should I do?</summary>

When you select **Connect**, your AI client opens a browser window or tab so you can sign in to [impact.com](http://impact.com/) and approve access.&#x20;

* If you have many tabs open, or the browser blocks pop-ups, that window can sit behind other tabs.&#x20;
* Cursor or Claude may then show an error such as *Authorization with* [impact.com](http://impact.com/) *failed* even though your account is eligible and MCP Access is on.
* This is not usually a permissions problem on your [impact.com](http://impact.com/) account.

**What to try**

* Look for a new browser tab or pop-up for [impact.com](http://impact.com/) sign-in, and complete it.
* Close extra tabs, or bring your browser to the front, then select **Connect** again.
* If pop-ups are blocked, allow them for your AI client and retry.
* Completing **Connect** in a less crowded browser session (or Claude Desktop) can make the sign-in window easier to see.

If you still cannot complete login after a visible [impact.com](http://impact.com/) window appears, contact your [impact.com](http://impact.com/) support channel and include the exact error text.

</details>

## Glossary of terms

| Term                                                            | Definition                                                                                                                                                                                                                                                                                        |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MCP                                                             | Abbreviation of Model Context Protocol. MCP is a standard way for AI clients to connect to external services, tools, and data sources. For mcp.impact.com, it enables compatible AI clients to interact with selected impact.com capabilities.                                                    |
| Supported AI client / supported AI tool / MCP-compatible client | <p>An AI application or development tool that can connect to an MCP server and is supported for use with <a href="http://mcp.impact.com">mcp.impact.com</a>. </p><p>Examples currently include Claude Code, Cursor, and VS Code. Use the documented setup instructions for supported clients.</p> |
| MCP tool                                                        | <p>A specific capability exposed through the MCP service that an AI client can call on behalf of an authenticated user. </p><p>MCP tools are limited to the curated, customer-facing set made available for the beta.</p>                                                                         |
| Authentication                                                  | The process of confirming who the user is. In this beta, users authenticate with their existing impact.com credentials during the OAuth flow.                                                                                                                                                     |
| Authorization                                                   | The process of determining what an authenticated user is allowed to access or do. A user's impact.com permissions determine whether they can use a specific MCP tool or capability.                                                                                                               |
| OAuth                                                           | An authorization framework that lets a user grant an AI client permission to access supported impact.com capabilities without sharing separate API keys. The beta uses a one-time OAuth authorization flow with explicit user consent.                                                            |


# MCP Tools

impact.com MCP tools are actions your AI assistant can take on your live impact.com account once you connect [Claude](/ai-solutions/mcp-quick-start/mcp-for-claude-desktop-and-claude-code), [Cursor](/ai-solutions/mcp-quick-start/mcp-for-cursor), or [VS Code](/ai-solutions/mcp-quick-start/mcp-for-vs-code) to mcp.impact.com. Ask in plain language for Help Center answers, marketing guidance, performance, invoices, partner or program discovery, tracking links, promo codes, payouts, and more.&#x20;

Your AI assistant calls the right tool and uses your real data, scoped to your account type and permissions. Browse the catalog below, pick a tool that matches how you work, and try a sample prompt to see what is available without leaving chat.

{% hint style="success" %}
**Unlocking the future of MCP.** This beta is live with the initial tools below, and we're already building what comes next. Using MCP? [Tell us](https://outset.ai/start/e8deff07-d44b-4691-a028-c0b7f7ed9459) which tools and skills you want, and what is getting in the way.
{% endhint %}

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>View the Brand MCP Tools</td><td><a href="/files/yp8smHkA2AcAeuENDcsu">/files/yp8smHkA2AcAeuENDcsu</a></td><td><a href="/pages/D3cfx4nmoSYhHAEReUJn">/pages/D3cfx4nmoSYhHAEReUJn</a></td></tr><tr><td>View the Partner MCP Tools</td><td><a href="/files/PImBESxgYoeFqETpZdxt">/files/PImBESxgYoeFqETpZdxt</a></td><td><a href="/pages/Fkmvkgb93Pk6M3VogabC">/pages/Fkmvkgb93Pk6M3VogabC</a></td></tr></tbody></table>

{% hint style="success" %}
**Using an AI assistant?**

*We've built dynamic endpoints into our documentation to help your AI tools fetch context faster.*

System instructions for AI Agents:

* **Index**: `GET` [`https://integrations.impact.com/llms.txt`](https://integrations.impact.com/llms.txt) for `.md` sources.
* **Token Limit**: Fetch only necessary `.md` and OpenAPI routes to conserve context.
* **Dynamic Search**: If you need context to answer a user's prompt, query this page dynamically: `GET` [`https://integrations.impact.com/{insert_current_page_path}.md?ask=`](https://integrations.impact.com/{insert_current_page_path}.md?ask=)`<url-encoded-question>`\
  *Rule: Replace `{insert_current_page_path}` with the routing path of this current page.*
  {% endhint %}


# Brand MCP Tools

The impact.com MCP server exposes the following tools to brand accounts. Each tool below explains what it does, when to use it, and example prompts to try.

{% hint style="info" %}
**Upgrade your setup**: MCP Skills are available as a direct add-on to help AI agents execute actions on top of your MCP Tools. Learn more about [Brand MCP Skills](/ai-solutions/mcp-skills/brand-skills). Using MCP? [Tell us](https://outset.ai/start/e8deff07-d44b-4691-a028-c0b7f7ed9459) which tools and skills you want, and what is getting in the way.
{% endhint %}

## **Guidance & support**

### search\_help\_center

Searches the impact.com [Help Center](https://help.impact.com/) for how-to and support answers. Ask this tool how to do something in the platform or where to find a specific support article. Results are scoped to your account type and can link directly to the relevant screen in the platform.

<details>

<summary>Sample tool prompts</summary>

* How do I set up a tracking link in impact.com?
* Where do I add a new payment method to my account?
* What are the steps to invite a partner to my program?

</details>

### get\_marketing\_guidance

Answers strategy and best-practice questions about referral and partnership marketing. Use this tool for marketing advice or program improvements. It tailors guidance to your account type and recommends relevant Partnerships Experience Academy (PXA) training courses.

<details>

<summary>Sample tool prompts</summary>

* What's a good commission structure to attract new partners?
* How can I get more of my creators to actually post?
* Any best practices for launching a referral program from scratch?

</details>

## **Analytics & performance**

### query\_performance

Retrieves performance analytics for your account, including clicks, actions, and revenue, grouped by dimensions like partner or date. Ask this tool how your account, program, or partners are performing. Your account identity sets the data scope automatically, and you can request specific metrics, breakdowns, and date ranges.

<details>

<summary>Sample tool prompts</summary>

* How did my program perform last month: clicks, actions, and revenue?
* Show me my top partners by earnings this quarter.
* Compare my conversion numbers week over week for the last 30 days.

</details>

### get\_website\_metrics

Retrieves traffic, engagement, and audience metrics for a given website domain. Use this to evaluate a publisher, partner, or competitor site, or to check how a website is performing. Accepts a website URL and the metrics you're interested in.

<details>

<summary>Sample tool prompts</summary>

* How much traffic does [www.dinasoares.com](http://www.dinasoares.com) get?
* Pull the audience and engagement metrics for this publisher's site before I approve them.
* Is [www.dinasoares.com](http://www.dinasoares.com) bigger than this other review site I'm considering?

</details>

### get\_social\_metrics

Retrieves follower, engagement, and reach metrics for a social media profile. Use this to evaluate a creator or influencer, or to check how a social account is performing. Accepts the platform and profile handle.

<details>

<summary>Sample tool prompts</summary>

* What's the follower count and engagement rate for @dina\_soares on Instagram?
* Check this TikTok creator's reach before I sign them.
* How is my brand's Instagram account performing?

</details>

### investigate\_order\_action

Looks up conversion and action-tracking records for a specific order ID within a program. Ask this tool why an order did or didn't convert, why a commission looks missing or wrong, or whether a payable action is ready.

<details>

<summary>Sample tool prompts</summary>

* Why didn't order OID-11231 convert?
* This order tracked but the commission looks wrong. Can you dig into it?
* Is the action for order 10111 payable yet, and if not, why?

</details>

## **Finance**

### list\_invoices

Lists recipient-generated invoices for your account (newest first, 25 per page). You'll see invoices generated for your partners. Optionally filter by created date. Ask this tool for invoice history, unpaid or overdue line items, or totals, but not for current overdue funding or payout eligibility.

<details>

<summary>Sample tool prompts</summary>

* Show my invoices from the last 90 days.
* Which invoices still have PENDING or OVERDUE line items?
* List invoices created since 2026-01-01.

</details>

### get\_invoice

Retrieves one recipient-generated invoice by invoice number (from `list_invoices`), including line items and per-program breakdown. Ask this tool to open a specific invoice and summarize status, due dates, and totals.

<details>

<summary>Sample tool prompts</summary>

* Open invoice RG-12345 and summarize the line items.
* Get the details for that unpaid invoice.
* What’s on invoice number X: status, due dates, and totals?

</details>

### get\_brand\_overdue\_amount

Retrieves your account's total overdue fees, broken down into overdue impact.com fees and overdue partner fees. Ask this tool how much you owe or whether you need to add funding.

<details>

<summary>Sample tool prompts</summary>

* How much do I currently owe in overdue fees?
* Do I need to add funding to my account right now?
* Break down my overdue impact.com fees versus overdue partner fees.

</details>

## **Recommendations**

### recommend\_partners

Retrieves a ranked list of partners recommended for your program, based on category, country, promotional method, and audience-similarity signals. Ask this tool which publishers or creators to discover or recruit. This tool is not for assessing a partner you may already have in mind (use `evaluate_partner_recommendation` for that).

<details>

<summary>Sample tool prompts</summary>

* Find me some new partners to recruit for my program.
* Which publishers should I be reaching out to in the home & garden space in the US?
* Recommend creators whose audience looks like my best-performing partners.

</details>

### evaluate\_partner\_recommendation

Assesses how well a specific partner fits your program, returning a scored verdict with strengths and concerns. Ask this tool whether to partner with a specific publisher.

<details>

<summary>Sample tool prompts</summary>

* Should I partner with Dinah Soares for my program?
* Why was Dinah Soares recommended to me? Are they actually a good fit?
* Give me a fit assessment for this publisher before I approve them.

</details>

### **Partners list**

### list\_partners

Lists the partners in your program, with optional filters for account state, program, group, or country. Ask this tool who your partners are, which partners are pending, active, or declined, or for a filtered partner inventory.&#x20;

It's not for performance analytics (use `query_performance`), discovering new partners to recruit (use `recommend_partners`), or approving/declining applications.

<details>

<summary>Sample tool prompts</summary>

* List my partners.
* Which partners are pending approval on my program?
* Show me active partners in the US.
* Who is waiting to join our affiliate program?
* List declined partner applications from last month.

</details>

## **Tasks**

### list\_tasks

List tasks for the authenticated account’s program. Ask this tool which tasks are open, overdue, or assigned. Not for creating or updating tasks, or for performance analytics.

<details>

<summary>Sample tool prompts</summary>

* What tasks are open on my program?
* Show my overdue tasks.
* List my partner tasks.
* Which tasks are assigned this week?

</details>


# Partner MCP Tools

The impact.com MCP server exposes the following tools to partner accounts. Each tool below explains what it does, when to use it, and example prompts to try.

{% hint style="info" %}
**Upgrade your setup**: MCP Skills are available as a direct add-on to help AI agents execute actions on top of your MCP Tools. Learn more about [Partner MCP Skills](/ai-solutions/mcp-skills/partner-skills). Using MCP? [Tell us](https://outset.ai/start/e8deff07-d44b-4691-a028-c0b7f7ed9459) which tools and skills you want, and what is getting in the way.
{% endhint %}

## Guidance & support

### search\_help\_center

Searches the impact.com [Help Center](https://help.impact.com/) for how-to and support answers. Ask this tool how to do something in the platform or where to find a specific support article. Results are scoped to your account type and can link directly to the relevant screen in the platform.

<details>

<summary>Sample tool prompts</summary>

* Where do I add a new payment method to my account?
* What are the steps to apply to a brand's program?
* How do I connect a tracking link to a new social channel?

</details>

### get\_marketing\_guidance

Answers strategy and best-practice questions about referral and partnership marketing. Use this tool for choosing products, improving promotion performance, or preparing payout requirements. It tailors guidance to your account type and recommends relevant Partnerships Experience Academy (PXA) training courses.

<details>

<summary>Sample tool prompts</summary>

* Any best practices for launching a referral program from scratch?
* How can I improve my promotion performance this quarter?
* What do I need to prepare before requesting a payout?

</details>

## **Analytics & performance**

### query\_performance

Retrieves performance analytics for your account, including clicks, actions, and revenue, grouped by dimensions like brand, partner, or date. Ask this tool how your account, program, or partners are performing. Your account identity sets the data scope automatically, and you can request specific metrics, breakdowns, and date ranges.

<details>

<summary>Sample tool prompts</summary>

* How did my program perform last month: clicks, actions, and revenue?
* Show me my top programs by earnings this quarter.
* Compare my conversion numbers week over week for the last 30 days.

</details>

## **Finance**

### list\_invoices

Lists recipient-generated invoices for your account (newest first, 25 per page). You'll see invoices generated for you. Optionally filter by created date. Ask this tool for invoice history, unpaid or overdue line items, or totals, but not for current overdue funding or payout eligibility.

<details>

<summary>Sample tool prompts</summary>

* Show my invoices from the last 90 days.
* Which invoices still have PENDING or OVERDUE line items?
* List invoices created since 2026-01-01.

</details>

### get\_invoice

Retrieves one recipient-generated invoice by invoice number (from `list_invoices`), including line items and per-program breakdown. Ask this tool to open a specific invoice and summarize status, due dates, and totals.

<details>

<summary>Sample tool prompts</summary>

* Open invoice RG-12345 and summarize the line items.
* Get the details for that unpaid invoice.
* What’s on invoice number X: status, due dates, and totals?

</details>

### get\_payout\_status

Retrieves your payment eligibility, available balance, and payout schedule. Ask this tool whether you're qualified to be paid, what your balance is, or when your next payout will land.

<details>

<summary>Sample tool prompts</summary>

* Am I cleared to get paid?
* What's my available balance and when's my next payout?
* Do I have a payment method set up, and when will I hit my threshold?

</details>

## Marketplace & promo codes

### search\_products

Searches the impact.com marketplace for products. Use this to find brands, offers, or product listings, or to discover promotable products. Accepts a search query and optional filters like category, merchant, or commission structure.

<details>

<summary>Sample tool prompts</summary>

* Find running shoes I can promote from brands I've joined.
* Show me the highest-commission electronics offers available to me.
* Any kitchen products under $50 in the marketplace I could feature?

</details>

### list\_partner\_promo\_codes

Retrieves your promo codes, returning ACTIVE and PENDING codes by default. Ask this tool to see, count, or search your promo codes, or filter them by state or brand.

<details>

<summary>Sample tool prompts</summary>

* Show me my promo codes.
* How many active promo codes do I have in total?
* List the promo codes I have for ACME Inc.

</details>

### get\_partner\_promo\_code

Retrieves full details for a single promo code you own: code text, credit rule, match mode, brand, deal, and schedule. Ask this tool to explain or inspect one specific code by ID. The promo code ID can be found using the `list_partner_promo_codes` tool.

<details>

<summary>Sample tool prompts</summary>

* Explain promo code 1231733.
* What are the full details and schedule for promo code ID 1231733?
* Which brand and deal does promo code 551111 belong to?

</details>

### create\_tracking\_links

Creates tracking links for program destinations you’re promoting. Ask this tool to generate tracking URLs for one or more program destinations.

<details>

<summary>Sample tool prompts</summary>

* Create a tracking link for this product URL on the ACME program.
* Generate tracking links for these three destination URLs.
* Make me a tracking link with a sub ID for this deep link.

</details>

## **Recommendations**

### recommend\_programs

Retrieves a ranked list of brand programs recommended for you, based on category, country, and audience-similarity signals. Ask this tool which programs to discover or apply to.

<details>

<summary>Sample tool prompts</summary>

* What brand programs should I apply to?
* Find me new programs in the fitness category I’d be a good match for.
* Recommend programs that fit my audience and the content I already publish.

</details>

### evaluate\_program\_recommendation

Assesses how well a specific program fits your audience and content, returning a scored verdict with strengths and concerns. Ask this tool whether to apply to a specific program.

<details>

<summary>Sample tool prompts</summary>

* Should I apply to the ACME program?
* Is this brand a good fit for my audience, and why was it recommended to me?
* Give me the strengths and concerns for joining ACME Fitness before I apply.

</details>

## Tasks

### list\_tasks

List tasks for the authenticated partner account. Ask this tool which tasks are open, overdue, or assigned. Not for creating or updating tasks, or for performance analytics.

<details>

<summary>Sample tool prompts</summary>

* “What tasks are open?”
* “Show me overdue tasks.”
* “List my tasks.”
* “Which tasks are assigned this week?”

</details>


# MCP Skills

MCP skills are reusable workflows you install in your AI client so it knows how to use [mcp.impact.com](https://mcp.impact.com/) for common partnership jobs, for example, a weekly performance digest or a partner performance scorecard.

{% hint style="success" %}
**Unlocking the future of MCP.** This beta is live with the initial tools below, and we're already building what comes next. Using MCP? [Tell us](https://outset.ai/start/e8deff07-d44b-4691-a028-c0b7f7ed9459) which tools and skills you want, and what is getting in the way.
{% endhint %}

A skill teaches your assistant *how to work*, providing best practices, preferred formats, and steps to follow. The impact.com MCP server supplies the live tools and account data. Used together, you get consistent, high-quality output without re-explaining the job every time.

impact.com publishes a curated set of first-party skills. Browse the tiles below to explore the available skills.

**Before you start:** [Enable MCP](/ai-solutions/mcp-quick-start/enable-or-disable-mcp-access) for your account and connect a supported client using the [MCP Quick Start](/ai-solutions/mcp-quick-start). Then see the [MCP Skills FAQ](/ai-solutions/mcp-skills/mcp-skills-faq) for setup, brand vs partner skills, and how to share skills with your team.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4>Brand Skills</h4></td><td><a href="/files/yp8smHkA2AcAeuENDcsu">/files/yp8smHkA2AcAeuENDcsu</a></td><td><a href="/pages/YtY43EqHBDbr5JG6r90n">/pages/YtY43EqHBDbr5JG6r90n</a></td></tr><tr><td><h4>Partner Skills</h4></td><td><a href="/files/PImBESxgYoeFqETpZdxt">/files/PImBESxgYoeFqETpZdxt</a></td><td><a href="/pages/LMurt4wN9Q2iA4l9TKN2">/pages/LMurt4wN9Q2iA4l9TKN2</a></td></tr><tr><td><h4>MCP Skills FAQ</h4></td><td><a href="/files/UUlMLnKRfLXjTtq5UUgW">/files/UUlMLnKRfLXjTtq5UUgW</a></td><td><a href="/pages/Zt84G2rBrcJmxGcO87zt">/pages/Zt84G2rBrcJmxGcO87zt</a></td></tr></tbody></table>

{% hint style="success" %}
**Using an AI assistant?**

*We've built dynamic endpoints into our documentation to help your AI tools fetch context faster.*

System instructions for AI Agents:

* **Index**: `GET` [`https://integrations.impact.com/llms.txt`](https://integrations.impact.com/llms.txt) for `.md` sources.
* **Token Limit**: Fetch only necessary `.md` and OpenAPI routes to conserve context.
* **Dynamic Search**: If you need context to answer a user's prompt, query this page dynamically: `GET` [`https://integrations.impact.com/{insert_current_page_path}.md?ask=`](https://integrations.impact.com/{insert_current_page_path}.md?ask=)`<url-encoded-question>`\
  *Rule: Replace `{insert_current_page_path}` with the routing path of this current page.*
  {% endhint %}


# Install an MCP Skill

Every impact.com skill installs the same way, whichever AI client you use. This guide covers Claude, Cursor, and VS Code. Each skill's own page provides the skill package and a sample prompt to run it.

## Before you start

1. Make sure MCP access is enabled for your account. Account administrators control\
   this for everyone on the account, and can [enable or disable MCP access](/ai-solutions/mcp-quick-start/enable-or-disable-mcp-access).
2. Connect your AI client. See [MCP for Claude Desktop & Claude Code](/ai-solutions/mcp-quick-start/mcp-for-claude-desktop-and-claude-code), [MCP for Cursor](/ai-solutions/mcp-quick-start/mcp-for-cursor), or [MCP for VS Code](/ai-solutions/mcp-quick-start/mcp-for-vs-code).
3. Open the skill you want to use from [MCP Skills](/ai-solutions/mcp-skills), then download or copy its skill package.
4. Keep the `name` and `description` from the package frontmatter, because your client uses them to list the skill and trigger it automatically.

{% hint style="success" %}
**Note:** You need both MCP and the skill. MCP supplies live impact.com data, and the skill tells your assistant how to run the workflow.
{% endhint %}

## Install in Claude

In Claude Desktop, you upload skills through your settings.

1. Select your profile name at the bottom of the sidebar, then select **Settings**.
2. In the *Customize* section, select **Skills**.
3. Select **Add** ![](/files/JiWIbPyMoIeWpNy8h0ba)**\[Drop-down menu]**, then select **Upload a skill**.
4. Select the skill package you downloaded.
5. Confirm the skill appears in your skills list.

## Install in Cursor

Cursor reads skills from a folder in your project or your home directory. The folder name must match the `name` in the package frontmatter, which uses lowercase letters and hyphens.

1. Create `.cursor/skills/<skill-name>/` in your project root, for example `.cursor/skills/partner-weekly-performance-digest/`.
2. Add the `SKILL.md` file from the skill package inside that folder.
3. Optionally, create the same folder at `~/.cursor/skills/` instead, so the skill applies across all your codebases.
4. In Agent chat, type `/` and select the skill by name.

Cursor also reads skills from shared paths such as `.agents/skills/`, `.claude/skills/`, and `.codex/skills/`.

## Install in VS Code

VS Code reads skills from a folder in your workspace or your user profile. The folder name must match the `name` in the package frontmatter, which uses lowercase letters and hyphens.

1. In VS Code settings, enable **Use Agent Skills**.
2. Create `.github/skills/<skill-name>/` in your project root for a single workspace, or `~/.copilot/skills/<skill-name>/` for all your projects.
3. Add the `SKILL.md` file from the skill package inside that folder.
4. In Copilot Chat, type `/skills` or open the *Agent Customizations* menu to confirm the skill is active.

## Run the skill

1. Open a chat where [mcp.impact.com](https://mcp.impact.com/) is connected.
2. Use the sample prompt from the skill's page, or describe the job in your own words.
3. Answer any follow-up questions about program, date range, and destinations so the skill can call the right tools.

Your client can also run the skill on its own when your request matches the skill's description, so you do not always need to name it.

You’ll know the skill worked when the assistant returns real-time data from your connected impact.com account instead of general guidance. Refer to each skill's dedicated page for a detailed description of its output.

If the skill runs but returns no data, see the troubleshooting answers in the [MCP Skills FAQ](/ai-solutions/mcp-skills/mcp-skills-faq).

## See also

<table data-view="cards"><thead><tr><th></th><th data-type="content-ref"></th></tr></thead><tbody><tr><td></td><td><a href="/pages/ZHOpWEHaknaj8nWohp3f">/pages/ZHOpWEHaknaj8nWohp3f</a></td></tr><tr><td></td><td><a href="/pages/YtY43EqHBDbr5JG6r90n">/pages/YtY43EqHBDbr5JG6r90n</a></td></tr><tr><td></td><td><a href="/pages/LMurt4wN9Q2iA4l9TKN2">/pages/LMurt4wN9Q2iA4l9TKN2</a></td></tr><tr><td></td><td><a href="/pages/Zt84G2rBrcJmxGcO87zt">/pages/Zt84G2rBrcJmxGcO87zt</a></td></tr></tbody></table>


# MCP Skills FAQ

Skills are reusable workflows you install in your AI client so it knows how to use [mcp.impact.com](https://mcp.impact.com/) tools for common partnership jobs. This FAQ covers the basics.

<details>

<summary>What is a skill?</summary>

A skill is a reusable instruction set that tells an AI assistant (like Claude, ChatGPT, Gemini, Cursor, and other compatible clients) how to handle a specific task. It encodes best practices, preferred formats, and workflows so the AI produces consistent, high-quality output, without you having to re-explain the context every time.

You can use skills to do things like analyze partner performance, create a weekly performance digest, draft partner communications, and more. impact.com publishes first-party skills for use with the impact.com MCP server; install them in your client, connect MCP, and run the job.

</details>

<details>

<summary>What is the difference between a skill and an MCP server?</summary>

Skills and MCP servers serve different purposes, but they are most powerful when used together.

* Skills teach your AI assistant how to work, encoding best practices, preferred formats, and workflow logic so the AI approaches tasks the way a partnerships professional would.
* MCP servers connect your AI assistant to external tools, services, and live data sources so it can act on real information rather than working in the abstract.

Think of it this way: a skill is the expertise, and an MCP server is the data. A partner performance scorecard skill tells the AI how to structure a ranked partner review; [mcp.impact.com](https://mcp.impact.com/) gives it the live clicks, actions, and revenue for your account to populate it. Used together, you get an AI assistant that knows both what to do and has the real-time context to do it well.

</details>

<details>

<summary>Do I need MCP connected to use a skill?</summary>

For impact.com skills that pull live account data, yes. The skill tells your AI how to run the workflow; [mcp.impact.com](https://mcp.impact.com/) supplies the tools and data. Without MCP connected, the assistant can still read the skill instructions, but it cannot securely access your impact.com account.

Enable MCP for your account and connect your client using the [MCP Quick Start](/ai-solutions/mcp-quick-start), then run the skill in a chat where that connection is active.

</details>

<details>

<summary>Which AI clients support impact.com skills?</summary>

Skills are installed in your AI client; impact.com MCP provides the live tools. Today, impact.com documents MCP setup for Claude (Desktop and Claude Code), Cursor, and VS Code. See:

* [MCP for Claude Desktop & Claude Code](/ai-solutions/mcp-quick-start/mcp-for-claude-desktop-and-claude-code)
* [MCP for Cursor](/ai-solutions/mcp-quick-start/mcp-for-cursor)
* [MCP for VS Code](/ai-solutions/mcp-quick-start/mcp-for-vs-code)

How you install a skill depends on the client. Use *Install an MCP Skill* for Claude, Cursor, and VS Code. Each skill page still provides the downloadable skill package and a sample prompt. Other MCP-compatible clients may work for MCP tools, but skill install steps may differ and are not all documented yet.

</details>

<details>

<summary>Why isn't the skill using my impact.com data?</summary>

Check these common causes:

1. MCP is not connected in the current chat or client. Reconnect using the [MCP Quick Start](/ai-solutions/mcp-quick-start).
2. MCP access is disabled for the impact.com account. An admin must enable it (see Enable or Disable MCP access).
3. Wrong account: you might be connected to a different impact.com account than the one with the data you expect (see Switch Between Accounts in the MCP Beta).
4. Wrong account type for the skill: a brand skill will not behave correctly on a partner session, and vice versa. Use a skill that matches your account type (see below).
5. Missing inputs: many skills need a date range, program name, or similar information before they can call tools. Answer those prompts, then retry.

If tools still fail after those checks, contact impact.com support.

</details>

<details>

<summary>Does a skill work for both brand and partner accounts?</summary>

Not always. Many skills are written for a specific account type because brand and partner accounts see different tools and data models.

* Check the skill page for its audience or account type, for example, brand vs. partner.
* Use a brand skill only when your MCP session is a brand (advertiser) account.
* Use a partner skill only when your MCP session is a partner (publisher) account.

If you use the wrong type, the skill may ask you to stop, call tools that are not available, or return empty results. Pick the skill that matches the account you connected.

</details>

<details>

<summary>How do I use a skill in my AI?</summary>

Skills live in your AI client. The impact.com MCP server supplies live account data. Use them together:

1. Enable and connect MCP for your impact.com account in a supported client (see the [MCP Quick Start](/ai-solutions/mcp-quick-start)).
2. Open the skill you want from the *Skills* section on integrations.impact.com (or the library skill page).
3. Download the skill package by copying its code block.
4. Install it in Claude, Cursor, or VS Code using Install an MCP Skill.
5. Run the skill in a chat where MCP is connected. Use the sample prompt on the skill page, for example, "Run the weekly performance digest for last week" or "Run the partner performance scorecard for last month".

If the skill asks for inputs like dates, program name, and so on, answer those prompts so it can call the right MCP tools. The AI should use live tool results, not invent metrics.

</details>

<details>

<summary>Can I edit a skill to suit my needs?</summary>

Yes. Once a skill is installed in your AI client, you can edit the skill package to match how your team works — for example, change the default date range, add a preferred output format, or ask for extra sections in the deliverable.

Keep these guardrails in mind:

* Leave MCP tool names as published unless you know a different supported tool is available for your account (see MCP Tools).
* Do not instruct the AI to invent metrics or skip live tool calls — skills should still use [mcp.impact.com](https://mcp.impact.com/) for account data.
* Edits apply to your copy of the skill in your client. They do not change the published skill on integrations.impact.com for other users.

If a published skill is updated by impact.com, re-copy it into your client if you want those upstream changes — your local edits are not overwritten automatically.

</details>

<details>

<summary>Can I share a skill with my team at work?</summary>

Yes. Skills are files, or pasted instructions, in your AI client, so you can share them the same way you share other internal enablement material.

Common approaches:

* Point teammates at the published skill on integrations.impact.com so everyone installs the same first-party package.
* Share your edited skill package, for example, via your wiki, shared drive, or repo, if your team uses a customized version.
* In Cursor or similar tools, keep the skill in a shared project repository so anyone who clones the project gets the same skill.

Each person still needs:

1. MCP access enabled on the impact.com account they use.
2. Their AI client connected to [mcp.impact.com](https://mcp.impact.com/) (see the [MCP Quick Start](/ai-solutions/mcp-quick-start)).
3. The skill installed in their client (or available via the shared project).

Sharing a skill does not grant impact.com access by itself. Teammates only see data their own account and permissions allow.

</details>


# Brand Skills

Brand skills are ready-to-run workflows designed to automate your day-to-day program management, for example scoring your partners' performance, ranking performance, or instantly flagging who needs attention. Browse the available skills below, install your chosen skill, and run it in a chat connected to the impact.com MCP.

{% hint style="info" %}
Every skill needs tools. Visit [Brand MCP Tools](/ai-solutions/mcp-tools/brand-mcp-tools) to browse our library of available tools. Using MCP? [Tell us](https://outset.ai/start/e8deff07-d44b-4691-a028-c0b7f7ed9459) which tools and skills you want, and what is getting in the way.
{% endhint %}

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4>Brand Partner Performance Scorecard</h4><p>Ranked partner table (clicks / actions / revenue) with period vs prior and three next actions.</p></td><td><a href="/pages/QHJ7m6WtHplNhL9MyJDl">/pages/QHJ7m6WtHplNhL9MyJDl</a></td></tr><tr><td><h4>Brand Partner Discovery Brief</h4><p>Ranked partners to discover/recruit with optional fit evaluates, three next actions.</p></td><td><a href="/pages/X8p6Sgi0oNLdbbIEUtMv">/pages/X8p6Sgi0oNLdbbIEUtMv</a></td></tr><tr><td><h4>Brand Channel / Media Mix Brief</h4><p>Share of performance by channel and media type (period vs prior, concentration callouts, three next actions).</p></td><td><a href="/pages/Kwd1dMUmLNvHq3AEb07g">/pages/Kwd1dMUmLNvHq3AEb07g</a></td></tr><tr><td><h4>Brand Action Quality &#x26; Reverse Brief</h4><p>Action quality / reverse rates (good, unconfirmed, rejected, reversed) with optional partner concentration and three next actions.</p></td><td><a href="/pages/Lgd66bvx0oZNlgKBMyEL">/pages/Lgd66bvx0oZNlgKBMyEL</a></td></tr><tr><td><h4>Brand Cost &#x26; Efficiency Brief</h4><p>Revenue vs cost / commission (ROAS-style ratios from returned numbers), optional partner efficiency table, three next actions.</p></td><td><a href="/pages/AC5vZSA1xOMjBlT78oN9">/pages/AC5vZSA1xOMjBlT78oN9</a></td></tr><tr><td><h4>Brand Campaign Performance Scorecard</h4><p>Ranked trackable / Product Boost / Creator / Performance campaigns (budget when present), period vs prior, three next actions.</p></td><td><a href="/pages/OF2vGa4tmMan0n5o4XO3">/pages/OF2vGa4tmMan0n5o4XO3</a></td></tr><tr><td><h4>Brand Invoice Status Brief</h4><p>Partner invoices with PENDING / OVERDUE callouts, optional detail, three next actions.</p></td><td><a href="/pages/jwVVSnAFmU4o36pOEi1X">/pages/jwVVSnAFmU4o36pOEi1X</a></td></tr><tr><td><h4>Brand QBR Brief</h4><p>Executive summary with KPI vs prior, top-partner concentration, and mix/quality callouts for one program, plus three decisions.</p></td><td><a href="/pages/80lL8XYsOhWrGc2AYfOW">/pages/80lL8XYsOhWrGc2AYfOW</a></td></tr><tr><td><h4>Brand Program Health Check</h4><p>Severity-ranked fix-it list plus three next actions.</p></td><td><a href="/pages/Oe4xL5mPduqN2rByVOBU">/pages/Oe4xL5mPduqN2rByVOBU</a></td></tr><tr><td><h4>Brand Partner Momentum Brief</h4><p>Wins/rising/slipping/gone-dark partner buckets plus three next actions.</p><h4><br></h4></td><td><a href="/pages/ta8oQL3jUVj295tBpiES">/pages/ta8oQL3jUVj295tBpiES</a></td></tr></tbody></table>


# Brand Partner Performance Scorecard

Use this skill to rank your active partners by clicks, actions, and revenue over any date range. It generates a markdown performance scorecard with period-over-period comparisons and three key action items.&#x20;

For partners you have not recruited yet, use the [Brand Partner Discovery Brief](/ai-solutions/mcp-skills/brand-skills/brand-partner-discovery-brief) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/uEjQgZaic370s1ZG7KZa" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand partner performance scorecard`
   * Description: `Build a ranked partner performance scorecard for an impact.com Brand account from live MCP data. Use to see which partners are driving clicks, actions, and revenue for a program, ranked and compared to a prior period.`
   * Folder name (Cursor / VS Code): `brand-partner-performance-scorecard`
4. With impact.com MCP connected, prompt: "Run the partner performance scorecard for last month."


# Brand Partner Discovery Brief

Use this skill to find and shortlist new partners to recruit based on category, geography, or similar signals. It generates a markdown discovery brief with a ranked prospect table, fit analysis, and three concrete next steps for your outreach planning.&#x20;

To analyze partners already active in your program, use the [Brand Partner Performance Scorecard](/ai-solutions/mcp-skills/brand-skills/brand-partner-performance-scorecard) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/9kPaPkPnNGGVOMwGIn01" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand partner discovery brief`
   * Description: `Build a ranked list of partners to discover or recruit for an impact.com Brand program from live MCP data. Use for new publisher or creator candidates, optionally scored for fit against a specific program.`
   * Folder name (Cursor / VS Code): `brand-partner-discovery-brief`
4. With impact.com MCP connected, prompt: "Find me new partners to recruit for my program."


# Brand Channel & Media Mix Brief

Use this skill to analyze how your program performance is distributed across different channels, media types, or networks. It generates percentage-based mix tables, period-over-period trends, and concentration callouts to help you evaluate your program's diversity and efficiency.

To see which specific partners are driving your volume, use the [Brand Partner Performance Scorecard](/ai-solutions/mcp-skills/brand-skills/brand-partner-performance-scorecard) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/tCefLFXYtX9Vil3s1GDy" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand channel / media mix brief`
   * Description: `Build a channel and media-type mix brief for an impact.com Brand program from live MCP data. Use to see how performance breaks down by channel and media type, compared to a prior period, with concentration risk called out.`
   * Folder name (Cursor / VS Code): `brand-channel-media-mix-brief`
4. With impact.com MCP connected, prompt: "Run the channel and media mix brief for last month."


# Brand Action Quality & Reverse Brief

Use this skill to analyze action health and reversal trends across your program by measuring approved versus pending, rejected, and reversed actions. It delivers a quality scorecard with period-over-period comparisons, partner concentration insights, and three next steps.

\
For processing actual pending actions or ops triage, use your impact.com platform dashboard instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/cvvbkuQd9P2vwypK47ec" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand action quality & reverse brief`
   * Description: `Build an action quality and reverse-rate brief for an impact.com Brand program from live MCP data. Use to see how actions break down by status (good, unconfirmed, rejected, reversed), compared to a prior period, with optional partner concentration on quality issues.`
   * Folder name (Cursor / VS Code): `brand-action-quality-and-reverse-brief`
4. With impact.com MCP connected, prompt: "Run the action quality and reverse brief for last month."


# Brand Cost & Efficiency Brief

Use this skill to evaluate your program's financial return by comparing overall costs and commissions against generated revenue. It delivers a cost-versus-revenue scorecard featuring ROAS-style efficiency ratios, period-over-period trends, and an optional partner efficiency table.\
\
To analyze action approvals and reversal rates, use the [Brand Action Quality and Reverse Brief](/ai-solutions/mcp-skills/brand-skills/brand-action-quality-and-reverse-brief) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/3bp9BXJ7T0ZLOW5ZzL9h" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand cost & efficiency brief`
   * Description: `Build a cost and efficiency brief for an impact.com Brand program from live MCP data. Use for revenue vs cost/commission and a ROAS-style efficiency ratio, compared to a prior period, with an optional partner efficiency table.`
   * Folder name (Cursor / VS Code): `brand-cost-and-efficiency-brief`
4. With impact.com MCP connected, prompt: "Run the cost and efficiency brief for last month."


# Brand Campaign Performance Scorecard

Use this skill to track performance across your various campaigns, including trackable, Product Boost, Creator, and Performance dimensions. It delivers a ranked campaign table with period-over-period comparisons and budget tracking.\
\
For individual partner rankings, use the [Brand Partner Performance Scorecard](/ai-solutions/mcp-skills/brand-skills/brand-partner-performance-scorecard) instead. For channel share, use the [Channel and media mix brief](/ai-solutions/mcp-skills/brand-skills/brand-channel-and-media-mix-brief) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/gB7zufvxqr2pLFvU6qW7" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand campaign performance scorecard`
   * Description: `Build a ranked campaign performance scorecard for an impact.com Brand program from live MCP data. Use to see how Trackable, Product Boost, Creator, or Performance campaigns are doing, ranked and compared to a prior period.`
   * Folder name (Cursor / VS Code): `brand-campaign-performance-scorecard`
4. With impact.com MCP connected, prompt: "Run the campaign performance scorecard for last month."


# Brand Invoice Status Brief

Use this skill to quickly monitor the status of invoices from your partner by tracking open, pending, and overdue line items. It delivers a structured summary with invoice history tables and specific invoice drill-downs.\
\
To check your overall account funding balances or outstanding brand deposit requirements, use your impact.com platform dashboard instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/t7s9zpXSkG2I4ikCdG1c" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand invoice status brief`
   * Description: `Build an invoice status brief for an impact.com Brand account from live MCP data. Use for recent partner invoices with PENDING or OVERDUE line items called out, with optional drill-down into a specific invoice.`
   * Folder name (Cursor / VS Code): `brand-invoice-status-brief`
4. With impact.com MCP connected, prompt: "Which of my partner invoices are PENDING or OVERDUE?"


# Brand QBR Brief

Use this skill to build a leadership-ready quarterly business review for one brand program, comparing the completed quarter against the prior one. It delivers a markdown Quarterly Business Review (QBR) brief with an executive summary, KPI movement vs prior, top-partner concentration, channel mix and quality callouts, and  3 suggestions tied to the data.

For a full ranked partner leaderboard, use the [Brand Partner Performance Scorecard](/ai-solutions/mcp-skills/brand-skills/brand-partner-performance-scorecard) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/u9kBRUR4QFZDLxOeS1Qr" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand QBR brief`
   * Description: `Build a leadership QBR brief for one impact.com Brand program from live MCP data. Use for a QBR, quarterly business review, last quarter vs prior, or an executive summary for one program over a named period.`
   * Folder name (Cursor / VS Code): `brand-qbr-brief`
4. With impact.com MCP connected, prompt: "Run a QBR brief for \[program] for last quarter."


# Brand Program Health Check

Use this skill to get a fix-it list for a brand program, ranking what needs attention across concentration, mix, quality, efficiency, and partner momentum. It delivers a markdown health check with up to seven severity-ranked findings, each pointing to the right sibling skill for a deeper dive, and exactly three next actions.

For a full partner leaderboard, use the [Brand Partner Performance Scorecard](/ai-solutions/mcp-skills/brand-skills/brand-partner-performance-scorecard) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/yGoCBO5TjRxM7CTExnc6" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand program health check`
   * Description: `Rank a Brand program's fix-it list across concentration, mix, quality, efficiency, and partner slippage from live MCP data. Use for what is wrong with a program, a health check, or where to look first.`
   * Folder name (Cursor / VS Code): `brand-program-health-check`
4. With impact.com MCP connected, prompt: "Run a health check on \[program]."


# Brand Partner Momentum Brief

Use this skill to see which partners in a brand program are winning, rising, slipping, or have gone dark compared to a prior period. The skill delivers a markdown brief that buckets partners into those four groups with clicks/actions/revenue deltas and suggests 3 actions.\
\
For a full ranked partner leaderboard, use the [Brand Partner Performance Scorecard](/ai-solutions/mcp-skills/brand-skills/brand-partner-performance-scorecard) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/LPHKcGTJrl9bkdOwe5E0" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Brand partner momentum brief`
   * Description: `Bucket Brand program partners into wins, rising, slipping, and gone-dark from live MCP data. Use for which partners are winning, rising, slipping, or gone dark vs a prior period.`
   * Folder name (Cursor / VS Code): `brand-partner-momentum-brief`
4. With impact.com MCP connected, prompt: "Which partners on \[program] are rising or slipping vs last period?"


# Partner Skills

Partner skills are ready-to-run workflows designed to automate your day-to-day partnership management, for example tracking campaign performance, auditing your payouts, or summarizing contract terms. Browse the available skills below, install your chosen skill, and run it in a chat connected to the impact.com MCP.

{% hint style="info" %}
Every skill needs tools. Visit [Partner MCP Tools](/ai-solutions/mcp-tools/partner-mcp-tools) to browse our library of available tools. Using MCP? [Tell us](https://outset.ai/start/e8deff07-d44b-4691-a028-c0b7f7ed9459) which tools and skills you want, and what is getting in the way.
{% endhint %}

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4>Partner Weekly Performance Digest</h4><p>Account performance summary with period-over-period KPIs, top movers, and three next actions.</p></td><td><a href="/pages/iFm6mDWIz8wgn4A5gKMb">/pages/iFm6mDWIz8wgn4A5gKMb</a></td></tr><tr><td><h4>Partner Program Portfolio Scorecard</h4><p>Ranked programs / brands (clicks / actions / earnings) with period vs prior and three next actions.</p></td><td><a href="/pages/nzKQcHjT2GcpibvRICXq">/pages/nzKQcHjT2GcpibvRICXq</a></td></tr><tr><td><h4>Partner Promo &#x26; Offers Readiness</h4><p>ACTIVE/PENDING promo codes by advertiser/program, ending-soon callouts, three next actions.</p></td><td><a href="/pages/VIICdM6hkhSB9aeBPPiL">/pages/VIICdM6hkhSB9aeBPPiL</a></td></tr><tr><td><h4>Partner Tracking-link Pack</h4><p>Confirm destinations, create Regular/Vanity tracking links (one call per URL), return a campaign-ready success/failure table, three next actions.     </p></td><td><a href="/pages/PbFePrFvjVRcB9Orn1ZF">/pages/PbFePrFvjVRcB9Orn1ZF</a></td></tr><tr><td><h4>Partner Invoice Status Brief</h4><p>Recent invoices with PENDING/OVERDUE callouts, optional detail, three next actions.</p></td><td><a href="/pages/UHNAQSI1ylRp80jpDPOs">/pages/UHNAQSI1ylRp80jpDPOs</a></td></tr><tr><td><h4>Partner Program Discovery Brief</h4><p>Ranked programs to discover/apply to with optional fit evaluates, three next actions.</p></td><td><a href="/pages/3rfRjGBqx5ZxShZwf6AB">/pages/3rfRjGBqx5ZxShZwf6AB</a></td></tr></tbody></table>


# Partner Weekly Performance Digest

Use this skill to generate a recurring performance summary of your partner account over last week or any date range you choose. It delivers a whole-account digest of headline KPIs including clicks, actions, and earnings compared against the prior period.\
\
To see a complete ranked list of all your active brand programs, use the [Partner Program Portfolio Scorecard](/ai-solutions/mcp-skills/partner-skills/partner-program-portfolio-scorecard) instead.

### Prerequisites

1. MCP access enabled on your impact.com partner account.
2. Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/aWhglrFo14m2WRbxGcHh" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Partner weekly performance digest`
   * Description: `Build a weekly performance digest for an impact.com Partner account from live MCP data. Use to create a recurring performance summary, week-over-week comparison, or a leadership-ready brief of clicks, actions, and earnings.`
   * Folder name (Cursor / VS Code): `partner-weekly-performance-digest`
4. With impact.com MCP connected, prompt: "Run the weekly performance digest for last week."


# Partner Program Portfolio Scorecard

Use this skill to see which of your active brand programs are driving your results by ranking them by clicks, actions, and earnings. It delivers a portfolio view of your account with a ranked brand performance table and period-over-period comparisons.\
\
For a high-level weekly KPI rollup without the ranked portfolio table, use the [Partner Weekly Performance Digest](/ai-solutions/mcp-skills/partner-skills/partner-weekly-performance-digest) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/LZaxXYYArrBgymqRtfm9" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Partner program portfolio scorecard`
   * Description: `Build a ranked program/brand portfolio scorecard for an impact.com Partner account from live MCP data. Use to see which programs or brands are driving clicks, actions, and earnings, ranked and compared to a prior period.`
   * Folder name (Cursor / VS Code): `partner-program-portfolio-scorecard`
4. With impact.com MCP connected, prompt: "Run the program portfolio scorecard for last month."


# Partner Promo & Offers Readiness

Use this skill to track your available promotional inventory by viewing active and pending promo codes or offers. It delivers an inventory readiness summary grouped by advertiser or brand program, including alerts for codes that are ending soon.\
\
For tracking your earnings or program performance analytics, use the [Partner Program Portfolio Scorecard](/ai-solutions/mcp-skills/partner-skills/partner-program-portfolio-scorecard) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/erwo0djhwwlVznVy0ebL" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Partner promo & offers readiness`
   * Description: `Build a promo code and offers readiness brief for an impact.com Partner account from live MCP data. Use to see ACTIVE/PENDING promo codes by advertiser or program, with codes ending soon called out.`
   * Folder name (Cursor / VS Code): `partner-promo-and-offers-readiness`
4. With impact.com MCP connected, prompt: "Which of my promo codes are ending soon?"


# Partner Tracking-Link Pack

Use this skill to generate a batch of trackable regular or vanity links for your campaign destinations. It confirms your destination URLs first and then writes real, live tracking links that are ready to copy directly into your campaigns.\
\
For viewing available promo codes or analyzing your earnings, use the [Partner Promo Codes and Offers](/ai-solutions/mcp-skills/partner-skills/partner-promo-and-offers-readiness) or [Weekly Performance Digest](/ai-solutions/mcp-skills/partner-skills/partner-weekly-performance-digest) skills instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/kcnibIrIJlWXVhxzIPTK" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Partner tracking-link pack`
   * Description: `Create a batch of impact.com tracking links for an impact.com Partner account from live MCP data. Use for Regular or Vanity tracking links generated for one or more destination URLs on a program, with a clear success/failure result for each.`
   * Folder name (Cursor / VS Code): `partner-tracking-link-pack`
4. With impact.com MCP connected, prompt: "Create tracking links for these three URLs on the ACME program."


# Partner Invoice Status Brief

Use this skill to quickly monitor the status of your partner invoices by tracking open, pending, and overdue billing items. It delivers a structured summary with invoice history tables, pending and overdue callouts, and specific invoice drill-downs.\
\
To check your overall payout eligibility, scheduled payment dates, or available account balance use the impact.com platform instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/6759AKnAANfPHtUA3Kh9" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Partner invoice status brief`
   * Description: `Build an invoice status brief for an impact.com Partner account from live MCP data. Use for recent invoices with PENDING or OVERDUE line items called out, with optional drill-down into a specific invoice.`
   * Folder name (Cursor / VS Code): `partner-invoice-status-brief`
4. With impact.com MCP connected, prompt: "Which of my invoices are PENDING or OVERDUE?"


# Partner Program Discovery Brief

Use this skill to find and shortlist new brand programs to apply to based on category, geography, or similar brand signals. It delivers a discovery brief with a ranked prospect table, optional fit analysis, and three next steps for your outreach planning.\
\
To analyze performance or track earnings for programs you have already joined, use the [Weekly Performance Digest](/ai-solutions/mcp-skills/partner-skills/partner-weekly-performance-digest) instead.

### Prerequisites

* MCP access enabled on your impact.com Brand account.
* Client connected per [MCP Quick Start](/ai-solutions/mcp-quick-start).

### Install the skill

{% file src="/files/wNHoTknuzFliPF2Dc6kX" %}

1. Download or copy the skill package above.
2. Install it in Claude, Cursor, or VS Code using [Install an MCP Skill](/ai-solutions/mcp-skills/install-an-mcp-skill).
3. Use this package's frontmatter when the AI client asks for metadata:
   * Name: `Partner program discovery brief`
   * Description: `Build a ranked list of brand programs to discover or apply to for an impact.com Partner account from live MCP data. Use for new program candidates, optionally scored for fit against your audience and content.`
   * Folder name (Cursor / VS Code): `partner-program-discovery-brief`
4. With impact.com MCP connected, prompt: "What brand programs should I apply to?"


# Building with LLMs

How agents and builders use machine-readable docs, OpenAPI, and safer integration patterns.

impact.com teams increasingly pair agents, assistants, and retrieval systems with the impact.com APIs. Those systems work best when they can anchor on truthful, structured context: a small discovery file (`llms.txt`), selectively fetched pages (`*.md`), consolidated text (`llms-full.txt`) when embedding the whole corpus, and OpenAPI for concrete operations—not on memory or guesswork.

### Machine-readable documentation

#### `llms.txt` (always start here)

**`llms.txt`** is a concise, Markdown-formatted index of published documentation. Agents and tooling should `GET` it early in a session—or cache it for a defined TTL—to discover linked guides and references before issuing API calls.

**Canonical URL:** `https://integrations.impact.com/llms.txt`

**What it provides**

* A browseable outline of the Integrations Hub: getting started, authentication, developer tools, AI solutions, integration guides, API reference entry points, and related material.
* Direct URLs to each page’s Markdown source, typically URLs ending in **`.md`** on **`integrations.impact.com`**.

**Suggested agent flow**

1. Fetch `https://integrations.impact.com/llms.txt`.
2. Parse outbound links matching your task (for example Authenticate, a specific REST tag, or a tracking guide).
3. `GET` only those `.md` pages plus the smallest useful OpenAPI slice (see OpenAPI specifications).

That keeps context fresh, scoped, and within token budgets.

#### `llms-full.txt` (full hub text)

**`llms-full.txt`** is a single concatenated export of the Integrations Hub content: one plaintext/Markdown document suitable for bulk ingestion rather than incremental browsing.

**Canonical URL:** `https://integrations.impact.com/llms-full.txt`

**When to use it**

* Offline or snapshot ingestion (archives, mirrored copies).
* Embedding search (“index the whole book once”) across narrative guides.
* Wide onboarding flows where fetching hundreds of URLs is inconvenient.

**Caveats**

* The artifact is large; runtime agents should normally prefer `llms.txt` + selective `.md` fetches.
* The export may retain portal markup artifacts (for example templating snippets or embedded HTML alongside Markdown). Sanitize or chunk accordingly for your retrieval pipeline.

#### Per-page Markdown

Every meaningful page has a `GET`-able Markdown representation. The authoritative list of URLs is **`llms.txt`**; developers should not hand-maintain parallel URL lists.

**Recommended practice**

* For each workflow, load Authenticate, Errors, rate-limit or versioning docs, plus only the endpoints and guides you intend to automate.
* Refresh from `llms.txt` when deployments change slug structure or TOC order.

#### OpenAPI specifications

OpenAPI (e.g. 3.x) describes operations, schemas, authentication, examples, and error shapes in machine-parseable form. Use it for tool definitions, codegen, and validating model-generated payloads against real field names and types.

**Where to obtain specs**

* OpenAPI documents are exposed from API reference surfaces in this portal (YAML/JSON downloads or viewer exports, depending on publication settings). Prefer the canonical link surfaced in-product for **Brand**, **Partner**, and **Agency** APIs over guessed paths.

**How to combine with prose**

<table><thead><tr><th width="246.453125">Source</th><th>Typical use</th></tr></thead><tbody><tr><td><strong>OpenAPI</strong></td><td>Parameter types, enums, HTTP methods/paths, security schemes, canonical request/response models.</td></tr><tr><td><strong>Markdown guides</strong></td><td>Sequencing, edge cases, product behavior not fully expressed in the schema, deprecation notices.</td></tr><tr><td><strong><code>llms.txt</code> / selective <code>.md</code></strong></td><td>Narratives; keep token load small during live reasoning.</td></tr></tbody></table>

For LLM-heavy flows, split large specs: include only paths and components referenced by active tools rather than dumping an entire mega-spec into prompt context.

### Copying documentation as Markdown

Technical writers and engineers often paste doc fragments into chats, prompts, runbooks, or tickets. Humans should:

1. Open the desired page at **`integrations.impact.com`** in the browser.
   * To the right of the page title, select![](/files/JiWIbPyMoIeWpNy8h0ba)**More** and select **Copy page.**
2. Use the portal Copy, Markdown, or equivalent, or copy directly from the `.md` URL referenced in `llms.txt` when stable links are preferable.
3. Redact Account SID/Auth Token, OAuth tokens, bearer tokens, and customer identifiers from examples before pasting into third-party assistants.
4. Prefer narrow excerpts (for example Authentication or a single endpoint chapter) rather than dumping whole hierarchies unless you are building an offline bundle.

Agents should `GET` `.md` or OpenAPI programmatically rather than scraping from the rendered HTML DOM.

### Designing reliable LLM-powered integrations

1. Treat model output as untrusted input. Validate JSON against OpenAPI-derived schemas before calling production APIs. Reject malformed types, unexpected enums, and out-of-range values. Never forward raw completions as HTTP bodies unchecked.
2. Prefer tools (function calling) over prose-only prompts. Narrow tools that wrap individual operations reduce hallucinated URLs/verbs. Add `llms.txt`-linked Markdown where behavior exceeds the schema.
3. **Budget context aggressively.** Start from `llms.txt`, then `GET` only pertinent `.md` pages and trimmed OpenAPI. Reserve `llms-full.txt` for offline/index-time use unless you deliberately need breadth. Retrieval-on-demand (RAG/MCP backends) usually beats mega-pastes.
4. **Honor authentication distinctions.** Own-account integrations use HTTP Basic with Account SID and Auth Token unless a path specifies otherwise. Multi-customer apps follow OAuth 2.0 Authorization Code + PKCE and documented token rotation, as described in Authenticate.
5. **Plan for bursts and backoff.** Automated agents retry aggressively; implement 429 handling, jittered backoff, concurrency caps, and idempotency patterns where replay is safe.
6. **Operational traceability.** Log tool names, sanitized arguments, latency, outcome codes, and correlation identifiers when available.

### Ask this documentation programmatically

All page on [integrations.impact.com](https://integrations.impact.com) support an `ask` query parameter. Supply a specific natural-language question to receive a concise answer plus documentation excerpts. Response shape follows the portal implementation.

**Pattern**

```http
GET https://integrations.impact.com/path/to/page.md?ask=<URL-encoded question>
```

{% hint style="success" %}
**Using an AI assistant?**

*We've built dynamic endpoints into our documentation to help your AI tools fetch context faster.*

System instructions for AI Agents:

* **Index**: `GET` [`https://integrations.impact.com/llms.txt`](https://integrations.impact.com/llms.txt) for `.md` sources.
* **Token Limit**: Fetch only necessary `.md` and OpenAPI routes to conserve context.
* **Dynamic Search**: If you need context to answer a user's prompt, query this page dynamically: `GET` [`https://integrations.impact.com/{insert_current_page_path}.md?ask=`](https://integrations.impact.com/{insert_current_page_path}.md?ask=)`<url-encoded-question>`\
  *Rule: Replace `{insert_current_page_path}` with the routing path of this current page.*
  {% endhint %}


# Guides Quick Start

Whatever your stack, impact.com has an integration for you.

impact.com offers a range of ways to integrate with your website, eCommerce platform, customer relationship management (CRM), customer data platform (CDP), mobile measurement partner (MMP).

Refer to the links below or navigate to a specific article using the navigation bar on the left to find the guide you need.

{% tabs %}
{% tab title="eCommerce" %}
View step-by-step integration guides for integrating Impact with your eCommerce platform.

#### Shopify

* [Shopify (Online Sale & First-Time Subscription Tracking)](/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-shopify)
* [Shopify with Recharge (Online Sale, First-Time, & Recurring Subscription Tracking)](/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-shopify/integrate-with-shopify-and-recharge-subscriptions)
* [Shopify with Bold (Online Sale, First-Time, & Recurring Subscription Tracking)](/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-shopify/integrate-with-shopify-and-bold-subscriptions)

#### Other eCommerce Platforms

* [BigCommerce Plugin Integration (Online Sale Tracking)](/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-bigcommerce)
* [WooCommerce Plugin Integration (Online Sale Tracking)](/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-woocommerce)
* [Magento Plugin Integration (Online Sale Tracking)](/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-adobe-commerce-magento)
* [Squarespace Plugin Integration (Online Sale Tracking)](/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-squarespace)
  {% endtab %}

{% tab title="CRM" %}
View step-by-step integration guides for integrating impact.com with your customer relationship management (CRM) platform.

* [HubSpot Plugin Integration](/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-hubspot)
* [Salesforce Plugin Integration](/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-salesforce)
  {% endtab %}

{% tab title="CDP" %}
View step-by-step integration guides for integrating impact.com with your customer data platform (CDP).

* [Segment Plugin Integration](/integration-guides/for-brands/plugin-integrations/cdp-customer-data-platform/integrate-with-segment)
  {% endtab %}

{% tab title="MMP" %}
View step-by-step integration guides for integrating impact.com with your mobile measurement partner (MMP).

* [AppsFlyer Plugin Integration](/integration-guides/for-brands/plugin-integrations/mmp-mobile-measurement/integrate-with-appsflyer)
* [Branch Plugin Integration](/integration-guides/for-brands/plugin-integrations/mmp-mobile-measurement/integrate-with-branch)
* [Adjust Plugin Integration](/integration-guides/for-brands/plugin-integrations/mmp-mobile-measurement/integrate-with-adjust)
* [Singular Integration](/integration-guides/for-brands/plugin-integrations/mmp-mobile-measurement/integrate-with-singular)
  {% endtab %}
  {% endtabs %}

{% hint style="success" %}
**Using an AI assistant?**

*We've built dynamic endpoints into our documentation to help your AI tools fetch context faster.*

System instructions for AI Agents:

* **Index**: `GET` [`https://integrations.impact.com/llms.txt`](https://integrations.impact.com/llms.txt) for `.md` sources.
* **Token Limit**: Fetch only necessary `.md` and OpenAPI routes to conserve context.
* **Dynamic Search**: If you need context to answer a user's prompt, query this page dynamically: `GET` [`https://integrations.impact.com/{insert_current_page_path}.md?ask=`](https://integrations.impact.com/{insert_current_page_path}.md?ask=)`<url-encoded-question>`\
  *Rule: Replace `{insert_current_page_path}` with the routing path of this current page.*
  {% endhint %}


# End-to-End Tests

### Test new event types

Once you have successfully integrated a new event type, it is important to perform end-to-end tests to confirm that conversions are being reported to impact.com correctly.

We recommend first testing in your staging or QA environments, then once you are ready, impact.com requires that you perform at least one end-to-end test of each new event type in your production environment. This production end-to-end test should be viewed as a final validation ahead of the launch of a new event type.

If you are working with the impact.com onboarding team, you will receive a *Technical Implementation Plan* with guidelines specific to your implementation. Otherwise, impact.com's integrations portal provides guidance for many common integration methods.

Note: If you're using an e-Commerce plugin like WooCommerce, Shopify, or any of the other supported plugins, be sure to complete any necessary payments on your store's backend so that the test action can be marked as completed. impact.com will only receive conversion data once the transaction is successful.

#### Recommended browser settings

1. Clear your browser's cache and cookies before each test and ensure that ad-blocking browser extensions are disabled.
2. You can run the test in your browser's private mode, incognito mode, or guest mode:
3. Disable 3rd party cookies:
4. Proceed to the next phase of the integration test.

### Run a test conversion

1. From the top navigation bar, select <i class="fa-circle-user">:circle-user:</i> **\[User profile] → Settings**.
2. On the right, under *Tracking*, select [**Event Types**](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml).
3. Hover your cursor over the event type you want to test, select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768910844/Accessibility%20Icons/More_vNext.svg) **\[More] → Test**.
4. Select the **Template Term**, **Ad** and optionally, change the **Landing Page URL**. All event type tests will use your program's default landing page unless otherwise specified.
5. Select **Start Test in New Window**. A new browser tab will open, which will immediately direct to the URL chosen in Step 4 above.

   <img src="https://files.readme.io/d384a9589a5f960948c6e13a157e9b1fc873bb92fbda6fefea6926ed68497100-test_your_integration.png" alt="" data-size="original">
6. Complete a test conversion on your website, in the same browser and in the same session as the one you used to select **Start Test in New Window**. Record the Order ID and payload parameters (i.e., product details, discount, price, etc.):
   * For *Sale* transactions, complete several tests with multiple SKUs, with a minimum quantity of 2 for each SKU, and some tests *with* a promo code and discount and some *without* a promo code and discount.
   * For *Lead* transactions, complete several transactions to test variations in payload parameters such as promo codes, notes, or text fields, that are relevant to your expected payout conditions.
7. Proceed to review your test results in the next section.

### Review test results

1. Log in to your impact.com user account.
2. Retrieve the tracked conversion payload details by following these steps:
   * From the left navigation bar, select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768905009/Accessibility%20Icons/engage-v2.svg) **Engage → Transactions →** [**Test Actions**](https://app.impact.com/secure/advertiser/engage/actions/tests/test-actions-flow.ihtml).
   * Find your test conversion(s) based on the *Order Id* you recorded above.
   * Hover your cursor over the transaction and select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768910844/Accessibility%20Icons/More_vNext.svg) **\[More] → See Details**.
3. Review the conversion payload details paying attention to revenue, discounts, product details, and any other element that will potentially affect partner payouts:
   * If all the details are as expected, select **Approve**. Congratulations! Your event type is validated and successfully integrated.
   * If any details are not correct, select **Reject**. If you reject the end-to-end test result, you will need to correct the integration and repeat the end-to-end process for that conversion event until you achieve a successful result.
4. It may take up to 30 minutes for a test transaction to surface on the *Test Actions* screen. If your test transaction does not appear on the test transaction screen, contact your Implementation Engineer, or [**support**](https://app.impact.com/support/portal.ihtml?createTicket=true).


# For Brands

These guides are designed to help you get your tracking live and your partnerships scaling.


# Action & Conversion Field References

To submit conversion data to impact.com via a batch file, use the reference doc that matches what you need to do:

* [**Submitting new conversions**](/integration-guides/for-brands/action-and-conversion-field-references/conversion-submission-field-references) — identify the correct fields for online sales, offline sales, CRM imports, chained actions, and scheduled conversion loads.
* [**Modifying or reversing existing conversions**](/integration-guides/for-brands/action-and-conversion-field-references/action-modification-and-reversal-field-references) — update conversion data, approve an action, identify a conversion event, or assign partner credit.


# Conversion Submission Field References

Use this reference to identify the correct fields when submitting new conversions in bulk. It covers standard submission scenarios as well as chained actions and other advanced use cases, and is suited for online sales, offline sales, CRM imports, and scheduled conversion loads.

Use [Action Modification & Reversal Field References](/integration-guides/for-brands/action-and-conversion-field-references/action-modification-and-reversal-field-references) to update or reverse an existing action.

The two most common use cases are

* Missed online conversions
* Uploading conversions again with the correct data<br>

| If you want to...                             | Use this method...                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Submit a manual, one-time file with no coding | ​[Email](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/submit-conversion-data-via-ftp-or-email) batch processing or [upload file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/batch-submit-conversion-data)                                                                                        |
| Set up automated conversion reporting         | ​[Conversions API](/integration-guides/for-brands/tracking-integrations/api-online-sale/implementation), [push file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/batch-submit-conversion-data), or [pull file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/batch-submit-conversion-data) |

## Conversion details reference

The references below let you submit new conversions.

### Event type fields

Use these fields to define what type of conversion occurred, e.g., online sale / app install. You should submit Event Type data when initially sending a conversion.

| Field             | Description                                                                                                                                                                                                                                                                            | Required?                                      | Format (Size)       | Example              | Notes                                                                                                                                                                                                                                                          |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ActionTrackerId` | Unique identifier for the event type (or action tracker) that tracked this conversion. Normal web: **Settings →** [**Event Types**](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml)**.** Mobile App: **Settings → Mobile App** | Required, unless `EventTypeCode` is provided   | INTEGER (10)        | 1000                 | Also known as `EventTrackerID`                                                                                                                                                                                                                                 |
| `EventTypeCode`   | Configurable string value for the event type that identifies it when submitting conversions. To view or configure this value, see **Settings → Event Types → Actions → View/Edit → "Codes"** in the platform.                                                                          | Required, unless `ActionTrackerId` is provided | STRING (128)        | SALE                 |                                                                                                                                                                                                                                                                |
| `EventCode`       | Custom identifier for the event that occurred in your mobile app that you want to report (e.g., INSTALL, SIGN-UP, SALE, etc.)                                                                                                                                                          | Required, when submitting mobile conversions   | STRING (128)        | INSTALL              | With Mobile events, the `ActionTrackerId` is specific to the mobile type (E.g., iOS, Android). `EventCode` is submitted to distinguish between the different mobile events (INSTALL, SIGN-UP, SALE, etc.)                                                      |
| `EventDate`       | The date and time when the conversion event occurred; use ISO 8601 format.                                                                                                                                                                                                             | Required                                       | DATETIME (ISO 8601) | 2038-01-19T03:14:08Z | NOW is also an accepted value, but should only be used when a datetime in ISO 8601 format cannot be provided. NOW records the time the event is processed, not when it occurred. If delays or outages happen, this may result in incorrect `EventDate` values. |
| `DispositionCode` | Configurable string value for the event type that will modify the conversion's Reporting State and/or Action State, depending on what's been configured.                                                                                                                               | Optional                                       | STRING (64)         | ORDER RETURNED       | Disposition codes are used to change the Reporting State of the action (report status partners can see), and/or Action State (i.e., approved, rejected, modified). See **Settings → Event Types → … → Disposition Codes** in the platform.                     |

### Attribution fields

Use these fields to determine which partner receives credit for a conversion and how the consumer journey is evaluated. You can submit attribution data when reporting new conversions.

{% hint style="success" %}
**Note:** At least one attribution key is required. See the *Required* column below for more details.
{% endhint %}

| Parameter Name                 | Type         | Description                                                                                                                                                                                                                                                                                                              | Required                                                                                                                         | Example                                                      |
| ------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `CustomerId`                   | STRING (255) | A unique identifier that you (or your systems) generate for the customer driving this conversion. These IDs should be **non-identifying** (e.g., plain text email addresses are not permitted).                                                                                                                          | Required, unless another attribution parameter is provided.                                                                      | `R523GSSD2342333FSCSA`                                       |
| `CustomProfileId`              | STRING (70)  | An ID used to uniquely identify a user on your property (regardless of whether they are signed in or not).                                                                                                                                                                                                               | Required, unless another attribution parameter is provided                                                                       | `POOWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0`                    |
| `OrderPromoCode` / `PromoCode` | STRING (255) | The promotional code associated with this conversion. Note that this only works as an attribution key if this code was assigned as a unique tracking code to a particular partner. In that case, that partner will win credit for this conversion. Otherwise, this will be reported as the promo code used for an order. | Required (if available), unless another attribution parameter is provided                                                        | `ACMEPARTNER`                                                |
| `UniqueUrl`                    | STRING (255) | Only used if you have issued unique URLs to partners for tracking purposes. You may send the unique URL here that referred this conversion. Note that these must first be set up in your account before they can be used for attribution.                                                                                | Required (if available), unless another attribution parameter is provided                                                        | <https://www.example.com/acmepartner>                        |
| `GoogAId`                      | STRING (36)  | Google `Advertising Id` associated with the mobile device the customer converted on.                                                                                                                                                                                                                                     | Required (if available), unless another attribution parameter is provided                                                        | `cdda802e-fb9c-47ad-9866-0794d394c912`                       |
| `AppleIfa`                     | STRING (36)  | `Apple Id` for Advertising (IDFA) associated with the mobile device the customer converted on.                                                                                                                                                                                                                           | Required (if available), unless another attribution parameter is provided                                                        | `EA7583CD-A667-48BC-B806-42ECB2B48606`                       |
| `AppleIfv`                     | STRING (36)  | Apple ID for Vendors (IDFV) associated with the mobile device the customer converted on.                                                                                                                                                                                                                                 | Required (if available), unless another attribution parameter is provided                                                        | `AEBE52E7-03EE-455A-B3C4-E57283966239`                       |
| `MediaId` / `MediaPartnerId`   | INTEGER (10) | ID of the partner or media source that will automatically receive credit for the conversion. By passing this value, you force them to win credit for this conversion, bypassing the consumer journey. Only used in specific cases where forced attribution is required — *do not submit this value otherwise.*           | Only used and required for Forced Attribution (read description and notes)                                                       | `1234567`                                                    |
| `ClickId`                      | STRING (64)  | An identifier for a referred click that represents the consumer's journey. When a visitor lands on your page via an impact.com tracking link, this value is generated and appended as a query string parameter, which should be captured for conversion reporting.                                                       | Required, unless another attribution parameter is provided. Required when you or your partners are passing SubIds or a SharedId. | `QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0`                    |
| `IpAddress`                    | STRING (128) | The customer's public IP address when driving the conversion. The IP address is used to help the system identify fraudulent activity. The IP address will only be used for attribution in the case of installs.                                                                                                          | Optional, primarily used for mobile app tracking                                                                                 | `72.194.216.61` or `2001:0db8:85a3:0000:0000:8a2e:0370:7334` |
| `PhoneNumber`                  | STRING       | Phone number the customer called in call tracking conversions. If call tracking is configured to use unique phone numbers, value is used to match the conversion to the originating call record.                                                                                                                         | Only used and required for Call Tracking (read description and notes)                                                            | `15558675309`                                                |
| `CallerId`                     | STRING       | Unique identifier of the customer in call tracking conversions. Value is used to match the conversion to the originating call record.                                                                                                                                                                                    | Only used and required for Call Tracking (read description and notes)                                                            |                                                              |
| `CountryCode`                  | STRING (2)   | Two-letter country code of the customer's phone country code; use ISO 3166-1 alpha-2.                                                                                                                                                                                                                                    | Only used and required for Call Tracking (read description and notes)                                                            | `US`                                                         |

{% hint style="success" %}
**Note:** If available, it's generally always recommended to pass the ClickId value when reporting a conversion. Also note that any generated ClickId value can be associated with multiple clicks — it is not unique to an individual click.
{% endhint %}

### Program fields <a href="#program-fields" id="program-fields"></a>

Use this field to associate a conversion with a specific impact.com program (formerly known as a campaign). Every conversion must belong to a program.

| Parameter Name | Type         | Description                                                                             | Required | Example | Notes                                                      |
| -------------- | ------------ | --------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------- |
| `CampaignId`   | INTEGER (10) | Unique identifier for the campaign (or program) that the conversion is associated with. | Required | `1000`  | This value is always required when submitting conversions. |

## Advanced scenarios reference

These references are relevant only to specific tracking configurations, e.g., parent-child events or phone call events.

### Chained action fields

Chained actions allow impact.com to associate follow-up events with an original conversion, e.g., a ticket sale with an initial reservation. Use these fields to link together multiple related conversion events.

| Parameter Name | Format (Size) | Description                                                                                                                                                                                    | Requirement | Example              | Notes                                                                                                                                                                                                                                    |
| -------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CustomerId`   | STRING (255)  | A unique identifier that you (or your systems) generate for the customer driving this conversion. These IDs should be **non-identifying** (e.g. plain text email addresses are not permitted). | Required    | R523GSSD2342333FSCSA | This key will be used for insights reporting along with conversion chaining. In the case of chained actions, for the Child Tracker, you should pass the same customer ID as that of the Parent event or else it won't chain the actions. |

### Call conversion fields

{% hint style="warning" %}
**Warning:** Native phone number tracking has been deprecated. For alternative solutions, use a [supported 3rd-party provider](https://integrations.impact.com/brand-api-reference/reference/call-data) like Invoca.
{% endhint %}

Use these fields when reporting conversions that originate from tracked phone calls. This data is only required for call tracking integrations and should not be sent for web or app conversions.

| Parameter name                | Format              | Requirement | Description                                                                                                                                                                                                                                                       |
| ----------------------------- | ------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CampaignId`                  | INTEGER             | Required    | Unique identifier for the campaign (or program) that the call conversion is associated with.                                                                                                                                                                      |
| `MediaId`                     | INTEGER             | Required    | Unique identifier for the partner or media source.                                                                                                                                                                                                                |
| `EventDate`                   | DATETIME (ISO 8601) | Required    | ISO 8601 format of the date and time when the call conversion event occurred.                                                                                                                                                                                     |
| `ActionTrackerId`             | INTEGER             | Required    | Unique identifier for the action tracker (i.e., event type) that's tracking the phone call.                                                                                                                                                                       |
| `CallProvider`                | STRING              | Required    | The vendor or client who is sending the call event data                                                                                                                                                                                                           |
| `CallSessionId`               | STRING              | Required    | A unique session ID that the vendor or client uses to identify the call.                                                                                                                                                                                          |
| `CallerId`                    | STRING              | Required    | The phone number of the originating call, used to match the final conversion.                                                                                                                                                                                     |
| `CalledPhoneNumber`           | STRING              | Required    | The destination phone number or the phone number that received the call.                                                                                                                                                                                          |
| `CallDuration`                | STRING              | Required    | Total duration (in seconds) of the call.                                                                                                                                                                                                                          |
| `TalkDuration`                | STRING              | Required    | Actual talk duration (in seconds) of the call.                                                                                                                                                                                                                    |
| `AdId`                        | INTEGER             | Optional    | Unique identifier for the ad associated with the call conversion.                                                                                                                                                                                                 |
| `CallStatus`                  | STRING              | Optional    | This value indicates the final outcome of the call. If the field is not present in request, we make it `ANSWER` by default. Valid values are: `UNKNOWN_CALLERID`, `FAILURE`, `CONGESTION`, `INCOMPLETE`, `CANCEL`, `IVR_DROPOFF`, `NO_TRANSFER_ATTEMPT`, `ANSWER` |
| `CallerPhoneNumberCountry`    | STRING              | Optional    | Two-digit country code for the originating phone number (ISO 3166 alpha-2). When NULL, defaults to US.                                                                                                                                                            |
| `CalledPhoneNumberCountry`    | STRING              | Optional    | Two-digit country code for the called phone number (ISO 3166 alpha-2). When NULL, defaults to US.                                                                                                                                                                 |
| `SubId1`                      | STRING              | Optional    | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them.                                                                                 |
| `SubId2`                      | STRING              | Optional    | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them.                                                                                 |
| `SubId3`                      | STRING              | Optional    | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them.                                                                                 |
| `ClickId`                     | STRING              | Optional    | Unique case-sensitive identifier generated by impact.com of a referring click, used to construct a consumer journey.                                                                                                                                              |
| `Country`                     | STRING              | Optional    | Country of the CallerId - as identified by the call tracking vendor.                                                                                                                                                                                              |
| `City`                        | STRING              | Optional    | City of the CallerId - as identified by the call tracking vendor.                                                                                                                                                                                                 |
| `Region`                      | STRING              | Optional    | Region of the CallerId - as identified by the call tracking vendor.                                                                                                                                                                                               |
| `Zip`                         | INTEGER             | Optional    | Zip of the CallerId - As identified by the call tracking vendor.                                                                                                                                                                                                  |
| `RepeatCaller`                | STRING              | Optional    | Repeat vs New call to indicate whether the caller was recorded as a repeat caller by the call tracking vendor.                                                                                                                                                    |
| `PhoneType`                   | STRING              | Optional    | The type of phone (i.e., landline, mobile).                                                                                                                                                                                                                       |
| `CallRecording`               | STRING              | Optional    | Unique URL of the call recording.                                                                                                                                                                                                                                 |
| `IvrDuration`                 | STRING              | Optional    | Duration in seconds that the call spent in the IVR tree.                                                                                                                                                                                                          |
| `Keypresses`                  | STRING              | Optional    | List of unique key names that were pressed during the call.                                                                                                                                                                                                       |
| `Key1`                        | STRING              | Optional    | Name of the first key that was pressed.                                                                                                                                                                                                                           |
| `Key2`                        | STRING              | Optional    | Name of the second key that was pressed.                                                                                                                                                                                                                          |
| `Key3`                        | STRING              | Optional    | Name of the third key that was pressed.                                                                                                                                                                                                                           |
| `Key4`                        | STRING              | Optional    | Name of the fourth key that was pressed.                                                                                                                                                                                                                          |
| `TrafficSource`               | STRING              | Optional    | Source of the transaction (referring media source).                                                                                                                                                                                                               |
| `OptInSms`                    | STRING              | Optional    | Whether the caller opted in to receive an SMS promotion.                                                                                                                                                                                                          |
| `UserAgent`                   | STRING              | Optional    | The user agent of the conversion generator.                                                                                                                                                                                                                       |
| `DispositionName`             | STRING              | Optional    | The Conversion Event Name.                                                                                                                                                                                                                                        |
| `SaleAmount`                  | CURRENCY            | Optional    | If Sale Conversion, Sale Amount                                                                                                                                                                                                                                   |
| `ReferenceId`                 | STRING              | Optional    | Customer Disposition Code for reference.                                                                                                                                                                                                                          |
| `CustomConversionEvent1Name`  | STRING              | Optional    | Custom name for reporting on conversion events                                                                                                                                                                                                                    |
| `CustomConversionEvent2Name`  | STRING              | Optional    | Custom name for reporting on conversion events                                                                                                                                                                                                                    |
| `CustomConversionEvent3Name`  | STRING              | Optional    | Custom name for reporting on conversion events                                                                                                                                                                                                                    |
| `CustomConversionEvent1Value` | STRING              | Optional    | Custom value for reporting on conversion events                                                                                                                                                                                                                   |
| `CustomConversionEvent2Value` | STRING              | Optional    | Custom value for reporting on conversion events                                                                                                                                                                                                                   |
| `CustomConversionEvent3Value` | STRING              | Optional    | Custom value for reporting on conversion events                                                                                                                                                                                                                   |
| `VendorEventId`               | STRING              | Optional    | Will be unique for call event and unique for the conversion event.                                                                                                                                                                                                |
| `PromoNumberDescription`      | STRING              | Optional    | Describes the called phone number                                                                                                                                                                                                                                 |
| `CustomCallEvent1Name`        | STRING              | Optional    | Custom name for reporting on call events                                                                                                                                                                                                                          |
| `CustomCallEvent2Name`        | STRING              | Optional    | Custom name for reporting on call events                                                                                                                                                                                                                          |
| `CustomCallEvent3Name`        | STRING              | Optional    | Custom name for reporting on call events                                                                                                                                                                                                                          |
| `CustomCallEvent1Value`       | STRING              | Optional    | Custom value for reporting on call events                                                                                                                                                                                                                         |
| `CustomCallEvent2Value`       | STRING              | Optional    | Custom value for reporting on call events                                                                                                                                                                                                                         |
| `CustomCallEvent3Value`       | STRING              | Optional    | Custom value for reporting on call events                                                                                                                                                                                                                         |

## Optional reporting fields reference

Use these fields to add extra context to a conversion for reporting or troubleshooting. These fields are all optional and enhance reporting, segmentation, and analytics. If you don’t need this data in your reports, you can leave these fields out.

| Parameter Name     | Type           | Description                                                                                                                                                                                                                                                                                        | Required/Optional | Example       |
| ------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------- |
| `Money1-3`         | DECIMAL (18,3) | General decimal fields for any financial data. Appears in reports.                                                                                                                                                                                                                                 | Optional          | 12345.67      |
| `Numeric1-3`       | DECIMAL (18,3) | General decimal fields for any numeric data. Appears in reports.                                                                                                                                                                                                                                   | Optional          | 987654.321    |
| `Date1-3`          | STRING (30)    | <p>General date fields for any date/datetime. Appears in reports.<br><br>Accepted formats: <code>2026-08-21T07:25:00Z</code>, <code>2026-08-06</code>, <code>2026-08-06 13:14:57</code>, <code>2026-08-06T13:14:57.000Z</code>, <code>2026-08-06T13:14:57-07:00</code>, <code>2026-8-6</code>.</p> | Optional          | 2038-01-19    |
| `SubId1-3`         | STRING (255)   | General fields used for event-level reporting purposes.                                                                                                                                                                                                                                            | Optional          |               |
| `Text1-50`         | STRING (64)    | General text fields for adding any text data. Modifiable and appears in reports.                                                                                                                                                                                                                   | Optional          |               |
| `ItemText1-10`     | STRING (64)    | General text fields for adding item text data.                                                                                                                                                                                                                                                     | Optional          |               |
| `ItemNumeric1-10`  | DECIMAL (18,3) | General decimal fields for any numeric data.                                                                                                                                                                                                                                                       | Optional          | 10.00         |
| `ItemDate1-10`     | STRING (30)    | <p>General item date fields.<br><br>Accepted formats: <code>2026-08-21T07:25:00Z</code>, <code>2026-08-06</code>, <code>2026-08-06 13:14:57</code>, <code>2026-08-06T13:14:57.000Z</code>, <code>2026-08-06T13:14:57-07:00</code>, <code>2026-8-6</code>.</p>                                      | Optional          | 2028-01-19    |
| `ItemMoney1-3`     | DECIMAL (18,3) | Decimal fields for item financial data.                                                                                                                                                                                                                                                            | Optional          | 12345.67      |
| `UserAgent`        | STRING (255)   | Describes the user agent associated with the conversion.                                                                                                                                                                                                                                           | Optional          | Mozilla/5.0   |
| `CustomerStatus`   | STRING (30)    | Customer status at the time of conversion.                                                                                                                                                                                                                                                         | Optional          | New           |
| `CustomerCity`     | STRING (255)   | Customer's city during conversion.                                                                                                                                                                                                                                                                 | Optional          | Amsterdam     |
| `CustomerCountry`  | STRING (255)   | Customer's country during conversion.                                                                                                                                                                                                                                                              | Optional          | Netherlands   |
| `CustomerPostCode` | STRING (255)   | Customer's postal code during conversion.                                                                                                                                                                                                                                                          | Optional          | 1011 AC       |
| `CustomerRegion`   | STRING (255)   | Customer's region during conversion.                                                                                                                                                                                                                                                               | Optional          | North Holland |


# Action Modification & Reversal Field References

Use this reference to identify the fields for modifying, reversing, or approving existing conversions in bulk.\
\
Use [Conversion Submission Field References](/integration-guides/for-brands/action-and-conversion-field-references/conversion-submission-field-references) to submit new conversions in bulk.

| If you want to...                             | Use this method...                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Submit a manual, one-time file with no coding | ​[Email](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/submit-conversion-data-via-ftp-or-email#before-you-start) batch processing or [upload file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/batch-modify-conversion-data/submit-batch-modifications-and-reversals#upload-file-to-system-ftp-server)                                                                                                                                                                                                                 |
| Set up automated conversion reporting         | ​[Conversions](https://integrations.impact.com/brand-api-reference/reference/conversions/conversions) / [Actions](https://integrations.impact.com/brand-api-reference/reference/actions) API, [push file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/batch-modify-conversion-data/submit-batch-modifications-and-reversals#upload-file-to-system-ftp-server), or [pull file via FTP](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/batch-modify-conversion-data/submit-batch-modifications-and-reversals#pull-file-from-your-own-ftp-server) |

## Action processing reference

Use these fields to [modify or reverse action data in bulk](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/batch-modify-conversion-data/submit-batch-modifications-and-reversals) after a conversion has occurred.

### Modification fields

Use these fields to process modifications or approvals of partner-driven actions. You can apply changes at either the order level or item level, depending on whether the change affects the entire order or specific items within it.

<table><thead><tr><th>Field</th><th width="128">Level</th><th>Required?</th><th>Description</th><th>Editable?</th><th>Note for use</th><th>Format</th><th>Example</th></tr></thead><tbody><tr><td><code>ActionID</code></td><td>Order/Item</td><td>Conditionally Required</td><td>An action’s unique identifier, used to specify which action you want to modify.</td><td>Non-editable</td><td>Recommended when the deduplication window is short. At least one identifier path must be provided (<code>ActionID</code> or <code>OrderId/Oid</code> + <code>ActionTrackerId</code>).</td><td>Integer (10)</td><td>12345</td></tr><tr><td><code>Oid</code> / <code>OrderId</code></td><td>Order/Item</td><td>Conditionally Required</td><td>Value you assign to the order—typically an order ID or confirmation number.</td><td>Non-editable</td><td>Required when using <code>ActionTrackerID</code>. At least one identifier path must be provided (<code>ActionID</code> or <code>OrderId/Oid</code> + <code>ActionTrackerId</code>).</td><td>String (64)</td><td>T52324111211</td></tr><tr><td><code>ActionTrackerID</code></td><td>Order/Item</td><td>Conditionally Required</td><td>Value impact.com assigns to the Event Type that tracked the action.</td><td>Non-editable</td><td>Required when using <code>OrderId/Oid</code>. At least one identifier path must be provided (<code>ActionID</code> or <code>OrderId/Oid</code> + <code>ActionTrackerId</code>).</td><td>Integer (10)</td><td>98765</td></tr><tr><td><code>Amount</code>*</td><td>Order/Item</td><td>Conditionally Required</td><td>Total amount of the order/item, pre-tax, pre-shipping, and post-discount.</td><td>Editable</td><td>Set the new total amount for the order. If you modify <code>Quantity</code>, this field requires modification too.</td><td>Decimal (8,2)</td><td>1234.99</td></tr><tr><td><code>CustomerStatus</code></td><td>Order</td><td>Optional</td><td>The customer’s status at the time of conversion.</td><td>Editable</td><td>Set the customer’s status at the time of conversion (e.g., New).</td><td>String (30)</td><td>New</td></tr><tr><td><code>SKU</code>*</td><td>Item</td><td>Required</td><td>Unique stock-keeping unit (SKU) of the product.</td><td>Non-editable</td><td>Provide the SKU of the item you want to modify. Must be included for each item.</td><td>String (255)</td><td>ABC123</td></tr><tr><td><code>Quantity</code>*</td><td>Item</td><td>Optional</td><td>Quantity of the item that was purchased in the order.</td><td>Editable</td><td>Set the new quantity of items in the order.</td><td>Integer</td><td>1</td></tr><tr><td><code>Category</code>*</td><td>Item</td><td>Optional</td><td>Category for the product - can be automatically pulled if a product catalog has been uploaded.</td><td>Editable</td><td>Set the category of the item.</td><td>String (255)</td><td>Footwear</td></tr><tr><td><code>Reason</code>*</td><td>Order/Item</td><td>Required</td><td>Your reason for modifying the action data.</td><td>Editable</td><td>Provide a valid <a href="/spaces/wMLlMoFBtKJa8ptd3zaw/pages/grLBZqm6GXUeKWoVD923">reason code</a> for the modification. For item-level modifications, include a <code>Reason</code> for each item.</td><td>String</td><td><code>ITEM_RETURNED</code> (See supported values)</td></tr></tbody></table>

\*When modifying multiple items in an order, these fields must be included for each item. The identifier fields are always included only once per order.

{% hint style="info" %}
**Tip:** If you want to approve actions, *Approve* needs to be set up as a [custom disposition code](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/tracking/set-up-tracking/manage-disposition-codes). You can then submit the approval with its reason code as you would a modification.
{% endhint %}

### Reversal fields

Use these fields to process reversals of partner-driven actions. You can apply reversals at the order level to reverse an entire order, or at the item level to reverse individual items within an order.

| Field             | Level      | Required?              | Description                                                                     | Editable?    | Note for use                                                                                                                                                                                                              | Format        | Example      |
| ----------------- | ---------- | ---------------------- | ------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------ |
| `ActionID`        | Order/Item | Conditionally Required | An action’s unique identifier, used to specify which action you want to modify. | Non-editable | Recommended when the deduplication window is short. At least one identifier path must be provided (`ActionID` or `OrderId/Oid` + `ActionTrackerId`).                                                                      | Integer (10)  | A12345       |
| `Oid` / `OrderId` | Order/Item | Conditionally Required | Value you assign to the order—typically an order ID or confirmation number.     | Non-editable | Required when using `ActionTrackerID`. At least one identifier path must be provided (`ActionID` or `OrderId/Oid` + `ActionTrackerId`).                                                                                   | String (64)   | T52324111211 |
| `ActionTrackerID` | Order/Item | Conditionally Required | Value impact.com assigns to the Event Type that tracked the action.             | Non-editable | Required when using `OrderId/Oid`. At least one identifier path must be provided (`ActionID` or `OrderId/Oid` + `ActionTrackerId`).                                                                                       | Integer (10)  | 98765        |
| `Amount`\*        | Order/Item | Conditionally Required | Total amount of the order/item, pre-tax, pre-shipping, and post-discount.       | Editable     | Adjust accordingly when reversing an item, or set to **0** to reverse the order (unless original order *Amount = 0*). If original order *Amount = 0*, leave `Amount` unchanged to avoid misclassifying as a modification. | Decimal (8,2) | 0            |
| `SKU`\*           | Item       | Required               | Unique stock-keeping unit of the product.                                       | Non-editable | Provide the SKU value of the item you want to reverse.                                                                                                                                                                    | String (255)  | ABC123       |
| `Quantity`\*      | Item       | Optional               | Quantity of the item that was purchased in the order.                           | Editable     | Set the new quantity of items in the order.                                                                                                                                                                               | Integer       | 0            |
| `Reason`\*        | Order/Item | Required               | Your reason for reversing the action data.                                      | Editable     | Provide a valid [reason code](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/tracking/set-up-tracking/manage-disposition-codes) for the reversal.                                     | String        | `RETURN`     |

\*When reversing multiple items in an order, these fields must be included for each item. The identifier fields are always included only once per order.

{% hint style="warning" %}
**Warning:** If original order *Amount = 0*, leave *Amount* unchanged to avoid misclassifying as a modification.
{% endhint %}

### Additional optional fields <a href="#additional-optional-fields" id="additional-optional-fields"></a>

While the fields above are those most commonly used in modifications and reversals, these additional fields can also be submitted when needed. Include them only when you want to modify them.

| Field               | Level | Description                                                                                                                           | Editable? | Format         | Example        |
| ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- | -------------- |
| `PaymentType`       | Order | Method of payment used for this conversion.                                                                                           | Editable  | STRING (32)    | CREDIT         |
| `OrderSubtotal`     | Order | Subtotal of the order before discounts, taxes, shipping, or other costs.                                                              | Editable  | DECIMAL        | 49.99          |
| `OrderDiscount`     | Order | Total discount applied to the order. Automatically subtracted from the order total. Exclude shipping discounts.                       | Editable  | DECIMAL (12,2) | 3.99           |
| `OrderShipping`     | Order | Cost of shipping for this conversion. Total sale amount used for payout excludes shipping.                                            | Editable  | DECIMAL (14,2) | 9.99           |
| `OrderTax`          | Order | Cost of tax for this conversion. Total sale amount used for payout excludes tax.                                                      | Editable  | DECIMAL (14,2) | 8.99           |
| `OrderMargin`       | Order | Total margin on the conversion (revenue less costs). Typically provided through product catalog.                                      | Editable  | DECIMAL (14,2) | 12.34          |
| `GiftPurchase`      | Order | Indicates if the order is a gift purchase. Submit `true` for gift, `false` otherwise.                                                 | Editable  | BOOLEAN        | true/false     |
| `LocationId`        | Order | Unique identifier for the location in accommodations or similar contexts.                                                             | Editable  | STRING (64)    | SBHOTEL        |
| `LocationName`      | Order | Name of the location in accommodations or similar contexts.                                                                           | Editable  | STRING (64)    | Fess Parker    |
| `LocationType`      | Order | Category of the location in accommodations or similar contexts.                                                                       | Editable  | STRING (64)    | Hotel          |
| `ItemSubCategory`   | Item  | Subcategory for the product, if applicable. Can be automatically pulled from a product catalog.                                       | Editable  | STRING (255)   | Metalsmithing  |
| `Name`              | Item  | Name of the product. Can be automatically appended via product catalog.                                                               | Editable  | STRING (255)   | Iron Anvil     |
| `ItemMpn`           | Item  | Manufacturer part number (MPN) for the product. Can be pulled from a product catalog.                                                 | Editable  | STRING (64)    | 123456789      |
| `ItemBrand`         | Item  | Brand name of the product. Can be automatically pulled from a product catalog.                                                        | Editable  | STRING (64)    | Acme Corp      |
| `ItemDiscount`      | Item  | Discount applied to each product of this type, not the entire line item.                                                              | Editable  | DECIMAL (12,2) | 2.99           |
| `ItemPromoCode`     | Item  | Promotional code applied to this item. Does not work with unique tracking codes for partners.                                         | Editable  | STRING (255)   | ITEMDISCOUNT10 |
| `ItemTotalDiscount` | Item  | Discount applied to this line item. Automatically subtracted from `ItemSubTotal` to determine final sale amount for payout/reporting. | Editable  | DECIMAL (12,2) | 49.99          |
| `ItemDeliveryType`  | Item  | Type of delivery method for this item.                                                                                                | Editable  | STRING (64)    | EXPRESS        |


# Item-Level Template

Use the item-level template to prepare conversion data for [submission via FTP or email](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/submit-conversion-data-via-ftp-or-email). You can copy it directly from the code block below, or download it as a CSV file and open it with your preferred spreadsheet application.

### Copy the template

**Blank template**

{% tabs %}
{% tab title="CSV" %}

```csv
CampaignId,ActionTrackerId,OrderId,EventDate,Amount,CurrencyCode,Sku,Category,Quantity,ClickId
```

{% endtab %}
{% endtabs %}

**Template with sample data**

{% tabs %}
{% tab title="CSV" %}

```csv
CampaignId,ActionTrackerId,OrderId,EventDate,Amount,CurrencyCode,Sku,Category,Quantity,ClickId
1111,12345,9876543,2038-01-19T10:26:05-04:00,215.53,USD,987XYZ6540111,birdseed,1,ZfXLH51WY5DghyMkWGJ7CpX3O0IyPqM2c5e3t5Z
1111,12345,9876543,2038-01-19T10:26:05-04:00,140.72,USD,123ABC5670111,metal,1,r1NJgMzZnYtKETog6J5yVBCPi152BwWzlRXBaYk
```

{% endtab %}
{% endtabs %}

### Download as a CSV

* [Item level template](https://res.cloudinary.com/product-enablement/raw/upload/v1744106104/Submit_Conversion_Data_-_Item-Level_Template_-_Sample_data_l0xzxp.csv) for submitting conversion data
* [Item level template](https://res.cloudinary.com/product-enablement/raw/upload/v1768295823/CSVs/Batch%20Action%20Processing/Item-level_modifications_template.csv) for modifications
* [Item level template](https://res.cloudinary.com/product-enablement/raw/upload/v1768298926/CSVs/Batch%20Action%20Processing/Item-level_reversals_template.csv) for reversals

<br>


# Order-Level Template

Use the order-level template to prepare conversion data for [submission via FTP or email](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/submit-conversion-data-via-ftp-or-email). You can copy it directly from the code block below, or download it as a CSV file and open it with your preferred spreadsheet application.

### Copy the template

**Blank template**

{% tabs %}
{% tab title="CSV" %}

```csv
CampaignId,ActionTrackerId,OrderId,EventDate,Amount,CurrencyCode,ClickId
```

{% endtab %}
{% endtabs %}

**Template with sample data**

{% tabs %}
{% tab title="CSV" %}

```csv
CampaignId,ActionTrackerId,OrderId,EventDate,Amount,CurrencyCode,ClickId
1111,12345,9876543,2038-01-19T10:26:05-04:00,123.45,USD,ZfXLH51WY5DghyMkWGJ7CpX3O0IyPqM2c5e3t5Z
1111,12345,1234567,2038-01-20T11:21:43-04:00,98.76,USD,r1NJgMzZnYtKETog6J5yVBCPi152BwWzlRXBaYk
```

{% endtab %}
{% endtabs %}

### Download as a CSV

Alternatively, you can download this template as a CSV. Then, open it in your preferred spreadsheet application and add your data.

* [Order level template](https://res.cloudinary.com/product-enablement/raw/upload/v1744041202/Submit_Conversion_Data_-_Order-Level_Template_-_Sample_data_ran6tj.csv) for submitting conversion data
* [Order level template](https://res.cloudinary.com/product-enablement/raw/upload/v1768295823/CSVs/Batch%20Action%20Processing/Order-level_modifications_template.csv) for modifications
* [Order level template](https://res.cloudinary.com/product-enablement/raw/upload/v1768295823/CSVs/Batch%20Action%20Processing/Order-level_reversals_template.csv) for reversals


# Chained Actions Template

Use the chained actions template to prepare conversion data for [submission via FTP or email](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/submit-conversion-data-via-ftp-or-email). You can copy it directly from the code block below, or download it as a CSV file and open it with your preferred spreadsheet application.

{% hint style="success" %}
**Note:** Providing values for **both** ClickId and CustomerId is optional. ClickId is the more commonly-used attribution method.
{% endhint %}

### Copy the template

**Blank template**

```csv
CampaignId,ActionTrackerId,CustomerId,OrderId,EventDate,Amount,CurrencyCode,ClickId
```

**Template with sample data**

```csv
CampaignId,ActionTrackerId,CustomerId,OrderId,EventDate,Amount,CurrencyCode,ClickId
1111,45678,R523GSSD2,9876543,2038-01-19T10:26:05-04:00,123.45,USD,ZfXLH51WY5DghyMkWGJ7CpX3O0IyPqM2c5e3t5Z
1111,12345,R523GSSD2,8765432,2038-01-20T12:16:22-04:00,98.76,USD,r1NJgMzZnYtKETog6J5yVBCPi152BwWzlRXBaYk
```

### Download as a CSV

Alternatively, you can download this template as a CSV. Then, open it in your preferred spreadsheet application and add your data.

* [Chained actions template](https://res.cloudinary.com/product-enablement/raw/upload/v1744041202/Submit_Conversion_Data_-_Chained_Actions_Template_-_Sample_data_a6z28e.csv) for submitting conversion data


# Advocate


# Integrate SMS Messaging into Your Advocate Referral Program

impact.com doesn't offer a native SMS integration for Advocate, but you can build one using the Advocate REST API and webhooks. This guide explains how to retrieve referral links and discount codes and how to trigger SMS messages at key points in a referral flow. For example, sending an invite, delivering a friend's discount code, or confirming a reward.&#x20;

{% hint style="warning" %}
**Important:** This integration guide assumes familiarity with REST APIs and webhooks; non-technical users will likely find this integration difficult to implement without developer support.
{% endhint %}

```mermaid
flowchart TB
    API["Advocate API"]
    FE["Your frontend"]
    HOOK["Your webhook endpoint"]
    SMS["SMS provider"]

    API <-->|"Referral code + link"| FE
    API <-->|"reward.created event"| HOOK
    FE -->|"Send SMS: link"| SMS
    HOOK -->|"Send SMS: code (+ link)"| SMS
```

## Why build an SMS integration

Referral programs often perform best over SMS, but Advocate doesn't have the capability to send SMS messages directly. Instead, you connect Advocate's data to your own SMS provider, e.g., Twilio, Attentive, using API calls and webhook events. A typical SMS referral flow strings together several messages, such as:

1. An initial "refer your friends" message to existing customers.
2. A "here's your code" message when a referred friend joins the program.
3. A reminder if a referred friend hasn't completed a purchase.
4. A confirmation when a referred friend places an order.
5. A reward message to the original referrer once they qualify.

Each message depends on knowing *what* data to fetch and *when* to fetch it. The rest of this guide covers both.

## Common integration patterns

* **Send a referral link on demand** — call [**Lookup a User**](/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user#get-tenant_alias-account-accountid-user-userid) when a participant requests their link, e.g., tapping "invite friends" in an app, then send it by SMS.
* **Trigger an SMS when a reward is created** — subscribe to `reward.created`, extract the discount code, and fire the SMS immediately.
* **Chain multiple messages from one trigger** — use the data from the initial webhook to schedule follow-up messages (reminders, confirmations) through your SMS provider or a job scheduler.

## Data you can access for SMS messages

Two pieces of data drive most SMS referral flows: a participant's referral link and their discount code. They come from different parts of the API.

### Referral links

Retrieve a participant's referral link with the [Lookup a User endpoint](/brand-api-reference/advocate-api-reference-v1/reference/user-overview). This is an on-demand call — use it whenever you need a share link to include in an SMS.

* `GET /{tenant_alias}/account/{accountId}/user/{userId}` — look up by user ID
* `GET /{tenant_alias}/user?referralCode={code}` — look up by referral code

Both return `referralCode` and `shareLinks` (the participant's referral links, organized by share medium — including SMS — and engagement type).

### Discount codes

Discount codes can be retrieved two ways:

| Method                                                                                                                                                      | Recommendation                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`reward.created` webhook](https://integrations.impact.com/integration-guides/for-brands/advocate/pages/eXuv1TBheoZgQxDb75yr#reward.created)                | Real-time events — recommended for triggering SMS the moment a reward is issued |
| [Rewards API](/brand-api-reference/advocate-api-reference-v1/reference/reward-overview) (`GET /{tenant_alias}/reward` or `GET /{tenant_alias}/reward/{id}`) | On-demand lookups, e.g. for support tooling or reconciliation                   |

The webhook payload does not include the participant's referral link, so most flows that need both a code and a link end up calling the Lookup a User endpoint as a follow-up.

## Trigger an SMS with the `reward.created` webhook&#x20;

`reward.created` fires when a reward becomes available, for example, when a referred friend completes their first purchase and the reward pending period has ended. One [webhook subscription](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/create-and-manage-advocate-webhook-subscriptions) covers every reward-issuing scenario, e.g., a friend opting in, or a referrer qualifying for a reward, so you don't need separate subscriptions per scenario.

Delivery order and timing between events aren't guaranteed, so don't build logic that depends on webhooks arriving in a specific sequence. If your endpoint doesn't return a `200` response, impact.com retries delivery hourly for up to approximately 3 days (72 attempts) before giving up.

{% stepper %}
{% step %}

### Create a subscription

You can create a subscription using one of the following methods:

* **Using the Webhook API:** [`POST /{tenant_alias}/subscription`](/brand-api-reference/advocate-api-reference-v1/reference/webhook-overview/webhook#post-tenant_alias-subscription) with body:

{% code expandable="true" %}

```json
{
"endpointUrl": "https://your-domain.com/webhooks/advocate", 
"webhookTypes": ["reward.created"], 
"name": "sms-reward-trigger"
}
```

{% endcode %}

* **Through the UI:** Refer to [Create & Manage Advocate Webhook Subscriptions](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/create-and-manage-advocate-webhook-subscriptions) for more information.
  {% endstep %}

{% step %}

### Send a test event to confirm delivery

`POST /{tenant_alias}/subscription/{url}/test`

Every webhook event shares this envelope:

{% code expandable="true" %}

```json
{
  "id": "evt_3f2a1c9e",          // Unique identifier for this event
  "type": "FUELTANK",            // Webhook event type
  "fuelTankCode": "FRIEND8389KP3", // The specific code associated with the fueltank reward
  "tenantAlias": "yourbrand",    // The tenant this event belongs to
  "live": false,                  // true for Live tenant events, false for Test
  "created": 1731542400000,      // Event creation timestamp, in milliseconds
  "data": {                      // Event-specific payload — the reward object for reward.created
    "id": "rew_8d4b2f11",         // Unique reward identifier
    "type": "PCT_DISCOUNT",       // Reward type: PCT_DISCOUNT, CREDIT, or FUELTANK
    "userId": "usr_7a1c9e2b",     // Owner of the reward — pass to Lookup a User for the referral link
    "referralId": "ref_5e9d4a01", // The referral that triggered this reward
    "amount": 15,                 // Quantity earned
    "currency": "USD",            // Currency for credit-based rewards
    "dateGiven": "2026-07-10T14:32:00Z" // When the reward was issued
  }
}
```

{% endcode %}
{% endstep %}

{% step %}

### Extract the reward data

When the webhook fires, parse the payload and extract the reward data from the `data` field.
{% endstep %}

{% step %}

### Send the SMS

Send the SMS using the data available in the payload.&#x20;
{% endstep %}

{% step %}

### (Optional) Retrieve the participant's referral link

If you also need the participant's referral link, call [**Lookup a User**](/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user#get-tenant_alias-account-accountid-user-userid) with the `userId` from the payload.&#x20;
{% endstep %}
{% endstepper %}

## Implementation checklist

* [ ] Create a webhook subscription for `reward.created` and confirm it with a test event
* [ ] Parse the webhook payload and validate the `data` object before using it
* [ ] Handle delivery failures — your endpoint should return `200` promptly, since non-200 responses trigger hourly retries for up to 3 days
* [ ] Call Lookup a User when you need a referral link alongside a discount code
* [ ] Test the full flow end-to-end with your SMS provider before going live


# Integrate Advocate with Optimize

This guide explains how to integrate Advocate activities with Optimize, ensuring that referral and advocate-driven traffic is accurately tracked and displayed in Optimize reports.

Integrating Advocate with Optimize allows you to:

* Attribute referral traffic and conversions to the Advocate channel.
* Analyze the performance of advocate-driven campaigns alongside other marketing channels.
* Surface advocate activities in Optimize reports for better decision-making.

### Prerequisites

* [Universal Tracking Tag (UTT)](/integration-guides/for-brands/advocate/advocate-tracking-integrations/implement-with-utt-for-advocate) or [Page Load API](https://integrations.impact.com/brand-api-reference/reference/page-load/page-load) must be implemented on your website to report all referral activity to impact.com.
* Your Advocate program must be active and generating referral links.
* Access to Optimize with permissions to configure channels and rules.

### How Advocate activities are tracked in Optimize

Advocate activities are tracked in Optimize by capturing clicks and conversions that originate from [referral codes or share links](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/assign-vanity-share-links-or-referral-codes) generated by your Advocate program. These activities are identified using specific URL parameters and are categorized into the appropriate channel within Optimize.

Optimize uses a combination of the following to allocate traffic to channels:

* UTM parameters (e.g., `utm_source`, `utm_medium`)
* Custom parameters (e.g., `rscode`)
* Referrer data

### Setting up Advocate as a channel in Optimize

{% stepper %}
{% step %}

#### Enable default channels

1. In the left navigation menu, select ![](/files/zm9mkdwQDEB5qaYnKweJ) **Optimize → Settings →** [**Channels**](https://app.impact.com/secure/advertiser/optimize/mediamanager/channels/list-mediasource-channels-flow.ihtml) and ensure that the *Direct* and *Organic Referral* channels are enabled.

<div data-with-frame="true"><figure><img src="/files/02eHtxtjFhqh60FKsuME" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Configure Rules to Identify (RTI) for Advocate

1. In the left navigation menu, select ![](/files/zm9mkdwQDEB5qaYnKweJ) **Optimize → Settings →** [**Channels**](https://app.impact.com/secure/advertiser/optimize/mediamanager/channels/list-mediasource-channels-flow.ihtml).
2. Select **Create Channel** or select ![](/files/QIUzi1ogqnG2NvotPFQE) **\[More] → Edit** if you already have an existing *Advocate* channel. Learn more about [creating a channel](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/cross-channel-performance-insights/optimize-channels/create-an-optimize-channel).
3. Ensure that *Identify Channel Traffic* is ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggled on]**.
4. In the *Rules to identify* section, define rules that capture traffic with parameters unique to Advocate referrals (see next section).

<div data-with-frame="true"><figure><img src="/files/9Hiumo5KMuCrgfEYhfgw" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Test and save your rule

* Test by generating a referral link from Advocate and clicking through to ensure the activity appears in Optimize under the correct channel.
* Select a [credit group](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/actions-and-payouts/credit-groups-explained) to assign the rule to.
* Select **Save** to save your channel configuration.
  {% endstep %}
  {% endstepper %}

### Key parameters for tracking

* `rscode`: A unique referral code parameter appended to Advocate-generated links. Optimize can use this to identify and attribute traffic to the Advocate channel.
* `utm_source`: Indicates the source of the traffic. Set to `referral` for Advocate-generated links (e.g. `utm_source=referral`).
* `utm_medium`: Indicates the marketing medium. Use this to categorise the type of referral traffic (e.g. `utm_medium=affiliate`).
* `utm_campaign`: Identifies the specific campaign associated with the referral link (e.g. `utm_campaign=november-promo`).

{% hint style="info" %}
**Tip:** Always ensure that Advocate-generated links include both `rscode` and relevant UTM parameters for maximum attribution accuracy.
{% endhint %}

### Example request

{% tabs %}
{% tab title="JSON" %}

```json
{
  "user_id": "12345",
  "activity_type": "referral",
  "channel": "email",
  "parameters": {
    "rscode": "ADVOCATE2025",
    "utm_source": "referral",
    "utm_campaign": "november-promo"
  },
  "timestamp": "2024-08-01T00:00:00Z"
}
```

{% endtab %}
{% endtabs %}

### Example response

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script>
  {
    "status": "success",
    "message": "Advocate activity recorded.",
    "activity_id": "act_67890",
    "visible_in_optimize": true,
    "caveats": [
      "Activity will be visible in Optimize reports within 15 minutes.",
      "Only activities with valid rscode or utm_source=referral are displayed."
    ]
  }
</script>
```

{% endtab %}
{% endtabs %}

### Visibility conditions & caveats

Advocate activities are only visible in Optimize if:

* The UTT or Page Load API is correctly implemented and capturing all click data.
* The Rules to Identify (RTI) are set up to recognize Advocate-specific parameters.
* The referral traffic is not filtered out by other channel rules with higher priority (check the assigned credit groups).

Caveats:

* If the Advocate program uses non-standard parameters or custom implementations, additional configuration may be required.
* Only last-click attribution is supported for Optimize channels. If your program uses first-click or mixed attribution, results may differ.
* Postback programs (where data is provided by another program) are not supported for Optimize reporting.<br>


# Process Order Refunds and Retractions in Advocate

This guide explains how to process order refunds and retractions as well as reward cancellations within the Advocate program.

{% stepper %}
{% step %}

### Set up your Advocate program rule configuration

To enable automatic reward retraction when a referred purchase is refunded, you must configure a specific rule in your Advocate program. This rule is essential. Without it, API calls to reverse actions will not trigger reward retraction.

In the impact.com platform:

1. In the left navigation menu, select ![](/files/hr700haJWzy65lcXmxJk) **\[Engage] → Program rules**.
2. Select **Add Rule** within the *Program rules* section.

<div data-with-frame="true"><figure><img src="/files/6vJIPAgiTGrHHvKEmFJt" alt="" width="563"><figcaption></figcaption></figure></div>

3. Select **Friend refunds a purchase** as the rule trigger from the dropdown menu.
4. Select the purchase event that the refund is associated to, and give the rule a name.
5. Select **Next**.
6. Select the action you want to take once it triggers.
7. Give the action a name, then select **Next**.
8. Review the rule details, then select **Save**.
   {% endstep %}

{% step %}

### Trigger a retraction action via API

Advocate requires a specific API call to process a refund or retraction. Do not create a new conversion event. Instead, use the [Reverse an Action ](/brand-api-reference/brand-api-reference-v13/reference/actions/actions#delete-a-dvertisers-accountsid-actions)API to trigger the retraction.

#### Key requirements

* You must include `Amount=0` in your API call to indicate a full retraction.

When you send a modification or reversal request, you can use two methods:

* Use an **order ID** (`OID`) **+ event type ID** (`ActionTrackerID`) combination: All actions associated with this event type ID and order ID will be reversed or modified.
* Use an **Action ID** (`action\_id`). Only the unique action will be reversed or modified.

{% tabs %}
{% tab title="Submit the ActionId" %}
How to find the `ActionId`:

* Use the [Get Rewards](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/reward-overview/reward) endpoint to list rewards.
* Once you have the reward, extract the associated `ActionId` for use in the reverse action API call.

{% hint style="success" %}
**Note:** The API may require iterating over participants to find the correct reward/action. There is currently no direct way to search by Order ID.
{% endhint %}
{% endtab %}

{% tab title="Submit the OrderId" %}
When submitting the `OrderId`, you’ll also need to submit the `ActionTrackerId`.
{% endtab %}
{% endtabs %}

**Example using Action ID:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl 'https://api.impact.com/Advertisers/<AccountSID>/Actions' \
  -X DELETE \
  -u '<AccountSID>:<AuthToken>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'ActionId=1234.5678.9123456' \
  -d 'Amount=0' \
  -d 'DispositionCode=RETRACTION'
```

{% endtab %}
{% endtabs %}

**Example using Order ID:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl 'https://api.impact.com/Advertisers/<AccountSID>/Actions' \
  -X DELETE \
  -u '<AccountSID>:<AuthToken>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'ActionTrackerId=12345' \
  -d 'OrderId=abc_123' \
  -d 'Amount=0' \
  -d 'DispositionCode=RETRACTION'
```

{% endtab %}
{% endtabs %}

**Example response**

{% tabs %}
{% tab title="JSON" %}

```json
{
  "Status": "QUEUED",
  "QueuedUri": "/Advertisers/<AccountSID>/APISubmissions/A-f1534308-e731-4146-86b9-56992f50eefe"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Important:** Setting `Amount=0` is required. This ensures the action is fully retracted and the reward is cancelled, not just treated as an adjustment.
{% endhint %}

#### Common pitfalls & troubleshooting

The Advocate program evaluates the event amount based on item-level fields (`ItemPrice`, `ItemQuantity`, etc.).

`OrderDiscount` and `OrderSubTotalPostDiscount` are recorded but do not drive the retraction logic. For a full refund, ensure that all item prices are set to **0** in the event payload.

For partial refunds, you’ll need to update the item prices to reflect the new (post-refund) amount.

If the retraction rule doesn’t trigger, double-check that:

* The *program rule* is configured as described above.
* The API call includes `Amount = 0`.
* The correct `ActionId` is used.
  {% endstep %}

{% step %}

### Submit batch reversals

#### Prepare your data file

Prepare a .CSV file containing your reversals. Use the following template:

{% tabs %}
{% tab title="CSV" %}

```csv
ActionTrackerId,OrderId,Amount,Reason
```

{% endtab %}
{% endtabs %}

Start by adding your action data in the first row under the headers. Then, save the file with an identifiable name, such as:

`Batch_Mods_Reversals_2020_02_12.csv`

**Example file**

{% tabs %}
{% tab title="CSV" %}

```csv
ActionTrackerId,OrderId,Amount,Reason
16027,O7427540,0,ITEM_RETURNED
16027,O8306075,0,OTHER
```

{% endtab %}
{% endtabs %}

Refer to [Batch Modifications and Reversals File Parameters and Reason Codes](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/protect-and-monitor-your-performance-program/event-risk/reason-codes-reference) for a list of reason codes and fields that can be used in an FTP/SMTP batch modification or reversal.

#### Submit the file

Refer to [Set Up & Submit Batch Modifications & Reversals via FTP or Email](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/batch-modify-conversion-data/submit-batch-modifications-and-reversals) for instructions on how to submit the file.
{% endstep %}

{% step %}

### Review the results

1. In the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User Profile] → Settings**.
2. Under the technical section, select **File Submissions** to see if the file has been processed. Submitted files will appear within 10-15 minutes of being processed.

You will see an `ACTION_NOT_FOUND` error on all lines that are related to Advocate events, this is normal and expected.

**Confirm referrals were successfully retracted:**

1. In the left navigation menu, select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768905009/Accessibility%20Icons/engage-v2.svg) **\[Engage] → Reporting → Referral Feed**.
2. Check if the referrals have been retracted. Retracted referrals will be listed with a status of *Started* and the date the Conversion was retracted.

<div data-with-frame="true"><figure><img src="/files/TaxebvJrGNVmd3dr8WuK" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}


# Advocate API


# Advocate REST API

The Advocate API is organized around REST. The API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. It uses built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

To make the Advocate API as explorable as possible, accounts have test-mode API keys as well as live-mode API keys. Use test-mode keys during development and live-mode keys in production.


# API Webhooks for Advocate Programs

Webhooks let you register a URL that we will POST to any time an event happens in your program. When the event occurs, for example when a vanity coupon code is created for a new participant, an event object is created. This object contains all the relevant information, including the type of event and the data associated with that event. Advocate then sends an HTTP POST request with the event object to any URLs in your account's webhook settings. You can find a full list of all event types below.

* **Multiple Subscriptions**\
  Multiple endpoints may be subscribed, in which case each endpoint will be notified using the behavior described above. Duplicate endpoint URLs will simply result in one subscription being created for that URL.
* **Delivery Order**\
  Delivery order of events is not guaranteed and delivery timing is not guaranteed. Avoid building logic that relies on a specific delivery ordering of webhook notifications.
* **Retry Policy**

  Rest hooks are delivered immediately after an event is triggered. If the endpoint does not successfully respond to a delivery attempt *(i.e., respond with a status code other than 200)*, the delivery will be considered as failed. Failed deliveries will be reattempted every hour after the previous failed attempt until either a successful delivery is made or until 72 attempts have been made (approximately 3 days at the rate of 1 retry per hour).

### Webhook Management API Endpoints

To use webhooks, you need a subscription first. These API endpoints can be used to create and manage the subscriptions that will receive webhook events.

* [Create a webhook subscription](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/webhook-overview/webhook)
* [List webhook subscriptions](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/webhook-overview/webhook)
* [Delete a webhook subscription](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/create-and-manage-advocate-webhook-subscriptions)
* [Test a webhook subscription](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/webhook-overview/webhook)

### Webhook events

<table><thead><tr><th>Event type<select><option value="TXvQ7p5zpJvF" label="user.created" color="blue"></option><option value="VvaDHm7zxtfn" label="user.reward.balance.changed" color="blue"></option><option value="AnZwnPUX7PUH" label="coupon.created" color="blue"></option><option value="NIiMOLwl4YKG" label="reward.created" color="blue"></option><option value="O2y9bUIHt3oa" label="referral.started" color="blue"></option><option value="Sk38Chx9rYYn" label="referral.converted" color="blue"></option><option value="xQG0visjb9wo" label="export.created" color="blue"></option><option value="ibzbpICLoGbQ" label="export.completed" color="blue"></option><option value="RKClrvwzn0nU" label="test" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><span data-option="TXvQ7p5zpJvF">user.created</span></td><td>Sent whenever a new user is created.</td></tr><tr><td><span data-option="VvaDHm7zxtfn">user.reward.balance.changed</span></td><td>Sent whenever a rewards balance is updated from new rewards, redemption, cancellation, or expiry. Only works with all <code>unit</code> types for <code>CREDIT</code> rewards, including <code>POINTS</code>, <code>CASH/USD</code>, and others.</td></tr><tr><td><span data-option="AnZwnPUX7PUH">coupon.created</span></td><td>Sent whenever a new referral code is created.</td></tr><tr><td><span data-option="NIiMOLwl4YKG">reward.created</span></td><td>Sent whenever a new reward is created.</td></tr><tr><td><span data-option="O2y9bUIHt3oa">referral.started</span></td><td>Sent whenever a new referral connection is successfully established.</td></tr><tr><td><span data-option="Sk38Chx9rYYn">referral.converted</span></td><td>Sent whenever a referral is converted.</td></tr><tr><td><span data-option="xQG0visjb9wo">export.created</span></td><td>Sent whenever a data export is queued for creation.</td></tr><tr><td><span data-option="ibzbpICLoGbQ">export.completed</span></td><td>Sent whenever an export that was being generated for a tenant has completed and is ready to be downloaded.</td></tr><tr><td><span data-option="RKClrvwzn0nU">test</span></td><td>Sent to test a subscription.</td></tr></tbody></table>

### Payloads

All webhook data conforms to the same data format.

| id          | **String** - A unique identifier for this event                |
| ----------- | -------------------------------------------------------------- |
| type        | **String** - The type of event                                 |
| tenantAlias | **String** - The tenant used to create this data               |
| live        | **Boolean** - True for Live tenants and false for Test tenants |
| created     | **Number** - The timestamp when this event was created         |
| data        | An arbitrary JSON object containing data related to this event |

### Webhook event details

After a webhook subscription is created, it will immediately start receiving webhook payloads. Each payload has a noted `type` field which can be used to differentiate between events. New event types may be added to the API, so avoid building logic that assumes it knows all event types.

#### `user.created`

Sent whenever a new User is created. Only fires when a new user is created, not for updates or deletes.

{% hint style="success" %}
**Note:** Users can be created via the REST API or UTT, the referral widget, or a batch upload process.
{% endhint %}

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "577303ece4b066c5cb171835",  
  "type": "user.created",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467155436449,  
  "data": {  
    "id": "sat09jsaet09setset",  
    "accountId": "90w4etjsa4et",  
    "email": "mike.keenerson@example.com",  
    "firstName": "Mike",  
    "lastName": "Keenerson",  
    "referralCodes": {  
      "referral-program": "MIKEKEENERSON",  
      "partner-program": "FREE"  
    },  
    "imageUrl": "",  
    "firstSeenIP": "10.230.163.157",  
    "lastSeenIP": null,  
    "dateCreated": 1467155436418,  
    "locale": "fr_CA",  
    "countryCode": "CA",  
    "programShareLinks": {  
      "partner-program": {  
        "cleanShareLink": "http://example.com/free",  
        "MOBILE": {  
          "DIRECT": "http://example.com/free?me"  
        },  
        "EMAIL": {  
          "DIRECT": "http://example.com/free?mP"  
        },  
        "UNKNOWN": {  
          "DIRECT": "http://example.com/free?mv"  
        }  
      }  
    },  
    "customFields": {  
      "birthday": "--02-29"  
    },  
    "segments": ["segment1"],  
    "referredByCodes": ["CODE1"]  
  }  
}
```

{% endtab %}
{% endtabs %}

#### `user.reward.balance.changed`

Sent whenever a rewards balance is updated. Only works with all `unit` types for `CREDIT` rewards, including `POINTS`, `CASH/USD`, and others.

**Examples of what might change a balance**:

* A credit reward is given to a user
* A pending credit reward is made available to a user
* A user's reward expires
* A user's reward is cancelled
* A user's reward is fully redeemed
* A user's reward is partially redeemed

Other rules to consider:

* The `user.reward.balance.changed` webhook only applies to `CREDIT` rewards. `PCT_DISCOUNT`, `FUELTANK` and `INTEGRATION` rewards won't trigger this webhook.
* The creation of a pending reward will not trigger a balance update because it doesn't affect the balance.
* This webhook is per unit balance changed (we don't combine balances in a single webhook).
* This webhook contains an available balance value calculated after (not exactly at) the time of the trigger.
* No balance update webhook is sent when a user is deleted and any external user balance will remain at its last known value.

**Eventual consistency**

Webhooks can also arrive at your application out-of-order. This can be due to issues such as network delays or webhook failures. However, you can order the events by examining the `resourceVersion` attribute of the resource sent by the webhook to ensure [Eventual Consistency](https://en.wikipedia.org/wiki/Eventual_consistency).

Since `resourceVersion` is incremented for changes made to the balance, you can only accept the latest data, and ignore old data.

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "577303ece4b066c5cb171835",  
  "type": "user.reward.balance.changed",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467155436449,  
  "data": {  
    "userId": "user123",  
    "accountId": "account123",  
    "unit": "USD",  
    "availableValue": 4500,  
    "resourceVersion": 1579030928001  
  }  
}
```

{% endtab %}
{% endtabs %}

#### `coupon.created`

Sent whenever a new referral code is created.

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "31049u0194u2105",  
  "type": "coupon.created",  
  "tenantAlias": "AAA111BBB222DDD333",  
  "live": false,  
  "created": 1337001337,  
  "data": {  
    "code": "ABC123ABC",  
    "dateCreated": 123123123123,  
    "programId": "program1"  
  }  
}
```

{% endtab %}
{% endtabs %}

#### `reward.created`

Sent whenever a new reward is created. Data is a single [Reward Object](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/reward-overview/reward) that is returned from the [List Rewards REST API Endpoint](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/reward-overview/reward)

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "577405e3e4b0cc57c1e2e687",  
  "type": "reward.created",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467221475167,  
  "data": {  
    "id": "577405e3e4b0cc57c1e2e684",  
    "type": "PCT_DISCOUNT",  
    "dateGiven": 1467221475151,  
    "dateExpires": 1475170275151,  
    "dateCancelled": null,  
    "accountId": "6UTR8OQZX0HE3QBP",  
    "userId": "56f2e6a9e4b08a1cbef6c561",  
    "cancellable": true,  
    "rewardSource": "FRIEND_SIGNUP",  
    "discountPercent": 15,  
    "unit": "%"  
  }  
}
```

{% endtab %}
{% endtabs %}

#### `referral.started`

Sent whenever a new referral connection is successfully established.

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "5773073fe4b066c5cb171900",  
  "type": "referral.started",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467156287085,  
  "data": {  
    "id": "5773073ee4b066c5cb1718fc",  
    "referred": {  
      "id": "5773073ee4b08b14ab979fb8",  
      "accountId": "5773073ee4b08b14ab979fb8"  
    },  
    "referrer": {  
      "id": "577306eae4b08b14ab979f70",  
      "accountId": "577306eae4b08b14ab979f70"  
    },  
    "referralCodeUsed": "LORETTABURKE10",  
    "shareLinkUsed": "http://ssqt.co/mPbcF5",  
    "moderationStatus": "PENDING",  
    "dateReferralStarted": 1467156286882,  
    "dateConverted": null  
  }  
}
```

{% endtab %}
{% endtabs %}

#### `referral.converted`

Sent whenever a referral is converted.

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "57731b5ee4b07320b5c0980a",  
  "type": "referral.converted",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467161438453,  
  "data": {  
    "id": "57731b43e4b07320b5c097ec",  
    "referred": {  
      "id": "5773073ee4b08b14ab979fb8",  
      "accountId": "5773073ee4b08b14ab979fb8"  
    },  
    "referrer": {  
      "id": "577306eae4b08b14ab979f70",  
      "accountId": "577306eae4b08b14ab979f70"  
    },  
    "referralCodeUsed": "LORETTABURKE10",  
    "shareLinkUsed": "http://ssqt.co/mPbcF5",  
    "moderationStatus": "PENDING",  
    "dateReferralStarted": 1467161411028,  
    "dateConverted": 1467161438415  
  }  
}
```

{% endtab %}
{% endtabs %}

#### `export.created`

Sent whenever a data export is queued for creation.

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "57740ebae4b0cc57c1e2e8b9",  
  "type": "export.created",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467223738961,  
  "data": {  
    "id": "57740ebae4b0cc57c1e2e8b8",  
    "name": "Test Export Webhook",  
    "requester": "Hayward Erikson",  
    "status": "PENDING",  
    "dateCreated": 1467223738947,  
    "dateExpires": null,  
    "dateCompleted": null,  
    "type": "USER",  
    "outputFormat": "CSV",  
    "params": {  
      "createdSince": null,  
      "createdBefore": null,  
      "updatedSince": null,  
      "updatedBefore": null,  
      "createdOrUpdatedSince": null,  
      "createdOrUpdatedBefore": null  
    }  
  }  
}
```

{% endtab %}
{% endtabs %}

#### `export.completed`

Sent whenever an export that was being generated has been completed and is ready to be downloaded.

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "57740ec5e4b034a7ceae80de",  
  "type": "export.completed",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467223749687,  
  "data": {  
    "id": "57740ebae4b0cc57c1e2e8b8",  
    "name": "Test Export Webhook",  
    "requester": "Hayward Erikson",  
    "status": "COMPLETED",  
    "dateCreated": 1467223738947,  
    "dateExpires": 1470247749304,  
    "dateCompleted": 1467223749304,  
    "type": "USER",  
    "outputFormat": "CSV",  
    "params": {  
      "createdSince": null,  
      "createdBefore": null,  
      "updatedSince": null,  
      "updatedBefore": null,  
      "createdOrUpdatedSince": null,  
      "createdOrUpdatedBefore": null  
    }  
  }  
}
```

{% endtab %}
{% endtabs %}

#### `test`

Sent to test a subscription.

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "id": "1337049u0194u2105",  
  "type": "test",  
  "tenantAlias": "AAA111BBB222DDD333",  
  "live": false,  
  "created": 1337001337,  
  "data": {  
    "endpointUrl": "http://example.com/hook",  
    "name": "Example"  
  }  
}
```

{% endtab %}
{% endtabs %}


# Webhook Security for Advocate Programs

[Webhook requests](/integration-guides/for-brands/advocate/advocate-api/api-webhooks-for-advocate-programs) originating from your Advocate program are *signed* so that you can confirm that the request is legitimate. Signatures are specific to every webhook, allowing you to confirm that the message was not intercepted in a man-in-the-middle attack.

All Advocate webhooks include two signatures that can be used to verify authenticity.

| Signature                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Hook-JWS-RFC-7797` **(Recommended)** | A [JSON Web Signature](https://datatracker.ietf.org/doc/html/rfc7797) (JWS) that supports key rotation, signed using the Advocate [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) (JWKS). It is asymmetrically signed.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `X-Hook-Signature`                      | <p>A <a href="https://datatracker.ietf.org/doc/html/rfc2104">HMAC-SHA1 hash</a> of the hook's body contents, signed by your <a href="https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/manage-api-access-tokens-as-a-brand">API key</a>.<br><br><strong>Note:</strong> <code>X-Hook-Signature</code> uses HMAC-SHA1, which is considered a weak hashing algorithm by modern security standards. For this reason, we recommend using <code>X-Hook-JWS-RFC-7797</code> for webhook verification, as it provides stronger security through asymmetric signing and supports key rotation.</p> |

Although you can verify the webhook's authenticity via the signature, you may still need to verify the state of the data by making an API call.

{% hint style="warning" %}
**Hook delivery order is not guaranteed:** Webhooks may be delivered in a different order than the update events that generated them, so relying on their contents may lead you to build a different final state.
{% endhint %}

***

## Verify a webhook payload

1. Confirm that the `X-Hook-JWS-RFC-7797` header exists. If it doesn't exist, then the request didn't come from impact.com.
2. Look up the public keys of the [Advocate JWKS](http://app.referralsaasquatch.com/.well-known/jwks.json). There should be a `kid` that matches the header of the JWS.

{% hint style="success" %}
**Note:** The JWKS changes regularly and should not be cached in its entirety. However, the `kid` for an individual JWK is immutable, and therefore it is safe and recommended to cache individual JWK's by their `kid` indefinitely.
{% endhint %}

3. Get the JSON body from the request.
4. Use a [JWT library](https://jwt.io/libraries) for your programming language to verify that the body matches the signature. The JWS signature uses a detached payload, so it is of the form `JWSHEADER..JWSSIGNATURE`.

To implement the verification, some languages may require you to Base64 encode the JWS payload (e.g. the webhook body) in order to verify the JWS. Note that vanilla Base64 does not work in this context. The JWT standard requires each part of a JWT to be encoded using the URL variant of Base64 encoding without padding.\
\
These libraries support [RFC-7797](https://datatracker.ietf.org/doc/html/rfc7797) and JWKS, and simplify verifying a JWS:

* [Java](https://mvnrepository.com/artifact/com.nimbusds/nimbus-jose-jwt): `com.nimbusds.jose`
* [Node.js](https://github.com/auth0/node-jsonwebtoken): `jsonwebtoken` using `jwks-rsa`
* [.Net (C#)](https://github.com/dvsekhvalnov/jose-jwt): `jose-jwt`

### Validation code examples

Below are code examples of validating the JWS of a webhook request.

{% tabs %}
{% tab title="Java" %}

```java
import java.net.MalformedURLException;
import java.net.URL;
import java.text.ParseException;
import java.util.Base64;
import java.util.Map;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.source.RemoteJWKSet;
import com.nimbusds.jose.proc.BadJOSEException;
import com.nimbusds.jose.proc.JWSVerificationKeySelector;
import com.nimbusds.jose.proc.SecurityContext;
import com.nimbusds.jose.util.DefaultResourceRetriever;
import com.nimbusds.jwt.proc.DefaultJWTProcessor;
import com.nimbusds.jwt.proc.JWTProcessor;

public class JwksExample {

  private final JWTProcessor<SecurityContext> advocateJwksJwtProcessor;

  {
    final DefaultJWTProcessor<SecurityContext> jwtProcessor = new DefaultJWTProcessor<>();
    try {
      jwtProcessor.setJWSKeySelector(new JWSVerificationKeySelector<>(JWSAlgorithm.RS256,
        new RemoteJWKSet<>(new URL("https://app.referralsaasquatch.com/.well-known/jwks.json"),
          new DefaultResourceRetriever(500, 1500))));
    } catch (MalformedURLException e) {
      throw new RuntimeException(e); // Won't happen. We know the URL is not malformed.
    }
    advocateJwksJwtProcessor = jwtProcessor;
  }

  /**
   * Validate the given JWT with the public JWKS and get the claims.
   *
   * @param token The input JWT
   * @return The validated claims as a Map
   * @throws ParseException when the input token is invalid
   * @throws BadJOSEException when the input token's claims contain bad values
   * @throws JOSEException when the input token's signature is incorrect
   */
  public Map<String, Object> validateWithAdvocateJwks(String token)
      throws ParseException, BadJOSEException, JOSEException {
    return advocateJwksJwtProcessor.process(token, null).toJSONObject();
  }

  /**
   * Validate a webhook coming from impact.com.
   *
   * @param webhookBody The raw bytes of the webhook body.
   * @param jwsNoPayloadHeader The value of the X-Hook-JWS-RFC-7797 header.
   * @return The validated claims as a Map
   * @throws ParseException when the input token is invalid
   * @throws BadJOSEException when the input token's claims contain bad values
   * @throws JOSEException when the input token's signature is incorrect
   */
  public Map<String, Object> validateAdvocateWebhook(byte[] webhookBody,
      String jwsNoPayloadHeader) throws ParseException, BadJOSEException, JOSEException {
    final String webhookBodyBase64 =
      Base64.getUrlEncoder().withoutPadding().encodeToString(webhookBody);
    final String token = jwsNoPayloadHeader.replace("..", '.' + webhookBodyBase64 + '.');
    return validateWithAdvocateJwks(token);
  }

}
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import * as jwt from "jsonwebtoken";
import * as jwksRsa from "jwks-rsa";
import { Base64 } from "js-base64";

const advocateJwksClient = jwksRsa({
  jwksUri: "https://app.referralsaasquatch.com/.well-known/jwks.json",
  cache: true,
});

/**
 * Validate the given JWT with the public JWKS and get the claims.
 * @param token The input JWT
 */
export function validateWithAdvocateJwks(token: string): Promise<object> {
  return new Promise((resolve, reject) => {
    jwt.verify(
      token,
      (header, callback) => {
        advocateJwksClient.getSigningKey(header.kid, (err, key) => {
          callback(err, key ? key.getPublicKey() : null);
        });
      },
      (err, decoded) => {
        if (err) {
          reject(err);
        } else {
          resolve(decoded);
        }
      }
    );
  });
}

/**
 * Validate a webhook coming from impact.com.
 *
 * @param webhookBody The raw text of the webhook body.
 * @param jwsNoPayloadHeader The value of the X-Hook-JWS-RFC-7797 header.
 */
export function validateAdvocateWebhook(
  webhookBody: string,
  jwsNoPayloadHeader: string
): Promise<object> {
  const webhookBodyBase64 = Base64.encodeURI(webhookBody);
  const token = jwsNoPayloadHeader.replace("..", "." + webhookBodyBase64 + ".");
  return validateWithAdvocateJwks(token);
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Linq;
using System.Net.Http;
using System.Runtime.Caching;
using System.Threading;
using System.Threading.Tasks;
using Jose;

public class JwksExample
{
  private static readonly string jwksUrl = "https://app.referralsaasquatch.com/.well-known/jwks.json";
  private readonly ObjectCache jwkCache = new MemoryCache("advocate_jwk_cache");
  private readonly SemaphoreSlim jwkCacheSemaphore = new SemaphoreSlim(1, 1);

  private async Task<Jwk> GetAdvocateJwkByKid(string kid)
  {
    {
      if (jwkCache[kid] is Jwk jwkFound)
      {
        return jwkFound;
      }
    }
    await jwkCacheSemaphore.WaitAsync();
    try
    {
      { // Double checked lock
        if (jwkCache[kid] is Jwk jwkFound)
        {
          return jwkFound;
        }
      }
      string jwksString;
      using (var httpClient = new HttpClient())
      {
        jwksString = await httpClient.GetStringAsync(jwksUrl);
      }
      var jwks = JwkSet.FromJson(jwksString, JWT.DefaultSettings.JsonMapper);
      var jwk = jwks.FirstOrDefault(jwk => jwk.KeyId.Equals(kid));
      if (jwk == null)
      {
        throw new Exception("JWK not found for kid");
      }
      jwkCache.Set(kid, jwk, DateTimeOffset.UtcNow.AddDays(1));
      return jwk;
    }
    finally
    {
      jwkCacheSemaphore.Release();
    }
  }

  /// <summary>
  /// Validate the given JWT with the public JWKS and get the claims.
  /// </summary>
  /// <param name="token">The input JWT</param>
  /// <returns>The validated payload JSON string</returns>
  public async Task<string> ValidateWithAdvocateJwks(string token)
  {
    var headers = JWT.Headers(token);
    var kid = headers["kid"] as string;
    var jwk = await GetAdvocateJwkByKid(kid);
    return JWT.Decode(token, jwk);
  }

  /// <summary>
  /// Validate a webhook coming from impact.com.
  /// </summary>
  /// <param name="webhookBody">The raw bytes of the webhook body.</param>
  /// <param name="jwsNoPayloadHeader">The value of the X-Hook-JWS-RFC-7797 header.</param>
  /// <returns>The validated webhook JSON string</returns>
  public Task<string> ValidateAdvocateWebhook(byte[] webhookBody, string jwsNoPayloadHeader)
  {
    var webhookBodyBase64 = Base64Url.Encode(webhookBody);
    var token = jwsNoPayloadHeader.Replace("..", '.' + webhookBodyBase64 + '.');
    return ValidateWithAdvocateJwks(token);
  }

}
```

{% endtab %}
{% endtabs %}

## Verify the webhook's IP address

Your Advocate program sends webhooks from one of the following IP Addresses. You can rely on this list for adding additional security, but we still recommend validation via JWS as your primary security mechanism.

```
35.202.24.73
35.222.215.196
35.236.200.194
35.186.188.88
```

{% hint style="warning" %}
**Important:** These are not all the IP addresses in use, only those relating to webhooks. Do not rely on this list for making calls to the API, using the SDKs, or Portal.
{% endhint %}

***

## Reference

### Signature generation process

The `X-Hook-JWS-RFC-7797` signature is a JWS with a detached payload. It is a string that looks like `JWSHeader..JWSSignature`.

The signature generation works as follows:

1. Webhook data is generated.
   * Example: A `reward.created` webhook.
2. The payload is signed using one of the keys from our JWS key set.
   * Example: `kid: 94ab304d-c90a-45ba-80e4-b4516a57a1c8`
3. The JWS header will contain some standard properties:
   * `kid`: The key used to sign the request. This can be looked up in the JWKS.
   * `alg`: `RS256`
   * `typ`: `JWT`
4. The JWS is added as the `X-Hook-JWS-RFC-7797` header to the webhook request.
5. The HTTP Request is sent as a POST to all the webhook endpoints subscribed.

### Cryptography standards

JSON Web Signature **(JWS)** represents content secured with digital signatures or Message Authentication Codes (MACs) using [JSON-based data structures](https://datatracker.ietf.org/doc/html/rfc7159). The JWS cryptographic mechanisms provide integrity protection for an arbitrary sequence of octets.

JSON Web Token **(JWT)** is a a compact, URL-safe means of representing claims to be transferred between two parties. Essentially, it is a JWS structure with a JSON object as the payload, enabling the claims to be digitally signed, MACed, or encrypted.

JSON Web Key Set **(JWKS)** is a standard for sharing crytographic keys. Our JWKS contains the public keys of the public/private key pairs used for *asymmetric encryption*. That means that it is signed with a private key known only to impact.com, but that the signature can be verified by anyone using the matching public key from the JWKS.

### Sample webhook content

{% tabs %}
{% tab title="JSON" %}

```json
Accept-Encoding: gzip,deflate,br
Content-Type: application/json; charset=UTF-8
Content-Length: 543
Connection: keep-alive
X-Hook-JWS-RFC-7797: eyJraWQiOiIzZDMxM2JjOC1hYjNiLTRmM2MtYWJiNy0zN2I4NGE0MmQwZGEiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..DQfCOrdudxqz4r7uiCAhyKIi4bGZignWmr1ct_7Bf6DXmgwUciQJaQTvYffc5lni9K6DqclQG0cfI6X5pqceeFays1_atEP-bsN6w_0krjKg72rcVHKecgEOlFNhsF0xfYdjoY-5z-tpzpjOU1QBKOl7eE8K9AkCL5FDg6Huu26Ov1TcmEGhNMSN7UW0zBNXvNsjeRfO57dKgtA-6wyl3TUcsxYsz81Q3Og0dprMfNBr-bcqvs4aHUUxLmU013RYXAdQmK395NvN54YJniZcsy8svF1THExp4WkmOw9WmX_kHUhsvadTegAI4PbGYx9h1xIcdV_IrfuzUV1Ta9WfKg
X-Hook-Signature: h2JX9dV4o1r2sJypeVBIWOqW0as=

{
  "id": "5dfaadc9d132f00f8b742288",
  "type": "reward.created",
  "tenantAlias": "a5kz4dlxt403z",
  "live": true,
  "created": 1576709577227,
  "data": {
    "type": "CREDIT",
    "id": "577405e3e4b0cc57c1e2e684",
    "dateCreated": 1467221475151,
    "dateScheduledFor": null,
    "dateGiven": 1467221475151,
    "dateExpires": 1475170275151,
    "dateCancelled": null,
    "accountId": [["example account ID"]],
    "userId": [["example user ID"]],
    "cancellable": true,
    "rewardSource": "FRIEND_SIGNUP",
    "programId": null,
    "unit": "%",
    "assignedCredit": null,
    "redeemedCredit": null,
    "name": null,
    "currency": null,
    "redemptions": null
  }
}
```

{% endtab %}
{% endtabs %}


# API Open Endpoints

Open Endpoints are API calls designed for simplified use of the REST API functionality. The primary use case for the Open Endpoints is in **client-server** interactions, such as through a mobile app. These actions typically involve looking up information about an advocate or whom they’ve referred.

**Some examples include**:

* [Look up a referral code](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/referral-code-overview/referral-code) after app install to display a dialog about who referred them
* [Register a new user](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user) in the referral program
* [Look up share links](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user) to display a custom sharing dialog
* [Look up referrals](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/referral-overview/referral) to display a list of referred friends

### Authentication options

* *Authentication via JSON Web Token (JWT)* - JWTs can be used for requests that require authentication. The process for building JWTs is outlined in our [JSON Web Tokens](/integration-guides/for-brands/advocate/advocate-tracking-integrations/json-web-tokens-jwts) documentation. Use for **client-server** communication.
* *Authentication via API Key* - Your API key can also be used for requests that require authentication. Use for **server-server** communication.
* *Unauthenticated* - Some Open Endpoints do not require any form of authentication.

#### Authentication Requirements by Method <a href="#authentication-requirements-by-method" id="authentication-requirements-by-method"></a>

The following table summarizes the Open Endpoint methods that are available for use, and their required level of authentication:

| Open Endpoint method                                                                                                                                    | Authentication required    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| [Create a user](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user)                             | Write Token or API key     |
| [Upsert a user](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user)                             | Write Token or API key     |
| [Look up a user](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user)                            | Read Token or API key      |
| [Look up a user by referral code](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user)           | No authentication required |
| [Look up a referral code](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/referral-code-overview/referral-code) | No authentication required |
| [Apply a referral code](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/referral-code-overview/referral-code)   | Write Token or API key     |
| [List referrals](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/referral-overview/referral)                    | Read Token or API key      |

#### Authentication with JWT

Authentication with JWTs should be used in **client-server**, not server-server communication.

The Advocate API accepts two types of JWTs: *read tokens* and *write tokens*. Read tokens are intended to validate a request to lookup information about an existing user/account while write tokens are intended to be used when adding or updating information about a user/account.

The format of the JWT payloads required for read and write tokens are outlined below:

**Read Token Payload**

The payload of a read token is based on the `user id` and `account id`:

{% tabs %}
{% tab title="JSON" %}

```json
{
  "user": {
    "id": "adfgafdg",
    "accountId": "adfklajdnrerereACdsedf"
  },
  "exp": 1462327764 
}
```

{% endtab %}
{% endtabs %}

**Write Token Payload**

The payload of a write token can contain the complete user object:

{% tabs %}
{% tab title="JSON" %}

```json
{
  "user": {
    "id": "adfgafdg",
    "accountId": "adfklajdnrerereACdsedf",
    "email": "bob@example.com",
    "firstName": "Bob",
    "lastName": "Testerson", 
    "locale": "en_US", 
    "referralCode": "BOBTESTERSON", 
    "imageUrl": "" 
  },
  "exp": 1462327764 
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
**Note:** The following fields are optional: `lastName`, `locale`, `referralCode`, `imageUrl`, and `exp` (expiry date in seconds since the epoch).
{% endhint %}

**Building the JWT**

{% hint style="info" %}
**Tip:** The process for building the JWT is outlined on our [JSON Web Tokens page](/integration-guides/for-brands/advocate/advocate-tracking-integrations/json-web-tokens-jwts).
{% endhint %}

Make sure that you are trying to sign the correct format of the payload (Read Token vs. Write Token) for your specific Open Endpoint API call.

#### Authentication with API Key

Authentication with your API key should be done when conducting **server-server** communication.

{% hint style="info" %}
**Tip:** Authenticating Open Endpoint calls with an API key is done in the same way as with our standard API calls, details for which can be found in [API Authentication](https://integrations.impact.com/rest-apis/api-quick-start/create-an-api-key).
{% endhint %}


# GraphQL API

The Advocate GraphQL API provides an API for building custom Advocate participant experiences, integrations, and admin interfaces based on GraphQL. Authentication for the GraphQL API is the same as the [Advocate REST API](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-api/advocate-rest-api).

## Endpoint

There is one endpoint for working with GraphQL. If you are integrating a referral program into your site, use the tenant endpoint so that you don't need to specify your `tenant_alias` throughout your GraphQL queries.

{% tabs %}
{% tab title="Tenant endpoint" %}

```html
https://app.referralsaasquatch.com/api/v1/`{tenant_alias}`/graphql
```

{% endtab %}
{% endtabs %}

To retrieve your tenant alias:

* In your impact.com account, from the top navigation bar, select **\[User Profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml?execution=e9s1).
* From the *Advocate Settings* section, select **General**.
* Retrieve your tenant alias from the *Tenant Details* section.

## Access GraphQL

1. In your impact.com account, select **\[User Profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml?execution=e9s1) from the top navigation bar.
2. From the *Advocate Settings* section, select **GraphQL**.

From this interface, you can run queries and see results.

## Run GraphQL queries

1. Enter your query in the leftmost panel (see image above as an example).
2. Select <i class="fa-play-circle">:play-circle:</i> **\[Run]**.
   * See the **Documentation Explorer** on the right of the screen for the complete GraphQL schema available to build queries with.
3. See the results in the middle pane.


# Advocate Program Bulk Import Methods

Import jobs can be started from impact.com, via the Advocate SFTP integration, or by using the Advocate API directly.

### File-based bulk imports in impact.com

Bulk imports can be started from within impact.com. To get started, select **Reporting → Imports & Exports** in the left navigation menu.

For full instructions on the file-based bulk import process, see our other guides:

* [Import Participants in Bulk](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/import-advocate-participants-in-bulk)
* [Delete Participants in Bulk](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/delete-participants-from-your-advocate-program)

### Bulk imports via SFTP integration

Bulk imports can be performed via Advocate SFTP integration. See our guide on the [SFTP integration here](/integration-guides/for-brands/advocate/advocate-tracking-integrations/sftp-import-integration-for-advocate-programs) for instructions on:

* Enabling and authenticating the integration
* Generating an SSH key
* Connecting to the SFTP server
* Uploading import files and checking their status

### Bulk imports via API

To start a bulk import job, there are three API requests to be performed.

* Uploading the import file
* Validating the import file
* Starting the import job

#### Uploading the import file

The `/export/upload` endpoint accepts a file upload in two different ways, either with `multipart/form-data` encoding or as a raw file upload.

**Example Request:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://app.referralsaasquatch.com/api/v1/{tenant_alias}/export/upload' \
  -u :{tenant_api_key} \
  --form 'file=@my_file.csv'
```

{% endtab %}
{% endtabs %}

When the file is successfully uploaded, a `fileRef` will be returned. The `fileRef` will be used in the next two API requests.

**Example Response:**

{% tabs %}
{% tab title="JSON" %}

```json
{
  "fileRef": "imports/test_akdq8a9wyvzba/userEvents_63323378e1edcd44b03eed9a.jsonl"
}
```

{% endtab %}
{% endtabs %}

#### Validating the import file

Before starting your import job, you can use the `validateJobInput` GraphQL mutation to validate the import file before attempting to start the import job.\
There are two inputs required, the `fileRef` from step 1, and the job `type`.\
These are the job types available:

* Import Users: `MUTATION/USER`
* Delete Users: `MUTATION/DELETE_USER`
* Import User Events: `MUTATION/USER_EVENT`

**Example:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://app.referralsaasquatch.com/api/v1/{tenant_alias}/graphql' \
  -u :{tenant_api_key} \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "validate",
    "variables": {
      "jobInput": {
        "fileRef": "{file_ref}",
        "type": "{job_type}"
      }
    },
    "query": "query validate($jobInput: JobInput!) {validateJobCreation(jobInput: $jobInput) { errors }}"
  }'
```

{% endtab %}
{% endtabs %}

If there are any errors found in the import file, they will be returned as an array in `errors`. If `errors` is empty, then the same `fileRef` can be used to start an import job in step 3.

**Example Response:**

{% tabs %}
{% tab title="JSON" %}

```json
{
  "data": {
    "validateJobCreation": {
      "errors": []
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Starting the import job

To start the import job, use the `createJob` GraphQL mutation. Provide the `fileRef` and job `type` from the upload step.

**Example:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://app.referralsaasquatch.com/api/v1/{tenant_alias}/graphql' \
  -u :{tenant_api_key} \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "jobInput": {
        "type": "{job_type}",
        "outputFormat": "CSV",
        "fileRef": "{file_ref}"
      }
    },
    "query": "mutation ($jobInput: JobInput!) { createJob(jobInput: $jobInput) {id type requester dateCreated}}"
  }'
```

{% endtab %}
{% endtabs %}

The `id` returned by the mutation can be used to query the status of the job.

**Example Response:**

{% tabs %}
{% tab title="JSON" %}

```json
{
  "data": {
    "createJob": {
      "id": "633b1cf34efc053cb50a3f6d",
      "type": "MUTATION/USER_EVENT",
      "requester": "API",
      "dateCreated": 1664818419661
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Check the status of the import job

To check the status of the import job, you can use the `job` GraphQL query and provide the job `id` returned in step 3.

**Example:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://app.referralsaasquatch.com/api/v1/{tenant_alias}/graphql' \
  -u :{tenant_api_key} \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "id": "{job_id}"
    },
    "query": "query ($id: ID!) { job(id: $id) { status stats { recordsProcessed }}}"
  }'
```

{% endtab %}
{% endtabs %}

**Example Response:**

{% tabs %}
{% tab title="JSON" %}

```json
{
  "data": {
    "job": {
      "status": "COMPLETED",
      "stats": {
        "recordsProcessed": 22
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}


# Advocate Plugin Integration


# Tango Card Integration Overview for Advocate

Tango Card allows you to buy, send, and track digital gift card orders. Advocate's Tango Card integration enables you to automatically reward your customer advocates and their referred friends with gift cards.

### Key features:

* Hands-off reward generation, fulfillment, and redemption.
* Automatically send participants their gift card redemption details by email.
* Use a native integration built directly on Tango Card's API.

### More info

* [Gift Card Rewards](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-rewards/gift-card-rewards-explained)
* [Integrate with Tango Card for Advocate Programs](/integration-guides/for-brands/advocate/advocate-plugin-integration/tango-card-integration-overview-for-advocate/integrate-with-tango-card-for-advocate-programs)


# Integrate with Tango Card for Advocate Programs

Tango Card allows you to reward your participants with a wide variety of digital gift cards. Integrating Tango Card into your Advocate referral program makes it simple to automate, manage, and deliver [gift card rewards](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-rewards/gift-card-rewards-explained).

## Tango Card account types

There are two ways to connect Tango Card to your Advocate referral program: a direct Tango Card account or a sub-account managed by Advocate. The right choice depends on how much control you want and how much setup your team is willing to manage.

| Criteria               | Direct Tango Card account                                                                                        | Sub-account managed by Advocate                                                                   |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Best for**           | Brands that want full control and are comfortable managing their own Tango Card account.                         | Brands that want a managed experience and prefer not to maintain a Tango Card account themselves. |
| **Setup effort**       | Higher: your team configures and maintains the account.                                                          | Lower: Advocate handles setup and most ongoing management.                                        |
| **API key access**     | Yes, you have your own.                                                                                          | No, Advocate manages a central API key.                                                           |
| **Reward catalog**     | Fully customizable.                                                                                              | Preconfigured catalog with a wide selection of gift cards.                                        |
| **KYC requirements**   | May be required for open-loop cards (such as Visa or Mastercard) that aren't already available through Advocate. | Not required unless requesting a new open-loop card not already available.                        |
| **Account management** | Your internal team handles account issues, balance monitoring, and fulfilment errors.                            | Advocate adds users and configures low-balance alerts on your behalf.                             |
| **Support**            | Standard support channels.                                                                                       | Faster, hands-on troubleshooting from the Advocate team.                                          |

#### Direct Tango Card account

A direct Tango Card account gives you the most functionality and control within Tango Card. You'll have full access to funding, users, reporting, and order management, as well as the ability to customize your reward catalog, use your own API key, and control groups and accounts within your Tango Card setup.

Your internal team is responsible for managing account issues, balance monitoring, and fulfilment errors. Open-loop cards (also known as prepaid cards, such as Visa or Mastercard) may require extra compliance steps like completing a Know Your Customer (KYC) process. If the card is already available through Advocate, it can be used without additional setup.

If you don't yet have a Tango Card account and would like to create one, follow these instructions to sign up.

#### Sub-account managed by Advocate

Sub-accounts are created and managed under Advocate's master Tango Card account. They offer a streamlined setup with fewer internal responsibilities and access to a preconfigured reward catalog with a wide selection of gift cards. Advocate handles user management and low-balance alerts on your behalf, and your team benefits from faster, hands-on troubleshooting from Advocate.

In exchange for the simpler setup, sub-accounts have a few restrictions. You won't have access to your own API key (Advocate manages a central one), and you'll need Advocate to add users or configure low-balance alerts. You won't need to complete KYC unless you request a new open-loop card that isn't already available.

Not sure which to choose? Contact your Advocate Program Strategy Manager or contact [support](mailto:saasquatch-support@impact.com) for guidance.

### Connect your Tango Card account to Advocate

Choose the appropriate setup steps based on your selected account type.

#### Connect your direct Tango Card account to Advocate

If you’re using your own Tango Card account:

1. In your Advocate account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. In the *Advocate Settings* section, select **Integrations**.
3. Scroll down to the Tango integration and expand the integration view by selecting **+ \[Add]**.
4. Below *API Platform Options*, select **Custom TangoCard Account (Advanced)** from the drop-down menu.
5. Enter your Tango Card account information:
   * **Account Identifier** and **Group Identifier**. Refer to [Tango Card’s help documentation](https://help.rewardsgenius.com/s/article/Find-account-and-customer-identifiers-for-Tango-API) on how to locate these identifiers.
   * **Tango Card Username**
   * **API Key**. Refer to [Tango Card's help documentation](https://help.rewardsgenius.com/s/article/manae-basic-auth-api-keys-in-tango) on how to locate it.
6. Select **Connect** at the bottom of the *Tango Card integration* section to save and connect your account.

#### Connect your Advocate-managed Tango Card Account

If you are using a sub-account managed by Advocate:

1. In your Advocate account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. In the *Advocate Settings* section, select **Integrations**.
3. Scroll down to the Tango integration and expand the integration view by selecting **+ \[Add]**.
4. Below *API Platform Options*, select **Advocate Hosted (Recommended)** from the drop-down menu.
5. Enter your Tango Card Account information:
   * **Account Identifier** and **Group Identifier**. Refer to [Tango Card’s help documentation](https://help.rewardsgenius.com/s/article/Find-account-and-customer-identifiers-for-Tango-API) on how to locate these identifiers.
6. Select **Connect** at the bottom of the *Tango Card integration* section to save and connect your account.

### Fund Your Tango Card Account

Both direct accounts and Advocate-managed sub-accounts must be funded before rewards can be issued. Without funding, rewards will not be sent, even if the integration is successfully connected.

To fund your account, follow the instructions from Tango Card on [How to Fund Your Account](https://help.rewardsgenius.com/s/topic/0TO1U000000Pnk2WAC/payment-options). For further funding questions visit [Tango Card's Funding FAQ](https://help.rewardsgenius.com/s/article/FundingFAQ).

### Testing Your Tango Card Reward

Whether you’re using a direct or Advocate-managed sub-account, you can test your reward setup using the Tango Card sandbox environment. The sandbox lets you simulate delivery and preview custom emails without spending real currency.

To enable sandbox testing for a direct Tango Card account:

1. In your Advocate account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. In the *Advocate Settings* section, select **Integrations**.
3. Scroll down to the Tango integration and expand the integration view by selecting **+** **\[Add]**.
4. Below *API Platform Options*, select **Advocate Hosted (Recommended)** from the drop-down menu.
5. Enter the sandbox **Account Identifier** and **Group Identifier**. Refer to [Tango Card’s help documentation for work environments](https://developers.tangocard.com/docs/set-up-work-environment).
6. ![](/files/nF7DY0rLLPpjNDQb5LMS)**\[Toggle on]** the Sandbox account option.
7. Select **Connect** at the bottom of the *Tango Card integration* section to save and connect your account.

To enable sandbox testing of your Advocate-Managed Tango Card Sub-Account please reach out to your Advocate Program Strategy Manager or contact [support](https://app.impact.com/support/portal.ihtml?createTicket=true) for help setting up sandbox access.

You can ![](/files/2t5Z86O6Zq5FIwJNttNP) **\[Toggle off]** sandbox at any time to begin sending live rewards. When testing in the live environment, reduce the reward value to *$0.01* or *$0.05* to avoid unnecessary costs.

### \[Optional] Configure Custom Tango Card Email Templates

Tango Card allows you to send branded, personalized emails along with your gift card rewards. These email templates are identified using an Email Template ID (ETID).

You can apply an ETID when:

* Editing an existing gift card reward
* Creating a new gift card reward in your Advocate reward catalog

{% stepper %}
{% step %}

#### Create Your Email Template in Tango Card

1. Log in to your Tango Card account.
2. Follow [Tango Card's instructions](https://help.rewardsgenius.com/s/article/HowtoCreateaCustomEmailTemplate) to create an email template.
3. Copy the Email Template ID (ETID) — it should look like: `Exxxxxxx`.
   {% endstep %}

{% step %}

#### Add the ETID in Your Advocate Account

If editing an existing gift card reward:

1. Navigate to your Advocate program.
2. In the left navigation menu, navigate to ![](https://res.cloudinary.com/product-enablement/image/upload/v1768905009/Accessibility%20Icons/engage-v2.svg) **Engage → Program Rules.**
3. Select the rule you want to edit the action of, then select ![](/files/eHosQ7egwdLcFW9kKpVu) **\[Edit action]**.
4. Select **Next**.
5. Paste the ETID into the Custom Tango Card Email Template ID field.
6. Select **Next**.
7. Review your changes and select **Save**.

<div data-with-frame="true"><figure><img src="/files/m2iwF72hiQimlAEaq57I" alt="" width="472"><figcaption></figcaption></figure></div>

If creating a new gift card reward:

1. In the left navigation menu, navigate to ![](https://res.cloudinary.com/product-enablement/image/upload/v1768905009/Accessibility%20Icons/engage-v2.svg) **Engage → Rewards → Catalog** and select **Create Reward**.
2. Enter a clear, descriptive name for the reward (e.g., $20 Advocate Gift Card) so it’s easy to recognize later.
3. Set the *Reward Type* to **Gift Card**.
4. Select the gift card you’d like to offer from the available options, and enter the corresponding reward amount.
5. Paste the ETID into the Custom Tango Card Email Template ID field.
6. Select **Save**.

<div data-with-frame="true"><figure><img src="/files/XwU9xgBu3wflNe7VKUJS" alt="" width="563"><figcaption></figcaption></figure></div>

Once issued, the reward will trigger the custom email linked to that ETID.

**Sandbox vs. Live ETIDs**

If you’re testing in the sandbox environment using an Advocate-managed sub-account, be aware of the following:

* ETIDs are account-specific. Templates created in the live account will not work in the sandbox account.
* If you try to use a live ETID while the integration is connected to the sandbox, the reward will enter a *pending/fulfillment* error state with the error reason: `UNHANDLED_ERROR`.
* The gift card will not be sent until the correct ETID is available or the integration is switched to the live environment.

When testing in the live environment, reduce the reward value to *$0.01* or *$0.05* to avoid unnecessary costs.

Need more guidance? Visit [Tango Card's Email Templates FAQ](https://help.rewardsgenius.com/s/article/EmailTemplatesFAQ) for tips on template creation and troubleshooting.
{% endstep %}
{% endstepper %}

#### Troubleshooting Tips

<details>

<summary>If you experience issues with your Tango integration, check the following solutions:</summary>

* **Credentials error**: Double-check your Account ID, Group ID, Username, and API Key.
* **No rewards sent**: Ensure your Tango account has sufficient funds.
* **Email not customized**: Confirm that your ETID is correctly entered and active.
* **Integration not saving**: Verify that all required fields are completed.

</details>


# Integrate with HubSpot for Advocate

This guide covers the HubSpot integration for Advocate programs, supporting standard HubSpot objects: Deals, Companies, and Contacts.

## Prerequisites

Use this guide to help you set up HubSpot integration for Advocate when:

* You already have a Performance or Creator program.
* You have [cross-program tracking](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/tracking/set-up-tracking/enable-cross-program-tracking) enabled between your Advocate and Performance programs, and use an existing performance conversion event shared with Advocate.
* You're adding a new Advocate program from the in-app prompt and checklist.

{% hint style="warning" %}
**Important architectural limitation:** The HubSpot integration is limited to connecting with only one Advocate Program ID per HubSpot instance. This one-to-one mapping is mandatory to ensure accurate data sync and program property visibility on contact records.
{% endhint %}

{% stepper %}
{% step %}

### Connect and configure HubSpot

<details>

<summary>Initial integration setup</summary>

If you are setting up your HubSpot integration for the first time, you must complete the following steps.

***

#### Connect and configure the HubSpot integration

Advocate adds special settings to your impact.com HubSpot integration. If you haven't set up the integration yet, follow our [Integrate with HubSpot](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-hubspot) guide to do the following. Then, return to this section for Advocate-specific setup steps.

1. [Install and connect](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-hubspot) the impact.com app in HubSpot.
   * On the *Settings* page in the connector, make sure you toggle on Advocate Program opt-in.
2. Enable [event triggers](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-hubspot). Configure [field mappings](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-hubspot).
   1. For Advocate, you must set up a few specific field mappings for the Deals object.
   2. You must pass the ClickId field on the conversion so it maps to your participants.
   3. In most cases, it's not required to map fields for either the Contact or Company objects. If your specific implementation requires mappings from either of these, a custom set of mappings will be provided to you by your impact.com-assigned Implementation Engineer.

| impact.com Mapping                                                                                                                                                                                         | HubSpot Mapping              | Required?   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- |
| `EventDate`                                                                                                                                                                                                | lastmodifieddate             | Yes         |
| `CustomerId`                                                                                                                                                                                               | hs\_object\_id               | Yes         |
| `CustomerEmail`                                                                                                                                                                                            | email                        | No          |
| <p><code>OrderId</code><br>This is the default field used by impact.com to uniquely identify each conversion event. However, you can select another field to use instead.</p>                              | deal\_\[stage]\_id           | Yes         |
| <p><code>EventTypeCode</code><br>This is the default field used by impact.com to determine which program rule to trigger for a conversion event. However, you can select another field to use instead.</p> | deal\_\[deal stage]          | Yes         |
| `OrderSubTotal`                                                                                                                                                                                            | amount                       | Recommended |
| `Date3`                                                                                                                                                                                                    | closedate                    | Recommended |
| `Text2`                                                                                                                                                                                                    | hs\_deal\_stage\_probability | Recommended |

***

#### Configure HubSpot for Advocate

If you already have impact.com and HubSpot connected, you can [reopen the connector](https://hubspot-integration.impact.com/) to configure Advocate for HubSpot.

{% hint style="warning" %}
**Important:** We use this single connected Advocate program as the source of information when creating these new contact properties in HubSpot: Referral Code, Share Link, Message Links, Referred-by Code, Advocate User and Account ID, and Referral Cookie.
{% endhint %}

</details>
{% endstep %}

{% step %}

### Review your Microsite

Use microsites to give your customer advocates an easy way to interact with your Advocate program and start sharing.

You’ll need to:

1. [Customize the appearance of your microsite](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/microsite-experiences/customize-microsite-layouts-and-pages).
2. Share the microsite URL with your Advocates when you launch the program.
   {% endstep %}

{% step %}

### Set up your cash rewards

Your customer advocate can be rewarded with cash payouts. Confirm that your impact.com account is [adequately funded](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/finance/add-funds-to-your-funding-account/deposit-funds-into-your-account).
{% endstep %}

{% step %}

### Test the integration

We recommend testing the integration to ensure it’s working as intended.

| Test                                                                                                                                                                                                                                                                                  | Purpose                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| <p>Create a deal with one of the new HubSpot contacts and change its status to <code>Closed Won</code>.<br>Use if you set up your program rules to perform an action when a deal’s status changes. If you used another status other than <code>Closed Won</code>, test with that.</p> | Confirm that program rules trigger correctly when a deal’s status changes. This should create and convert the referral. |

Congratulations! You’ve successfully navigated the technical setup. Your Advocate program is now integrated with HubSpot. To start seeing results and getting your Advocates engaged, make sure to share your unique microsite link across your marketing channels.
{% endstep %}
{% endstepper %}

## Optional enhancements

<details>

<summary>Upgrade your integration</summary>

For users already utilizing the [HubSpot integration](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-hubspot) for Performance and Creator programs, these Advocate-specific configurations are optional. You don’t need to make any immediate changes to your existing integration to launch your Advocate program; however, we recommend revisiting these enhancements once you’ve completed the initial setup steps above to ensure your integration is fully optimized.

Key benefits of activating the Advocate-specific integration include:

* Bi-directional data syncing: After setup, HubSpot can send referral tracking, deal stage, and contact information directly to impact.com. Important Advocate program properties like referral codes, share links, and more will be visible on contact records.
* Lead and Contact enrichment: Set up a HubSpot lead capture form that sends referral data to your Advocate program.

***

#### Manage your data sharing rules

This step takes place within the [HubSpot to impact.com connector](https://hubspot-integration.impact.com/login).

1. Choose which data is shared between impact.com and HubSpot when a new contact or participant is created.

| Action                                     | When                                                                              |
| ------------------------------------------ | --------------------------------------------------------------------------------- |
| Create contacts in HubSpot                 | An Advocate participant is created. An existing, unmapped participant is updated. |
| Create Advocate participants in impact.com | A HubSpot contact is created. An existing, unmapped contact is updated.           |

2. Refer to HubSpot's documentation to learn how to [customize the properties shown on records](https://knowledge.hubspot.com/object-settings/customize-properties-in-record-sections).
3. There are other, non-adjustable rules for deleting and updating participant and contact records. You can return to this screen to review them, or refer to [HubSpot & Advocate Data Mapping Explained](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-hubspot-for-advocate/hubspot-and-advocate-data-mapping-explained) for more details.
4. Update the contact record layout in HubSpot to show participants' Advocate data.
5. Review your selections and choose whether to sync all Advocate participant data to HubSpot after setup.
6. Select **Finish**.

{% hint style="success" %}
**Note:** The initial data sync does not transfer your HubSpot contact records to impact.com. If you’d like to import them after setting up the integration, then make sure you [sync your HubSpot data](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-hubspot-for-advocate).
{% endhint %}

***

#### Register Referred Leads

1. Create a new hidden field on your HubSpot form for the impact\_referredby\_code Contact Property.
2. Load the function below alongside your HubSpot lead form.
   * This function will break down the referral cookie and ensure the referred by code is submitted along with the rest of the customer’s information to HubSpot.
3. Replace ProgramID with your Advocate Program ID.

{% hint style="success" %}
**Note:** This function requires the Universal Tracking Tag to be loaded for all transactions.
{% endhint %}

```javascript
<script>
  document.addEventListener("DOMContentLoaded", function() {
    // Delay function to ensure HubSpot form fields are fully rendered
    setTimeout(function () {
      window.impactOnReady = function () {
        // Retrieve the DOM element you want to auto-fill the referral code into
        const elements = document.getElementsByName("impact_referredby_code");
        if (elements.length > 0) {
          const element = elements[0];
          // Retrieve referral information from the cookie and set on element
          impact.api().referralCookie()
            .then(function (response) {
              const referralCode = response.codes['PROGRAMID'];
              if (referralCode) {
                element.value = referralCode;
              }
            })
            .catch(function (error) {
              console.error("Error retrieving referral cookie:", error);
            });
        } else {
          console.error("No element found with name 'impact_referredby_code'");
        }
      }
      // Call the impactOnReady function
      if (typeof impact !== 'undefined') {
        window.impactOnReady();
      } else {
        console.error("Impact object not found.");
      }
    }, 1000) // 1-second delay to ensure HubSpot form fields are rendered
  });
</script>
```

***

#### Sync HubSpot data

Optionally, you can bulk import data into HubSpot to ensure your Advocate program’s participants are synced with your HubSpot leads and contacts.

1. Export your contacts from HubSpot as a .CSV file.
2. Adjust the .CSV file to match the accepted bulk import format.
   1. Make sure that the name of the email column in the import file is *email*. We use this field to map HubSpot contacts with Advocate participants.
   2. Learn more about [bulk imports](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/import-advocate-participants-in-bulk) and [download a sample CSV file](https://assets.ctfassets.net/s68ib1kj8k5n/7LOYwhDlsI22uuaIMaWImE/71cefe860edc71c0968c8065e1d6e953/sample-user-upload.csv).
3. In your impact.com account, from the left navigation menu, select **Participants**.
4. At the top-right corner of the page, select **Import users**.
5. Upload the .CSV file.
   * To avoid errors, check that the .CSV file you’ve prepared follows the accepted import format. Reach out to our support team if you have questions.

</details>

#### **What’s Next**

Finally, test your integration to make sure that participants are being correctly registered in impact.com and rewarded for successful referrals.

* [End-to-End Testing](https://integrations.impact.com/integration-guides/for-brands/advocate/end-to-end-testing-for-advocate)

<br>


# Send Data from a HubSpot Form to Advocate

Once you’ve integrated Advocate with HubSpot, you can automatically track referrals with HubSpot forms. Referrals are tracked by placing a cookie on the website that your referral form is on. Brands using other setups will need to add the UTT to their landing page.

An active HubSpot integration is required to send data from HubSpot Forms to Advocate. Refer to [Integrate with HubSpot for Advocate](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-hubspot-for-advocate) to get started.

{% hint style="success" %}
**Note on Program IDs:** This functionality relies on the single Advocate Program ID configured in your main HubSpot integration. It is not possible to send form data to multiple Advocate programs from a single HubSpot instance.
{% endhint %}

{% stepper %}
{% step %}

### Create a lead capture form in HubSpot

1. In HubSpot, create a lead capture form.
   * Skip this step if you have an existing lead capture form you want to use.
2. Make sure your form contains a field for `impact_referralcookies`. We recommend hiding this field from the interface.
   {% endstep %}

{% step %}

### Copy your UTT

1. From the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. On the right, below *Program → Tracking*, select **General**.
3. Copy your UTT and save it somewhere you can easily access it, like a notepad app.
   {% endstep %}

{% step %}

### Generate your referral attribution script

1. In your impact.com account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. On the left, below *Advocate Settings*, select **Install**.
3. In the *Use referral cookies* section, select whether you’re using a **HubSpot landing page** or a **custom landing page**.
4. Copy the resulting *referral attribution script* and save it somewhere you can easily access it, like a notepad app.
   {% endstep %}

{% step %}

### Set up your landing page

Next, continue based on which type of landing page you're using.

#### HubSpot landing page

{% hint style="success" %}
**Note:** Not all HubSpot landing pages support adding custom code. If yours does not, then you’ll need to use another type of landing page.
{% endhint %}

1. In HubSpot, go to your landing page’s settings.
2. Expand the advanced options.
3. In the *Additional code snippets* box, add the UTT and the referral attribution script.
4. Save your changes.

#### Custom landing page

1. Paste the UTT and the referral attribution script on your landing page.
2. In HubSpot, go to your form settings.
3. Select **Embed** and find the `region`, `portalId`, and `formId` values.
4. Paste them into the referral attribution script on your landing page. There are instructions in the script to show you where to add this information.
   {% endstep %}

{% step %}

### Optionally, test the form

Submit test information to the form to confirm that it’s properly attributing referrals. Make sure that:

* The lead is created as a new Advocate participant, if you’re using this data sharing rule.
* The contact in HubSpot contains Advocate properties like referral code, share link and, message links.
  {% endstep %}
  {% endstepper %}


# HubSpot & Advocate Data Mapping Explained

impact.com can receive event data (e.g., lead form submissions) from HubSpot and track it as an action within the impact.com platform. If you're running an Advocate referral program, you can also use HubSpot to sync data about your customer advocates between HubSpot and impact.com.

This guide goes into detail about specific data-sharing and event-handling behaviors. For integration setup instructions, refer to [Integrate with HubSpot for Advocate](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-hubspot-for-advocate).

{% hint style="success" %}
**Note on Program Configuration:** The HubSpot integration is limited to connecting with only one Advocate Program ID per HubSpot instance. This single program is the source for all data syncing, including referral codes and share links.
{% endhint %}

## Data sharing

Your Advocate program and HubSpot share data through a combination of report-based syncs and webhooks.

<div data-with-frame="true"><figure><img src="/files/5A8Z1MpQZaOZ7zaLx0kv" alt="" width="563"><figcaption></figcaption></figure></div>

Report-based sync sends data from impact.com to HubSpot in 1-minute intervals. They transmit to HubSpot any participant information that's been created or updated since the previous sync.

Webhooks share data from HubSpot to impact.com. When we receive a webhook that triggers the creation or mapping of a contact with an Advocate participant, we immediately send Advocate properties back to the contact in HubSpot. This means you’ll see Advocate-specific properties, like referral code and share link, as soon as a contact is created or updated.

### Sharing rules

By default, there are several situations in which we send data between platforms. Some of these rules can be adjusted when you set up the integration.

{% hint style="success" %}
**Note:** Your HubSpot account settings determine whether new contacts are marketing or non-marketing.
{% endhint %}

**Adjustable rules**

| Action                                                | Result                                          |
| ----------------------------------------------------- | ----------------------------------------------- |
| An Advocate participant is created                    | Create a contact in HubSpot                     |
| An existing, unmapped Advocate participant is updated | Create a contact in HubSpot                     |
| A HubSpot contact is created                          | Create a new Advocate participant in impact.com |
| An existing, unmapped HubSpot contact is updated      | Create a new Advocate participant in impact.com |

**Non-adjustable rules**

| Action                                                            | Result                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| An existing, mapped Advocate participant is updated in impact.com | Update the mapped contact’s record in HubSpot.                                                                                                                                                                                                                                                                                                                                                                        |
| An existing, mapped contact is updated in HubSpot                 | Update the mapped Advocate participant’s details in impact.com.                                                                                                                                                                                                                                                                                                                                                       |
| A contact is restored in HubSpot                                  | <p>Re-create the Advocate participant in impact.com.</p><p><strong>Important:</strong> Participant data like referral history can’t be restored. Refer to the <a href="https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-hubspot-for-advocate/hubspot-and-advocate-data-mapping-explained">Participant deletion</a> section for more information.</p> |

### Shared fields

We share data between specific HubSpot and Advocate fields when a creation or update is triggered. Only the fields mapped for a given object type will be synced. Check your integration’s data flow to see which apply for your Advocate program.

We consider a HubSpot contact’s record to be *updated* if 1 of these fields has changed values: email, referred-by code, referral cookies, user ID, or account ID.

{% hint style="success" %}
**Note:** The impact.com HubSpot integration does not support triggering or field mappings of Custom Properties in HubSpot. If there is specific Property information that you want to send in the conversion event you send to impact.com, then we recommend trying to include it in one of the default properties that HubSpot provides. Conversely, the integration is also not able to sync data into Custom Properties in HubSpot beyond the ones created by the integration.
{% endhint %}

{% tabs %}
{% tab title="Advocate participant is created" %}
**Example:** Someone who isn’t a HubSpot contact signs up for your referral program.

**Direction:** Advocate → HubSpot

| From field            | To field            |
| --------------------- | ------------------- |
| First name            | First name          |
| Last name             | Last name           |
| Email                 | Email               |
| Program referral code | Referral code       |
| Program share link    | Share link          |
| User ID               | Advocate user ID    |
| Account ID            | Advocate account ID |
| Message links         | Message links       |
| {% endtab %}          |                     |

{% tab title="Existing Advocate participant (mapped or unmapped) is updated" %}
**Example:** An existing program participant hasn’t yet been mapped to the matching HubSpot contact.

**Direction:** Advocate → HubSpot

| From field            | To field            |
| --------------------- | ------------------- |
| Program referral code | Referral code       |
| Program share link    | Share link          |
| User ID               | Advocate user ID    |
| Account ID            | Advocate account ID |
| Message links         | Message links       |
| {% endtab %}          |                     |

{% tab title="HubSpot contact is created" %}
**Example:** Your lead submission form adds a new contact to HubSpot.

**Direction:** HubSpot → Advocate

| From field       | To field           |
| ---------------- | ------------------ |
| Referred-by code | Referred-by code   |
| Referral cookie  | Cookie             |
| Contact ID       | HubSpot contact ID |
| {% endtab %}     |                    |

{% tab title="Existing HubSpot contact (mapped or unmapped) is updated" %}
**Example:** We receive a contact property change webhook.

**Direction:** HubSpot → Advocate

| From field       | To field           |
| ---------------- | ------------------ |
| First name       | First name         |
| Last name        | Last name          |
| Email            | Email              |
| Email            | User ID            |
| Email            | Account ID         |
| Referred-by code | Referred-by code   |
| Referral cookie  | Cookie             |
| Contact ID       | HubSpot contact ID |
| {% endtab %}     |                    |
| {% endtabs %}    |                    |

### Participant deletion

Participant deletion in impact.com is irreversible, and will impact your analytics and referral history information.

When a contact is deleted in HubSpot, their mapped Advocate participant will also be deleted. We support 2 types of participant deletion:

* Standard deletion, which allows a new participant to be created with the same email address
* GDPR-compliant deletion, which does not allow participant restoration or re-creation in Advocate

### Participant restoration

To a limited extent, restoring a HubSpot contact re-creates the mapped Advocate participant in impact.com. However, the re-created participant’s profile won’t display their previous referral history and associated analytics.

Contacts who request a GDPR-compliant, permanent deletion are never re-created in impact.com. We mark any permanently-deleted participants with a `do not track` label that prevents another participant from being created with this email address.

### Mass syncs

Mass syncs are triggered when you change the Advocate program that's connected to HubSpot. During the mass sync, all participants across all of your Advocate programs are updated or created in HubSpot. We follow your data-sharing rules to determine the specific sync behavior. For example, if your integration is set up to create contacts when a new participant is detected, we’ll also match any existing but unmapped Advocate participants during the mass sync.

## Mapping behaviors

We don’t automatically share changes to participants’ or contacts’ personally identifying information (name and email address) between platforms. This approach helps to avoid unintentional impacts to your sales or marketing processes.

A mapped contact and participant pair doesn't need matching email addresses after the initial data sync. Afterwards, the contact and participant will always be linked based on the Advocate user ID and account ID stored on the HubSpot contact. You can manually update the contact or participant record, but it’s not required for successful referral tracking.

However, contacts and participants may be manually remapped. We recommend doing so only in limited situations, such as if a business and personal contact need to be merged into the same participant. To map a contact with a different participant, change the user and account ID fields in HubSpot to match the participant you want to connect to.

## Program changes

{% hint style="warning" %}
**Consequence of Changing Programs:** While you may change the connected program later, it's best to avoid doing so if possible, as it will delete and re-create properties, requiring manual updates to forms and emails.
{% endhint %}

The program you select is the source of 3 new contact properties: referral code, share links, and message links. When you change connected programs, we:

* Delete all of the contact properties we previously created
* Re-create the properties using the newly selected program

You may run a mass sync when you change connected programs. The mass sync automatically updates all referral codes, share links, and message links in HubSpot to reflect your current program. However, HubSpot forms, emails, and other features that use Advocate properties will need to be manually updated to continue working properly.

## Event handling

You can adjust your program to trigger whenever we receive your impact.com-configured tracking event and 1 of its fields matches your selected criteria.

To view the event properties:

1. From the left navigation menu, select **Data Sources →** [**Events**](https://app.impact.com/secure/advertiser/engage/tracking-settings/actiontracker/view-actiontracker-flow.ihtml).
2. Select the name of the event to go to the event details page.


# Integrate with Salesforce for Advocate

## Prerequisites

Use this guide to help you set up Salesforce integration for Advocate when:

* You already have a Performance or Creator program.
* You have [cross-program tracking](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/tracking/set-up-tracking/enable-cross-program-tracking) enabled between your Advocate and Performance programs, and use an existing performance conversion event shared with Advocate.
* You're adding a new Advocate program from the in-app prompt and checklist.

{% hint style="warning" %}
**Important Architectural Limitation:** The Salesforce integration is limited to connecting with only one Advocate Program ID per Salesforce instance. This one-to-one mapping is mandatory to ensure accurate data sync and program property visibility on Lead and Contact records.
{% endhint %}

{% stepper %}
{% step %}

### Connect and configure Salesforce

<details>

<summary>Initial integration setup</summary>

If you’re setting up your Salesforce integration for the first time, you must complete the following steps.

#### Enable the Salesforce integration in impact.com

This may already be set up for you if you've previously used Salesforce for your Creator or Performance program.

Start by enabling Salesforce for your impact.com account's Advocate program.

1. In impact.com, from the top navigation menu, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. On the left, below *Advocate Settings*, select **Integrations**.
3. On the *Salesforce* card, select **+ \[Expand]**, then select **Enable Salesforce**.
4. Select **Log in with Salesforce** and enter your Salesforce credentials.
5. Select **Allow** to give impact.com access to your Salesforce organization.

***

#### Install the impact.com package in Salesforce

{% hint style="warning" %}
**Warning:** Only Salesforce System Administrators should install and configure the impact.com package.
{% endhint %}

1. In the Salesforce AppExchange, go to the [impact.com Partner Manager page](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000QsHhwEAF\&tab=e).
2. Select **Get It Now**.
3. Follow the on-screen instructions to install the impact.com app.

If you experience any issues installing from AppExchange, you can find a direct link to the package from the *Salesforce* card in your Advocate integration settings.

***

#### Configure your Sync settings in impact.com

1. In impact.com, from the top navigation menu, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. On the left, below *Advocate Settings*, select **Integrations**.
3. On the *Salesforce* card, select **+ \[Expand]** to expand the integration settings.
4. Select **Sync Settings**. Then, choose the Advocate program you want to connect and the sync frequency.
5. Only custom fields need to be set up in the sync settings. Basic lead and contact fields don't need to be mapped here.
6. Save your changes.

***

#### Configure your impact.com credentials in Salesforce

You'll need your impact.com Account SID, Auth Token, and program ID. Refer to [Edit API Access Tokens as a Brand](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/edit-api-access-tokens-as-a-brand) for help finding your Account SID and Auth Token. To find your program ID in your impact.com account, select the account selection dropdown menu in the upper-left corner of the page. Your program ID is listed on the right, below the *Programs* heading.

1. In your Salesforce account, open the impact.com integration, then navigate to the Impact Setup tab.
2. Input the required fields:
   1. Impact account SID
   2. Auth token
   3. Program ID
3. Select **Save**.
4. In the *Activate Data Sync* section, toggle on the option to enable communication between Salesforce and impact.com.

***

#### Configure field mappings and event triggers in Salesforce

In this step, you'll identify which conditions in Salesforce must be met for impact.com to track a conversion event.

Alternatively, you can use Flow Builder to set up custom logic on when events should be sent to impact.com. If you plan to use Flow Builder instead, contact your impact.com-assigned Implementation Engineer or our support team for assistance.

{% hint style="success" %}
**Reversing a conversion event**: Conversion events can be reversed or modified as long as the reward is still in its pending phase or hasn't been redeemed. You will have to send through the totalPostDiscount as 0 dollars for the rewards to get retracted. Once a reward has been redeemed, the referral is considered locked and the reward can no longer be cancelled. Refer to [Batch Modifications & Reversals via FTP or Email](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/batch-modify-conversion-data/batch-modifications-and-reversals-overview) for more information on the process.
{% endhint %}

***

**Field mappings**

The *Field Mappings* section is where you can specify which Salesforce fields are associated with impact.com fields to ensure accurate conversion and action reporting in impact.com.

1. In your Salesforce account, open the impact.com integration, then navigate to the **Impact Field Mapping** tab.
2. Ensure that the Salesforce field *clickId* is mapped with the impact.com field `irclickId`.
3. Some fields are mapped automatically. You can map other fields as required. If you're not sure which fields to map, reach out to your impact.com-assigned Implementation Engineer or our support team for assistance.

***

**Event triggers**

1. In Salesforce, navigate to the **Impact Event Triggers** tab.
2. In the section *Enable trigger event when a new record is created*, use the toggles to choose which events will trigger a conversion event in impact.com when a record is created in Salesforce for that object.
3. In the section *Enable trigger event when a field is changed*, use the toggles to add triggers for an event, if you want impact.com to create a conversion (and thus, create an action) when a record of the specified event is modified.
4. Exit the impact.com integration and return to your main Salesforce dashboard.

</details>
{% endstep %}

{% step %}

### Review your Microsite

Use microsites to give your customer advocates an easy way to interact with your Advocate program and start sharing.

You’ll need to:

1. [Customize the appearance of your microsite](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/microsite-experiences/customize-microsite-layouts-and-pages).
2. Share the microsite URL with your Advocates when you launch the program.
   {% endstep %}

{% step %}

### Set up your cash rewards

Your customer advocate can be rewarded with cash payouts. Confirm that your impact.com account is [adequately funded](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/finance/add-funds-to-your-funding-account/deposit-funds-into-your-account).
{% endstep %}
{% endstepper %}

Congratulations! You’ve successfully navigated the technical setup. Your Advocate program is now integrated with Salesforce. To start seeing results and getting your Advocates engaged, make sure to share your unique microsite link across your marketing channels.

## Optional enhancements

<details>

<summary>Upgrade your integration</summary>

If you’re already using the [Salesforce integration](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-salesforce) for a Performance or Creator program, completing these Advocate-specific steps is entirely optional. You don’t need to make any immediate changes to your existing integration to launch your Advocate program; however, we recommend revisiting these enhancements once you’ve completed the initial setup steps above to ensure your integration is fully optimized.

Key benefits of activating the Advocate-specific integration include:

* Bi-directional data syncing
* Lead and Contact enrichment

***

#### Register referred leads

To register the referred user using Salesforce:

1. Create an [attribution flow](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-salesforce-for-advocate/example-salesforce-flows-for-advocate).

{% hint style="warning" %}
**Important:** You must set up flows in Salesforce's Flow Builder to share data between Salesforce and your Advocate program. Data cannot be shared between the platforms without a flow.
{% endhint %}

2. [Create the *Referred by Code*](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-salesforce-for-advocate/example-salesforce-flows-for-advocate) on your lead object.
3. Capture *Referred by Code* in your lead form.
   1. Create a *Referred By Code* hidden field in the form to capture the referral code of the referrer.
   2. Use the *Autofill* function below to retrieve the referral code from the cookie and pass it into the *Referred By Code* field.

Place the below function on your lead form. This function will break down the referral cookie and ensure the referred user is attributed in Salesforce.

{% hint style="success" %}
**Note:** This function requires the Universal Tracking Tag to be loaded for all transactions.
{% endhint %}

```javascript
<script>
  // Replace `PROGRAMID` with your Program ID.
  window.impactOnReady = function () {
    // Retrieve the DOM element you want to auto-fill the referral code into
    // There are many methods to do this but some of the most common include:
    // getElementById
    // getElementsByClassName
    // getElementsByTagName
    const element = document.getElementById("referralCodeField");
    // Make the request to retrieve referral information from the dropped cookie
    // Cookies are dropped after a user clicks on a sharelink
    impact
      .api()
      .referralCookie()
      .then(function(response) {
        // Retrieve a specific program's referral code from the response and set it on your element
        // The response returns referral codes within an object called "codes"
        // Example:
        // {
        //   "program-1": "REFERRALCODE1",
        //   "program-2": "REFERRALCODE2"
        // }
        // Use your program ID to access and apply the correct referral code to your element
        // example: element.value = response.codes["12345"];
        element.value = response.codes["PROGRAMID"];
      });
  };
</script>
```

***

#### Add Advocate fields to your layout

Adding Advocate fields to your contacts will allow you to use the contact's unique referral share link when generating promotional emails sent out of Salesforce or another Email Marketing Platform that is integrated with your Salesforce instance.

1. In Salesforce, select the **Leads** tab.
2. In the upper-right corner, select **\[Settings]**, then **Edit Object**.
3. In the left navigation menu, select **Page Layouts**.
4. Select the layout you want to edit (e.g., Lead Layout).
5. From the layout panel at the top of the page, select and drag the **Section** field into the layout.
6. In the *Section Properties* window, enter a name (e.g., Advocate Information) and select a column style.
7. From the layout panel at the top of the page, select and drag the **Referral Code** and **Referral Link** fields into your new section.
8. Save your changes.
9. Return to the **Leads** tab and verify that the fields have been added to the layout.

You can add Advocate fields to your Contacts by following the steps above within your Contacts tab in Salesforce.

</details>

***

#### **What’s Next**

Finally, test your integration to make sure that participants are being correctly registered in impact.com and rewarded for successful referrals.

* [End-to-End Testing](https://integrations.impact.com/integration-guides/for-brands/advocate/end-to-end-testing-for-advocate)


# Example Salesforce Flows for Advocate

{% hint style="warning" %}
**Important:** You must have the core Salesforce for Advocate integration set up in order for these flows to work properly. For instructions, refer to [Integrate with Salesforce for Advocate](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-salesforce-for-advocate). These flows are configured to send data to the single Advocate Program ID established during your main Salesforce integration setup. It is not possible for these flows to attribute data to multiple programs.
{% endhint %}

Your Salesforce for Advocate integration relies on *flows* to share data between impact.com and Salesforce. At minimum, a *user upsert* (or *attribution*) flow is required. Optionally, an *event tracking* flow can be added. Additional flows may be useful for your program as well. Work with your impact.com-assigned implementation engineer or our [support team](https://app.impact.com/secure/advertiser/support/customer-support-portal-flow.ihtml) for guidance on the recommended approach.

Below are generic examples of an attribution flow that upserts users from Salesforce to impact.com, as well as an event tracking flow that sends order details from Salesforce to impact.com.

## Attribution flow

Attribution flows can be set up to upsert users from Salesforce to impact.com whenever new Leads contain a `Referred By Code`.

{% stepper %}
{% step %}

### Create a new flow

1. In your Salesforce account, launch Flow Builder.
2. In the top menu bar, select **New Flow**.
3. Select **Record-Triggered Flow** from the options, then select **Create.**
4. Under *Select Object*, search for `Lead`.
5. Under *Configure Trigger*, select **A record is created or updated**.
6. Under *Set Entry Conditions*, select **None**.
7. Ensure the field *Optimize the Flow for* is set to **Actions and Related Records**.
8. Select **Done**.
   {% endstep %}

{% step %}

### Create a `Referred By Code` field

1. In your Salesforce account, open the **Setup** page.
2. Go to **Object Manager**.
3. Select **Lead**.
4. Select **Fields & Relationships** from the sidebar.
5. Select **New**.
6. Choose the **Text** data type, then select **Next**.
7. In the **Label** field, enter `Referred By Code`.
8. Optionally, add a description.
9. Select **Next**.
10. Select which profiles should have access to the field depending on your organization structure, then select **Next**.
11. Select which page layouts should display this field. **All** is the recommended option.
12. Select **Save**.
    {% endstep %}

{% step %}

### Create a decision based on the `Referred By Code` field

1. In Salesforce, within your new flow, select **+ \[Add]** between the *Start* and *End* of the flow.
2. Select **Decision** from the *Logic* section.
3. In the *Label* field, add a title: `Has Referred By Code Been Added?`.
4. Optionally, add a description.
5. Ensure **New Outcome** is selected.
6. Under *Condition Requirements to Execute Outcome*, select **All Conditions Are Met (AND)** from the dropdown list.
7. In the *Resource* field, select **Record / Lead** from the dropdown list, then scroll down to select **Referred By Code** The final result should look like: `$Record > Referred By Code`.
8. From the *Operator* dropdown list, select **Is Null**.
9. In the *Value* field, type `false` and hit **Enter** or **Return**.
10. Select **Default Outcome** and change the label to `Referred By Code is blank` or similar.
11. Select **Done**.
    {% endstep %}

{% step %}

### Create an action to send the Referred Lead to impact.com

1. In Salesforce, within your flow, select **+ \[Add]** on the *Has Referred By Code* branch of the flow.
2. Select **Action** under the *Interaction* section of the list.
3. In the *New Action* window, choose **Type in the Filter By** dropdown.
4. Select **Apex Action** from the list.
5. Select the **Action** field, then select **Upsert User by ID**.
6. In the *Label* field, type `Upsert Referred User to impact.com`.
7. Optionally, add a description.
8. For both the `accountId` and `userId` fields, select **Lead** from the dropdown list, then scroll down to select **Email**.
9. Use the sliders to map the fields you want to send between Salesforce and impact.com.

{% hint style="warning" %}
**Required:** The `Referred By Code` created in step 2 needs to be mapped back to the impact.com `Referred By Code` field. This field mapping is required to pass the referral attribution connection between the Salesforce instance and the Advocate tenant.
{% endhint %}
{% endstep %}

{% step %}

### Review and test the flow

If the Flow looks complete, select **Save** to save your work.

You can use the Test and Debug tools to run the flow and review the outcomes. To fully test the Flow, create a new lead with a “Referred By Code” manually added to that field. The user should appear in your Advocate program's [participants list](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants) after a few minutes.
{% endstep %}
{% endstepper %}

## Opportunity-Closed Won flow

You can set up an Opportunity-Closed Won flow to send an event to impact.com when the associated Opportunity gets to the Closed Won stage.

{% stepper %}
{% step %}

### Create a new flow

1. In your Salesforce account, launch Flow Builder.
2. In the top menu bar, select **New Flow**.
3. Select **Record-Triggered Flow** from the options, then select **Create**.
4. Under *Select Object*, search for **Opportunity**.
5. Under *Configure Trigger*, select **A record is created or updated**.
6. Under *Set Entry Conditions*, from the *Condition Requirements* dropdown list, select **All Conditions Are Met (AND)**.
7. Select **Field**, then select **customerEmail**.
8. Select **Operator**, then select **Is Null**.
9. In the *Value* field, type `false` and hit **Enter** or **Return**.
10. Select **Add Condition** to create a second condition.
11. Select **Field**, then select **StageName**.
12. Select **Value** and select **Closed Won** from the dropdown menu.
13. Ensure the field *Optimize the Flow for* is set to **Actions and Related Records**.
14. Select **Done**.
    {% endstep %}

{% step %}

### Create an action to send the `Closed Won` event to impact.com

1. In Salesforce, within your new flow, select the **+ \[Add]** after the *After Last* label in the Flow.
2. Select **Action** under the *Interaction* section of the list.
3. In the *New Action* window, choose **Type** in the *Filter By* dropdown.
4. Select **Apex Action** from the list under the *Filter By* dropdown.
5. Select the **Action** field and select **Track Event by Email**.
6. In the *Label* field, type `Send Closed Won to impact.com`.
7. Add an optional description.
8. Enter values for the following fields:
   * **CampaignId:** The 5-digit `ID` of the Advocate program. If you already have a Performance program and are using event sharing, the `CampaignId` will be the 5-digit `ID` of the Performance program.
   * **CustomerEmail:** The lowercase email address you initially used for this field.
   * **EventDate:** Set to `NOW` if you want it to reflect the time that the Flow is triggered, or it can be tied to another date field from the Opportunity or Lead.
   * **EventTypeId:** Set to `closedWon`.
   * **OrderId:** Set to the `ID` of the Opportunity.
   * **CustomerId:** Set as the same email address you used in `CustomerEmail`.
9. Select **Done**.
   {% endstep %}

{% step %}

### Review and test the flow

If the Flow looks complete, select **Save** to save your work.

You can use the Test and Debug tools to run the flow and review the outcomes. To fully test the Flow, convert the lead from above into an Opportunity and then push it to a Closed Won stage. The `closedWon` event should appear in that [participant's profile](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/advocate-participant-profiles-explained) in impact.com after a couple of minutes.
{% endstep %}
{% endstepper %}


# Integrate with Shopify for Advocate

Once you've set up your Advocate program in the in-app checklist, you can integrate it with Shopify to track all purchases and referrals, display referral widgets on your site, and create a seamless referral experience for your customers This guide includes both technical steps and strategic insights to help you complete the process.

{% hint style="warning" %}
**Important:** The Shopify integration is limited to connecting with only one Advocate Program ID per Shopify store. This one-to-one mapping is mandatory to ensure accurate tracking of purchases, referrals, correct rendering of program widgets and reward processing.
{% endhint %}

{% stepper %}
{% step %}

### Install & configure the impact.com app on your Shopify store

If you don't already have the impact.com integration set up on your Shopify store, follow the instructions in our [general Shopify integration guide](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-shopify) to do so.
{% endstep %}

{% step %}

### Update your Shopify store settings

#### Require email at checkout

Ensure that your Shopify store requires customers to provide their email at checkout. This is needed to track referral conversions.

1. Navigate to **Settings → Checkout**.
2. Under *Customer contact method*, choose **Email**.

<div data-with-frame="true"><figure><img src="/files/vwiR7NNyhjmWqbybKgjX" alt="" width="550"><figcaption></figcaption></figure></div>

Need help? Visit [Shopify's guide on checkout form options](https://help.shopify.com/en/manual/checkout-settings/checkout-form-options).

#### Enable the UTT in your Shopify store

The UTT loads the widgets on your store pages.

1. Navigate to **Online Store** and select **Customize**.
2. Select the **App Embeds** icon in the left menu bar.
3. ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggle on] UTT**.

<div data-with-frame="true"><figure><img src="/files/jOFHqiT3A5nfSDHj3I7o" alt="" width="442"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Add referral widgets to your Shopify site

Your referral program has both a *customer advocate* and a *referred friend* experience. You'll need to set up the *customer advocate* experience. The Friend Widget is automatically set up, but you can choose to use the more advanced *embedded* widget style if you prefer.

#### Customer advocate experience

The **advocate referral widget** and the [**Shopify Post-Checkout Widget**](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/widget-experiences/shopify-post-checkout-widget) are required. It gives customer advocates instant access to start referring from your website, which is ideal for promoting social sharing and reducing drop-off. Place this widget in a high-traffic area like your homepage or product page to make it easy for advocates to participate without needing to log in or wait for an email.

First, create a page template that includes the Advocate referral widget. Then, create a new "Refer a Friend" page that uses the template.

#### Create a page template

1. [Create a new template](https://help.shopify.com/en/manual/online-store/themes/theme-structure/templates#create-a-new-template) in your Shopify admin. We recommend naming it **Advocate Referral Widget**.
2. Add the advocate referral widget to your template:
   * Under *Template* in the right-hand sidebar, select **(+) Add section**.
   * Switch to the *Apps* tab and select the **Advocate Referral Widget** from impact.com.
3. Select **Save**.

#### Create a page

1. [Create a new page](https://help.shopify.com/en/manual/online-store/themes/theme-structure/pages/add-edit-pages#add-new-page) titled **Refer a Friend**.
2. Assign your **advocate-referral-widget** template.
3. Leave the visibility set to *Hidden* and select **Save**.

Make this page visible and add it to your navigation menu once your widgets are customized and you’re ready to launch. Many brands place a link to the *Refer a Friend* page in the footer or main nav to keep it visible and drive ongoing engagement.

<details open>

<summary>Optional advanced setup: Verified access widget</summary>

The Verified Access Widget is an optional enhancement best suited for Shopify sites with a logged-in experience, such as customer account dashboards. It can only be accessed by users who are logged into your site. This widget allows returning advocates to quickly view and manage their referral link, referral history, and reward status directly from their account.

While this can offer a more integrated feel for repeat customers or subscribers, we recommend starting with the advocate referral widget for broader accessibility and easier setup. Use the verified access widget as a complement—not a replacement—if your customer flow includes account logins.

1. Create another template titled **Verified Access Widget**.
2. Select **(+) Add section**.
3. Select the **Verified Access Widget** from impact.com and save your changes.
4. Create a new page titled **Refer a Friend - Verified** and apply your **verified-access-widget** template.

</details>

#### Referred friend experience

The Friend Widget is required to register referred friends into your Advocate program. It appears when an advocate’s unique share link is clicked and can be configured to offer a coupon code reward once the referred friend enters their email address into the widget.

By default, the Friend Widget appears as a pop-up. Optionally, you can instead embed it directly on a dedicated page.

{% hint style="success" %}
**Choosing the right experience:** If your site already uses multiple pop-ups (e.g., welcome offers, newsletter signups), showing the friend as a pop-up may overload the referred friend. In this case, we recommend embedding the widget directly on a dedicated landing page to ensure a seamless referral experience and prevent attribution issues.
{% endhint %}

<details open>

<summary>Optional: Embed the Friend Widget</summary>

1. Follow the steps above to [create a new page template](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-shopify-for-advocate) titled **Referred User Landing Page**.
2. Add the Friend widget to your template:
   * Under *Template* in the right-hand sidebar, click on **(+) Add section**.
   * Switch to the *Apps* tab and select the **Friend widget** from impact.com.
3. Follow the steps above to [create a new page](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-shopify-for-advocate). Assign the **Referred User Landing Page** Template to it.

</details>
{% endstep %}

{% step %}

### Set up your rewards

{% hint style="success" %}
**Limited:** All of the listed reward options are already available to *referred users*. To enable them for *Advocates* too, you might need to upgrade your plan. [Contact us](https://app.impact.com/support/portal.ihtml?createTicket=true&&) to gain access.
{% endhint %}

When you set up your program in the checklist, you selected a reward for your customer advocate and the friends they refer. Now, you'll need to finish the reward setup.

#### Reward the customer advocate

Your customer advocate can be rewarded with cash payouts (this is the default reward method), a coupon code for a discount or credit, or a gift card. You may need to [upgrade your Advocate account](https://app.impact.com/support/portal.ihtml?createTicket=true&&) however, to have all reward options available.

* Cash payouts: Confirm that your impact.com account is [adequately funded](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/finance/add-funds-to-your-funding-account/deposit-funds-into-your-account). Also, [configure your microsite](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-rewards/pay-with-cash/set-up-cash-payouts-for-advocate)—your advocates will be sent a link to the microsite to provide their payout details.
* Discounts and credits: [Add coupon codes](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-rewards/set-up-a-fuel-tank-reward) for your participants to redeem. You'll also need to set up the codes for redemption in your system.
* Gift cards: Fund your [Tango Card account](https://www.tangocard.com/).

#### Reward the referred friend

If your referral program rewards either the customer advocate or the referred friend with a discount, you must create discount codes and then [set up your Shopify code sync](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-rewards/set-up-a-fuel-tank-reward).

To set up your program with **cash** or **gift card** rewards, simply follow the instructions above in the *Reward the customer advocate* section.

{% hint style="success" %}
**Note:** The Shopify code sync only works if one Shopify integration is set up for one account.
{% endhint %}
{% endstep %}

{% step %}

### Test your integration

Finally, test your integration to make sure that participants are being correctly registered in impact.com and rewarded for successful referrals. Refer to the [Advocate End-to-End Testing](https://integrations.impact.com/integration-guides/for-brands/advocate/end-to-end-testing-for-advocate) guide for instructions.

{% hint style="success" %}
**Reversing a conversion event:** Conversion events can be reversed or modified before they lock. For example, if the referred friend refunds a purchase, you can reverse or modify the details of the order to retract their reward (as long as it wasn't redeemed). Refer to [Batch Modifications & Reversals Overview](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/batch-modify-conversion-data/batch-modifications-and-reversals-overview) for more information on the process—note that you must send through the `totalPostDiscount` as `0` for the reward to be retracted.
{% endhint %}
{% endstep %}
{% endstepper %}


# Klaviyo for Advocate

impact.com's Klaviyo integration expands your ability to leverage Advocate program data in your marketing efforts. This integration supports bidirectional synchronization of data between your Advocate program and Klaviyo, empowering you to deliver targeted, personalized outreach at scale.

{% hint style="success" %}
**Note:** This integration supports both Shopify and non-Shopify customers and can be accessed via Klaviyo’s integration marketplace.
{% endhint %}

## Why it's useful

Advocate participant data, including names, referral activity, and reward information, is automatically synced with Klaviyo. Once synced, you can use this data to personalize email communication and build audience segments for referral engagement.

The Advocate + Klaviyo integration provides two main capabilities:

#### Participant data syncing

Your Advocate program's participant details, referral stats, and rewards are sent to Klaviyo automatically, so you can use these details for marketing decisions. Any new Klaviyo profiles also show up as Advocate program participants in impact.com.

#### Automatic participant segmentation

Once an Advocate participant has been synced and a Klaviyo profile exists for them, they are automatically added to advocate segments. You can then perform targeted outreach using email templates in the app.

| Segment                | Includes                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| **Advocates**          | All synced participants with referral data.                                                  |
| **Active Advocates**   | Participants who referred, were referred, or earned a reward in the last 30 days.            |
| **Inactive Advocates** | Participants who have *not* referred, been referred, or earned a reward in the last 30 days. |

## Prerequisites

You will need to have:

* An existing Klaviyo store.
* An existing Advocate program.
  * View [this help doc flow](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/introduction-welcome-to-advocate) on our help center for help getting your new Advocate program off the ground.

{% stepper %}
{% step %}

### Install the app on your Klaviyo store

1. Install [impact.com's Klaviyo plugin](https://www.klaviyo.com/integrations/01J80FGJWXZK0NGXSY6JEYY917/details) from Klaviyo's app marketplace.
2. Log in to the app with your Klaviyo credentials.
3. Select the Klaviyo account you want to connect.
4. Review the access permissions that impact.com needs from your Klaviyo account, then select **Allow**.

<div data-with-frame="true"><img src="https://files.readme.io/8faa6054be3df2068671caef2d58db9e3f2610b2a7bfc01ba98e8c037119a1fe-Screenshot_2025-01-31_at_6.12.54_PM.png" alt="" width="375"></div>
{% endstep %}

{% step %}

### Configure integration settings

1. In the *Account information* section, fill in all the fields:

<div data-with-frame="true"><img src="https://files.readme.io/f624e89720de338d7378079a2906dc921eac6702ca0c3bcdded5a6326f369015-Screenshot_2025-07-10_at_12.14.36_PM.png" alt="" width="375"></div>

2. Select **Save** to save the setup.
3. See the *Field reference* below for details on each field or setting.

### Field reference

| Field or Setting                                       | Description                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account SID\***                                      | To find your Account SID, in the impact.com platform, navigate to ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings →** [**API**](https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml) and copy the full case-sensitive value.                                                                                                |
| **Auth Token\***                                       | To find your Auth Token, in the impact.com platform, navigate to ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings →** [**API**](https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml) and copy the full case-sensitive value.                                                                                                 |
| **Account Id\***                                       | <p>To find your Account Id, in the impact.com platform, select your <strong>account name</strong> in the upper-left corner and copy the number string below your account name in the left column.</p><p><img src="https://files.readme.io/09d1833e5d241a57d94c3b20492d6e1268fc9c1a90534b0a95d109a070b5fc0a-advocate_prog_2.png" alt="" data-size="original"></p> |
| **Program Id\***                                       | <p>To find your Program Id, in the impact.com platform, select your <strong>account name</strong> in the upper-left corner and copy the number string below your program name in the right column.</p><p><img src="https://files.readme.io/b8f1a2977ad66a5aca170084da2b8609e28cf5c666a48e33be3d5f266650506e-adv_prog_no.png" alt="" data-size="original"></p>    |
| **Sync all Advocate participants to Klaviyo profiles** | Update existing Klaviyo profiles with corresponding participant data. If there are any new participants who don't have existing Klaviyo profiles, create Klaviyo profiles for them.                                                                                                                                                                              |
| **Add Advocate segments to Klaviyo**                   | Add the segments *Advocate*, *Inactive Advocate*, and *Active Advocate* to your Klaviyo account.                                                                                                                                                                                                                                                                 |
| **Create new Advocate participant in impact.com**      | When a new profile is created in Klaviyo, create a new participant in your Advocate program.                                                                                                                                                                                                                                                                     |
| {% endstep %}                                          |                                                                                                                                                                                                                                                                                                                                                                  |

{% step %}

### Test the data sync

#### Klaviyo steps

1. In Klaviyo, from the left navigation bar, select **Audience → Profiles**.
2. Under *Explore Profiles*, view your profiles or select a profile to open its details.
3. Review the data *Keys* as these should match the participant details in your Advocate program.

<div data-with-frame="true"><img src="https://files.readme.io/76c1c1a0942f30255543924ce2fc38ee5272542cfc633381d1a419d589c31a9e-Screenshot_2025-01-31_at_6_26_29_PM.png" alt="" width="563"></div>

#### impact.com steps

1. In impact.com, go into your Advocate program and from the top navigation bar, select ![](/files/hr700haJWzy65lcXmxJk) **Engage → Participants**.
2. On the *Participants* screen, you should see new Advocate program participants for each Klaviyo profile.
3. Select a participant to open and review participant details like referral codes, share links, etc.
4. See [Advocate Participant Profiles Explained](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/advocate-participant-profiles-explained) to better understand these details.

<div data-with-frame="true"><img src="https://files.readme.io/92f31d6ebe952a1d630fb3a372ad375751c26076275794dca57dc5f3ab398ee4-participants.png" alt="" width="563"></div>
{% endstep %}
{% endstepper %}

## Turn off profile syncing \[Optional]

By default, the Klaviyo integration syncs new Klaviyo profiles into Advocate as referral program participants. If you’d prefer not to automatically create new participants in Advocate when a new Klaviyo profile is added, you can disable this setting:

1. Log in to your Klaviyo account, and from the left navigation menu, select **Integrations** tab.
2. Select the **impact.com** integration.
3. Under *Settings*, select *Go to* **Impact.com Referrals** *to manage your settings*.

<div data-with-frame="true"><img src="https://files.readme.io/ace53d2e0022308253d5d8e6e22530d8f0ccc125d367cf5a2f8789832b2bf629-Screenshot_2025-07-10_at_12.55.30_PM.png" alt="" width="563"></div>

4. Scroll to the **Sync data from Klaviyo to your Advocate program** section.
5. Uncheck the ![](/files/FdvT4C3ocg3u5J4W27p4) **\[Checkbox]** labeled **Create new participant** **in Advocate when a new profile is created in Klaviyo**.

<div data-with-frame="true"><img src="https://files.readme.io/5588feebc2f29a7096f8a7ce1896111f8dd652481e11a6050c12006b383895d1-Screenshot_2025-07-10_at_12.49.45_PM.png" alt="" width="563"></div>

This prevents customers added through Klaviyo from being auto-enrolled in your referral program unless they engage directly (e.g., through a referral link or widget).


# Set Up Your Klaviyo Notifications

The Advocate + Klaviyo integration enables smarter referral engagement by syncing participant data, triggering referral-based flows, and allowing you to manage both transactional and marketing communications in Klaviyo.

Ensure you have the [impact.com app for Klaviyo](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/klaviyo-for-advocate) app installed.

Once installed, use this guide to set up key referral notification emails using *Klaviyo flows*. With this setup, you can:

* Automatically trigger referral emails based on Advocate events (e.g., sign-up, conversion)
* Personalize content with referral and reward data
* Ensure reliable delivery through Klaviyo’s transactional email system
* Customize messaging to match your brand tone and voice

This guide includes step-by-step setup instructions, example flows, email templates, and merge tag references to get you up and running.

## Sending Advocate Notifications via Klaviyo

Instead of using Advocate's built-in emails, you can send referral notifications via Klaviyo using custom flows. This allows for greater control over branding, timing, and content.

In this example, we will create a Referred Friend Welcome Email that sends a discount code to the referred friend after they sign up.

{% hint style="success" %}
**Note on Program IDs:** These Klaviyo flows and event data are configured to communicate with the single Advocate Program ID established during your main Klaviyo integration setup. It is not possible to source events or participant data from multiple programs.
{% endhint %}

{% stepper %}
{% step %}

### Create a Flow

1. In Klaviyo, navigate to **Flows → New Flow → Build your own**.
2. Give the flow a name (e.g., “Referral Welcome Email”).
   {% endstep %}

{% step %}

### Set the Trigger

1. Under the *Your metrics* section, select **impact.com Referrals**.
2. Choose a trigger, then select **Save**.
   * See the table below for a list of triggers available. For this example, we'll select Referral Started → Referred.

| Triggers                      | Description                                                                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Referral Converted → Referred | Sent to the referred friend when the referral is converted. *Example: They made a purchase.*                                                  |
| Referral Converted → Referrer | Sent to the referrer (advocate) when the referral is converted. *Example: Their friend made a purchase.*                                      |
| Referral Started → Referred   | Sent to the referred friend when the referral has started. *Example: They used their friend’s share link and filled out the friend widget.*   |
| Referral Started → Referrer   | Sent to the referrer (advocate) when the referral has started. *Example: Their friend uses their share link and fills out the friend widget.* |
| Reward Created                | Sent when a reward is issued to a participant, including cases beyond *Referral Started* or *Referral Converted* events.                      |

<div data-with-frame="true"><figure><img src="/files/c5zUWOSjEM0GqmNyFnC6" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Add Email to Flow

1. From the *Actions* panel on the left, drag an **Email** block into your flow where you want the message to be sent.

<div data-with-frame="true"><figure><img src="/files/byCvCv2Ya8tCVtjkdYkE" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Configure the Email

1. Select the email block you added in the previous step.
2. In the *Settings* tab, uncheck **Skip recently emailed profiles** and then select **Save**.
3. Next, create your email content. You’ll need to design and write your own message. We've provided some examples to inspire you in the *Example Notification Flows* section below.
4. Once you’re ready to publish, select **Review & Turn On** in the top-right corner, then select **Save**.
   {% endstep %}

{% step %}

### Apply for Transactional Status

Marking your email as transactional helps ensure it’s delivered, especially to users who haven’t opted in to marketing emails (like referred friends).

{% hint style="warning" %}
**Important:** Klaviyo requires approval for transactional emails, which can take up to 24 hours. You won’t be able to edit the message while it’s under review. If you edit the email after it’s approved, the transactional status will be removed and must be re-applied.
{% endhint %}

**To apply**:

1. In your flow, select the email message you want to mark as transactional.
2. In the right-hand sidebar, select **Apply for transactional status**.
3. Wait for the approval (usually within 1 business day).
4. Once approved, the email will send as a transactional message.

You can view more information on [How to use flows to send transactional emails](https://help.klaviyo.com/hc/en-us/articles/360003165732) if needed.
{% endstep %}

{% step %}

### Disable Notifications in Advocate

Turn off corresponding notifications in your [Advocate Program Rules](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/getting-started-with-advocate/advocate-program-rules-explained) to avoid duplicates.
{% endstep %}
{% endstepper %}

### Examples of Notification Flows

Below is an example of a referral notification flow based on a common double-sided referral program setup.

These examples assume the following structure:

#### Program rules

* Double-sided program rewarding both the Referrer and the Referred Friend.

#### Widgets used

* **Website Widget**: for Referrer access.
* **Friend Widget**: for Referred Friend sign-up.

#### Program goals

| Trigger                                | Action                                                     |
| -------------------------------------- | ---------------------------------------------------------- |
| **Referral Started**                   | Notify the Referrer. Reward and email the Referred Friend. |
| **Purchase Made** (Referral Converted) | Reward and email the Referrer.                             |

Use these flows in Klaviyo to replicate similar messaging, triggers, and logic.

<details>

<summary>Referred Friend Notification Email</summary>

The Referred Friend receives a discount code when they sign up on the **Friend widget**.

#### **Trigger**

*Referral Started - Referred*

#### **Subject line**

You earned a discount from `{{event.referrerFirstName|default:"your friend"}}`!

#### **Sample contents**

Thanks for giving MyCompany a chance! Since you signed up with `{{event.referrerFirstName|default:"your friend"}}`'s referral code, here’s `{{event.rewardPrettyValue }}` off for your first purchase. Use this unique discount code when you check out:

Discount code: `{{event.fuelTankCode }}`

<div data-with-frame="true"><figure><img src="/files/0Dn0FqnHYeXfOTpXKGwF" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Referrer Notification Email</summary>

The Referrer gets notified that their Referred friend has started the referral process by entering their email on the **Friend widget**.

#### **Trigger**

*Referral Started - Referrer*

#### **Subject line**

Your reward is almost here!

#### **Sample contents**

Your friend `{{event.referredFirstName}}` `{{event.referredLastName}}` is shopping at `MyCompany` after clicking your share link. That means you’re just one step away from earning a `{{event.rewardPrettyValue }}`!

If they complete their first purchase, your reward will be automatically e-mailed to you after 30 days.

Want to earn even more? Keep sharing your link with friends and stack up the savings!

`\{\{ person.sharelink|default:'' }}`

<div data-with-frame="true"><figure><img src="/files/OfDD3LsoYk17dYLgNWNW" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Referral Converted Notification</summary>

The Referrer receives an account credit as a reward when the referral is converted.

#### **Trigger**

*Referral Converted - Referrer*

#### **Subject line**

You've earned a reward for referring `{{event.referredFirstName|default:"your Friend"}}`!

#### **Sample contents**

You earned `{{event.rewardPrettyValue }}` off your next purchase!

`{{event.referredFirstName|default:"Your friend"}}` used your referral link and made their first purchase with `MyCompany`. To say thank you for spreading the word, here’s `{{event.rewardPrettyValue}}` off your next purchase!<br>

<div data-with-frame="true"><figure><img src="/files/o1jLhuoBr1WL7I6iV9f5" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Additional Templates for Non-Transactional Emails</summary>

The Advocate + Klaviyo integration includes two ready-to-use marketing templates to help promote and scale your referral program.

#### **Rewards Program Re-Engagement**

Encourage referrers (advocates) to keep sharing with a personalized nudge and easy access to their referral link.

#### **Rewards Program Launch Announcement**

Announce the launch of your program and invite customers to start referring.

#### **Sample contents**

<div data-with-frame="true"><figure><img src="/files/WN0cVN4QTZLM4O0bMERM" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Field reference table</summary>

The following tags can be used in your Advocate emails in Klaviyo to insert personalized values.

| Description                  | Field                                                    |
| ---------------------------- | -------------------------------------------------------- |
| Share link                   | `{{person.sharelink or default:''}}`                     |
| Referred friend’s first name | `{{event.referredFirstName or default: "your Friend"}}`  |
| Referred friend’s last name  | `{{event.referredLastName}}`                             |
| Referrer first name          | `{{event.referrerFirstName or default: "your Friend"}}'` |
| Referrer last name           | `{{event.referrerLastName}}`                             |
| Reward name                  | `{{event.rewardPrettyValue }}`                           |
| Discount code                | `{{event.fuelTankCode}}`                                 |
| Reward                       | `{{event.rewardPrettyValue}}`                            |
| Reward type                  | `{{event.rewardType}}`                                   |
| Reward value                 | `{{event.rewardValue}}`                                  |
| Reward source                | `{{event.rewardSource}}`                                 |
| Reward expiry date           | `{{event.rewardDateExpires}}`                            |

</details>

## Troubleshooting

<details>

<summary>If your notification emails aren't being sent as expected, check the following:</summary>

* Ensure **Skip recently emailed profiles** is unchecked on the email triggered by your flow.
* Mark emails as **transactional** to reach referred friends who haven't opted in to receive marketing emails.

</details>


# Advocate Tracking Integrations


# Implement with UTT for Advocate

The UTT integration uses a small JavaScript tag added to your website or landing page that tracks conversions and sends the information to impact.com. To get started, choose **No integration** as your integration type in the setup checklist.

## Prerequisites

Use this guide to help you set up UTT tracking for Advocate when:

* You already have a Performance program.
* You have [cross-program tracking](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/tracking/set-up-tracking/enable-cross-program-tracking) enabled between your Advocate and Performance programs.
* You're adding a new Advocate program from the in-app prompt and checklist.
* You aren't using another integration—like Shopify, Salesforce, or HubSpot—to send conversion events to impact.com.

{% hint style="warning" %}
**Important:** If your impact.com-assigned Implementation Engineer provided you with a Technical Implementation Plan, please follow the instructions provided in that document instead.
{% endhint %}

{% stepper %}
{% step %}

### \[Optional] Install the Universal Tracking Tag (UTT)

<details open>

<summary>Locate and copy the UTT</summary>

If you have a Performance or Creator program, you may already have the UTT installed. Check your website before continuing.

The UTT script you must install is specific to your account. Retrieve it from your impact.com account, then install it on your website.

#### Find your UTT script

1. Sign in to your impact.com account.
2. From the top navigation menu, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
3. On the right, under *Tracking*, select [**General**](https://app.impact.com/secure/advertiser/fr/general-tracking-settings.ihtml).
4. Copy the Universal Tracking Tag.

***

#### Add it to your website

We recommend placing the tracking tag in your website HTML rather than on a specific web page.

1. Go to the `head` tag of your website's HTML.
2. Paste the UTT script.

</details>
{% endstep %}

{% step %}

### Review your Microsite

Use microsites to give your customer advocates an easy way to interact with your Advocate program and start sharing.

You’ll need to:

1. [Customize the appearance of your microsite](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/microsite-experiences/customize-microsite-layouts-and-pages).
2. Share the microsite URL with your Advocates when you launch the program.
   {% endstep %}

{% step %}

### Set up your cash rewards

Your customer advocate can be rewarded with cash payouts. Confirm that your impact.com account is [adequately funded](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/finance/add-funds-to-your-funding-account/deposit-funds-into-your-account).
{% endstep %}

{% step %}

### Test your setup

Finally, [test](https://integrations.impact.com/integration-guides/for-brands/advocate/end-to-end-testing-for-advocate) your setup to make sure that referrals are tracked and rewarded as you expect.
{% endstep %}
{% endstepper %}


# Advocate Installation Scripts

This page has a selection of the key scripts you may need when implementing your Advocate program. These are general scripts meant for reference purposes.

{% hint style="success" %}
**Note:** Your implementation may not use all of the scripts below. See your *Technical Implementation Plan* for information about which are required for your program.
{% endhint %}

## Universal Tracking Tag (UTT) for Advocate

Your Advocate program's Universal Tracking Tag (UTT) uses [first-party cookie](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/tracking-cookies-for-advocate-programs) tracking technology to build more accurate conversion paths, attribute referrals to your advocates, and enhance our other cookie-less tracking methodologies, as well as expand the levels of data that we can receive and display in reporting.

The entire code snippet is copied from your Technical Integration Plan document. It will look like:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script type="text/javascript">
  (function(a,b,c,d,e,f,g){
    e['ire_o']=c;
    e[c]=e[c]||function(){
      (e[c].a=e[c].a||[]).push(arguments)
    };
    f=d.createElement(b);
    g=d.getElementsByTagName(b)[0];
    f.async=1;
    f.src=a;
    g.parentNode.insertBefore(f,g);
  })(
    'https://utt.impactcdn.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX.js',
    'script',
    'ire',
    document,
    window
  );
</script>
```

{% endtab %}
{% endtabs %}

The UTT is placed within the global `<head>` HTML element of your site. If you use a tag manager, add the UTT as a custom HTML tag.

{% hint style="success" %}
**Why does the UTT need to be first?** The UTT is required for the other functions to work. If the UTT doesn't load first, the integration can break.
{% endhint %}

## `Identify` function

The `identify` function is used to identify users as accurately as possible across your site, particularly across devices. You'll supply identifiers so impact.com can map them to conversion events for attribution.

1. Access your *Technical Integration Plan* document and find the *Identify Function* section.
2. Copy the entire code snippet from this document.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script type="text/javascript">
  ire('identify', {
    customerId: 'Customer Id',
    customerEmail: 'SHA1 Email Address',
    customProfileId: 'UUID'
  });
</script>
```

{% endtab %}
{% endtabs %}

3. Modify the snippet's placeholder values with real values from your platform:
   * `customProfileId`: A unique identifier used to identify a visitor on your website (regardless of whether they're signed in). Common examples include UUIDs, anonymous user cookies, and IDFVs.
   * `customerId`: a visitor's unique identifier that maps to your site's backend systems.
   * `customerEmail`: A SHA-1 hash of a visitor's email address.
   * If any of these values are unknown, pass an empty string.
4. Add your modified code snippet at the top of the `<body>` HTML element of each page on your website, or use a tag manager to add this code snippet to the top of each `<body>` HTML element across your site.

{% hint style="success" %}
**Note:** When you pass the SHA-1 hash of the visitor's email address, impact.com uses an additional HMAC-SHA-256 hash on the passed value for additional security. Learn more about [customer email hashing](https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/impact.com-customer-email-hashing-explained).
{% endhint %}

## Environment setup

Adding a [JSON Web Token](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/json-web-tokens-jwts) to the `head` of your HTML page allows for easier integration of our widget, track conversion, registration, and autofill scripts into individual pages. The `impactToken` JWT added here will be used for user upsert when a widget loads. It can be placed after the UTT.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script type="text/javascript">
  window.impactToken = "o5b236b23632/b326b236236.nb236236326";
</script>
```

{% endtab %}
{% endtabs %}

## Display a widget

Widgets are participants' main way to access and use your Advocate program. In addition to showing program information to your participants, widgets create and update user information in our system.

There are two main [types of widgets](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/widget-experiences/widget-types-explained) available: instant access, and verified widgets. Both types can be displayed as an *embedded widget* or a *popup widget*. *Embedded widgets* show up directly within your web page or app. *Popup* widgets are displayed in a modal window. When you use the `impact-popup` element, any HTML within the children of the element will serve as the CTA for opening the popup.

The examples provided below are for informational purposes. We recommend generating a personalized script for your implementation. To find your personalized script:

1. In your impact.com account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. From the *Advocate Settings* section, select **Install**.
3. Select a script from the *Display widgets* section.

### Verified access widgets

[Verified access widgets](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/widget-experiences/widget-types-explained) provide a robust, in-app experience for your customer advocates and their referred friends. To protect your participants' personal information, we recommend displaying this widget only to those who have signed in to your product.

{% hint style="warning" %}
**Important:** JWTs are required for verified access widgets.
{% endhint %}

#### Embedded widget

{% tabs %}
{% tab title="HTML" %}

```html
<impact-embed widget="w/referral"><div>Loading...</div></impact-embed>
```

{% endtab %}
{% endtabs %}

#### Popup widget

{% tabs %}
{% tab title="HTML" %}

```html
<impact-popup widget="w/referral"><button>Click me to show widget</button></impact-popup>
```

{% endtab %}
{% endtabs %}

### Instant access widgets

[Instant access widgets](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/widget-experiences/widget-types-explained) give your participants a simple way to engage with your referral program-without signing into your product or service. JWTs are not required for instant access widgets.

#### Embedded widget

{% tabs %}
{% tab title="HTML" %}

```html
<impact-embed widget="w/referral"><div>Loading...</div></impact-embed>
```

{% endtab %}
{% endtabs %}

#### Popup widget

{% tabs %}
{% tab title="HTML" %}

```html
<impact-popup widget="{widget-type}"><button>Click me to show widget</button></impact-popup>
```

{% endtab %}
{% endtabs %}

#### Auto popup widget

In addition to the standard embedded and popup widget styles, instant access widgets allow for an automatic pop-up widget to appear whenever the page is loaded. Participants don't need to interact with your page to trigger a widget load.

## Register participants

Use the `impact.api` method to add or update a participant in your referral program if you aren't displaying a widget. For example, this method can be used to create a new participant in your Advocate program when someone fills out a registration form.

{% hint style="success" %}
**Note:** If you added a JWT during the environment setup, then you don't need to include one with this script too. If there is an existing token on `window.impactToken`, then all requests will use that as the default.
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script type="text/javascript">
  window.impactOnReady = function() {
    const userConfig = {
      user: {
        id: 'abc_123',
        accountId: 'abc_123',
        email: 'john@example.com',
      },
      jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFiY18xMjMiLCJhY2NvdW50SWQiOiJhYmNfMTIzIiwiZW1haWwiOiJqb2huQGV4YW1wbGUuY29tIn0.oDqQ5jAmNsQeLElpFz-i6iGHWMBJdfDMY0_7UWtAEzQ'
    };

    impact.api().upsertUser(userConfig).then(function(response) {
      const user = response.user;
    }).catch(function(error) {
      console.log(error);
    });
  };
</script>
```

{% endtab %}
{% endtabs %}

## `trackConversion` function

The `trackConversion` function is used to track the conversion data reported to your Advocate program. To find and install `trackConversion`:

1. Access your *Technical Integration Plan* document and find the *Conversion Tracking Tags* section.
2. Copy the entire code snippet from the *Technical Integration Plan* document.
3. Modify the snippet's placeholder values with real values from your platform (all fields are required):

```javascript
<script type="text/javascript">
  ire('trackConversion', ${eventId}, {
    orderId: "Order Id here",
    customerId: "Customer Id here",
    customerEmail: "SHA1 Hash of Customer's Email",
    customerStatus: "Customer Status here",
    currencyCode: "USD",
    orderPromoCode: "Promo Code here",
    orderDiscount: 15.00,
    items: [
      {
        subTotal: 28.00,
        category: "Product Category 1",
        sku: "sku-11111",
        quantity: 2,
        name: "Product Name 1"
      },
      {
        subTotal: 99.00,
        category: "Product Category 2",
        sku: "sku-11112",
        quantity: 3,
        name: "Product Name 2"
      }
    ]
  },
  {
    verifySiteDefinitionMatch: true
  });
</script>

```

4. Add your modified code snippet at the top of the body HTML element of the order confirmation page of your site, or use a tag manager to add this code snippet to the order confirmation page.

Refer to our [JavaScript Tag Installation Guide](https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/javascript-tag-utt/installation) for more details about the `trackConversion` parameters and an example payload.

{% hint style="warning" %}
**Before passing additional variables:** Your *Technical Integration Plan* specifies which variables you need to pass - refer to that document for details. At a minimum, your Advocate program requires the `customerEmail` variable to be passed. Contact our [support team](https://app.impact.com/support/portal.ihtml?createTicket=true) before passing additional variables.
{% endhint %}

## Autofill referral codes or cookies

The UTT can be used to pick up a referral code from first-party cookies. The library can also use a CSS selector to pick up the cookie itself if one is present in the referred person's browser.

Using the code or cookie to pre-fill a signup form field can reduce the chance of the referral not being attributed or the referred friend not receiving their reward. Autofill can be used during registration and with specific integrations.

#### Autofill referral codes

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script>
  window.impactOnReady = () => {
    impact.autofill("#referral-code")
  }
</script>
<input type="hidden" id="referral-code" />
```

{% endtab %}
{% endtabs %}

#### Autofill referral cookies

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script>
  window.impactOnReady = () => {
    impact.api().referralCookie().then(res => {
      const input = document.querySelector("#referral-cookie")
      input.value = res.encodedCookie
    })
  }
</script>
<input type="hidden" id="referral-cookie" />
```

{% endtab %}
{% endtabs %}


# Advanced Advocate Installation Scripts

Below are some advanced use cases that you may run into when implementing UTT for a referral program. Please speak to your Implementation Engineer before using these scripts for your program.

For a list of key scripts that apply to most or all implementations, go to [Advocate Installation Scripts](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/advocate-installation-scripts).

## Multi-program support

UTT allows you to include multiple widgets on the same page. Here’s an example:

{% tabs %}
{% tab title="HTML" %}

```html
<script type="text/javascript">
  // Setup configuration
</script>

<impact-embed widget="w/referral-widget"></impact-embed>
<impact-popup widget="w/popup-widget"></impact-popup>
```

{% endtab %}
{% endtabs %}

## Display translated widgets

{% hint style="success" %}
**Note:** To display a translated widget, you must first upload [translated content](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/translate-and-localize-your-advocate-program) for your Advocate program.
{% endhint %}

Translated widget content can be displayed to participants in two ways:

* By including a `locale` attribute with the `impact-embed` web component
* By including a `locale` value on a participant’s user object

For the best participant experience, we recommend including a `locale` attribute with the web component. This `locale` allows you to serve content to the participant according to their browser language. It temporarily overrides any `locale` value on the user object. If a locale value exists on both the user object and in the web component, then the value used in the web component determines which version of the content your participants see.

**Example:**

{% tabs %}
{% tab title="HTML" %}

```html
<impact-embed locale="fr_FR" widget="w/myWidget"></impact-embed>
```

{% endtab %}
{% endtabs %}

## Preload an embedded widget

Reduce load times for participants by preloading an embedded widget in the background.

You can pass a parent container or a query selector to UTT, giving you more control on where and how your widget is loaded within your app. When you pass UTT a container or query selector, the embedded widget is shown via a calling method instead of being displayed when loaded. For example, the widget can be loaded and then shown or hidden as a participant navigates your app, instead of re-rendering.

The widget returned from your call to UTT has `.open()` and `.close()` methods to show or hide itself. Calling '.open()' reveals the widget and can trigger a background refresh. Calling '.close()' hides the widget.

The following example applies to popup and embedded widgets with a container or custom query selector. The code opens the widget as soon as it is available:

{% tabs %}
{% tab title="HTML" %}

```html
<div class="widget-container"></div>
<impact-embed
  widget="w/widget-type"
  container="widget-container"
  open
></impact-embed>
```

{% endtab %}
{% endtabs %}

The example below opens the widget as soon as it's available and closes it after a 5 second delay:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script type="text/javascript">
  document.addEventListener("sqh:widget-loaded", () => {
    setTimeout(() => {
      const widget = document.querySelector("impact-embed");
      widget.close();
    }, 5000);
  });
</script>
<impact-embed widget="w/widget-type" open></impact-embed>
```

{% endtab %}
{% endtabs %}


# SFTP Import Integration for Advocate Programs

The SFTP integration allows you to securely provide impact.com with data for your Advocate program in bulk. You can send us a list of participants to add or delete or provide a list of rewards to redeem.

{% stepper %}
{% step %}

### Enable the integration

1. In your impact.com account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml?).
2. Under *Advocate Settings*, select **Integrations**.
3. On the *SFTP Import Integration* card, select **+ \[Add]** to expand the integration's settings.
4. Select **Enable SFTP Import Integration**.
   {% endstep %}

{% step %}

### Generate an SSH key

An SSH key is used to authenticate the integration. Both `RSA` and `ED25519` SSH keys are accepted. In these steps we will walk through generating an `ED25519` SSH key using your terminal.

1. Open your terminal.
2. Enter `$ ssh-keygen -t ed25519`.
3. Choose a location in which to save the file, or press **enter** to use the default location. Be careful not to overwrite any existing SSH keys that you may have stored in the default location.

{% hint style="warning" %}
**Important:** Do not enter a passphrase when prompted to “Enter passphrase (empty for no passphrase)”. Instead, press **Enter** to skip this command and then press **Enter** again to confirm.
{% endhint %}

4. **Result**: Two files are created: a private key and a public key. The public key has the file extension `.pub`.
5. In your impact.com account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml?).
6. Under *Advocate Settings*, select **Integrations**.
7. Expand the **SFTP Import Integration** card and enter the public key in the **Public Key** text box.
8. Select **Save**.
   {% endstep %}

{% step %}

### Connect to the SFTP server

Now that you have saved the public half of your SSH key, you'll be able to connect to the Advocate-managed SFTP server.

1. On the SFTP Import Integration card, expand the *Connect to SFTP Server* section.
2. Take note of the host and username information.
3. Authenticate using your private key.
   {% endstep %}

{% step %}

### Upload import files

Once you have made a connection to the Advocate-managed SFTP server, you can use the SFTP server to import data into your Advocate program.

The files must be prefixed with the type of data that the import file contains. Refer to the *Supported file names* section in the integration's settings to view the supported import types and the corresponding file prefixes. You can also download example import files from this section.

{% hint style="success" %}
**Note:** The maximum file size for a data import is 100 MB.
{% endhint %}
{% endstep %}

{% step %}

### Check the status of your import

After uploading a file to the SFTP server, you can check its status from the *File upload history* section. If the status is *Import Job Created*, then the file was successfully uploaded. If the status is *Upload failed*, then you can hover over the error message to read the full text.

Uploaded files may take up to 30 minutes to process. To check whether an import job is complete:

1. In your impact.com account, from the left navigation menu, select ![](/files/hr700haJWzy65lcXmxJk) **Engage → Reporting → Imports & Exports**.
2. Locate your import in the *Imports & Exports* table.
   {% endstep %}
   {% endstepper %}


# Tracking Cookies for Advocate Programs

Advocate uses first-party cookies for *referral attribution*—the process of connecting a referred friend to the customer advocate who made the referral. The cookies are based on UTM parameters passed through the URL. By placing the [UTT](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/implement-with-utt-for-advocate) on your landing page, it is able to read the UTM parameters and create a valid first-party cookie that’s in compliance with all browsers.

## Set up first-party cookies

We recommend that all implementations that make use of our referral cookie adhere to the following instructions to enable usage of first-party cookies:

* Add the UTT to your landing page. This sets the first-party cookie.
* Place the UTT on the signup page where your participants are upserted. This reads the first-party cookie.

Here’s how it works:

1. The UTT reads `_saasquatch` from the URL and stores a first-party cookie on the specified landing page's domain.
2. It automatically sets the cookies field on users during an upsert.
3. It reads the first-party cookie during use of autofill.

## Attribution Preference Hierarchy

As there are several ways to attribute a referred friend to a customer advocate, the connection will always be linked following the below scheme:

1. Explicit inclusion of a `referredByCodes` either via UTT or the REST API will always override any identified cookie.
2. If a referral code is not included directly with a user upsert, then UTT will look for the first-party cookie and make the attribution.
3. If no first-party cookie exists and a third-party cookie is available through a compatible browser, the third-party cookie will be detected and applied.


# JSON Web Tokens (JWTs)

A JSON Web Token, or JWT, is an [open standard](https://tools.ietf.org/html/rfc7519) for securely sharing information as a JSON object. JWTs are small enough to be used in a GET or POST parameter or an HTTP header, and because they are digitally signed, the information inside can be trusted.

JWTs can be generated using a library. Options can be found on [JWT.io](https://jwt.io/#libraries-io) or [GitHub](https://github.com/search?utf8=%E2%9C%93\&q=json+web+token\&type=Repositories\&ref=searchresults).

{% stepper %}
{% step %}

### Collect the data object

Whether you are using a JWT with UTT or the Open Endpoints, you will need to start with the data object that you are trying to sign.

For Advocate implementations, `id` and `accountId` will always be set to the same thing.

{% tabs %}
{% tab title="JSON" %}

```json
{
  "id": "john@example.com",
  "accountId": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "locale": "en_US"
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
**Note:** The `id` and `accountId` fields should be replaced with your own unique identifier for this user. The value used will be dependent on your implementation.
{% endhint %}
{% endstep %}

{% step %}

### Assemble the JWT payload

The JWT payload structures the data trying to be signed in this format:

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "user":{  
    "id": "john@example.com", //This field will be dependent on your implementation
    "accountId": "john@example.com", //This field will be dependent on your implementation
    "firstName": "John",  
    "lastName": "Doe",  
    "email": "john@example.com",  
    "locale": "en_US"  
  }  
}
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Sign the payload

Use your chosen library to build the JWT with the payload, and sign it with your [API key and Auth Token](https://integrations.impact.com/brand-api-reference/readme/authentication).

{% tabs %}
{% tab title="C#" %}

```csharp
// Example uses jose-jwt: https://github.com/dvsekhvalnov/jose-jwt

using System.Collections.Generic;
using System.Text;
using Jose;

namespace JwtExample
{
  class Jwt
  {
    // An example for building a user JWT.
    //   accountSid/authToken - your impact.com API credentials
    //   userId - your unique identifier for this user
    public static string BuildJwt(string accountSid, string authToken, string userId, string email, string firstName, string lastName)
    {
      // Build the user payload. Most fields are optional, but id and accountId are required 
      // and are set to the same value. See the API documentation for more fields that you 
      // can add to your users.
      var userPayload = new Dictionary<string, object>() {
        { "id", userId },           // required
        { "accountId", userId },    // required
        { "firstName", firstName }, // optional
        { "lastName", lastName },   // optional
        { "email", email }          // optional
      };

      // Expiry date is optional, but recommended
      var expiryDate = ((DateTimeOffset)DateTime.UtcNow.Date.AddDays(7)).ToUnixTimeSeconds();

      var payload = new Dictionary<string, object>() {
        { "user", userPayload },
        { "exp", expiryDate }
      };

      var headers = new Dictionary<string, object>() {
        { "typ", "JWT" },
        { "kid", accountSid }
      };

      var byteSecret = Encoding.UTF8.GetBytes(authToken);

      return Jose.JWT.Encode(payload, byteSecret, JwsAlgorithm.HS256, extraHeaders: headers);
    }
  }
}
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
# Example uses ruby-jwt: https://github.com/jwt/ruby-jwt

require "jwt"

# An example for building a user JWT.
#   accountSid/authToken - your impact.com API credentials
#   userId - your unique identifier for this user
def build_jwt(accountSid, authToken, userId, email, firstName, lastName)

  # Build the user payload. Most fields are optional, but id and accountId are required
  # and are set to the same value. See the API documentation for more fields that you
  # can add to your users.
  userPayload = {
    id: userId,            # required
    accountId: userId,     # required
    firstName: firstName,  # optional
    lastName: lastName,    # optional
    email: email,          # optional
  }

  # Expiry date is optional, but recommended
  expiryDate = Time.now.to_i + 7 * 24 * 3600

  payload = {
    user: userPayload,
    exp: expiryDate,
  }

  headers = {
    typ: "JWT",
    kid: accountSid,
  }

  return JWT.encode(payload, authToken, algorithm = "HS256", header_fields = headers)
end
```

{% endtab %}

{% tab title="Java" %}

```java
// Example uses nimbus-jose-jwt: https://bitbucket.org/connect2id/nimbus-jose-jwt/src/master/

import java.time.Duration;
import java.time.Instant;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JOSEObjectType;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.JWSHeader;
import com.nimbusds.jose.crypto.MACSigner;
import com.nimbusds.jwt.JWTClaimsSet;
import com.nimbusds.jwt.SignedJWT;

public class Jwt {

  // An example for building a user JWT.
  //   accountSid/authToken - your impact.com API credentials
  //   userId - your unique identifier for this user
  public static String buildJwt(String accountSid, String authToken, String userId, String email, String firstName, String lastName) {

    // Build the user payload. Most fields are optional, but id and accountId are required.
    // See the API documentation for more fields that you can add to your users.
    final Map<String, Object> userPayload = new HashMap<>();
    userPayload.put("id", userId);           // required
    userPayload.put("accountId", userId);    // required
    userPayload.put("firstName", firstName); // optional
    userPayload.put("lastName", lastName);   // optional
    userPayload.put("email", email);         // optional

    // Expiry date is optional, but recommended
    Date expiryDate = Date.from(Instant.now().plus(Duration.ofDays(7)));

    final JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
      .claim("user", userPayload)
      .expirationTime(expiryDate)
      .build();

    final JWSHeader header = new JWSHeader.Builder(JWSAlgorithm.HS256)
      .type(JOSEObjectType.JWT)
      .keyID(accountSid)
      .build();

    final SignedJWT jwt = new SignedJWT(header, claimsSet);

    try {
      jwt.sign(new MACSigner(authToken));
    } catch (JOSEException e) {
      // This will happen if your secret is shorter than 256 bits.
      // If you are using your impact.com API keys, you won't need to worry about it.
      throw new RuntimeException(e);
    }

    return jwt.serialize();
  }

}
```

{% endtab %}

{% tab title="PHP" %}

```php
// Example uses php-jwt: https://github.com/firebase/php-jwt

use Firebase\JWT\JWT;

// An example for building a user JWT.
//   accountSid/authToken - your impact.com API credentials
//   userId - your unique identifier for this user
function buildJwt($accountSid, $authToken, $userId, $email, $firstName, $lastName)
{
    // Build the user payload. Most fields are optional, but id and accountId are required 
    // and are set to the same value. See the API documentation for more fields that you 
    // can add to your users.
    $userPayload = [
        "id" => $userId,           // required
        "accountId" => $userId,    // required
        "firstName" => $firstName, // optional
        "lastName" => $lastName,   // optional
        "email" => $email,         // optional
    ];
    
    // Expiry date is optional, but recommended
    $now = new DateTime();
    $expiryDate = $now->add(new DateInterval('P7D'))->getTimestamp();

    $payload = [
        "user" => $userPayload,
        "exp" => $expiryDate
    ];
    
    $headers = [
        "typ" => "JWT",
        "kid" => $accountSid
    ];

    return JWT::encode($payload, $authToken, 'HS256', null, $headers);
}
```

{% endtab %}

{% tab title="Python" %}

```python
# Example uses PyJWT: https://github.com/jpadilla/pyjwt/

import time
import jwt

# An example for building a user JWT.
#   accountSid/authToken - your impact.com API credentials
#   userId - your unique identifier for this user
def buildJwt(accountSid, authToken, userId, email, firstName, lastName):

    # Build the user payload. Most fields are optional, but id and accountId are required 
    # and are set to the same value. See the API documentation for more fields that you 
    # can add to your users.
    userPayload = {
        'id': userId,           # required
        'accountId': userId,    # required
        'firstName': firstName, # optional
        'lastName': lastName,   # optional
        'email': email          # optional
    }
    
    # Expiry date is optional, but recommended
    expiryDate = time.time() + 7 * 24 * 3600
    
    payload = {
        'user': userPayload,
        'exp': expiryDate
    }

    headers = {
        'typ': 'JWT',
        'kid': accountSid
    }
    
    return jwt.encode(payload, authToken, algorithm='HS256', headers=headers)
```

{% endtab %}
{% endtabs %}

For other fields that can be included in user objects, visit the [User Upsert API documentation](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user).
{% endstep %}

{% step %}

### Include the JWT with your calls

After creating a JWT, it must be included with all of your calls.

{% tabs %}
{% tab title="UTT" %}
Here’s an example of how a UTT call that includes the JWT would appear:

```javascript
<script>
  window.impactToken = "JWT_GOES_HERE";
</script>

<impact-embed widget="p/program-id/w/referrerWidget"></impact-embed>
```

{% endtab %}

{% tab title="Open Endpoint API Call" %}
For Open Endpoint API calls, the JWT must be included as a header with the key `X-SaaSquatch-User-Token`. cURL uses the `-H` flag to pass an extra header. You may specify any number of extra headers.

{% hint style="success" %}
**Note:** Open Endpoint API calls made from a server should be signed with your API key. Only Open Endpoint calls from a client should be signed with a JWT.
{% endhint %}

```http
curl -X POST 'https://app.referralsaasquatch.com/api/v1/{tenant_alias}/open/account/{accountId}/user/{userId}' \
  -H "X-SaaSquatch-User-Token: {X-SaaSquatch-User-Token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "john@example.com",
    "accountId": "john@example.com",
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Testerson",
    "locale": "en_US",
    "referralCode": "JOHNTESTERSON"
  }'
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}


# Integrate Google Tag Manager with Advocate

This guide outlines the basic steps needed to leverage Google Tag Manager (GTM) to upsert users to your Advocate program. Learn more about [using Google Tag Manager with impact.com](https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/google-tag-manager/introduction).

{% stepper %}
{% step %}

### Load the UTT into Google Tag Manager

Follow the instructions in the [standard GTM pre-integration checklist](https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/google-tag-manager/implementation) for loading the UTT and setting up data layer variables.
{% endstep %}

{% step %}

### Create an Advocate firing trigger

1. In [Google Tag Manager](https://tagmanager.google.com/#/home), go to the *Workplace* screen, then select **Triggers** from the left navigation menu.
2. Select **New** to open the *Trigger Configuration* screen, then select ![](/files/eHosQ7egwdLcFW9kKpVu) **\[Edit]** to choose the base trigger.
3. Select the **Custom Event** trigger type.
4. Enter an **event name**.
5. Select the option to have the trigger fire on **All Custom Events**.
6. Select **Save** at the top right of the window.
   {% endstep %}

{% step %}

### Set up a *user upsert* tag

{% hint style="success" %}
**JWTs are required for user upsert:** To use the User Upsert tag, you must have the ability to generate a JWT on your back-end and pass it through to GTM as a variable. If you can't, then you'll need to use an [API call](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/integrate-google-tag-manager-with-advocate) to upsert the user instead.
{% endhint %}

1. In [Google Tag Manager](https://tagmanager.google.com/#/home), go to the *Workplace* screen, then select **Tags** from the left navigation menu.
2. Select **New** to open the *Tag Configuration screen*, then select **\[Edit]** to choose a tag type.
3. Select **Custom HTML** and paste the following script:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script>
  // 1. When UTT is ready, run the following function.
  window.impactOnReady = function() {
    // 2. Configure UTT for your user and widget.
    //  The information provided here is used to track your user and register them in your Advocate program.
    //  This request is authenticated via JWT.
    //  A note about generating JWTs:
    //    JWTs are tokens that are signed with your tenant API key. They must be generated server-side.
    //    To ensure the security of your tenant and program, do not expose your tenant API key to your frontend.
    //    For more information see https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/json-web-tokens-jwts
    var userConfig = {
      // 2b. Add details about your user.
      //  This must include id and accountId but other fields such as email, firstName, locale,
      //  or even custom fields can be included.
      //  For more details and a list of user fields see https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/advocate-installation-scripts
      user: {
        id: '{{email}}',
        accountId: '{{email}}',
        locale: 'en_US',
        cookies: '{{advocate}}'
      },
      // 2c. Add your generated JWT here to authenticate your request.
      jwt: '{{jwt}}'
    };

    // 3. Make the request to upsert your user and render your widget.
    impact.api().upsertUser(userConfig).then(function(response) {
      // The widget API automatically inserts the HTML for your widget into your page via an iFrame.
      // However if needed, you can retrieve details about the upserted user and the widget HTML
      // through this function response.
      var user = response.user;
      console.log(user);
      window.dataLayer.push({'event': 'user upserted'});
    }).catch(function(error) {
      console.log(error);
    });
  };
</script>
```

{% endtab %}
{% endtabs %}

4. Expand the **Advanced Settings**.
5. From the *Tag Firing Options* dropdown list, select **Once per event**.
6. Expand the **Tag Sequencing** section.
7. Select the check box for **Fire a tag before Upsert User fires**.
8. From the *Setup tag* dropdown list, select **UTT**.
9. In the *Triggering* section, select the **Advocate** trigger.
10. Select **Save** at the top right of the window.

#### (Optional) Set up an *API upsert* tag <a href="#api-upsert" id="api-upsert"></a>

Follow the steps above and substitute this script **only** if you're unable to generate a JWT and pass it as a variable to GTM.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script>
  var username = '{{username}}';     // Replace with your username
  var password = '{{password}}';     // Replace with your password
  var tenantAlias = '{{tenantalias}}';
  var email = '{{email}}';

  var url = 'https://app.referralsaasquatch.com/api/v1/' + tenantAlias + '/open/account/' + email + '/user/' + email;

  var headers = new Headers();
  headers.set('Authorization', 'Basic ' + btoa(username + ':' + password));
  headers.set('Content-Type', 'application/json');

  var userObject = {
    id: '{{email}}',
    accountId: '{{email}}',
    cookies: '{{advocate}}'
  };

  fetch(url, {
    method: 'PUT',
    headers: headers,
    body: JSON.stringify(userObject)
  })
  .then(function(response) {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    console.log(response.body);
    console.log('upserted via API');
  });
</script>
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Set up a tag for the `identify` and `trackConversion` functions

Follow the `identify` function and `trackConversion` function sections of the [standard Pre-Integration Checklist](https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/google-tag-manager/implementation) for instructions.
{% endstep %}
{% endstepper %}

#### Next steps

Now that your setup is complete, learn how to publish the [GTM container](https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/google-tag-manager/final-steps).


# End-to-End Testing for Advocate

We recommend testing your Advocate program end-to-end to confirm that participants are being correctly registered in impact.com and rewarded for successful referrals.

The basic E2E testing steps are applicable to most Advocate implementations: create a customer advocate, refer a friend through the advocate, then confirm that the referral and reward were correctly tracked. If you have a more complex implementation, reach out to [support](https://app.impact.com/support/portal.ihtml?createTicket=true) for assistance.

{% hint style="warning" %}
**important:** If you're rewarding cash and you complete the tax interview and provide your banking details as part of testing, you will receive a reward and a processing fee for the reward will be applied.
{% endhint %}

## Prerequisites

Before beginning E2E testing, your Advocate program must be fully set up. Make sure that:

* The basic setup steps for your tracking integration—such as Shopify, Salesforce, HubSpot, or UTT—are complete.
* The conversion event you send to impact.com includes the `customerEmail` field.
* Program rules and rewards have been configured in your impact.com account.
* Program touchpoints—including widgets or microsites—have been added to your website or landing page (as required).

## End-to-End Test

{% stepper %}
{% step %}

### Create a test customer advocate

1. This process will depend on how you've implemented with impact.com.
2. Through the website referral widget, register using a unique email address that is not already registered in your program.
3. Copy and store the share link for the test customer advocate.
4. In your impact.com account, from the left navigation menu, select ![](/files/hr700haJWzy65lcXmxJk) **Engage → Participants**. Check that the customer advocate appears in the list.

<div data-with-frame="true"><figure><img src="/files/rG8CxaQXNnJdLBrFvdhm" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Start a new referral

We recommend completing this step in an incognito or private browser window. Existing cookies stored in your browser might alter your test results.

1. In an incognito or private browser window, load the share link you copied from the test customer advocate.
2. Confirm that your landing page URL loads with the following referral URL parameters: `_saasquatch` and `rsCode`.

{% tabs %}
{% tab title="Example" %}

```
example.com/landing-page?utm_source=xxxx&utm_medium=xxxx&utm_campaign=saasquatch&rsCode=xxxxxx&rsShareMedium=xxxx&rsEngagementMedium=xxxx&_saasquatch=xxxxx
```

{% endtab %}
{% endtabs %}

3. In your impact.com account, check that the referred friend was registered correctly.
   1. From the left navigation menu, select ![](/files/hr700haJWzy65lcXmxJk) **Engage → Participants**.
   2. Confirm that the test referred friend appears in the list.
   3. Select their name to open their participant profile.
   4. In the *Referral Info* section at the top, confirm that the test customer advocate is listed in the *Referred By* field.

<div data-with-frame="true"><figure><img src="/files/K3OXYf35lqYf65ijztj3" alt=""><figcaption></figcaption></figure></div>

4. Optionally, if your program rules are set up to send an email to the customer advocate when a referred friend signs up, check that the email was received.
   {% endstep %}

{% step %}

### Convert the referral

The process for converting the referral varies depending on your tracking integration with impact.com. If you don't see your integration in this list, reach out to your impact.com-assigned Implementation Engineer for help.

* **Shopify**: Complete a purchase.
* **HubSpot:** Change the referred friend's Deal stage to *Closed Won*.
* **Salesforce:** Convert the referred friend's *Lead* to an *Opportunity*. Then mark the *Opportunity* as *Closed Won*.
* **JavaScript UTT:** Complete a purchase or action that will trigger the `trackConversion` function.
  {% endstep %}

{% step %}

### Confirm the conversion in impact.com

Confirm that the conversion event is logged for the referred user. Events typically take 5-10 minutes to process.

1. From the left navigation menu, select ![](/files/hr700haJWzy65lcXmxJk) **Engage → Participants**.
2. Select the referred friend's name from the list to open their profile.
3. In the *Events* section at the bottom, use the ![](/files/JiWIbPyMoIeWpNy8h0ba) **\[Drop-down list]** to select your conversion event. Make sure that the test conversion appears.

   <div data-with-frame="true"><img src="https://files.readme.io/0e260e99ed89a4bbb6ae12ca06c8943aaf276ab2a8d345975b5f476b868ec942-Screenshot_2025-04-22_at_18.10.47.png" alt="A conversion event appears on Russel Sprout&#x27;s participant profile"></div>
4. Confirm that the test customer advocate and test referred friend received any emails, in alignment with your program rules.
   {% endstep %}

{% step %}

### Confirm that rewards were issued

Check that your program issued rewards for this conversion, as defined by your program rules.

1. From the left navigation menu, select ![](/files/hr700haJWzy65lcXmxJk) **Engage → Participants**.
2. Select the test customer advocate's name to open their participant profile.
3. In the *Rewards* section, make sure the customer advocate received their reward.
4. If your program rules also reward the referred friend, check their profile as well.
   {% endstep %}

{% step %}

### Remove your test data in impact.com

Finally, we recommend removing the test data in impact.com.

1. Mark the event you sent to impact.com [as a test](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/referrals-and-events/mark-an-event-as-a-test-for-advocate).
2. [Cancel the unredeemed reward](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-rewards/manage-existing-rewards#cancel-an-unredeemed-reward).
3. [Delete the referral](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/referrals-and-events/delete-a-referral) in the referral feed.
4. [Delete the test participant](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/delete-participants-from-your-advocate-program).
   {% endstep %}
   {% endstepper %}


# Mobile Options for Advocate


# Mobile Options for Advocate Programs

Advocate helps you grow your mobile app with a referral program. We provide mobile widgets to engage your customer advocates and their referred friends; attribution to track referrals; and analytics to measure the success of your program.

<p align="center"><img src="https://files.readme.io/9b083f7-logo-android.png" alt=""><br></p>

Our *Android SDK* gives you complete control over how your referral program is presented inside your Android app.

**Go to** [**Android SDK**](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/android-sdk-overview)**.**

<p align="center"><img src="https://files.readme.io/1fbc42b-logo-ios.png" alt=""><br></p>

Our *iOS SDK* gives you complete control over how your referral program is presented inside your iOS app.

**Go to** [**iOS SDK**](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/ios-sdk-overview)**.**

<p align="center"><img src="https://files.readme.io/600bfba-logo_branch_io.png" alt=""><br></p>

Our *Branch Metrics* integration lets you personalize the onboarding experience of new users who use their phone.

**Go to** [**Branch Metrics integration**](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/branch-metrics-for-advocate/integrate-with-branch-for-advocate-programs)**.**

<div align="center"><img src="https://files.readme.io/4a11a2a-appsflyerLogo.png" alt="AppsFlyer logo"></div>

Our *AppsFlyer* integration lets you incorporate deeplinking into your mobile apps.

**Go to** [**Appsflyer**](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/appsflyer-for-advocate/integrate-with-appsflyer-for-advocate-programs) **integration.**


# iOS SDK Overview

The Advocate iOS SDK gives you complete control of the look and feel of your Advocate program on mobile devices. With options for both Swift and Objective-C programming languages, the iOS SDK provides the flexibility to work directly with the data from your program and display it in your mobile app.

With our SDK, you can register your users with Advocate, track their referrals, and fetch user information like referral codes, referral links, and rewards.

Our mobile SDK has been designed to be part of a hybrid mobile device implementation. Client-side SDK elements are used in conjunction with server-side REST API functionality for the most complete, and secure, solution.

The nature of the hybrid combination of mobile client and server for our SDK means that there are certain limitations to be aware of. Please read through the documentation for the SDK carefully to understand the capabilities of the SDK.

{% hint style="success" %}
**Note**: The mobile SDK does not currently support payment provider programs.
{% endhint %}

## Next Steps

Our [iOS SDK](https://github.com/saasquatch/squatch-ios/blob/main/README.md) provides a walkthrough of installing the iOS SDK as well as detailed explanations of common usage cases with code examples.

## Additional Resources

Our SDK can also be used with our [Branch integration](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/branch-metrics-for-advocate/integrate-with-branch-for-advocate-programs) to provide an exceptional first-time user experience with a personalized landing page.

The GitHub repositories for the iOS SDK framework for [Swift](https://github.com/saasquatch/squatch-ios) are also available for reference.

We also have a [Sample App](https://github.com/saasquatch/squatch-ios/tree/main/Example) to help you get started.


# Android SDK Overview

The Advocate Android SDK gives you complete control of the look and feel of your referral program on mobile devices. The Android SDK provides the flexibility to work directly with the data from your program and display it in your mobile app.

With our SDK, you can register your users with Advocate, track their referrals, and fetch user information like referral codes, referral links, and rewards.

Our mobile SDK has been designed to be part of a hybrid mobile device implementation. Client-side SDK elements are used in conjunction with server-side REST API functionality for the most complete, and secure, solution.

The nature of the hybrid combination of mobile client and server for our SDK means that there are certain limitations to be aware of. Please read through the documentation for the SDK carefully to understand the capabilities of the SDK.

{% hint style="success" %}
**Note**: The mobile SDK does not currently support payment provider programs.
{% endhint %}

## Next Steps

Our [Android SDK](https://github.com/saasquatch/squatch-android) provides a walkthrough of installing the Android SDK as well as detailed explanations of common usage cases with code examples.

## Additional Resources

Our SDK can also be used with our [Branch integration](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/branch-metrics-for-advocate/integrate-with-branch-for-advocate-programs) to provide an exceptional first-time user experience with a personalized landing page.

The GitHub repository for the [Android SDK](https://github.com/saasquatch/squatch-android) is also available for reference.

We also have a [Java SDK](https://github.com/saasquatch/saasquatch-java-sdk) to provide additional context.


# AppsFlyer for Advocate

AppsFlyer is a mobile marketing analytics and attribution platform. Advocate integrates with AppsFlyer to provide a better user experience, additional attribution and personalization, and more robust analytics by using AppsFlyer's OneLink attribution links.

## Key features

* Improve all aspects of your mobile app referral experience—downloading, installing, and sharing.
* Seamlessly direct referred friends on mobile to download your app.
* Automatically generated App Links (for Android) and Universal Links (for iOS).
* Track referred friends through the app store using AppsFlyer deep linking data.


# Integrate with AppsFlyer for Advocate Programs

{% hint style="info" %}
**Tip:** We recommend testing your AppsFlyer integration on a mobile device, not a desktop, to ensure you see the most accurate and updated information.
{% endhint %}

{% stepper %}
{% step %}

### Activate Advocate as an integrated partner

Advocate is an AppsFlyer Integrated Partner (partner id: `saasquatch_int`). To begin, you must activate the partner integration from your dashboard.

1. Open your [AppsFlyer dashboard](https://hq1.appsflyer.com/).
2. Select **Integrated Partners** from the left sidebar menu.
3. Search for the code `SaaSquatch`.
4. Select the `SaaSquatch` partner and enable the **Activate Partner** toggle.
5. Select **Save Integration**.
   {% endstep %}

{% step %}

### Create a OneLink template and link

Follow AppsFlyer's documentation to create a:

* [OneLink template](https://support.appsflyer.com/hc/en-us/articles/207032246-OneLink-templates)
* [OneLink link](https://support.appsflyer.com/hc/en-us/articles/208874366-OneLink-links-and-experiences)

After creating the OneLink link:

1. Copy the Long or Short URL.
2. Replace **"CHANGEME"** in the link with **"saasquatch\_int"**. This is the URL you will add to your Advocate program's integration settings.

For example, if your Long URL is:

```
https://my-one-link-for-saasquatch.onelink.me/JFlJ?pid=CHANGEME&c=MyCampaign
```

You will need to use the following URL in your Advocate program:

```
https://my-one-link-for-saasquatch.onelink.me/JFlJ?pid=saasquatch_int&c=MyCampaign
```

{% endstep %}

{% step %}

### Set up the AppsFlyer integration in impact.com

1. In your impact.com account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile]** → [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml?).
2. Under *Advocate Settings*, select **Integrations**.
3. On the AppsFlyer integration card, select **+ \[Expand]**.
4. Select **Enable AppsFlyer**.
5. Add your modified Long or Short URL into the **AppsFlyer Base Attribution Link** field.
6. **Save** the integration configuration.

You are now set up to use AppsFlyer with your Advocate program.
{% endstep %}

{% step %}

### Update your Mobile App

To access the AppsFlyer deep linking data from within your mobile application, you will need to install the AppsFlyer SDK. The [AppsFlyer documentation](https://dev.appsflyer.com/hc/docs/getting-started) contains all the steps required to get their SDK setup on your application.

Once set up, you can retrieve the deep link data from AppsFlyer. This data contains information about the referral and can be used to attribute the referral and customize the signup experience for new users.

AppsFlyer may add other parameters depending on how your OneLink is configured. The most important parameter for your referral program is `_saasquatch` (or the equivalent `deep_link_sub1`, if you are using Unified Deep Linking). It contains the referral code and share link used for the referral, and is needed for attributing the referral. For more detail on data fields and behavior, refer to the [AppsFlyer technical reference](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/appsflyer-for-advocate/appsflyer-for-advocate-technical-reference).

Here is an example of the referral program data that will be appended to the AppsFlyer OneLink:

{% tabs %}
{% tab title="JSON" %}

```json
{  
  "pid": "saasquatch_int",  
  "c": "saasquatch",  
  "af_web_dp": "http://myReferralLandingPage.com",  
  "deep_link_sub1": "eyJhcHAucmVmZXJyYWxzYWFzcXVhdGNoLmNvbSI6eyJ0ZXN0XzEyMzQ1NjdfQ09ERSI6eyJjb2RlcyI6eyJyZWZlcnJhbCI6IlJFRkVSUkFMQ09ERSJ9LCJjb2Rlc0V4cCI6eyJSRUZFUlJBTENPREUiOjE2Mjk1ODIxOTl9LCJsaW5rcyI6eyJyZWZlcnJhbCI6Imh0dHBzOi8vc3NxdC5jby9temFBMjIifSwibGlua3NFeHAiOnsiaHR0cHM6Ly9zc3F0LmNvL216YUEyMiI6MTYyOTU4MjE5OX19fX0=",  
  "deep_link_sub2": "invite",  
  "deep_link_sub3": "link",  
  "deep_link_sub4": "saasquatch",  
  "deep_link_sub5": "REFERRALCODE",  
  "deep_link_sub6": "UNKNOWN",  
  "deep_link_sub7": "UNKNOWN"  
}
```

{% endtab %}
{% endtabs %}

### Unified Deep Linking on iOS

Prior to implementing deep linking in your mobile application, be sure to follow the AppsFlyer [iOS SDK initial setup documentation](https://dev.appsflyer.com/hc/docs/dl_ios_init_setup) to initialize and implement the SDK in your application and read their [iOS developer documentation](https://dev.appsflyer.com/hc/docs/ios-sdk) for general information on setting up deep linking within your application.

Once you have followed the [steps to set up unified deep linking](https://dev.appsflyer.com/hc/docs/dl_ios_unified_deep_linking) and configured the AppsFlyer integration in Advocate, referral information will be available in the `deep_link_sub1` through `deep_link_sub7` params. Below is a modified code example showing how to extract the `_saasquatch` cookie from the DeepLink data.

{% tabs %}
{% tab title="Swift" %}

```swift
func application(\_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {  
  ...  
  AppsFlyerLib.shared().deepLinkDelegate = self  
  ...  
}

// For Swift version < 4.2 replace function signature with the commented out code  
// func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool { // this line for Swift \< 4.2  
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {  
  AppsFlyerLib.shared().continue(userActivity, restorationHandler: nil)  
  return true  
}

// Open URI-scheme for iOS 9 and above  
func application(\_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {  
  AppsFlyerLib.shared().handleOpen(url, options: options)  
  return true  
}

extension AppDelegate: DeepLinkDelegate {  
    func didResolveDeepLink(\_ result: DeepLinkResult) {
    switch result.status {
    case .notFound:
        NSLog("[AFSDK] Deep link not found")
        return
    case .failure:
        print("Error %@", result.error!)
        return
    case .found:
        NSLog("[AFSDK] Deep link found")
    }

    guard let deepLinkObj:DeepLink = result.deepLink else {
        NSLog("[AFSDK] Could not extract deep link object")
        return
    }

    if deepLinkObj.clickEvent.keys.contains("deep_link_sub1") {
        let saasquatchCookie:String = deepLinkObj.clickEvent["deep_link_sub1"] as! String
        NSLog("[AFSDK] AppsFlyer: _saasquatch param: \(saasquatchCookie)")
    } else {
        NSLog("[AFSDK] Could not extract _saasquatch param")
    }

    let deepLinkStr:String = deepLinkObj.toString()
    NSLog("[AFSDK] DeepLink data is: \(deepLinkStr)")

    if( deepLinkObj.isDeferred == true) {
        NSLog("[AFSDK] This is a deferred deep link")
    }
    else {
        NSLog("[AFSDK] This is a direct deep link")
    }

    // ...
  }
}
```

{% endtab %}
{% endtabs %}

### Unified Deep Linking on Android

Prior to implementing deep linking in your mobile application, be sure to follow the AppsFlyer [Android SDK initial setup documentation](https://dev.appsflyer.com/hc/docs/dl_android_init_setup) to initialize and implement the SDK in your application and read their [Android developer documentation](https://dev.appsflyer.com/hc/docs/android-sdk) for general information on setting up deep linking within your application.

Once you have followed the [steps to set up unified deep linking](https://dev.appsflyer.com/hc/docs/dl_android_unified_deep_linking) and configured the Appsflyer integration in Advocate, referral information will be available in the `deep_link_sub1` through `deep_link_sub7` params. Below is a modified code example showing how to extract the `_saasquatch` cookie from the DeepLink data.

{% tabs %}
{% tab title="Java" %}

```java
appsflyer.subscribeForDeepLink(new DeepLinkListener() {
  @Override
  public void onDeepLinking(@NonNull DeepLinkResult deepLinkResult) {
    DeepLinkResult.Status dlStatus = deepLinkResult.getStatus();
    if (dlStatus == DeepLinkResult.Status.FOUND) {
      Log.d(LOG_TAG, "Deep link found");
    } else if (dlStatus == DeepLinkResult.Status.NOT_FOUND) {
      Log.d(LOG_TAG, "Deep link not found");
      return;
    } else {
      // dlStatus == DeepLinkResult.Status.ERROR
      DeepLinkResult.Error dlError = deepLinkResult.getError();
      Log.d(LOG_TAG, "There was an error getting Deep Link data: " + dlError.toString());
      return;
    }

    DeepLink deepLinkObj = deepLinkResult.getDeepLink();
    try {
      Log.d(LOG_TAG, "The DeepLink data is: " + deepLinkObj.toString());
    } catch (Exception e) {
      Log.d(LOG_TAG, "DeepLink data came back null");
      return;
    }

    // An example for using is_deferred
    if (deepLinkObj.isDeferred()) {
      Log.d(LOG_TAG, "This is a deferred deep link");
    } else {
      Log.d(LOG_TAG, "This is a direct deep link");
    }

    if (deepLinkObj.has("deep_link_sub1")) {
      String _saasquatch = deepLinkObj.getStringValue("deep_link_sub1");
      Log.d(LOG_TAG, "The SaaSquatch cookie is: " + _saasquatch);
    } else {
      Log.d(LOG_TAG, "deep_link_sub1/_saasquatch not found");
    }

    // ...
  }
});
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}


# AppsFlyer for Advocate — Technical Reference

Your Advocate program can integrate with AppsFlyer.

This technical reference explains the specific fields, features, and functionality that is used in the integration. Just getting started? Learn how to [integrate AppsFlyer with Advocate](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/appsflyer-for-advocate/integrate-with-appsflyer-for-advocate-programs).

## Link handling behaviors

After the AppsFlyer integration is configured, link-handling behaviors will change.

Advocate will create AppsFlyer links dynamically by passing custom attribution parameters to the link provided in your AppsFlyer configuration. Data is passed using the `deep_link_sub1` through `deep_link_sub7` URL parameters. You can use `deep_link_sub1` or `_advocate` (depending on your deep linking) to attribute referrals, and the other parameters to customize the mobile landing experience.

We will redirect all link clicks through AppsFlyer. Mobile users will be directed by AppsFlyer according to your OneLink configuration and desktop users will be directed to the landing page URL you configured for your referral program. Advocate passes this URL through the `af_web_dp` parameter. If you set the value for `af_web_dp` in AppsFlyer it will overwrite the value configured for your referral program.

{% hint style="warning" %}
**Important:** If you have both Branch Metrics and AppsFlyer integrations enabled, share links will still be redirected to AppsFlyer links. However, the Branch deep link will be passed to the AppsFlyer integration instead of your landing page link. In effect, both integrations are applied—Branch first, then AppsFlyer.
{% endhint %}

## Data fields <a href="#data-fields" id="data-fields"></a>

| Field            | Type   | Description                                                                                                                                                                                                                                                                 |
| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pid`            | string | Media source, set as `saasquatch_int` in AppsFlyer when configuring your custom attribution link.                                                                                                                                                                           |
| `c`              | string | Campaign name, set as `saasquatch` in AppsFlyer when configuring your custom attribution link.                                                                                                                                                                              |
| `af_web_dp`      | string | The URL where desktop users will be redirected. Set this as the landing page for your Advocate program in impact.com. Do not configure a value for this parameter when creating your custom link in AppsFlyer.                                                              |
| `deep_link_sub1` | string | The Base64URL encoded attribution cookie values. This is necessary to attribute the referral. When decoded, the schema will resemble the following: `{"app.referralsaasquatch.com": {"tenantAlias_CODE": {"codes": {"program1": "CODE1"},"codesExp": {"CODE1": 1234567}}}}` |
| `deep_link_sub2` | string | Google Analytics-compatible traffic source identifier.                                                                                                                                                                                                                      |
| `deep_link_sub3` | string | Google Analytics-compatible advertising or marketing medium.                                                                                                                                                                                                                |
| `deep_link_sub4` | string | Google Analytics-compatible campaign name.                                                                                                                                                                                                                                  |
| `deep_link_sub5` | string | The customer advocate's referral code.                                                                                                                                                                                                                                      |
| `deep_link_sub6` | string | The medium through which the customer advocate shared their referral (e.g. Facebook share button).                                                                                                                                                                          |
| `deep_link_sub7` | string | The medium from which the customer advocate engaged with the referral program (e.g. embedded widget).                                                                                                                                                                       |

## Example Deep Link <a href="#example-deep-link" id="example-deep-link"></a>

When Advocate creates links dynamically in AppsFlyer, the link and its custom attribution parameters will look similar to the following example.

{% tabs %}
{% tab title="JSON" %}

```json
{
  "pid": "saasquatch_int",
  "c": "saasquatch",
  "af_web_dp": "http://myReferralLandingPage.com",
  "utm_source": "invite",
  "utm_medium": "link",
  "utm_campaign": "saasquatch",
  "rsCode": "REFERRALCODE",
  "rsShareMedium": "UNKNOWN",
  "rsEngagementMedium": "UNKNOWN",
  "_saasquatch": "eyJhcHAucmVmZXJyYWxzYWFzcXVhdGNoLmNvbSI6eyJ0ZXN0XzEyMzQ1NjdfQ09ERSI6eyJjb2RlcyI6eyJyZWZlcnJhbCI6IlJFRkVSUkFMQ09ERSJ9LCJjb2Rlc0V4cCI6eyJSRUZFUlJBTENPREUiOjE2Mjk1ODIxOTl9LCJsaW5rcyI6eyJyZWZlcnJhbCI6Imh0dHBzOi8vc3NxdC5jby9temFBMjIifSwibGlua3NFeHAiOnsiaHR0cHM6Ly9zc3F0LmNvL216YUEyMiI6MTYyOTU4MjE5OX19fX0="
}
```

{% endtab %}
{% endtabs %}


# Branch Metrics for Advocate

Branch Metrics is a free mobile attribution platform. Advocate integrates with Branch Metrics to provide a better user experience, additional attribution and personalization, and more robust analytics by using Branch's deep links.

## Key Features

* Improve all aspects of your mobile app referral experience—downloading, installing, and sharing.
* Seamlessly direct referred friends on mobile to download your app.
* Automatically generated App Links (for Android) and Universal Links (for iOS).
* Track referred friends through the app store using Branch Deep Linking data.


# Integrate with Branch for Advocate Programs

{% stepper %}
{% step %}

### Configure Branch

A Branch Metrics account is needed in order to integrate the Branch functionality into your referral program.

#### Create an account

Branch is a free platform. If you don't have a Branch account yet, you can sign up for one for free from [branch.io](https://branch.io/). All that's required is a valid email account.

#### Configure redirects

1. Go to your Branch dashboard.
2. Under the *Channels & Links* heading in the left sidebar, select **Link Settings**.
3. Configure Redirects for all the platforms where you have an app. Leave the **Custom landing page for desktop** field empty, as that will be set in your impact.com Advocate program.

<div data-with-frame="true"><figure><img src="/files/ZIh2jC8d6cVkkz5IFN79" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Connect Branch with Advocate

1. Retrieve the Branch Key from the Account Settings tab of the Setup & Testing section inside of [your Branch dashboard](https://dashboard.branch.io/).
2. In your impact.com account, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml?).
3. Under *Advocate Settings*, select **Integrations**.
4. On the Branch integration card, select **+ \[Add]** to open the integration's settings.
5. Paste your Branch Key into the **Branch API Key** field.
6. Select **Connect**.
   {% endstep %}

{% step %}

### Update your mobile app

To access the Branch deep link data in your app, you need to install the Branch SDK into your mobile apps. [Branch's documentation](https://help.branch.io/developers-hub/docs/native-sdks-overview) includes a full walk-through of everything you need to do to add the SDK to an app.

Once you’ve got your app set up, you'll be able to retrieve the deep link data from Branch when your app is opened. This data contains information about the referral. You can use this data to customize the login/signup experience for new participants.

Here is an example of referral program [keys and values](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/branch-metrics-for-advocate/branch-for-advocate-technical-reference) from the Branch deep link data:

{% tabs %}
{% tab title="JSON" %}

```json
{
  "code": "BRITTANYTEST2",
  "$desktop_url": "http://landingpage.com/a/test_a6whcgrt0vcw3/widgets/referral?code=BRITTANYTEST&referralMedium=DIRECT&referralSource=STANDARD",
  "sq_accountId": "55a43496ebbaff9cf86443d3",
  "sq_amount": "10",
  "sq_firstName": "Brittany",
  "sq_id": "55a43496ebbaf01cebac42cb",
  "sq_imageUrl": "http://gravatar.com/avatar/77af7eba41d1ccad2bf2c13704637c25?d=mm",
  "sq_lastName": "Test",
  "sq_referralCode": "BRITTANYTEST2",
  "sq_type": "PCT_DISCOUNT",
  "sq_unit": "PERCENT",
  "~channel": "DIRECT",
  "~tags": ["STANDARD"],
  "~creation_source": "API",
  "+is_first_session": false,
  "+clicked_branch_link": true
}
```

{% endtab %}
{% endtabs %}

The most important value there is `sq_referralCode`. That's the one you need to attribute the referral. This way you know who brought the referred friend to your product.

For a full technical reference of data fields and behavior, refer to our Branch Metrics [technical reference](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/branch-metrics-for-advocate/branch-for-advocate-technical-reference).

#### Deep linking on iOS

* Follow the [Branch iOS SDK Integration Guide](https://help.branch.io/developers-hub/docs/native-sdks-overview) to set up your app for use with Branch.
* Familiarize yourself with the Branch [Deep Link Routing Guide](https://help.branch.io/developers-hub/docs/in-app-routing). The following setup steps are based on this document.

**Start a Branch Session**

To configure a View Controller to accept deep links, open the view controller that you want to appear when a participant clicks a link.

Import the Branch framework:

{% tabs %}
{% tab title="Swift" %}

```swift
import Branch
```

{% endtab %}
{% endtabs %}

Register your view controller for the delegate `BranchDeepLinkController`:

{% tabs %}
{% tab title="Swift" %}

```swift
class ExampleDeepLinkingController: UIViewController, BranchDeepLinkingController {
```

{% endtab %}
{% endtabs %}

Receive the delegate method that will be called when the view controller is loaded from a link click:

{% tabs %}
{% tab title="Swift" %}

```swift
func configureControl (withData params: [AnyHashable: Any]!) 
{  
   let dict = params as Dictionary  
   if dict["sq_referralCode"] != nil {  
       // there is a referral code, the user was referred, do action  
   }  
}
```

{% endtab %}
{% endtabs %}

Since the view controller is displayed modally, you should add a close button:

{% tabs %}
{% tab title="Swift" %}

```swift
var deepLinkingCompletionDelegate: BranchDeepLinkingControllerCompletionDelegate?  
func closePressed() {  
   self.deepLinkingCompletionDelegate!.deepLinkingControllerCompleted()  
}
```

{% endtab %}
{% endtabs %}

**Handle Incoming Links**

You now need to tell Branch about the view controller you just configured, and which key it is using from the link’s data dictionary.

In your AppDelegate.swift file, find this method inside `didFinishLaunchingWithOptions` (you would have added it in the [SDK Guide](https://help.branch.io/developers-hub/docs/native-sdks-overview)):

{% tabs %}
{% tab title="Swift" %}

```swift
branch.initSession(launchOptions: launchOptions, deepLinkHandler: { params, error in
  if error == nil {
    // params are the deep linked params associated with the link that the user clicked -> was re-directed to this app
    // params will be empty if no data found
    // ... insert custom logic here ...
    print("params: %@", params.description)
  }
})
```

{% endtab %}
{% endtabs %}

Remove it, and insert this snippet in the same place:

{% tabs %}
{% tab title="Java" %}

```java
var controller = UIStoryboard.init("Main", NSBundle.mainBundle()).instantiateViewControllerWithIdentifier("DeepLinkingController") branch.registerDeepLinkController(controller, forKey: "sq_referralCode")  
branch.initSession(launchOptions: launchOptions, automaticallyDisplayDeepLinkController: true)
```

{% endtab %}
{% endtabs %}

Now whenever your app launches from a Branch link that has the `sq_referralCode` key set in its data dictionary, the `ExampleDeepLinkingController` view controller will be displayed.

**Example \[Swift]**

The following example makes use of the Branch SDK to perform custom logic if the participant that opened the app was referred.

Inside the `andRegisterDeepLinkHandler` callback in your AppDelegate, you will want to examine the params dictionary to determine whether the participant followed a referral link.

{% tabs %}
{% tab title="Swift" %}

```swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  let branch: Branch = Branch.getInstance()
  branch.initSession(launchOptions: launchOptions, deepLinkHandler: { params, error in
    // If the key 'sq_referralCode' is present in the deep link dictionary
    if error == nil && params["+clicked_branch_link"] != nil && params["sq_referralCode"] != nil {
      // user was referred, perform custom logic
      referralCode = params["sq_referralCode"]
    } else {
      // user was not referred, load your normal view
    }
  })
  return true
}
```

{% endtab %}
{% endtabs %}

**Next Steps**

With access to the Branch deep linking data (like referral code) you know that the participant was referred. You can use this information when the participant is signing up.

If the referred friend needs a reward applied at signup use the `sq_amount` amount to determine what their reward should be.

Use the referral code `sq_referralCode` to attribute the referral when you identify the participant to impact.com. This can be done using the mobile widget or Mobile SDK.

#### Deep Linking on Android

* Follow the [Branch Android SDK Integration Guide](https://help.branch.io/developers-hub/docs/android-sdk-overview) to setup your app for use with Branch.
* Familiarize yourself with the Branch [Deep Link Routing Guide](https://help.branch.io/developers-hub/docs/in-app-routing). The following setup steps are based on this document.

**Start a Branch Session**

A Branch session needs to be started each time the app opens. We check to see if the participant came from a Branch link and if so, the callback method returns any deep link parameters for that link.

{% tabs %}
{% tab title="Java" %}

```java
Branch branch = Branch.getInstance(getApplicationContext());  
branch.initSession(new Branch.BranchReferralInitListener() {  
    @Override  
    public void onInitFinished(JSONObject referringParams, BranchError error) {
// TODO: Store this code in the current session, to connect attribution post-signup (see next step)
String referralCode = referringParams.getString("sq_referralCode");
}
});
```

{% endtab %}
{% endtabs %}

**Example \[Android]**

The following example makes use of the Branch SDK to customize the login/signup experience for new users.

{% tabs %}
{% tab title="Java" %}

```java
@Override  
public void onStart() {  
    super.onStart();
Branch branch = Branch.getInstance(getApplicationContext());
branch.initSession(new Branch.BranchReferralInitListener() {
    @Override
    public void onInitFinished(JSONObject referringParams, BranchError error) {
        if (error == null) {
            // params are the deep linked params associated with the link that the user clicked before showing up
            Log.i("BranchConfigTest", "deep link data: " + referringParams.toString());

            if (referringParams.has("sq_firstName")) {
                try {
                    //setup referrer name
                    TextView referrerName = (TextView) findViewById(R.id.referrer_name);
                    String displayText = referringParams.getString("sq_firstName") + " " 
                        + referringParams.getString("sq_lastName");
                    displayText += " recommends that you try Example App.";
                    referrerName.setText(displayText);

                    //setup referrer image
                    WebView referrerImage = (WebView) findViewById(R.id.referrer_image);
                    referrerImage.loadUrl(referringParams.getString("sq_imageUrl"));

                    //setup referral reward
                    String rewardText = "You'll get $" + referringParams.getString("sq_amount") +
                        " credit for signing up!";
                    TextView reward = (TextView) findViewById(R.id.reward);
                    reward.setText(rewardText);
                } catch (JSONException e) {
                    e.printStackTrace();
                }
            }
        }
    }
}, this.getIntent().getData(), this);
  }
```

{% endtab %}
{% endtabs %}

**Next Steps**

With access to the Branch deep linking data (like referral code) you know that the participant was referred. You can use this information when the participant is signing up.

If the referred participant needs a reward applied at signup use the `sq_amount` amount to determine what their reward should be.

Use the referral code `sq_referralCode` to attribute the referral when you identify the participant to impact.com. This can be done using the mobile widget or Mobile SDK.
{% endstep %}
{% endstepper %}


# Branch for Advocate — Technical Reference

Your Advocate program can integrate with [Branch Metrics](http://branch.io/).

This technical reference explains the specific fields, features, API calls and functionality that is used in the integration. Just getting started? Learn how to [Integrate with Branch for Advocate Programs](/integration-guides/for-brands/advocate/mobile-options-for-advocate/branch-metrics-for-advocate/integrate-with-branch-for-advocate-programs).

### Link handling behaviors

After the Branch integration is configured, link-handling behaviors will change.

* Referral links (e.g., `ssqt.co/h126b21`) will begin redirecting to Branch links
* Advocate will [create branch links](https://help.branch.io/using-branch/docs/creating-a-deep-link) dynamically and set values for `data`, `channel`, `tags`, and `desktop_URL`.
* Branch deep link `data` will include details of the referral code, advocate, and reward. See the field reference below for an example.
* Analytics tags will be added to help you track the performance of different platforms.
  * `channel`: The referral medium. Value can be 1 of: `FACEBOOK`, `TWITTER`, `EMAIL`, `DIRECT`, `REMINDER`, or `UNKNOWN`.
  * `tags`: The source of the referral. Value may be 1 of: `STANDARD`, `MOBILE`, or `UNKNOWN`.

impact.com will send all link clicks through Branch, but will continue to redirect desktop traffic to your program’s landing page. This is done by setting the Branch value for `desktop_url`. If you set a desktop url for your app in Branch, it will be overwritten.

### Field reference <a href="#field-reference" id="field-reference"></a>

When impact.com creates links dynamically in Branch, we include a number of metadata fields in the data field. These include fields from the User, Referral Code and Reward objects.

| Field             | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sq_id`           | string | The customer advocate's user ID. This allows you to look up the user in your own system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `sq_accountId`    | string | The customer advocate's account ID. This allows you to look up group or company info.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `sq_firstName`    | string | The customer advocate's first name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sq_lastName`     | string | The customer advocate's last name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `sq_imageUrl`     | string | The customer advocate's profile image URL. Note that unlike the user's imageUrl that is used other places in Advocate, if this field is set to null it won't actually be null. Instead, when set to null it is replaced by an gravatar link that is automatically generated based on a hash for the customer advocate's email address. If you want to detect for null images instead, you should look for its gravatar, or not use this field and look up the value in your user database.                                                                                                                                                   |
| `sq_referralCode` | string | The customer advocate's referral code. This is necessary to attribute the referral.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sq_amount`       | string | <p>The amount of the referred friend's reward. We map this abstract field to other rewards fields that can be looked up via the API or UTT.</p><ul><li>For rewards of type <code>TIME\_CREDIT</code> and <code>CREDIT</code>, this field is equal to the reward field called <code>credit</code></li><li>For rewards of type <code>PCT\_DISCOUNT</code>, this field is equal to the reward field called <code>discountPercent</code></li><li>For rewards of type <code>FEATURE</code>, this field is equal to the reward field called <code>quantity</code></li><li>For rewards of type <code>GIFTCODE</code>, this field is empty</li></ul> |
| `sq_unit`         | string | The unit of the referred friend's reward. For example, in a 10% off referral program, this would be `PERCENT`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sq_type`         | string | The type of the referred friend's reward. One of: `PCT_DISCOUNT`, `TIME_CREDIT`, `FEATURE`, `CREDIT`, `GIFTCODE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Example deep link

When impact.com creates a link dynamically in Branch, the resulting deep link will include analytics tags, redirects, and custom metadata. Here’s an example.

{% tabs %}
{% tab title="JSON" %}

```json
{
  "code": "BRITTANYTEST",
  "$desktop_url": "http://landingpage.com/a/test_a6whcgrt0vcw3/widgets/referral?code=BRITTANYTEST&referralMedium=DIRECT&referralSource=STANDARD",
  "sq_accountId": "55a43496ebbaff9cf86443d3",
  "sq_amount": "10",
  "sq_firstName": "Brittany",
  "sq_id": "55a43496ebbaf01cebac42cb",
  "sq_imageUrl": "http://gravatar.com/avatar/77af7eba41d1ccad2bf2c13704637c25?d=mm",
  "sq_lastName": "Test",
  "sq_referralCode": "BRITTANYTEST",
  "sq_type": "PCT_DISCOUNT",
  "sq_unit": "PERCENT",
  "~channel": "DIRECT",
  "~tags": ["STANDARD"],
  "~creation_source": "API",
  "+is_first_session": false,
  "+clicked_branch_link": true
}
```

{% endtab %}
{% endtabs %}


# Advocate Bulk Import Methods

Import jobs can be started from impact.com, via Advocate’s SFTP integration, or by using the Advocate API directly.

### File-based bulk imports in impact.com

Bulk imports can be started from within impact.com. To get started, from the left navigation menu, select ![](/files/hr700haJWzy65lcXmxJk) **Engage → Reporting → Imports & Exports**.

For full instructions on the file-based bulk import process, see our other guides:

* [Import Participants in Bulk](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/import-advocate-participants-in-bulk)
* [Delete Participants in Bulk](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/delete-participants-from-your-advocate-program)

### Bulk imports via SFTP integration

Bulk imports can be performed via the SaaSquatch SFTP integration. See our guide on the [SFTP integration](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/sftp-import-integration-for-advocate-programs) for instructions on:

* Enabling and authenticating the integration
* Generating an SSH key
* Connecting to the SFTP server
* Uploading import files and checking their status

### Bulk imports via API

To start a bulk import job, there are three API requests to be performed.

* Uploading the import file
* Validating the import file
* Starting the import job

#### Uploading the import file

The `/export/upload` endpoint accepts a file upload in two different ways, either with `multipart/form-data` encoding or as a raw file upload.

**Example Request:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://app.referralsaasquatch.com/api/v1/{tenant_alias}/export/upload' \
        -u :{tenant_api_key} \
        --form 'file=@my_file.csv'
```

{% endtab %}
{% endtabs %}

When the file is successfully uploaded, a `fileRef` will be returned. The `fileRef` will be used in the next two API requests.

**Example Response:**

{% tabs %}
{% tab title="JSON" %}

```json
{
    “fileRef”: “imports/test_akdq8a9wyvzba/userEvents_63323378e1edcd44b03eed9a.jsonl”
}
```

{% endtab %}
{% endtabs %}

#### Validating the import file

Before starting your import job, you can use the `validateJobInput` GraphQL mutation to validate the import file before attempting to start the import job.\
There are two inputs required, the `fileRef` from step 1, and the job `type`.\
These are the job types available:

* Import Users: `MUTATION/USER`
* Delete Users: `MUTATION/DELETE_USER`
* Import User Events: `MUTATION/USER_EVENT`

**Example:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/graphql \ 
    -u :{tenant_api_key} \
    -H "Content-Type: application/json" 
    -d '{
    "operationName":"validate",
    "variables": {
        "jobInput": {
            "fileRef":"{file_ref}",
            "type":"{job_type}"
        }
    },
    "query": "query validate($jobInput: JobInput!) {validateJobCreation(jobInput: $jobInput) { errors }}"
}'
```

{% endtab %}
{% endtabs %}

If there are any errors found in the import file, they will be returned as an array in `errors`. If `errors` is empty, then the same `fileRef` can be used to start an import job in step 3.

**Example Response:**

{% tabs %}
{% tab title="JSON" %}

```json
{
    "data": {
        "validateJobCreation": {
            "errors": []
        }
    }
}
```

{% endtab %}
{% endtabs %}

#### Starting the import job

To start the import job, use the `createJob` GraphQL mutation. Provide the `fileRef` and job `type` from the [Validating the import file](#validating-the-import-file) section.

**Example:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/graphql \ 
    -u :{tenant_api_key}
    -H "Content-Type: application/json" 
    -d '{
    "variables":{
        "jobInput": {
            "type":"{job_type}",
            "outputFormat":"CSV",
            "fileRef":"{file_ref}"
        }
    },
    "query":"mutation ($jobInput: JobInput!) { createJob(jobInput: $jobInput) {id type requester dateCreated}}"
}'
```

{% endtab %}
{% endtabs %}

The `id` returned by the mutation can be used to query the status of the job

**Example Response:**

{% tabs %}
{% tab title="JSON" %}

```json
{
    "data": {
        "createJob": {
            "id": "633b1cf34efc053cb50a3f6d",
            "type": "MUTATION/USER_EVENT",
            "requester": "API",
            "dateCreated": 1664818419661
        }
    }
}
```

{% endtab %}
{% endtabs %}

#### Check the status of the import job

To check the status of the import job, you can use the `job` GraphQL query and provide the job `id` returned from the [Starting the import job](#starting-the-import-job) section.

**Example:**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://app.referralsaasquatch.com/api/v1/{tenant_alias}/graphql \
    -u :{tenant_api_key} \
    -H "Content-Type: application/json" 
    -d '{
    "variables": {
        "id": "{job_id}"
    },
    "query": "query ($id: ID!) { job(id: $id) { status stats { recordsProcessed }}}"
}'
```

{% endtab %}
{% endtabs %}

**Example Response:**

{% tabs %}
{% tab title="JSON" %}

```json
{
    "data": {
        "job": {
            "status": "COMPLETED",
            "stats": {
                "recordsProcessed": 22
            }
        }
    }
}
```

{% endtab %}
{% endtabs %}


# Build a Custom Advocate Experience with GraphQL

We advise most users to use the built-in widgets and [widget editor](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/widget-experiences/customize-program-widgets) to power the Advocate experience, but in some cases, building your own Advocate experience using data pulled in via [GraphQL](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-api/graphql-api) is recommended. The best implementation path for your program will be discussed with your onboarding team. These are some situations in which a custom Advocate participant experience may be the right choice:

* Your company has a strict Content Security Policy (CSP) that prevents our custom JavaScript from rendering on the page.
* You're building a mobile app natively and need an advanced degree of control over widget creation.
* You want to load the widget on the server or back-end, rather than on the front-end.

#### Build, test, or run GraphQL queries and mutations

You can build and test GraphQL queries and mutations as well as explore our GraphQL documentation within your impact.com account.

To get started:

1. In your impact.com account, from the top navigation bar, select ![](/files/hr700haJWzy65lcXmxJk) **\[User profile]** → [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. In the *Advocate Settings* section, select **GraphQL**.
3. Use the interface to build, test, or run queries, or explore our documentation.

<div data-with-frame="true"><figure><img src="/files/L0acyXyvrDYCH0uyn7UE" alt="" width="563"><figcaption></figcaption></figure></div>

{% stepper %}
{% step %}

### Authenticate

You will need a [GraphQL client](https://graphql.org/code/#graphql-clients) to begin.

The endpoint URL is `https://app.referralsaasquatch.com/api/v1/{tenant_alias}/graphql`. You can find your tenant alias in the impact.com platform:

1. From the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile]** → [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml) .
2. Under *Advocate Settings*, select **General**.
3. Retrieve your tenant alias from the *Tenant Details* section at the top of the page.

To simplify authentication, we recommend making GraphQL calls authorized as the end user. You'll need to generate a [JSON Web Token](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/json-web-tokens-jwts) for your user on the server, using your tenant's [API key](/rest-apis/api-quick-start/create-an-api-key). Use the header `Authorization: Bearer {JWT}`.
{% endstep %}

{% step %}

### Build GraphQL queries

{% hint style="success" %}
**Note:** Basic auth is required when making GraphQL calls.
{% endhint %}

The following queries and mutations are commonly used when building a custom experience.

#### Look up the user

The easiest way to get data in a custom experience is to use the special `viewer` property to look up the user that is currently authorized.

#### GraphQL Query

{% tabs %}
{% tab title="GraphQL" %}

```graphql
{
  viewer {
    ... on User {
      firstName
      lastName
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Example

{% tabs %}
{% tab title="JSON" %}

```json
{
  "viewer": {
    "firstName": "Carrie",
    "lastName": "Oakey"
  }
}
```

{% endtab %}
{% endtabs %}

### Display a list of rewards

You can look up a list of rewards to show people what they've earned from your programs.

* `prettyValue` vs `value`: When building custom widgets it's usually best to use the `prettyValue` for rewards, since that will format and localize the reward value into something readable. Note that there are also pretty fields for available and expired values.
* `value` vs `availableValue`: The value of a reward may change due to it being expired, or canceled, or redeemed. If you want to show a sense of progress, you can show a lifetime earned amount.

#### GraphQL Query

{% tabs %}
{% tab title="GraphQL" %}

```graphql
{
  viewer {
    ... on User {
      firstName
      lastName
      rewards {
        data {
          prettyValue
          prettyAvailableValue
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Example

{% tabs %}
{% tab title="JSON" %}

```json
{
  "viewer": {
    "firstName": "Carrie",
    "lastName": "Oakey",
    "rewards": {
      "data": {
        "prettyValue": "$10.00",
        "prettyAvailableValue": "$4.75"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Show who referred the participant

If someone has been referred, showing them "You were referred by `{name}`" in the user interface is common. To look that up, use the `referredByReferral` connection to find out more about the referral.

#### GraphQL Query

{% tabs %}
{% tab title="GraphQL" %}

```graphql
{
  viewer {
    ... on User {
      firstName
      lastName
      referredByReferral(programId: "referral") {
        referrerUser {
          firstName
          lastName
        }
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Example

{% tabs %}
{% tab title="JSON" %}

```json
{
  "viewer": {
    "firstName": "Sansa",
    "lastName": "Stark",
    "referredByReferral": {
      "referrerUser": {
        "firstName": "Jon",
        "lastName": "Snow"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Display list of referrals

To show someone their list of referrals, and any rewards earned because of those referrals, use the referrals connection on a user.

Note that you'll need to include your `programId` in this call only if one user is making referrals across different referral programs, and you want to filter them out.

#### GraphQL Query

{% tabs %}
{% tab title="GraphQL" %}

```graphql
{
  viewer {
    ... on User {
      firstName
      lastName
      referrals(filter: {programId_eq: "referral"}, limit: 3) {
        data {
          referrerUser {
            firstName
            lastName
          }
        }
        totalCount
        count
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Example

{% tabs %}
{% tab title="JSON" %}

```json
{
  "viewer": {
    "firstName": "Carrie",
    "lastName": "Oakey",
    "referrals": {
      "data": [
        {
          "referrerUser": {
            "firstName": "Noah",
            "lastName": "Lott"
          }
        },
        {
          "referrerUser": {
            "firstName": "Olivia",
            "lastName": "Sutton"
          }
        },
        {
          "referrerUser": {
            "firstName": "Earl",
            "lastName": "Bird"
          }
        }
      ],
      "totalCount": 1021,
      "count": 3
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Update a participant's information

You can also do a complete upsert, instead of using the user upsert from [UTT](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-tracking-integrations/advocate-installation-scripts) or our [REST API](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-api/advocate-rest-api). Only the fields that are included are updated, so you can add new fields, or add new segments, without removing or overriding previous values.

#### GraphQL Mutation

{% tabs %}
{% tab title="GraphQL" %}

```graphql
mutation {
  upsertUser(userInput: {
    id: "",
    accountId: "",
    lastName: "Lott",
    segments: ["Platinum"],
    customFields: {
      VIP: true
    }
  }) {
    firstName
    lastName
    segments
    customFields
  }
}
```

{% endtab %}
{% endtabs %}

#### Example

{% tabs %}
{% tab title="JSON" %}

```json
{
  "upsertUser": {
    "firstName": "Carrie",
    "lastName": "Lott",
    "segments": [
      "Platinum"
    ],
    "customFields": {
      "VIP": true
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Look up reward configuration

You can advertise what people will earn from your program by looking up the program by `id`, and then looking up the program's rewards. Every program has a different set of reward keys.

#### GraphQL Query

{% tabs %}
{% tab title="GraphQL" %}

```graphql
{
  viewer {
    ... on User {
      firstName
      lastName
    }
  }
  program(id: "referral") {
    rewards {
      prettyValue
    }
    tierOneOnly: reward(key: "referrerTier1") {
      prettyValue
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Example

{% tabs %}
{% tab title="JSON" %}

```json
{
  "viewer": {
    "firstName": "Carrie",
    "lastName": "Oakey"
  },
  "program": {
    "rewards": [
      {
        "key": "referredReward",
        "prettyValue": "$10.00"
      },
      {
        "key": "referrerTier1",
        "prettyValue": "$20.00"
      }
    ],
    "tierOneOnly": {
      "prettyValue": "$20.00"
    }
  }
}
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

## Other queries and mutations

See our GraphQL explorer in your impact.com account for a full list of the available queries and mutations.

1. In your impact.com account, from the top navigation bar, select ![](/files/hr700haJWzy65lcXmxJk) **\[User profile]** → [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. In the *Advocate Settings* section, select **GraphQL**.
3. Use the interface to build, test, or run queries, or explore our documentation.


# Share Links for Advocate

Each participant in your referral program has unique *share links* that they can send to family and friends as an easy way to make referrals. These links will direct the referred person to the landing page you have configured for your referral program, where the [Universal Tracking Tag](/integration-guides/for-brands/tracking-integrations/javascript-tag-utt) will create an attribution event between the customer advocate and the person they referred.

If you're building a custom Advocate participant experience, then you'll need to include the customer advocate's *share link object* to dynamically populate their share links.

{% hint style="info" %}
**Before building a custom Advocate experience...**\
Connect with your implementation team to make sure a custom experience is a good fit. We recommend that **most clients** use the [Advocate widget](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/widget-experiences/widget-types-explained) editor to create program widgets. If your organization is unable to do so, e.g., because of a strict Content Security Policy (CSP), then you can create a custom experience instead, using our API or GraphQL to pull in data.
{% endhint %}

## Retrieve the share link object

You can retrieve the share link object you need via REST API, GraphQL, or within your impact.com Advocate program.

* [REST API](/integration-guides/for-brands/advocate/share-links-for-advocate#rest-api)
* [GraphQL](#graphql)
* [impact.com](#impact.com)

{% tabs %}
{% tab title="Rest API" %}
Use one of the following REST API calls to retrieve share links.

* [Lookup a user](/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user#get-tenant_alias-user)
* [Lookup a user's Share URLs](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/share-links-overview/share-links)
  {% endtab %}

{% tab title="GraphQL" %}
Use the [query](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-api/graphql-api) `user.shareLinks`.
{% endtab %}

{% tab title="impact.com" %}

1. In the left navigation menu, select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768905009/Accessibility%20Icons/engage-v2.svg) **Engage → Participants**.
2. Search for a participant and select their **name** to open their participant profile.
3. Select the **Codes and links** tab.
4. Find the share link for your program below the *Sharelinks* heading.
5. Select the down arrow to the left of the share link, then select **See More Sharelinks**. This will open the share link object view.
6. Select the share link object for the engagement medium your widget is using.
   {% endtab %}
   {% endtabs %}

## Reference

Share links are specific to an *engagement medium* and a *share medium*. The *engagement medium* is the method you use to show a participant's share information to them, e.g., a pop-up widget. The *share medium* is the method the participant used to distribute their share link to others, e.g, via WhatsApp.

### Share mediums

* `FACEBOOK`
* `FBMESSENGER`
* `TWITTER` (X)
* `EMAIL`
* `DIRECT`
* `LINKEDIN`
* `SMS`
* `WHATSAPP`
* `LINEMESSENGER`
* `PINTEREST`
* `UNKNOWN`

### Engagement mediums

| Engagement Medium | Description                                                                                                                                                                                                                                                |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POPUP`           | Displayed to participants as a pop-up modal that renders on top of other elements on a page.                                                                                                                                                               |
| `EMBED`           | Displayed to participants in-line as part of your page.                                                                                                                                                                                                    |
| `HOSTED`          | Displayed to participants in a [microsite](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/microsite-experiences).                                                               |
| `cleanShareLink`  | A share link available on the participant's profile in your Advocate program.                                                                                                                                                                              |
| `UNKNOWN`         | A set of share links retrieved for a participant via [the user details report](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-reporting-and-analytics/advocate-program-reports-explained#user-details-report). |
| `EMAIL`           | Displayed to participants in [program notification emails](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/set-up-an-advocate-smtp-email-integration).                                         |
| `MOBILE`          | Displayed to participants via the [mobile SDKs](/integration-guides/for-brands/advocate/mobile-options-for-advocate).                                                                                                                                      |

### Share link object example

{% tabs %}
{% tab title="JSON" %}

```javascript
{ 
  "POPUP": {
    "FACEBOOK": "https://ssqt.co/m93Jla9", 
    "TWITTER": "https://ssqt.co/mM3Jla9", 
    "EMAIL": "https://ssqt.co/mo3Jla9", 
    "DIRECT": "https://ssqt.co/m53Jla9", 
    "LINKEDIN": "https://ssqt.co/m73Jla9", 
    "SMS": "https://ssqt.co/ma3Jla9", 
    "FBMESSENGER": "https://ssqt.co/mh3Jla9", 
    "WHATSAPP": "https://ssqt.co/mF3Jla9", 
    "LINEMESSENGER": "https://ssqt.co/mD3Jla9", 
    "PINTEREST": "https://ssqt.co/Rz3Jla9", 
    "UNKNOWN": "https://ssqt.co/mB3Jla9" 
  	}, 
    "EMBED": { 
      "FACEBOOK": "https://ssqt.co/mw3Jla9", 
      "TWITTER": "https://ssqt.co/mc3Jla9", 
      "EMAIL": "https://ssqt.co/mJ3Jla9", 
      "DIRECT": "https://ssqt.co/mQ3Jla9", 
      "LINKEDIN": "https://ssqt.co/mH3Jla9", 
      "SMS": "https://ssqt.co/m23Jla9", 
      "FBMESSENGER": "https://ssqt.co/mg3Jla9", 
      "WHATSAPP": "https://ssqt.co/mZ3Jla9", 
      "LINEMESSENGER": "https://ssqt.co/mx3Jla9", 
      "PINTEREST": "https://ssqt.co/mf3Jla9", 
      "UNKNOWN": "https://ssqt.co/mX3Jla9" 
    }, 
    "HOSTED": { 
      "FACEBOOK": "https://ssqt.co/mu3Jla9",
      "TWITTER": "https://ssqt.co/mS3Jla9",
      "EMAIL": "https://ssqt.co/ml3Jla9", 
      "DIRECT": "https://ssqt.co/mt3Jla9", 
      "LINKEDIN": "https://ssqt.co/mY3Jla9", 
      "SMS": "https://ssqt.co/mq3Jla9", 
      "FBMESSENGER": "https://ssqt.co/mK3Jla9", 
      "WHATSAPP": "https://ssqt.co/mr3Jla9", 
      "LINEMESSENGER": "https://ssqt.co/mW3Jla9", 
      "PINTEREST": "https://ssqt.co/Rm3Jla9", 
      "UNKNOWN": "https://ssqt.co/mA3Jla9" 
    }, 
    "cleanShareLink": "https://ssqt.co/mz3Jla9",
     "UNKNOWN":{
       "FACEBOOK": "https://ssqt.co/mm3Jla9", 
       "TWITTER": "https://ssqt.co/mR3Jla9", 
       "EMAIL": "https://ssqt.co/mL3Jla9", 
       "DIRECT": "https://ssqt.co/mv3Jla9", 
       "LINKEDIN": "https://ssqt.co/m63Jla9", 
       "SMS": "https://ssqt.co/mk3Jla9", 
       "FBMESSENGER": "https://ssqt.co/m03Jla9", 
       "WHATSAPP": "https://ssqt.co/mI3Jla9", 
       "LINEMESSENGER": "https://ssqt.co/m83Jla9", 
       "PINTEREST": "https://ssqt.co/mp3Jla9",
       "UNKNOWN": "https://ssqt.co/mz3Jla9" 
     }, 
     "EMAIL": { 
       "FACEBOOK": "https://ssqt.co/mT3Jla9", 
       "TWITTER": "https://ssqt.co/mG3Jla9", 
       "EMAIL": "https://ssqt.co/mb3Jla9", 
       "DIRECT": "https://ssqt.co/mP3Jla9",
       "LINKEDIN": "https://ssqt.co/m13Jla9",
       "SMS": "https://ssqt.co/mO3Jla9", 
       "FBMESSENGER": "https://ssqt.co/m43Jla9", 
       "WHATSAPP": "https://ssqt.co/mi3Jla9", 
       "LINEMESSENGER": "https://ssqt.co/my3Jla9", 
       "PINTEREST": "https://ssqt.co/RL3Jla9", 
       "UNKNOWN": "https://ssqt.co/mV3Jla9" 
     }, 
     "MOBILE": { 
       "FACEBOOK": "https://ssqt.co/mn3Jla9", 
       "TWITTER": "https://ssqt.co/mC3Jla9", 
       "EMAIL": "https://ssqt.co/mE3Jla9", 
       "DIRECT": "https://ssqt.co/me3Jla9",
       "LINKEDIN": "https://ssqt.co/m33Jla9", 
       "SMS": "https://ssqt.co/mN3Jla9",
       "FBMESSENGER": "https://ssqt.co/mU3Jla9", 
       "WHATSAPP": "https://ssqt.co/ms3Jla9", 
       "LINEMESSENGER": "https://ssqt.co/md3Jla9", 
       "PINTEREST": "https://ssqt.co/RR3Jla9", 
       "UNKNOWN": "https://ssqt.co/mj3Jla9" 
     } 
}
```

{% endtab %}
{% endtabs %}


# Plugin Integrations


# MMP - Mobile Measurement


# Integrate with Adjust

impact.com can integrate with Adjust to receive attribution and in-app event data through automated callbacks.

## How it works

* In the Adjust platform, you’ll add the impact.com integration module to your app configuration, which enables the standard *Install* callback by default. Additional callbacks can be configured to suit your use case.
* Once integrated, you'll generate an Adjust *Tracker URL* (or *Measurement URL*), append a necessary query string parameter, then set it as your mobile app(s)'s *Download URL* in the impact.com platform.
* From there, you'll be able to test the integration with a test ad that will forward a user to your app's Adjust link. Events that you've configured in the integration and occur in your app will appear as *Actions* in the impact.com platform.

## Enable the integration

impact.com is an *integrated module partner* within the Adjust platform. The instruction set below will enable the integration, which sends *App Installs* by default.

1. In the Adjust dashboard, navigate to the panel on the left and select **Campaign Lab →** **Partners**, then select ![](/files/gbGEaKuAkSekAQcCkyV2) **\[Add]** **New Partner**.

<div data-with-frame="true"><figure><img src="/files/EVsfMhsainbuBBJJM139" alt="" width="563"><figcaption></figcaption></figure></div>

2. Search for and select `impact`.
3. On the *App selection* screen, select the app you want to configure, then select **Next**.

<div data-with-frame="true"><figure><img src="/files/nwnhwOIgXSMVHZnnT8zp" alt="" width="563"><figcaption></figcaption></figure></div>

4. On the *Data sharing* screen, select **Edit** to open the *Enable data sharing* modal, then enter the following:

<table><thead><tr><th width="185.14453125">Field</th><th>Value</th></tr></thead><tbody><tr><td><strong>App ID</strong></td><td>The impact.com <em>System App ID</em> for your mobile app. In impact.com, go to <img src="/files/NAwewjCC7OYTjHnAmreE" alt=""> <strong>[User profile] → Settings →</strong> <a href="https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml"><strong>Mobile Apps</strong>.</a></td></tr><tr><td><strong>Account SID</strong></td><td>Your impact.com API Account SID (case-sensitive). In impact.com, go to <img src="/files/NAwewjCC7OYTjHnAmreE" alt=""> <strong>[User profile] → Settings →</strong> <a href="https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml#sortBy=CREATED_ON&#x26;sortOrder=DESC"><strong>API</strong>.</a></td></tr><tr><td><strong>Auth token</strong></td><td>Your impact.com API Auth Token (case-sensitive). In impact.com, go to <img src="/files/NAwewjCC7OYTjHnAmreE" alt=""> <strong>[User profile] → Settings →</strong> <a href="https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml#sortBy=CREATED_ON&#x26;sortOrder=DESC"><strong>API</strong>.</a></td></tr></tbody></table>

<div data-with-frame="true"><figure><img src="/files/46uyOydyd2V9qPho79IA" alt="" width="563"><figcaption></figcaption></figure></div>

5. Select **Enable**, then select **Next**.
6. In the *Set your data sharing options* section, you can choose from which source to pull data. Select <img src="/files/0aa2T5y6wtv5RR5CsEju" alt="" data-size="line"> **\[Radio button] Data from all attribution sources** — this is the recommended setting.
   * If you want to limit callbacks to impact.com-attributed data, select <img src="/files/0aa2T5y6wtv5RR5CsEju" alt="" data-size="line"> **\[Radio button] Only data attributed to Impact**.

<div data-with-frame="true"><figure><img src="/files/2HsMcCg5NETYVr0ohave" alt="" width="563"><figcaption></figcaption></figure></div>

7. On the *Link structure* screen, enter a name for the link. Select **Next**.
8. On the *User destinations* screen, configure the user flow for the link (for example, redirect and fallback destinations). Select **Next**.

<div data-with-frame="true"><figure><img src="/files/kVyPlLcjcSbiGkySHJrp" alt="" width="563"><figcaption></figcaption></figure></div>

9. On the *Attribution settings* screen, navigate to the *New user: attribution* section → **Clicks**. Select ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggle on] Enable probabilistic modeling** and configure the *Attribution window* as needed. Select **Next**.

<div data-with-frame="true"><figure><img src="/files/U86OMToiXVxCjc43c7BC" alt="" width="563"><figcaption></figcaption></figure></div>

10. Complete any remaining steps and select **Quick create** or **Next** to finish setup.

### Additional forwarding options

{% hint style="success" %}
**Note:** These are advanced options that may require support from impact.com—for assistance, [contact us](https://help.impact.com/other/reference-documentation/get-help-and-support).
{% endhint %}

Within the Adjust integration module, there are 3 toggles for additional callbacks that impact.com can receive:

* **Revenue Forwarding** — forwards in-app revenue amounts and revenue event data to impact.com.
* **Parameter Forwarding** — forwards Adjust partner parameters that collect custom data points to mapped impact.com parameters. See [*Parameter mapping*](#parameter-mapping) below.
* **Session Forwarding** — forwards in-app session information to impact.com; due to usually high volume of sessions recorded for an app, ensure this feature is disabled unless explicitly stated otherwise by an impact.com integration engineer.

#### Event Linking

If you want to send in-app events (e.g., *Sale*, *Lead*, etc.), configure these in the Event Linking section. Each event in Adjust must match a specific *Event Code* you’ve configured for your mobile app in impact.com.

For example, if you're tracking in-app sales, `EVENT-REVENUE` can be set to the case-sensitive value of the Event Code for an *In-app Sale* that you’ve configured for your mobile app(s) in impact.com (e.g., `PURCHASE`)\
\
To send in-app events (for example, *Sale* or *Lead*) to impact.com, configure them in the *Map your events* section within Adjust's Data sharing setup.

1. In the Adjust dashboard, navigate to **Campaign Lab → Partners**, then select the **Data sharing** tab.
2. Find your app from the list and select the pencil icon on the right of the row to edit.

<div data-with-frame="true"><figure><img src="/files/OWeGUQ61AfgYuiT9tZ56" alt="" width="563"><figcaption></figcaption></figure></div>

3. Navigate to the *Map your events* section.
4. Add the events you want to track with impact.com and enter their corresponding Event Code value. This Event Code will be set up on the impact.com side.
   * The Event Code must match exactly as configured for your mobile app in impact.com.
   * Each mapped event will then appear as an *Action* in the impact.com platform once triggered in your app.

#### Parameter mapping

Refer to the linked resource below for the list of parameters that impact.com retrieves from Adjust in a callback. If you have custom values outside of this list you want to send to impact.com, these can be mapped here (e.g., `SomeCustomString` from your app could be mapped to `Text1` on the impact.com side and could be configured as a condition for payouts and appear in your impact.com reports).

See the [list of all parameters forwarded to impact.com ](https://help.adjust.com/en/integrated-partners/impact?src=search#list-of-all-parameters-forwarded)in the Adjust Help Center.

**Custom mapping of non-default parameters**

If your app uses parameters that don't match the default mapping between impact.com and Adjust, you can configure custom mappings in the *Map your parameters* section of the Adjust Data sharing setup.

1. In the Adjust dashboard, navigate to **Campaign Lab → Partners**, then select the **Data sharing** tab.
2. Find your app from the list and select the pencil icon on the right of the row to edit.
3. Navigate to the *Map your parameters* section.
4. Map each custom Adjust parameter to its corresponding impact.com parameter.

## Create Tracker URLs

If you have more than one app, repeat this process for both apps.

1. In your Adjust dashboard, find your app’s tile and select **Tracker URLs**.
2. In the modal, select **New Tracker**.
3. For Tracker Name, input a sensible value like `Impact`.
4. Select **Quick Create**.
5. Once created, copy the *Click URL*.
6. Append the following query string parameter to the link:
   * `impactradius_click_id={clickid}`

## Configure mobile apps

This section assumes you’ve already set up an app. See [Mobile App Tracking Explained](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/tracking/mobile-app-tracking/mobile-app-tracking-explained) in the impact.com Help Center for details on configuring a mobile app.

### Update Download URL

If you have more than one app, repeat this process for both apps.

1. In the impact.com platform, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. In the right column, navigate to the *Tracking* section and select [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml?).
3. In the list, find the mobile app that you want to modify and select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768910844/Accessibility%20Icons/More_vNext.svg) **\[More] → View/Edit**.
4. Find the *Download URL* line item and paste in the *Tracker/Measurement URL* from Adjust, and make sure to append the following required query string parameter:
   * `adgroup={sharedid}&campaign={irpid}&creative={iradid}&impactradius_click_id={clickid}`

### Manage Event Codes

For each additional in-app event you’re tracking, you’ll need to configure it as an Event Code for your mobile app. Once added, this will make the event payable to partners.

1. In the impact.com platform, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. In the right column under the *Tracking* section, select [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml).
3. In the list, find the mobile app that you want to modify and select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768910844/Accessibility%20Icons/More_vNext.svg) **\[More] → Manage Event**.
4. In the top-right corner of the screen, select **Add Event**.
5. Find the *In-App Events* line item and select ![](/files/gbGEaKuAkSekAQcCkyV2) **Add Another Event**.
6. Enter the following information:
   * **Event Display Name** — This is simply a name for this event that will appear in the impact.com platform.
   * **Event Code** — Enter the Event Code for this event - it must be exactly as it appears on the *Event Linking* screen within the Impact Module.
   * **Crediting Rule** — Select **Install** if you are looking to add an `INSTALL` Event Code, or select **Last Click** if you are looking to track the source of the last referring click to your app.
7. Select ![](/files/gbGEaKuAkSekAQcCkyV2) **Add Another Event** to add another, otherwise select **Save**.

<div data-with-frame="true"><figure><img src="/files/Jmz4u4Zf3luivYTBm4lG" alt="" width="425"><figcaption></figcaption></figure></div>

## Other Resources

See the [Set up Impact](https://help.adjust.com/en/integrated-partners/impact) article in the Adjust Help Center for additional documentation on this integration.


# Integrate with AppsFlyer

impact.com can integrate with your existing AppsFlyer mobile app setup to enable tracking, reporting, and payouts for events in your mobile apps.

The integration supports a range of app events, including *Installs*, *In-App Sales*, *Leads*, *App Opens*, and *Sign-ups*, and can be customized to suit your specific use case.

{% hint style="success" %}
**Note:** This article covers the Integration with AppsFlyer for a Performance Program. Learn more about how to [Integrate with AppsFlyer for your Advocate Program](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/appsflyer-for-advocate/integrate-with-appsflyer-for-advocate-programs).
{% endhint %}

#### How it works

* In your AppsFlyer account, you’ll enable the impact.com module, configure its settings, then get your app’s attribution link.
* In your impact.com account, you'll add (or update) your mobile app(s)' *Download URL* with the attribution link created while integrating.
* For each in-app event you want to send to impact.com, you'll add new events (and *Event Codes*) to your mobile app(s) in impact.com.

## Enable the module

***

1. Log in to your [**AppsFlyer**](https://www.appsflyer.com/) account.
2. In the AppsFlyer dashboard, find the *Configuration* section and select **Integrated Partners**.
3. In the *App Search*, input `impact_radius` then select **Activate Partner**.

## Enable permissions

***

For efficient support and troubleshooting, make your AppsFlyer app visible to the impact.com team.

1. From the top navigation bar, select Permissions.
2. ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggle on] Ad Network Permissions**.

<div data-with-frame="true"><figure><img src="/files/Ulh5ungkI9nNJVOdltv4" alt="" width="563"><figcaption></figcaption></figure></div>

## Configure the module

***

Each subsection below refers to the relevant setting section of the module. To configure the module in AppsFlyer, navigate to **Configuration → Integrated Partners**, find the impact.com module and select **Edit**.

### General Settings

In the General Settings section, you’ll need to add your mobile app’s System App ID and your impact.com API credentials (Account SID & Auth Token).

{% hint style="success" %}
**Note:** The *General Settings* section configures the *Install* event — other events are configured in the *In-App Events* section.
{% endhint %}

| Field             | Description                                                                                                                                                                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `password`        | Your impact.com API Auth Token. In the impact.com platform, navigate to your [API Credentials](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/manage-api-access-tokens-as-a-brand) to find your Auth Token.   |
| `ActionTrackerId` | Your impact.com System App ID for your mobile app. In the impact.com platform, navigate to your [Mobile Apps](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml) to find your System App ID.                                       |
| `user`            | Your impact.com API Account SID. In the impact.com platform, navigate to your [API Credentials](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/manage-api-access-tokens-as-a-brand) to find your Account SID. |
|                   |                                                                                                                                                                                                                                                                                    |

### Default Postbacks

The Default Postbacks section allows you to configure which events are sent to impact.com. For the *Install* event, you must set the **for users from dropdown** to *All media sources, including organic* to ensure impact.com receives data for all installs (paid, non-attributed, and organic).

{% hint style="success" %}
**Note:** The option `All media sources, including organic` may not be immediately visible for the Install event. If it is not visible, please contact AppsFlyer Support and ask them to enable this setting for the impact.com partner integration.
{% endhint %}

### In-App Events Postback

If you want to send in-app events to impact.com (e.g., *Sale*, *Lead*, etc.), enable the *In-App Events Postback* option.

### In-App Event Settings

If the *In-App Events Postback* option is enabled, make sure to fill out this section; otherwise, leave this blank.

Your credentials here are identical to the ones used in the *General Settings* section — simply duplicate the values used for `user`, `password`, and `AppId` (identical to `ActionTrackerId`).

#### In-App Postback Window

Refer to [**In-app event postback window**](https://support.appsflyer.com/hc/en-us/articles/208439256-In-app-events-postback-configuration#inapp-event-postback-window) on AppsFlyer's Help Center for documentation on this feature.

#### Parameters

| Parameter                | Description                                                                                                                                                                                                                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SDK event name           | The SDK Name is the name of the parameter you’re using in the AppsFlyer SDK to track a data point.                                                                                                                                                                                                 |
| Partner event identifier | This is the identifier that impact.com will look for — must be configured as an Event Code for your mobile app. For example, if you want to track an in-app order with an SDK event name of af\_purchase, then af\_purchase must be configured as an Event Code for your mobile app in impact.com. |
| Sending option           | Determine where this data point will be sent. Select `All media sources, including organic` for all configured In-App events to ensure impact.com receives all event data (paid, non-attributed, and organic).                                                                                     |
| Send Revenue             | If the SDK is set to send a specific parameter- toggle on Send Values and Revenue (if revenue is available) or Send Values and No Revenue (if no revenue is available).                                                                                                                            |

#### Fixed structure parameter mapping

AppsFlyer sends conversion postbacks to impact.com with a fixed structure. While it’s not possible to update the fixed structure, it is possible to update the mapping for custom event data (`event-values`). Refer to [custom parameters](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/mmp-mobile-measurement/integrate-with-appsflyer#custom-parameter-mapping) for more information.

<details>

<summary>Fixed structure parameters</summary>

| AppsFlyer Parameter                                     | impact.com Parameter |
| ------------------------------------------------------- | -------------------- |
| `APPSFLYER`                                             | `IntegrationSource`  |
| `(appsflyer-device-id)(idfa)(vendorId)(timestamp)`      | `OrderId`            |
| `(device-model)`                                        | `DeviceModel`        |
| `(ip)`                                                  | `IpAddress`          |
| `(ip)`                                                  | `IpAddressCarrier`   |
| `(appsflyer-device-id)`                                 | `appsflyer_id`       |
| `(os-version)`                                          | `DeviceOs`           |
| `(carrier)`                                             | `DeviceCarrier`      |
| `(ip)`                                                  | `IpAddressWifi`      |
| `(event-value)`                                         | `appsflyer-custom`   |
| `(AppId)`                                               | `ActionTrackerId`    |
| `(mapped-iae) \| INSTALL`                               | `EventCode`          |
| `(app-version-name)`                                    | `AppVer`             |
| `NOW`                                                   | `EventDate`          |
| `(custom-user-id)`                                      | `CustomerId`         |
| `(city)`                                                | `CustomerCity`       |
| `(country-code)`                                        | `CustomerCountry`    |
| `(app-id)`                                              | `AppPackage`         |
| `(idfa)`                                                | `AppleIfa`           |
| `(advertiserId)`                                        | `GoogAId`            |
| `(clickid)`                                             | `ClickID`            |
| `re-attribution \| empty`                               | `Text1`              |
| `(country-code) - Install only`                         | `Text2`              |
| `re-engagement \| empty`                                | `Text3`              |
| `(af_siteid) - if impression attribution via appsflyer` | `MPID`               |

</details>

#### Custom parameter mapping

Event-specific data (`event-values`) are sent by AppsFlyer as a JSON body and have the following default mapping if impact.com receives one of the AppsFlyer parameters for a conversion:

<details>

<summary>Custom <code>event-value</code> parameters</summary>

| AppsFlyer Parameter | impact.com Parameter | Type    |
| ------------------- | -------------------- | ------- |
| `af_order_id`       | `OrderId`            | String  |
| `af_content_id`     | `ItemSku`            | String  |
| `af_content_type`   | `ItemCategory`       | String  |
| `af_quantity`       | `ItemQuantity`       | int     |
| `af_price`          | `ItemPrice`          | decimal |
| `af_revenue`        | `Amount`/`Revenue`   | decimal |
| `af_currency`       | `Currency`           | String  |
| `af_date_a`         | `Date1`              | String  |
| `af_date_b`         | `Date2`              | String  |
| `af_city`           | `CustomerCity`       | String  |
| `af_region`         | `CustomerRegion`     | String  |
| `af_country`        | `CustomerCountry`    | String  |
| `af_coupon_code`    | `OrderPromoCode`     | String  |
| `af_param1`         | `IR_OrderDiscount`   | decimal |
| `af_param2`         | `IR_ItemSubTotal`    | decimal |
| `af_param3`         | `IR_CustomerStatus`  | String  |
| `af_param4`         | `CustomerEmail`      | String  |
| `af_param5`         | `IR_CustomerId`      | String  |

</details>

{% hint style="success" %}
**Note:** If you want to update the default mapping for `event_values`, [contact support](https://app.impact.com/support/portal.ihtml?createTicket=true).
{% endhint %}

**JSON example**

The example below shows passing item-level data.

{% tabs %}
{% tab title="JSON" %}

```json
event-value={
  "af_order_id":"AF_test6", 
  "af_currency":"USD", 
  "af_coupon_code":"SALE20", 
  "af_city":"Santa Barbara", 
  "af_region": "CA", 
  "af_country":"USA", 
  "af_param1":"10.55", 
  "af_param2"::"123.45", 
  "af_param3":"NEW", 
  "af_param4":"914FEC35CE8BFA1A067581032F26B053591EE38A",
  "af_content_type":["hat","glasses", "bracelet"], "af_content_id":["sku-000","sku010","sku011"],
  "af_quantity":[1,2,2],
  "af_price":[35.21,300.03,250]
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Warning:** If you're only reporting order-level data, pass the `af_revenue` parameter, which maps to the impact.com `Amount` parameter — item-level parameters (e.g., `af_price`) will be ignored.\
\
If passing item-level data (`af_content_type`, `af_quantity`, `af_price`) for an event, send it in array format (e.g., `af_quantity = [ItemQuantity1, ItemQuantity2]`) — the order-level `af_revenue` will be ignored.
{% endhint %}

## AppsFlyer attribution link

***

You’ll need to retrieve an AppsFlyer attribution link or generate an AppsFlyer OneLink ([learn more about OneLink in the AppsFlyer Help Center](https://support.appsflyer.com/hc/en-us/articles/115005248543-OneLink-overview)).

Whichever link you retrieve needs to be set as the *Download URL* for your mobile app(s) within the impact.com platform.

{% hint style="success" %}
**Note:** Standard attribution links *do not* support deep linking — only OneLink does.
{% endhint %}

### OneLink

1. On your AppsFlyer dashboard, in the left navigation menu, find the *Collaborate* section and select **Active Integrations**.
2. Select **impact.com**, then select the **Attribution link** tab.
3. Below the *Choose your attribution link type* section, select **Use OneLink**.
4. Below the *Select OneLink template* section, select the relevant template from the drop-down menu.
5. In the *Click attribution link* section, **copy the OneLink** so it can be configured as your app(s) Download URL in impact.com.

#### OneLink example

{% tabs %}
{% tab title="HTTP" %}

```http
acme.onelink.me/3218718612?af_siteid={irpid}&pid=impactradius_int&af_click_lookback=7d&clickid={clickid}&af_sub_siteid={sharedid}&c={iradname}&af_c_id={iradid}&is_retargeting=true&af_dp={gwlurl}
```

{% endtab %}
{% endtabs %}

### Attribution link

1. On your AppsFlyer dashboard, in the left navigation menu, find the *Collaborate* section and select **Active Integrations**.
2. Select **impact.com**, then select the **Attribution link** tab.
3. Below the *Choose your attribution link type* section, select **Use single-platform link**.
4. The *Attribution link parameters* section will allow you to add custom parameters to the click tracking link at the bottom — required parameters for impact.com are already set.
5. Once you have appended the required parameters, **copy the Click attribution link**.

#### Attribution Link example

{% tabs %}
{% tab title="HTTP" %}

```
app.appsflyer.com/id1486762009?af_siteid={irpid}&pid=impactradius_int&af_click_lookback=7d&clickid={clickid}&af_sub_siteid={sharedid}&c={iradname}&af_c_id={iradid}&is_retargeting=true&af_dp={gwlurl} 
```

{% endtab %}
{% endtabs %}

## Configure mobile app(s)

***

See [**Set up Mobile App Tracking**](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/tracking/mobile-app-tracking) in the impact.com Help Center for details on configuring a mobile app. This section assumes you’ve already set up an app — it focuses on two key parts related to integrating with AppsFlyer.

### Update Download URL

1. In the impact.com platform, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. In the right column, select [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml?).
3. In the list, find the mobile app that you want to modify and select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768910844/Accessibility%20Icons/More_vNext.svg) **\[More] → View/Edit**.
4. Find the Download URL line item and paste in the URL from AppsFlyer (either the attribution link or OneLink), and make sure to append the following required query string parameter:

```
af_siteid={irpid}&pid=impactradius_int&af_click_lookback=7d&clickid={clickid}&af_sub_siteid={sharedid}&c={iradname}&af_c_id={iradid}&is_retargeting=true&af_dp={gwlurl}
```

### Manage Event Codes

For each additional in-app event you’re tracking, you’ll need to configure it as an Event Code for your mobile app. Once added, this will make the event payable to partners.

1. In the impact.com platform, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. In the right column, select [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml?).
3. In the list, find the mobile app that you want to modify and select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768910844/Accessibility%20Icons/More_vNext.svg) **\[More] → Manage Event**.
4. In the top-right corner of the screen, select **Add Event**.
5. Find the In-App Events line item and select **Add Another Event**.
6. Enter an **Event Display Name** — this is simply a name for this event that will appear in the impact.com platform.
7. Enter the **Event Code** for this event — it must be exactly as it appears under the Partner event identifier line in AppsFlyer.
8. Choose a *Crediting Rule* — in most cases, this will be **Last Click**.
9. Select *Add Another Event* to add another, otherwise select **Save**.


# Integrate with Branch

If you're using Branch to manage links & routing to your app(s), you can integrate it with impact.com to track, report, and pay out on various events.

{% hint style="success" %}
**Note:** This article covers the Integration with Branch for a Performance Program. Learn more about how to [Integrate with Branch for your Advocate Program](https://integrations.impact.com/integration-guides/for-brands/advocate/mobile-options-for-advocate/branch-metrics-for-advocate/integrate-with-branch-for-advocate-programs).
{% endhint %}

#### How it works

* In the Branch dashboard, you'll add impact.com as an *Ad Partner* to your account, which enables the standard postbacks. Additional postbacks can be configured to suit your use case.
* Once integrated, you'll create a Branch *Ad Link*, append a necessary query string parameter, then set it as your mobile app(s)'s *Download URL* in the impact.com platform.
* From there, you'll be able to test the integration with a test ad that will forward a user to your app's Branch *Ad Link*. Events that you've configured in the integration and occur in your app will appear as *Actions* in the impact.com platform.

{% hint style="success" %}
**Note:** This guide assumes a developer has already implemented the Branch SDK in your app(s) and completed the *Universal Ads* prerequisite — [learn more](https://help.branch.io/using-branch/page/impact).
{% endhint %}

## Enable the integration

***

1. In the Branch dashboard, select **Ads → Partner Management**.
2. In the Ad Partners sidebar, search for `impact`.
3. Under *More Ad Partners*, select **Impact**.
4. In the *Ad Account Information panel*, add your impact.com account info:<br>

   | **iOS Tracker**           | Input the System App ID of your iOS app. In the impact.com platform, navigate to your [Mobile Apps](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml) to find your System App ID.                |
   | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Android Tracker**       | Input the System App ID of your Android app. In the impact.com platform, navigate to your [Mobile Apps](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml) to find your System App ID.            |
   | **Impact Account SID \*** | In the impact.com platform, navigate to your [API Credentials](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/manage-api-access-tokens-as-a-brand) to find your Account SID. |
   | **Auth Token \***         | In the impact.com platform, navigate to your [API Credentials](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens/manage-api-access-tokens-as-a-brand) to find your Auth Token.  |
5. Select **Save & Enable**.

## Create Branch Ad Link for impact.com

***

Once the integration is enabled and you've configured postbacks, [**Create a Branch Ad Link**](https://help.branch.io/using-branch/docs/ad-links).

{% hint style="success" %}
**Note:** When creating your ad link, make sure to select **Impact as the Ad Partner** to ensure the correct query string parameters are appended.
{% endhint %}

### Update Download URL in impact.com

This section assumes you've already set up an app. See [**Set up Mobile App Tracking**](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/tracking/mobile-app-tracking/set-up-a-mobile-app) in the impact.com Help Center for details on configuring a mobile app.

Configure your newly created *Branch Ad Link* as the *Download URL* for your app in impact.com.

1. In the impact.com platform, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. In the right column, select [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml).
3. In the list, find the mobile app that you want to modify and select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768910844/Accessibility%20Icons/More_vNext.svg) **\[More] → View/Edit**.
4. Find the Download URL line item and **paste in the Ad Link** from Branch, making sure that all query string parameters are present.

## Integration options

***

### Postback config

The *Postback Config* screen is where you can manage the postbacks that Branch is sending to impact.com. Refer to the Postback templates section for common use case examples — the templates can be easily modified with the parameters you want impact.com to receive.

#### Postback templates

For each example, a parameter denoted in brackets indicates this is a value or variable that you need to add in order for the postback to work.

| Parameter               | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| `[AccountSID]`          | Your impact.com Account SID value.                                     |
| `[AuthToken]`           | Your impact.com Auth Token value.                                      |
| `[iOS_SystemAppID]`     | For iOS apps, the impact.com System App ID.                            |
| `[Android_SystemAppID]` | For Android apps, the impact.com System App ID.                        |
| `[UUID_Value]`          | If available, the UUID value that the Branch SDK assigns to a user.    |
| `[ProgramId]`           | Your impact.com Program ID.                                            |
| `[EventTypeId]`         | Your impact.com Event Type ID.                                         |
| `[EventCode]`           | If the event type is using event codes, the case-sensitive event code. |

{% hint style="info" %}
**Tip:** For documentation on API calls, see the API Reference section for the PageLoad and Conversions endpoints.
{% endhint %}

**App Open**

{% tabs %}
{% tab title="App Open" %}

```json
https://trkapi.impact.com/PageLoad?CampaignId=[ProgramID]&PageUrl=${(last_attributed_touch_data.$original_url)!}&CustomProfileId=[UUID_Value]&EventDate=2024-08-01T23:55:24-08:00&AndroidId=${(user_data.android_id)!}&AppleIfa=${ (user_data.idfa)! }&GoogAId=${ (user_data.aaid)! }&ImpactAppId=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os=="IOS">[iOS_SystemAppID]<#elseif bundle.os == "ANDROID">[Android_SystemAppID]</#if><@break/></#if></@loop>
```

{% endtab %}
{% endtabs %}

**App Install / Reinstall (Basic Auth Required)**

{% tabs %}
{% tab title="App Install / Reinstall (Basic Auth Required)" %}

```json
https://[AccountSID]:[AuthToken]@api.impact.com/Advertisers/[AccountSID]/Conversions/?ActionTrackerId=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os=="IOS">[iOS_SystemAppID]<#elseif bundle.os == "ANDROID">[Android_SystemAppID]</#if><@break/></#if></@loop>&AppPackage=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os == "IOS"><@break/><#elseif bundle.os == "ANDROID">${(bundle.android.package_name)!}</#if><@break/></#if></@loop>&AppName=${ (app.name)!}&EventDate=2024-08-01T23:55:24-08:00&EventCode=INSTALL&AndroidId=${(user_data.android_id)!}&AppleIfa=${(user_data.idfa)!}&GoogAId=${(user_data.aaid)!}&AppInstallRef=${(last_attributed_touch_data.AppInstallRef)!}&DeviceOs=${(user_data.os)!}&DeviceOSVer=${(user_data.os_version)!}&IpAddress=${(user_data.ip)!}&ClickId=${(last_attributed_touch_data.~click_id)!}&Oid=${(id)!}&CampaignId=[ProgramId]&CustomProfileId=[UUID_Value]&subID1=${(last_attributed_touch_data.subID1)!}&subID2=${(last_attributed_touch_data.subID2)!}&subID3=${(last_attributed_touch_data.subID3)!}&ShareId=${(last_attributed_touch_data.ShareId)!}&IntegrationSource=BRANCH
```

{% endtab %}
{% endtabs %}

**Lead (Basic Auth Required)**

{% tabs %}
{% tab title="Lead (Basic Auth Required)" %}

```json
https://${ (ad_network.credentials.Account_SID)!}:${ (ad_network.credentials.Authorization_Token)! }@api.impactradius.com/Advertisers/${ (ad_network.credentials.Account_SID)! }/Conversions/?CampaignId=[ProvidedByImpact]&ActionTrackerId=[ProvidedByImpact]&AppPackage=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os=="IOS"><@break/><#elseif bundle.os == "ANDROID">${(bundle.android.package_name)!}</#if><@break/></#if></@loop>&Text1=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os=="IOS">iOSApp<#elseif bundle.os == "ANDROID">AndroidApp</#if><@break/></#if></@loop>&IrAppId=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os=="IOS">[ProvidedByImpact]<#elseif bundle.os == "ANDROID">[ProvidedByImpact]</#if><@break/></#if></@loop>&AppName=${ (app.name)! }&EventDate=2024-08-01T23:55:24-08:00&CustomProfileId=${(user_data.developer_identity)!}&AndroidId=${ (user_data.android_id)! }&AppleIfa=${ (user_data.idfa)! }&GoogAId=${ (user_data.aaid)! }&AppInstallRef=${ (last_attributed_touch_data.AppInstallRef)! }&DeviceOs=${ (user_data.os)!}&DeviceOSVer=${ (user_data.os_version)! }&IpAddress=${ (user_data.ip)! }&ClickId=${ (last_attributed_touch_data.irclickid)! }&ClickId=${ (last_attributed_touch_data.~click_id)! }&Oid=${(event_data.transaction_id)!}&subID1=${ (last_attributed_touch_data.subID1)! }&subID2=${ (last_attributed_touch_data.subID2)! }&subID3=${ (last_attributed_touch_data.subID3)! }&ShareId=${ (last_attributed_touch_data.ShareId)! }&IntegrationSource=BRANCH
```

{% endtab %}
{% endtabs %}

**Conversion (Basic Auth Required)**

{% tabs %}
{% tab title="Conversion (Basic Auth Required)" %}

```json
https://${ (ad_network.credentials.Account_SID)!}:${ (ad_network.credentials.Authorization_Token)! }@api.impactradius.com/Advertisers/${ (ad_network.credentials.Account_SID)! }/Conversions/?CampaignId=[ProvidedByImpact]&ActionTrackerId=[ProvidedByImpact]&AppPackage=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os=="IOS"><@break/><#elseif bundle.os == "ANDROID">${(bundle.android.package_name)!}</#if><@break/></#if></@loop>&Text1=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os=="IOS">iOSApp<#elseif bundle.os == "ANDROID">AndroidApp</#if><@break/></#if></@loop>&IrAppId=<@loop data=app.app_bundles val="bundle"><#if user_data.os == bundle.os><#if bundle.os=="IOS">[ProvidedByImpact]<#elseif bundle.os == "ANDROID">[ProvidedByImpact]</#if><@break/></#if></@loop>&AppName=${ (app.name)! }&EventDate=2024-08-01T23:55:24-08:00&CustomProfileId=${(user_data.developer_identity)!}&AndroidId=${ (user_data.android_id)! }&AppleIfa=${ (user_data.idfa)! }&GoogAId=${ (user_data.aaid)! }&AppInstallRef=${ (last_attributed_touch_data.AppInstallRef)! }&DeviceOs=${ (user_data.os)!}&DeviceOSVer=${ (user_data.os_version)! }&IpAddress=${ (user_data.ip)! }&ClickId=${ (last_attributed_touch_data.irclickid)! }&ClickId=${ (last_attributed_touch_data.~click_id)! }&Oid=${(event_data.transaction_id)!}&CustomerStatus=${(custom_data.UserType)!}&OrderPromoCode=${(event_data.coupon)!}&subID1=${ (last_attributed_touch_data.subID1)! }&subID2=${ (last_attributed_touch_data.subID2)! }&subID3=${ (last_attributed_touch_data.subID3)! }&ShareId=${ (last_attributed_touch_data.ShareId)! }&CurrencyCode=${(event_data.currency)!}&IntegrationSource=BRANCH
```

{% endtab %}
{% endtabs %}

*Item-level data*

When sending item-level conversion data to impact.com, use the following format (replacing `{variable}` in the example with the actual value without curly brackets):

{% tabs %}
{% tab title="Item-level data" %}

```json
&branch-custom=1&ItemCategory=<@urlencode><#if content_items?has_content><@loop data=content_items val="attributes"><@json>{${(attributes.$product_category)!}}</@json><@sep>,</@sep></@loop></#if></@urlencode>&ItemName=<@urlencode><#if content_items?has_content><@loop data=content_items val="attributes"><@json>{${(attributes.$product_name)!}}</@json><@sep>,</@sep></@loop></#if></@urlencode>&ItemSku=<@urlencode><#if content_items?has_content><@loop data=content_items val="attributes"><@json>{${(attributes.$sku)!}}</@json><@sep>,</@sep></@loop></#if></@urlencode>&ItemPrice=<@urlencode><#if content_items?has_content><@loop data=content_items val="attributes"><@json>{${(attributes.$price)!}}</@json><@sep>,</@sep></@loop></#if></@urlencode>&ItemQuantity=<@urlencode><#if content_items?has_content><@loop data=content_items val="attributes"><@json>{${(attributes.$quantity)!}}</@json><@sep>,</@sep></@loop></#if></@urlencode>&revenue=${(event_data.revenue_in_usd)!}
```

{% endtab %}
{% endtabs %}

*Encoded data example*

{% tabs %}
{% tab title="Encoded data example" %}

```json
branch-custom=1&ItemCategory=%22%7Btest1%7D%22%2C%22%7Btest2%7D%22%2C%22%7Btest3%7D%22&ItemSubTotal=%22%7B21.6%7D%22%2C%22%7B20%7D%22%2C%22%7B891%7D%22&ItemSku=%22%7Bsku%7D%22%2C%22%7Bsku2%7D%22%2C%22%7Bsku3%7D%22&ItemQuantity=%22%7B1%7D%22%2C%22%7B2%7D%22%2C%22%7B1%7D%22
```

{% endtab %}
{% endtabs %}

*Decoded data example*

{% tabs %}
{% tab title="Decoded data example" %}

```json
branch-custom=1&ItemCategory="{test1}","{test2}","{test3}"&ItemSubTotal="{21.6}","{20}","{891}"&ItemSku="{sku}","{sku2}","{sku3}"&ItemQuantity="{1}","{2}","{1}"
```

{% endtab %}
{% endtabs %}

### Link Parameters reference

The *Link Parameters* tab shows the default query string parameter mapping between Branch and impact.com — these are added to all generated links by default, and cannot be remapped.

| Branch Parameter    | impact.com Parameter | Description                                                                                                                                                  |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Custom Link Macro   | `{AppInstallRef}`    | Unique Install Referrer retrieved from the Google Play Store. [Learn how to retrieve this value](https://developer.android.com/google/play/installreferrer). |
| Click ID            | `{clickid}`          | impact.com token used to track the customer's journey.                                                                                                       |
| Custom Link Macro   | `{subid1}`           | First Sub-affiliate ID — query string parameter used by impact.com partners for their own reporting.                                                         |
| Custom Link Macro   | `{subid2}`           | Second Sub-affiliate ID — query string parameter used by impact.com partners for their own reporting.                                                        |
| Custom Link Macro   | `{subid3}`           | Third Sub-affiliate ID — query string parameter used by impact.com partners for their own reporting.                                                         |
| Custom Link Macro   | `{sharedid}`         | Shared ID — query string parameter used by impact.com partners that appears in your reporting.                                                               |
| Secondary Publisher | `{irmpname}`         | Name of the impact.com partner.                                                                                                                              |
| Campaign ID         | `{ircid}`            | Your impact.com Program ID value.                                                                                                                            |

### Attribution windows

The *Attribution Windows* tab is where you can customize attribution windows for the impact.com integration. impact.com also provides pre-configured attribution windows for links — select **Use ad partner attribution settings** to use the recommended settings.

[Learn more about Attribution Windows in the Branch Help Center](https://help.branch.io/using-branch/docs/attribution-windows-link-settings).

### Postback testing

The Postback Testing tab offers the ability to test your postbacks before setting them live.

Learn more about how to [Test Postbacks in the Branch Help Center](https://help.branch.io/using-branch/docs/testing-postbacks).


# Integrate with Singular

This guide explains how to integrate your impact.com account with Singular, a Mobile Measurement Partner (MMP), to report iOS and Android mobile events. This integration allows you to track and attribute mobile app conversions driven by your marketing efforts.

### Prerequisites

* You must have an existing impact.com account.
* You must have an existing Singular account with your mobile app(s) configured.
* You’ll need *Administrator* access to both your impact.com and Singular accounts.
* This integration requires a skilled technical resource with a background in web development.

{% stepper %}
{% step %}

### Activate impact.com in your Singular account

1. In Singular, from the left navigation menu, select **Attribution Setup → Partner Configuration**.
2. Search for "Impact" and select ![](/files/gbGEaKuAkSekAQcCkyV2) **\[Add]** **Add App site** for both Android and iOS.
   {% endstep %}

{% step %}

### Configure the impact.com module in your Singular account

To link your accounts, you must provide Singular with your impact.com API credentials and the App install Event Type ID (Tracker ID) assigned to your mobile apps.

1. On the *Partner Configuration* screen, hover over each version of the app and select **Edit**.
2. Select the **Attribution Postbacks & Settings** tab.
3. Below **Impact Parameters**, enter the following:
   * **Account SID/Username**: Your impact.com [Account SID](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens).
   * **Install Action Tracker ID**: Your system app ID. To find your app ID, navigate to ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings →&#x20;*****Tracking*****&#x20;→** [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml).
   * **Account Token**: Your [impact.com Auth Token](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/api-tokens).
4. Select **Next**.
   {% endstep %}

{% step %}

### Map your Singular in-app SDK event names to impact.com event codes

#### Retrieve your SDK event names

1. On the *Impact Partner Configuration* page, select the **In-App Events Postback** tab.
2. Navigate to the *Events Postbacks* section.
3. Capture your app’s SDK Event Names.
   * You'll map these SDK event names to event codes in the *Manage Event Codes* section below.
4. Select **Next**.
5. In the **Advanced Settings** tab, select **Save**.

#### Manage event codes

For each additional in-app event you’re tracking, you’ll need to configure it as an event code for your mobile app. Once added, this will make the event payable to partners.

1. In the impact.com platform, from the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. In the right column, select [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml?).
3. In the list, find the mobile app that you want to modify and select ![](/files/QIUzi1ogqnG2NvotPFQE) **\[More] → Manage Event**.
4. In the top-right corner of the screen, select **Add Event**.
5. Find the In-App Events line item and select **Add Another Event**.
6. Enter an **Event Display Name** — this is simply a name for this event that will appear in the impact.com platform.
7. Enter the **Event Code** for this event — it must be exactly as it appears under the *SDK Event Name* column in Singular.
8. Choose a *Crediting Rule* — in most cases, this will be **Last Click**.
9. Select *Add Another Event* to add another, otherwise select **Save**.
   {% endstep %}

{% step %}

### Retrieve tracking information

Before your integration can go live, you must gather the following specific information. This data is essential for the impact.com team to complete your solution configuration. Once collected, provide these details to your implementation engineer.

#### Identify your iOS Application Identifiers

For the iOS version of your app, you need to provide two unique identifiers:

* **App ID**: The unique numerical ID assigned to your app in the Apple App Store.
* **Bundle ID**: The unique string identifier for your app in the Apple ecosystem, e.g., `com.acme.ios`.

#### Identify your Android Package ID

For the Android version of your app, you must provide the unique application identifier:

* **Package ID**: The unique string identifier for your app in the Google Play Store, e.g., `com.acme.android`.

#### Retrieve your Singular Click Attribution Link

Retrieve your unique Click Attribution Link from your Singular account and share it with your impact.com implementation engineer. The tracking link will be used to attribute traffic coming from impact.com.

1. In Singular, from the left navigation menu, select **Attribution Setup → Manage Links**.
2. Search for “Impact”.
3. Retrieve the impact.com click attribution link.

{% tabs %}
{% tab title="Example" %}
`singularassist.sng.link/D59c0/un48?idfa={AppleIfa}&aifa={GoogAId}&psid={irmpid}&psn={irmpname}&cl={clickid}&pcrn={iradname}&pcid={ircid}&pcrid={iradid}`
{% endtab %}
{% endtabs %}

4. To enable probabilistic matching in Singular, append the param `_smtype=3` to the links.
5. Ensure this link redirects as expected when the user has the app installed, as opposed to not installed.
   {% endstep %}
   {% endstepper %}

### End-to-end testing & event validation

{% stepper %}
{% step %}

### Set up test device(s) in Singular (Optional)

Set up test devices in Singular so that multiple tests can be made from the same device. Refer to [Testing Singular SDK Integration](https://support.singular.net/hc/en-us/articles/360002675072-How-to-Test-Your-Singular-SDK-Integration#Testing_Singular_SDK_Integration) for more information.
{% endstep %}

{% step %}

### Enable mobile fallback

1. Log in to impact.com.
2. Refer to [Create a Text Link Asset](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/ads/create-ads/create-a-text-link-asset) for more information.
3. When creating the asset, only complete the required fields:
   * **Name**: Enter Mobile Test Ad.
   * Set a Default or Custom Landing Page from the ![](/files/JiWIbPyMoIeWpNy8h0ba) **\[Drop-down menu]** and enter the desired Landing Page URL for the asset redirection.
   * ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggle on]** **Mobile Fallback**.
   * If your program is currently active, ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggle on]** **Restrict Partner Access**.
     {% endstep %}

{% step %}

### Generate a test tracking link

1. Log in to impact.com.
2. Refer to [Create Test Actions](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/actions-and-payouts/actions/create-test-actions) for more information.
   {% endstep %}

{% step %}

### Execute the end-to-end conversion test

1. Uninstall your app from your mobile device if it is already installed.
2. Copy and paste the test tracking link in your mobile device’s web browser; the link will direct you to your app store listing.
3. Record the `im_ref` value from the URL in your web browser.
4. Complete a conversion event on your app and record the Order ID and payload parameters.
   * **Recommendations for Sale transactions**: Complete several tests with multiple SKUs, a minimum quantity of 2 for each SKU, and some tests with a promo code & discount, and some without a promo code and discount.
   * **Recommendations for Lead transactions**: Complete several transactions to test variations in payload parameters such as promo codes, notes, or text fields that are relevant to your expected payout conditions.
5. Repeat the process for both iOS and Android devices.
   {% endstep %}

{% step %}

### Validate the end-to-end conversion test

1. Log in to your impact.com user account.
2. From the left navigation bar, select ![](/files/hr700haJWzy65lcXmxJk) **\[Engage] → Transactions → Test Actions**.
3. Find your test conversion(s) based on the `Order Id` you recorded above.
4. Hover over the transaction and select ![](/files/QIUzi1ogqnG2NvotPFQE) **\[More] → View Details** to open the *Test Event Details* screen.
5. Review the conversion payload details, paying attention to revenue, discounts, product details, and any other element that will potentially affect partner payouts.
6. If all the details are as expected, select **Approve**.
7. If any detail is not correct, select **Reject**.
   * If you reject the end-to-end test result, you’ll need to correct the integration and repeat the end-to-end process for that conversion event until you achieve a successful result.

{% hint style="success" %}
**Note:** It may take up to 30 minutes for a test transaction to surface on the *Test Actions* screen. If your test transaction does not appear on the test transaction screen, contact your implementation engineer.
{% endhint %}
{% endstep %}
{% endstepper %}

### Post-integration validation

Once the solution has been in production for 24 hours:

1. Pull a log file from your backend/eCommerce engine that includes the date, time, time zone, order ID, and conversion revenue amount.
2. Include all revenue-related metrics like tax, shipping, discounts, subtotals, etc.
3. Send the data to your implementation engineer for data validation.


# CDP -Customer Data Platform


# Integrate with Segment

If you use Segment to track certain events, you can add impact.com as a Destination function so that your impact.com program receives events from Segment. The integration supports both web and mobile (iOS & Android) events.

#### How it works

* In the impact.com platform, you can set up an OAuth connection between your Segment account and your impact.com brand account that supports multiple sources.
* From the Segment spec, four API calls are supported: *Track*, *Page*, *Screen*, and *Identify*. Event names within each of these APIs can be mapped to either *Page Load*, *Install*, or *Action* event names in impact.com.
* Once configured, impact.com will start receiving event data from Segment through the destination based on your specific configuration.

#### Implementation overview

1. Connect your impact.com brand account to your Segment account.
2. Configure Segment event mappings to impact.com Event Types.
3. Verify parameters in your Segment schema are mapped correctly to impact.com.
4. Configure custom parameter mapping to pass parameters that don’t fit the standard Segment specs into impact.com.

## Connect impact.com to Segment

***

The steps below will connect your impact.com brand account to your Segment account and enable your first Segment source.

1. From the top navigation bar, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings**.
2. In the right column, go to the *Tracking* section and select [**General**](https://app.impact.com/secure/advertiser/fr/general-tracking-settings.ihtml).
3. In the *Segment Traffic* section, select **Connect Segment Account**.

<div data-with-frame="true"><figure><img src="/files/IuV6bihQl6eKaI5Yu8Ih" alt="" width="503"><figcaption></figcaption></figure></div>

4. Once redirected to Segment, **log in to your Segment account**.
5. On the *Authorize* screen, select:
   * The **Workspace** that impact.com can access.
   * The **Source** that impact.com can access.
6. Select **Allow**. You'll be redirected back to the impact.com platform.
7. Confirm that the *Enable with Segment* line now reads **Successfully connected**.

<div data-with-frame="true"><figure><img src="/files/GiV2BDlW2m9wQbzbXolV" alt="" width="563"><figcaption></figcaption></figure></div>

If you want to add another Segment source to your impact.com brand account, repeat the above steps for any remaining sources — in Step 5, choose the other source you want to connect.

## Destination/Connection Settings reference

***

The table below organizes and describes each of the available settings and configuration options for the impact.com destination function. Items with a red asterisk (**\***) are required.

| Name                        | Description                                                                                                                                                                                                                                                                                                                                                           | Type      |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| Account SI&#x44;**\***      | Your impact.com account Account SID. This is automatically filled as part of the installation procedure and is always required.                                                                                                                                                                                                                                       | `STRING`  |
| API Ke&#x79;**\***          | Your impact.com account Auth Token value. This is automatically filled as part of the installation procedure and is always required.                                                                                                                                                                                                                                  | `STRING`  |
| Campaign I&#x44;**\***      | Unique identifier for the Program (or Campaign) in your impact.com account. This is automatically filled as part of the installation procedure and is always required.                                                                                                                                                                                                | `STRING`  |
| Enable Page Events          | **Required for web tracking**. Enables *Page* events to be tracked within impact.com.                                                                                                                                                                                                                                                                                 | `BOOLEAN` |
| iOS App ID                  | **Required for iOS mobile app tracking**. To find your *System App ID* in impact.com for your iOS App, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings** and then select [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml).                                                   | `STRING`  |
| Android App ID              | **Required for Android mobile app tracking**. To find your *System App ID* in impact.com for your Android App, select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings** and then select [**Mobile Apps**](https://app.impact.com/secure/advertiser/tracking-settings/mobileapps/view-mobile-apps-flow.ihtml).                                           | `STRING`  |
| Action Event Names          | List of Segment track events that correspond to a user registration, completed order or other payable event. If multiple events need to be tracked as actions in impact.com, please add all events to the array (e.g., `Order Completed`, `User Registered`, etc.). This helps us send your events to the correct impact.com endpoint. Defaults to `Order Completed`. | `ARRAY`   |
| Custom Mapping for Products | Use instead of *Custom Parameter Mapping* for mapping parameters in Segment’s products array. See the *Custom Parameter Mapping for Products* section to learn more.                                                                                                                                                                                                  | `MAP`     |
| Custom Parameter Mapping    | Mapping for any non-default parameters that were specified by impact.com. See the *Custom Parameter Mapping* section to learn more.                                                                                                                                                                                                                                   | `MAP`     |
| Enable Identify Events      | Enables *Identify* events to be tracked within impact.com.                                                                                                                                                                                                                                                                                                            | `BOOLEAN` |
| Enable Screen Events        | Enables *Screen* events to be tracked within impact.com.                                                                                                                                                                                                                                                                                                              | `BOOLEAN` |
| Event Type ID               | Unique identifier for the event type (or action tracker) used to track events in impact.com. If left blank, defaults to the event name from Segment to map to impact.com's event types. Confirm with your CSM (or support) to ensure this is correct.                                                                                                                 | `STRING`  |
| Install Event Names         | List of Segment *Track* events that correspond to the app install event. Defaults to `Application Installed`. See the note about application installed events to learn more.                                                                                                                                                                                          | `ARRAY`   |
| Page Load Event Names       | List of Segment track events that correspond to an app open or page load. Defaults to `Application Opened`. Note that events from *Page*, *Screen* or *Identify* are enabled separately with the toggle options and are automatically considered page load events in impact.com's platform.                                                                           | `ARRAY`   |

## Segment Spec: Track calls

***

The [Segment `track` API call](https://segment.com/docs/connections/spec/track/) can send event data to impact.com via the `Conversions` endpoint or the `PageLoad` endpoint, depending on your configuration.

* `track` events sent to the `Conversions` endpoint will be reported as conversions to impact.com, which are attributed to a partner and appear as an action in the impact.com platform (*Action Event Names* in the Destination/Connection settings).
* `track` events sent to the `PageLoad` endpoint may be reported as a Click if they fit that definition (e.g., a `track` call sent to `PageLoad` that counts as a Click is an *Application Opened* event — a visitor opened your mobile app). These can be customized to fit your specific needs.

<details>

<summary>Example Track Call: Click to view the complete payload</summary>

JSON

```json
   {
     "type": "track",
     "event": "Order Completed",
     "userId": "AiUGstSDIg",
     "anonymousId": "7c4f9a82-5b1d-41e0-b2c3-8fa912d4e27b",
     "messageId": "msg-abcdef-1234567890",
     "timestamp": "2025-09-16T22:05:00.000Z",
     "properties": {
       "order_id": "50314b8e9bcf000000000000",
       "total": 57.50,
       "revenue": 55.00,
       "shipping": 2.50,
       "tax": 0,
       "discount": 5.00,
       "coupon": "FALL5",
       "currency": "USD",
       "products": [
         {
           "product_id": "prod_001",
           "sku": "ABC123",
           "name": "T-Shirt",
           "price": 20.00,
           "quantity": 1,
           "category": "Apparel"
         },
         {
           "product_id": "prod_002",
           "sku": "XYZ456",
           "name": "Jeans",
           "price": 40.00,
           "quantity": 1,
           "category": "Apparel"
         }
       ]
     },
     "context": {
       "ip": "123.123.123.123",
       "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
       "locale": "en-US",
       "page": {
         "url": "https://www.example.com/checkout/thank-you",
         "path": "/checkout/thank-you",
         "referrer": "https://www.example.com/cart",
         "title": "Thank You For Your Order"
       }
     }
   }
```

</details>

impact.com passes a unique `im_ref` query string parameter into the landing page URL when redirecting the user through our tracking domains. The value associated with this parameter is used to perform attribution analysis.

If you're using a Segment JavaScript source on every page of your site, this value is automatically received from Segment (e.g. as part of `context.page.url`). This works similarly for in-app events, where the Segment Mobile (iOS or Android) source captures an `Application Opened` event, which is reported to impact.com alongside the `anonymousId` generated by Segment.

If you’re not using the Segment JavaScript source on every page or the `anonymousId` is not consistently populated on *Track* and *Page* events, we recommend you cache this value in the user’s browser or app (using a cookie or app storage) to pass along with track events — see the Advanced options section.

### Track events mapping

impact.com can track multiple events from Segment, but they need to be mapped to corresponding Event Types in your impact.com account. These can be configured as Event Codes for your event types.

Before beginning, go to the Sources screen in your Segment account and take note of your Events names with the Track type:

<div data-with-frame="true"><figure><img src="/files/B4u6faOy4pRD0ZCd39Tm" alt="" width="563"><figcaption></figcaption></figure></div>

1. Sign in to impact.com and select ![](/files/NAwewjCC7OYTjHnAmreE) **\[User profile] → Settings** from the top navigation bar.
2. In the right column, go to the *Tracking* section and select [**Event Types**](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml).

<div data-with-frame="true"><figure><img src="/files/qkVED9toB7qEbi5tojvM" alt=""><figcaption></figcaption></figure></div>

3. On the [**Event Types**](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml) screen, hover your cursor over the right-most column and select ![](https://res.cloudinary.com/product-enablement/image/upload/v1768910844/Accessibility%20Icons/More_vNext.svg)**\[More] → View/Edit**.

<div data-with-frame="true"><figure><img src="/files/U4ttzOl1Dm2tUbNIsnTr" alt=""><figcaption></figcaption></figure></div>

4. Next to the *Codes* line item, select ![](https://res.cloudinary.com/product-enablement/image/upload/v1769162858/Accessibility%20Icons/Edit_light.svg) **\[Edit]**.
5. In the text field, enter your Segment Track event name exactly as it appeared in Segment (case-sensitive & punctuation-sensitive).
6. Select **Save**.

### Track events parameter mapping reference

| impact.com Parameter                       | Segment Property                                                                                                                       |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `AppleAdTrack`                             | `context.device.adTrackingEnabled`                                                                                                     |
| `AppleIfa`                                 | `context.device.advertisingId`                                                                                                         |
| `AppleIfv`                                 | `context.device.id`                                                                                                                    |
| `AppName`                                  | `context.app.name`                                                                                                                     |
| `AppPackage`                               | `context.app.namespace`                                                                                                                |
| `AppVer`                                   | `context.app.version`                                                                                                                  |
| `CampaignId`                               | `settings.campaignId`                                                                                                                  |
| `ClickId`<sup>\[1]</sup>                   | `context.referrer.id`                                                                                                                  |
| `CurrencyCode`                             | `properties.currency`                                                                                                                  |
| `CustomerEmail`<sup>\[2]</sup>             | `context.traits.email \|\| properties.email`                                                                                           |
| `CustomerId`<sup>\[3]</sup>                | `userId`                                                                                                                               |
| `CustomerStatus`                           | `context.traits.status`                                                                                                                |
| `CustomProfileId`                          | `anonymousId`                                                                                                                          |
| `DeviceCarrier`                            | `context.network.carrier`                                                                                                              |
| `DeviceLocale`                             | `context.locale`                                                                                                                       |
| `DeviceMfr`                                | `context.device.manufacturer`                                                                                                          |
| `DeviceModel`                              | `context.device.model`                                                                                                                 |
| `DeviceOs`                                 | `context.device.type \|\| context.os.name`                                                                                             |
| `DeviceOsVer`                              | `context.os.version`                                                                                                                   |
| `EventCode`                                | `INSTALL`                                                                                                                              |
| `EventDate`                                | `timestamp`                                                                                                                            |
| `EventTypeCode`                            | `event`                                                                                                                                |
| `EventTypeId`                              | `settings.eventTypeId`                                                                                                                 |
| `GoogAId`                                  | `properties.advertisingId`                                                                                                             |
| `IpAddress`                                | `context.ip`                                                                                                                           |
| `ItemBrand{i}`                             | `properties.products[i].brand`                                                                                                         |
| `ItemCategory{i}`                          | `properties.products[i].category`                                                                                                      |
| `ItemName{i}`                              | `properties.products[i].name`                                                                                                          |
| `ItemPrice{i}`                             | `properties.products[i].price`                                                                                                         |
| `ItemPromoCode{i}`                         | `properties.products[i].coupon`                                                                                                        |
| `ItemQuantity{i}`                          | `properties.products[i].quantity`                                                                                                      |
| `ItemSku{i}`                               | `properties.products[i].sku`                                                                                                           |
| `Latitude`                                 | `context.location.latitude`                                                                                                            |
| `Longitude`                                | `context.location.longitude`                                                                                                           |
| `OrderDiscount`                            | `properties.discount`                                                                                                                  |
| `OrderId`                                  | `properties.orderId \|\| properties.order_id \|\| properties.transactionID \|\| properties.messageId \|\| messageId \|\|"IR_AN_64_TS"` |
| `OrderPromoCode`                           | `properties.coupon`                                                                                                                    |
| `OrderShipping`                            | `properties.shipping`                                                                                                                  |
| `OrderSubTotalPostDiscount`<sup>\[4]</sup> | `properties.revenue`                                                                                                                   |
| `OrderTax`                                 | `properties.tax`                                                                                                                       |
| `ReferringUrl`                             | `context.referrer.url \|\| context.page.referrer`                                                                                      |
| `PageUrl`                                  | `context.page.url \|\| properties.url \|\| context.page.referrer \|\| context.referrer.url`                                            |
| `UserAgent`                                | `context.userAgent`                                                                                                                    |

<sup>\[1]</sup> — See the Using Click ID section in Advanced options. Note, Click ID is only mapped when the referrer.type is set to impactRadius.

<sup>\[2]</sup> — Email address will be SHA1 hashed (with a HEX output type) prior to being sent to impact.com. The email input is expected to be plain text (e.g. <example@company.com>).

<sup>\[3]</sup> — `Customerid` value in the page load needs to be 7 or more characters, with 3 being distinct, and without whitespace.

<sup>\[4]</sup> — this field will only be passed if the products array is not defined. The impact.com Destination expects that revenue will exclude discount. If necessary, this mapping can be overridden through the Custom Parameter Mapping option in the Destination Settings.

## Segment Spec: Page calls

***

The [Segment `page` API call](https://segment.com/docs/connections/spec/page/) is used to record when a visitor sees a page of your website, along with additional properties about the page.

{% hint style="success" %}
**Note:** If you’re tracking web events, `page` calls are required calls that should be enabled in the Destination/Connection settings of impact.com within Segment.
{% endhint %}

<details>

<summary>Example Page Call: Click to view the complete payload</summary>

JSON

```json
{
  "type": "page",
  "anonymousId": "7c4f9a82-5b1d-41e0-b2c3-8fa912d4e27b",
  "messageId": "msg-homepage-123456",
  "timestamp": "2025-09-16T20:35:00.000Z",
  "name": "Homepage",
  "context": {
    "ip": "123.123.123.123",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "locale": "en-US",
    "page": {
      "url": "https://www.example.com/?im_ref=QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0&utm_source=partnerships",
      "path": "/",
      "referrer": "https://partner.example.test",
      "title": "Welcome to Example Store"
    }
  }
}
```

</details>

`Page` calls are sent to impact.com via the `PageLoad` endpoint of the impact.com Brand API. They may appear as Clicks if they fit the definition of a unique click, which you can customize.

{% hint style="success" %}
**Note:** For impact.com to correctly track and attribute actions, it is important to receive the `page` analytics call on every page load within the website (e.g. not just the home page visit).
{% endhint %}

### Enable Page Events

1. Log in to your Segment account and select **Connections**.
2. Select **Destinations** and find the impact.com destination.
3. Under *Connection Settings*, select ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggle] Enable Page Events**.

#### Page Events parameter mapping reference

| `AppleIfa`                  | `context.device.advertisingId`                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| `AppleIfv`                  | `context.device.id`                                                                         |
| `AppName`                   | `context.app.name`                                                                          |
| `AppPackage`                | `context.app.namespace`                                                                     |
| `AppVer`                    | `context.app.version`                                                                       |
| `CampaignId`                | `settings.campaignId`                                                                       |
| `CustomerEmail`             | `context.traits.email \|\| properties.email`                                                |
| `CustomerId`<sup>\[1]</sup> | `userId`                                                                                    |
| `CustomProfileId`           | `anonymousId`                                                                               |
| `DeviceCarrier`             | `context.network.carrier`                                                                   |
| `DeviceLocale`              | `context.locale`                                                                            |
| `DeviceMfr`                 | `context.device.manufacturer`                                                               |
| `DeviceModel`               | `context.device.model`                                                                      |
| `DeviceOs`                  | `context.device.type \|\| context.os.name`                                                  |
| `DeviceOsVer`               | `context.os.version`                                                                        |
| `EventDate`                 | `timestamp`                                                                                 |
| `GoogAId`                   | `properties.advertisingId`                                                                  |
| `ImpactAppId`               | `settings.appId \|\| context.app.namespace`                                                 |
| `IpAddress`                 | `context.ip`                                                                                |
| `PageUrl`                   | `context.page.url \|\| properties.url \|\| context.page.referrer \|\| context.referrer.url` |
| `ReferringUrl`              | `context.referrer.url \|\| context.page.referrer`                                           |
| `UserAgent`                 | `context.userAgent`                                                                         |

<sup>\[1]</sup> – `Customerid` value in the page load needs to be 7 or more characters, with 3 distinct and without whitespace.

## Segment Spec: Screen calls

***

The [Segment screen API call](https://segment.com/docs/connections/spec/screen/) is used to record when a visitor sees a screen of a mobile app — essentially the mobile equivalent of the page call.

{% hint style="info" %}
**Tip:** `screen` calls are optional calls that you can enable in the Destination/Connection settings of impact.com within Segment.
{% endhint %}

<details>

<summary>Example Screen Call: Click to view the complete payload</summary>

JSON

```json
{
  "type": "screen",
  "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
  "messageId": "msg-screen-homepage-123456",
  "timestamp": "2025-09-16T22:50:00.000Z",
  "name": "Homepage",
  "context": {
    "ip": "123.123.123.123",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
    "locale": "en-US",
    "app": {
      "name": "Example Store App",
      "version": "1.0.0",
      "build": "100"
    }
  }
}
```

</details>

`Screen` calls are sent to impact.com via the `PageLoad` endpoint of the impact.com Brand API. They may appear as Clicks if they fit the definition of a unique click, which you can customize.

Parameter mapping for *Screen* in impact.com is the same as *Page*.

### Enable Screen Events

1. Log in to your Segment account and select **Connections**.
2. Select **Destinations** and find the impact.com destination.
3. Under *Connection Settings*, select ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggle on] Enable Screen Events**.

## Segment Spec: Identify calls

***

The [Segment Identify API call](https://segment.com/docs/connections/spec/identify/) is used to associate a user with their actions and record traits about that user.

{% hint style="info" %}
**Tip:** `Identify` calls are optional calls that you can enable in the Destination/Connection settings of impact.com within Segment.
{% endhint %}

<details>

<summary>Example Identify Call: Click to view the complete payload</summary>

JSON

```json
{
  "type": "identify",
  "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
  "userId": "AiUGstSDIg",
  "messageId": "msg-identify-123456",
  "timestamp": "2025-09-16T22:51:00.000Z",
  "context": {
    "ip": "123.123.123.123",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
  }
}
```

</details>

`Identify` calls are sent to impact.com via the `PageLoad` endpoint of the impact.com Brand API, enabling impact.com to update the user identifiers for more accurate correlation.

### Enable Identify Events

1. Log in to your Segment account and select **Connections**.
2. Select **Destinations** and find the impact.com destination.
3. Under *Connection Settings*, select ![](/files/nF7DY0rLLPpjNDQb5LMS) **\[Toggle] Enable Identify Events**.

## Advanced options

### Custom parameter mapping

***

Custom Parameter Mapping enables customized mapping for a parameter. If a default parameter mapping is inconsistent with your schema (or you’ve been advised to create custom mappings), this setting enables you to specify the new parameter names.

#### Configure a Custom Parameter Mapping

1. Log in to your Segment account and select **Connections**.
2. Select **Destinations** and find the impact.com destination.
3. Under Connection Settings, select **Custom Parameter Mapping**.
4. In the left column, input the impact.com parameter that you want to re-map, and in the right column, input the Segment parameter you want to remap to (see the example below):

<div data-with-frame="true"><figure><img src="/files/gkx5zuyIIu8WheySYLqi" alt="" width="563"><figcaption></figcaption></figure></div>

By default, `CustomerStatus` is mapped to `context.traits.status`. In the screenshot above, it's being remapped to `properties.customer_status`.

5. For another mapping, select **Add row** and input a new parameter.
6. Repeat for any more custom mappings, then select **Save**.

## Custom mapping for products

***

Use this setting instead of *Custom Parameter Mapping* when overriding the default mapping in the products array. Only mapping of parameters from the products array in Segment are supported.

For example, you can map `ItemPrice` to `product_revenue` as below — see the code example below that illustrates the products array and the `product_revenue` parameter as passed in the array:

{% tabs %}
{% tab title="JSON" %}

```json
{
    "event": "Order Completed",
    "messageId": "123",
    "originalTimestamp": "2021-02-21T11:10:56-04:00",
    "properties": {
      "products": [
        {
          "name": "My Product Name 1",
          "product_revenue": 20,
          "quantity": 1,
          "sku": "my-product-1"
        },
        {
          "name": "My Product Name 2",
          "product_revenue": 20,
          "quantity": 2,
          "sku": "my-product-2"
        }
      ],
      "revenue": 60,
      "shipping": 10,
      "subtotal": 70,
      "tax": 0
    },
    "receivedAt": "2021-02-21T15:10:57.013Z",
    "sentAt": "2021-02-21T15:10:56.000Z",
    "timestamp": "2021-02-21T15:10:57.013Z",
    "type": "track",
    "userId": "abc-12345-6789"
  }
```

{% endtab %}
{% endtabs %}

#### Configure a Custom Mapping for Products

1. Log in to your Segment account and select **Connections**.
2. Select **Destinations** and find the impact.com destination.
3. Under Connection Settings, select **Custom Mapping for Products**.
4. In the left column, input the impact.com parameter that you want to re-map, and in the right column, input the Segment parameter you want to remap to (see the example below):

<div data-with-frame="true"><figure><img src="/files/rcvJXAsTUmeO1rotXJ7P" alt="" width="563"><figcaption></figcaption></figure></div>

5. For any more custom mappings, select **Add row** and input new parameters.
6. When you've finished, select **Save**.

### Attributing Track events

***

If you’re not using the Segment JavaScript source on every page or the `anonymousId` is not consistently populated on Track and Page events, we recommend you cache this value in the user’s browser or app (using a cookie or app storage) to pass along with track events.

#### Using Click ID

You can find the value in the query string of the URL. The default parameter is `im_ref=`, but be sure to verify in the Gateway Tracking Settings of your impact.com brand account. Set context.referrer.id to `clickid`, and set context.referrer.type to `impactRadius`. See the context.referrer object example below:

{% tabs %}
{% tab title="Python" %}

```python
analytics.track('Some Conversion Event' { someProperty: true }, {
  context: {
    referrer: {
      type: 'impactRadius',
      id: [CACHED_CLICK_ID]
    }
  }
})
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
**Note:** *Application Installed* events supports real-time correlation between the app store click and install, meaning you wouldn’t need to pass a `clickId` on an *Application Installed* event or any other install event name as specified in *Install Event Names* within your Destination/Connection settings.
{% endhint %}

#### Other methods

impact.com uses `anonymousId` to associate events with the same user’s journey and attribute track events to the original referring event. However, it is common that an advertiser will track initial events like a Sign-up using a Segment Mobile (iOS or Android) or JavaScript source and subsequent events like a Conversion using a server-side source. Whereas `anonymousId` is provided in the former, it’s usually not present in any of the requests from server-side sources.

The first example below illustrates the problem where we don’t have a common identifier to associate the Page event to the subsequent Sign-Up event. The following options provide 3 different solutions that would allow advertisers to ensure accurate correlation of the page event, containing the referrer information, and subsequent track events.

<div data-with-frame="true"><figure><img src="/files/G3LwJw7TIPkjO4yyFqWj" alt="" width="563"><figcaption></figcaption></figure></div>

#### Use Repeater Destinations to Split Traffic from a Single Source to Multiple Destinations

This approach involves replicating a source using the [Segment Repeater destination](https://segment.com/docs/connections/destinations/catalog/repeater/) so that different sources can be configured with different impact.com destinations that have different settings (i.e., different campaigns or parameter mapping).

1. **Create a new Segment source** and take a note of the write key.
2. Navigate to the original source and **add the Segment-maintained Repeater destination from the Segment Catalog**.
3. Configure the Repeater destination **with the write key** for the new Segment source created in step 1.
4. For the Repeater destination, **add a filter** to only receive data based on a custom property (e.g., `properties.region = United States`).
5. **Add the impact.com destination** to the new source created in step 1 and configure the desired destination settings.
6. **Add the impact.com destination** to the original source and configure it with a different set of settings.
7. **Add a filter to the impact.com destination** associated with the original source to receive data based on a mutually exclusive custom property, which can be the same custom property as configured in step 4 (e.g., `properties.region = Canada`).

<br>


# CRM - Customer Relationship Management


# Integrate with HubSpot

{% hint style="success" %}
Looking to integrate with Advocate? Refer to [Integrate with HubSpot for Advocate](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-hubspot-for-advocate) for additional instructions.
{% endhint %}

The impact.com / HubSpot extension can receive event data (e.g., lead form submissions) from HubSpot and track it as an action within the impact.com platform. You'll be able to identify specific event conditions that represent a conversion event, then configure a flexible mapping of data points to be sent from HubSpot to impact.com.

The most common use case is using HubSpot to monitor changes in status for contacts and deals (such as a lead turning into a sale), then reporting that data to impact.com as a conversion. From there, you can use the contracting and payment features of impact.com to credit partners for those actions.

This integration supports the following standard HubSpot objects:

* Deals
* Companies
* Contacts

## Prerequisites

***

{% hint style="success" %}
**Note:** You must activate consent for every single HubSpot entity for which you want to report conversions. You must also map all required impact.com fields for the conversion to be successful.
{% endhint %}

This section covers the prerequisites to meet before installing the impact.com app to your HubSpot account.

## Tracking Leads via impact.com or HubSpot

#### **Track leads via impact.com**

Events can be tracked using the impact.com UTT (Universal Tracking Tag), which is a small piece of JavaScript code that can be loaded using a Tag Manager solution, or placed manually on your website. Using the UTT offers richer user-level reporting in impact.com, supports *Direct Tracking* features, and more.

If you're planning to track lead events using the UTT, the *Customer ID* value sent via the `TrackConversion` function must also be available to the HubSpot objects that are being monitored and reported on. In other words, HubSpot needs to receive a Customer ID value in order for the integration to accurately correlate events.

#### **Track leads via HubSpot**

Lead submission can also be tracked through HubSpot. Impact appends an `im_ref` parameter + dynamic value (per click) on your landing page URLs. Example link: `yourdomain.com?im_ref=ref123`. The `im_ref` value (`ref123`) must be captured and stored. When the user submits the lead form, the `im_ref` value must be sent in a hidden field to HubSpot. There must be a consistent ID available in HubSpot objects that are being monitored and reported on to send in the `CustomerId` parameter.

{% hint style="success" %}
**Note:** If you're already tracking events with HubSpot or plan to do so, you can skip to [installing impact.com in HubSpot](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-hubspot).
{% endhint %}

### Event Trigger Availability

Before planning your integration, review the limited set of predefined event triggers available within the impact.com plugin in HubSpot. Any custom-defined triggers in your HubSpot account will not be reflected as options in the event trigger drop-down menu.

### Check before integrating

impact.com will complete several integration steps on your behalf. Check with your implementation engineer to ensure that the following configuration steps have been completed: *Event Type*, *Gateway Tracking*, *General Tracking*.

## Install & connect impact.com in HubSpot

***

Once your impact.com is configured, you can install & connect the impact.com / HubSpot extension to your HubSpot account. Then, configure field mappings so that data appears in both platforms as expected.

### Install the impact.com app

1. Navigate to the [**Connector website**](https://hubspot-integration.impact.com/login).

<div data-with-frame="true"><figure><img src="/files/cHF8NgVIahZDHMgX4hR9" alt="" width="375"><figcaption></figcaption></figure></div>

2. Select **Click here to login through HubSpot**, then log in with your HubSpot credentials.

<div data-with-frame="true"><figure><img src="/files/RajBIyZZQDxpDvTO0pRj" alt="" width="375"><figcaption></figcaption></figure></div>

3. Select the HubSpot account you want to connect, then select **Choose Account**.

<figure><img src="/files/E3GEaNe3LX8tcYKf3NpF" alt="" width="375"><figcaption></figcaption></figure>

4. Review the access that impact.com is requesting, then select **Connect app**.

<div data-with-frame="true"><figure><img src="/files/IiqjoLXjRoIzZhGrvufk" alt="" width="350"><figcaption></figcaption></figure></div>

Once completed, you'll be redirected back to the app configuration page to enable and configure it.

### Connect your impact.com account

1. Navigate to the [**Connector website**](https://hubspot-integration.impact.com/login) — in the impact.com / HubSpot plugin menu, select **Settings**.

<div data-with-frame="true"><figure><img src="/files/FTkbHpdwPMRqpt3NTRUF" alt="" width="563"><figcaption></figcaption></figure></div>

2. Add your *Account SID*, *Auth Token*, and *Program ID*:

| Value              | Where to find it                                                                                                                                                                                                            |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account SID \*** | In the impact.com platform, navigate to your API Credentials.                                                                                                                                                               |
| **Auth Token \***  | In the impact.com platform, navigate to your API Credentials.                                                                                                                                                               |
| **Program ID \***  | <p>In the impact.com platform, select your account name in the upper-left corner and copy the gray numeric string below your program name in the right column.</p><p><br><img src="/files/gPZ9JQKGST9iStZEa6oG" alt=""></p> |

3. Select **Submit** to connect your impact.com account.

### Configure the impact.com / HubSpot app

### Enable event triggers

Use the *Event Triggers* screen to enable and disable the types of events you want to track in impact.com.

1. Set an event trigger to **Active** if you want impact.com to track a conversion (and thus, create an action) when a record of the specified event is *created*.

<div data-with-frame="true"><figure><img src="/files/16UOoSEFwCiDk0g02pH9" alt="" width="563"><figcaption></figcaption></figure></div>

2. Select **Add trigger** for an event if you want impact.com to track a conversion (and thus, create an action) when a record of the specified event is *modified*.

<div data-with-frame="true"><figure><img src="/files/ic4t19GPUjfV8ZRfWcZX" alt="" width="563"><figcaption></figcaption></figure></div>

3. Adding multiple triggers acts as an `OR` statement. For example, if `Deal Type (dealtype)` and `Deal Name (dealname)` are added, a conversion event will be created whenever either field is modified.

<div data-with-frame="true"><figure><img src="/files/wbJXDI8x3Qwz6DAZH68V" alt="" width="563"><figcaption></figcaption></figure></div>

### Configure field mappings

The *Field Mappings* section is where you can specify which HubSpot fields are associated with impact.com fields to ensure accurate conversion (and action) reporting in impact.com.

<div data-with-frame="true"><figure><img src="/files/ytWmvBjDtnApYb932N2u" alt="" width="563"><figcaption></figcaption></figure></div>

Below are examples of field mappings for companies.

<div data-with-frame="true"><figure><img src="/files/Tzei8sR88MlxNsAc1Tuv" alt="" width="563"><figcaption></figcaption></figure></div>

* Select **Add mapping** under an event to map a HubSpot field to an impact.com field.

<div data-with-frame="true"><figure><img src="/files/vhXYltyp7oDwQEUCMOqR" alt="" width="563"><figcaption></figcaption></figure></div>

Refer to the tables below for examples of associated mappings. For each section, select **Add mapping** to add them.

{% hint style="success" %}
**Note:** These are example mappings that show different configurations. Choose mappings that apply to your integration, since you probably won't need them all.
{% endhint %}

#### Contacts

Only use `contact_[lead_status]_id` as a Contact's unique identifier when lead status is updated consistently at every stage of your HubSpot conversion funnel.

For `OrderId`, you have two recommendations depending on how consistently lead status is updated:

* **Lead status updated at every stage:** Map `contact_[lead_status]_id` to `OrderId`.
* **Lead status not updated at every stage:** Do not use `contact_[lead_status]_id` at all. Instead, map `hs_object_id` to `OrderId` (without removing the mapping of `hs_object_id` to `CustomerId`).

| HubSpot Field (Parameter)                                                       | impact.com Field   |
| ------------------------------------------------------------------------------- | ------------------ |
| `Lifecycle Stage (lifecyclestage)`                                              | `EventTypeCode`    |
| `Contact ID (hs_object_id)`                                                     | `CustomerId`       |
| `Contact Lead Status ID (contact_[lead_status]_id)` — only use when recommended | `OrderId`          |
| `Last Modified Date (lastmodifieddate)`                                         | `EventDate`        |
| `Company Name (company)`                                                        | `Text3`            |
| `City (city)`                                                                   | `CustomerCity`     |
| `Country/Region (country)`                                                      | `CustomerCountry`  |
| `Postal Code (zip)`                                                             | `CustomerPostCode` |
| `Impact Click ID (custom_impact_click_id)`                                      | `ClickId`          |

#### Deals

If you intend to configure mappings for multiple HubSpot object types (e.g., Contacts and Deals), the `CustomerId` must remain consistent across all event types. To achieve this, ensure *Deal* events reference the associated *Contact*’s `hs_object_id` rather than the Deal’s own `hs_object_id`.

**Before configuring Deals mappings:**

1. Create a **custom** Deal property to use as an ID.
2. Use a HubSpot workflow to populate this field automatically when a Deal is created with the associated *Contact*’s `hs_object_id`.
3. Map this custom property with `CustomerId` to ensure consistent event linking across object types.

| HubSpot Field (Parameter)                                                            | impact.com Field |
| ------------------------------------------------------------------------------------ | ---------------- |
| `Deal Stage (deal_[deal stage])`                                                     | `EventTypeCode`  |
| Custom `Deal ID` property (populated with the associated *Contact*'s `hs_object_id`) | `CustomerId`     |
| `Deal Stage ID (deal_[stage]_id)`                                                    | `OrderId`        |
| `Last Modified Date (hs_lastmodifieddate)`                                           | `EventDate`      |
| `Close Date (closedate)`                                                             | `Text3`          |
| `Deal Stage Probability (hs_deal_stage_probability)`                                 | `Text2`          |
| `Amount (amount)`                                                                    | `OrderSubTotal`  |

#### Line items

You can add the following field mappings to your deals mapping to include specific line item attributes:

| HubSpot Field                            | impact.com Field |
| ---------------------------------------- | ---------------- |
| `Line item hs_sku (line_item{i}.hs_sku)` | `ItemSku{i}`     |
| `Line item name (line_item{i}.name)`     | `ItemName{i}`    |
| `Line item price (line_item{i}.price)`   | `ItemPrice{i}`   |

For more information, see a detailed example in [HubSpot Line Items](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/crm-customer-relationship-management/integrate-with-hubspot).

{% hint style="success" %}
**Note:** If you have set up any custom fields that are not available in the mapping dropdown, try refreshing the custom fields by selecting the ![](https://files.readme.io/6268af0-refresh.png) **\[Circle]** next to the section title.
{% endhint %}

### Uninstall impact.com from HubSpot

***

#### Uninstall in HubSpot

Uninstalling impact.com in HubSpot will essentially pause the integration — if objects are updated or changed in HubSpot, it won't be reported to impact.com. Your settings will remain the same in case you wish to reinstall the integration in the future.

1. Log in to your HubSpot account — in the top navigation bar, select **Settings.**

<div data-with-frame="true"><figure><img src="/files/e9Hal1FIAj2KmPdhGvEb" alt="" width="563"><figcaption></figcaption></figure></div>

2. In the left navigation menu, select **Integrations → Connected Apps**.
3. Find the *Scale partnerships: impact.com* app and select **Actions → Uninstall**.

<div data-with-frame="true"><figure><img src="/files/qs3VojYRu7HzfcRG3ptk" alt="" width="563"><figcaption></figcaption></figure></div>

4. Read the prompt, type `uninstall` into the text field and select **Uninstall**.

<div data-with-frame="true"><figure><img src="/files/eGLxVOn4PUNHha2NfhEI" alt="" width="375"><figcaption></figcaption></figure></div>

### Delete account in impact.com extension dashboard

***

Deleting your account in the impact.com / HubSpot extension dashboard will delete your entire configuration. If you wish to use the integration in the future, you will need to reconfigure everything from scratch.

1. Navigate to the [**Connector website**](https://hubspot-integration.impact.com/login).
2. In the left navigation menu, select **Delete Account**.
3. Select **Delete** to delete your account configuration.

<div data-with-frame="true"><figure><img src="/files/1fW6jKHgaUqqvpZEQDcT" alt="" width="563"><figcaption></figcaption></figure></div>


# Integrate with Salesforce

B2B SaaS brands can use Salesforce and impact.com together to monitor and track conversion events, like leads and business opportunities. With flexible mapping, marketers can set conditions that trigger conversion events, allowing to be paid through impact.com’s contracting and commissioning features.

The integration works in both directions, meaning you can use impact.com to set up a hosted widget that captures B2B SaaS *Leads*, *Opportunities*, *Contacts*, and *Accounts* from your partners and automatically send them to Salesforce via an API integration. When these records turn into deals, sales, or reach meaningful milestones, the changes can be sent back to impact.com as conversion events.

## How it works

***

* With a few clicks, verify that your impact.com account is ready to go for the Salesforce integration, making adjustments to a few account settings as necessary.
* Then, you'll install the impact.com package in Salesforce and configure a few settings.
* Once configured, you can customize the data parameter mapping to establish which events from Salesforce you want impact.com to track and report on.

Currently this is a integration that supports the following Salesforce objects:

* Leads
* Opportunities
* Contacts
* Accounts

## Integration Prerequisites

***

### Lead submission tracking

<details>

<summary>You can set up lead submission tracking via impact.com or Salesforce:</summary>

#### Track leads via impact.com

Lead submissions can be tracked using via impact.com's Universal Tracking Tag (UTT), which is a small piece of JavaScript code that can be loaded using a Tag Manager solution, or placed manually on your website. Using the UTT offers richer user-level reporting in impact.com, supports *Optimize*, *Direct Tracking* features, and more. If you're planning to track lead events using the UTT, the Customer ID value sent via the `TrackConversion` function must also be available to the Salesforce objects that are being monitored and reported on. In other words, Salesforce needs to receive a Customer ID value in order for the integration to accurately correlate events.

Refer to the account setup steps below to ensure your account is configured correctly.

#### Track leads via Salesforce

Lead submission can also be tracked through Salesforce. impact.com appends an `im_ref` parameter + dynamic value (per click) on your landing page URLs. Example link: `yourdomain.com?im_ref=clickid123`. The `clickId` value (`clickid123`) must be captured and stored. When the user submits the lead form, the `clickId` value must be sent in a hidden field to Salesforce. There must be a consistent ID available in Salesforce objects that are being monitored and reported on to send in the `CustomerId` parameter.

</details>

### Account setup

<details>

<summary>Follow the prerequisite steps below to ensure their account is ready for the integration. At a high level, these include:</summary>

1. Verify that a couple key account settings are properly configured.
2. Confirm that your account is ready for the Salesforce integration, and make adjusts if needed.
3. Establish a unique customer identifier (e.g., `customerId`) that persists across all entities that need to be tracked — from when a new lead is tracked, to when it becomes an opportunity, etc.

</details>

### Establish a Customer Identifier

<details>

<summary>As part of your tracking integration, you'll need to generate a unique customer ID value across each event type to be tracked.</summary>

* If you're using the impact.com UTT tracking integration, your lead form site will need to generate a unique Customer ID value that's passed when a potential lead submits the form, and this value needs to be passed across each event type as the lead progresses towards a "Signed Contract" final state in order to ensure that it's the same customer and the partner that referred them receives credit. Learn about [the UTT `identify` function](https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/javascript-tag-utt/introduction).
* If you're tracking via API, refer to the [Conversion object](https://integrations.impact.com/brand-api-reference/reference/conversions) reference documentation — your lead form site will need to generate a unique Customer ID value that's passed when a potential lead submits the form, and this value needs to be passed across each event type as the lead progresses towards a "Signed Contract" final state in order to ensure that it's the same customer and the partner that referred them receives credit.

</details>

### Check before integrating

impact.com will complete several integration steps on your behalf. Check with your implementation engineer to ensure that the following configuration steps have been completed: *Event Type*, *Gateway Tracking*, *General Tracking*.

## Installation

***

{% stepper %}
{% step %}

### Install the impact.com package to Salesforce

Only Salesforce System Administrators should install and configure the impact.com package.

1. Visit the *impact.com Partner Manager* [**Salesforce AppExchange page**](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000QsHhwEAF\&tab=e).
2. Select **Get It Now**.
3. Follow the on-screen instructions to get the impact.com app installed.
4. If you experience any issues installing from the AppExchange, please use this [direct link](https://login.salesforce.com/?ec=302\&startURL=%2Fpackaging%2FinstallPackage.apexp%3Fp0%3D04t5e000000j9Vc) instead.

<div data-with-frame="true"><figure><img src="/files/5v6FQh2wegm1AMI6P52i" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Configure your impact.com credentials in Salesforce

You'll need your impact.com *Account SID*, *Auth Token*, and *Program ID*.

1. In your Salesforce account, navigate to the *Impact Setup* tab.
2. In the tab, input the required fields:

<table><thead><tr><th>Account Data</th><th width="344">Description</th></tr></thead><tbody><tr><td><strong>Account SID *</strong></td><td>In the impact.com platform, from the top navigation bar, select <img src="/files/NAwewjCC7OYTjHnAmreE" alt=""> <strong>[User profile] → Settings →</strong> <a href="https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml"><strong>API</strong></a> and copy the Account SID.</td></tr><tr><td><strong>Auth Token *</strong></td><td>In the impact.com platform, from the top navigation bar, select <img src="/files/NAwewjCC7OYTjHnAmreE" alt=""> <strong>[User profile] → Settings →</strong> <a href="https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml"><strong>API</strong></a> and copy the Auth Token.</td></tr><tr><td><strong>Program ID *</strong></td><td>In the impact.com platform, select your brand name in the top-left corner of the impact.com app. Your <strong>Program ID</strong> is the numerical value under the program name.<br><br><img src="/files/Ot2LaAjHFj4sydMSb55V" alt=""></td></tr></tbody></table>

3. Select **Save**.

<div data-with-frame="true"><figure><img src="/files/WKLrGOjAuotwKE3jDuIl" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Set up impact.com monitoring condition

In this step, you'll identify which conditions in Salesforce need to occur for impact.com to track it as a conversion event.

1. In the *Impact Integration* app in Salesforce, select the **Impact Event Triggers** tab.
2. Under the **Enable sending events when records are created** section, use the **toggles** to choose which events will trigger a conversion event in impact.com when a record is created in Salesforce for that object.
3. Under the **Enable sending events when records are updated** section, use the **toggles** to choose which events will trigger a conversion event in impact.com when an object's record is updated in Salesforce.
4. Under the **Record multiple field changed** section, select the fields that you want a conversion event to occur for when they're updated.

   The multiple field selections act as an `OR` statement — for example, if `Lead Status` and `Lead Source` are selected for an object, a conversion event is created whenever either field is modified.

<div data-with-frame="true"><figure><img src="/files/URb22VCQtHZTn5IfRPzQ" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Configure Salesforce & impact.com data mappings

This step is where you'll configure a map of which Salesforce data parameters map to their equivalent impact.com data parameters. This step is key in ensuring the data you send from Salesforce is accurate for conversion reporting.

The instructions below apply to Lead, Opportunity, and Contact objects.

#### Add a mapping

When a Salesforce field is mapped to an impact.com field, the data in that field will be reported to impact.com in the conversion data.

1. In the *Impact Integration* app in Salesforce, select the **Impact Field Mapping** tab.
2. Refer to the *Data mapping reference* tables below for details.
3. Under *Salesforce Field*, use the dropdown menu to select a **Salesforce object field**.
4. Under the *Impact Field*, use the dropdown menu to select an **impact.com data field**.
5. Select **Add**.

<div data-with-frame="true"><figure><img src="/files/NQKGydbWLeUfB8mfvdH0" alt="" width="563"><figcaption></figcaption></figure></div>

#### Remove a mapping

Removing a data mapping will no longer report that field to impact.com — be careful, as this can alter your conversion reporting.

1. In the *Impact Integration* app in Salesforce, select the **Impact Field Mapping** tab.
2. Select the section (e.g., *Leads*, *Opportunities*, etc.) from which you want to remove a data mapping.
3. In the list of existing data mappings, find the one you wish to delete and select **Remove**.

<div data-with-frame="true"><figure><img src="/files/NQKGydbWLeUfB8mfvdH0" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

## Test your integration

impact.com registers and tracks conversion events from Salesforce sandbox environments, allowing you to test your setup safely before moving to production. Your Salesforce sandbox environment is completely separate from your live Salesforce account, and anything you do here won’t affect your production data. [Learn more](https://www.salesforce.com/platform/sandboxes-environments/guide/).

1. Complete all the integration steps in your Salesforce sandbox environment.
2. Simulate a conversion that matches your trigger conditions, e.g., create a lead.
3. On impact.com, from the left navigation menu, navigate to ![](https://res.cloudinary.com/product-enablement/image/upload/v1768905009/Accessibility%20Icons/engage-v2.svg) **\[Engage] → Reports →** [**More Reports**](https://app.impact.com/secure/advertiser/engage/fr/all_reports.ihtml), and confirm that the test action appears in your reporting.
4. Once you've verified that the integration is working correctly in your sandbox environment, you can replicate the setup in your Salesforce production environment.

## Data mapping reference

***

### Salesforce Lead

Replace `$STATUS` with the actual status value for the lead.

| Object Field       | impact.com data field |
| ------------------ | --------------------- |
| `Lead_$STATUS`     | `EventTypeCode`       |
| `ID`               | `CustomerId`          |
| `Lead_$STATUS_ID`  | `OrderId`             |
| `LastModifiedDate` | `EventDate`           |
| `Company`          | `Text3`               |
| `City`             | `CustomerCity`        |
| `Country`          | `CustomerCountry`     |
| `PostalCode`       | `CustomerPostCode`    |

### Salesforce Opportunity

Replace `$STAGE` with the actual stage value for the opportunity.

| Object Field            | impact.com data field       |
| ----------------------- | --------------------------- |
| `Opportunity_$STAGE`    | `EventTypeCode`             |
| `ID`                    | `CustomerId`                |
| `Opportunity_$STAGE_ID` | `OrderId`                   |
| `LastModifiedDate`      | `EventDate`                 |
| `CloseDate`             | `Date3`                     |
| `Probability`           | `Text2`                     |
| `Amount`                | `OrderSubTotalPostDiscount` |

### Salesforce Products

| Object Field          | impact.com data field |
| --------------------- | --------------------- |
| `Product_Name`        | `ItemName1`           |
| `Product_ProductCode` | `ItemSku1`            |
| `Product_Quantity`    | `ItemQuantity1`       |
| `Product_UnitPrice`   | `ItemPrice1`          |
| `Product_Description` | `ItemCategory1`       |
| `Product_TotalPrice`  | `ItemSubTotal1`       |

### Salesforce Contact

{% hint style="success" %}
**Note:** Contact object mapping is customizable and impact.com recommends that you map according to your use case. The table below is neither suggested nor required, but an example.
{% endhint %}

| Object Field           | impact.com data field |
| ---------------------- | --------------------- |
| `LeadSource`           | `EventTypeCode`       |
| `Contact ID`           | `CustomerId`          |
| `Contact_[Contact ID]` | `OrderId`             |
| `LastModifiedDate`     | `EventDate`           |

### Salesforce Account

| Object Field  | impact.com data field |
| ------------- | --------------------- |
| `Id`          | `OrderId`             |
| `CreatedDate` | `EventDate`           |


# e-Commerce




---

[Next Page](/llms-full.txt/1)