# Ampersand AI SDK
Source: https://docs.ampersand.ai/ai-sdk

Install the Ampersand AI SDK and use tools like createRecord and updateRecord in agents built with the Vercel AI SDK or Mastra to act on SaaS platforms.

The [Ampersand AI SDK](https://www.npmjs.com/package/@amp-labs/ai) enables AI agents to seamlessly perform operations on connected SaaS tools through Ampersand's platform.

<Note>
  The Ampersand AI SDK is in alpha. It may change in non backwards-compatible ways. (Although we are very serious about semantic versioning.)

  If you have any feedback, please file an issue [on Github](https://github.com/amp-labs/ai/issues).
</Note>

## Installation

```bash theme={"dark"}
npm install @amp-labs/ai
# or
yarn add @amp-labs/ai
# or
pnpm add @amp-labs/ai
```

## Usage

The SDK provides several modules that can be used depending on your framework preference:

### Use with Vercel AI SDK

[AI SDK](https://ai-sdk.dev/) by Vercel unifies LLM access in TypeScript & makes it easy to build AI agents.

This is a simple example of how to use the AI SDK tools by Ampersand in a Vercel AI agent.

```typescript theme={"dark"}
import { openai } from '@ai-sdk/openai';
import { generateObject, generateText } from 'ai';
import { z } from 'zod';
import { createRecord, updateRecord } from "@amp-labs/ai/aisdk";

// Vercel Agent with AI SDK tools by Ampersand
async function handleCustomerQuery(query: string) {
  const model = openai('gpt-4o');

  const { text: response } = await generateText({
    model:
      classification.complexity === 'simple'
        ? openai('gpt-4o-mini')
        : openai('o3-mini'),
    system: '... your system prompt here',
    prompt: query,
    tools: {
      // AI SDK tools by Ampersand being used here
      createRecord,
      updateRecord,
    },
  });

  return { response };
}
```

### Use with Mastra

[Mastra](https://mastra.ai) is a Typescript toolkit that offers agent workflows and eval tools so teams can turn prototypes into production-ready AI agents.

This is a simple example of how to use the AI SDK tools by Ampersand in an agent built with Mastra.

```typescript theme={"dark"}
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { createRecord, updateRecord } from "@amp-labs/ai/mastra";

// Mastra Agent with Mastra tools
export const mastraToolsAgent: Agent = new Agent({
  name: "Mastra Tools Agent",
  instructions: "You can use tools defined in Mastra.",
  model: openai("gpt-4o-mini"),
  tools: {
    createRecord,
    updateRecord,
  },
});
```

## Available Tools

The SDK provides the following tools for interacting with SaaS platforms:

| Tool | Description | Purpose |
| - | - | - |
| `createRecord` | Creates a new record in the connected SaaS platform | Create new records like contacts, deals, tickets etc. |
| `updateRecord` | Updates an existing record in the connected SaaS platform | Modify existing records with new data |
| `sendReadRequest` | Makes authenticated GET API calls to the provider through Ampersand | Reading and searching records |
| `sendRequest` | Makes authenticated API calls to the provider through Ampersand | Do any action that is available via the API |
| `checkConnection` | Verifies if there is an active connection to the SaaS provider | Validate connection status before creating an installation |
| `createInstallation` | Creates a new installation for a provider | Create an installation for an existing connection |
| `checkInstallation` | Checks if there is an active installation for a provider | Verify installation status |
| `startOAuth` | Returns URL for initiating OAuth flow for connecting to a provider | Authenticates a new user |

Have a tool in mind that we could add? Let us know [on Discord!](https://discord.gg/BWP4BpKHvf)


# Access via JWT
Source: https://docs.ampersand.ai/api/jwt-auth

Generate an RSA key pair, register the public key with Ampersand, sign JWTs on your server, and fetch them in your frontend to authenticate API requests.

This guide explains how to generate and use JWTs for authentication, so that you can securely interact with Ampersand APIs from your frontend and your customers will only have access to their own Ampersand installations.

When you first start using Ampersand's [prebuilt UI components](/embeddable-ui-components) or [headless UI](/headless), using a frontend API key is convenient since it does not require you to implement any server logic. However, as you move into production, we recommend that you stop using frontend API keys and start using JWT authentication for better security.

<Warning>
  Do not do JWT signing in the frontend. It invalidates the security model.
</Warning>

## Overview

The overall flow uses RSA-based JWT tokens with RS256 signing. It consists of:

1. **RSA Key Pair Generation** - Create a public/private key pair.
2. **Key Registration** - Register the public key with Ampersand.
3. **JWT Token Generation** - Create signed JWT tokens in your server.
4. **API Authentication** - Use JWTs to authenticate API requests made by your frontend code, by providing a `getToken` method to the Ampersand UI library.

## 1. Generate RSA key pair

First, generate an RSA key pair for signing JWTs. You can use any crypto library that can generate an RSA key pair. Only RS256 algorithm is supported. The example below uses the Node.js library `crypto`.

You only need to do this step when you first implement JWT auth, and every time you want to rotate keys.

```javascript theme={"dark"}
const crypto = require('crypto');
const fs = require('fs');

// Generate RSA key pair (2048-bit recommended)
const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem'
  },
  privateKeyEncoding: {
    type: 'pkcs1',
    format: 'pem'
  }
});

// Persist the keys somewhere
fs.writeFileSync('private_key.pem', privateKey);
fs.writeFileSync('public_key.pem', publicKey);

console.log('RSA key pair generated successfully!');
```

## 2. Register public key with Ampersand

### Using the Ampersand Dashboard

You can add your RSA public key and view your existing Key IDs (kid) directly in the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/jwt-keys).

<img alt="JWT Key Management in Dashboard" />

### Using the API

You can also register the public key programmatically using the [Create a new JWT key endpoint](/reference/jwt-key/create-a-new-jwt-key).

## 3. Generate JWT tokens in server

Create JWT tokens for a particular `groupRef` and `consumerRef` combo using public and private keys generated in step 1. You can use any library of choice that can sign JWT keys. The example below uses the Node.js library `jsonwebtoken`.

You need to then expose an API endpoint that your frontend code can call to fetch a JWT token.

```javascript theme={"dark"}
const jwt = require('jsonwebtoken');
const fs = require('fs');

// Function for generating JWT
function generateJWT(keyId, claims, ttlSeconds = 600) {
  const privateKey = fs.readFileSync('private_key.pem', 'utf8');
  
  // JWT payload with required claims
  const payload = {
    sub: claims.subject,
    groupRef: claims.groupRef,
    consumerRef: claims.consumerRef,
    iat: Math.floor(Date.now() / 1000), // Issued at time
    // Expiry time, the max TTL allowed is 600 seconds.
    exp: Math.floor(Date.now() / 1000) + ttlSeconds
  };

  // Sign the token
  const token = jwt.sign(payload, privateKey, {
    algorithm: 'RS256',
    header: {
      kid: keyId  // Key ID returned by Ampersand in step 2.
    }
  });

  return token;
}

// Expose an API that your frontend code can call.
// This example assumes you are using Express.
// You need to adapt this code to your server framework.
const app = express();
app.use(express.json());

app.post('/api/generate-jwt', async (req, res) => {
  try {
    const { groupRef, consumerRef } = req.body;
    
    const token = generateJWT('your-key-id', {
      groupRef: groupRef,
      consumerRef: consumerRef,
      // The subject can be any string that helps you with debugging,
      // such as username, email, etc. Ampersand doesn't pay attention
      // to this field.
      subject: 'user@example.com',
    }, 300); // 5 minute expiration

    res.json(token);
  } catch (error) {
    res.status(500).json({
      error: 'Internal server error',
      message: 'Failed to generate JWT token'
    });
  }
});
```

## 4. Fetch JWT token in frontend

<Note> This functionality is only available in `@amp-labs/react` version `2.8.7` and above.</Note>

In [AmpersandProvider](/embeddable-ui-components#ampersandprovider), instead of using the `apiKey` property, provide a `getToken` method that calls your backend to fetch a JWT token. The UI library will call it whenever it needs to generate a new token, or when the existing token expires.

The `getToken` method must have the following type signature:

`(params: {consumerRef: string, groupRef: string}) => Promise<string>`

```javascript theme={"dark"}
import { AmpersandProvider } from '@amp-labs/react';
import '@amp-labs/react/styles';

const options = {
  project: 'my-ampersand-project',
  getToken: ({consumerRef, groupRef}) => {
    const token = await getTokenFromMyBackend(consumerRef, groupRef);
    return token;
  }
};

function App() {
  return (
    <AmpersandProvider options={options}>
        // You can use any of the Ampersand components here.
    </AmpersandProvider>
  )
}
```

## Key management API endpoints

The backend provides these endpoints for managing JWT keys:

* [Register a new public key](/reference/jwt-key/create-a-new-jwt-key)
* [List all keys for a project](/reference/jwt-key/list-jwt-keys)
* [Get a specific key](/reference/jwt-key/get-a-specific-jwt-key)
* [Update a key's label or status](/reference/jwt-key/update-a-jwt-key)
* [Delete a key](/reference/jwt-key/delete-a-jwt-key)

## Important security notes

1. **Private Key Security**: Never expose private keys in client-side code. Store them securely on your backend servers.

2. **Token Expiration**: Tokens can have a maximum TTL of 10 minutes (600 seconds). The Ampersand UI library will automatically call the `getToken` function you provide when the token expires.

3. **Key Rotation**: Regularly rotate your RSA key pairs for better security.


# Access via API key
Source: https://docs.ampersand.ai/api/key-auth

Authenticate Ampersand API requests with the X-Api-Key header, and create, name, and view API keys from the API Keys page in the Ampersand Dashboard.

## Using the API

All API endpoints require authenticated access via an API key passed as a header `X-Api-Key`: your Ampersand API key.

If you don't have one yet, create as many as you'd like on the Ampersand Dashboard's [API Keys page](https://dashboard.withampersand.com/projects/_/api-keys).

## Creating and Viewing API Key

<Frame>
  <img alt="Generating an API key" />
</Frame>

1. Go to the [API Keys page](https://dashboard.withampersand.com/projects/_/api-keys) on the Ampersand Dashboard.
2. Click on the "New API Key" button.
3. Give your API key a descriptive name and click on the "Save Changes" button.
4. Your API key will be generated. You can view it by clicking on the button with the name of the key.

<Frame>
  <img alt="Copy API key" />
</Frame>


# Ampersand REST APIs: Write, Read, Platform, and Proxy
Source: https://docs.ampersand.ai/api/overview

Learn when to use Ampersand's four REST APIs (Write, Read, Platform, and Proxy) instead of your amp.yaml manifest, and try them in the Postman Collection.

Reference documentation for Ampersand's REST APIs.

Most integration behavior is declared in your `amp.yaml` manifest rather than called directly. If you're setting up your first integration, start with [how Ampersand works](/concepts) and the [starter project](/starter-project). Come back here when you need to trigger a read on demand, write records from your backend, manage installations programmatically, or call a provider endpoint Ampersand doesn't model.

Ampersand offers 4 APIs:

* **Write API**: for writing data to your customer's SaaS instance. Learn more in [Write Actions](/write-actions).
* **Read API**: for advanced read use cases like triggering an off-schedule read of your customer's SaaS instance, or for managing read schedules. If you simply want to do scheduled reads, you do not need to use this API. Please refer to [Read Actions](/read-actions).
* **Platform API**: for advanced use cases in managing integrations and customer installations. Most customers do not use the Platform API directly, but interact with the Ampersand Dashboard, CLI or UI library instead.
* **Proxy API**: for making direct API requests to your customer's SaaS instance without any transformations. Learn more in [Proxy Actions](/proxy-actions).

> If you prefer exploring APIs interactively, check out the official Ampersand Postman Collection.
> [<img alt="Run In Postman" />](https://god.gw.postman.com/run-collection/29973051-00c27855-f4bf-48be-8730-a63a19aada9b?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D29973051-00c27855-f4bf-48be-8730-a63a19aada9b%26entityType%3Dcollection%26workspaceId%3D4646d536-d0c0-45a7-a2ad-058b0eae9c2b#?env%5BProduction%5D=W3sia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly9hcGkud2l0aGFtcGVyc2FuZC5jb20vdjEiLCJ0eXBlIjoiZGVmYXVsdCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoicmVhZEJhc2VVcmwiLCJ2YWx1ZSI6Imh0dHBzOi8vcmVhZC53aXRoYW1wZXJzYW5kLmNvbS92MSIsInR5cGUiOiJkZWZhdWx0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ3cml0ZUJhc2VVcmwiLCJ2YWx1ZSI6Imh0dHBzOi8vd3JpdGUud2l0aGFtcGVyc2FuZC5jb20vdjEiLCJ0eXBlIjoiZGVmYXVsdCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBpS2V5IiwidmFsdWUiOiIiLCJ0eXBlIjoic2VjcmV0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwcm9qZWN0SWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJpbnRlZ3JhdGlvbklkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoicHJvdmlkZXJBcHBJZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Imluc3RhbGxhdGlvbklkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoib2JqZWN0TmFtZSIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Imdyb3VwUmVmIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImVuYWJsZWQiOnRydWV9XQ==)


# Install and use the Ampersand CLI
Source: https://docs.ampersand.ai/cli/overview

Install the Ampersand CLI on macOS, Windows, or other systems, log in, deploy integrations from amp.yaml, and run it in CI/CD with an API key.

The Ampersand Command Line Interface (CLI) enables you to deploy integrations and interact with the Ampersand platform.

## Installation

### For macOS using Homebrew

To install the CLI using Homebrew (macOS users):

```bash theme={"dark"}
brew tap amp-labs/cli
brew update
brew install amp-labs/cli/cli
```

#### Updating to new version

If you already have the CLI installed, and want to upgrade to the latest version, run:

```
brew upgrade amp-labs/cli/cli
```

### For Windows

1. Visit [Ampersand CLI Releases](https://github.com/amp-labs/cli/releases).

2. Download the appropriate binary for your machine’s architecture.

3. Extract the downloaded folder containing the `exe` file.

4. To use the CLI, open Command Prompt in the extracted folder:
   * Navigate to the folder in File Explorer
   * Click in the address bar
   * Type `cmd` and press Enter

5. Verify the installation by running:

   ```cmd theme={"dark"}
   amp
   ```

   This should display a list of commands or options available in the CLI, confirming that it is properly configured and ready for use.

6. To make the CLI accessible from anywhere, add the folder to your `PATH`:
   * Open the Start menu
   * Search for "Environment Variables"
   * Click "Edit the system environment variables"
   * Click "Environment Variables"
   * Under "System variables", select "Path" and click "Edit"
   * Click "New" and add the path to the folder containing the `exe` file
   * Click "OK" on all windows

### For other systems

1. Visit [Ampersand CLI Releases](https://github.com/amp-labs/cli/releases).
2. Download the appropriate binary for your machine’s architecture.
3. Place the binary somewhere on your `PATH` (e.g. `/usr/bin`).

**Note:**\
To ensure the CLI is accessible from anywhere, the binary must be placed in a directory listed in your `PATH`. You can inspect your current `PATH` using the following commands:

* **Linux/macOS:**
  ```bash theme={"dark"}
  echo $PATH
  ```

## Using the CLI

### Checking the version

To check the version and build information of your CLI, run:

```
amp version
```

### Log into your Ampersand account

Ensure you have an Ampersand account. Create one on the [Ampersand Dashboard](https://dashboard.withampersand.com/sign-up) if you don't already have one.

To log into the CLI:

```
amp login
```

To log out:

```
amp logout
```

### Deploy integrations

Once you have defined your integrations in an `amp.yaml` file, use the following commands to deploy:

```bash theme={"dark"}
amp login
amp deploy <folder_with_amp.yaml> --project <id-or-name>
```

### View all commands

To list all available commands and global flags:

```bash theme={"dark"}
amp help
```

**Note:** For detailed explanations of each command and its options, refer to the [Command Reference](/cli/reference) section.

### Running in CI/CD Environments

#### Github Action

You can use the [official Ampersand Github Action](https://github.com/marketplace/actions/official-ampersand-github-action) to automatically deploy integrations from your repository.

#### Generate an API key

If you are using the official Github Action, or if you want to create your own CI/CD pipeline, you will need to generate an API key to run the CLI in a non-interactive mode that does not require a log in prompt.

1. Create an API key in the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/api-keys).
2. Use the API key with the `key` flag.

```
amp list:integrations --key <api-key> --project <id-or-name>
```

Alternatively, you can set the API key as an environment variable:

```
export AMP_API_KEY=<api-key>
amp list:integrations --project <id-or-name>
```

### Debug mode

For more detailed output, run commands with the `debug` flag.

```
amp login --debug
```


# CLI command reference
Source: https://docs.ampersand.ai/cli/reference

Syntax, flags, and examples for every Ampersand CLI command, from login and deploy to delete:integration, delete:installation, and the list commands.

This section provides a detailed overview of the Ampersand CLI, including the available commands, their usage, and options.

## Usage

The general syntax for using the Ampersand CLI is:

```
amp [command] [flags]
```

Where `[command]` is one of the available commands, and `[flags]` are parameters that modify the command's behavior.

## Global flags

Global flags are options available for any Ampersand CLI command, allowing you to modify behavior or provide additional information consistently across all operations.

Here are the available global flags:

* `-d, --debug`: Enables debug logging mode (default: false). This flag is useful for troubleshooting as it provides more detailed output about the command's execution.

* `-h, --help`: Displays help information for the command. This can be used to get more details about a specific command's usage and options.

* `-k, --key string`: Specifies the Ampersand API key. This allows you to authenticate your CLI sessions using an API key instead of interactive login, which can be particularly useful in automated scripts or CI/CD pipelines.

* `-p, --project string`: Specifies the Ampersand project name or ID. You can use `amp list:projects` to view available projects.

You can use these flags by adding them after any command. For example:

```
amp list:integrations --debug --project my-project
```

This command would list integrations for the project "my-project" with debug logging enabled.

## Authentication commands

These commands allow you to manage your session with the Ampersand CLI. Use these to log in to your Ampersand account before running other commands. As an alternative to logging in, you can also run commands using an API key. See [Running in CI/CD environments](/cli/overview#running-in-cicd-environments) for details.

### login

Authenticates you against the CLI via an interactive browser flow.

**Syntax:**

```bash theme={"dark"}
  amp login
```

**Example:**

```bash theme={"dark"}
  amp login
```

### logout

Logs out from your Ampersand account.

**Syntax:**

```bash theme={"dark"}
  amp logout
```

## Utility commands

These commands provide general functionality to help you use and understand the Ampersand CLI.

### help

Displays help information about any command. You can use `amp help` for general help and `amp help [command]` for command-specific help.

**Syntax:**

```bash theme={"dark"}
amp help [command]
```

**Example:**

```bash theme={"dark"}
amp help deploy
```

**Notes:**

* Provides detailed information about command usage and available options.

### version

Displays the version of the Ampersand CLI installed on your system.

**Syntax:**

```bash theme={"dark"}
amp version
```

**Notes:**

* Useful for verifying your CLI version or checking if updates are available.
* Outputs the current version number of the CLI.

**Example:**

```bash theme={"dark"}
amp version
```

## Managing integrations

These commands are used to manage your integrations within Ampersand. They allow you to deploy changes to your integrations, delete integrations, and manage installations of integrations.

### deploy

Deploys the integrations defined in the `amp.yaml` file to Ampersand. If an integration already exists, this command will apply any changes to the existing integration.

**Syntax:**

```bash theme={"dark"}
amp deploy <folder_with_amp.yaml> --project <id-or-name> [--key <api-key>] [--debug]
```

**Notes:**

* Requires a folder containing an `amp.yaml` file.
* Use this command to deploy new integrations or update existing ones.
* Use this command when you've made changes to your integration

**Example:**

```bash theme={"dark"}
amp deploy ./integrations --project my-project
```

### delete:integration

Deletes a specific integration from your project.

**Syntax:**

```bash theme={"dark"}
amp delete:integration <integration-id> --project <id-or-name> [--key <api-key>] [--debug]
```

**Notes:**

* This action is irreversible. Use with caution.
* Removes the integration & any associated installations from your project.

**Example:**

```bash theme={"dark"}
amp delete:integration f47ac10b-58cc-4372-a567-0e02b2c3d479 --project my-project
```

### delete:installation

Deletes a specific installation of an integration.

**Syntax:**

```bash theme={"dark"}
amp delete:installation <integration-id> <installation-id> --project <id-or-name> [--key <api-key>] [--debug]
```

**Notes:**

* This removes a specific installation of an integration, not the integration itself.
* Requires both the integration ID and installation ID.

**Example:**

```bash theme={"dark"}
amp delete:installation 550e8400-e29b-41d4-a716-446655440000 91c38b0b-814c-4edd-8221-7e4f70a90123 --project my-project

```

## Resource commands

These commands help you view and manage various resources within your Ampersand projects. Use them to inspect available destinations, current installations, integrations, and projects associated with your account.

### list:destinations

Lists all available destinations in your project. For more details on Destinations, refer to the [Ampersand Destinations](https://docs.ampersand.ai/destinations) Documentation.

**Syntax:**

```bash theme={"dark"}
amp list:destinations --project <id-or-name> [--key <api-key>] [--debug]
```

**Notes:**

* The output includes destination IDs and names.

**Example:**

```bash theme={"dark"}
amp list:destinations --project my-project
```

### list:installations

Displays all current installations of a given integration in your project.

**Syntax:**

```bash theme={"dark"}
amp list:installations <integration-id> --project <id-or-name> [--key <api-key>] [--debug]
```

**Example:**

```bash theme={"dark"}
amp list:installations 550e8400-e29b-41d4-a716-446655440000 --project my-project 

```

### list:integrations

Provides a list of all integrations in your specified project.

**Syntax:**

```bash theme={"dark"}
amp list:integrations --project <id-or-name> [--key <api-key>] [--debug]
```

**Example:**

```bash theme={"dark"}
amp list:integrations --project my-project
```

### list:projects

Displays all projects associated with your Ampersand account.

**Syntax:**

```bash theme={"dark"}
amp list:projects [--key <api-key>] [--debug]
```

**Notes:**

* Lists your projects to help identify available projects when using other commands. Note that this command only displays project information and does not provide interactive project selection.
* Shows project IDs and names.

**Example:**

```bash theme={"dark"}
amp list:projects
```


# Concepts
Source: https://docs.ampersand.ai/concepts

Understand how Ampersand integrations, installations, revisions, connections, and configs fit together, and how a customer's config overrides a revision.

Ampersand has one core idea: **you define an integration once, and each of your customers gets their own installation of it.**

You describe what the integration can do in a manifest file. Each customer then connects their own account and chooses how much of that to enable. Ampersand stores those choices as a config and runs the integration against that customer's SaaS instance on their behalf.

```mermaid theme={"dark"}
flowchart TD
    A["amp.yaml<br/>what the integration can do"] -->|amp deploy| B["Revision<br/>a versioned snapshot"]
    B --> C["Your customer connects<br/>and picks objects and fields"]
    C --> D["Installation"]
    D --> E["Connection<br/>their credentials"]
    D --> F["Config<br/>what they chose"]
    B --> G["What actually runs<br/>= revision, with config overrides applied"]
    F --> G
```

## Integration

An **integration** defines how your application interacts with a third-party SaaS tool. You have a single integration for every customer connecting to that provider. For example, one integration called `mySalesforceIntegration`, where Salesforce is the **provider**.

You create an integration by defining it in a [manifest file](/manifest-reference) and deploying it with the [`amp` CLI](/cli/overview).

The manifest describes what is *possible*, not what any particular customer has turned on. It can say:

* objects and fields that are always read (`requiredFields`)
* fields the customer may choose from (`optionalFields`, or `optionalFieldsAuto: all`)
* fields the customer must map to their own schema (`mapToName`)
* a schedule, a destination, and backfill behavior

## Installation

An **installation** is one customer's instance of an integration. `mySalesforceIntegration` might have 30 installations, one per customer who has connected their Salesforce.

An installation is created when a customer connects through an [embeddable UI component](/embeddable-ui-components), or when you call the [Create installation](/reference/installation/create-a-new-installation) endpoint.

Each installation holds two things:

<CardGroup>
  <Card title="Connection" icon="key">
    The credentials for that customer's SaaS instance. Ampersand supports OAuth, API keys, and basic auth, and handles token refresh for you.
  </Card>

  <Card title="Config" icon="sliders">
    That customer's choices, stored as overrides on the integration's definition: fields, mappings, schedule, and destination.
  </Card>
</CardGroup>

## Revision

Every time you change `amp.yaml` and run `amp deploy`, Ampersand stores a new **revision**, a versioned snapshot of the integration's definition.

Revisions matter because your customers are not all on the same version at the same moment. A config records the revision it was created or last updated against, so you can tell which definition a given customer is running.

<Note>
  When Ampersand renders the field-mapping UI, it requests a **hydrated revision**: the revision enriched with live field metadata from that customer's connected instance. It carries the fields that actually exist in their account, with display names and types. That is how the UI can offer a customer *their* custom fields, not a generic list.
</Note>

## Config

The **config** records one customer's choices for an installation. It is not a complete description of what runs. It is a set of **overrides on top of the revision**.

<Note>
  Anything the config specifies wins for that installation. Anything it leaves unset falls back to what the integration's revision defines. A config is a diff, not a replacement.
</Note>

This is why two customers on the same integration can behave differently without you maintaining two manifests, and why a customer who has changed nothing simply follows what you declared.

### What a config can override

For a read object, a config can set the fields the customer selected (`selectedFields`, or `selectedFieldsAuto: all`), the mappings they chose (`selectedFieldMappings`, `selectedValueMappings`), and operational settings: `schedule`, `destination`, `backfill`, `fieldFilters`, and `disabled` to pause an object entirely. For a write object it can set `deletionSettings`, `selectedFieldSettings`, and `selectedValueDefaults`.

### A worked example

Suppose your manifest declares:

```yaml theme={"dark"}
- objectName: contact
  destination: contactsWebhook
  schedule: "*/15 * * * *"
  requiredFields:
    - fieldName: email
    - mapToName: lifecycle_stage
  optionalFieldsAuto: all
```

A customer installs it and maps `lifecycle_stage` to their `hs_lead_status` field, adds two optional fields, and leaves everything else alone. Their config carries only those choices.

What actually runs for them is the merge: `email` and their two optional fields are read, `hs_lead_status` is mapped to `lifecycle_stage`, and the schedule and destination come from your revision, because the config never mentioned them.

If that customer later asks for hourly syncs, you set `schedule` on their config. It now overrides yours, for them alone. Every other installation still follows the manifest.

You can read a config with [Get an installation](/reference/installation/get-an-installation), or from the SDK via `installation.config`, and change one with [Update an installation](/reference/installation/update-an-installation).

## How they work together

<Steps>
  <Step title="You deploy an integration">
    `amp deploy` creates a revision from your `amp.yaml`. Nothing runs yet. You have only described what is possible.
  </Step>

  <Step title="A customer connects">
    They authenticate against their own SaaS instance through your embedded UI. Ampersand stores those credentials as a connection.
  </Step>

  <Step title="They choose what to share">
    Ampersand hydrates the revision with the live schema from their instance, and the UI offers the fields your manifest allows. Their selections become the config.
  </Step>

  <Step title="Ampersand runs it">
    Scheduled reads, writes, and subscriptions execute against that customer's instance, using your revision with their config's overrides applied, and deliver results to your destination.
  </Step>
</Steps>

### What this means in practice

* **One integration, many configs.** Two customers on the same integration can read different fields, because each customer's config decides what's included.
* **A config only carries what the customer changed.** Everything else follows your manifest, so defaults stay in one place.
* **To change one customer, update their config.** To change the default for everyone, change the manifest and deploy.
* **Mapped fields need a customer decision.** A `mapToName` entry cannot resolve until someone tells Ampersand which of their fields it corresponds to.

## Related terms

A **provider** is the third-party API you integrate with. A **provider app** is the OAuth app you register with that provider, stored in Ampersand so customers can authenticate against it. A **destination** is where read results are delivered: a webhook, warehouse, or queue.

For the full glossary, see [Terminology](/terminology).


# BigQuery
Source: https://docs.ampersand.ai/customer-guides/bigquery

Connect a BigQuery dataset to an integration: enable APIs, create a GCP service account and JSON key, gather connection details, and fix access issues.

This guide walks you through connecting your Google BigQuery dataset to an integration using a GCP service account.

## Before installing a BigQuery integration

You will need access to a Google Cloud Platform (GCP) project that contains the BigQuery dataset you want to connect. You must have sufficient permissions to create service accounts and manage IAM roles (typically **Owner** or **Editor** access).

### 1. Enable the required APIs

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Select your project from the project picker at the top of the page.
3. Navigate to **APIs & Services** > **Enabled APIs & Services**.
4. Search for **BigQuery API** and verify it is enabled. If not, click **Enable**.
5. Also search for and enable the **BigQuery Storage API**, as this is required for high-performance data reads.

### 2. Create a service account

A service account is a special-purpose GCP account used by applications to access resources.

1. In the Google Cloud Console, navigate to **IAM & Admin** > **Service Accounts**.
2. Click **Create Service Account**.
3. Enter a name (e.g., "Integration Service Account") and an optional description.
4. Click **Create and Continue**.
5. Grant the following roles:
   * **BigQuery Data Viewer** — allows reading table data and metadata.
   * **BigQuery Job User** — allows running queries in the project.
6. Click **Done**.

<Note>If you only want to grant access to a specific dataset rather than the entire project, you can assign the **BigQuery Data Viewer** role at the dataset level instead. Navigate to the dataset in the BigQuery console, click **Sharing** > **Permissions**, and add the service account there.</Note>

### 3. Create and download a key

1. From the **Service Accounts** page, click on the service account you just created.
2. Go to the **Keys** tab.
3. Click **Add Key** > **Create new key**.
4. Select **JSON** as the key type and click **Create**.
5. A JSON file will be downloaded. Store it securely. This file contains credentials that grant access to your BigQuery data.

You will need to base64-encode the contents of this file before providing it during installation. Use the command that matches your environment:

**macOS (Terminal)**

```bash theme={"dark"}
base64 -i service-account-key.json
```

**Linux, Git Bash, or WSL**

```bash theme={"dark"}
base64 -w 0 service-account-key.json
```

**Windows (PowerShell)**

```powershell theme={"dark"}
[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path 'service-account-key.json')))
```

Copy the encoded string (a long single line). You will paste it when installing the integration.

### 4. Gather your connection details

You will need the following information when installing the integration:

| Input | Where to find it |
| - | - |
| **Service Account Key** | The base64-encoded contents of the JSON key file from step 3. |
| **GCP Project ID** | Your project's ID (not the project number). Find it at the top of the Google Cloud Console or under **IAM & Admin** > **Settings**. It looks like `my-project-id`, not a number. |
| **Dataset Name** | The name of the BigQuery dataset you want to connect. Find it in the BigQuery console under your project in the left sidebar. |
| **Timestamp Column** | The name of a `TIMESTAMP` or `DATETIME` column in your tables that tracks when rows were last modified (e.g., `updated_at`, `modified_date`). This is used for incremental syncing. |

## Installing the integration

When you are installing the integration, you will be prompted for the inputs listed above. After providing them, the integration will begin syncing data from your BigQuery dataset.

## Troubleshooting

### Access blocked despite valid credentials

If your GCP project is protected by [VPC Service Controls](https://cloud.google.com/vpc-service-controls/docs/overview), all external API requests are denied by default, including the BigQuery Storage Read API used by this integration. Ask your GCP administrator to create an ingress rule that allows the service account to access `bigquery.googleapis.com` from outside the perimeter.

### Missing or filtered data

If columns in your tables use [column-level security](https://cloud.google.com/bigquery/docs/column-level-security-intro) (Data Catalog policy tags), the service account also needs the `Fine-Grained Reader` role on those policy tags. If your tables use [row-level security](https://cloud.google.com/bigquery/docs/row-level-security-intro), rows may be silently filtered. Please ensure the service account is included in the relevant row access policies.


# Gong
Source: https://docs.ampersand.ai/customer-guides/gong

Create a Gong automation rule that sends call.created webhooks to your developer's webhook URL, and learn when to expect each webhook after a call ends.

## Checklist before you start

Confirm the following:

* You are a Gong **Technical Administrator** (the role required to create automation rules and configure outbound webhooks).
* Your developer has provided you with a **webhook URL** in this format:

  ```
  https://subscribe-receiver.withampersand.com/zt1secx7jknlhb/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
  ```

## Set up webhooks for real-time updates (Subscribe Actions)

To send `call.created` events to your developer's application, you'll create an **automation rule** in Gong that fires a webhook each time a call is processed.

1. Sign in to Gong and open **Admin Settings** in the left sidebar.
   <img />
2. In the left sidebar, navigate to **Automation rules**.
   <img />
3. Click **Add rule**.
   <img />
4. (Optional) Add any filters you'd like to apply — for example, restrict the rule to specific participants. Leave the filters empty to send every new call.
   <img />
5. Paste the webhook URL your developer gave you into the **Enter URL** field.
   <img />
6. Give the rule a descriptive name and toggle **"Rule Status"** to **Enabled**.
   <img />
7. (Optional) Send a test webhook and click Save.
   <img />

## When to expect the webhook to fire

Gong fires the `call.created` webhook after a call has finished processing and appears in your Gong call library, which can take **several hours** after the call ends. You will not see events arrive immediately after a call wraps up — this is expected.

The screenshot below shows where a processed call shows up. Once a call reaches this state, the webhook has been (or will shortly be) sent.

<img />

## For official setup details, see:

* [Gong Automation Rules overview](https://help.gong.io/docs/introduction-to-automation-rules)
* [Send a webhook from an automation rule](https://help.gong.io/docs/create-a-webhook-rule)


# Google (workspace delegation)
Source: https://docs.ampersand.ai/customer-guides/google-workspace-delegation

Connect your Google Workspace domain with a GCP service account using domain-wide delegation for Gmail, Calendar, and Contacts, and fix common auth errors.

This guide walks you through connecting your Google Workspace domain to an integration that uses a GCP service account with [domain-wide delegation](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority). This is a headless, server-to-server authentication method — there is no interactive login, and the integration accesses Gmail, Calendar, and Contacts data on behalf of users in your domain.

## Before installing a Google (Workspace Delegation) integration

You will need:

* **Google Cloud Platform (GCP)** access with permission to create service accounts (typically **Owner** or **Editor** on a GCP project).
* **Google Workspace super-admin** access to your domain (required to authorize domain-wide delegation).

### 1. Enable the required APIs

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Select (or create) a GCP project that will own the service account.
3. Navigate to **APIs & Services** > **Library**.
4. Enable the APIs your integration needs:
   * **Gmail API** for Gmail integrations.
   * **Google Calendar API** for Calendar integrations.
   * **People API** for Contacts integrations.

### 2. Create a service account

1. In the Google Cloud Console, navigate to **IAM & Admin** > **Service Accounts**.
2. Click **Create Service Account**.
3. Enter a name and an optional description.
4. Click **Create and Continue**, then **Done**. You do not need to grant any project-level IAM roles for domain-wide delegation as the authorization happens in the Workspace Admin console in step 4.

### 3. Create and download a key

1. From the **Service Accounts** page, click on the service account you just created.
2. Note the **Unique ID** (a numeric client ID, e.g. `123456789012345678901`). You will need this in the next step.
3. Go to the **Keys** tab.
4. Click **Add Key** > **Create new key**.
5. Select **JSON** as the key type and click **Create**.
6. A JSON file will be downloaded. Store it securely — this file contains credentials that can impersonate any user in your Workspace domain once delegation is authorized.

You will need to base64-encode the contents of this file before providing it during installation. Use the command that matches your environment:

**macOS (Terminal)**

```bash theme={"dark"}
base64 -i service-account-key.json
```

**Linux, Git Bash, or WSL**

```bash theme={"dark"}
base64 -w 0 service-account-key.json
```

**Windows (PowerShell)**

```powershell theme={"dark"}
[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path 'service-account-key.json')))
```

Copy the encoded string (a long single line). You will paste it when installing the integration.

### 4. Authorize domain-wide delegation

This step grants the service account permission to impersonate users in your Workspace domain. It must be performed by a **super-admin** of the Google Workspace domain.

1. Go to the [Google Admin console](https://admin.google.com/).
2. Navigate to **Security** > **Access and data control** > **API controls**.
3. Click **Manage Domain Wide Delegation**.
4. Click **Add new**.
5. In **Client ID**, paste the numeric **Unique ID** of the service account from step 3.
6. In **OAuth scopes**, enter a comma-separated list of the scopes your integration needs. For example:
   * Gmail (read/write): `https://mail.google.com/`
   * Gmail (read-only): `https://www.googleapis.com/auth/gmail.readonly`
   * Calendar (read/write): `https://www.googleapis.com/auth/calendar`
   * Calendar (read-only): `https://www.googleapis.com/auth/calendar.readonly`
   * Contacts (read/write): `https://www.googleapis.com/auth/contacts`
   * Contacts (read-only): `https://www.googleapis.com/auth/contacts.readonly`
7. Click **Authorize**.

<Note>Changes to domain-wide delegation can take up to 24 hours to propagate, though most take only a few minutes. If the integration returns `unauthorized_client` errors immediately after installation, wait and retry.</Note>

### 5. Gather your connection details

You will need to share the following information with the integration builder:

| Input | Where to find it |
| - | - |
| **Service Account Key** | The base64-encoded contents of the JSON key file from step 3. |
| **User Emails** | A full list of email addresses of all the users whose data the integration should access (e.g. `user1@company.com, user2@company.com`). |
| **Scopes** | The exact list of OAuth scopes you authorized in step 4 (or a subset). |


# Housecall Pro
Source: https://docs.ampersand.ai/customer-guides/housecallPro

Generate a Housecall Pro API key as an Admin on a MAX subscription, and optionally set up webhooks with your developer's URL for real-time updates.

## Checklist before you start

Confirm the following:

* You are a Housecall Pro **Admin** user.
* Your Housecall Pro account has a **MAX subscription**.

## 1. Generate your Housecall Pro API key

Follow these steps to generate your Housecall Pro API key.

1. Click the **My Apps** icon (3x3 grid) in the top-right corner.
   <img />
2. Click **Go to App Store**.
   <img />
3. Under **My Apps**, find and open the **API Key Management** app card.
   <img />
4. Click **Generate API Key**.
   <img />
5. Enter a descriptive name for the key.
   <img />
6. Copy the API key and store it securely.
   <img />

## 2. Set up webhooks for real-time updates (Subscribe Actions)

Skip this section if your developer did not give you a webhook URL, or if you do not need real-time updates.

Follow these steps to set up webhooks in Housecall Pro.

1. Click the **My Apps** icon (3x3 grid) in the top-right corner.
   <img />
2. Click **Go to App Store**.
   <img />
3. Under **All apps**, find and open **Webhooks**.
   <img />
4. Set Webhooks to **Active**, paste the link the developer gave you into the **Webhook URL** field, then click **Save**.
   <img />
5. Enable the webhook events that you want to subscribe to, then click **Save**.
   <img />
   <Note>
     **`pro.created`** in Housecall Pro means a new **employee**; the connected
     product may display it as **`employee.created`**.
   </Note>

## For official setup details, see:

* [Housecall Pro API Overview](https://help.housecallpro.com/en/articles/8505035-api-overview#h_3b0cd3e648)
* [Housecall Pro Webhooks Setup](https://help.housecallpro.com/en/articles/5683520-how-to-enable-webhooks)


# HubSpot
Source: https://docs.ampersand.ai/customer-guides/hubspot

Check HubSpot requirements before installing an integration: you must be a Super Admin, and you need a Sales Hub seat if the integration accesses Leads.

## Checklist before installing a HubSpot integration

We recommend verifying the following requirements before installing the HubSpot integration to ensure a smooth setup.

### 1. Ensure you are a HubSpot Super Admin

You must be a **Super Admin** to install an app. This is a [HubSpot requirement](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/oauth/oauth-quickstart-guide).

### 2. Ensure you have a Sales Hub seat (if access to Leads is required)

If your integration requires access to Leads, you must have a Sales Hub seat in HubSpot. Without this, you may not be able to retrieve or manage lead data.

To check if you have a Sales Hub seat:

1. Log in to *HubSpot*.
2. Click on your profile picture and select **Settings**.
3. In the left sidebar, navigate to **Users & Teams**.
4. Locate your user account and check for **Sales Hub seat** assignment.
5. If you do not have a Sales Hub seat, ask your HubSpot administrator to assign one to you.

Learn more about different HubSpot seats [here](https://knowledge.hubspot.com/account-management/manage-seats).


# Loxo
Source: https://docs.ampersand.ai/customer-guides/loxo

Find the metadata values you need before installing a Loxo integration: your full domain from the browser URL and your Agency Slug from workspace settings.

## Checklist before installing a Loxo integration

Before beginning the installation, you’ll need to gather a few metadata values from your Loxo account. The steps below outline where to locate each of these values.

### 1. Full Domain

Log in to your Loxo account and check the URL in your browser’s address bar. It typically follows this pattern: `https://[your-domain-here]`.

<img alt="loxo-full-domain" />

### 2. Agency Slug

Go to **Settings > Workspace > General**. In the **Agency Info** section, check the **Resume Forwarding Address**. The text before the '@' symbol is your **Agency Slug**.

<img alt="loxo-agency-slug" />


# Marketo
Source: https://docs.ampersand.ai/customer-guides/marketo

Prepare Marketo for an integration by creating an API-only role, an API-only user, and a LaunchPoint custom service, then find your Munchkin Account ID.

## Checklist before installing a Marketo integration

We recommend completing the following steps before installing the Marketo integration to ensure a smooth setup.

### 1. Create an API-Only Role

1. Log in to **Adobe Experience**.
2. Click on **Marketo Engage** and launch your instance.
3. At the top, navigate to **Admin**.
4. In the left sidebar, go to **Admin** → **Security** → **Users & Roles**.
5. Click on **Roles**, then **New Role**, and provide the API role name (used in Step 2).
6. Select the appropriate API access permissions for this role.\\
   <img alt="Img" />
7. Click **Create**.

For more information, refer to [Marketo's official documentation](https://experienceleague.adobe.com/en/docs/marketo/using/product-docs/administration/users-and-roles/create-an-api-only-user-role).

### 2. Create an API-Only User

1. Log in to **Adobe Experience**.
2. Click on **Marketo Engage** and launch your instance.
3. At the top, navigate to **Admin**.
4. In the left sidebar, go to **Admin** → **Security** → **Users & Roles**.
5. Click on **Users**, then **Create API Only User**, and fill in the required details.
6. Under **Roles**, select the role created in Step 1.\\
   <img alt="Img" />
7. Click **Create**.

For more information, refer to [Marketo's official documentation](https://experienceleague.adobe.com/en/docs/marketo/using/product-docs/administration/users-and-roles/create-an-api-only-user).

### 3. Create a Custom Service

1. Log in to **Adobe Experience**.
2. Click on **Marketo Engage** and launch your instance.
3. At the top, navigate to **Admin**.
4. In the left sidebar, go to **Admin** → **Integration** → **LaunchPoint**.
5. Click on **New** → **New Service**, and provide the following details:
   * **Display Name**: (Your preference)
   * **Service**: Custom
   * **Description**: (Your preference)
   * **API Only User**: Select the user created in Step 2\\
     <img alt="Img" />
6. Click **Create**.
7. After creation, you can view the **Client ID** and **Client Secret** by clicking **View Details**.\\
   <img alt="Img" />
8. You will also need the `workspaceId` (Munchkin Account ID). This can be found under **Admin** → **Integration** → **Munchkin**.\\
   <img alt="Img" />

For more information, refer to [Marketo's official documentation](https://experienceleague.adobe.com/en/docs/marketo/using/product-docs/administration/additional-integrations/create-a-custom-service-for-use-with-rest-api#_blank).


# NetSuite
Source: https://docs.ampersand.ai/customer-guides/netsuite

Connect NetSuite with OAuth 2.0 Client Credentials: install the bundle, create an integration record, generate a certificate, and map it to a role.

This guide walks you through connecting your NetSuite account to an integration using OAuth 2.0 Client Credentials (Machine to Machine).

## Before installing a NetSuite integration

You will need **Administrator access** to your NetSuite account.

### 1. Install the bundle

1. Navigate to **Customization** > **SuiteBundler** > **Search & Install Bundles**.
2. Search for the bundle name or ID.
3. Select the bundle from the results and click **Install**.
4. Wait for the installation to complete. This may take a few minutes.

The bundle will install SuiteScripts and custom objects (fields, records, roles, etc) into your NetSuite account.

### 2. Verify the deployment

1. Navigate to **Customization** > **Scripting** > **Script Deployments**.
2. Find the RESTlet deployment installed by the bundle and click on 'View'.

<img />

3. Verify the deployment **Status** is **Released**.
4. Click on the name of the script, then note the **URL** — you will need it for the installation step.

<img />

### 3. Enable required features

1. Log in to *NetSuite* as an Administrator.
2. Navigate to **Setup** > **Company** > **Enable Features** > **SuiteCloud**.
3. Under **Manage Authentication**, check **OAuth 2.0**.
4. Under **SuiteScript**, check **Server SuiteScript**.
5. Under **Manage Authentication** (or **SuiteTalk**), check **REST Web Services**.
6. Make sure that the following features are also enabled in your environment:

* Accounting
* Custom Records
* File Cabinet

7. Click **Save**.

### 4. Create an integration record

The integration record identifies the external application that will connect to your NetSuite account.

1. Navigate to **Setup** > **Integration** > **Manage Integrations** > **New**.
2. Enter a **Name** for the integration (e.g. "Ampersand Integration").
3. Under the **Token-based Authentication** section:
   * Uncheck **TBA: Authorization Flow**
   * Uncheck **Token-Based Authentication**
4. Under the **OAuth 2.0** section:
   * Uncheck **Authorization Code Grant**
   * Check **Client Credentials (Machine to Machine) Grant**
5. Under **Scope**, check the following:
   * **RESTlets**
   * **REST Web Services**
6. Click **Save**.

<img />

7. After saving, NetSuite displays the **Consumer Key / Client ID** under the **Client Credentials** section. Copy this value and store it securely — it is shown only once and cannot be retrieved later.

<img />

### 5. Generate a certificate key pair

In this step you'll use your computer's terminal to create two files: a private key and a self-signed certificate. This is a one-time operation — if anything goes wrong, you can delete the files and start over.

Before you begin, you need **OpenSSL** available in your terminal. macOS and most Linux distributions include it by default. On **Windows**, use **Git Bash** (bundled with [Git for Windows](https://gitforwindows.org/), which includes OpenSSL), **WSL**, or install OpenSSL and ensure it is on your `PATH`.

#### a. Create a folder and open a terminal in it

Create a new folder anywhere you'll remember — your Desktop works fine. For example, create one called `netsuite-keys`. Then open a terminal *inside that folder* so the files you generate end up there:

* **macOS**: In **Finder**, right-click the folder and choose **New Terminal at Folder**. (If you don't see this option, enable it under **System Settings** > **Keyboard** > **Keyboard Shortcuts** > **Services** > **Files and Folders** > **New Terminal at Folder**.)
* **Windows**: In **File Explorer**, right-click inside the folder and choose **Open in Terminal** or **Open Git Bash here**.
* **Any OS (fallback)**: Open your terminal app, type `cd ` (with a trailing space), drag the folder from your file browser onto the terminal window, and press **Enter**.

#### b. Run the OpenSSL commands

Copy each command below, paste it into the terminal right after the prompt (`%` on macOS, `$` on Linux/Git Bash, `PS>` on PowerShell), and press **Enter**. Run them one at a time.

```bash theme={"dark"}
openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
```

```bash theme={"dark"}
openssl req -new -x509 -key private-key.pem -out cert.pem -days 730
```

The second command will prompt you for certificate details (country, organization name, email, etc.). **Press Enter at every prompt to accept the defaults** — these values are not used by the integration, so it doesn't matter what they are.

#### c. Confirm the two files were created

If the commands succeeded, your folder now contains two files:

* `private-key.pem` — your private key. You'll base64-encode it in the next sub-step.
* `cert.pem` — your public certificate. You'll upload it to NetSuite in step 7.

Open the folder in **Finder** (macOS) or **File Explorer** (Windows) to confirm both files are there. If you can't see them, search your computer for `cert.pem` — the files were created in whichever folder your terminal was open in.

<Note>If anything looks wrong — missing files, error messages, accidentally hit Enter too many times — just delete the files and run the commands again. The keys aren't registered anywhere until you upload `cert.pem` to NetSuite in step 7, so there's no risk in starting over.</Note>

#### d. Base64-encode the private key

Run the command below to print a base64-encoded version of your private key directly in the terminal. Use the version that matches your environment:

**macOS (Terminal)**

```bash theme={"dark"}
base64 -i private-key.pem
```

**Linux, Git Bash, or WSL**

```bash theme={"dark"}
base64 -w 0 private-key.pem
```

**Windows (PowerShell)**

```powershell theme={"dark"}
[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path 'private-key.pem')))
```

After running the command, you should see a long single-line string printed in the terminal, starting with `LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0t...`. Select and copy the entire string — you'll paste it during the installation process.

### 6. Assign the integration role to a user or create a new user

The bundle will include a custom role with the permissions needed for the integration. You need to assign this role to the employee/user account that the integration will run as.

1. Navigate to **Setup** > **Users/Roles** > **User Management** > **Employees** (or **Lists** > **Employees**).
2. Find and edit the employee record you want the integration to run as. This can be an existing user or a dedicated integration user.
3. Go to the **Access** tab.
4. In the **Roles** subtab, click **Add**.
5. Select the custom role from the dropdown.
6. Click **Save**.

<Note>If you prefer to use a dedicated integration user rather than an existing employee, create a new user/employee record first, then assign the role as described above. This is recommended for security purposes.</Note>

### 7. Create a machine-to-machine certificate mapping

1. Navigate to **Setup** > **Integration** > **OAuth 2.0 Client Credentials (M2M) Setup**.
2. Click **Create New**.
3. Configure the following fields:
   * **Entity**: Select the employee/user account the integration will run as (from the previous step)
   * **Role**: Select the custom role that the bundle installed. Please note that the role must include the **Log in Using OAuth 2.0 Access Tokens** permission.
   * **Application**: Select the integration record you created in step 4.
   * **Certificate**: Upload the `cert.pem` file you generated in step 5.
4. Click **Save**.

<img />

5. Copy the **Certificate ID** from the list — you will need this value when installing the integration.

<img />

<Note>Check that the `Valid Until` date for the certificate is two years in the future. NetSuite allows a maximum validity of 730 days.</Note>

## Installing the integration

When you are installing the integration, you will be prompted for a number of inputs:

<img />

Here is where to find each value:

| Input | Where to find it |
| - | - |
| **Client ID** | The Consumer Key from step 2. |
| **Certificate ID** | From step 4. |
| **Private Key** | Base64-encoded contents of `private-key.pem` (from step 3) |
| **Account ID** | Your NetSuite URL (e.g. `https://1234567.app.netsuite.com` → Account ID is `1234567`), or **Setup** > **Company** > **Company Information**. |
| **RESTlet Deployment URL** | This is printed out in the Deployments tab of the script (see previous step), and looks like `/app/site/hosting/restlet.nl?script=3045&deploy=1`. |

<Note>**Sandbox accounts**: If you are connecting a sandbox account, your Account ID may contain an underscore and suffix (e.g. `1234567_SB1`). Provide it exactly as shown in your NetSuite URL or Company Information page.</Note>


# Ampersand customer guides for integration setup
Source: https://docs.ampersand.ai/customer-guides/overview

Learn what the Ampersand customer guides offer end users setting up integrations: step-by-step instructions, troubleshooting tips, and prerequisites.

Welcome to the Ampersand **Customer Guides** section!

Customer guides are specifically designed for end users who are setting up or troubleshooting integrations built with Ampersand. While our Provider Guides are intended for developers building integrations, these guides focus on clear, step-by-step instructions for anyone—whether or not they have a technical background.

With the customer guides, we want to simplify the setup process for you. Each guide covers common setup steps, troubleshooting tips, and best practices to ensure a smooth and hassle-free experience.

## What you'll find here

* Step-by-step instructions for common integration platforms
* Troubleshooting tips for common issues
* Prerequisites checklists before installation
* Visual aids including screenshots and GIFs to guide you through complex processes


# Salesforce
Source: https://docs.ampersand.ai/customer-guides/salesforce

Set up your Salesforce org for an integration using an External Client App or Connected App, with the user permissions and OAuth policies it requires.

This guide helps you set up your Salesforce org to work with an Ampersand-powered integration. The steps differ depending on whether the integration uses an **External Client App** or a **Connected App**. If you're not sure which one you're using, ask the developer who built the integration.

## Checklist before installing

Complete these checks before you install or connect the integration. If any of them fail, the connection will not work.

### 1. Confirm your edition has API access

Your Salesforce edition must include API access. Without it, the integration cannot connect.

Check [Salesforce's API access by edition](https://help.salesforce.com/s/articleView?language=en_US\&id=000385436\&type=1). If your edition does not include API access, contact your Salesforce account representative to upgrade.

### 2. Know which app type you're installing

Ask the developer whether this integration uses an **External Client App** or a **Connected App**. Use the matching tab in the sections below.

### Glossary

* **License** — Purchased from Salesforce; sets the maximum permissions a user can receive. Which license you need depends on who connects — see [Choose credentials and grant access](#choose-credentials-and-grant-access).
* **Profile** — Controls object, field, and feature access. Each user has exactly one profile (standard or custom), tied to one license. System Administrator is a profile, not a license.
* **Permission set** — Extra permissions assigned on top of a profile. Users can have multiple permission sets; each set is tied to a license.

## Setting up the integration

<Tabs>
  <Tab title="External Client App">
    ### Install the package

    The developer will provide a **package install URL**. Complete this install **before** connecting Salesforce in the integration UI, or OAuth will fail.

    1. Open the package install URL provided by the developer.
    2. Log in to your Salesforce org if prompted.
    3. Select **Install for All Users**.
    4. Check the acknowledgment checkbox.
    5. Click **Install**.

    <img />

    You will see a progress screen while the installation completes.

    <img />

    Once complete, you should see a confirmation screen:

    <img />

    To verify, go to **Setup**, search for **Installed Packages**, and confirm the package appears in the list.

    <img />
  </Tab>

  <Tab title="Connected App">
    ### Configure token policy settings

    Set the refresh token policy so the integration stays connected after access tokens expire.

    1. Log in to **Salesforce**.

    2. Go to **Setup**.

    3. In the **Quick Find** box, search for **Connected Apps**.

    4. Click **Manage Connected Apps**.

    5. Find and click the name of the application you are integrating with.

    6. Scroll to **OAuth Policies**.

    7. Under **IP Relaxation**, select **Relax IP restrictions**.

    8. Set **Refresh Token Policy** to **Refresh token is valid until revoked**.

       <img alt="Refresh Token Settings" />

    9. Click **Save**.

    After you connect the app, also confirm **Permitted Users** under app policies. See [After installing the integration](#after-installing-the-integration).

    **IP Relaxation** applies to the IP address you sign in from when you authorize the app, not to the IP addresses the integration makes API calls from. If you want to limit where the integration's API calls can come from, see [Restrict API access by IP address](#restrict-api-access-by-ip-address).
  </Tab>
</Tabs>

## Choose credentials and grant access

Pick one way to connect, then grant the permissions below.

### Required system permissions

The following system permissions need to be enabled on the profile or permission set you configure. The sections below provide instructions on how to enable them.

* **API Enabled**
* If the integration includes real-time Subscribe Actions, also enable the [Subscribe Action permissions](#subscribe-action-permissions)
* If the integration creates or updates custom fields, also enable the [custom field management permissions](#custom-field-management-permissions)
* For Connected Apps only, also enable one of:
  * **Use Any API Client** (shown if your org has [API Access Control](https://help.salesforce.com/s/articleView?id=xcloud.security_api_access_control_about.htm\&type=5) enabled)
  * **Approve Uninstalled Connected Apps** (if you do not see **Use Any API Client**)

### Option A: Human user

Use one of the following:

* **System Administrator** — Already on a supported license (System Administrator is a profile on the **Salesforce** license). You still need to grant the correct object and field permissions; they are not always included by default.
* **Sales team member or other human user** — Must have the **Salesforce** User License. The **Salesforce Platform** User License is insufficient. This user can have a standard profile (such as **Standard User**) or a custom profile.

#### 1. Configure system permissions

In **Setup**, search for **Profiles** in the **Quick Find** box and open it. Then:

1. Select the profile you'd like to view and edit.
2. Click **Edit** at the top of the page.

<img alt="Edit profile" />

3. Ensure the checkboxes for the [required system permissions](#required-system-permissions) are checked.
4. Click **Save**.

#### 2a. Field permissions for a standard profile

If the user has a standard profile (such as **Standard User**):

1. Click the gear icon in the top-right corner and select **Setup**.
2. In the left-hand search bar, type **Object Manager** and open it.

<img alt="Setup Object Manager" />

3. Choose the object you need (for example, **Account**), then select **Fields & Relationships** from the left navbar.

<img alt="Setup Object Manager Account" />

4. Find the field you want to adjust and click it.
5. Click **Set Field-Level Security**.

<img alt="Set Field Level Security" />

6. Ensure **Visible** is selected for the profile. If the profile is not in the list, it does not have access to the object and that cannot be changed here.

<img alt="Check Visible for profile" />

7. Repeat steps 4–6 for all fields the integration needs to read, especially custom fields.

#### 2b. Object and field permissions for a custom profile

If the user has a custom profile:

1. Click the gear icon in the top-right corner and select **Setup**.
2. In the left-hand search bar, type **Object Manager** and open it.

<img alt="Setup Object Manager" />

3. Choose the object you need (for example, **Account**) and go to **Object Access** in the left navbar. Select the **Profiles** tab, click **Edit**, and grant the necessary permissions for your custom profile.
   * If the integration needs to read data, ensure **Read**, **View All Records**, and **View All Fields** are checked.
   * If the integration needs to write data, ensure all boxes are checked.

<img alt="Edit Object Access" />

### Option B: Salesforce Integration user

Use a **Salesforce Integration** user when you want an API-only identity with no Salesforce UI access. Create the user with the **Salesforce Integration** license (steps below).

#### 1. Create a new user

1. Click the gear icon in the top-right corner and select **Setup**.
2. In the left-hand search bar, type **Users** and open it.
3. Create a new user:
   * For **User License**, select **Salesforce Integration**.
   * For **Profile**, select **Minimum Access - API Only Integrations**.

<img />

#### 2. Create a permission set

1. Click the gear icon in the top-right corner and select **Setup**.
2. In the left-hand search bar, type **Permission Sets** and open it.
3. Click **New**.

<img />

4. Create the permission set:
   * Name it something general (for example, `Integration User Permission Set`) or describe the access (for example, `Account and Contact Access`).
   * In the **License** dropdown, select **Salesforce API Integration**.

<img />

#### 3. Configure object permissions

1. Click **Object Settings**.

<img />

2. For each object the integration needs, open it (for example, **Accounts**).

<img />

3. Check the relevant boxes under **Object Permissions** and **Field Permissions**, then click **Save**.

<img />

4. Repeat for every object the integration needs to access.

#### 4. Configure system permissions

1. Select **System Permissions**.

<img />

2. Ensure the [required system permissions](#required-system-permissions) are selected, then click **Save**.

<img />

#### 5. Assign the permission set to the integration user

1. Click **Manage Assignments**.

<img />

2. Click **Add Assignment**.

<img />

3. Select the integration user you created in step 1.

<img />

4. Set **Expires On** to **Never Expires**, then click **Assign**.

<img />

## After installing the integration

Configure OAuth policies so the integration can maintain a stable connection.

<Tabs>
  <Tab title="External Client App">
    1. Log in to **Salesforce**.
    2. Go to **Setup**.
    3. In the **Quick Find** box, search for **External Client App Manager**.
    4. Click the name of the installed External Client App.
    5. Go to the **Policies** tab and click **Edit**.
    6. Under **OAuth Policies**, set **Permitted Users** to **All users may self-authorize**.
    7. Under **App Authorization**:
       * Set **Refresh Token Policy** to **Refresh token is valid until revoked**.
       * Set **IP Relaxation** to **Relax IP restrictions**.
    8. Click **Save**.

    **IP Relaxation** applies to the IP address you sign in from when you authorize the app, not to the IP addresses the integration makes API calls from. If you want to limit where the integration's API calls can come from, see [Restrict API access by IP address](#restrict-api-access-by-ip-address).

    <img alt="Configure ECA OAuth Policies" />
  </Tab>

  <Tab title="Connected App">
    Confirm **Permitted Users** so the right people can authorize the app.

    1. Log in to **Salesforce**.
    2. Go to **Setup**.
    3. In the **Quick Find** box, search for **Connected Apps OAuth Usage**.
    4. Find this integration's connected app and click **Manage App Policies**.
    5. Under **OAuth Policies**, set **Permitted Users** to one of:

       * **Admin approved users are pre-authorized** — only selected users can access.
       * **All users may self-authorize** — all users can access the app.

       <img alt="Permitted Users" />

    If you need to change these settings:

    1. Click **Install** next to your connected app.
    2. In **OAuth Usage and Policies**, set the appropriate permissions level.
    3. Click **Save**.
  </Tab>
</Tabs>

## Restrict API access by IP address

This section is optional. It restricts the addresses that the integration's Salesforce user is allowed to log in from.

All API requests the integration makes to your Salesforce org originate from a [fixed set of Ampersand IP addresses](/security/outgoing-ip-addresses), so you can limit that user to those addresses plus your own.

Two settings are easy to mistake for this one:

* **IP Relaxation** on the app applies to the IP address your browser connects from when you authorize the integration, not to the addresses the integration makes API calls from. Leave it set to **Relax IP restrictions**.
* **Trusted IP Ranges** under **Setup** → **Security** → **Network Access** are not a restriction. Logins from those addresses skip identity verification, but logins from other addresses are still allowed, so listing Ampersand's addresses there does not block a stolen token.

The control that actually restricts access is **Login IP Ranges** on a profile, which is what the steps below configure.

### Before you start

Login IP ranges are set on one profile at a time, from that profile's detail page. If you do not see a **Login IP Ranges** section, check that you opened a profile rather than the profile list, and that your edition sets the ranges on profiles rather than on the Session Settings page (see the note at the end of this section).

You need the **Manage Profiles and Permission Sets** permission to add or edit login IP ranges, and **View Setup and Configuration** to view them.

Two things determine whether this works:

* **Whose profile you restrict.** You choose which profile to put the ranges on, and every user on that profile is then restricted by them. It has to be the profile of whoever authorizes the integration, so if that person is on a shared profile such as **System Administrator**, everyone else on that profile is restricted too. Create a user for the integration and give it a profile of its own.
* **Which addresses you allow.** The list must include Ampersand's addresses **and** the addresses that same user signs in from in a browser. Authorization happens in a browser, so if their own address is missing they cannot log in to connect or reconnect the integration.

### Step 1: Add the allowed IP ranges to the profile

1. Log in to **Salesforce**.
2. Go to **Setup**.
3. In the **Quick Find** box, search for **Profiles** and open the profile list.
4. Click the **name** of the profile belonging to the user who authorizes the integration. Do not click **Edit** next to it; login IP ranges are not on the edit page, only on the profile's detail page.
5. Find **Login IP Ranges** on that detail page:
   * In the original profile interface, scroll to the bottom of the page to the **Login IP Ranges** related list and click **New**.
   * If your org has the enhanced profile user interface enabled, click **Login IP Ranges** in the list of links near the top of the page, then click **Add IP Ranges**.
6. Add one entry for each address listed in [Ampersand's outgoing IP addresses](/security/outgoing-ip-addresses). A single address is entered as a range, so put the same address in both **Start IP Address** and **End IP Address**, and give each entry a description such as `Ampersand` so it is recognizable later.
7. Add one more entry for the range your own users sign in from, so the person who authorizes the integration is not locked out.
8. Click **Save**.

At this point, the user cannot log in from anywhere outside the addresses you listed.

### Step 2: Verify the integration still works

1. Reconnect the integration from your vendor's app.
2. Confirm that data still syncs in both directions.

If requests start failing with login or authentication errors after this change, an address is missing from the profile's login IP ranges.

Restricting login IP addresses is available in all Salesforce editions, but where you set the ranges depends on the edition. In Enterprise, Performance, Unlimited, and Developer editions they are set on a profile, as described above. In other editions they are set from **Setup** → **Session Settings** instead. For details, see Salesforce's guide to [restricting login IP addresses in profiles](https://help.salesforce.com/s/articleView?id=platform.login_ip_ranges.htm\&type=5).

## Subscribe Action permissions

If the integration includes Subscribe Actions, enable these permissions.

Explicitly enable:

* **API Enabled** - allows the integration to make API calls
* **Modify Metadata Through Metadata API Functions** — configure event channels and memberships through Metadata API
* **Customize Application** — configure artifacts like Named Credentials so Ampersand can connect to event channels securely

Salesforce auto-enables these dependent permissions when you enable the ones above:

* **View Setup and Configuration** — access setup configuration to create webhook subscription settings
* **View Roles and Role Hierarchy** — correct visibility context so Salesforce can deliver events (without this, events may be generated but not delivered)
* **Manage Custom Permissions** — create and manage dedicated event channels and channel memberships for the installation

Enable these on the profile (Option A, step 1) or permission set (Option B, step 4) you configured above.

## Custom field management permissions

If the integration creates or updates custom fields in your Salesforce instance, you will need to enable the following permissions:

* **API Enabled** - allows the integration to make API calls
* **Modify Metadata Through Metadata API Functions** — allows the integration to call the Metadata API in order to modify custom fields
* **Customize Application** — allows the creation and update of custom fields
* **Manage Profiles and Permission Sets** - allows a new permission set to be created to give the current user permission to read from and write to the field
* **Assign Permission Sets** - allows the integration to assign the new permission set to the current user

Enable these on the profile (Option A, step 1) or permission set (Option B, step 4) you configured above.


# Salesforce (JWT authentication)
Source: https://docs.ampersand.ai/customer-guides/salesforce-jwt

Connect Salesforce using the OAuth 2.0 JWT Bearer Flow: generate an RSA key pair, create an External Client App, set OAuth policies, and fix auth errors.

This guide walks you through connecting your Salesforce org to an integration that uses the [OAuth 2.0 JWT Bearer Flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm\&language=en_US\&type=5). This is a headless, server-to-server authentication method — there is no interactive login, and the integration runs on behalf of a designated user using credentials you configure up front.

If your integration uses the standard Salesforce OAuth flow instead, please refer to the [Salesforce customer guide](/customer-guides/salesforce). If you are unsure which guide is applicable to you, please ask the integration developer.

## Before installing a Salesforce (JWT) integration

You will need **Administrator access** to your Salesforce org.

### 1. Generate a certificate and RSA private key

The JWT Bearer flow requires an RSA key pair. You'll upload the public certificate to your Salesforce External Client App and share the private key (base64-encoded) with the integration.

Open a terminal in the folder where you want to create the files. You need **OpenSSL** available in that environment (macOS and most Linux distributions include it by default). On **Windows**, use **Git Bash** (bundled with [Git for Windows](https://gitforwindows.org/), which includes OpenSSL), **WSL**, or install OpenSSL and ensure it is on your `PATH`.

Run the following command to generate a 2048-bit RSA private key and a matching self-signed X.509 certificate in a single step:

```bash theme={"dark"}
openssl req -x509 -sha256 -nodes -days 3650 -newkey rsa:2048 \
  -keyout private-key.pem -out cert.pem \
  -subj "/CN=salesforce-jwt-integration"
```

This produces two files:

* `private-key.pem` — Your RSA private key. You will base64-encode this and share it when installing the integration.
* `cert.pem` — Your public certificate. You will upload this to Salesforce in a later step.

<Note>Salesforce requires an RSA key. ECDSA (`ecparam`) keys are not accepted for the JWT Bearer flow. Use a key length of at least 2048 bits.</Note>

You will then need to base64-encode your private key before sharing it during the installation process. Use the command that matches your environment:

**macOS (Terminal)**

```bash theme={"dark"}
base64 -i private-key.pem
```

**Linux, Git Bash, or WSL**

```bash theme={"dark"}
base64 -w 0 private-key.pem
```

**Windows (PowerShell)**

From the directory that contains `private-key.pem`:

```powershell theme={"dark"}
[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path 'private-key.pem')))
```

Copy the encoded string (a long single line, e.g. starting with `LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tL...`). It will be required during the installation process.

### 2. Create the External Client App

The External Client App identifies the integration to Salesforce and holds the certificate used to verify JWT signatures.

1. Log in to *Salesforce* as an Administrator.

2. Navigate to the gear icon in the top right corner and select **Setup**.

   <img alt="Alt text" />

3. Search for **External Client App Manager**.

4. Click **New External Client App**.

<img alt="New ECA" />

5. Fill in the basic information:
   * **External Client App Name**: e.g. `My Integration`
   * **API Name**: auto-filled from the name
   * **Contact Email**: your administrator email
   * **Distribution State**: **Local**
6. Under **API (Enable OAuth Settings)**:
   * Check **Enable OAuth**.
   * For **Callback URL**, enter `https://api.withampersand.com/callbacks/v1/oauth`. The JWT Bearer flow does not use the callback, but Salesforce requires a value.
   * Under **Selected OAuth Scopes**, add:
     * **Manage user data via APIs (`api`)**
     * **Perform requests at any time (`refresh_token`, `offline_access`)** — this is required for Salesforce to accept JWT Bearer exchanges even though no refresh token is issued.
7. Under **Flow Enablement**, check **Enable JWT Bearer Flow** and upload the `cert.pem` file you generated in the previous step.
8. Under **Security**, ensure **Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows** is unchecked. (It's unchecked by default, but worth verifying.)

<Note>Leave **Issue JSON Web Token (JWT)-based access tokens for named users** unchecked. Despite the similar name, this is a different feature that changes the format of access tokens Salesforce returns — and those JWT-format tokens only work with the REST API, not with the Bulk API or Metadata API that this integration also uses. Enabling it will break bulk writes and subscribe-action registration.</Note>
9\. Click **Create**. After saving, it may take 2 to 10 minutes for Salesforce to propagate the new External Client App. If you hit errors when testing the integration immediately after creation, wait a few minutes and try again.

### 3. Copy the Consumer Key

1. In **Setup**, open **External Client App Manager** again.
2. Select your External Client App from the list.
3. Go to the **Settings** tab and expand **OAuth Settings**.
4. Under **App Settings**, click **Consumer Key and Secret**. This opens a new page — you may be prompted to verify your identity before the values are shown.
5. Copy the **Consumer Key**. Store it securely — you will need it during the installation step. (The Consumer Secret is not needed for JWT Bearer flow.)

### 4. Configure OAuth policies

1. In **Setup**, open **External Client App Manager** and select your External Client App.
2. Go to the **Policies** tab, click **Edit**.
3. Expand **OAuth Policies**.
4. Scroll down to **App Authorization** section:
   * Set **Refresh Token Policy** to **Refresh token is valid until revoked**.
   * Set **IP Relaxation** to **Relax IP restrictions**.
5. Click **Save**.

<img />

<Note>Setting **Refresh Token Policy** to **Refresh token is valid until revoked** is also required, even though the JWT Bearer flow never actually issues a refresh token. Salesforce internally checks for a non-expired approval record for the user before issuing an access token, and any other setting causes that approval to age out — which silently breaks the integration later. The other options (`Immediately expire`, `Expire after specific time`, etc.) will cause `invalid_grant` errors.</Note>

### 5. Create an integration user

The JWT Bearer flow runs as a specific Salesforce user. Every API call made by the integration is attributed to this user, and its Profile and permission sets determine what data the integration can read and write.

#### 1. Create a new user

1. Click the gear icon in the top-right corner and select **Setup**.

2. In the left-hand search bar, type **Users** and open it.

3. Create a new user:

* For **User License**, select `Salesforce Integration`.
* For **Profile**, select `Minimum Access - API Only Integrations`.

<img />

#### 2. Create a Permission Set

1. Click the gear icon in the top-right corner and select **Setup**.

2. In the left-hand search bar, type **Permission Sets** and open it.

3. Click on "New" to create a new permission set.

<img />

4. Follow the prompts to create the permission set:

* For the name, you can call it something general like `Integration User Permission Set` or something that describes the level of access it has - such as `Account and Contact Access`.
* In the **License** dropdown, you must select `Salesforce API Integration`.

<img />

#### 3. Configure object permissions

1. Click on **Object Settings**

<img />

2. For each of the objects that the integration needs to access you need to set up its permissions. Start by clicking on the first object, for example "Accounts".

<img />

3. Edit the permission so that all relevant boxes under **Object Permissions** and **Field Permissions** are checked. Then click on **Save**.

<img />

4. Repeat for all the other objects that the integration needs to access.

#### 4. Configure system permissions

1. Select **System Permissions**.

<img />

2. Ensure that the checkboxes for the necessary [system permissions](/customer-guides/salesforce#required-system-permissions) are selected, and then click **Save**.

<img />

#### 5. Assign permission set to integration user

1. Click on **Manage Assignments**.

<img />

2. Click on **Add Assignment**.

<img />

3. Select the integration user you created in step 1.

<img />

4. Ensure "Expires On" is set to "Never Expires", and then click on "Assign".

<img />

<Note>The username you chose when creating the user is exactly the value you'll paste into the **Salesforce Username** field when installing the integration. Copy it somewhere you can find it later.</Note>

### 6. Associate the Permission Set with the app

You need to add the permission set you created in step 5 to the app's pre-authorized Permission Sets list. This is what satisfies the **Admin approved users are pre-authorized** OAuth policy from step 4 — it tells Salesforce "any user who has this permission set is allowed to use this app."

1. In **Setup**, open **External Client App Manager** and select your External Client App.
2. Go to the **Policies** tab, click **Edit**.
3. Expand **OAuth Policies**, under **Plugin Policies**, set **Permitted Users** to **Admin approved users are pre-authorized**. Click on **OK** in the dialog that pops up.

<img />

4. Expand **App Policies**, under **Select Permission Sets**, move the permission set that you created in step 5 from **Available Permission Sets** to **Selected Permission Sets** using the arrow button (`>`).
5. Click **Save**.

<img />

<Note>This is the step that actually pre-authorizes the integration user for JWT Bearer. Without it — even if everything else is configured correctly — Salesforce rejects the JWT assertion with `invalid_app_access: user is not admin approved to access this app`.</Note>

### 7. Confirm your Salesforce subdomain

Your Salesforce My Domain subdomain is the unique part of your Salesforce URL. You will need it to install the integration.

* **Production**: if your login URL is `https://acme.my.salesforce.com`, your subdomain is `acme`.
* **Sandbox (Enhanced Domains)**: if your login URL is `https://acme--dev.sandbox.my.salesforce.com`, your subdomain is `acme--dev.sandbox`.
* **Sandbox (legacy)**: if your login URL is `https://acme--dev.my.salesforce.com`, your subdomain is `acme--dev`.
* **Developer accounts**: if your login URL is `https://acme-dev-ed.develop.my.salesforce.com`, your subdomain is `acme-dev-ed.develop`.

You can also find your subdomain in **Setup** > **My Domain**.

## Installing the integration

When you are installing the integration, you will be prompted for a number of inputs.

Here is where to find each value:

| Input | Where to find it |
| - | - |
| **Consumer Key** | From step 3. |
| **Salesforce Username** | The username of the integration user from step 5. |
| **Private Key** | Base64-encoded contents of `private-key.pem` (from step 1). |
| **Subdomain** | Your My Domain subdomain (from step 7). |

<Note>**Sandbox refresh**: After refreshing a sandbox, the integration user's username may be re-suffixed with the sandbox name (e.g. `integration@acme.com` becomes `integration@acme.com.dev`). If this happens, update the **Salesforce Username** field on your Ampersand connection to match the new username.</Note>

## Troubleshooting

If the integration experiences authentication errors after setup, here are some common causes.

* **`invalid_app_access: user is not admin approved to access this app`**: The integration user's permission set is not in the app's **Selected Permission Sets** list. Revisit step 6 and confirm the permission set from step 5 is in **Selected Permission Sets** (not just **Available Permission Sets**), and that the permission set is actually assigned to the integration user. To reproduce the error independently, use the Salesforce CLI: `sf org login jwt --client-id <key> --jwt-key-file private-key.pem --username <user> --instance-url https://<workspace>.my.salesforce.com`.
* **`user hasn't approved this consumer`**: Either the integration user's permission set is not associated with your app (revisit step 6), or the **Refresh Token Policy** on the app is not set to **Refresh token is valid until revoked** (revisit step 4). Both are required.
* **Worked for weeks or months, then started failing with `invalid_grant`**: Almost always the Refresh Token Policy silently aging out the approval. Set **Refresh Token Policy** to **Refresh token is valid until revoked** and re-associate the permission set if needed.
* **`invalid_grant: audience is invalid`**: The production vs sandbox environment was auto-detected incorrectly from your subdomain. Double-check that your subdomain string matches the format shown in step 7 — sandboxes should include a `--` or `.sandbox` segment.
* **`invalid_grant: invalid assertion`**: The private key or certificate is mismatched. Regenerate the pair in step 1 and re-upload the certificate in step 2.
* **`not authorized`**: Check **IP Relaxation** is set to **Relax IP restrictions** (step 4), and that the integration user's permission set has **API Enabled** under **System Permissions**.
* **Works immediately after setup, then fails**: Wait 2 to 10 minutes after creating or modifying the app for Salesforce to propagate the changes.


# Snowflake
Source: https://docs.ampersand.ai/customer-guides/snowflake

The Snowflake provider is currently in private preview and not yet generally available. Learn how to request access by emailing support@withampersand.com.

This provider is currently in private preview. Please reach out to us at [support@withampersand.com](mailto:support@withampersand.com) to get access.


# Update a connection
Source: https://docs.ampersand.ai/customer-guides/update-connection

Update the credentials for an integration from the Manage tab, including when to re-authenticate, such as a bad_credentials status or switching accounts.

If the credentials you provided for an integration need to be updated, you can use the **Manage** tab in the UI component to update your connection.

## When to update a connection

Re-authentication for the connection may be required in the following scenarios:

* In the **Manage** tab, the **Status** of the connection is showing as "bad\_credentials".
* Your integration isn't working.
* You need to switch to a different account.

## How to update a connection

1. Navigate to the **Manage** tab.

<img alt="Permitted Users" />

2. Under the **Update connection** section enter credentials as needed and click the **Next** button.

## If Manage tab isn't visible

If you do not see the **Manage** tab, it means that the app builder needs to update `@amp-labs/react` to v2.7+ in their code.


# Zoho
Source: https://docs.ampersand.ai/customer-guides/zoho

Prepare your Zoho account by activating Zoho CRM with an organization user, and create Zoho Mail outgoing webhooks for Subscribe Actions.

## Checklist before installing a Zoho integration

Before you proceed with the Zoho integration, you need to have a Zoho account with the Zoho CRM application activated.

If you haven't already done so, follow these steps to activate Zoho CRM on your existing Zoho account.

### Activate Zoho CRM

> **Note:** Having a general Zoho account (e.g., for Zoho Mail or Writer) does not automatically grant you access to Zoho CRM. You must sign up for it explicitly.

If you have not yet activated Zoho CRM, follow these steps:

1. Navigate to the [Zoho CRM signup page](https://www.zoho.com/crm/signup.html).
2. Enter your **Full Name**.
3. Enter your **Work Email**. If this email is already associated with a Zoho account, you will be prompted to sign in.
4. Enter your **Password**.
5. Provide your phone number.
6. Click **GET STARTED**.

   <img alt="Activating ZohoCRM" />

The integration supports all available Zoho CRM editions: Free, Standard, Professional, Enterprise, Ultimate and CRM Plus.
Although some actions like creating custom fields are not supported with the free plan.

### User Permissions

In Zoho CRM, there are two main types of users:

* Organization users

* Team users

You should use an **organization user** account when connecting to the integration.

## Zoho Mail: set up webhooks for real-time updates (Subscribe Actions)

If your integration uses Zoho Mail Subscribe Actions, you need to create an **outgoing webhook** in the Zoho Mail console. Zoho Mail has no API for this, so it must be configured by hand.

### Checklist before you start

* You have a Zoho Mail account with access to the **Developer Space** section of **Settings**.
* Your developer has provided you with a **webhook URL** in this format:

  ```
  https://subscribe-receiver.withampersand.com/zt1secx7jknlhb/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
  ```

### Create the outgoing webhook

1. Sign in to [Zoho Mail](https://mail.zoho.com) and open **Settings**.

2. Scroll to the **Developer Space** section in the left sidebar and select **Webhooks**.

3. Select the **Outgoing Webhooks** tab and click **Create new configuration**.

   <Warning>
     Make sure you are on the **Outgoing Webhooks** tab — that is what sends events from Zoho Mail to your developer's application.
   </Warning>

   <img alt="Outgoing Webhooks in Zoho Mail settings" />

4. Select the entity you want to send events for:
   * **Mail** — fires a webhook each time a new email is received. You can optionally narrow it down with conditions (e.g. sender or subject filters) or tags.
   * **Tasks** — fires a webhook on task activity in groups you own or moderate (you can select up to 3 groups).

5. Give the webhook a name and paste the webhook URL your developer gave you into the **Webhook URL** field.

6. Save the webhook.

If your integration subscribes to both new emails and task activity, create a webhook for each entity, pointing at the same URL.

For official setup details, see the [Zoho Mail outgoing webhook documentation](https://www.zoho.com/mail/help/dev-platform/webhook.html).


# Azure Service Bus destinations
Source: https://docs.ampersand.ai/destinations/azureservicebus

Publish Read and Subscribe Action payloads as JSON messages to an Azure Service Bus queue or topic using a connection string with Send permission.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand publishes the payload as messages to your Azure Service Bus queue or topic.

## Prerequisites

Before setting up an Azure Service Bus destination, ensure that you have:

* An Azure Service Bus namespace with a queue or topic
* A connection string with `Send` permission on that queue or topic

## Data format

Ampersand publishes each read or subscribe message to your queue or topic as JSON. The full payload schema is defined in [webhook.yaml](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml).

## Create an Azure Service Bus destination

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new Azure Service Bus destination.

You'll need to provide:

| Field | Type | Required | Example | Description |
| - | - | - | - | - |
| **Destination name** | string | Yes | `ampersandServiceBus` | Alias to reference in your `amp.yaml` file |
| **Name** | string | Yes | `ampersand-events` | Name of the queue or topic to publish to |
| **Connection string** | string | Yes | | Connection string with `Send` permission |

## Refer to the destination in your integration

After creating your Azure Service Bus destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToServiceBus
    displayName: Salesforce to Azure Service Bus
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandServiceBus
        - objectName: contact
          destination: ampersandServiceBus
```


# BigQuery destinations
Source: https://docs.ampersand.ai/destinations/bigquery

Insert Read and Subscribe Action data into a Google BigQuery table with id and payload columns, using a service account key and optional batch settings.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand inserts the payload as rows into your Google BigQuery table.

## Prerequisites

Before setting up a BigQuery destination, ensure that you have:

* A Google Cloud project with BigQuery enabled
* A dataset and table to insert into (see [Data format and table setup](#data-format-and-table-setup))
* A service account with the `BigQuery Data Editor` role (or `bigquery.tables.updateData` permission) on that dataset, and a JSON key for it

## Data format and table setup

Ampersand delivers each read or subscribe message as a JSON object. The full payload schema is defined in [webhook.yaml](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml).

The BigQuery destination writes each message into two columns: `id` (a generated identifier) and `payload` (the full message JSON, written as a string). Create the table with exactly these columns:

```sql theme={"dark"}
CREATE TABLE `my-project.my_dataset.my_table` (
  id STRING,
  payload STRING
);
```

## Create a BigQuery destination

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new BigQuery destination.

You'll need to provide:

| Field | Type | Required | Example | Description |
| - | - | - | - | - |
| **Destination name** | string | Yes | `ampersandBigQuery` | Alias to reference in your `amp.yaml` file |
| **Project ID** | string | Yes | `my-gcp-project` | Google Cloud project ID |
| **Dataset ID** | string | Yes | `analytics` | BigQuery dataset ID |
| **Table ID** | string | Yes | `ampersand_events` | BigQuery table ID |
| **Service account credentials** | string | Yes | | Service account key JSON with write access to the table |
| **Batch size** | integer | No | `1000` | Rows to buffer before flushing a batch (defaults to 1000) |
| **Max wait (seconds)** | integer | No | `30` | Max seconds to wait before flushing a batch (defaults to 30) |

## Refer to the destination in your integration

After creating your BigQuery destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToBigQuery
    displayName: Salesforce to BigQuery
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandBigQuery
        - objectName: contact
          destination: ampersandBigQuery
```


# ClickHouse destinations
Source: https://docs.ampersand.ai/destinations/clickhouse

Insert synced data into a ClickHouse table over HTTPS, matching payload keys to column names, and configure the URL, credentials, database, and batch size.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand inserts the payload as rows into your ClickHouse table.

## Prerequisites

Before setting up a ClickHouse destination, ensure that you have:

* A ClickHouse instance reachable over HTTPS (ClickHouse Cloud or self-hosted)
* A table to insert into (see [Data format and table setup](#data-format-and-table-setup))
* A username and password with `INSERT` privileges on that table

## Data format and table setup

Ampersand delivers each read or subscribe message as a JSON object. The full payload schema is defined in [webhook.yaml](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml).

ClickHouse matches the payload's top-level keys to your table's columns by name. Create a column for each top-level key you want to store. Keys with no matching column are ignored. `result` is the array of synced records; store it as a JSON string.

```sql theme={"dark"}
CREATE TABLE ampersand_events (
  action         String,
  objectName     String,
  operationId    String,
  installationId String,
  operationTime  String,
  result         String,
  ...
)
ENGINE = MergeTree()
ORDER BY tuple();
```

## Create a ClickHouse destination

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new ClickHouse destination.

You'll need to provide:

| Field | Type | Required | Example | Description |
| - | - | - | - | - |
| **Destination name** | string | Yes | `ampersandClickHouse` | Alias to reference in your `amp.yaml` file |
| **URL** | string | Yes | `https://abc.clickhouse.cloud:8443` | HTTPS URL of your ClickHouse instance |
| **Username** | string | Yes | `default` | ClickHouse username |
| **Password** | string | Yes | | ClickHouse password |
| **Table name** | string | Yes | `ampersand_events` | Table to insert rows into |
| **Database** | string | Yes | `analytics` | Database containing the table |
| **Batch size** | integer | No | `1000` | Rows to buffer before flushing a batch (defaults to 1000) |
| **Max wait (seconds)** | integer | No | `30` | Max seconds to wait before flushing a batch (defaults to 30) |

## Refer to the destination in your integration

After creating your ClickHouse destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToClickHouse
    displayName: Salesforce to ClickHouse
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandClickHouse
        - objectName: contact
          destination: ampersandClickHouse
```


# Kinesis destinations
Source: https://docs.ampersand.ai/destinations/kinesis

Send Read and Subscribe Action messages to an AWS Kinesis stream: create the stream and IAM credentials, set partition keys, and review the message format.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand can send the payload to your AWS Kinesis stream.

## Prerequisites

Before setting up a Kinesis destination, ensure that you have:

* An AWS account with access to Kinesis
* A Kinesis stream (or permissions to create one)
* AWS credentials with the following permissions:
  * `kinesis:PutRecord`
  * `kinesis:PutRecords`
  * `kinesis:DescribeStream`

## Create a Kinesis destination

### Step 1: Set up your Kinesis stream

If you don't already have a Kinesis stream, create one in the AWS Console or using the AWS CLI:

```bash theme={"dark"}
aws kinesis create-stream \
  --stream-name ampersand-integration-stream \
  --shard-count 1 \
  --region us-west-2
```

Wait for the stream to become active. You can check by running this command:

```bash theme={"dark"}
aws kinesis describe-stream \
  --stream-name ampersand-integration-stream \
  --region us-west-2
```

You should see `"StreamStatus": "ACTIVE"` in the response.

### Step 2: Create AWS credentials

Create an IAM user or role with permissions to write to your Kinesis stream. You need:

* **AWS Access Key ID**
* **AWS Secret Access Key**
* **AWS Session Token** (optional, for temporary credentials)

**Example IAM policy:**

```json theme={"dark"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesis:PutRecord",
        "kinesis:PutRecords",
        "kinesis:DescribeStream"
      ],
      "Resource": "arn:aws:kinesis:us-west-2:123456789012:stream/ampersand-integration-stream"
    }
  ]
}
```

### Step 3: Add the destination to Ampersand

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new Kinesis destination.

You'll need to provide:

| Field | Type | Required | Description |
| - | - | - | - |
| **Destination name** | string | Yes | Alias to reference in your `amp.yaml` file |
| **Stream name** | string | Yes | Name of your Kinesis stream |
| **Region** | string | Yes | AWS region where your stream is located (e.g., `us-west-2`) |
| **AWS Access Key ID** | string | Yes | AWS access key with Kinesis permissions |
| **AWS Secret Access Key** | string | Yes | AWS secret access key |
| **AWS Session Token** | string | No | Session token for temporary credentials |
| **Partition key template** | string | No | [JMESPath](https://jmespath.org) template for partition key |
| **Endpoint URL** | string | No | Custom Kinesis endpoint if applicable (e.g. when using [LocalStack](https://www.localstack.cloud)) |

## Refer to the destination in your integration

After creating your Kinesis destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToKinesis
    displayName: Salesforce to Kinesis
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandKinesisStream
        - objectName: contact
          destination: ampersandKinesisStream
```

## Message format

Ampersand sends messages to your Kinesis stream in JSON format. All data is wrapped in a top-level `data` object.

### Read action messages

```json theme={"dark"}
{
  "data": {
    "action": "read",
    "projectId": "9482e676-4874-43a4-beea-fa8081d13a07",
    "provider": "hubspot",
    "groupRef": "group-id-1",
    "groupName": "group-name-1",
    "consumerRef": "user-id",
    "consumerName": "user-name",
    "installationId": "085353b1-07f1-4209-b471-7e028c0a68c8",
    "installationUpdateTime": "2025-10-14T02:58:55.595861Z",
    "objectName": "contacts",
    "operationId": "0199e0a8-149d-7ee9-9f50-0514403517f9",
    "operationTime": "2025-10-14T02:58:59.323405308Z",
    "result": [
      {
        "fields": {
          "id": "438",
          "firstname": "Maria",
          "lastname": "Johnson",
          "email": "maria@example.com",
          "city": "Brisbane"
        },
        "raw": {
          "archived": false,
          "createdAt": "2023-10-26T17:55:48.301Z",
          "id": "438",
          "properties": {
            "firstname": "Maria",
            "lastname": "Johnson",
            "email": "maria@example.com",
            "city": "Brisbane",
            "createdate": "2023-10-26T17:55:48.301Z"
          }
        }
      }
    ]
  }
}
```

**Key fields:**

* `action`: The action type (`read` or `subscribe`)
* `projectId`: Your Ampersand project identifier
* `provider`: The SaaS provider name (e.g., `hubspot`, `salesforce`)
* `groupRef` / `groupName`: Customer group identifier and name
* `consumerRef` / `consumerName`: End user identifier and name
* `installationId`: The installation instance ID
* `installationUpdateTime`: When the installation was last updated
* `objectName`: The object being synced
* `operationId`: Unique identifier for this sync operation
* `operationTime`: When the operation completed
* `result`: Array of records synced
  * `fields`: Normalized field data
  * `raw`: Original API response from the provider

### Subscribe action messages

Subscribe action messages follow the same structure as read actions, but include additional event-related fields within each result entry:

```json theme={"dark"}
{
  "data": {
    "action": "subscribe",
    "projectId": "9482e676-4874-43a4-beea-fa8081d13a07",
    "provider": "salesforce",
    "groupRef": "webhook-demo-group-id",
    "groupName": "webhook-demo-group-name",
    "consumerRef": "user-id",
    "consumerName": "user-name",
    "installationId": "0c9230e1c-8fbe-4b28-bf10-2beee8fbf4ce",
    "installationUpdateTime": "2025-04-10T23:00:52.618406Z",
    "objectName": "company",
    "operationTime": "2025-04-10T23:22:25.000Z",
    "result": [
      {
        "fields": {
          "id": "001Dp00000ZDgmxIAD",
          "annualrevenue": null,
          "website": null
        },
        "subscribeEventType": "update",
        "providerEventType": "UPDATE",
        "raw": {
          "Id": "001Dp00000ZDgmxIAD",
          "AnnualRevenue": null,
          "Description": "Notes about the account",
          "Name": "Acme Corp",
          "Website": null,
          "attributes": {
            "type": "Account",
            "url": "/services/data/v59.0/sobjects/Account/001Dp00000ZDgmxIAD"
          }
        },
        "rawEvent": {
          "ChangeEventHeader": {
            "changeOrigin": "com/salesforce/api/soap/63.0;client=SfdcInternalAPI/",
            "changeType": "UPDATE",
            "changedFields": ["Description", "LastModifiedDate"],
            "commitNumber": 12041091891110,
            "commitTimestamp": 1744327345000,
            "commitUser": "005Dp000003Cd1SIAS",
            "entityName": "Account",
            "recordId": "001Dp00000ZDgmxIAD",
            "sequenceNumber": 1,
            "transactionKey": "00051705-2e99-d1e5-7e7a-48e3af682d07"
          },
          "Description": "Notes about the account",
          "LastModifiedDate": "2025-04-10T23:22:25.000Z"
        }
      }
    ]
  }
}
```

**Additional fields in subscribe actions:**

* `subscribeEventType`: Normalized event type (`create`, `update`, `delete`, `associationUpdate`)
* `providerEventType`: Raw event type from the provider API
* `rawEvent`: Original webhook event from the provider (when available)

## Partition key configuration

Kinesis uses partition keys to distribute messages across shards. (Learn more in [the AWS docs](https://docs.aws.amazon.com/streams/latest/dev/key-concepts.html)). You can customize the partition key using a JMESPath template. JMESPath is a query language for JSON. See [jmespath.org](https://jmespath.org) for the full specification.

You can specify a partition key template when creating a Kinesis destination in the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/destinations). If you don't specify one, by default we use the message ID as the partition key, so the messages we send will be evenly distributed across your shards.

### Custom partition key examples

You can customize the partition key by using any of the attributes inside of the message. Since all message data is wrapped in a `data` object, you need to prefix your JMESPath expressions with `data.`. Here are some examples:

**Use installation ID:**

```
data.installationId
```

**Use group reference:**

```
data.groupRef
```

**Use object name:**

```
data.objectName
```

**Combine multiple fields:**

```
join('_', [data.groupRef, data.objectName])
```

**Use operation ID:**

```
data.operationId
```

## Troubleshooting

### Messages not appearing in Kinesis

**Check destination configuration:**

1. Verify that the stream name and region are correct in the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/destinations).
2. Test your AWS credentials:
   ```bash theme={"dark"}
   aws kinesis describe-stream \
     --stream-name your-stream-name \
     --region your-region
   ```
3. Check that IAM permissions for the credential include `kinesis:PutRecord` and `kinesis:PutRecords`.

## Limitations

* **Message size**: Individual records cannot exceed 1 MB (AWS Kinesis limit). If a single record is bigger than this limit, we send it to you in a download URL, similar to what we do for webhook destinations. ([More details here](/destinations/webhooks#read-action-webhooks)).
* **Throughput**: Limited by Kinesis shard capacity (1 MB/sec write per shard).
* **Retention**: Messages are retained for 24 hours to 365 days (configurable in AWS).
* **Ordering**: Only guaranteed within a single partition key.

<Info>
  If you hit these limits, contact `support@withampersand.com` to discuss scaling strategies.
</Info>


# Route synced data and notifications to destinations
Source: https://docs.ampersand.ai/destinations/overview

Learn which destinations Ampersand supports, how to add one in the Dashboard, and how to route Read Action, Subscribe Action, and notification data to it.

Ampersand supports webhook and Slack destinations, S3, a range of data warehouse destinations (ClickHouse, Snowflake, BigQuery, and Redshift), and a range of stream and queue destinations (Kinesis, Amazon SQS, Google Cloud Pub/Sub, RabbitMQ, and Azure Service Bus). Destinations allow you to route data synced from SaaS instances via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), and to receive real-time [Notifications](/notifications) about important lifecycle events in your projects.

## Add a destination to the Ampersand Dashboard

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard to add a new Destination. You'll need to provide:

* **Destination name**: this is an alias for the destination that you can then refer to in the `amp.yaml` file.
* **URL**: this is the URL of your webhook destination. It must start with `https`. In the case of webhooks, you can easily create a temporary one using tools like [Hookdeck Console](https://console.hookdeck.com?provider=ampersand).

## Using destinations for data delivery

For read and subscribe actions, you can specify destinations for each object. You can either have one destination for each object or route multiple objects to the same destination. Here's what your `amp.yaml` file might look like if you had created 2 destinations in the Ampersand Dashboard, one named `accountWebhook` and one named `contactWebhook`.

```YAML YAML theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: readFromSalesforce
    displayName: Salesforce read
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: accountWebhook
        - objectName: contact
          destination: contactWebhook
```

## Using destinations for notifications

Destinations can also be used to receive [notifications](/notifications) about important lifecycle events in your project, such as when customers install or update integrations, when backfills complete, or when sync issues occur. Notifications use a topic-based routing system where you connect event types to topics, and topics to destinations. See the [Notifications overview](/notifications) for complete setup instructions.

## Supported destinations

* [Webhook destinations](/destinations/webhooks)
* [Slack destinations](/destinations/slack)

### Blob storage

* [Amazon S3 destinations](/destinations/s3)

### Databases and warehouses

* [ClickHouse destinations](/destinations/clickhouse)
* [Snowflake destinations](/destinations/snowflake)
* [BigQuery destinations](/destinations/bigquery)
* [Amazon Redshift destinations](/destinations/redshift)

### Streams and queues

* [Azure Service Bus destinations](/destinations/azureservicebus)
* [Amazon Kinesis destinations](/destinations/kinesis)
* [Google Cloud Pub/Sub destinations](/destinations/pubsub)
* [RabbitMQ destinations](/destinations/rabbitmq)
* [Amazon SQS destinations](/destinations/sqs)

## Other Destinations

We have more destination types on the roadmap, including:

* Postgres
* Ampersand-hosted Postgres


# Google Cloud Pub/Sub destinations
Source: https://docs.ampersand.ai/destinations/pubsub

Publish Read and Subscribe Action payloads as JSON to a Google Cloud Pub/Sub topic using a project ID, topic ID, and a Pub/Sub Publisher service account.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand publishes the payload as messages to your Google Cloud Pub/Sub topic.

## Prerequisites

Before setting up a Pub/Sub destination, ensure that you have:

* A Google Cloud project with a Pub/Sub topic
* A service account with the `Pub/Sub Publisher` role (or `pubsub.topics.publish` permission) on that topic, and a JSON key for it

## Data format

Ampersand publishes each read or subscribe message to your topic as JSON. The full payload schema is defined in [webhook.yaml](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml).

## Create a Pub/Sub destination

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new Pub/Sub destination.

You'll need to provide:

| Field | Type | Required | Example | Description |
| - | - | - | - | - |
| **Destination name** | string | Yes | `ampersandPubSub` | Alias to reference in your `amp.yaml` file |
| **Project ID** | string | Yes | `my-gcp-project` | Google Cloud project ID |
| **Topic ID** | string | Yes | `ampersand-events` | Pub/Sub topic ID |
| **Service account credentials** | string | Yes | | Service account key JSON with publish access to the topic |

## Refer to the destination in your integration

After creating your Pub/Sub destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToPubSub
    displayName: Salesforce to Pub/Sub
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandPubSub
        - objectName: contact
          destination: ampersandPubSub
```


# RabbitMQ destinations
Source: https://docs.ampersand.ai/destinations/rabbitmq

Publish synced data as JSON messages to an existing RabbitMQ exchange, setting the server URL, optional TLS, and publish credentials in the Dashboard.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand publishes the payload as messages to your RabbitMQ instance.

## Prerequisites

Before setting up a RabbitMQ destination, ensure that you have:

* A RabbitMQ instance reachable from the internet
* An exchange that already exists on that instance
* A username and password with permission to publish to that exchange

## Data format

Ampersand publishes each read or subscribe message to your RabbitMQ exchange as JSON. The full payload schema is defined in [webhook.yaml](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml).

## Create a RabbitMQ destination

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new RabbitMQ destination.

You'll need to provide:

| Field | Type | Required | Example | Description |
| - | - | - | - | - |
| **Destination name** | string | Yes | `ampersandRabbitMQ` | Alias to reference in your `amp.yaml` file |
| **Server URL** | string | Yes | `rabbitmq.example.com:5672` | Host and port of your RabbitMQ instance |
| **Exchange** | string | Yes | `ampersand-events` | Name of an exchange that already exists |
| **TLS** | boolean | No | `false` | Whether to connect over TLS. Defaults to false (plain AMQP); set to true for managed brokers that require TLS, e.g. CloudAMQP |
| **Username** | string | Yes | `ampersand` | Username with permission to publish |
| **Password** | string | Yes | | Password for the username |

## Refer to the destination in your integration

After creating your RabbitMQ destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToRabbitMQ
    displayName: Salesforce to RabbitMQ
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandRabbitMQ
        - objectName: contact
          destination: ampersandRabbitMQ
```


# Amazon Redshift destinations
Source: https://docs.ampersand.ai/destinations/redshift

Insert synced data into an Amazon Redshift Serverless table via the Redshift Data API, using created_at and payload columns, AWS credentials, and batching.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand inserts the payload as rows into your Amazon Redshift table, delivered to a Redshift Serverless workgroup.

## Prerequisites

Before setting up a Redshift destination, ensure that you have:

* An Amazon Redshift Serverless workgroup
* A target database, and a table to insert into (see [Data format and table setup](#data-format-and-table-setup))
* AWS credentials with permission to run the Redshift Data API and insert into the target table

## Data format and table setup

Ampersand delivers each read or subscribe message as a JSON object. The full payload schema is defined in [webhook.yaml](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml).

The Redshift destination writes each message into two columns: `created_at` (the insert time) and `payload` (the full message JSON). The payload is written as a string, so `payload` must be a character column large enough to hold it. Create the table like this:

```sql theme={"dark"}
CREATE TABLE events (
  created_at TIMESTAMP,
  payload    VARCHAR(65535)
);
```

## Create a Redshift destination

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new Redshift destination.

You'll need to provide:

| Field | Type | Required | Example | Description |
| - | - | - | - | - |
| **Destination name** | string | Yes | `ampersandRedshift` | Alias to reference in your `amp.yaml` file |
| **Region** | string | Yes | `us-west-2` | AWS region where your Redshift resource lives |
| **AWS Access Key ID** | string | Yes | `AKIAIOSFODNN7EXAMPLE` | AWS access key with Redshift Data API permissions |
| **AWS Secret Access Key** | string | Yes | | AWS secret access key |
| **Database** | string | Yes | `dev` | Target database name |
| **Schema** | string | Yes | `public` | Target schema |
| **Table name** | string | Yes | `events` | Target table |
| **Workgroup name** | string | Yes | `my-workgroup` | Redshift Serverless workgroup name |
| **Batch size** | integer | No | `1000` | Rows to buffer before flushing a batch (defaults to 1000) |
| **Max wait (seconds)** | integer | No | `30` | Max seconds to wait before flushing a batch (defaults to 30) |

## Refer to the destination in your integration

After creating your Redshift destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToRedshift
    displayName: Salesforce to Redshift
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandRedshift
        - objectName: contact
          destination: ampersandRedshift
```


# Amazon S3 destinations
Source: https://docs.ampersand.ai/destinations/s3

Write Read and Subscribe Action payloads as JSON objects to an Amazon S3 bucket, with IAM setup, object key templates, storage class, and troubleshooting.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand can write the payload as objects to your Amazon S3 bucket.

## Prerequisites

Before setting up an S3 destination, ensure that you have:

* An AWS account with access to S3
* An S3 bucket (or permissions to create one)
* AWS credentials with the following permission:
  * `s3:PutObject`

## Create an S3 destination

### Step 1: Set up your S3 bucket

If you don't already have an S3 bucket, create one in the AWS Console or using the AWS CLI:

```bash theme={"dark"}
aws s3api create-bucket \
  --bucket ampersand-integration-bucket \
  --region us-west-2 \
  --create-bucket-configuration LocationConstraint=us-west-2
```

### Step 2: Create AWS credentials

Create an IAM user or role with permissions to write to your S3 bucket. You need:

* **AWS Access Key ID**
* **AWS Secret Access Key**
* **AWS Session Token** (optional, for temporary credentials)

**Example IAM policy:**

```json theme={"dark"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::ampersand-integration-bucket/*"
    }
  ]
}
```

### Step 3: Add the destination to Ampersand

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new S3 destination.

You'll need to provide:

| Field | Type | Required | Description |
| - | - | - | - |
| **Destination name** | string | Yes | Alias to reference in your `amp.yaml` file |
| **Bucket** | string | Yes | Name of your S3 bucket |
| **Region** | string | Yes | AWS region where your bucket is located (e.g., `us-west-2`) |
| **AWS Access Key ID** | string | Yes | AWS access key with S3 permissions |
| **AWS Secret Access Key** | string | Yes | AWS secret access key |
| **AWS Session Token** | string | No | Session token for temporary credentials |
| **Object key template** | string | No | [JMESPath](https://jmespath.org) template for object key naming |
| **Storage class** | string | No | S3 storage class for written objects (defaults to `STANDARD`) |

## Refer to the destination in your integration

After creating your S3 destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToS3
    displayName: Salesforce to S3
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandS3Bucket
        - objectName: contact
          destination: ampersandS3Bucket
```

## Message format

Ampersand writes each message as a JSON object to your S3 bucket. The object body is the message payload itself — there is no wrapper envelope.

In addition to the object body, each S3 object carries event metadata as [S3 object metadata](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html) (`x-amz-meta-*` headers), including `projectId`, `installationId`, `connectionId`, `destinationId`, `operationId`, `objectName`, `event-id`, `timestamp`, and `topic`.

### Read action messages

```json theme={"dark"}
{
  "action": "read",
  "projectId": "9482e676-4874-43a4-beea-fa8081d13a07",
  "provider": "hubspot",
  "groupRef": "group-id-1",
  "groupName": "group-name-1",
  "consumerRef": "user-id",
  "consumerName": "user-name",
  "installationId": "085353b1-07f1-4209-b471-7e028c0a68c8",
  "installationUpdateTime": "2025-10-14T02:58:55.595861Z",
  "objectName": "contacts",
  "operationId": "0199e0a8-149d-7ee9-9f50-0514403517f9",
  "operationTime": "2025-10-14T02:58:59.323405308Z",
  "result": [
    {
      "fields": {
        "id": "438",
        "firstname": "Maria",
        "lastname": "Johnson",
        "email": "maria@example.com",
        "city": "Brisbane"
      },
      "raw": {
        "archived": false,
        "createdAt": "2023-10-26T17:55:48.301Z",
        "id": "438",
        "properties": {
          "firstname": "Maria",
          "lastname": "Johnson",
          "email": "maria@example.com",
          "city": "Brisbane",
          "createdate": "2023-10-26T17:55:48.301Z"
        }
      }
    }
  ]
}
```

**Key fields:**

* `action`: The action type (`read` or `subscribe`)
* `projectId`: Your Ampersand project identifier
* `provider`: The SaaS provider name (e.g., `hubspot`, `salesforce`)
* `groupRef` / `groupName`: Customer group identifier and name
* `consumerRef` / `consumerName`: End user identifier and name
* `installationId`: The installation instance ID
* `installationUpdateTime`: When the installation was last updated
* `objectName`: The object being synced
* `operationId`: Unique identifier for this sync operation
* `operationTime`: When the operation completed
* `result`: Array of records synced
  * `fields`: Normalized field data
  * `raw`: Original API response from the provider

### Subscribe action messages

Subscribe action messages follow the same structure as read actions, but include additional event-related fields within each result entry:

```json theme={"dark"}
{
  "action": "subscribe",
  "projectId": "9482e676-4874-43a4-beea-fa8081d13a07",
  "provider": "salesforce",
  "groupRef": "webhook-demo-group-id",
  "groupName": "webhook-demo-group-name",
  "consumerRef": "user-id",
  "consumerName": "user-name",
  "installationId": "0c9230e1-8fbe-4b28-bf10-2beee8fbf4ce",
  "installationUpdateTime": "2025-04-10T23:00:52.618406Z",
  "objectName": "company",
  "operationTime": "2025-04-10T23:22:25.000Z",
  "result": [
    {
      "fields": {
        "id": "001Dp00000ZDgmxIAD",
        "annualrevenue": null,
        "website": null
      },
      "subscribeEventType": "update",
      "providerEventType": "UPDATE",
      "raw": {
        "Id": "001Dp00000ZDgmxIAD",
        "AnnualRevenue": null,
        "Description": "Notes about the account",
        "Name": "Acme Corp",
        "Website": null,
        "attributes": {
          "type": "Account",
          "url": "/services/data/v59.0/sobjects/Account/001Dp00000ZDgmxIAD"
        }
      },
      "rawEvent": {
        "ChangeEventHeader": {
          "changeOrigin": "com/salesforce/api/soap/63.0;client=SfdcInternalAPI/",
          "changeType": "UPDATE",
          "changedFields": ["Description", "LastModifiedDate"],
          "commitNumber": 12041091891110,
          "commitTimestamp": 1744327345000,
          "commitUser": "005Dp000003Cd1SIAS",
          "entityName": "Account",
          "recordId": "001Dp00000ZDgmxIAD",
          "sequenceNumber": 1,
          "transactionKey": "00051705-2e99-d1e5-7e7a-48e3af682d07"
        },
        "Description": "Notes about the account",
        "LastModifiedDate": "2025-04-10T23:22:25.000Z"
      }
    }
  ]
}
```

**Additional fields in subscribe actions:**

* `subscribeEventType`: Normalized event type (`create`, `update`, `delete`, `associationUpdate`)
* `providerEventType`: Raw event type from the provider API
* `rawEvent`: Original webhook event from the provider (when available)

## Object key configuration

Each message is written as a separate object in your bucket. You can customize the object key (the object's path within the bucket) using a JMESPath template. JMESPath is a query language for JSON. See [jmespath.org](https://jmespath.org) for the full specification.

You can specify an object key template when creating an S3 destination in the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/destinations). If you don't specify one, the default key is the message timestamp followed by the message ID:

```
2025-10-14T02:58:59.323405308Z_0199e0a8-149d-7ee9-9f50-0514403517f9.json
```

### Template context

Your template can reference three namespaces:

| Namespace | Fields |
| - | - |
| `metadata` | `projectId`, `installationId`, `connectionId`, `destinationId`, `operationId`, `objectName`, `event-id`, `timestamp`, `topic` |
| `time` | `year`, `month`, `day`, `hour`, `minute`, `second`, `date`, `datetime`, `unix`, `rfc3339`, `rfc3339_nano` |
| `data` | The message payload (e.g., `data.installationId` — see [Message format](#message-format) above) |

<Info>
  JMESPath is case-sensitive: `metadata.operationId` works, `metadata.operationid` does not. Fields containing a hyphen must be quoted, e.g. `metadata."event-id"`. Templates are validated when you create or update the destination.
</Info>

### Custom object key examples

**Group objects by synced object name:**

```
join('/', [metadata.objectName, metadata.operationId])
```

**Partition by date:**

```
join('/', [metadata.objectName, time.date, metadata."event-id"])
```

**Add a file extension:**

```
join('', [time.rfc3339_nano, '_', metadata."event-id", '.json'])
```

**Use a field from the payload:**

```
join('/', [data.installationId, metadata.operationId])
```

<Info>
  Make sure your template produces a unique key for every message — include `metadata."event-id"` or `metadata.operationId`. If two messages evaluate to the same key, the later object overwrites the earlier one.
</Info>

## Storage class

By default, objects are written with the `STANDARD` storage class. You can choose a different class when creating the destination, such as `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING`, `GLACIER`, `GLACIER_IR`, or `DEEP_ARCHIVE`. See [the AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html) for a comparison.

## Troubleshooting

### Objects not appearing in S3

**Check destination configuration:**

1. Verify that the bucket name and region are correct in the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/destinations).
2. Test your AWS credentials:
   ```bash theme={"dark"}
   echo '{}' > test.json
   aws s3api put-object \
     --bucket your-bucket-name \
     --key ampersand-test.json \
     --body test.json
   ```
3. Check that IAM permissions for the credential include `s3:PutObject` on the bucket.

## Limitations

* **Message size**: Unlike Kinesis, S3 destinations have no practical message size limit — large payloads are written directly to your bucket.
* **One object per message**: Each message becomes a separate S3 object. High-volume syncs produce many small objects, which affects S3 request costs.
* **Ordering**: S3 objects are independent; there are no ordering guarantees. Use the `timestamp` object metadata or a time-based key template to order messages.

<Info>
  If you have questions about scaling, contact `support@withampersand.com`.
</Info>


# Slack destinations
Source: https://docs.ampersand.ai/destinations/slack

Set up a Slack destination with an incoming webhook URL to post notifications and small read or subscribe payloads, and understand message truncation.

For more information on destinations, see the [Destinations](/destinations) page.

A Slack destination delivers messages to a Slack channel using a [Slack incoming webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks). It's a great fit for [Notifications](/notifications) or quickly testing webhook payloads. For example, posting a message to your team's channel whenever a customer connects an integration or a sync runs into an error may be a good fit for this destination.

## Setting up a Slack destination

1. In Slack, [create a Slack app](https://api.slack.com/apps?new_app=1) (or use an existing one), enable **Incoming Webhooks**, and add a webhook to the channel you want Ampersand to post to. Slack gives you a URL that looks like `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX`.
2. In the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/destinations), add a new destination of type **Slack** and paste in that URL. (The URL must be a `hooks.slack.com` URL.)

<Note>
  The Slack channel is fixed when you create the incoming webhook. Ampersand posts to that channel and cannot override it.
</Note>

## Notifications

Notifications are rendered as a short, human-friendly sentence, followed by the raw notification payload for full detail. For example, a `connection.error` notification appears as:

> ⚠️ Salesforce connection for Acme (ID `conn_123`) encountered an error: The refresh token is invalid or expired
>
> ```
> {"notificationType":"connection.error","data":{ ... }}
> ```

You can route notification events to a Slack destination the same way as any other destination. See the [Notifications overview](/notifications) for setup.

## Read & subscribe data

Data read via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions) is delivered as the JSON payload nested directly into the Slack message text.

<Warning>
  Slack renders roughly **16-20 KB** per message and **silently truncates** anything larger. The request still succeeds, so oversized content is dropped without an error. Be careful using Slack destinations for data delivery: a large record or batch may be cut off. For anything beyond small payloads, use a [webhook](/destinations/webhooks), [Kinesis](/destinations/kinesis), or [S3](/destinations/s3) destination instead.
</Warning>


# Snowflake destinations
Source: https://docs.ampersand.ai/destinations/snowflake

Send read and subscribe data into a Snowflake table with key-pair authentication, create the id, created_at, and payload columns, and set batching.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand inserts the payload as rows into your Snowflake table.

## Prerequisites

Before setting up a Snowflake destination, ensure that you have:

* A Snowflake account
* A user configured for [key-pair authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth) (Ampersand authenticates with an RSA private key, not a password)
* A target database, schema, and table (see [Data format and table setup](#data-format-and-table-setup)), with `INSERT` privileges granted to that user

## Data format and table setup

Ampersand delivers each read or subscribe message as a JSON object. The full payload schema is defined in [webhook.yaml](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml).

The Snowflake destination writes each message into three columns: `id` (a generated identifier), `created_at` (the insert time), and `payload` (the full message JSON, written as text). Create the table with exactly these columns:

```sql theme={"dark"}
CREATE TABLE my_db.my_schema.my_table (
  id         TEXT,
  created_at TIMESTAMP,
  payload    TEXT
);
```

## Create a Snowflake destination

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new Snowflake destination.

You'll need to provide:

| Field | Type | Required | Example | Description |
| - | - | - | - | - |
| **Destination name** | string | Yes | `ampersandSnowflake` | Alias to reference in your `amp.yaml` file |
| **Account identifier** | string | Yes | `myorg-myaccount` | Your Snowflake account identifier |
| **User ID** | string | Yes | `SVC_AMPERSAND` | Snowflake user configured for key-pair auth |
| **Private key** | string | Yes | | Unencrypted **PKCS#8** PEM-encoded RSA private key for that user (headers `-----BEGIN PRIVATE KEY-----`). Convert a PKCS#1 key with `openssl pkcs8 -topk8 -nocrypt` |
| **Database** | string | Yes | `ANALYTICS` | Target database |
| **Schema** | string | Yes | `PUBLIC` | Target schema |
| **Table name** | string | Yes | `ampersand_events` | Target table |
| **Batch size** | integer | No | `1000` | Rows to buffer before flushing a batch (defaults to 1000) |
| **Max wait (seconds)** | integer | No | `30` | Max seconds to wait before flushing a batch (defaults to 30) |

## Refer to the destination in your integration

After creating your Snowflake destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToSnowflake
    displayName: Salesforce to Snowflake
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandSnowflake
        - objectName: contact
          destination: ampersandSnowflake
```


# Amazon SQS destinations
Source: https://docs.ampersand.ai/destinations/sqs

Publish read and subscribe action data as JSON messages to an Amazon SQS queue using a queue URL and AWS credentials with sqs:SendMessage permission.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand publishes the payload as messages to your Amazon SQS queue.

## Prerequisites

Before setting up an SQS destination, ensure that you have:

* An AWS account with an SQS queue
* AWS credentials with `sqs:SendMessage` permission on that queue

## Data format

Ampersand publishes each read or subscribe message to your queue as JSON. The full payload schema is defined in [webhook.yaml](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml).

## Create an SQS destination

Go to the [Destinations page](https://dashboard.withampersand.com/projects/_/destinations) in the Ampersand Dashboard and create a new SQS destination.

You'll need to provide:

| Field | Type | Required | Example | Description |
| - | - | - | - | - |
| **Destination name** | string | Yes | `ampersandSQS` | Alias to reference in your `amp.yaml` file |
| **Queue URL** | string | Yes | `https://sqs.us-east-1.amazonaws.com/123456789012/my-queue` | URL of your SQS queue |
| **AWS Access Key ID** | string | Yes | `AKIAIOSFODNN7EXAMPLE` | AWS access key with `sqs:SendMessage` permission |
| **AWS Secret Access Key** | string | Yes | | AWS secret access key |

## Refer to the destination in your integration

After creating your SQS destination, reference it in your `amp.yaml` file:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceToSQS
    displayName: Salesforce to SQS
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: ampersandSQS
        - objectName: contact
          destination: ampersandSQS
```


# Webhook destinations
Source: https://docs.ampersand.ai/destinations/webhooks

Receive read and subscribe action results at your webhook endpoint, handle inline or URL payloads and size limits, and verify Svix signatures.

For more information on destinations, see the [Destinations](/destinations) page.

When new data is read from a SaaS instance via a [Read Action](/read-actions) or [Subscribe Action](/subscribe-actions), Ampersand sends a payload to your configured webhook.

## OpenAPI spec

Check out our [OpenAPI spec](https://github.com/amp-labs/openapi/blob/main/webhook/webhook.yaml) for the full webhook message schema and more details on the data structure. You can use this to generate types for your language and easily parse the webhook message.

## Read action webhooks

For read actions, Ampersand attaches results to a webhook message in two ways:

1. **Inline**: In most cases, the result is directly included in the webhook's `result` field. If a read action returns a large number of records, you might receive multiple webhooks in quick succession, each delivering a subset of the data. Read more about [message frequency](#handling-the-message-frequency) here.
2. **URL**: If a single record in the result set is over 300KB, it becomes too big to be sent over a webhook. In this case, the result won't be included inline. Instead, the webhook message will contain a signed download URL in `resultInfo.downloadUrl`. **The URL expires after 15 minutes.**

`resultInfo.type` indicates how the result is attached to the message:

If type is `inline`, the full result is in the `result` field.
If type is `url`, you can fetch the full result by making a GET request to `resultInfo.downloadUrl`.

In both cases, `resultInfo.numRecords` tells you how many records are available in the result.

### Example webhook message (inline)

Here's a sample webhook message for a Salesforce Contact object:

```JavaScript JavaScript theme={"dark"}
{
  "action": "read",
  "consumerRef": "user-123",
  "consumerName": "John Doe",
  "groupRef": "xyz-company",
  "groupName": "XYZ Company",
  "installationId": "installation-id",
  "installationUpdateTime": "2024-12-07T00:20:36Z",
  "objectName": "Contact",
  "operationId": "operation-uuid",
  "operationTime": "2024-12-07T00:20:40Z",
  "projectId": "ampersand-project-id",
  "provider": "salesforce",
    // If there is a mapping for this object, rawObjectName contains the original provider API name.
  "rawObjectName": "Contact",
    // readType indicates the type of read operation:
    // - "backfill":  Initial backfill.
    // - "scheduled": Regular scheduled read.
    // - "triggered": On-demand read triggered via API.
  "readType": "scheduled",
    // Only certain providers will have workspace available.
  "workspace": "salesforce-subdomain",
  "resultInfo": {
    "type": "inline",
    "numRecords": 2
  },
  "result": [
    {
      "fields": {
        "id": "001Dp00000P8QurIAF",
        "firstname": "Sally",
        "lastname": "Jones"
      },
      "mappedFields": {
        "pronoun": "she"
      },
      "raw": {
        "id": "001Dp00000P8QurIAF",
        "firstname": "Sally",
        "lastname": "Jones",
        "pronoun_custom_field": "she"
        // ... other fields for this record
      }
    },
    {
      "fields": {
        "id": "001Dp00000P9BusEIS",
        "firstname": "Taylor",
        "lastname": "Lao"
      },
      "mappedFields": {
        "pronoun": "they"
      },
      "raw": {
        "id": "001Dp00000P9BusEIS",
        "firstname": "Taylor",
        "lastname": "Lao",
        "pronoun_custom_field": "they"
        // ... other fields for this record
      }
    }
  ]
}
```

### Example webhook message (URL)

```JavaScript JavaScript theme={"dark"}
{
  "action": "read",
  "projectId": "ampersand-project-id",
  "provider": "salesforce",
  "groupRef": "xyz-company",
  "groupName": "XYZ Company",
  "consumerRef": "user-123",
  "consumerName": "John Doe",
  "installationId": "installation-id",
  "installationUpdateTime": "2024-12-07T00:20:36Z",
  "objectName": "Contact",
  "rawObjectName": "Contact",
  "workspace": "salesforce-subdomain",
  "operationId": "operation-uuid",
  "operationTime": "2024-12-07T00:20:40Z",
  "readType": "backfill",
  "resultInfo": {
    "type": "url",
    "downloadUrl": "https://storage.googleapis.com/....",
    "numRecords": 1
  }
}
```

## Subscribe action webhooks

Subscribe action webhooks look very similar to read action webhooks with a few additional fields in each result entry:

* **subscribeEventType**: this is the normalized event type string, which can be: `create`, `update`, `delete`, `associationUpdate` (for HubSpot only).
* **providerEventType**: this is the raw event type string from the API provider.
* **rawEvent**: when available, this is the raw webhook event from the API provider.

Here is a sample message:

```JavaScript JavaScript theme={"dark"}
{
    "action": "subscribe",
    "projectId": "948234676-4874-43a4-beea-fa8081d13a07",
    "provider": "salesforce",
    "groupRef": "webhook-demo-group-id",
    "groupName": "webhook-demo-group-name",
    "consumerRef": "user-123",
    "consumerName": "John Doe",
    "installationId": "0c9230e1c-8fbe-4b28-bf10-2beee8fbf4ce",
    "installationUpdateTime": "2025-04-10T23:00:52.618406Z",
    "objectName": "company",
    "rawObjectName": "account",
    "workspace": "my-salesforce-workspace",
    "result": [
        {
            "fields": {
                "annualrevenue": null,
                "id": "001Dp00000ZDgmxIAD",
                "website": null
            },
            "mappedFields": {
                "accountName": "johnAmp",
                "notes": "Notes about the account"
            },
            "subscribeEventType": "update",
            "providerEventType": "UPDATE",
            "raw": {
                "AnnualRevenue": null,
                "Description": "Notes about the account",
                "Id": "001Dp00000ZDgmxIAD",
                "Name": "johnAmp",
                "Website": null,
                "attributes": {
                    "type": "Account",
                    "url": "/services/data/v59.0/sobjects/Account/001Dp00000ZDgmxIAD"
                }
            },
            "rawEvent": {
                "ChangeEventHeader": {
                    "changeOrigin": "com/salesforce/api/soap/63.0;client=SfdcInternalAPI/",
                    "changeType": "UPDATE",
                    "changedFields": [
                        "Description",
                        "LastModifiedDate"
                    ],
                    "commitNumber": 12041091891110,
                    "commitTimestamp": 1744327345000,
                    "commitUser": "005Dp000003Cd1SIAS",
                    "entityName": "Account",
                    "recordId": "001Dp00000ZDgmxIAD",
                    "sequenceNumber": 1,
                    "transactionKey": "00051705-2e99-d1e5-7e7a-48e3af682d07"
                },
                "Description": "Notes about the account",
                "LastModifiedDate": "2025-04-10T23:22:25.000Z"
            }
        }
    ],
    "resultInfo": {
        "numRecords": 1,
        "type": "inline"
    }
}
```

## Handling webhook results

Here's some pseudo-code to illustrate how you can parse the result from a webhook:

```go go theme={"dark"}
// Generated from the OpenAPI spec
type WebhookMessage struct {
	Action string `json:"action"`
	GroupName string `json:"groupName"`
	GroupRef string `json:"groupRef"`
     ...
}

func handleWebhookEndpointMessage(message WebhookMessage) {
  // Assumes that you have already parsed the webhook message into the openapi.WebhookMessage type

  var results map[string]any

  switch message.ResultInfo.Type {
    case "url":
      // If result type is "url", download the data
      res, err := http.Get(message.ResultInfo.DownloadUrl)
      if err != nil {
        // handle error
      }

      results = parseBodyIntoMap(res.Body)
    case "inline":
      // If result type is "inline", data is directly in the message
      results = message.Result

    default:
      // This should not happen - contact us if it does!
  }

  fmt.Printf("Received %d records", message.ResultInfo.NumRecords)

  // Process results as needed
}
```

### Handling the payload size

The maximum size of a webhook payload Ampersand may send to your destination is **300 KB**. Most API gateways can handle this by default. If you implement your webhook using AWS Lambda or Google Cloud Run Functions, they will also be able to handle this payload size without any additional configuration.

If you are using the Node.js framework [Express](https://expressjs.com) in your webhook receiver, and are using the [json middleware](https://expressjs.com/en/api.html#express.json) to parse request bodies, you will need to modify it to increase the maximum request body size.

```js theme={"dark"}
  const app = express();

  app.use([
    express.json({
      limit: "350kb", // Set the max to 350 KB to allow for some buffer.
    }),
  ]);
```

### Handling the message frequency

By default, Ampersand will send you at most 1000 webhook messages per second across all your destinations. If you wish to change this limit, please contact `support@withampersand.com`. Alternatively, you can set the delivery mode to [on request](/read-actions#on-request-deprecated) to only get webhook messages when you request for them via an API call.

## Webhook signature verification

Every webhook message that Ampersand sends includes a cryptographic signature. This signature lets you confirm that the payload is both authentic and unchanged when it reaches your system.

Ampersand uses Svix to deliver webhooks to your destination, which is why the signature is sent in the `svix-signature` header. Each destination has its own unique secret, called the "webhook signing secret", which is used to generate the signature.

To verify a webhook, you will need to:

1. [Get the signing secret](#viewing-your-secret) for your destination from the Ampersand dashboard.
2. Use that secret with any of the Svix libraries to verify the `svix-signature` header and confirm the message is valid. You can find more information on how to do this [here](https://docs.svix.com/receiving/verifying-payloads/how).

#### Viewing your secret

To find a destination's webhook signing secret, navigate to the destination in the Ampersand dashboard and click on **"Click here to view the secret"**.

1. Log in to the [Ampersand dashboard](https://dashboard.withampersand.com) & navigate to **[Destinations](https://dashboard.withampersand.com/projects/_/destinations)**.
2. Click on the destination you want to view the secret for.
3. Click on **"Click here to view the secret"**.

<img alt="Alt text" />

#### Rotating your secret

If you need to rotate your signing secret for security reasons, you can do so from the Ampersand dashboard.

1. Navigate to the **[Destinations](https://dashboard.withampersand.com/projects/_/destinations)** section in the Ampersand dashboard & click on the destination you want to rotate the secret for.
2. Click on **"Click here to view the secret"**.
3. Click on **"Rotate secret"** to rotate the secret & confirm the rotation.


# Dev and prod environments
Source: https://docs.ampersand.ai/dev-and-prod-environments

Set up separate dev and prod projects, deploy one amp.yaml to each with the amp CLI, reuse destination names, and automate it with the Github Action.

You can create multiple projects per organization, so we recommend at least creating two projects:

* one for your production environment.
* one for your development environment, where you can test integrations before shipping them to customers.

You can deploy the same set of integrations to all of your projects by defining a single `amp.yaml` file. Then you can use the amp CLI to deploy it to all of your projects:

```bash theme={"dark"}
amp login

# First deploy to dev
amp deploy my-integrations-folder --project=my-dev-project

# Promote to prod when you are ready
amp deploy my-integrations-folder --project=my-prod-project
```

Please note that for each of your projects, you will need to:

* Add Provider Apps to the Ampersand Dashboard. See [Provider Guides](/provider-guides/overview) for more details. <b>Do not reuse the same Provider App across projects</b>, as this will lead to OAuth tokens in one project being invalidated when the same SaaS credential is used to generate tokens in another project.
* Generate API keys for embedding UI components or for making API calls.
* Add [Destinations](/destinations) to the Ampersand Dashboard if you have any read actions.

## Destination names

You should use the same names for the webhook destinations in each of your projects. For example, `my-dev-project` can have a `hubspotWebhook` which has the URL `https://www.my-dev-webhook.com`, and `my-prod-project` can have a `hubspotWebhook` which has the URL `https://www.my-prod-webhook.com`. Then in my `amp.yaml` file, my integration will be defined as follows:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations: 
  - name: readHubspotContacts
    provider: hubspot
    module: crm
    read:
      objects:
        - objectName: contact
          # In dev, webhook messages will go to `https://www.my-dev-webhook.com`,
          # In prod, they will go to `https://www.my-prod-webhook.com`.
          destination: hubspotWebhook
          ...
```

## Deploy to multiple environments with Github Action

With the [official Ampersand Github Action](https://github.com/marketplace/actions/official-ampersand-github-action), you can automate promotions between your different environments. Here is a [sample Github workflow](https://github.com/amp-labs/demo-hubspot-apollo/blob/main/.github/workflows/amp_deploy.yml) that deploys to a dev project on commits to a Pull Request, and deploys to a prod project once a Pull Request is merged to the main branch.


# Prebuilt UI components
Source: https://docs.ampersand.ai/embeddable-ui-components

Install @amp-labs/react, set up AmpersandProvider with an API key or JWT, embed the install integration and connect provider components, and style them.

## Project setup

### Prerequisites

* You need a React app to embed the components into. If you don't already have one, you can use the [Ampersand starter project](/starter-project).
* The Ampersand UI library requires **React v18+**.

### Install the Ampersand React library

In your repo, use `npm` or `yarn` to install the package:

```
npm install @amp-labs/react
```

or

```
yarn add @amp-labs/react
```

## AmpersandProvider

The `AmpersandProvider` is the foundational component that provides context for all Ampersand functionality, including both headless hooks and prebuilt UI components. It can be placed at any level in your component tree, but it must wrap all Ampersand components and hooks in your application.

The `AmpersandProvider` accepts an `options` object with the following required properties:

* `project`: Your Ampersand project name or ID (found on your [General Settings page](https://dashboard.withampersand.com/projects/_/settings))
* Authentication method: Either `apiKey` or `getToken` (but not both)

```tsx theme={"dark"}
import { AmpersandProvider } from '@amp-labs/react';
import '@amp-labs/react/styles';

const options = {
  project: 'PROJECT', // Your Ampersand project name or ID

  // Pick one of the following authentication methods:
  apiKey: 'API_KEY',  // Ampersand API key (simple)
  // OR 
  getToken: async ({consumerRef, groupRef}) => {  // JWT Authentication (advanced)
    // Custom logic to fetch JWT token from your backend, e.g.
    return await getTokenFromMyBackend(consumerRef, groupRef);
  },
};

function App() {
  return (
    <AmpersandProvider options={options}>
      {/* All your Ampersand components and hooks go here */}
    </AmpersandProvider>
  );
}
```

### Authentication Methods

The `AmpersandProvider` supports two authentication methods through the `options` parameter. Only one method can be used at a time.

#### API key authentication

When you are first developing integrations with Ampersand, API keys are a quick way to get started.

You can create an API key on the [API keys page](https://dashboard.withampersand.com/projects/_/api-keys) of your Ampersand Dashboard. Select "UI Library" for "Where will you use the API key?"

#### JWT authentication

When you are ready to ship your integrations to production, we highly recommend that you move to JWT authentication, as it is more secure than using API keys in the frontend. JWT tokens are time-bound and also enforce that your users only have access to their own integration data.

```tsx theme={"dark"}
const options = {
  project: 'PROJECT',
  getToken: async ({consumerRef, groupRef}) => {
    // Custom logic to fetch JWT token from your backend, e.g.
    return await getTokenFromMyBackend(consumerRef, groupRef);
  },
};
return (
  <AmpersandProvider options={options}>
    {/* All your Ampersand components and hooks go here */}
  </AmpersandProvider>
);
```

The `getToken` function should return a promise that resolves to a valid JWT token by making a call to your backend. For detailed information on how to generate JWT tokens, see [JWT Authentication](/api/jwt-auth).

## Components

### Install integration

The `InstallIntegration` component prompts your customer for their SaaS credentials, and then guides them through the installation flow for an integration. If they've already installed this integration, then the component will display the current configuration of the integration and allow them to update it.

Please note that each [group](/terminology#group) is able to install the integration once, so if someone else with the same `groupRef` has already installed the integration, then the user will not be able to install the same integration again.

The parameters of the component are:

* **integration** (string): the name of an integration that you've defined in `amp.yaml`.
* **consumerRef** (string): the ID that your app uses to identify this end user.
* **consumerName** (string, optional): the display name for this end user.
* **groupRef** (string): the ID that your app uses to identify a company, team, or workspace. See [group](/terminology#group).
* **groupName** (string, optional): the display name for this group.
* **onInstallSuccess** (function, optional): a callback function that gets invoked after a consumer successfully installs the integration. If the integration has [always-enabled objects](#always-enabled-objects), this fires right after the consumer connects.
* **onUpdateSuccess** (function, optional): a callback function that gets invoked after a consumer successfully updates an existing integration with the new configuration.
* **onUninstallSuccess** (function, optional): a callback function that gets invoked after a consumer successfully uninstalls the integration.
* **fieldMapping** (JSON): a JSON object that specifies the dynamic mapping configuration for this installation. Learn more about dynamic mapping [here](/object-and-field-mapping#dynamic-field-mappings)

Both `onInstallSuccess` and `onUpdateSuccess` should be functions with the following signature: `(installationId: string, config: Config) => void`. `Config` is an exported type from `@amp-labs/react`.

```JSX theme={"dark"}
 <InstallIntegration 
  integration = {myIntegrationName}
  consumerRef = {userId}
  consumerName = {userFullName}
  groupRef = {teamId}
  groupName = {teamName}
  onInstallSuccess = {(installationId, configObject) =>
    console.log(`Successfully installed ${installationId}`
      + `with configuration ${JSON.stringify(configObject, null, 2)}`)
  }
  onUpdateSuccess = {(installationId, configObject) =>
    console.log(`Successfully updated ${installationId}`
      + ` with configuration ${JSON.stringify(configObject, null, 2)}`)
  }
  onUninstallSuccess = {(installationId) =>
    console.log(`Successfully uninstalled ${installationId}`)
  }
  fieldMapping={{
    contacts: [
      {
        mapToName: 'priority',
        mapToDisplayName: 'Priority',
        prompt: 'Which field do you use to track the priority of a deal?',
      },
      ... // other field mapping options
    ],
  }}
/>
```

<Steps>
  <Step title="Your end user connects their SaaS instance.">
    <img alt="ConnectProvider initial screen" />
  </Step>

  <Step title="They configure the integration's objects, fields, and mappings.">
    <img alt="InstallIntegration configuration screen" />
  </Step>
</Steps>

#### Always-enabled objects

When your integration has [read objects marked `enabled: always`](/read-actions#always-enabled-objects), the component installs them for the consumer, since the consumer can't opt out of them:

* **As soon as the consumer connects**, the component creates the installation with those objects, and `onInstallSuccess` fires. Reads and backfills for them start right away, even if the consumer leaves before configuring anything else.
* **When the consumer opens an existing installation** that doesn't have one of those objects, the component adds it, and `onUpdateSuccess` fires.
* After that, the consumer only updates the installation. They can pick optional fields and mappings for these objects, but the component doesn't offer a way to stop reading them.
* If installing them fails (for example, the [sample read](/read-actions#install-time-validation) is rejected because the connected user can't access the object), the component shows the error with a **Retry** button, and the consumer can't continue until it succeeds.

<Note>
  If you close your install dialog in `onInstallSuccess`, it will close right after the consumer connects when the integration has always-enabled objects. Use `onUpdateSuccess`, or keep the dialog open until the consumer finishes, if you want them to configure the rest of the integration first.
</Note>

#### Wizard mode (Beta)

The wizard mode replaces the standard configuration view with a guided, multi-step installation flow during initial set up. It walks your end users through connecting, selecting objects, configuring fields/mappings, and reviewing before creating an installation.

<img alt="" />

<Warning>The wizard mode is currently in beta preview. The `variant="wizard"` prop is hidden and does not appear in the public TypeScript declarations as of `@amp-labs/react` v2.13.1. See the supported features table below for details on what is currently available.</Warning>

To activate wizard mode, pass `variant="wizard"` to the `InstallIntegration` component:

```JSX theme={"dark"}
<InstallIntegration
  integration={myIntegrationName}
  consumerRef={userId}
  consumerName={userFullName}
  groupRef={teamId}
  groupName={teamName}
  // @ts-expect-error -- needed since hidden as an internal prop
  variant="wizard"
/>
```

When no installation exists, the wizard renders. If an installation already exists, the standard configuration UI is shown instead.

With [always-enabled objects](#always-enabled-objects), the installation is created when the consumer connects, and the wizard continues from there: those objects are preselected on the object selection step and can't be deselected, and the review step saves the existing installation instead of creating a new one.

| Feature | Supported |
| - | - |
| [Read objects](/read-actions) | Yes |
| [Write objects](/write-actions) | Yes |
| [Required fields](/read-actions#required-fields-and-optional-fields) | Yes |
| [Optional fields](/read-actions#required-fields-and-optional-fields) | Yes |
| [Field mappings](/object-and-field-mapping#field-mapping) | Yes |
| [Object mappings](/object-and-field-mapping#object-mapping) | Yes |
| [Value mappings](/object-and-field-mapping#mapping-values) | No |
| [Field mapping `default`](/object-and-field-mapping#field-mapping-1) | No |
| [Dynamic field mappings](/object-and-field-mapping#dynamic-field-mappings) (`fieldMapping` prop) | No |

### Connect provider

The ConnectProvider component allows your customer to put in their SaaS credential, but does not lead them through the installation flow. After their SaaS credential is persisted by Ampersand, you can then make an API request to the [CreateInstallation](/reference/installation/create-a-new-installation) endpoint.

The parameters of the component are:

* **provider** (string): the name of the SaaS provider, such as "salesforce".
* **consumerRef** (string): the ID that your app uses to identify this end user.
* **consumerName** (string, optional): the display name for this end user.
* **groupRef** (string): the ID that your app uses to identify a company, team, or workspace. See [group](/terminology#group).
* **groupName** (string, optional): the display name for this group.
* **module** (string, optional): the module to use for this connection. Determines which module-specific metadata to collect from providers that have modules defined. Falls back to the provider's default module if not specified, and is ignored if the provider does not have modules. If a connection already exists but is missing metadata required by the specified module, a prefilled metadata form will be shown automatically. Supported in `@amp-labs/react` `v2.12.1+`.
* **redirectUrl** (string, optional): if provided, the page will be redirected to this URL once a consumer successfully connects. This can either be an absolute or relative URL.
* **onConnectSuccess** (function, optional): a callback function that gets invoked after a consumer successfully connects.
* **onDisconnectSuccess** (function, optional): a callback function that gets invoked after a consumer successfully disconnects.

Both `onConnectSuccess` and `onDisconnectSuccess` should be functions with the following signature: `(connection: Connection) => void`. `Connection` is an exported type from `@amp-labs/react`.

```TypeScript theme={"dark"}
 <ConnectProvider
  provider = "salesforce"
  consumerRef = {userId}
  consumerName = {userFullName}
  groupRef = {teamId}
  groupName = {teamName}
  module = "account-engagement"
  redirectUrl = "/connection-success"
  onConnectSuccess = {connection =>
    console.log(`Successfully created connection ${connection.id}`)
  }
  onDisconnectSuccess = {connection =>
    console.log(`Successfully deleted connection ${connection.id}`)
  }
/>
```

<table>
  <thead>
    <tr><th>Connect</th><th>Success</th></tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <img alt="ConnectProvider initial state" />
      </td>

      <td>
        <img alt="ConnectProvider connected state" />
      </td>
    </tr>
  </tbody>
</table>

*The component prompts for credentials (left), then displays the connected state with an option to reauthenticate or refresh (right).*

## Hooks

### Check if integration is installed

We provide a hook `useIsIntegrationInstalled` to check if an integration has been installed yet for this [group](/terminology#group). It takes the following parameters:

* **integration** (string): the name of an integration that you've defined in `amp.yaml`.
* **groupRef** (string): the ID that your app uses to identify a company, team, or workspace. See [group](/terminology#group).
* **consumerRef** (string, optional): the ID that your app uses to identify this end user. If you are using [JWT authentication](/embeddable-ui-components#jwt-authentication), you must provide this parameter, or ensure that this hook is called inside [InstallationProvider](/headless#context-setup). This parameter is supported in `@amp-labs/react` `v2.10.1+`.

It returns an object with the following fields:

* **isLoaded** (boolean): indicates whether the API call has resolved.
* **isIntegrationInstalled** (boolean): indicates whether the integration has already been installed by somebody in the group.
* **isError** (boolean): indicates whether an error occurred while fetching the integration or installation data.
* **error** (Error | null): contains the error object if an error occurred, otherwise null.
* **config** (Config): the configuration object for the installation (see below for usage examples).

```TypeScript theme={"dark"}
const {
  isLoaded,
  isIntegrationInstalled,
  isError,
  error
} = useIsIntegrationInstalled("read-salesforce", groupRef);

// Handle errors
if (isError) {
  console.error("Failed to check integration status:", error);
}
```

#### Using with JWT authentication

If you are using [JWT authentication](/embeddable-ui-components#jwt-authentication), you must provide the `consumerRef` parameter, or ensure that this hook is called inside [InstallationProvider](/headless#context-setup).

```TypeScript theme={"dark"}
const {
  isLoaded,
  isIntegrationInstalled,
} = useIsIntegrationInstalled("read-salesforce", groupRef, consumerRef);
```

### Check if specific objects are installed

Currently, the [InstallIntegration](/embeddable-ui-components#install-integration) component will create an `Installation` as soon as the user saves a single object. This means that when
`useIsIntegrationInstalled` returns true for `isIntegrationInstalled`, not all objects would have been configured and saved yet.
If you need to know when all objects or specific objects are installed, inspect the [Config](/reference/installation/update-an-installation#body-installation-config-content) object.

```TypeScript theme={"dark"}
const {
  isLoaded,
  isIntegrationInstalled, 
  config,
} = useIsIntegrationInstalled("read-salesforce", groupRef);

// All 3 read objects are installed
if (isLoaded && isIntegrationInstalled && config.read.objects.length === 3) {
  // Do something 
}

// check if the Account object is installed
if (isLoaded && isIntegrationInstalled && config.read.objects.filter(o => o.objectName === "Account").length === 1) {
  // Do something 
}

// All 3 write objects are installed
if (isLoaded && isIntegrationInstalled && config.write.objects === 3) {
  // Do something 
}
```

## Customize styles

<Warning>Customized styling is only supported in v2.x.x </Warning>

To customize the look and feel of Ampersand components, import your own CSS file directly after `@amp-labs/react/styles`.

You can override CSS variables that are exposed in the [variables.css file](https://github.com/amp-labs/react/blob/main/src/styles/variables.css). By convention, CSS variables that are used in the Ampersand components are named with `--amp` as a prefix.

```TypeScript theme={"dark"}
import { AmpersandProvider } from '@amp-labs/react';
import '@amp-labs/react/styles';
import './App.css'; // Optional: your own css override
```

### Example App.css

```css App.css theme={"dark"}
:root {
    /* These affect the look and feel of buttons */
    --amp-colors-primary: #4360e0;
    --amp-default-border-radius: 8px;

    /* Override with your own color palette */
    --amp-colors-neutral-25: #FEFEFE;
    --amp-colors-neutral-50: #FDFCFD;
    --amp-colors-neutral-100: #FAFAFC;
    --amp-colors-neutral-200: #F6F5F9;
    --amp-colors-neutral-300: #F1EFF5;
    --amp-colors-neutral-400: #EDEAF2;
    --amp-colors-neutral-500: #E8E5EF;
    --amp-colors-neutral-600: #918E95;
    --amp-colors-neutral-700: #646266;
    --amp-colors-neutral-800: #363638;
    --amp-colors-neutral-900: #1D1D1D;
}
```

## Dark mode

<Warning>Dark mode is only supported in v2.1.0+ </Warning>

Ampersand's UI components support dark mode. Ensure that you have the following lines in your application's CSS:

```CSS theme={"dark"}
:root {
  color-scheme: light dark;
}
```

When a user sets their system settings to dark mode, then Ampersand's UI components will automatically render in dark mode. We do this by making use of the [light-dark CSS function](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark) in our default colors. You can customize the colors by adding an override CSS file. See [Customize styles](#customize-styles).

## Migrating to v2

`@amp-labs/react` v2.x.x no longer requires Chakra as a dependency, and also provides users with the ability to [customize styles](#customize-styles). When upgrading from v1.x.x to v2.x.x, you must add an additional line after importing the library:

```TypeScript theme={"dark"}
import { AmpersandProvider, InstallIntegration } from '@amp-labs/react';
import '@amp-labs/react/styles'; // Add this line when migrating to v2
import './App.css'; // Optional: your own CSS override 
```

## Troubleshooting

### Why did installing or updating fail with a field error?

When a customer creates or updates an installation, Ampersand runs a [sample read](/read-actions#install-time-validation) against the provider before saving. If a selected field isn't visible to the connected user, or a field name doesn't exist on the object, the install is rejected and the component shows the provider's error message. Your customer can fix it in the flow — for example, by granting field access — instead of hitting a broken sync later.

This runs automatically on `@amp-labs/react` **2.13.5 and later**. Older versions show only a generic error, so upgrade for the detailed messages. See [Install-time validation](/read-actions#install-time-validation) for the full behavior.

### Why does styling look so bare?

You likely forgot to import the stylesheet, please add this line once in your application.

```
import '@amp-labs/react/styles';
```


# Headless UI library
Source: https://docs.ampersand.ai/headless

Use Headless UI library hooks from @amp-labs/react to manage connections, installations, field metadata, and local read and write config in a custom UI.

The Headless UI library is part of `@amp-labs/react` and provides a powerful foundation for managing connections and installations while giving you complete control over your UI implementation. This library is designed for developers who want to build custom user interfaces while leveraging robust connection, integration, and installation management capabilities.

<Note>
  The Headless UI library is in beta. It may change in non-backwards-compatible ways. (Although we are very serious about semantic versioning.)

  If you have any feedback, please file an issue [on Github](https://github.com/amp-labs/react/issues).
</Note>

## Overview

The Headless UI Library provides a series of React hooks that manage connections, installations, and other configuration data using query and mutation hooks. The hooks may be used together or independently of the [prebuilt UI components](/embeddable-ui-components).

The Headless UI Library separates the logic of connection and installation management from the UI components, allowing you to:

* Manage connections to various services and platforms.
* Handle installation processes.
* Implement custom UI components.
* Maintain full control over the user experience.

## Prerequisites

### Install the library

The Headless UI Library is currently in the same package as our [prebuilt UI components](/embeddable-ui-components).

```bash theme={"dark"}
npm install @amp-labs/react
# or
yarn add @amp-labs/react
```

### Context setup

In order for the headless hooks and functions to have relevant context, you can only use them inside `AmpersandProvider` and `InstallationProvider`.

The `AmpersandProvider` needs to wrap all usages of headless hooks and functions as well as prebuilt UI components. See [AmpersandProvider](/embeddable-ui-components#ampersandprovider) for more details on configuration and authentication methods.

The `InstallationProvider` needs to wrap any code that interacts with a particular installation. This means that if your UI needs to handle multiple installations (e.g., one for Asana and one for Zendesk), then you need two instances of `InstallationProvider`: one that wraps the code for Asana setup, and one that wraps the code for Zendesk setup.

`InstallationProvider` requires the following props:

* **integration** (string): the name of an integration that you've defined in `amp.yaml`.
* **consumerRef** (string): the ID that your app uses to identify this end user.
* **consumerName** (string, optional): the display name for this end user.
* **groupRef** (string): the ID that your app uses to identify a company, team, or workspace. See [group](/terminology#group).
* **groupName** (string, optional): the display name for this group.

```tsx theme={"dark"}
import {
  AmpersandProvider,     // Needed for all hooks and components in @amp-labs/react.
  InstallationProvider,  // Needed for headless hooks and functions.
} from "@amp-labs/react"

const options = {
  project: 'PROJECT', // Your Ampersand project name or ID

  // Pick one of the following authentication methods.
  apiKey: 'API_KEY',  // Ampersand API key (simple)
  // OR 
  getToken: async ({consumerRef, groupRef}) => {  // JWT Authentication (advanced)
    // Custom logic to fetch JWT token from your backend, e.g.
    return await getTokenFromMyBackend(consumerRef, groupRef);
    // See https://docs.ampersand.ai/api/jwt-auth
  },
};

// Define variables that will be used for this code snippet and
// other code snippets on this page.
const integration = "my-salesforce-integration"; // Must match name in `amp.yaml`.
const provider = "salesforce";
const groupRef = "group-test-1";
const groupName = "Test Group";
const consumerRef = "consumer-test-1";
const consumerName = "Test Consumer";

function App() {
  return (
    <AmpersandProvider options={options}>
      <InstallationProvider
        integration={integration}
        groupRef={groupRef}
        groupName={groupName}
        consumerRef={consumerRef}
        consumerName={consumerName}
      >
        {/* Your custom component */}
        <MyComponent />
      </InstallationProvider>
    </AmpersandProvider>
  );
}
```

## Connection management

The library provides hooks and utilities for managing [Connections](/terminology#connection).

The `useConnection` hook provides access to the current connection state and management functions. It returns an object with the following properties:

* `connection`: The current Connection object, or null if there isn't one.
* `error`: Any error that occurred while fetching the Connection.
* `isPending`: If true, there is no data yet.
* `isFetching`: If true, the data is being fetched (including refetches).
* `isError`: If true, an error occurred while fetching the connection.
* `isSuccess`: If true, the last fetch was successful.

```tsx theme={"dark"}
import { useConnection, ConnectProvider } from '@amp-labs/react';

function MyComponent() {
  const {
    connection, // Connection object
    error,
    isPending,
    isFetching,
    isError,
    isSuccess,
  } = useConnection();

  // Use these values to build your custom UI
  return (
    <div>
      {connection ? (
        {/* If there isn't a Connection, show prebuilt ConnectProvider component. */}
        <ConnectProvider
          provider={provider}
          consumerRef={consumerRef}
          groupRef={groupRef}
          onConnectSuccess={(connection) => {
            console.log("Connection successful:", connection);
          }}
          onDisconnectSuccess={(connection) => {
            console.log("Disconnection successful:", connection);
          }}
        />
      ) : (
        {/* If user is already connected, guide them through the rest of the configuration. */}
        <MyConfigurationComponent/>
      )}
    </div>
  );
}
```

## Installation management

### Get current installation

The `useInstallation` hook provides access to the current installation state and management functions. It returns an object with the following properties:

* `installation`: The current [Installation](/terminology#installation) object, or null if not installed.
* `error`: Any error that occurred while fetching the Installation.
* `isPending`: If true, there is no data yet.
* `isFetching`: If true, the data is being fetched (including refetches).
* `isError`: If true, an error occurred while fetching the connection.
* `isSuccess`: If true, the last fetch was successful.

```tsx theme={"dark"}
import { useInstallation } from '@amp-labs/react';

function InstallationComponent() {
  const { installation } = useInstallation();

  return (
    <div>
      {installation ? (
        <div>You've successfully installed the integration!</div>
      ) : (
        <MyInstallationComponent/>
      )}
    </div>
  );
}
```

### Get config from existing installation

To access the configuration from an existing installation, you can use the `installation.config` property. See [API reference](/reference/installation/get-an-installation#response-config) for more details:

```tsx theme={"dark"}
import { useInstallation } from '@amp-labs/react';

function ConfigDisplayComponent() {
  const { installation } = useInstallation();

  if (!installation) {
    return <div>No installation found</div>;
  }

  // Access the configuration from the installation
  const config = installation.config;

  // Use the config to build your custom UI
}
```

<Note>
  For more advanced config management: including getting/setting read/write objects in the config and managing a local draft copy, use the [`useLocalConfig()`](#local-config-management) hook.
</Note>

### Create, update, and delete installations

The following hooks provide granular control over [Installation](/concepts#installation) operations:

* `useCreateInstallation`
* `useUpdateInstallation`
* `useDeleteInstallation`

For example, the `useCreateInstallation` hook is used to create a new Installation.

<Note>
  As of `v2.12.1`, `useCreateInstallation` automatically populates `config.provider` from the integration object if it is not explicitly set in the config. This means you no longer need to manually set the provider.
</Note>

It returns the following:

* `createInstallation`: a tanstack-query mutation function to create a new Installation. Its signature is:

```typescript theme={"dark"}
(params: {
  config: InstallationConfigContent;
  onSuccess?: (data: Installation) => void;
  onError?: (error: Error) => void;
  onSettled?: () => void;
}) => void;
```

* `isPending`: Boolean indicating if creation is in progress.
* `error`: Any error that occurred during creation.
* `errorMsg`: String message describing the error.
* `isIdle`: If true, `createInstallation` has not been called yet.
* `isSuccess`: If true, installation was successfully created.

`useUpdateInstallation` and `useDeleteInstallation` follow similar conventions.

Here's an example of how you can use these hooks:

```tsx theme={"dark"}
import { useCreateInstallation } from '@amp-labs/react';

function InstallationForm() {
  const {
    createInstallation,
    isPending,
    error,
    errorMsg,
  } = useCreateInstallation();

  const handleSubmit = async (e) => {
    e.preventDefault();
    createInstallation({
      // Add your installation config here
      config: {
        read: {
          objects: {
            companies: {
              objectName: 'companies',
              selectedFieldsAuto: 'all', // Read all fields
            },
          },
        },
      },
      onSuccess: (data) => {
        console.log("Installation created", { installation: data });
      },
      onError: (error) => {
        console.error("Installation creation failed", { error });
      },
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <button
        type="submit"
        disabled={isPending}
      >
        {isPending ? 'Creating...' : 'Create Installation'}
      </button>
      {error && <div className="error">{errorMsg}</div>}
    </form>
  );
}
```

## Get manifest and field metadata

The `useManifest` hook provides the data that you need to build input forms for your users to help them configure the integration. This hook allows you to:

* Access integrations as defined in the [manifest](/terminology#manifest) (`amp.yaml`).
* Retrieve object and field metadata from the connected provider (e.g., Salesforce, Hubspot). This allows your application to know about the exact objects and fields that exist in your customer's SaaS instance, including custom objects and fields. With this information, you can build dropdowns, checkboxes, etc.

<Note>
  `useManifest` always returns the integration's latest published [revision](/terminology#revision) of `amp.yaml` — it is not tied to any specific installation. If an installation was created against an older revision, `useManifest` will still reflect the current `amp.yaml` and may differ from the installation's saved config. See [`useManifest` vs `useLocalConfig`](#usemanifest-vs-uselocalconfig).
</Note>

> `useManifest` exposes typed helpers for read and write objects (`getReadObject`, `getReadObjects`, `getWriteObject`).

```TypeScript theme={"dark"}
import { useManifest } from "@amp-labs/react";

const {
  getReadObjects: () => HydratedIntegrationObject[],  // Get all read objects from manifest (v2.12.1+)
  getReadObject: (objectName: string) => {
    object: HydratedIntegrationObject | null;
    getRequiredFields: () => HydratedIntegrationField[] | null;
    getOptionalFields: () => HydratedIntegrationField[] | null;
    isAlwaysEnabled: () => boolean;  // Object is marked `enabled: always` in amp.yaml (v2.18.0+)
  },
  getCustomerFieldsForObject: (objectName: string) => {
    // Map of field names to field metadata.
    allFields: { [field: string]: FieldMetadata } | null;
    // Get a specific field's metadata.
    getField: (field: string) => FieldMetadata | null;
  },
  data: HydratedRevision | undefined,
  isPending: boolean,
  isFetching: boolean,
  isError: boolean,
  isSuccess: boolean,
  error: Error | null,
} = useManifest();
```

### Get fields from customer's SaaS

The `getCustomerFieldsForObject` function returned by `useManifest` allows you to retrieve the standard and custom fields that exist in your customer's SaaS instance for a particular object.

```tsx theme={"dark"}
  const { getCustomerFieldsForObject } = useManifest();

  // Get all the fields that exist on the customer's Account object,
  // including standard and custom fields.
  const fields = getCustomerFieldsForObject("account");

  // This is a map of field names to field metadata,
  const allFields = fields?.allFields;

  // Convert to array if you want to show all of them in a list.
  const allFieldsArray = allFields ? Object.values(allFields) : [];
```

[The fields mapping page of the demo app](https://github.com/amp-labs/demo-headless/blob/main/src/components/FieldMappingTable/FieldMappingTable.tsx) provides a full example for using `useManifest` to build the UI for customers to configure the installation.

### Get all read objects from manifest

The `getReadObjects` function returned by `useManifest` returns all read objects defined in the manifest, which is useful when you need to iterate over all objects rather than fetching them individually by name. Supported in `@amp-labs/react` `v2.12.1+`.

```tsx theme={"dark"}
const { getReadObjects } = useManifest();

const allReadObjects = getReadObjects(); // HydratedIntegrationObject[]

allReadObjects.forEach((obj) => {
  console.log(obj.objectName);
});
```

## Local config management

Managing the [Config](/terminology#config) that keeps track of each customer's preference for how the integration behaves can be complex, with deeply nested objects and the need to manage this state locally.

The `useLocalConfig` hook simplifies local state management of the config object by providing flexible utilities to manipulate the config through a set of setters and getters. It maintains a draft state, which you can modify before committing changes to the installation.

<Note>
  **Deprecated:** `useConfig` has been deprecated in v2.9.0. It has been renamed to `useLocalConfig()` without any other changes.

  For fetching an existing config from an installation, use [`useInstallation`](#get-current-installation) which provides access to the current installation's configuration.
</Note>

<Note>
  **Prefer the helper functions** (`readObject`, `writeObject`, `proxy`, `setDraft`, `removeObject`, `reset`, `get`) over accessing `draft` directly. The helpers encapsulate how the draft is initialized, synced with the installation, and merged with manifest defaults. For authoritative installation state, use [`useInstallation`](#get-current-installation). For the integration's latest manifest (from your `amp.yaml` file), use [`useManifest`](#get-manifest-and-field-metadata). See [`useManifest` vs `useLocalConfig`](#usemanifest-vs-uselocalconfig).
</Note>

It returns these fields:

```typescript theme={"dark"}
// Return values of `useLocalConfig` hook.
{
  draft: InstallationConfigContent;  // Current draft configuration
  get: () => InstallationConfigContent;  // Get current configuration
  reset: () => void;  // Reset to installation's current config
  setDraft: (config: InstallationConfigContent) => void;  // Update draft config
  removeObject: (objectName: string) => void;  // Remove object from all actions (v2.12.1+)
  readObject: (objectName: string) => ReadObjectHandlers;  // Manage read object config
  writeObject: (objectName: string) => WriteObjectHandlers;  // Manage write object config
}

// Shape of ReadObjectHandlers (returned by `readObject` function above).
{
  object: BaseReadConfigObject | undefined;  // Current read object configuration
  setEnableRead: () => void;  // Enable reading for object, initializes with defaults (v2.12.1+)
  setDisableRead: () => void;  // Disable reading for object (v2.12.1+)
  getSelectedField: (fieldName: string) => boolean;  // Check if field is selected
  setSelectedField: (params: { fieldName: string; selected: boolean }) => void;  // Toggle field selection
  getFieldMapping: (fieldName: string) => string | undefined;  // Get field mapping
  setFieldMapping: (params: { fieldName: string; mapToName: string }) => void;  // Set field mapping
  deleteFieldMapping: (mapToName: string) => void;  // Delete field mapping
}

// Shape of WriteObjectHandlers (returned by `writeObject` function above).
{
  object: BaseWriteConfigObject | undefined;  // Current write object configuration
  setEnableWrite: () => void;  // Enable write for object
  setDisableWrite: () => void;  // Disable write for object
  setEnableDeletion: () => void;  // Enable deletion for object
  setDisableDeletion: () => void;  // Disable deletion for object
  getWriteObject: () => BaseWriteConfigObject | undefined;  // Get write object config
   // advanced write features
  // https://docs.ampersand.ai/write-actions#advanced-use-cases
  getDefaultValues: (fieldName: string) => FieldSettingDefault | undefined;
  setDefaultValues: (params: {
    fieldName: string;
    value: FieldSettingDefault;
  }) => void;
  getWriteOnCreateSetting: (
    fieldName: string,
  ) => FieldSettingWriteOnCreateEnum | undefined;
  setWriteOnCreateSetting: (params: {
    fieldName: string;
    value: FieldSettingWriteOnCreateEnum;
  }) => void;
  getWriteOnUpdateSetting: (
    fieldName: string,
  ) => FieldSettingWriteOnUpdateEnum | undefined;
  setWriteOnUpdateSetting: (params: {
    fieldName: string;
    value: FieldSettingWriteOnUpdateEnum;
  }) => void;
  getSelectedFieldSettings: (fieldName: string) => FieldSetting | undefined;
  setSelectedFieldSettings: (params: {
    fieldName: string;
    settings: FieldSetting;
  }) => void;
}
```

### Basic example

This is a basic example that hard-codes a Config and does not allow the user to modify it.

```typescript theme={"dark"}
function ConfigManager() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();
  
  config.setDraft({
    provider: "salesforce",
    read: {
      objects: {
        contact: {
          objectName: "contact",
          selectedFields: {
            "name": true,
            "email": true
          },
          selectedFieldsMappings: {
            // Mapping from billingaddress (in SaaS API) to address (in your application).
            "address": "billingaddress"
          }
        }
      }
    }
  });

  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };

  return (<button onClick={handleSave}>Create installation</button>)
}
```

### Manage read config

This is an example for how to use helper functions to more easily construct a read config, so you do not have to create the full config object manually.

```typescript theme={"dark"}
function ReadObjectConfig() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();
  const contactConfig = config.readObject("contact");
  
  // Check if field is already selected in local config
  const isNameSelected = contactConfig.getSelectedField("name");
  
  // Select a field
  contactConfig.setSelectedField({ fieldName: "email", selected: true });
  
  // Get existing mapping for a field in local config
  const mappedField = contactConfig.getFieldMapping("email_address");

  // Set field mapping
  contactConfig.setFieldMapping({ 
    fieldName: "email", // raw field from provider API
    mapToName: "email_address" // mapped field
  });
  
  // Create an installation with the current config
  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };
}
```

### Enable, disable, and remove read objects

The `readObject()` handlers include `setEnableRead` and `setDisableRead` to control whether an object is read. `removeObject` fully deletes an object from the config. Supported in `@amp-labs/react` `v2.12.1+`.

* **`setEnableRead`** — initializes a read object in the draft config and enables it. Safe to call multiple times (idempotent). For convenience, you can skip calling this function if you are already calling `setFieldMapping` or `setSelectedField`.
* **`setDisableRead`** — pauses reads for the object without removing its config (sets a `disabled` flag).
* **`removeObject`** — fully deletes an object from all actions (both read and write) in the draft config.

<Note>
  Objects marked [`enabled: always`](/read-actions#always-enabled-objects) in your `amp.yaml` are read for every installation, so they can't be turned off. Starting in `v2.18.0`, `setDisableRead` does nothing for them (and logs a warning), and `removeObject` removes only their write config. Use `useManifest().getReadObject(objectName).isAlwaysEnabled()` to find these objects, for example to show them as selected and locked in your UI.

  Unlike the [`InstallIntegration` component](/embeddable-ui-components#always-enabled-objects), the headless hooks don't install these objects on their own: the installation is created when your code calls `createInstallation`, and Ampersand adds any always-enabled objects your config leaves out.
</Note>

<Note>
  Calling `setSelectedField` or `setFieldMapping` will also automatically enable the read object, so `setEnableRead` is primarily useful when you want to enable an object without configuring fields, or to re-enable an object that was previously disabled.
</Note>

```typescript theme={"dark"}
function ObjectManager() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();

  // Enable reading for the "contact" and "account" objects
  config.readObject("contact").setEnableRead();
  config.readObject("account").setEnableRead();

  // Pause reads for "account" (keeps its config intact)
  config.readObject("account").setDisableRead();

  // Or fully remove "account" from both read and write config
  config.removeObject("account");

  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };

  return (<button onClick={handleSave}>Create installation</button>)
}
```

### Manage write config

The headless UI library provides helper functions to more easily construct a write config. Here's a simple example that enables a particular object to be written to:

```typescript theme={"dark"}
function WriteObjectConfig() {
  const { createInstallation } = useCreateInstallation();
  const config = useLocalConfig();
  const contactWriteConfig = config.writeObject("contact");
  
  // Enable write for Contact object
  contactWriteConfig.setEnableWrite();

  // Create an installation with the current config
  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };
}
```

You can also configure [advanced write use cases](/write-actions#advanced-use-cases), which include the ability to:

* Set default values for certain fields.
* Prevent overwriting of existing customer data.

#### Configure features individually

You can configure write settings for individual features using these methods:

```typescript theme={"dark"}
function WriteObjectConfig() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();
  const contactWriteConfig = config.writeObject("contact");
  
  // Set default value for a field
  contactWriteConfig.setDefaultValues({
    fieldName: "source",
    value: {
      stringValue: "myApp"  // String default
    }
  });
  
  contactWriteConfig.setDefaultValues({
    fieldName: "amount",
    value: {
      integerValue: 0  // Number default
    }
  });
  
  contactWriteConfig.setDefaultValues({
    fieldName: "automated",
    value: {
      booleanValue: true  // Boolean default
    }
  });
  
  // Configure which fields should be written to during create operations
  contactWriteConfig.setWriteOnCreateSetting({
    fieldName: "source",
    value: "always"  // Always write source field on create
  });
  
  contactWriteConfig.setWriteOnCreateSetting({
    fieldName: "notes",
    value: "never"  // Never write notes field on create
  });
  
  // Configure which fields should be written to during update operations
  contactWriteConfig.setWriteOnUpdateSetting({
    fieldName: "source",
    value: "never"  // Never write source field on update
  });
  
  contactWriteConfig.setWriteOnUpdateSetting({
    fieldName: "notes",
    value: "always"  // Always write notes field on update
  });
  
  // Get current local settings
  const defaultValues = contactWriteConfig.getDefaultValues("source");
  const writeOnCreate = contactWriteConfig.getWriteOnCreateSetting("source");
  const writeOnUpdate = contactWriteConfig.getWriteOnUpdateSetting("source");

  // Create an installation with the current config
  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };
}
```

#### Configure features together

You can use `setFieldSettings` to set all advanced write features at once for a field:

```typescript theme={"dark"}
function WriteObjectConfig() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();
  const contactWriteConfig = config.writeObject("contact");
  
  // Configure a field with both write behavior and default value
  contactWriteConfig.setFieldSettings({
    fieldName: "customSource",
    settings: {
      writeOnCreate: "always",  // Write on create
      writeOnUpdate: "never",   // Don't write on update
      default: {
        stringValue: "myApp"    // Default value
      }
    }
  });

  // Get current settings
  const current = contactWriteConfig.getFieldSettings("customSource");

  // Create an installation with the current config
  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };
}
```

## `useManifest` vs `useLocalConfig`

| | `useManifest()` | `useLocalConfig()` |
| - | - | - |
| **Represents** | The integration's [`amp.yaml`](/manifest-reference) manifest | The in-progress draft of this [installation's](/terminology#installation) config |
| **Revision source** | The integration's latest published [revision](/terminology#revision) | Whatever revision the installation was saved against |
| **Scope** | Everything the integration *could* support | Only what this installation *selected*, plus local edits |
| **Mutable?** | No — read-only query result | Yes — via helper functions |
| **Tied to an installation?** | No | Yes |

### Use the right hook for the job

* **"What does this integration currently support?"** → `useManifest()`. Use this when building configuration UI — pickers, field checkboxes, mapping dropdowns — that should follow the current `amp.yaml`.
* **"What did this installation actually deploy?"** → `useInstallation().installation.config.content`. This is the authoritative saved state. See the [installation response schema](/reference/installation/get-an-installation) for its shape. Do not use `useLocalConfig` for this — the draft is mutable and may include unsaved edits.
* **"Let the user edit the installation's config."** → `useLocalConfig()`, via its helper functions. See below.

### Read and write through helper functions, not `draft`

Interact with `useLocalConfig` through its helpers rather than reading or mutating `draft` directly:

```typescript theme={"dark"}
const config = useLocalConfig();

// Per-object read handlers encapsulate initialization, default-seeding, and selection.
const contact = config.readObject("contact");
const isEmailSelected = contact.getSelectedField("email");
contact.setSelectedField({ fieldName: "email", selected: true });
contact.setFieldMapping({ fieldName: "email", mapToName: "email_address" });

// Per-object write handlers do the same for write config.
const contactWrite = config.writeObject("contact");
contactWrite.setEnableWrite();

// Snapshot for save. Revert to the installation's saved state.
const configToSave = config.get();
config.reset();
```

## Examples

### Demo app

[View the source code on GitHub](https://github.com/amp-labs/demo-headless)

<img alt="Dynamic Fields Table Example" />

The [headless demo app](https://github.com/amp-labs/demo-headless) uses a Salesforce integration, and includes:

* Ability to map fields; the dropdown is populated with standard and optional fields from the connected Salesforce instance.
* Ability to create and update an Installation with the "Install" button.
* Ability to reset Config to previous state with the "Reset" button.
* Ability to delete an Installation with the "Delete" button.
* Usage of Shadcn UI components + Tailwind CSS to demonstrate how you can bring your own design system.

It uses the following headless hooks:

* [useConnection](#connection-management): manage when to show [ConnectProvider](/embeddable-ui-components#connect-provider)
* [useManifest](#get-manifest-and-field-metadata): manage objects and metadata
* [useConfig](#local-config-management): manage installation configuration state
* [useCreateInstallation, useUpdateInstallation, and useDeleteInstallation](#installation-management): manage installation lifecycle

### Demo app with write config

[View the source code on GitHub](https://github.com/amp-labs/demo-headless-write)

<img alt="Write Features Table Example" />

The [headless write demo app](https://github.com/amp-labs/demo-headless-write) uses a Salesforce integration, and extends the [basic demo app](https://github.com/amp-labs/demo-headless) with:

* Ability to set default values for fields when writing.
* Ability to prevent overwriting of customer data.

### Pre-defined configuration flow

If you do not want your users to be able to modify or configure the installation, you can build a pre-defined configuration flow using the code snippet below. This is helpful if you do not want your user to be able to modify which objects and fields your integration reads and writes, and you do not need them to do any field mappings.

```tsx theme={"dark"}
import {
  AmpersandProvider, ConnectProvider, useConnection, useInstallation,
} from '@amp-labs/react';

import { ConfigContent, AmpersandProviderOptions } from '@amp-labs/react/types';

const projectOptions: AmpersandProviderOptions ={
  apiKey: 'my-api-key',
  project: 'my-project',
}

const installationParams = {
  integration: 'my-hubspot-integration',
  consumerRef: 'user-123',
  groupRef: 'company-456',
};

export function App() {
  // Wrap your custom component inside of AmpersandProvider and InstallationProvider
  return (
    <AmpersandProvider options={projectOptions}>
      <InstallationProvider
        integration={installationParams.integration}
        consumerRef={installationParams.consumerRef}
        groupRef={installationParams.groupRef}
      >
        <MyIntegrationComponent />
      </InstallationProvider>
    </AmpersandProvider>
  );
}

// Static content for the installation, no user input needed
const myConfig: ConfigContent = {
  read: {
    objects: {
      companies: {
        objectName: 'companies',
        // Auto-select all fields to be read,
        // alternatively you can specify any desired fields & mappings here.
        selectedFieldsAuto: 'all',
      },
    }
};

function MyIntegrationComponent() {
  const {
    installation,
    isPending: isInstallationPending, // No data yet
    isFetching: isInstallationFetching, // Data is being refreshed
    isError: isInstallationError,
    error: installationError,
  } = useInstallation();
  
  const {
    connection,
    isPending: isConnectionPending, // No data yet
    isFetching: isConnectionFetching, // Data is being refreshed
    isError: isConnectionError,
    error: connectionError,
  } = useConnection(); 

  // Custom connection loading, error, and installation state overrides
  if (isConnectionPending || isInstallationPending) return <div>Loading </div>;
  if (isConnectionError) return <div>Error loading connection: {connectionError.message}</div>;
  if (isInstallationError) return <div>Error loading installation: {installationError.message}</div>;

  // The installation already exists
  if (!!installation) { return (<MyManageInstallationComponent />) } 

  if (connection) {
     createInstallation({ config: myConfig });
  };

  // Use Ampersand's built in UI for the Connection flow
  // This is the same as the existing ConnectProvider component but parameters
  // can be ommited since we are inside of InstallationProvider
  // When the connection is successful, this component will re-render since
  // `useConnection` will return the new connection.
  return (
     <ConnectProvider
        consumerRef={installationParams.consumerRef}
        groupRef={installationParams.groupRef}
     />
  );
}
```


# Manage customer schemas
Source: https://docs.ampersand.ai/manage-customer-schemas

Fetch fields from your customer's SaaS, create or update custom fields in Salesforce and HubSpot, and monitor schema changes with watchSchema.

Ampersand helps you manage the schema of objects in your customer's SaaS instances by giving you the ability to:

* Get a list of the current fields (including standard and custom fields)
* Create or update custom fields
* Detect when fields have been created, deleted, or have their types changed

On the other hand, if you are looking to manage the schema of the data that Ampersand sends you, you can use [Object and field mappings](/object-and-field-mapping).

## Fetch existing fields

### Using headless UI

Use the `useManifest` hook to retrieve existing fields from your customer's SaaS instance. The `getCustomerFieldsForObject` function returns all fields for a given object, including both standard and custom fields.

```tsx theme={"dark"}
const { getCustomerFieldsForObject } = useManifest();

// Get all fields for a specific object
const fields = getCustomerFieldsForObject("account");
```

See the [headless UI library page](/headless#get-fields-from-customers-saas) for more details.

### Using API

Use the Ampersand API to get object metadata that includes all fields for an object:

* [Get object metadata via installation](/reference/objects-&-fields/get-object-metadata-via-installation) - Use this when you have an installation
* [Get object metadata via connection](/reference/objects-&-fields/get-object-metadata-via-connection) - Use this when you only have a connection, this is helpful if you need to retrieve fields while a customer is setting up their integration.

Both endpoints return field metadata such as field names, types, display names, and whether fields are custom or read-only.

## Create or update custom fields

You can programmatically create or update custom fields in your customer's SaaS instance using Ampersand's API. This is useful when you need to ensure specific custom fields exist before writing data to them. **Please note that only Salesforce and HubSpot support this feature at the moment.**

Ampersand provides two endpoints for managing custom fields:

* [Upsert custom fields for installation](/reference/objects-&-fields/upsert-custom-fields-for-installation) - Use this when you already have an installation
* [Upsert custom fields for connection](/reference/objects-&-fields/upsert-custom-fields-for-connection) - Use this when you only have a connection (useful during installation setup)

Both endpoints accept field definitions that specify the field name, type, display name, and other properties. The API will create the field if it doesn't exist, or update it if it does.

### Provider-specific behavior

#### Salesforce

<Warning>Please instruct your customers to provide the integration with adequate permissions, see [Salesforce customer guide](/customer-guides/salesforce#custom-field-management-permissions) for more details.</Warning>

When creating custom fields in Salesforce, Ampersand automatically handles field permissions to ensure your integration can access the newly created fields:

1. **Permission Set**: Ampersand creates a managed Permission Set named `IntegrationCustomFieldVisibility` that grants read and edit access to custom fields
2. **Field Permissions**: View and write permissions for the new custom fields are automatically added to this Permission Set
3. **User Assignment**: The Permission Set is automatically assigned to the user that provided their credentials for the Connection

This ensures that custom fields are immediately accessible to your integration after creation.

#### HubSpot

When creating custom fields in HubSpot, Ampersand automatically organizes them into a property group:

1. **Property Group**: Ampersand creates a managed property group named `integrationcreatedproperties` (displayed as "Integration Created Properties")
2. **Field Organization**: All custom fields created through Ampersand are organized under this group for easy management

## Watch schema changes

Ampersand allows you to monitor changes to the schema of objects in your customers' SaaS applications. This enables your application to react when fields are created, deleted, or have their types changed, helping you keep your integration in sync with your customers' evolving data structures.

To do this, add `watchSchema` as a key in your integration defined in `amp.yaml` & deploy the integration using `amp deploy`. You need to specify:

* The name of the [destination](/destinations) where you want to receive schema change notifications.
* The schedule frequency for Ampersand to check for schema changes. The most frequent schedule you can set is once per hour, and the default is once every 24 hours.
* The type of schema changes to monitor (fields added, removed, or changed)

Once you deploy the integration, Ampersand will start monitoring the requested schema changes for all objects across all installations of your integration. If you wish to stop monitoring schema changes, you can remove the `watchSchema` key from your integration definition & redeploy the integration using `amp deploy`.

### Event types

You can configure which types of schema changes to monitor:

* **fieldCreated:** triggers when a new field is added to an object.
* **fieldDeleted:** triggers when a field is removed from an object.
* **fieldChanged:** triggers when a field's data type, label, or description is modified.

For each event type, set `enabled: always` to be notified of that type of change.

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: hubspotIntegration
    provider: hubspot
    read:
      objects:
        .....

    watchSchema:
      destination: schemaChangeWebhook
      schedule: "0 0 */2 * *" # once every 2 days
      allObjects: # For now, you need to listen to changes on all objects in your read action.
        fieldCreated:
          enabled: always
        fieldDeleted:
          enabled: always
        fieldChanged:
          enabled: always
```

### Receiving schema change events

You will receive webhook messages when schema changes are detected in your customers' SaaS instances. These webhooks are sent to the destination you specified in your `watchSchema` configuration.

Depending on the types of schema change events you've enabled, the webhook payload can contain different arrays in the `result` object:

* **createdFields:** fields that have been added to the object.
* **deletedFields:** fields that have been removed from the object.
* **changedFields:** fields that have been modified, including both the old and new field definitions.

### Example payload

```json theme={"dark"}
{
  "action": "schema.watch",
  "projectId": "my-project-id",
  "provider": "hubspot",
  "groupRef": "my-group-ref",
  "groupName": "my-group-name",
  "consumerRef": "my-consumer-ref",
  "consumerName": "my-consumer-name",
  "installationId": "my-installation-id",
  "installationUpdateTime": "my-installation-update-time",
  "objectName": "object-name",
  "result": {
    "createdFields": [
      {
        "fieldName": "address",
        "displayName": "Street Address",
        "valueType": "string",
        "providerType": "string",
        "isCustom": false,
        "readOnly": false
      }
    ],
    "deletedFields": [
      {
        "fieldName": "old_field",
        "displayName": "Old Field",
        "valueType": "string",
        "providerType": "string",
        "isCustom": true,
        "readOnly": false
      }
    ],
    "changedFields": [
      {
        "oldSchema": {
          "fieldName": "email",
          "displayName": "Email Address",
          "valueType": "string",
          "providerType": "string",
          "isCustom": false,
          "readOnly": true
        },
        "newSchema": {
          "fieldName": "email",
          "displayName": "Email",
          "valueType": "string",
          "providerType": "string",
          "isCustom": false,
          "readOnly": false
        }
      }
    ]
  }
}
```


# Manifest schema reference
Source: https://docs.ampersand.ai/manifest-reference

Field-by-field reference for the amp.yaml manifest schema: integration, read, write, proxy, and subscribe definitions, plus schedule and backfill options.

## Introduction

An Ampersand manifest (`amp.yaml`) is a YAML file that defines how your application integrates with various SaaS platforms through the Ampersand integration platform.

This page provides a comprehensive reference for the schema of this file, including detailed field descriptions and best practices.

<Tip>
  **VSCode Extension for amp.yaml**

  Install the [Ampersand Schema Validator](https://marketplace.visualstudio.com/items?itemName=amp-labs.ampersand-schema-validator) extension for Visual Studio Code to get:

  * Real-time validation and error detection
  * Auto-completion for all manifest fields
  * Hover documentation with examples
  * Quick fixes for common issues
  * Template generation for various providers

  This extension helps you write valid `amp.yaml` files faster and catch errors before deployment.
</Tip>

## OpenAPI spec

The OpenAPI spec for the manifest [is available on GitHub](https://github.com/amp-labs/openapi/blob/main/manifest/manifest.yaml).

## Top-level structure

The Ampersand manifest starts with a top-level structure that specifies the schema version and a list of integrations:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: integration1
    provider: provider1
    # ... integration 1 configuration
  - name: integration2
    provider: provider2
    # ... integration 2 configuration
```

| Field | Type | Required | Description |
| - | - | - | - |
| `specVersion` | String | Yes | The version of the manifest specification. Format: `MAJOR.MINOR.PATCH`. Currently only `1.0.0` is supported. |
| `integrations` | Array | Yes | An array of [integration configurations](#integration-definition). Each element defines a complete integration with a specific provider. |

<Note>
  Notes

  * Only one `specVersion` is allowed per manifest file.
  * The `integrations` array must contain at least one integration configuration.
  * Multiple integrations can reference the same provider with different configurations.
</Note>

## Integration definition

Each integration defines a connection to a specific provider (e.g., Salesforce, HubSpot). This section contains the basic metadata about the integration:

```yaml theme={"dark"}
name: my-integration
displayName: My Integration
provider: salesforce
module: crm  # Optional: for providers with modules
read:
  ...
write:
  ...
proxy:
  ...
subscribe:
  ...
```

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | String | Yes | A unique identifier for this integration within your manifest. Use lowercase alphanumeric characters, hyphens and underscores only. Maximum length: 64 characters. |
| `displayName` | String | No | A human-readable name for this integration. Maximum length: 100 characters. |
| `provider` | String | Yes | The provider/platform for this integration. Must be one of the [supported providers](/provider-guides/overview) (e.g., `salesforce`, `hubspot`, `intercom`). Case-sensitive. |
| `module` | String | No | Module within the provider (e.g., `crm` for HubSpot CRM). Only applicable for certain providers. |
| `subscribe` | Object | No | The [subscribe definition](#subscribe-definition). See [Subscribe Actions](/subscribe-actions) for implementation details. |
| `read` | Object | No | The [read definition](#read-definition). See [Read Actions](/read-actions) for implementation details. |
| `write` | Object | No | The [write definition](#write-definition). See [Write Actions](/write-actions) for implementation details. |
| `proxy` | Object | No | The [proxy definition](#proxy-definition). See [Proxy Actions](/proxy-actions) for implementation details. |

<Note>
  Naming Conventions

  * `name`: Use descriptive, unique names that identify the purpose of the integration. Examples: `salesforce-contacts-sync`, `hubspot-crm-integration`, `github-issues-tracker`.
  * `displayName`: Use proper capitalization and spacing for better readability in UIs. Examples: "Salesforce Contacts Sync", "HubSpot CRM Integration", "GitHub Issues Tracker".
</Note>

## Subscribe definition

The `subscribe` section defines how to subscribe to real-time create, update, and delete events from the provider. This section is optional - if your integration does not need real-time data, you can omit this section. Learn more in [Subscribe Actions](/subscribe-actions).

```yaml theme={"dark"}
subscribe:
  objects:
    - objectName: account
      destination: accountWebhook
      inheritFieldsAndMapping: true
      createEvent:
        enabled: always
      updateEvent:
        enabled: always
        watchFieldsAuto: all  # Alternatively, use requiredWatchFields
      deleteEvent:
        enabled: always
```

| Field | Type | Required | Description |
| - | - | - | - |
| `objects` | Array | Yes | An array of [objects to subscribe](#subscribe-object) to. Each element defines a specific object type to receive events for. |

<Note>
  Subscribe considerations

  * Check the specific [provider guide](/provider-guides/overview) to see which providers support subscribe actions. If subscribe actions aren't supported for a particular provider, you can still use read actions to get updated data every 10 minutes.
  * A `read` block must always be defined alongside a `subscribe` block. Each subscribed object that uses `createEvent`, `updateEvent`, or `deleteEvent` must also have a matching object entry in the `read` block (with the same `objectName`) and set `inheritFieldsAndMapping: true`. Objects that only use `otherEvents` do not need their own entry in the `read` block.
  * Only one of `requiredWatchFields` or `watchFieldsAuto` should be provided for update events.
  * See [Subscribe Actions documentation](/subscribe-actions) for detailed implementation guidance.
</Note>

## Read definition

The `read` section defines what data to read from the provider. This section is optional - if your integration only writes data or uses proxy, you can omit this section. Learn more in [Read Actions](/read-actions).

```yaml theme={"dark"}
read:
  objects:
    - objectName: contact
      destination: defaultWebhook
      schedule: "*/30 * * * *"
      requiredFields:
        - fieldName: firstname
        - fieldName: lastname
      optionalFields:
        - fieldName: phone
      backfill:
        defaultPeriod:
          fullHistory: true
```

| Field | Type | Required | Description |
| - | - | - | - |
| `objects` | Array | Yes | An array of [objects to read](#read-object) from the provider. Each element defines a specific object type (e.g., contacts, leads) to read. |

<Note>
  Read considerations

  * Check the specific [provider guide](/provider-guides/overview) to see which objects support reading.
  * For complex integrations, consider combining read actions with [subscribe actions](#subscribe-definition) to get both historical data and real-time updates.
  * See [Read Actions documentation](/read-actions) for detailed implementation guidance.
</Note>

## Write definition

The `write` section defines what data can be written to the provider. This section is optional - if your integration only reads data, subscribes to events, or uses proxy, you can omit this section. Learn more in [Write Actions](/write-actions).

```yaml theme={"dark"}
write:
  objects:
    - objectName: contact
      inheritMapping: true
```

| Field | Type | Required | Description |
| - | - | - | - |
| `objects` | Array | Yes | An array of [objects to write](#write-object) to the provider. Each element defines a specific object type (e.g., contacts, leads) that can be written to. |

<Note>
  Write Considerations

  * Check the specific [provider guide](/provider-guides/overview) to see which objects support writing.
  * When `inheritMapping: true` is set, field mappings defined in the read definition will also be used for writing, which simplifies definition for bidirectional syncs.
  * See [Write Actions documentation](/write-actions) for detailed implementation guidance.
</Note>

## Proxy definition

The `proxy` section configures API call proxying. This allows direct access to the provider's API through Ampersand's proxy. This section is optional - if your integration does not need to make proxy calls, you can omit this section. Learn more in [Proxy Actions](/proxy-actions).

```yaml theme={"dark"}
proxy:
  enabled: true
```

| Field | Type | Required | Description |
| - | - | - | - |
| `enabled` | Boolean | No | Whether proxy is enabled for this integration. Default: `false`. |

## Object-level definition

### Read object

Each object in the `objects` array defines a specific data type to read from the provider:

| Field | Type | Required | Description |
| - | - | - | - |
| `objectName` | String | Yes | The [name of the object](#object-name) to read (e.g., `contact`, `lead`, `account`). This must match an object type supported by the provider's API (see note below). Case-sensitive. |
| `destination` | String | Yes | The [webhook destination](#destination) for the read data. This determines where the data will be sent after it's read. Must match a webhook configured in your Ampersand account. See [Destinations](/destinations) for setup. |
| `schedule` | String | Yes | A [cron schedule](#schedule) for reading the data. Defines how frequently the data should be read. Uses standard cron syntax. Examples: `*/10 * * * *` (every 10 minutes), `0 0 * * *` (daily at midnight). |
| `enabled` | String | No | Set to `always` to read this object for every installation. Consumers can't turn it off. See [Always-enabled objects](/read-actions#always-enabled-objects). |
| `backfill` | Object | No | [Configuration for backfilling](#backfill) historical data. Defines how historical data should be loaded. See [backfill behavior](/read-actions#backfill-behavior) for details. |
| `requiredFields` | Array | No | Fields that are always read for every customer. These fields will always be included in the data that's read. See [Field Configuration](#field) for more details. |
| `optionalFields` | Array | No | Optional fields that can be included. Customers can choose which of these fields to include. See [Field Configuration](#field) for more details. |
| `optionalFieldsAuto` | String | No | Set to `all` to automatically include all available fields. This can be used instead of explicitly listing optional fields. |
| `mapToName` | String | No | An optional name mapping for this object. Used to standardize object names across different providers. See [Object and Field Mapping](/object-and-field-mapping) for details. |
| `mapToDisplayName` | String | No | An optional display name mapping for this object. Used for UI display. |

These fields control **which fields** are read. To control **which records** are read, use `fieldFilters`, which is set per-installation in the installation config rather than in `amp.yaml`.

> Learn more in [Field filters](#field-filters).

<Note>
  When configuring fields for a read object, keep these points in mind:

  * You can combine `requiredFields` and `optionalFields` in the same object definition.
  * For detailed options on configuring individual fields, see the [Field Configuration](#field) section.
  * Learn more about [Object and Field Mapping](/object-and-field-mapping).
</Note>

### Write object

| Field | Type | Required | Description |
| - | - | - | - |
| `objectName` | String | Yes | The [name of the object](#object-name) to write to. Must match an object type supported by the provider's API. Case-sensitive. |
| `inheritMapping` | Boolean | No | Whether to inherit mappings from read definition. If `true`, field mappings defined in the read definition will be used for writing. Default: `false`. |

### Subscribe Object

Each object in the `objects` array defines a specific object type to subscribe to:

| Field | Type | Required | Description |
| - | - | - | - |
| `objectName` | String | Yes | The [name of the object](#object-name) to subscribe to. Must match an object type supported by the provider. Case-sensitive. |
| `destination` | String | Yes | The [webhook destination](#destination) for the event data. This determines where the event data will be sent. Must match a webhook configured in your Ampersand account. See [Destinations](/destinations) for setup. |
| `inheritFieldsAndMapping` | Boolean | Conditional | Whether to inherit field mappings from read configuration. Required and must be set to `true` when the object uses `createEvent`, `updateEvent`, or `deleteEvent`. Not required for objects that only use `otherEvents`. |
| `createEvent` | Object | No | Configuration for create events. See [Event Configuration](#subscribe-action-events) below. |
| `updateEvent` | Object | No | Configuration for update events. See [Event Configuration](#subscribe-action-events) below. |
| `deleteEvent` | Object | No | Configuration for delete events. See [Event Configuration](#subscribe-action-events) below. |
| `associationChangeEvent` | Object | No | Configuration for association change events. |
| `otherEvents` | Array | No | Array of non-standard events to subscribe to (e.g., `object.merged`, `object.restored`). |

## Details

### Object Name

The `objectName` must match the API object name in the provider's system. Some common examples:

* Salesforce: `contact`, `lead`, `account`, `opportunity`
* HubSpot: `contacts`, `companies`, `deals`, `tickets`
* GitHub: `repos`, `issues`, `pulls`, `users`
* Intercom: `contacts`, `companies`, `conversations`, `teams`

See the [Provider Guides](/provider-guides/overview) for provider-specific object names.

### Destination

The `destination` field must match a destination configured in your Ampersand dashboard. Common patterns for naming include:

* Provider-specific webhooks: `salesforceWebhook`, `hubspotKinesisStream`, `intercomWebhook`
* Generic webhooks: `defaultWebhook`, `dataStream`, `analyticsWebhook`

> Learn more in [Destinations](/destinations).

### Schedule

The `schedule` field uses standard cron syntax with five fields:

```
┌───────────── minute (0 - 59)
│ ┌─────────── hour (0 - 23)
│ │ ┌───────── day of month (1 - 31)
│ │ │ ┌─────── month (1 - 12)
│ │ │ │ ┌───── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *
```

Common patterns:

* `*/10 * * * *`: Every 10 minutes
* `*/30 * * * *`: Every 30 minutes

<Note>
  Scheduling Considerations

  * Higher frequency (e.g., every 10 minutes) provides more up-to-date data but increases API usage.
  * Lower frequency (e.g., daily) reduces API usage but data may be less current.
  * Consider the provider's API rate limits when setting schedules.
  * For less frequently updated data (e.g., user profiles), a lower frequency may be sufficient.
  * For rapidly changing data (e.g., chat messages), a higher frequency is recommended.
</Note>

### Backfill

The `backfill` section configures how historical data is loaded.

> Learn more about [backfill behavior](/read-actions#backfill-behavior):

```yaml theme={"dark"}
backfill:
  defaultPeriod:
    fullHistory: true
```

| Field | Type | Required | Description |
| - | - | - | - |
| `defaultPeriod` | Object | No | The default time period for backfilling. |
| `defaultPeriod.fullHistory` | Boolean | No | Whether to backfill the full history (`true`) or just recent data (`false`). Default: `false`. |
| `defaultPeriod.days` | Number | No | The number of days to backfill. Default: `0`. |

<Note>
  Backfill Considerations

  * Setting `fullHistory: true` may result in longer initial sync times, especially for large datasets.
  * Some providers may have API rate limits that affect backfill performance.
  * In the installation config, the `backfill` object accepts one additional key, `fieldFilters`, which restricts the records read during backfill. It is not available in `amp.yaml`. See [Field filters](#field-filters).
  * See [Read Actions backfill behavior](/read-actions#backfill-behavior) for detailed implementation guidance.
</Note>

### Field filters

Field filters restrict **which records** a read action returns, by matching against field values. Only matching records are read and delivered to your destination.

Unlike every other field on this page, `fieldFilters` is **not part of the manifest schema** — it cannot be set in `amp.yaml`. It is set per-installation in the installation config, when creating or updating an installation via the [REST API](/reference/installation/create-a-new-installation) or Headless UI's [createInstallation method](/headless#create-update-and-delete-installations). See the linked documentation for more information.

### Field

In [Read Actions](#read-definition), fields can be configured in two main ways - either using a simple `fieldName` reference or using a mapped field approach (`mapToName`, `mapToDisplayName`, `prompt`, `default`). This flexibility allows for both direct field references and more sophisticated field mapping options.

> Learn more about [Object and Field Mapping](/object-and-field-mapping) and [Dynamic Field Mappings](/object-and-field-mapping#dynamic-field-mappings).

**Simple Field Reference**

For straightforward field access where you directly reference a provider's field without renaming it:

```yaml theme={"dark"}
- fieldName: firstname
```

<Tip>
  This approach is best when:

  * The field name in the provider's API is already meaningful to your application
  * You don't need to standardize field names across different providers
  * No user configuration is needed for the field
</Tip>

**Field Mapping**

For more complex scenarios, you can use field mapping to standardize field names or prompt users for configuration.

> Learn more about [field mapping strategies](/object-and-field-mapping).

```yaml theme={"dark"}
# Predefined mapping (no user input required)
- fieldName: mobilephone
  mapToName: phone
  mapToDisplayName: Phone Number

# User-defined mapping (prompts user during setup)
- mapToName: priority
  mapToDisplayName: Priority Score
  prompt: Which field do you use to track the priority of a lead?
  default: priority_level  # Optional default value
```

<Tip>
  Field mapping is useful when:

  * You want to standardize field names across different providers
  * Different customers use different field names for the same concept
  * You need to provide user-friendly display names
  * You want to prompt users to select the appropriate fields during setup

  See [Dynamic Field Mappings](/object-and-field-mapping#dynamic-field-mappings) for implementation details.
</Tip>

| Field | Type | Required | Description |
| - | - | - | - |
| `fieldName` | String | Yes\* | The name of the field in the provider's API. Must match a field available in the provider's API for the specified object. Case-sensitive. For nested fields, use JSONPath bracket notation (e.g. `$['parentField']['childField']`). See [Nested field mapping](/object-and-field-mapping#nested-field-mapping). |
| `mapToName` | String | No\* | An optional name mapping for this field. Used to standardize field names across different providers. |
| `mapToDisplayName` | String | No\* | An optional display name mapping for this field. Used for UI display. |
| `prompt` | String | No\* | An optional prompt to show when configuring this field. Helps users understand what the field is for. |
| `default` | String | No | An optional default field name to suggest when prompting users. Should only use standard fields as defaults. |

\*Either `fieldName` or all of `mapToName`, `mapToDisplayName`, and `prompt` are required.

**Common Patterns and Best Practices**

1. **Direct Field Access**: Use simple `fieldName` references for standard, unchanging fields:
   ```yaml theme={"dark"}
   - fieldName: email
   - fieldName: firstname
   - fieldName: lastname
   ```

2. **Standardized Field Names**: Use `fieldName` with `mapToName` to standardize field names:
   ```yaml theme={"dark"}
   - fieldName: FirstName  # Salesforce
     mapToName: first_name
   - fieldName: firstname  # HubSpot
     mapToName: first_name
   ```

3. **User-Defined Mapping**: Use `mapToName` without `fieldName` when users need to select the field:
   ```yaml theme={"dark"}
   - mapToName: notes
     mapToDisplayName: Contact Notes
     prompt: Select the field where you store notes about your contacts
   ```

4. **Combined Approach**: For complex integrations, combine these patterns:
   ```yaml theme={"dark"}
   requiredFields:
     - fieldName: email  # Direct field access
     - fieldName: firstname
       mapToName: first_name  # Standardized name
   optionalFields:
     - mapToName: lead_source  # User-defined mapping
       mapToDisplayName: Lead Source
       prompt: Which field tracks where this lead came from?
   ```

> Learn more about [Object and Field Mapping](/object-and-field-mapping).

### Subscribe action events

In [Subscribe Actions](/subscribe-actions), each event type can be configured with specific options:

**Create event**

The `createEvent` definition specifies how to handle create events:

```yaml theme={"dark"}
createEvent:
  enabled: always
```

| Field | Type | Required | Description |
| - | - | - | - |
| `enabled` | String | Yes | Whether to enable create events. Currently, only `always` is supported. |

**Update event**

The `updateEvent` definition specifies how to handle update events:

```yaml theme={"dark"}
updateEvent:
  enabled: always
  watchFieldsAuto: all  # Options: "all" or "selected"
```

Or alternatively:

```yaml theme={"dark"}
updateEvent:
  enabled: always
  requiredWatchFields:  # Watch specific fields
    - name
    - email
    - phone
```

| Field | Type | Required | Description |
| - | - | - | - |
| `enabled` | String | Yes | Whether to enable update events. Currently, only `always` is supported. |
| `watchFieldsAuto` | String | No\* | `all` watches all fields for changes. `selected` watches only user-selected fields when `inheritFieldsAndMapping` is true. |
| `requiredWatchFields` | Array | No\* | An array of field names to watch for changes. These can include mapped fields. |

<Note>Only one of `watchFieldsAuto` or `requiredWatchFields` should be specified.</Note>

**Delete event**

The `deleteEvent` definition specifies how to handle delete events:

```yaml theme={"dark"}
deleteEvent:
  enabled: always
```

| Field | Type | Required | Description |
| - | - | - | - |
| `enabled` | String | Yes | Whether to enable delete events. Currently, only `always` is supported. |

**Association change event**

The `associationChangeEvent` definition specifies how to handle association change events:

```yaml theme={"dark"}
associationChangeEvent:
  enabled: always
  includeFullRecords: true
```

| Field | Type | Required | Description |
| - | - | - | - |
| `enabled` | String | Yes | Whether to enable association change events. Currently, only `always` is supported. |
| `includeFullRecords` | Boolean | No | Whether to include full records in the event payload. Default: `false`. |

**Other events**

The `otherEvents` array allows you to subscribe to non-standard events specific to certain providers:

```yaml theme={"dark"}
otherEvents:
  - object.merged
  - object.restored
```

<Tip>
  Combine subscribe actions with read actions to get a complete picture of your customers' data:

  * Use read actions with backfill to get initial historical data
  * Use subscribe actions to get real-time updates going forward
  * Learn more about [combining read and subscribe actions](/subscribe-actions#specify-backfill-behavior)
</Tip>


# MCP Server
Source: https://docs.ampersand.ai/mcp-server

Connect your AI agent or MCP client to the multi-tenant Ampersand MCP server using your project ID, integration name, group ref, and API key.

Connect your agents to the 150+ connectors we offer at Ampersand via this multi-tenant MCP server. We expose the primitives we offer on the Ampersand platform as native tools here.

<Note>
  The Ampersand MCP server is in alpha. It may change in non backwards-compatible ways. (Although we are very serious about semantic versioning.)

  If you have any feedback, please file an issue [on Github](https://github.com/amp-labs/ai/issues).
</Note>

## Connect to the MCP server

Here is how you can connect to the Ampersand hosted MCP server from your AI agent or from another MCP client (such as Cursor or OpenAI Responses API).

If you wish to locally run the server, please see instructions in the [Github README](https://github.com/amp-labs/ai/tree/main/mcp-server#readme).

If your MCP client supports headers:

```JSON theme={"dark"}
{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "url": "https://mcp.withampersand.com/v1/sse?project=<AMPERSAND_PROJECT_ID>&integrationName=<AMPERSAND_INTEGRATION_NAME>&groupRef=<AMPERSAND_GROUP_REF>",
      "headers": {
        "x-api-key": "<AMPERSAND_API_KEY>"
      }
    }
  }
}
```

If your MCP client does not support headers, you can pass the API key in the query param:

```JSON theme={"dark"}
{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "url": "https://mcp.withampersand.com/v1/sse?apiKey=<AMPERSAND_API_KEY>&project=<AMPERSAND_PROJECT_ID>&integrationName=<AMPERSAND_INTEGRATION_NAME>&groupRef=<AMPERSAND_GROUP_REF>"
    }
  }
}
```

## Available tools

The Ampersand MCP server exposes the same set of tools that are available in the [Ampersand AI SDK](/ai-sdk#available-tools).


# Notification payloads
Source: https://docs.ampersand.ai/notifications/notification-payloads

See example notification payloads for webhook, Kinesis, and Amazon S3 destinations, covering installation, read, write, subscribe, and connection events.

The payload structure depends on your destination type:

* **Webhook destinations**: Payloads include `notificationType` and `data` fields.
* **Kinesis and Amazon S3 destinations**: Payloads contain the `data` object. The `notificationType` is included in the event metadata (for S3, this is the object's metadata).

You can find the OpenAPI spec for notification payloads [on GitHub](https://github.com/amp-labs/openapi/blob/main/notifications/notifications.yaml), or refer to the examples below:

<Note>
  Some payloads may include a `config` field nested within the `data` field. This config contains the complete installation configuration, including read, write, subscribe, and proxy settings.
  The installation.updated event also includes an additional lastConfig field representing the previous configuration.
  If the configuration object is too large to include inline, we will generate a signed URL you can use to fetch full configuration via GET request as a JSON file.

  <Accordion title="Example payload">
    ```json theme={"dark"}
    {
      "notificationType": "installation.updated",
      "data": {
        ...,
        "config": { //If the config content is too large, the config field will be empty and you can retrieve the content from the URL provided in `configURL`.
          "read": {
            "objects": {
              "account": {
                "objectName": "account",
                "destination": "my-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        },
        // "configURL": "https://example.com/config.json" // If the config content is too large to deliver directly, we will provide a signed URL where you can download the content as a JSON file.
        "lastConfig": { // Only for `installation.updated` notifications. If the config is too large, it will be omitted and the content will be available in `lastConfigURL`.
          "read": {
            "objects": {
              "account": {
                "objectName": "account",
                "destination": "my-old-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        }
        // "lastConfigURL": "https://example.com/lastconfig.json"
      }
    }
    ```
  </Accordion>
</Note>

<AccordionGroup>
  <Accordion title="Installation events (created, updated, deleted)">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "installation.created",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "config": { //If the config content is too large, the config field will be empty and you can retrieve the content from the URL provided in `configURL`.
          "read": {
            "objects": {
              "account": {
                "objectName": "account",
                "destination": "my-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        },
        "lastConfig": { // Only for `installation.updated` notifications. If the config is too large, it will be omitted and the content will be available in `lastConfigURL`.
          "read": {
            "objects": {
              "account": {
                "objectName": "account",
                "destination": "my-old-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        }
        // "lastConfigURL": "https://example.com/lastconfig.json"
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "config": {
        "read": {
          "objects": {
            "Account": {
              "objectName": "Account",
              "destination": "my-webhook",
              "requiredFields": [...],
              "optionalFields": [...]
            }
          }
        }
      }
    }
    ```

    Note: `config` contains the complete installation configuration object including read, write, subscribe, and proxy settings. `installation.updated` includes an additional `lastConfig` field with the previous configuration.
  </Accordion>

  <Accordion title="read.backfill.done">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "read.backfill.done",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account"
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account"
    }
    ```
  </Accordion>

  <Accordion title="read.backfill.error">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "read.backfill.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account",
        "error": "Authentication failed"
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account",
      "error": "Authentication failed"
    }
    ```

    Note: `error` describes what went wrong during the backfill. A later retry of the backfill can still succeed, in which case a `read.backfill.done` notification follows.
  </Accordion>

  <Accordion title="read.schedule.paused">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "read.schedule.paused",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "config": {
          "read": {
            "objects": {
              "Account": {
                "objectName": "Account",
                "destination": "my-webhook",
                "requiredFields": [...],
                "optionalFields": [...]
              }
            }
          }
        },
        "error": "Authentication failed"
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "config": {
        "read": {
          "objects": {
            "Account": {
              "objectName": "Account",
              "destination": "my-webhook",
              "requiredFields": [...],
              "optionalFields": [...]
            }
          }
        }
      },
      "error": "Authentication failed"
    }
    ```

    Note: `config` contains the complete installation configuration object including read, write, subscribe, and proxy settings.
  </Accordion>

  <Accordion title="read.triggered.done">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "read.triggered.done",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account",
        "fromTimestamp": "2026-01-01T00:00:00Z",
        "untilTimestamp": "2026-01-01T23:59:59Z"
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account",
      "fromTimestamp": "2026-01-01T00:00:00Z",
      "untilTimestamp": "2026-01-01T23:59:59Z"
    }
    ```

    Note: `fromTimestamp` and `untilTimestamp` indicate the time range of the triggered read.
  </Accordion>

  <Accordion title="read.triggered.error">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "read.triggered.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account",
        "fromTimestamp": "2026-01-01T00:00:00Z",
        "untilTimestamp": "2026-01-01T23:59:59Z",
        "error": "Authentication failed"
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account",
      "fromTimestamp": "2026-01-01T00:00:00Z",
      "untilTimestamp": "2026-01-01T23:59:59Z",
      "error": "Authentication failed"
    }
    ```

    Note: `error` describes what went wrong during the triggered read.
  </Accordion>

  <Accordion title="write.async.done">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "write.async.done",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "objectName": "Account",
        "success": true,
        "successfulRecordIds": ["provider-record-id-1", "provider-record-id-2"],
        "errors": []
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "objectName": "Account",
      "success": true,
      "successfulRecordIds": ["provider-record-id-1", "provider-record-id-2"],
      "errors": []
    }
    ```

    Note: For partial failures, `success` is `false` with both `successfulRecordIds` and `errors` populated.
  </Accordion>

  <Accordion title="subscribe.create.success">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "subscribe.create.success",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe"
    }
    ```
  </Accordion>

  <Accordion title="subscribe.update.success">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "subscribe.update.success",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe"
    }
    ```
  </Accordion>

  <Accordion title="subscribe.delete.success">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "subscribe.delete.success",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe"
    }
    ```
  </Accordion>

  <Accordion title="subscribe.create.error">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "subscribe.create.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "error": "provider returned 403: insufficient access to EventChannelMember"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "error": "provider returned 403: insufficient access to EventChannelMember"
    }
    ```
  </Accordion>

  <Accordion title="subscribe.update.error">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "subscribe.update.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "error": "provider returned 403: insufficient access to EventChannelMember"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "error": "provider returned 403: insufficient access to EventChannelMember"
    }
    ```
  </Accordion>

  <Accordion title="subscribe.delete.error">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "subscribe.delete.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "error": "provider unsubscribe failed after retries; the provider subscription may still be active"
      }
    }
    ```

    **Kinesis destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "error": "provider unsubscribe failed after retries; the provider subscription may still be active"
    }
    ```
  </Accordion>

  <Accordion title="Connection events (created, refreshed, updated, deleted)">
    `connection.created`, `connection.refreshed`, `connection.updated`, and `connection.deleted` share the same payload shape. `notificationType` reflects the specific event.

    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "connection.created",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "provider": "salesforce",
        "groupRef": "customer-group-ref",
        "consumerRef": "user-123",
        "consumerName": "John Doe"
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "provider": "salesforce",
      "groupRef": "customer-group-ref",
      "consumerRef": "user-123",
      "consumerName": "John Doe"
    }
    ```
  </Accordion>

  <Accordion title="connection.error">
    <Note>The `error` field is deprecated and kept for backward compatibility. Use `errors` instead. Both fields contain the same value.</Note>

    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "connection.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "provider": "salesforce",
        "groupRef": "customer-group-ref",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "errors": ["Authentication failed", "Token refresh error"],
        "error": ["Authentication failed", "Token refresh error"]
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "provider": "salesforce",
      "groupRef": "customer-group-ref",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "errors": ["Authentication failed", "Token refresh error"],
      "error": ["Authentication failed", "Token refresh error"]
    }
    ```
  </Accordion>

  <Accordion title="destination.webhook.disabled">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "destination.webhook.disabled",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "destinationId": "2e8f4c1a-9b3d-4e7f-8a2c-0d1e2f3a4b5c",
        "destinationName": "production-alerts",
        "url": "https://your-webhook.com"
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "destinationId": "2e8f4c1a-9b3d-4e7f-8a2c-0d1e2f3a4b5c",
      "destinationName": "production-alerts",
      "url": "https://your-webhook.com"
    }
    ```
  </Accordion>

  <Accordion title="destination.delivery.error">
    **Webhook destination payload:**

    ```json theme={"dark"}
    {
      "notificationType": "destination.delivery.error",
      "data": {
        "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
        "provider": "salesforce",
        "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "integrationName": "Salesforce Integration",
        "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
        "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
        "groupRef": "customer-group-ref",
        "groupName": "Customer Name",
        "consumerRef": "user-123",
        "consumerName": "John Doe",
        "destinationId": "2e8f4c1a-9b3d-4e7f-8a2c-0d1e2f3a4b5c",
        "destinationName": "production-kinesis",
        "objectName": "account",
        "action": "subscribe",
        "error": "Delivery to aws_kinesis destination exhausted retries after 3 attempts. ResourceNotFoundException: Stream not found."
      }
    }
    ```

    **Kinesis and S3 destination payload:**

    ```json theme={"dark"}
    {
      "projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
      "provider": "salesforce",
      "integrationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integrationName": "Salesforce Integration",
      "installationId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
      "groupRef": "customer-group-ref",
      "groupName": "Customer Name",
      "consumerRef": "user-123",
      "consumerName": "John Doe",
      "destinationId": "2e8f4c1a-9b3d-4e7f-8a2c-0d1e2f3a4b5c",
      "destinationName": "production-kinesis",
      "objectName": "account",
      "action": "subscribe",
      "error": "Delivery to aws_kinesis destination exhausted retries after 3 attempts. ResourceNotFoundException: Stream not found."
    }
    ```

    Note: `action` is `read` or `subscribe`, and `error` describes why the final delivery attempt failed. When the destination is a webhook, the payload also includes its `url`. This notification is sent to the destinations configured for `destination.delivery.error`, which may or may not include the destination that failed.
  </Accordion>
</AccordionGroup>


# Overview
Source: https://docs.ampersand.ai/notifications/overview



Ampersand notifications deliver real-time messages about important lifecycle changes in your project. They allow you to track when customers install, update, or delete integrations; when backfills complete; and when sync issues occur.

If you want to be notified when there are changes in your customer's SaaS instances, use [Subscribe Actions](/subscribe-actions).

## How notifications work

Notifications use topics to give you fine-grained control over which events reach which destinations. You can configure each topic to receive specific event types and route notifications to one or more destinations.

<Frame>
  <img alt="Notification Diagram" />
</Frame>

## Available events

Ampersand supports the following notification event types:

**Installation lifecycle**

* **`installation.created`**: Fires when a customer installs your integration to their SaaS instance. With the prebuilt UI and [always-enabled objects](/read-actions#always-enabled-objects), this happens as soon as the customer connects.
* **`installation.updated`**: Fires when a customer modifies their integration configuration (e.g., changes field mappings)
* **`installation.deleted`**: Fires when a customer uninstalls your integration from their SaaS instance

**Read operations**

* **`read.backfill.done`**: Fires when historical data sync completes so you know backfill data is ready to process
* **`read.backfill.error`**: Fires when a historical data sync (backfill) fails
* **`read.schedule.paused`**: Fires when a scheduled data sync is paused, often due to authentication issues or other errors
* **`read.triggered.done`**: Fires when an on-demand triggered read completes successfully
* **`read.triggered.error`**: Fires when an on-demand triggered read fails

**Write operations**

* **`write.async.done`**: Fires when an asynchronous write operation completes, indicating success or failure and which records were written or had errors

**Subscribe**

* **`subscribe.create.success`**: Fires when a subscription becomes active. For providers that Ampersand subscribes to programmatically, this is when the subscribe action is set up successfully; for providers whose webhooks are configured manually in the provider's UI, this is when the first event is delivered
* **`subscribe.update.success`**: Fires when an update to an existing subscribe action completes successfully
* **`subscribe.delete.success`**: Fires when a subscribe action is removed successfully, including tearing down the subscription on the provider's side
* **`subscribe.create.error`**: Fires when Ampersand fails to set up a subscribe action for an installation
* **`subscribe.update.error`**: Fires when Ampersand fails to update an existing subscribe action for an installation
* **`subscribe.delete.error`**: Fires when a subscribe action is removed but Ampersand could not tear down the subscription on the provider's side, so it may still be active and continue to consume provider resources (for example, event or subscription quota). You may need to remove it manually in the provider

**Connection**

* **`connection.created`**: Fires when a new OAuth connection is established with a SaaS provider
* **`connection.refreshed`**: Fires when Ampersand automatically refreshes a connection's OAuth access token as it nears expiry, using the connection's refresh token. This happens with no user involvement and keeps the connection active
* **`connection.updated`**: Fires when an existing connection is updated, either when a user re-authenticates (for example, reconnecting to resolve an errored connection) or when the connection's credentials or metadata are changed via the update connection API
* **`connection.deleted`**: Fires when a connection is deleted, such as through the dashboard or the delete connection API
* **`connection.error`**: Fires when there's an error with an OAuth connection, such as authentication failures or token refresh issues

**Destination**

* **`destination.webhook.disabled`**: Fires when a webhook destination endpoint is disabled. This can happen automatically after repeated failed delivery attempts.
* **`destination.delivery.error`**: Fires when Ampersand could not deliver read or subscribe results to a destination after all retry attempts were exhausted. This applies to every destination type (webhooks, Kinesis, S3, and other sinks). The payload identifies the destination, the installation and object whose data could not be delivered, and the error.

## Setting up notifications

There are two ways to set up notifications:

* **[Using the Dashboard](#set-up-via-dashboard)**: Visual interface for quick setup
* **[Using the API](#set-up-via-api)**: Programmatic setup for automation and integration

### Set up via Dashboard

1. **Create destinations**
   * Go to [Destinations](https://dashboard.withampersand.com/projects/_/settings/destinations/)
   * Click **New Destination** and configure:
     * **Name**: A descriptive name (e.g., "production-alerts")
     * **Type**: Choose webhook, [Slack](/destinations/slack), Kinesis, or Amazon S3
     * **Configuration**: Provide the endpoint URL or stream details
   * Click **Create Destination**

2. **Create topics**
   * Go to [Notifications](https://dashboard.withampersand.com/projects/_/notifications/)
   * Click **New Topic**
   * Configure your topic:
     * **Name**: A descriptive name (e.g., "installation-events")
     * **Event types**: Select the events this topic should receive
     * **Destinations**: Select which destinations should receive notifications
   * Click **Create Topic**

### Set up via API

When using the API, you need to create routes explicitly to connect events to topics and topics to destinations. The dashboard handles this automatically when you create a topic.

See the API Reference for complete endpoint documentation.

<Accordion title="1. Create a destination">
  ```bash theme={"dark"}
  POST https://api.withampersand.com/v1/projects/{projectIdOrName}/destinations
  {
    "name": "production-alerts",
    "type": "webhook",
    "metadata": {
      "url": "https://your-webhook.com"
    }
  }
  ```
</Accordion>

<Accordion title="2. Create a topic">
  ```bash theme={"dark"}
  POST https://api.withampersand.com/v1/projects/{projectIdOrName}/topics
  {
    "name": "installation-events"
  }
  ```
</Accordion>

<Accordion title="3. Create notification-event-topic routes">
  **Notification-Event-Topic Routes** connect specific event types to topics. This determines which events are sent to each topic.

  ```bash theme={"dark"}
  POST https://api.withampersand.com/v1/projects/{projectIdOrName}/notification-event-topic-routes
  {
    "topicId": "your-topic-id",
    "eventType": "installation.created"
  }
  ```
</Accordion>

<Accordion title="4. Create topic-destination routes">
  **Topic-Destination Routes** connect topics to destinations. This determines which destinations receive notifications for each topic.

  ```bash theme={"dark"}
  POST https://api.withampersand.com/v1/projects/{projectIdOrName}/topic-destination-routes
  {
    "topicId": "your-topic-id",
    "destinationId": "your-destination-id"
  }
  ```
</Accordion>


# Object and field mapping
Source: https://docs.ampersand.ai/object-and-field-mapping



Ampersand supports object mapping and field mapping. This allows you to either pre-define a set of mappings, or prompt your users to define their own mappings via Ampersand's UI components.

## Predefined mapping

### Object mapping

You can map an object from a provider API to a label of your choice. This can help you with any naming/semantic conventions that you need, or even help you build a unified API across different API providers.

For example, if you map the `account` object from **Salesforce** and the `companies` object from **HubSpot** to a unified label like `company`, your read action results will be delivered under the object name of `company`. The original object name will still be available in the response's `rawObjectName` key.

If you wish to write data to `company`, you can [inherit the mapping](/write-actions#share-mappings-with-read-actions) from the read action.

Here's an example of a Salesforce integration that maps the `account` object to `company`:

```YAML theme={"dark"}
  - name: salesforce-integration
    displayName: My Salesforce integration
    provider: salesforce
    read:
      objects:
        - objectName: account
          mapToName: company
          # Additional configuration
    write:
      objects:
        - objectName: account
          inheritMapping: true
```

### Field mapping

You can map individual fields to labels of your choosing. This can help you enforce naming conventions, or standardize field names across API providers.

For example, you could map a `mobilephone` field to `phone`. Read results will deliver the field under the `phone` key, and when you make a call to the Write API, you can use `phone` to update the original `mobilePhone` field if the write action inherits the mapping.

```YAML theme={"dark"}
  - name: hubspot-integration
    displayName: My HubSpot integration
    provider: hubspot
    module: crm
    read:
      objects:
        - objectName: contacts
          requiredFields:
            - fieldName: mobilephone
              mapToName: phone
    write:
      objects:
        - objectName: contacts
          inheritMapping: true
```

## User-defined mapping

User-defined mappings allow your end users (or consumers, in [Ampersand terminology](/terminology)) to define mappings. Currently, only user-defined field mappings are supported, not object mappings yet.

### Field mapping

Your end users may have a custom field to add notes to an Account object. You can ask your consumers to define this mapping at the time of installation, and receive data across different consumers under a single unified field like `notes`.

**Example**:

* You define a `notes` field in your integration.
* **User A** stores notes in `field_a`, while **User B** uses `field_b`.
* The UI library will ask each user to identify which field to map, and Ampersand delivers them under `notes`, accommodating custom fields unique to each consumer.
* You can write back to each user's specific fields by writing to the `notes` field, if you inherit the mapping.

Field mappings can either be inside `requiredFields` or `optionalFields`, you'll specify:

* **mapToName:** when Ampersand delivers the data from this field to you, this is the name that will be used to identify the field.
* **mapToDisplayName:** the text to display to the user in the UI component when asking them to select a field.
* **default** (optional): the default field, you should only use standard fields as defaults.
* **prompt** (optional): additional context that you want to show your user in the UI Component about this field, in a tooltip.

```YAML theme={"dark"}
  - name: salesforce-integration
    provider: salesforce
    read:
      objects:
        - objectName: account
          optionalFields:
            # There is no fieldName for user-mapped fields
            - mapToName: notes
              mapToDisplayName: Account notes
              prompt: Please select the field that contains notes for this account
          # Additional configuration
    write:
      objects:
        - objectName: account
          inheritMapping: true
```

If you have an optional field mapping, and the user chose not to map the field (because they do not have a field that corresponds to notes), you can still make Write API calls with `notes` populated, and Ampersand will automatically strip it from the request before writing to the provider API to prevent errors.

### Dynamic field mappings

With regular field mappings, you can define a set of fields that all your users need to map. Sometimes, you may want different users to map different sets of fields.

> For example: SampleApp is using Ampersand to integrate with their customer's HubSpot.
> SampleApp needs to ask the customer to map their SampleApp fields to their HubSpot fields, and different customers can have different sets of fields in SampleApp.

To achieve this, you can pass in the mapping configuration in the `fieldMapping` property of the `InstallIntegration` component:

```TYPESCRIPT theme={"dark"}
function MyComponent() {
  const mapping = {
    // You'd likely construct this dynamically based on your business logic
    // of determining which fields the user need to map.
    // The example is static for simplicity.
    contacts: [
      {
        mapToName: 'source',
        // Both mapToDisplayName and prompt are optional.
        mapToDisplayName: 'Source',
        prompt: 'Which field do you use to track the source of a contact?',
      },
      {
        mapToName: 'priority',
        mapToDisplayName: 'Priority',
        prompt: 'Which field do you use to track the priority of a contact?',
      }
    ],
    // Field mapping for the companies object
    companies: [
      {
        mapToName: 'AccountID',
        mapToDisplayName: 'Sales Territory',
        prompt: 'Which field do you use to track the sales territory of a company?',
      }
    ]
  }
  return (<InstallIntegration
    integration = "myHubSpotIntegration"
    consumerRef = {userId}
    consumerName = {userFullName}
    groupRef = {teamId}
    groupName = {teamName}
    fieldMapping = {mapping}
  />);
}

```

<Tip>Dynamic mappings are considered optional for a user to set, i.e., your users can install the integration without explicitly mapping a field. </Tip>

Note you can also use this configuration in tandem with static field mappings (the ones defined in `amp.yaml`):

```YAML theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: myHubSpotIntegration
    provider: hubspot
    module: crm
    read:
      objects:
        # contacts also has a static field mapping
        - objectName: contacts
          optionalFields:
            - mapToName: pronoun
              mapToDisplayName: Pronoun
              prompt: We will use this word when addressing this person in emails we send out.
          ...
        - objectName: companies
          ...
```

When the webhook message is delivered, both statically mapped fields (defined in `amp.yaml`) and dynamically mapped fields (defined in the UI component) will be present in `result.mappedFields`

```JSON theme={"dark"}
{
 ...
 "objectName": "Contact",
 "result": [
  {
    "fields": {
      ... // non-mapped fields
    },
    "mappedFields": {
      "pronoun": "she", // statically mapping
      "source": "LinkedIn", // dynamically mapped
      "priority": "high", // dynamically mapped
    },
    "raw": {
      ...
    }
  }
 ]
}
```

### Mapping values

Ampersand platform also offers the flexibility of mapping values of fields from your app to a provider like HubSpot.

These might be for fields that are mapped either in a user-defined fashion or have a pre-defined mapping defined.

Let's take an example:

* SampleApp is using Ampersand to integrate with their customer's HubSpot.
* SampleApp needs to ask the customer to map their SampleApp fields to their HubSpot fields.
* For a certain field, such as `Priority`,
  SampleApp has the values `Very High`, `High`, `Medium`, `Low` while HubSpot has the values
  `P1`, `P2`, `P3`, and `P4`. SampleApp would like the user to map the correlation between the SampleApp values and HubSpot values.

To achieve this you can define the SampleApp side of the values that need to be mapped in `InstallIntegration` component like below:

```TYPESCRIPT theme={"dark"}
const mapping = {
    deals: [
      {
        mapToName: 'priority',
        mapToDisplayName: 'Priority',
        prompt: 'Which field do you use to track the priority of a deal?',
        // Mapping values for a field that's mapped by a user
        mappedValues: [
          {
            mappedValue: 'veryhigh',
            mappedDisplayValue: 'Very High'
          },
          {
            mappedValue: 'high',
            mappedDisplayValue: 'High'
          },{
            mappedValue: 'medium',
            mappedDisplayValue: 'Medium'
          },{
            mappedValue: 'low',
            mappedDisplayValue: 'Low'
          },
        ]
      },
      {
        fieldName: 'stage',
        /**
        ** Here `stage` only needs the values to be mapped.
        ** The users will not need to map the field.
        **/
        mappedValues: [
          {
            mappedValue: 'open',
            mappedDisplayValue: 'Open'
          },{
            mappedValue: 'closedWon',
            mappedDisplayValue: 'Closed Won'
          },{
            mappedValue: 'closedLost',
            mappedDisplayValue: 'Closed Lost'
          },
        ],
      },
    ],
    companies: [
      {
        mapToName: 'territory', // No mapping of values on this field
        mapToDisplayName: 'Sales Territory',
        prompt: 'Which field do you use to track the sales territory of a company?',
      }
    ]
  }
...
return (<InstallIntegration
   integration="myHubSpotIntegration"
   fieldMapping={mapping}
   groupRef={groupRef}
   ...
/>);

```

This will ensure that your users see a mapping UI where they can select the values from the HubSpot side to be mapped to the app side values defined here.

<Tip> We only allow one-to-one mapping of values </Tip>

## Nested field mapping

Some provider APIs may have nested structures. Ampersand supports mapping from and to nested fields using [JSONPath's](https://www.rfc-editor.org/rfc/rfc9535.html) bracket notation, allowing you to extract values from nested objects or write values into nested structures.

Nested field paths use the format `$['parentField']['childField']`. Bracket notation ensures that field names containing dots, spaces, or other special characters are correctly parsed. For example, `$['parentField']['childField$With.Special"Characters"']` is valid.

Value mappings also support bracket notation.

<Note>
  When you call the [Get Object Metadata](/reference/objects-&-fields/get-object-metadata-via-connection) API, some providers may return nested fields such as `$['parentField']['childField']`. These field names can be used directly in your `amp.yaml` configuration.
</Note>

### Reading nested data

When a provider API returns nested data, you can use field mappings to extract nested values into mapped fields. Here is an example:

**Provider returns:**

```JSON theme={"dark"}
{
  "userInfo": {
    "email": "john@example.com",
    "name": "John Doe"
  },
  "status": "active"
}
```

**With this pre-defined field mapping in `amp.yaml`:**

```YAML theme={"dark"}
    read:
      objects:
        - objectName: contacts
          requiredFields:
            - mapToName: contactEmail
              fieldName: $['userInfo']['email']
            - mapToName: contactName
              fieldName: $['userInfo']['name']
            - mapToName: $['moreInfo']['currentStatus']
              fieldName: status
```

**Your destination receives:**

```JSON theme={"dark"}
{
  "mappedFields": {
    "contactEmail": "john@example.com",
    "contactName": "John Doe",
    "moreInfo": {
      "currentStatus": "active"
    }
  }
}
```

### Writing nested data

The same mappings will be applied in reverse when writing to a provider using the [Write API](/write-actions).

**Your app sends:**

```JSON theme={"dark"}
{
  "contactEmail": "john@example.com",
  "contactName": "John Doe",
  "moreInfo": {
    "currentStatus": "deleted"
  }
}
```

**Provider receives:**

```JSON theme={"dark"}
{
  "userInfo": {
    "email": "john@example.com",
    "name": "John Doe"
  },
  "status": "deleted"
}
```

## Full example

To see a full example of how to define object and field mappings, check out the [unified CRM example](https://github.com/amp-labs/samples/blob/main/unifiedCRM/amp.yaml) in our samples repository.


# Integration infrastructure for enterprise products
Source: https://docs.ampersand.ai/overview

Ampersand lets your enterprise product read, write, search, and subscribe to events in customers' SaaS, with per-customer field mappings and a managed runtime.

If you are a developer building an enterprise product or agent, Ampersand enables your product to reliably work across your customers’ systems of record. More specifically, you can:

* Read historical and current data from your customer’s system.
* Write data to your customer’s system.
* Search your customer’s system by filter criteria, with matching records returned immediately.
* Subscribe to events (creates, deletes, and field changes) in your customer’s system.

Ampersand’s declarative interface and UI components let your customers configure integrations with their CRM, ERP, or other systems of record directly within your product.

[Quickstart →](/starter-project) · [Explore supported systems →](/provider-guides/overview)

## Built for each of your customers’ configurations

**Ampersand handles multi-tenancy at scale.** Say you have 400 customers on Salesforce. Every one of them has customized it to reflect how they run their business, with different custom objects, fields, permissions, and rules for how your product interacts with their data. Two very similar companies can store the same data in completely different places.

Ampersand separates the integration you build from each customer's configuration. You define the schema and actions your application needs once, and each installation keeps track of the per-customer mappings. For example, you define `renewalDate` once, and each customer uses the embeddable UI library to map it to where they're actually storing the renewal date in their Salesforce.

| Customer | Where `renewalDate` lives |
| - | - |
| Customer A | `Account.Renewal_Date__c` |
| Customer B | `Account.Contract_End__c` |
| Customer C | `Subscription__c.End_Date__c` |
| …397 more | Each set by the customer during setup |

Your application reads and writes `renewalDate`. Ampersand translates it to each customer’s field.

## How Ampersand works

<Steps>
  <Step title="Define an integration">
    Use an `amp.yaml` file to declare each integration: the system to connect to, the objects and fields to read or write, and the configuration options to expose to your customers. See the [manifest reference](/manifest-reference).
  </Step>

  <Step title="Let customers connect and configure">
    Embed authentication and configuration in your product with [prebuilt UI components](/embeddable-ui-components), [headless UI library](/headless), or [API](/api/overview). Customers connect their own instance and choose field mappings and preferences, and Ampersand saves those choices in their installation.
  </Step>

  <Step title="Ampersand runs it">
    A managed runtime tracks every customer's configuration and makes the right API calls for each one. It handles authentication, scheduling, retries, rate limits, and non-standard provider error messages. You can either make direct API calls or have async results delivered to your [destinations](/destinations/overview).
  </Step>

  <Step title="Monitor, adapt, and recover">
    Inspect installations and operation logs, get [notifications](/notifications/overview) about connection issues, sync failures, and configuration changes, and [watch for schema changes](/manage-customer-schemas#watch-schema-changes) when fields are added, removed, or modified. Use these signals to operationalize your integrations by alerting your team or your customers when actions need to be taken.
  </Step>
</Steps>

## Actions

Actions are the verbs of every integration. You declare them in your manifest.

<CardGroup>
  <Card title="Read" icon="download" href="/read-actions">
    Scheduled or on-demand reads with full backfills and incremental syncs.
  </Card>

  <Card title="Write" icon="upload" href="/write-actions">
    Create and update records, synchronously or asynchronously.
  </Card>

  <Card title="Subscribe" icon="bell" href="/subscribe-actions">
    Get notified about creates, updates, and deletes as they happen.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/search-actions">
    Targeted searches based on field filters.
  </Card>

  <Card title="Proxy" icon="arrow-right-arrow-left" href="/proxy-actions">
    Call any provider endpoint directly with managed auth and rate limit handling.
  </Card>
</CardGroup>

## Watch demo

<iframe title="Ampersand demo" />

## Get started

<CardGroup>
  <Card title="Clone the starter project" icon="rocket" href="/starter-project">
    If you want to see an example.
  </Card>

  <Card title="Onboard with Claude Code" icon="rocket" href="/use-with-ai-ide">
    If you want to add integrations to an existing codebase.
  </Card>
</CardGroup>

## Dig deeper

<CardGroup>
  <Card title="Browse the integration directory" icon="plug" href="/provider-guides/overview">
    Search the supported providers.
  </Card>

  <Card title="How Ampersand works" icon="book" href="/concepts">
    Learn the concepts.
  </Card>

  <Card title="REST API" icon="code" href="/api/overview">
    Platform, read, write, search, and proxy APIs.
  </Card>

  <Card title="UI Library" icon="cube" href="/headless">
    Prebuilt components and headless UI.
  </Card>

  <Card title="Manifest schema" icon="file-code" href="/manifest-reference">
    Learn what goes into the `amp.yaml` file.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/reference">
    Install the Ampersand CLI for deploying and managing integrations.
  </Card>
</CardGroup>

## Contact us

Need help? Join our [Discord channel](https://discord.gg/7XTz4HRR47) or email [support@withampersand.com](mailto:support@withampersand.com).

If you want to chat through your use case with our team, <a href="https://www.ampersand.ai/demo?cta=docs_home">book a call</a>.


# AccuLynx
Source: https://docs.ampersand.ai/provider-guides/accuLynx

Connect AccuLynx to Ampersand with an API key to read, write, and subscribe to jobs, contacts, and custom fields, plus proxy calls to the AccuLynx API.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. **Please note that incremental read is only supported for `jobs`, `jobs/history`, `jobs/custom-fields`, `contacts/custom-fields`, `estimates/sections`, and `company-settings/custom-fields`.**
* [Write Actions](/write-actions).
* [Subscribe Actions](/subscribe-actions). Ampersand creates and updates the AccuLynx webhook subscription on your behalf when the customer installs your integration — no manual webhook setup is required in the AccuLynx UI.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.acculynx.com`.

### Supported objects

The AccuLynx connector supports the following objects:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

\* The connector will read all jobs - assigned and unassigned.

\*\* For these objects, the connector will first enumerate all the jobs, and then list their child records. (e.g. For `jobs/financials`, the connector will first list all jobs, and then read the financials for all jobs.)

<Note>
  **Writes are limited by AccuLynx's API:**

  * **Create-only:** `jobs`, `contacts`, and their nested write endpoints (except custom-fields) — AccuLynx has no update endpoints for these records.
  * **Update-only:** `contacts/custom-fields` and `jobs/custom-fields` — you can change a custom field's value, but cannot create, update, or delete the field definitions themselves.
</Note>

**Custom fields** defined in AccuLynx are automatically discovered and surfaced on `contacts` and `jobs` records.

**Subscribe events:** create and update are supported directly on `contacts` and `jobs`. The other 6 subscribe-enabled objects in the table above are subscribed via [`otherEvents`](/subscribe-actions#other-events) under their parent `contacts` or `jobs` object in your `amp.yaml`. AccuLynx emits additional `jobs` change topics too — financial, appointment, category, trade/work-type, and more — which you subscribe to the same way. See AccuLynx's [webhook topics reference](https://apidocs.acculynx.com/reference/gettopics) for the full list.

### Example integration

For an example manifest file of an AccuLynx integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/accuLynx/amp.yaml).

## Before you get started

To use the AccuLynx connector, you'll need an API key from your AccuLynx account. Here's how to get it:

1. Sign in to your AccuLynx account as a Location or Company Administrator.
2. Click your name in the upper-right corner and select **Account Settings**.
3. In the left sidebar, expand **Add-On Features and Integrations** and click **API Keys** (or go directly to the [API Keys page](https://my.acculynx.com/apikeys)).
4. Click **Create Key**, enter a descriptive name, and select a Lead Source.
5. Click **Create Key** in the modal, then **Copy Key** to copy the token.

<img alt="AccuLynx API Key" />

API keys are scoped to a single AccuLynx account location, so each Ampersand connection corresponds to one AccuLynx location. Each integration within an AccuLynx account location should have its own dedicated API key.

For more details, see the [AccuLynx Authentication documentation](https://apidocs.acculynx.com/reference/authentication).

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with AccuLynx:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions or Subscribe Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for their API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Acuity Scheduling
Source: https://docs.ampersand.ai/provider-guides/acuityScheduling

Register an Acuity Scheduling OAuth app for Ampersand, then read appointments, clients, and orders, write blocks and certificates, and make proxy calls.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental reading is only supported for `appointments`, `availability/classes`, `blocks`. For all other objects, a full read of the Acuity Scheduling instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://acuityscheduling.com`.

### Supported objects

The Acuity Scheduling connector supports reading from the following objects:

* [appointments](https://developers.acuityscheduling.com/reference/get-appointments)
* [appointment-addons](https://developers.acuityscheduling.com/reference/appointments-addons)
* [appointment-types](https://developers.acuityscheduling.com/reference/appointment-types)
* [availability/classes](https://developers.acuityscheduling.com/reference/get-availability-classes)
* [blocks](https://developers.acuityscheduling.com/reference/blocks)
* [calendars](https://developers.acuityscheduling.com/reference/get-calendars)
* [certificates](https://developers.acuityscheduling.com/reference/get-certificates)
* [clients](https://developers.acuityscheduling.com/reference/clients)
* [forms](https://developers.acuityscheduling.com/reference/forms)
* [labels](https://developers.acuityscheduling.com/reference/labels)
* [orders](https://developers.acuityscheduling.com/reference/get-orders)
* [products](https://developers.acuityscheduling.com/reference/get-products)

The Acuity Scheduling connector supports writing to the following objects:

* [appointments](https://developers.acuityscheduling.com/reference/post-appointments)
* [blocks](https://developers.acuityscheduling.com/reference/post-blocks)
* [certificates](https://developers.acuityscheduling.com/reference/post-certificates)
* [clients](https://developers.acuityscheduling.com/reference/post-clients)

### Example integration

For an example manifest file of an Acuity Scheduling integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/acuityscheduling/amp.yaml).

## Before You Get Started

To integrate Acuity Scheduling with Ampersand, you will need [an Acuity Scheduling Account](https://acuityscheduling.com/).

Once your account is created, you'll need to register an Oauth app and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials and scopes to connect your application to Ampersand.

### Create an Acuity Scheduling Account

Here's how you can sign up for an Acuity Scheduling account:

* Go to the [Acuity Scheduling Sign Up page](https://login.squarespace.com/api/1/login/oauth/provider/authorize?client_id=aHW16IlRwTPNctfSvoofuCarXfdJDvJK\&state=U2dzVitmZFBhVjd0aGJpekJHcFdkU0JoTHY4bnk5U3dGTHRNN3c2MlVidz06eyJ1IjowLCJ4IjoxNzIyNTA5MjA2LCJuIjoiZTZlYmVkZTcifQ%3D%3D\&redirect_uri=https%3A%2F%2Fsecure.acuityscheduling.com%2Foauth2%2Fsquarespace-trial%2Fcallback\&access_type=offline\&action=form\&type=professional\&freeTrial=1\&lite=1\&btn=nav\&action=form\&type=professional\&freeTrial=1\&lite=1\&btn=nav\&overrideLocale=en-US\&device_id=d000e6d3-e4b3-4e9a-b8f5-5136c400de1e\&analytics_id=d000e6d3-e4b3-4e9a-b8f5-5136c400de1e\&entry_point=acuity#/signup).
* Sign up using your preferred method and complete any necessary verification.

### Creating an Acuity Scheduling App

Follow the steps below to create an Acuity Scheduling app:

1. Go to [Acuity Scheduling OAuth2 Account Registration](https://acuityscheduling.com/developers).
2. Enter the following details:
   1. **Account Name:** The name of your Acuity Scheduling account or organization.
   2. **Email Address:** The email address associated with your Acuity Scheduling account. This will be used for communication regarding your app.
   3. **Website:** The URL of your application's website. This helps users understand what your application does.
   4. **Application Description:** A brief description of your application and its purpose.
   5. **Callback URIs:** Enter the Redirect URI as `https://api.withampersand.com/callbacks/v1/oauth`. This URI is where users will be redirected after authorizing your app.
3. Click **Save**.

<img alt="Acuity Scheduling App Creation" />

You will see the **Client ID** and **Client Secret** in the app details. Note these credentials, as you will need them to connect your app to Ampersand.

<img alt="Acuity Scheduling App Creation" />

## Add Your Acuity Scheduling App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create an Acuity Scheduling integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Acuity Scheduling* from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in *Acuity Scheduling*.

   <img alt="Ampersand Integration" />

7. Click **Save Changes**.

## Using the connector

To start integrating with Acuity Scheduling:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Aha!
Source: https://docs.ampersand.ai/provider-guides/aha

Connect Aha! to Ampersand via an OAuth application to read epics, features, ideas, and goals, write select objects, and make proxy calls to the Aha! API.

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `audits`, `historical_audits`, `ideas/endorsements` and `ideas` currently. For all other objects, a full read of the Aha! instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.aha.io/api`.

### Supported Objects

The Aha! connector supports writing to and reading from the following objects:

* [audits](https://www.aha.io/api/resources/audits/retrieve_record_history) (incremental read)
* [capacity\_scenarios](https://www.aha.io/api/resources/capacity_scenarios/list_capacity_scenarios) (read)
* [screen\_definitions](https://www.aha.io/api/resources/custom_layouts/list_all_custom_layouts) (read)
* [custom\_field\_definitions](https://www.aha.io/api/resources/custom_fields/list_all_custom_fields) (read)
* [epics](https://www.aha.io/api/resources/epics/list_epics) (read)
* [features](https://www.aha.io/api/resources/features/list_features) (read)
* [goals](https://www.aha.io/api/resources/goals/list_goals) (read)
* [historical\_audits](https://www.aha.io/api/resources/historical_audits/read_the_contents_of_the_historical_index) (incremental read, write)
* [idea\_portals](https://www.aha.io/api/resources/idea_portals/list_all_idea_portals_in_an_account) (read)
* [idea\_organizations](https://www.aha.io/api/resources/idea_organizations/list_idea_organizations) (read, write)
* [idea\_users](https://www.aha.io/api/resources/idea_users/list_idea_users_for_an_account) (read, write)
* [ideas](https://www.aha.io/api/resources/ideas/list_ideas) (incremental read)
* [ideas/endorsements](https://www.aha.io/api/resources/idea_votes/list_votes_for_an_account) (incremental read)
* [identity\_providers](https://www.aha.io/api/resources/identity_providers/list_active_identity_providers_that_can_be_used_for_sso) (read)
* [initiatives](https://www.aha.io/api/resources/initiatives/list_initiatives) (read)
* [integrations](https://www.aha.io/api/resources/integrations/list_integrations_for_an_account) (read, write)
* [me/tasks](https://www.aha.io/api/resources/me/list_pending_tasks_assigned_to_the_current_user) (read)
* [me/assigned](https://www.aha.io/api/resources/me/list_records_assigned_to_the_current_user) (read)
* [paid\_seat\_groups](https://www.aha.io/api/resources/paid_seat_groups/list_the_administered_paid_seat_groups) (read)
* [products](https://www.aha.io/api/resources/products/list_products_with_idea_portals_in_the_account) (read, write)
* [release\_phases](https://www.aha.io/api/resources/release_phases/list_release_phases_in_the_account) (read, write)
* [schedules](https://www.aha.io/api/resources/schedules/list_schedules) (read)
* [strategy\_models](https://www.aha.io/api/resources/strategic_models/list_strategic_models) (read)
* [strategy\_positions](https://www.aha.io/api/resources/strategic_positionings/list_strategic_positionings) (read)
* [strategy\_visions](https://www.aha.io/api/resources/strategic_visions/list_strategic_visions) (read)
* [team\_members](https://www.aha.io/api/resources/team_members/list_virtual_team_members) (read, write)
* [teams](https://www.aha.io/api/resources/teams/list_teams) (read)
* [tasks](https://www.aha.io/api/resources/to-dos/list_approvals) (read, write)
* [users](https://www.aha.io/api/resources/users/list_users) (read)

## Before You Get Started

To integrate Aha! with Ampersand, you need to [Create an Aha! Account](#create-an-aha-account) and obtain the following credentials from your Aha! App:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create an Aha! Account

You need an **Aha!** account to connect with Ampersand. If you do not have an Aha! account, here's how you can sign up:

* Go to the [Aha! site](https://www.aha.io/) and sign up for a free account.
* Sign up using your preferred account.
* Verify your email and complete the registration process.

### Creating an Aha! App

Once your Aha! account is ready, you need to create an Aha! application. Learn more about creating an Aha! application [here](https://www.aha.io/support/api/authentication).

1. Log in to Your [Aha! Account](https://www.aha.io/).

2. Click the gear icon in the top-right corner and then click **Personal**.

3. On the *Personal* settings page, click **Developer**.

<img alt="Img" />

4. Click the **OAuth applications** tab.

5. Click **Register OAuth application**.

6. On the *Register new OAuth application* form, enter the Oauth application **Name** and the Ampersand **Redirect URI**: `https://api.withampersand.com/callbacks/v1/oauth`

7. Click **Create**.

The OAuth applications tab shows **Client ID** and **Client Secret** keys.

<img alt="Img" />

## Add Aha! App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Aha! App.

   <img alt="Ampersand Project Selection" />

3. Navigate to the **Provider Apps** section.

4. Select **Aha!** from the Provider list.

5. Enter the previously obtained **Client ID / Application ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

<img alt="Img" />

6. Click **Save Changes**

## Using the connector

To start integrating with Aha!:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/aha/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Aircall
Source: https://docs.ampersand.ai/provider-guides/aircall

Register an Aircall OAuth2 app through the Aircall marketplace team, then use Ampersand to read and write calls, users, contacts, numbers, teams, and tags.

## What's Supported

### Supported Actions

This connector supports:

* [Read Action](/read-actions), including full historic backfill. Incremental read is supported for Contact, User, Number, and Call. Note that for Team and Tag, a full read of the Aircall instance will be done for each scheduled read.
* [Write Action](/write-actions).
* [Proxy Action](/proxy-actions), using the base URL `https://api.aircall.io`.

### Supported Objects

The Aircall connector supports writing to and reading from the following objects:

* [Call](https://developer.aircall.io/api-references/#call) (`call`)
* [User](https://developer.aircall.io/api-references/#user) (`user`)
* [Contact](https://developer.aircall.io/api-references/#contact) (`contact`)
* [Number](https://developer.aircall.io/api-references/#number) (`number`)
* [Team](https://developer.aircall.io/api-references/#team) (`team`)
* [Tag](https://developer.aircall.io/api-references/#tag) (`tag`)

## Before You Get Started

To integrate **Aircall** with **Ampersand**, you must register an **Aircall OAuth2** application. To do this, contact `marketplace@aircall.io` and provide the following details:

* **Name** and **Purpose** of your application.
* **Redirect URI** for an HTTPS endpoint that will handle the secure callback. Use the following callback URL for Ampersand integration: `https://api.withampersand.com/callbacks/v1/oauth`.
* **Install URI**: A valid installation URI for your application.

Once you have registered your application, you will receive two credentials: **client\_id** and **client\_secret**. These are required to connect Aircall with Ampersand.

## Add Your Aircall App Info to Ampersand

Once you have your Aircall app set up and registered, you can proceed to connect it with Ampersand by following these steps:

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create an *Aircall* integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Aircall* from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in *Aircall*.

<img alt="Dashboard" />

7. Click **Save Changes**.

## Using the connector

To start integrating with Aircall:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/aircall/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Action](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Action](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Action](/proxy-actions), you can start making Proxy API calls.


# Airtable
Source: https://docs.ampersand.ai/provider-guides/airtable

Register an Airtable OAuth integration in the Builders Hub, add its client ID, secret, and scopes to Ampersand, and make proxy calls to the Airtable API.

## What's Supported

### Supported Actions

This connector supports:

* **Proxy Actions**, using the base URL `https://api.airtable.com`.

## Before You Get Started

To integrate Airtable with Ampersand, you will need an [Airtable](https://airtable.com) Account.

Once your account is created, you'll need to register an OAuth app and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create an Airtable Account

Here's how you can sign up for an Airtable account:

* Go to the [Airtable Site](https://airtable.com/signup) and sign up for a free account.
* Sign up using your preferred method and complete any necessary verification.

### Creating an Airtable OAuth App

Follow the steps below to create an Airtable OAuth app:

1. Login to [Airtable](https://airtable.com/login) using your credentials.

2. Go to the [Airtable's Builders Hub](https://airtable.com/create/oauth).

3. Click on **Register New Oauth Integration**.

4. Enter the following details:

   1. **Name:** Choose a name for your application.
   2. **OAuth Redirect URL:** Enter `https://api.withampersand.com/callbacks/v1/oauth`.
   3. Click on **Register Integration**.

5. You will see the **Client ID** here. Click on **Generate client secret** to generate the client secret. Keep these credentials handy to connect your app to Ampersand later.

6. Select the appropriate scopes for your application.

7. Complete the rest of the setup & click on **Save changes**.

<img alt="Alt text" />

## Add Your Airtable App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create an *Airtable* integration.
3. Select **Provider Apps**.
4. Select *Airtable* from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.
6. Enter the scopes set for your application in *Airtable*.

<img alt="Alt text" />

7. Click **Save Changes**.


# Amplemarket
Source: https://docs.ampersand.ai/provider-guides/amplemarket

Make proxy calls to the Amplemarket API through Ampersand using API key auth, with a sample amp.yaml manifest and a link to create an Amplemarket API key.

## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.amplemarket.com`.

### Example integration

To define an integration for Amplemarket, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: amplemarket-integration
    displayName: My Amplemarket Integration
    provider: amplemarket
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Amplemarket:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.amplemarket.com`.

## Creating an API key for Amplemarket

[Click here](https://docs.amplemarket.com/guides/quickstart) for more information about generating an API key for Amplemarket. The UI components will display this link, so that your users can successfully create API keys.


# Amplitude
Source: https://docs.ampersand.ai/provider-guides/amplitude

Use Basic Auth to connect Amplitude to Ampersand, read cohorts, events, annotations, and taxonomy objects, write attribution and releases, and proxy calls.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Amplitude instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://amplitude.com`.

### Supported Objects

The Amplitude connector supports reading from the following objects:

* [annotations](https://amplitude.com/docs/apis/analytics/chart-annotations#get-all-chart-annotations)
* [cohorts](https://amplitude.com/docs/apis/analytics/behavioral-cohorts#get-all-cohorts)
* [events](https://amplitude.com/docs/apis/analytics/dashboard-rest#get-events-list)
* [lookup\_table](https://amplitude.com/docs/apis/analytics/lookup-table#list-all-lookup-tables)
* [taxonomy/category](https://amplitude.com/docs/apis/analytics/taxonomy#get-all-event-categories)
* [taxonomy/event](https://amplitude.com/docs/apis/analytics/taxonomy#get-all-event-types)
* [taxonomy/event-property](https://amplitude.com/docs/apis/analytics/taxonomy#get-event-properties)
* [taxonomy/user-property](https://amplitude.com/docs/apis/analytics/taxonomy#get-all-user-properties)
* [taxonomy/group-property](https://amplitude.com/docs/apis/analytics/taxonomy#get-group-properties)

The Amplitude connector supports writing to the following objects:

* [attribution](https://amplitude.com/docs/apis/analytics/attribution#send-an-attribution-event)
* [release](https://amplitude.com/docs/apis/analytics/releases#create-a-release)
* [annotations](https://amplitude.com/docs/apis/analytics/chart-annotations#create-an-annotation)

### Example Integration

For an example manifest file of an Amplitude integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/amplitude/amp.yaml).

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Amplitude:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/amplitude/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Anthropic
Source: https://docs.ampersand.ai/provider-guides/anthropic

Proxy requests to the Anthropic API at api.anthropic.com through Ampersand with customer-supplied API keys, including an example manifest and setup steps.

## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.anthropic.com`.

### Example integration

To define an integration for Anthropic, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: anthropic-integration
    displayName: My Anthropic Integration
    provider: anthropic
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Anthropic:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.anthropic.com`.

## Creating an API key for Anthropic

[Click here](https://docs.anthropic.com/en/api/getting-started#authentication) for more information about generating an API key for Anthropic. The UI components will display this link, so that your users can successfully create API keys.


# Apollo
Source: https://docs.ampersand.ai/provider-guides/apollo

Link Apollo to Ampersand via an API key to read and write contacts, accounts, and deals, read sequences and tasks, and set a master key for custom fields.

## What's supported

### Supported actions

The Apollo connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `contacts` and `accounts` only. For all other objects, a full read of the Apollo instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.apollo.io`.

### Supported Objects

The Apollo connector supports reading from the following objects:

* [emailer\_campaigns (sequences)](https://docs.apollo.io/reference/search-for-sequences)
* [accounts](https://docs.apollo.io/reference/search-for-accounts)
* [account\_stages](https://docs.apollo.io/reference/list-account-stages)
* [contacts](https://docs.apollo.io/reference/search-for-contacts)
* [contact\_stages](https://docs.apollo.io/reference/list-contact-stages)
* [opportunities (deals)](https://docs.apollo.io/reference/list-all-deals)
* [opportunity\_stages (deal stages)](https://docs.apollo.io/reference/list-deal-stages)
* [email\_accounts](https://docs.apollo.io/reference/get-a-list-of-email-accounts)
* [labels (lists and tags)](https://docs.apollo.io/reference/get-a-list-of-all-liststags)
* [tasks](https://docs.apollo.io/reference/search-tasks)
* [typed\_custom\_fields (custom fields)](https://docs.apollo.io/reference/get-a-list-of-all-custom-fields)
* [users](https://docs.apollo.io/reference/get-a-list-of-users)

Note: Due to limitations in the Apollo API, Ampersand can read a maximum of 50,000 records each time for **Accounts**, **Contacts**, or **Tasks**.

The Apollo connector supports writing to the following objects:

* [opportunities (deals)](https://docs.apollo.io/reference/list-all-deals)
* [contacts](https://docs.apollo.io/reference/search-for-contacts)
* [accounts](https://docs.apollo.io/reference/search-for-accounts)

### Example integration

For an example manifest file of an Apollo integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/apollo/amp.yaml).

## Before You Get Started

### Creating an API key for Apollo

[Click here](https://docs.apollo.io/docs/create-api-key) for more information about generating an API key for Apollo. The UI components will display this link, so that your users can successfully create API keys.

<Warning>Apollo requires the API key to be set as a master key to discover custom fields on objects. If your users have custom fields defined, ensure the API key is configured as a master key.</Warning>

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Apollo:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/apollo/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Asana
Source: https://docs.ampersand.ai/provider-guides/asana

Create an Asana app with the Ampersand redirect URL to read projects, tags, and users, write tasks, goals, and portfolios, and make proxy calls to Asana.

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Asana instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://app.asana.com/api`.

### Supported Objects

The Asana connector supports writing to and reading from the following objects:

* [access\_requests](https://developers.asana.com/reference/createaccessrequest) (write only)
* [allocations](https://developers.asana.com/reference/createallocation) (write only)
* [custom\_fields](https://developers.asana.com/reference/createcustomfield) (write only)
* [goals](https://developers.asana.com/reference/creategoal) (write only)
* [memberships](https://developers.asana.com/reference/createmembership) (write only)
* [organization\_exports](https://developers.asana.com/reference/createorganizationexport) (write only)
* [portfolios](https://developers.asana.com/reference/createportfolio) (write only)
* [projects](https://developers.asana.com/reference/getprojects) (read and write)
* [status\_updates](https://developers.asana.com/reference/createstatusforobject) (write only)
* [tags](https://developers.asana.com/reference/gettags) (read and write)
* [tasks](https://developers.asana.com/reference/createtask) (write only)
* [teams](https://developers.asana.com/reference/createteam) (write only)
* [users](https://developers.asana.com/reference/getusers) (read only)
* [webhooks](https://developers.asana.com/reference/createwebhook) (write only)
* [workspaces](https://developers.asana.com/reference/getworkspaces) (read only)

<Note>
  When performing Write actions, the payload should be sent directly in the `record` field, not wrapped inside a `data` object as shown in Asana's API documentation.
</Note>

## Before You Get Started

To integrate Asana with Ampersand, you will need [an Asana Account](https://asana.com/create-account).

Once your account is created, you'll need to create an app in Asana, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create an Asana Account

Here's how you can sign up for an Asana account:

* Go to the [Asana Sign Up page](https://asana.com/create-account).
* Sign up using your preferred method.

### Creating an Asana App

Follow the steps below to create an Asana app and add

1. Log in to your [Asana](https://app.asana.com/-/login?_gl=1*6sugw2*_gcl_au*MTkwOTM5OTQ5Ny4xNzE0MDIwNjA3*FPAU*MTkwOTM5OTQ5Ny4xNzE0MDIwNjA3*_ga*MzkyNTg3NTguMTcxNDAyMDYwNw..*_ga_J1KDXMCQTH*MTcxOTMyNzI3NS41LjEuMTcxOTMyNzMwNS4zMy4wLjE1MzI1OTc1NTI.*_fplc*STdUUVd6UFZ4Q0ttJTJGNU5sYnhxQXVDeENYcGtVdFZsT1M5MGVROTIxY0RBUWlaU0lObkxKMUpaM0JmZGxQeGpMRkhzb0NqYTNaVHU2RUxOcFFCMnZzVXEzNFg5aVI4N3RYZ0s2eHBnWGwzdEdtTmZBc25xNUY2NzM2MjBvcVElM0QlM0Q.) account.

2. Navigate to the [Asana Developer App Console](https://app.asana.com/0/my-apps).

3. Click **Create New App** to create a new app.

4. Enter **App Name** and select the relevant app requirements.

   <img alt="Alt text" />

<br />

### Adding Ampersand Redirect URL in Your App

1. Navigate to the **OAuth** section.
2. In the **Redirect URLs** section, click **Add redirect URL**.
3. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
4. Click **Add**.

<img alt="Alt text" />

The **Basic information** section displays **Client ID** and **Client Secret** keys for your App. You'll use these credentials to connect your app to [Ampersand](/provider-guides/asana#add-your-asana-app-info-to-ampersand).

## Add Your Asana App info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create an Asana integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Asana* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save changes**.


# Ashby
Source: https://docs.ampersand.ai/provider-guides/ashby

Connect Ashby to Ampersand with Basic Auth to read and write applications, candidates, jobs, and offers, with incremental reads for select objects.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `application`, `applicationFeedback` and `interviewSchedule` currently. For all other objects, a full read of the Ashby instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.ashbyhq.com`.

### Supported Objects

The Ashby connector supports writing to and reading from the following objects:

* [application](https://developers.ashbyhq.com/reference/applicationlist) (read, write),
* [applicationFeedback](https://developers.ashbyhq.com/reference/applicationfeedbacklist) (read),
* [applicationHiringTeamRole](https://developers.ashbyhq.com/reference/applicationhiringteamrolelist) (read)
* [archiveReason](https://developers.ashbyhq.com/reference/archivereasonlist) (read)
* [assessment](https://developers.ashbyhq.com/reference/assessmentlist) (read),
* [candidate](https://developers.ashbyhq.com/reference/candidatelist) (read, write),
* [candidateTag](https://developers.ashbyhq.com/reference/candidatetaglist) (read, write),
* [communicationTemplate](https://developers.ashbyhq.com/reference/communicationtemplatelist) (read)
* [customField](https://developers.ashbyhq.com/reference/customfieldlist) (read, write),
* [department](https://developers.ashbyhq.com/reference/departmentlist) (read, write),
* [feedbackFormDefinition](https://developers.ashbyhq.com/reference/feedbackformdefinitionlist) (read)
* [interview](https://developers.ashbyhq.com/reference/interviewlist) (read)
* [interviewPlan](https://developers.ashbyhq.com/reference/interviewplanlist) (read)
* [interviewSchedule](https://developers.ashbyhq.com/reference/interviewschedulelist) (read, write),
* [interviewStageGroup](https://developers.ashbyhq.com/reference/interviewstagegrouplist) (read)
* [interviewerPool](https://developers.ashbyhq.com/reference/interviewerpoollist) (read, write),
* [job](https://developers.ashbyhq.com/reference/joblist) (read, write),
* [jobBoard](https://developers.ashbyhq.com/reference/jobboardlist) (read)
* [jobPosting](https://developers.ashbyhq.com/reference/jobpostinglist) (read),
* [jobTemplate](https://developers.ashbyhq.com/reference/jobtemplatelist) (read)
* [location](https://developers.ashbyhq.com/reference/locationlist) (read, write),
* [offer](https://developers.ashbyhq.com/reference/offerlist) (read, write),
* [opening](https://developers.ashbyhq.com/reference/openinglist) (read, write),
* [project](https://developers.ashbyhq.com/reference/projectlist) (read)
* [referral](https://developers.ashbyhq.com/reference/referralcreate) (write)
* [source](https://developers.ashbyhq.com/reference/sourcelist) (read)
* [sourceTrackingLink](https://developers.ashbyhq.com/reference/sourcetrackinglinklist) (read)
* [surveyFormDefinition](https://developers.ashbyhq.com/reference/surveyformdefinitionlist) (read)
* [surveyRequest](https://developers.ashbyhq.com/reference/surveyrequestcreate) (write)
* [surveySubmission](https://developers.ashbyhq.com/reference/surveysubmissioncreate) (write)
* [user](https://developers.ashbyhq.com/reference/userlist) (read)
* [webhook](https://developers.ashbyhq.com/reference/webhookcreate) (write)

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Ashby:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/ashby/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Atlassian
Source: https://docs.ampersand.ai/provider-guides/atlassian

Integrate Atlassian Jira with Ampersand to read and write Issues, with steps to create an OAuth 2.0 app, add scopes, and set the redirect URL.

## What's Supported

### Supported Actions

For Jira, the following is supported:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.atlassian.com`.

### Supported Objects

The Atlassian connector supports writing to and reading from Jira **Issues**.

### Example Integration

For an example manifest file of a Jira integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/jira/amp.yaml).

## Before You Get Started

To integrate Atlassian Jira with Ampersand, you will need [an Atlassian Account](https://id.atlassian.com/signup).

Once your account is created, you'll need to create an app in Atlassian, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials and scopes to connect your application to Ampersand.

### Create an Atlassian Account

Here's how you can sign up for an Atlassian account:

* Go to the [Atlassian Sign Up page](https://www.atlassian.com/try/cloud/signup?bundle=jira-software\&edition=free\&skipBundles=true) and create an account.
* Sign up using your preferred method.

### Creating an Atlassian App

Follow the steps below to create an *Atlassian* app:

1. Go to the [Atlassian Developer Console My Apps Page](https://developer.atlassian.com/console/myapps/).
2. Click the **Create** dropdown to create a new app.
3. Select **Oauth 2.0 integration**.
4. Enter the **App Name**.
5. Select the **I agree to be bound by Atlassian's developer terms.** checkbox.
6. Click **Create**.

   <br />

   <img alt="Alt text" />

### Adding Scopes in your Atlassian App

You need to define the necessary permissions for your Atlassian app by selecting and adding required scopes, to allow Ampersand to access data effectively. You can limit the access to only the specific scopes needed for your application.

Follow the steps below to add scopes to your Atlassian App:

1. In the [Atlassian Developer Console My Apps Page](https://developer.atlassian.com/console/myapps/), select your app.
2. Go to **Permissions**.
3. Select the scopes for your application. Atlassian will authorize access to the selected scopes for your application.

<img alt="Alt text" />

For more information on the scopes, go to [Scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/) section in the Atlassian documentation.

### Adding Ampersand Redirect URL in Your App

Follow the steps below to add the Ampersand redirect URL in your Atlassian app:

1. In the [Atlassian Developer Console My Apps Page](https://developer.atlassian.com/console/myapps/), select your app.
2. Go to **Authorization**.
3. Next to **OAuth 2.0 (3LO)**, click **Add**.
4. Enter the Ampersand **Callback URL**: `https://api.withampersand.com/callbacks/v1/oauth`.
5. Click **Save changes**.

<img alt="Alt text" />

You'll find the **Client ID** and **Client Secret** keys for your app in the **Settings** section.

<img alt="Alt text" />

You'll use these credentials while connecting your app to Ampersand.

## Add Your Atlassian App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create an Atlassian integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Atlassian* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Enter the scopes set for your application in *Atlassian*. In addition to the scopes you configured, **you must add the `offline_access` scope.**

7. Click **Save changes**.

## Using the connector

To start integrating with Atlassian:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/jira/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Attio
Source: https://docs.ampersand.ai/provider-guides/attio

Connect Attio to Ampersand to read, write, and subscribe to People, Companies, Deals, Notes, and Tasks, and create an Attio OAuth app with scopes.

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Subscribe Actions](/subscribe-actions). Ampersand creates and manages the Attio webhook subscription on your behalf when the customer installs your integration — no manual webhook setup is required in the Attio UI.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.attio.com`.

### Supported Objects

The Attio connector supports the following objects:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

\* WorkspaceMembers only supports **create** events for subscriptions.

### Subscribe events

Attio uses two subscription patterns depending on the object:

* **Standard and custom objects** (People, Companies, Users, Deals, Workspaces, and any custom object) are subscribed through Attio's generic record events (`record.created`, `record.updated`, `record.deleted`), scoped to the specific object. They support **create**, **update**, and **delete** events.
* **Core objects** are subscribed through object-specific events: **Notes**, **Tasks**, and **Lists** support **create**, **update**, and **delete**; **WorkspaceMembers** supports **create** only. Note that **Lists** events fire on the list object itself (a list being created, updated, or deleted) — not on records being added to or removed from a list.

Please note that:

* **Standard objects must be activated.** Attio delivers `record.*` events only for objects that are active in the workspace. People, Companies, and Deals are active by default; Users and Workspaces are optional standard objects that must be enabled under **Workspace settings → Objects** before they can be subscribed to.
* **Watched fields are not supported.** Attio webhook payloads do not include changed-field data, so field-level update filtering (`requiredWatchFields`) is not available. Use `watchFieldsAuto: all` for update events — they fire on any change to the record, and Ampersand fetches the full updated record for you.
* **Scopes gate webhook creation and delivery.** Your Attio app must be granted **read-write access to the Webhooks scope** (to create the subscription) and **read access to record objects** (so Ampersand can fetch the changed record). Grant these under **Workspace settings → Developers → \[your app] → Scopes**; without them, subscription creation fails with a `403`.

For example:

```yaml theme={"dark"}
subscribe:
  objects:
    - objectName: people
      destination: attioWebhook
      inheritFieldsAndMapping: true
      createEvent:
        enabled: always
      updateEvent:
        enabled: always
        watchFieldsAuto: all
      deleteEvent:
        enabled: always
    - objectName: notes
      destination: attioWebhook
      inheritFieldsAndMapping: true
      createEvent:
        enabled: always
```

### Example integration

For an example manifest file of an Attio integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/attio/amp.yaml).

## Before You Get Started

To connect Attio with Ampersand, you will need [an Attio Account](https://app.attio.com/auth/sign-in).

Once your account is created, you'll need to create an app in Attio and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create an Attio Account

Here's how you can sign up for an Attio account:

* Go to the [Attio Sign Up page](https://app.attio.com/auth/sign-in).
* Sign up using your preferred method.

### Creating an Attio App

Follow the steps below to create an Attio app and add the Ampersand redirect URL.

1. Log in to your [Attio](https://build.attio.com/auth/login) account.

2. Click on **New app** to open the **New app** dialog.

3. Enter a name for the application in the **name** section and click **Create app**.

4. Navigate to the **OAuth** section and enable **OAuth** switch to view the Client ID and Client Secret.

5. In the **Redirect URIs** section, click **New redirect URI**, add the Ampersand Redirect URI: `https://api.withampersand.com/callbacks/v1/oauth`.

6. Click **Configure scopes**, enable the necessary scopes, and click Save changes.

<img alt="Attio App Creation" />

## Add Your Attio App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create an Attio integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Attio* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Ampersand Integration" />

6. Click **Save Changes**.

## Using the connector

To start integrating with Attio:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/attio/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions or Subscribe Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Avoma
Source: https://docs.ampersand.ai/provider-guides/avoma

Use API key auth to connect Avoma to Ampersand, reading meetings, calls, notes, and transcriptions, writing calls and templates, and proxy calls.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.avoma.com`.

### Supported Objects

The Avoma connector supports reading from the following objects:

* [calls](https://dev694.avoma.com/#tag/Calls/paths/~1v1~1calls~1/get)
* [custom\_categories](https://dev694.avoma.com/#tag/Custom-Category/paths/~1v1~1custom_categories~1/get)
* [meetings](https://dev694.avoma.com/#tag/Meetings/paths/~1v1~1meetings~1/get)
* [notes](https://dev694.avoma.com/#tag/Notes/paths/~1v1~1notes~1/get)
* [scorecard\_evaluations](https://dev694.avoma.com/#tag/Scorecard-Evaluations/operation/scorecard_evaluations_list)
* [scorecards](https://dev694.avoma.com/#tag/Scorecards/operation/scorecards_list)
* [smart\_categories](https://dev694.avoma.com/#tag/Smart-Category/paths/~1v1~1smart_categories~1/get)
* [transcriptions](https://dev694.avoma.com/#tag/Transcriptions/paths/~1v1~1transcriptions~1/get)
* [template](https://dev694.avoma.com/#tag/Templates/paths/~1v1~1template~1/get)
* [users](https://dev694.avoma.com/#tag/Users/paths/~1v1~1users~1/get)

The Avoma connector supports writing to the following objects:

* [calls](https://dev694.avoma.com/#tag/Calls/operation/createExtCall)
* [smart\_categories](https://dev694.avoma.com/#tag/Smart-Category/paths/~1v1~1smart_categories~1/post)
* [template](https://dev694.avoma.com/#tag/Templates/paths/~1v1~1template~1/post)

### Example integration

For an example manifest file of an Avoma integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/avoma/amp.yaml).

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with Avoma:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Avoma

See the [Avoma documentation](https://help.avoma.com/api-integration-for-avoma) for instructions on how to create an API key.


# AWeber
Source: https://docs.ampersand.ai/provider-guides/aweber

Set up the AWeber connector for Proxy Actions by creating an AWeber app with an OAuth2 redirect URL and adding its Client ID and Secret to Ampersand.

## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.aweber.com`.

### Example integration

To define an integration for AWeber, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: aweber-integration
    displayName: My AWeber Integration
    provider: aWeber
    proxy:
      enabled: true
```

## Before You Get Started

To connect *AWeber* with *Ampersand*, you will need [an AWeber Account](https://labs.aweber.com/).

Once your account is created, you'll need to configure an app in *AWeber* and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will use these credentials to connect your application to Ampersand.

### Create an AWeber Account

Here's how you can sign up for an **AWeber Developer** account:

* Go to the [AWeber Sign Up page](https://www.aweber.com/create-account.htm) and create an account.

### Creating an AWeber App

Follow the steps below to create an *AWeber* app and add the Ampersand redirect URL in the app:

1. Log in to your [AWeber Developer Account](https://labs.aweber.com/).

2. Click **Create A New App**.

3. Enter the **Application Name**, **Author** details, and **Application Website**.

4. In the **OAuth2 Redirect URL** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

5. Enter application **Description**.

   <img alt="AWeber App Creation" />

6. Click **Create New App**.

You'll see the details of your newly created application. Note the **Client ID** and **Client Secret** keys as they are necessary for connecting your app to Ampersand.

<img alt="AWeber App Credentials" />

## Add Your AWeber App Info to Ampersand

1. Log in to your [Ampersand Console](https://console.withampersand.com).

2. Select the project where you want to create an AWeber integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider apps**.

4. Select *AWeber* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Enter the scopes set for your application in *AWeber*.

   <img alt="AWeber Integration in Ampersand" />

7. Click **Save changes**.

## Using the connector

To start integrating with AWeber:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# AWS
Source: https://docs.ampersand.ai/provider-guides/aws

Read and write AWS IAM Identity Center objects like Users, Groups, Applications, and PermissionSets, using an Access Key ID and Secret for Basic Auth.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the AWS instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), unsupported.

### Supported Objects

The AWS connector supports reading and writing to and from the following objects:

* [AccountAssignmentCreationStatus](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/list-account-assignment-creation-status.html) (read)
* [AccountAssignmentDeletionStatus](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/list-account-assignment-deletion-status.html) (read)
* [ApplicationProviders](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/list-application-providers.html) (read)
* [Applications](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/list-applications.html) (read/create/update/delete)
* [Groups](https://docs.aws.amazon.com/cli/latest/reference/identitystore/list-groups.html) (read/create/update/delete)
* [Instances](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/list-instances.html) (read/create/update/delete)
* [PermissionSetProvisioningStatus](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/list-permission-set-provisioning-status.html) (read)
* [TrustedTokenIssuers](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/list-trusted-token-issuers.html) (read/create/update/delete)
* [Users](https://docs.aws.amazon.com/cli/latest/reference/identitystore/list-users.html) (read/create/update/delete)

Objects without read capability:

* [AccountAssignments](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/create-account-assignment.html) (create)
* [ApplicationAccessScopes](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/put-application-access-scope.html) (update)
* [ApplicationAssignmentConfigurations](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/put-application-assignment-configuration.html) (update)
* [ApplicationAssignments](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/create-application-assignment.html) (create)
* [ApplicationAuthenticationMethods](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/put-application-authentication-method.html) (update)
* [ApplicationGrants](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/put-application-grant.html) (update)
* [GroupMemberships](https://docs.aws.amazon.com/cli/latest/reference/identitystore/create-group-membership.html) (create/delete)
* [InstanceAccessControlAttributeConfigurations](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/create-instance-access-control-attribute-configuration.html) (create/delete)
* [PermissionSets](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/create-permission-set.html) (create/update/delete)

## Using the connector

This connector uses **Basic Auth**:

* **Username** = AWS Access Key ID
* **Password** = AWS Access Key Secret

### Obtain Access Key ID and Secret

Follow instructions to [get your AWS access keys](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/getting-started.html#get-your-aws-access-keys).

### Obtain connector metadata

To initialize the connector, you need:

* AWS region
* Identity Store ID
* Instance ARN
  To find these, open AWS dashboard, search for **IAM Identity Center** service, then open the **Settings** tab.


# Basecamp
Source: https://docs.ampersand.ai/provider-guides/basecamp

Use the Basecamp connector for Proxy Actions only, registering an OAuth app in 37signals Launchpad and collecting the customer Basecamp account ID.

## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://3.basecampapi.com/{{.workspace}}`.

### Supported objects

Basecamp is supported through Proxy Actions only. Use the proxy to call any [Basecamp API](https://github.com/basecamp/bc3-api) endpoint, for example `GET /projects.json`.

### Example integration

To define an integration for Basecamp, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: basecampIntegration
    displayName: My Basecamp Integration
    provider: basecamp
    proxy:
      enabled: true
```

## Before you get started

To integrate Basecamp with Ampersand, you will need a [Basecamp account](https://basecamp.com/).

Once your account is created, you'll need to create a Basecamp app and obtain the following credentials from it:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

Every Basecamp API endpoint is prefixed with an account ID, which is the `{{.workspace}}` token in the base URL. Your customers find their account ID in their Basecamp URL: for example, if the URL is `https://app.basecamp.com/6258233/projects`, the account ID is `6258233`. Ampersand prompts your customers for this value when they install the integration.

### Creating a Basecamp app

1. Log in to the [37signals Launchpad integrations page](https://launchpad.37signals.com/integrations).
2. Click **Register another application**.
3. Enter a **Name**, **Company**, and **Website URL** for your app.
4. Set the **Redirect URI** to: `https://api.withampersand.com/callbacks/v1/oauth`
5. Under **Products**, select **Basecamp** (the current version, not Basecamp 2 or Basecamp Classic).
6. Click **Register this app**.
7. Open the app you registered and copy the **Client ID** and **Client Secret**.

Learn more about Basecamp OAuth apps in the [Basecamp API authentication guide](https://github.com/basecamp/api/blob/master/sections/authentication.md).

### Add your Basecamp app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Basecamp integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Basecamp** from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from your Basecamp app.

6. Click **Save Changes**.

## Using the connector

To start integrating with Basecamp:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization and their Basecamp account ID.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically handle the authentication with Basecamp.


# Bentley
Source: https://docs.ampersand.ai/provider-guides/bentley

Connect Bentley to Ampersand to read and write iTwins, library, and reality analysis objects, write savedviews, and register a Bentley web app for OAuth.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental reading is only supported for `contextcapture/jobs`, `reality-analysis/jobs`, and `realityconversion/jobs`. For all other objects, a full read of the Bentley instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.bentley.com`.

### Supported objects

The Bentley connector supports reading from the following objects:

* [contextcapture/jobs](https://developer.bentley.com/apis/contextcapture/operations/jobs-get-all/) (incremental read)
* [curated-content/cesium](https://developer.bentley.com/apis/cesium-curated-content/operations/list-content/)
* [edfs/packages](https://developer.bentley.com/apis/edfs/operations/subscribed-packages-get/)
* [itwins](https://developer.bentley.com/apis/itwins/operations/get-my-itwins/)
* [itwins/exports](https://developer.bentley.com/apis/itwins/operations/get-my-exports/)
* [itwins/favorites](https://developer.bentley.com/apis/itwins/operations/get-my-favorite-itwins/)
* [itwins/recents](https://developer.bentley.com/apis/itwins/operations/get-my-recently-used-itwins/)
* [library/applications](https://developer.bentley.com/apis/library/operations/get-applications/)
* [library/brands](https://developer.bentley.com/apis/library/operations/get-brands/)
* [library/catalogs](https://developer.bentley.com/apis/library/operations/get-catalogs/)
* [library/categories](https://developer.bentley.com/apis/library/operations/get-categories/)
* [library/components](https://developer.bentley.com/apis/library/operations/get-components/)
* [library/manufacturers](https://developer.bentley.com/apis/library/operations/get-manufacturers/)
* [reality-analysis/detectors](https://developer.bentley.com/apis/reality-analysis/operations/detectors-get-all/)
* [reality-analysis/files](https://developer.bentley.com/apis/reality-analysis/operations/files-get-all/)
* [reality-analysis/jobs](https://developer.bentley.com/apis/reality-analysis/operations/jobs-get-all/) (incremental read)
* [reality-management/reality-data](https://developer.bentley.com/apis/reality-management/operations/get-all-reality-data/)
* [realityconversion/jobs](https://developer.bentley.com/apis/realityconversion/operations/jobs-get-all/) (incremental read)
* [webhooks](https://developer.bentley.com/apis/webhooks-v2/operations/get-webhooks/)

The Bentley connector supports writing to the following objects:

* [contextcapture/jobs](https://developer.bentley.com/apis/contextcapture/operations/jobs-create/)
* [contextcapture/workspaces](https://developer.bentley.com/apis/contextcapture/operations/workspaces-create/)
* [itwins](https://developer.bentley.com/apis/itwins/operations/create-itwin/)
* [itwins/exports](https://developer.bentley.com/apis/itwins/operations/create-export/)
* [grouping-and-mapping/datasources/imodel-mappings](https://developer.bentley.com/apis/grouping-and-mapping/operations/create-mapping/)
* [imodels](https://developer.bentley.com/apis/imodels-v2/operations/update-imodel/)
* [library/applications](https://developer.bentley.com/apis/library/operations/create-application/)
* [library/catalogs](https://developer.bentley.com/apis/library/operations/create-catalog/)
* [library/categories](https://developer.bentley.com/apis/library/operations/create-category/)
* [library/components](https://developer.bentley.com/apis/library/operations/create-component/)
* [library/manufacturers](https://developer.bentley.com/apis/library/operations/create-manufacturer/)
* [named-groups](https://developer.bentley.com/apis/named-groups/operations/create-group/)
* [savedviews/groups](https://developer.bentley.com/apis/savedviews/operations/create-group/)
* [savedviews](https://developer.bentley.com/apis/savedviews/operations/create-savedview/)
* [savedviews/tags](https://developer.bentley.com/apis/savedviews/operations/create-tag/)
* [schedules](https://developer.bentley.com/apis/schedules/operations/post-schedule/)
* [reality-management/reality-data](https://developer.bentley.com/apis/reality-management/operations/create-reality-data/)
* [reality-analysis/detectors](https://developer.bentley.com/apis/reality-analysis/operations/detectors-create/)
* [reality-analysis/jobs](https://developer.bentley.com/apis/reality-analysis/operations/jobs-create/)
* [realityconversion/jobs](https://developer.bentley.com/apis/realityconversion/operations/jobs-create/)
* [insights/reporting/reports](https://developer.bentley.com/apis/insights/operations/create-report/)
* [insights/carbon-calculation/ec3/configurations](https://developer.bentley.com/apis/carbon-calculation/operations/create-ec3-configuration/)
* [insights/carbon-calculation/ec3/jobs](https://developer.bentley.com/apis/carbon-calculation/operations/create-ec3-job/)
* [insights/carbon-calculation/oneclicklca/jobs](https://developer.bentley.com/apis/carbon-calculation/operations/create-oneclicklca-job/)
* [changedelements/comparisonjob](https://developer.bentley.com/apis/changed-elements-v2/operations/create-comparison-job/)
* [forms](https://developer.bentley.com/apis/forms-v2/operations/create-form-data/)
* [export/connections](https://developer.bentley.com/apis/export/operations/create-export-connection/)
* [synchronization/imodels/manifestconnections](https://developer.bentley.com/apis/synchronization/operations/create-manifest-connection/)
* [synchronization/pnidtoitwin/inferences](https://developer.bentley.com/apis/pnid-to-itwin-v2/operations/create-inference/)
* [synchronization/imodels/storageconnections](https://developer.bentley.com/apis/synchronization/operations/create-storage-connection/)
* [transformations](https://developer.bentley.com/apis/transformations/operations/create-transformation/)
* [transformations/configurations/createfork](https://developer.bentley.com/apis/transformations/operations/createfork/)
* [mesh-export](https://developer.bentley.com/apis/mesh-export/operations/start-export/)
* [webhooks](https://developer.bentley.com/apis/webhooks-v2/operations/create-webhook/)

### Example integration

For an example manifest file of a Bentley integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/bentley/amp.yaml).

## Before you get started

To connect Bentley with Ampersand, you will need [a Bentley Account](https://developer.bentley.com).

Once your account is created, you'll need to register an application in the Bentley developer portal and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Creating a Bentley app

1. Log in to the [Bentley Developer Portal](https://developer.bentley.com).

2. Navigate to **[My Apps](https://developer.bentley.com/my-apps/)** and click **Register New**.

3. Enter the following details for your application:
   * **Application Name**: The name of your app.
   * **Application Type**: Select **Web App** (for Authorization Code grant).

4. Under **Redirect URIs**, add: `https://api.withampersand.com/callbacks/v1/oauth`

5. Select the scopes required for your integration.

6. Click **Register**. Note the **Client ID** and **Client Secret**. You will need these to connect your app to Ampersand.

<img alt="Bentley App Creation" />

### Add your Bentley app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Bentley integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Bentley** from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from your Bentley app.

6. Enter the scopes configured for your application in Bentley.

   <img alt="Ampersand Integration" />

7. Click **Save Changes**.

## Using the connector

To start integrating with Bentley:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# BigQuery
Source: https://docs.ampersand.ai/provider-guides/bigquery

Read any BigQuery table in a dataset with incremental reads using a service account key, plus field limits, timestamp column needs, and proxy calls.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://bigquery.googleapis.com`.

### Supported objects

The BigQuery connector can read from any table in the specified dataset. Tables are referenced by name in the `objectName` field of your manifest (e.g., `my_table`).

For each table, the connector supports:

* All columns, subject to the [field limit](#limits) per read operation.
* Standard BigQuery types: STRING, INT64, FLOAT64, BOOL, TIMESTAMP, DATE, BYTES, NUMERIC, RECORD, and more.

### Limits

* **Maximum fields per read**: 7. BigQuery is a columnar store, so reading additional columns is significantly more expensive.
* **Default page size**: 50,000 rows per page.
* **Timestamp column required**: Every table you read must have a `TIMESTAMP` or `DATETIME` column for incremental reads and backfill windowing.

### Example integration

To define an integration for BigQuery, create a manifest file that looks like this:

```yaml theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: bigquery-integration
    displayName: My BigQuery Integration
    provider: bigquery
    read:
      objects:
        - objectName: my_table
          requiredFields:
            - fieldName: name
            - fieldName: billingcity
              mapToName: city
              mapToDisplayName: City
            - mapToName: country
              mapToDisplayName: Country
              prompt: Which field is the country for the account?
          destination: myWebhook
```

## Using the connector

This connector uses a service account key for authentication, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with BigQuery:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their service account key, GCP project ID, dataset name, and timestamp column.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls. Please note that this connector's base URL is `https://bigquery.googleapis.com`.

## Customer guide

The [BigQuery customer guide](/customer-guides/bigquery) is a guide that can be shared with your customers to help them set up a service account and provide the required credentials.


# Bird (MessageBird)
Source: https://docs.ampersand.ai/provider-guides/bird

Connect Bird (MessageBird) to Ampersand with API key auth and make proxy calls to api.bird.com using a manifest, the amp CLI, and InstallIntegration UI.

## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.bird.com`.

### Example integration

To define an integration for Bird (MessageBird), create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: bird-integration
    displayName: My Bird (MessageBird) Integration
    provider: bird
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Bird (MessageBird):

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.bird.com`.

## Creating an API key for Bird (MessageBird)

[Click here](https://docs.bird.com/api) for more information about generating an API key for Bird (MessageBird). The UI components will display this link, so that your users can successfully create API keys.


# Bitbucket
Source: https://docs.ampersand.ai/provider-guides/bitbucket

Integrate Bitbucket with Ampersand to read repositories, projects, hooks, and members, write snippets and projects, and register an OAuth consumer.

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `repositories` only. For all other objects, a full read of the Bitbucket instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.bitbucket.org`.

### Supported Objects

The Bitbucket connector supports reading from the following objects:

* [addon/linkers](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-addon/#api-addon-linkers-get)
* [pipelines-config/variables](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines/#api-workspaces-workspace-pipelines-config-variables-get)
* [repositories](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-get)
* [user/emails](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-users/#api-user-emails-get)
* [hook\_events](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-webhooks/#api-hook-events-get)
* [hooks](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-workspaces/#api-workspaces-workspace-hooks-get)
* [members](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-workspaces/#api-workspaces-workspace-members-get)
* [projects](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-workspaces/#api-workspaces-workspace-projects-get)

The Bitbucket connector supports writing to the following objects:

* [pipelines-config/variables](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines/#api-workspaces-workspace-pipelines-config-variables-post)

* [projects](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-projects/#api-workspaces-workspace-projects-post)

* [snippets](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-snippets/#api-snippets-post)

* [hooks](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-workspaces/#api-workspaces-workspace-hooks-post)

### Example integration

For an example manifest file of a Bitbucket integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/bitbucket/amp.yaml).

## Before You Get Started

To connect Bitbucket with Ampersand, you will need [a Bitbucket/Atlassian Account](https://bitbucket.org/).

Once your account is created, you'll need to create an OAuth consumer in your bitbucket workspace, configure the app, and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Bitbucket Account

Follow these steps to sign up for a Bitbucket account:

* Go to the [Atlassian website](https://id.atlassian.com/login?application=bitbucket) and sign up for a new account.

### Register a Bitbucket OAuth App

Follow the steps below to register a Bitbucket OAuth app:

1. Log in to your [Bitbucket account](https://id.atlassian.com/login?application=bitbucket).
2. Go to **Workspace Settings** by clicking the gear icon in the top-right navigation bar.
3. Select **OAuth consumers** from the left sidebar then click **Add consumer**.
4. Enter the following details in the create application form:
   1. **Name**: Enter a name for your app.
   2. **Description**: Provide a brief description of your app.
   3. **Callback URL**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
5. Select the permissions you want to grant to your app.
6. Click **Save**.
   <img alt="Bitbucket Oauth creation" />

Once your app is created, you can access the **Client ID** and **Client Secret** credentials. Note these down, as you will need them to connect your app to Ampersand.

<img alt="Bitbucket Oauth secrets" />

## Add Your Bitbucket App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a Bitbucket integration.\\
   <img alt="Ampersand Project Selection" />
3. Select **Provider Apps**.
4. Select **Bitbucket** from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

   <br />

   <img alt="Ampersand Project Selection" />
6. Click **Save Changes**.


# Blackbaud
Source: https://docs.ampersand.ai/provider-guides/blackbaud

Connect Blackbaud to Ampersand via the SKY API to read and write events and registrants, write constituents and batches, and create a Blackbaud OAuth app.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions). Please note pagination is not supported because the functionality of getting the next page is missed by the blackbaud engineering team. The team has acknowledged this gap and plans to address it in a future service pack release.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL [https://api.sky.blackbaud.com](https://api.sky.blackbaud.com).

### Supported Objects

The Blackbaud connector supports writing to and reading from the following objects:

* [crm-adnmg/batches](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=CreateBatch) (write)
* [crm-adnmg/batches/revenue](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=CreateRevenueBatchRow) (write)
* [crm-adnmg/batchtemplates](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=ListBatchTemplates) (read)
* [crm-adnmg/businessprocess/launch](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=LaunchBusinessProcess) (write)
* [crm-adnmg/businessprocessinstances](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=ListBusinessProcessInstances) (read)
* [crm-adnmg/businessprocessparameterset](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=SearchBusinessProcessParameters) (read)
* [crm-adnmg/businessprocessstatus](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=ListBusinessProcessStatuses) (read)
* [crm-adnmg/currencies](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=ListCurrencies) (read)
* [crm-adnmg/notifications](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=CreateNotification) (write)
* [crm-adnmg/sites](https://developer.sky.blackbaud.com/api#api=crm-adnmg\&operation=SearchSites) (read)
* [crm-conmg/addresses](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentAddress) (write)
* [crm-conmg/alternatelookupids](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentAlternateLookupId) (write)
* [crm-conmg/constituentappeals](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentAppeal) (write)
* [crm-conmg/constituentappealresponses](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentAppealResponse) (write)
* [crm-conmg/constituentattributes](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentAttribute) (write)
* [crm-conmg/constituentcorrespondencecode](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentCorrespondenceCode) (write)
* [crm-conmg/constituentnotes](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentNote) (write)
* [crm-conmg/constituents](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituent) (write)
* [crm-conmg/educationalhistories](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateEducation) (write)
* [crm-conmg/emailaddresses](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentEmailAddress) (write)
* [crm-conmg/fundraisers](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentFundraiser) (write)
* [crm-conmg/individuals](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateIndividual) (write)
* [crm-conmg/interaction](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentInteraction) (write)
* [crm-conmg/mergetwoconstituents](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateMergeTwoConstituents) (write)
* [crm-conmg/organizations](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateOrganization) (write)
* [crm-conmg/phones](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentPhone) (write)
* [crm-conmg/relationshipjobsinfo](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateRelationshipJobInfo) (write)
* [crm-conmg/solicitcodes](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateConstituentSolicitCode) (write)
* [crm-conmg/tribute](https://developer.sky.blackbaud.com/api#api=crm-conmg\&operation=CreateTribute) (write)
* [crm-evtmg/events](https://developer.sky.blackbaud.com/api#api=crm-evtmg\&operation=SearchEvents) (read, write)
* [crm-evtmg/locations](https://developer.sky.blackbaud.com/api#api=crm-evtmg\&operation=LocationSearch) (read, write)
* [crm-evtmg/registrants](https://developer.sky.blackbaud.com/api#api=crm-evtmg\&operation=SearchEventRegistrants) (read, write)
* [crm-evtmg/registrationoptions](https://developer.sky.blackbaud.com/api#api=crm-evtmg\&operation=CreateEventRegistrationOption) (write)
* [crm-evtmg/registrationtypes](https://developer.sky.blackbaud.com/api#api=crm-evtmg\&operation=SearchEventRegistrationTypes) (read, write)
* [crm-fndmg/designations/hierarchies](https://developer.sky.blackbaud.com/api#api=crm-fndmg\&operation=ListDesignationHierarchies) (read)
* [crm-fndmg/educationalhistory](https://developer.sky.blackbaud.com/api#api=crm-fndmg\&operation=SearchEducationalHistories) (read)
* [crm-fndmg/fundraisingpurposes](https://developer.sky.blackbaud.com/api#api=crm-fndmg\&operation=SearchFundraisingPurposes) (read, write)
* [crm-fndmg/fundraisingpurposerecipients](https://developer.sky.blackbaud.com/api#api=crm-fndmg\&operation=SearchFundraisingPurposeRecipients) (read, write)
* [crm-fndmg/fundraisingpurposetypes](https://developer.sky.blackbaud.com/api#api=crm-fndmg\&operation=ListFundraisingPurposeTypes) (read)
* [crm-mktmg/appeals](https://developer.sky.blackbaud.com/api#api=crm-mktmg\&operation=SearchMarketingAppeals) (read, write)
* [crm-mktmg/correspondencecodes](https://developer.sky.blackbaud.com/api#api=crm-mktmg\&operation=ListCorrespondenceCodes) (read, write)
* [crm-mktmg/responsecategories](https://developer.sky.blackbaud.com/api#api=crm-mktmg\&operation=CreateResponseCategory) (write)
* [crm-mktmg/segments](https://developer.sky.blackbaud.com/api#api=crm-mktmg\&operation=CreateMarketingSegment) (write)
* [crm-mktmg/segments/recordsources](https://developer.sky.blackbaud.com/api#api=crm-mktmg\&operation=ListMarketingSegments) (read)
* [crm-mktmg/solicitcodes](https://developer.sky.blackbaud.com/api#api=crm-mktmg\&operation=ListMarketingSolicitCodes) (read)
* [crm-prsmg/prospectcontactreports](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=CreateProspectContactReport) (write)
* [crm-prsmg/prospectmanagers](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=SearchProspectManagers) (read)
* [crm-prsmg/prospectopportunities](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=SearchProspectOpportunities) (read, write)
* [crm-prsmg/prospectplans](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=CreateProspectPlan) (write)
* [crm-prsmg/prospects](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=CreateProspect) (read, write)
* [crm-prsmg/prospectsconstituency](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=CreateProspectConstituency) (write)
* [crm-prsmg/prospectsegmentations](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=CreateProspectManager) (write)
* [crm-prsmg/prospectsteps](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=CreateProspectSteps) (write)
* [crm-prsmg/stewardshipplans](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=CreateStewardshipPlan) (write)
* [crm-prsmg/stewardshipplansteps](https://developer.sky.blackbaud.com/api#api=crm-prsmg\&operation=SearchStewardshipPlanSteps) (read, write)
* [crm-revmg/payments](https://developer.sky.blackbaud.com/api#api=crm-revmg\&operation=SearchRevenuePayments) (read, write)
* [crm-revmg/recurringgifts](https://developer.sky.blackbaud.com/api#api=crm-revmg\&operation=CreateRecurringGift) (write)
* [crm-revmg/revenuenotes](https://developer.sky.blackbaud.com/api#api=crm-revmg\&operation=CreateRevenueNote) (write)
* [crm-revmg/revenuetransactions](https://developer.sky.blackbaud.com/api#api=crm-revmg\&operation=SearchRevenueTransactions) (read)
* [crm-volmg/jobs](https://developer.sky.blackbaud.com/api#api=crm-volmg\&operation=SearchJobs) (read, write)
* [crm-volmg/occurrences](https://developer.sky.blackbaud.com/api#api=crm-volmg\&operation=SearchJobOccurrences) (read, write)
* [crm-volmg/volunteerassignments](https://developer.sky.blackbaud.com/api#api=crm-volmg\&operation=SearchAssignments) (read, write)
* [crm-volmg/volunteers](https://developer.sky.blackbaud.com/api#api=crm-volmg\&operation=SearchVolunteers) (read, write)
* [crm-volmg/volunteerschedules](https://developer.sky.blackbaud.com/api#api=crm-volmg\&operation=CreateVolunteerSchedule) (write)

## Before You Get Started

To connect Blackbaud with Ampersand, you need [a Blackbaud Account](https://developer.blackbaud.com/).

Once your account is created, you'll need to create an app in Blackbaud and obtain the following credentials from your app:

* Application ID
* Application secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Blackbaud App

Follow the steps below to create a Blackbaud app.

1. Log in to your [Blackbaud](https://developer.blackbaud.com/) account.

2. After logging in, navigate to **SKY API -> My account**.

3. Click **My applications -> New application**

4. In the **Application name** field, enter the name of your application and provide additional details in the **Application details** section.

5. In the **Application website URL** field, enter your website URL, then click **Save**.

6. Under **Settings**, click **Edit redirect URIs** in the **Redirect URIs** section. Add the required redirect URIs and click **Save**.

7. Under **Settings**, click **Edit scopes** in the **Scopes** section. Select the required scopes and click **Save**.

   <img alt="Blackbaud OAuth Creation" />

### Example integration

For an example manifest file of a Blackbaud integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/blackbaud/amp.yaml).

## Add Your Blackbaud App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Blackbaud integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select Blackbaud from the **Provider** list.

5. Enter the previously obtained Application ID in the **Client ID** field, the Application Secret in the **Client Secret** field.

   <img alt="Ampersand Integration" />

To start integrating with Blackbaud:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/blackbaud/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Blueshift
Source: https://docs.ampersand.ai/provider-guides/blueshift

Use Ampersand with Blueshift via Basic Auth to read campaigns and segments, write customers and events, and manage email, push, and SMS templates.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Blueshift instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.getblueshift.com/api`.

### Supported Objects

The Blueshift connector supports writing to and reading from the following objects:

* [campaigns](https://developer.blueshift.com/reference/get_api-v2-campaigns-json) (read only)
* [catalogs](https://developer.blueshift.com/reference/get_api-v1-catalogs) (read only)
* [customers](https://developer.blueshift.com/reference/post_api-v1-customers) (write only)
* [custom\_user\_lists/create](https://developer.blueshift.com/reference/post_api-v1-custom-user-lists-create) (write only)
* [email\_templates](https://developer.blueshift.com/reference/get_api-v1-email-templates-json) (read and write)
* [event](https://developer.blueshift.com/reference/post_api-v1-event) (write only)
* [external\_fetches](https://developer.blueshift.com/reference/get_api-v1-external-fetches-json) (read and write)
* [onsite\_slots](https://developer.blueshift.com/reference/get_api-v1-onsite-slots-json) (read only)
* [push\_templates](https://developer.blueshift.com/reference/get_api-v1-push-templates-json) (read and write)
* [seed\_lists](https://developer.blueshift.com/reference/get_api-v1-custom-user-lists-seed-lists) (read only)
* [segments/list](https://developer.blueshift.com/reference/get_api-v1-segments-list) (read only)
* [sms\_templates](https://developer.blueshift.com/reference/get_api-v1-sms-templates-json) (read and write)
* [tag\_contexts/list](https://developer.blueshift.com/reference/get_api-v1-tag-contexts-list) (read only)

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Blueshift:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://api.getblueshift.com/api`.


# Blueshift (EU)
Source: https://docs.ampersand.ai/provider-guides/blueshiftEU

Connect Blueshift (EU) to Ampersand using Basic Auth with a username and password, then make proxy calls to the EU base URL at api.eu.getblueshift.com.

## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.eu.getblueshift.com/api`.

### Example integration

To define an integration for Blueshift (EU), create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: blueshiftEU-integration
    displayName: My Blueshift (EU) Integration
    provider: blueshiftEU
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Blueshift (EU):

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://api.eu.getblueshift.com/api`.


# Box
Source: https://docs.ampersand.ai/provider-guides/box

Connect Box to Ampersand for proxy calls to api.box.com, with steps to create a Box app using User Authentication (OAuth 2.0) and add the redirect URI.

## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.box.com`.

## Before You Get Started

To integrate Box with Ampersand, you will need [a Box Account](https://account.box.com/signup/).

Once your account is created, you'll need to create an app in Box, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Box Account

Here's how you can sign up for a Box account:

* Go to the [Box Sign Up page](https://account.box.com/signup/).
* Sign up using your preferred method.

### Creating a Box App

Follow the steps below to create a Box app and add the Ampersand redirect URL.

1. Log in to your [Box](https://account.box.com/login) account.

2. Navigate to the [Box Developer Console](https://app.box.com/developers/console).

3. Click **Create New App** to create a new app.

4. Select the **Custom type** in the app type section.

5. Enter **App Name**.

6. Select a purpose for the app.

7. Click **Next**.

8. In the **Authentication Method** panel, select **User Authentication (OAuth 2.0)**.

9. Click **Create App**.

   <img alt="Alt text" />

The **OAuth 2.0 Credentials** section displays **Client ID** and **Client Secret** keys for your app. You'll use these credentials to connect your app to [Ampersand](/provider-guides/box#add-your-box-app-info-to-ampersand).

### Configure Your App

1. From the more options next to your app and select **Configure App**.
2. In the **OAuth 2.0 Redirect URIs** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
3. Click **Add**.
4. Select applicable scopes for your app.

<img alt="Alt text" />

## Add Your Box App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Box integration.

   <img alt="Alt text" />

3. Select **Provider Apps**.

4. Select *Box* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save Changes**.


# Braintree
Source: https://docs.ampersand.ai/provider-guides/braintree

Link Braintree to Ampersand with Basic Auth to read customers, transactions, refunds, and disputes incrementally, and write customers and paymentMethods.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `customers`, `transactions`, `refunds`, `disputes`, `verifications`, and `payments` objects.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://payments.sandbox.braintree-api.com/graphql`.

### Supported Objects

The Braintree connector supports reading from the following objects:

* [customers](https://developer.paypal.com/braintree/graphql/guides/customers/)
* [transactions](https://developer.paypal.com/braintree/graphql/guides/transactions/)
* [refunds](https://developer.paypal.com/braintree/graphql/reference/#Object--Refund)
* [disputes](https://developer.paypal.com/braintree/graphql/guides/disputes/)
* [verifications](https://developer.paypal.com/braintree/graphql/reference/#Object--Verification)
* [merchantAccounts](https://developer.paypal.com/braintree/graphql/reference/#Object--MerchantAccount)
* [inStoreLocations](https://developer.paypal.com/braintree/graphql/reference/#Object--InStoreLocation)
* [inStoreReaders](https://developer.paypal.com/braintree/graphql/reference/#Object--InStoreReader)
* [businessAccountCreationRequests](https://developer.paypal.com/braintree/graphql/reference/#Object--BusinessAccountCreationRequest)
* [payments](https://developer.paypal.com/braintree/graphql/reference/#Interface--Payment)

The Braintree connector supports writing to the following objects:

* [customers](https://developer.paypal.com/braintree/graphql/guides/customers/) (create/update)
* [transactions](https://developer.paypal.com/braintree/graphql/guides/transactions/) (charge/capture)
* [paymentMethods](https://developer.paypal.com/braintree/graphql/guides/payment_methods/) (create/update)

### Example integration

To define an integration for Braintree, create a manifest file that looks like this:

```yaml theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: braintree-integration
    displayName: My Braintree Integration
    provider: braintree
    read:
      objects:
        - objectName: customers
          destination: myWebhook
          schedule: "*/10 * * * *"
        - objectName: transactions
          destination: myWebhook
          schedule: "*/10 * * * *"
    write:
      objects:
        - objectName: customers
    proxy:
      enabled: true
```

## Using the connector

This connector uses **Basic Auth**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with Braintree:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for their API credentials.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Getting API credentials for Braintree

1. Log in to your [Braintree Control Panel](https://www.braintreegateway.com/login).
2. Navigate to **Settings** > **API Keys**.
3. Generate or view your API credentials (Public Key, Private Key, and Merchant ID).

<img alt="Braintree API Keys" />

For more details, see the [Braintree API Credentials documentation](https://developer.paypal.com/braintree/articles/control-panel/important-gateway-credentials#api-keys).

Note: Make sure you're using the correct environment (Sandbox or Production) credentials.


# Braze
Source: https://docs.ampersand.ai/provider-guides/braze

Integrate Braze with Ampersand using an API key and Rest Instance ID to read campaigns, canvases, and segments, and write catalogs and scheduled messages.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for `contacts` only.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://rest.{{.restInstanceId}}.braze.com`.

### Supported Objects

The Braze connector supports reading from the following objects:

* [catalogs](https://www.braze.com/docs/api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs)
* [cdi/integrations](https://www.braze.com/docs/api/endpoints/cdi/get_integration_list)
* [email/hard\_bounces](https://www.braze.com/docs/api/endpoints/email/get_list_hard_bounces)
* [email/unsubscribes](https://www.braze.com/docs/api/endpoints/email/get_query_unsubscribed_email_addresses)
* [campaigns](https://www.braze.com/docs/api/endpoints/export/campaigns/get_campaigns)
* [canvas](https://www.braze.com/docs/api/endpoints/export/canvas/get_canvases)
* [events/list](https://www.braze.com/docs/api/endpoints/export/custom_events/get_custom_events)
* [events](https://www.braze.com/docs/api/endpoints/export/custom_events/get_custom_events_data)
* [purchases/product\_list](https://www.braze.com/docs/api/endpoints/export/purchases/get_list_product_id)
* [segments](https://www.braze.com/docs/api/endpoints/export/segments/get_segment)
* [custom\_attributes](https://www.braze.com/docs/api/endpoints/export/custom_attributes/get_custom_attributes)
* [messages/scheduled\_broadcasts](https://www.braze.com/docs/api/endpoints/messaging/schedule_messages/get_messages_scheduled)
* [preference\_center/v1/list](https://www.braze.com/docs/api/endpoints/preference_center/get_list_preference_center)
* [sms/invalid\_phone\_numbers](https://www.braze.com/docs/api/endpoints/sms/get_query_invalid_numbers)
* [content\_blocks/list](https://www.braze.com/docs/api/endpoints/templates/content_blocks_templates/get_list_email_content_blocks)
* [templates/email/list](https://www.braze.com/docs/api/endpoints/templates/email_templates/get_list_email_templates)

The Braze connector supports writing to the following objects:

* [catalogs](https://www.braze.com/docs/api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog)
* [email/status](https://www.braze.com/docs/api/endpoints/email/post_email_subscription_status)
* [email/bounce/remove](https://www.braze.com/docs/api/endpoints/email/post_remove_hard_bounces)
* [email/spam/remove](https://www.braze.com/docs/api/endpoints/email/post_remove_spam)
* [email/blocklist](https://www.braze.com/docs/api/endpoints/email/post_blocklist)
* [users/export/ids](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier)
* [users/export/segment](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_segment)
* [users/export/global\_control\_group](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_global_control_group)
* [campaigns/duplicate](https://www.braze.com/docs/api/endpoints/messaging/duplicate_messages/post_duplicate_campaigns)
* [canvas/duplicate](https://www.braze.com/docs/api/endpoints/messaging/duplicate_messages/post_duplicate_canvases)
* [messages/schedule/create](https://www.braze.com/docs/api/endpoints/messaging/schedule_messages/post_schedule_messages)
* [campaigns/trigger/schedule/create](https://www.braze.com/docs/api/endpoints/messaging/schedule_messages/post_schedule_triggered_campaigns)
* [canvas/trigger/schedule/create](https://www.braze.com/docs/api/endpoints/messaging/schedule_messages/post_schedule_triggered_canvases)
* [messages/schedule/update](https://www.braze.com/docs/api/endpoints/messaging/schedule_messages/post_update_scheduled_messages)
* [campaigns/trigger/schedule/update](https://www.braze.com/docs/api/endpoints/messaging/schedule_messages/post_update_scheduled_triggered_campaigns/#prerequisites)
* [canvas/trigger/schedule/update](https://www.braze.com/docs/api/endpoints/messaging/schedule_messages/post_update_scheduled_triggered_canvases)
* [sends/id/create](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_create_send_ids)
* [messages/send](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_messages)
* [campaigns/trigger/send](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_campaigns)
* [canvas/trigger/send](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_canvases)
* [preference\_center/v1](https://www.braze.com/docs/api/endpoints/preference_center/post_create_preference_center)
* [scim/v2/Users](https://www.braze.com/docs/api/endpoints/scim/post_create_user_account)
* [sms/invalid\_phone\_numbers/remove](https://www.braze.com/docs/api/endpoints/sms/post_remove_invalid_numbers)
* [subscription/status/set](https://www.braze.com/docs/api/endpoints/subscription_groups/post_update_user_subscription_group_status)
* [v2/subscription/status/set](https://www.braze.com/docs/api/endpoints/subscription_groups/post_update_user_subscription_group_status_v2)
* [content\_blocks/create](https://www.braze.com/docs/api/endpoints/templates/content_blocks_templates/post_create_email_content_block)
* [content\_blocks/update](https://www.braze.com/docs/api/endpoints/templates/content_blocks_templates/post_update_content_block)
* [templates/email/create](https://www.braze.com/docs/api/endpoints/templates/email_templates/post_create_email_template)
* [templates/email/update](https://www.braze.com/docs/api/endpoints/templates/email_templates/post_update_email_template)
* [campaigns/translations](https://www.braze.com/docs/api/endpoints/translations/campaigns/put_update_translation_campaign)
* [canvas/translations](https://www.braze.com/docs/api/endpoints/translations/canvas/put_update_translation_canvas)
* [templates/email/translations](https://www.braze.com/docs/api/endpoints/translations/email_templates/put_update_template)
* [users/alias/new](https://www.braze.com/docs/api/endpoints/user_data/post_user_alias)
* [users/alias/update](https://www.braze.com/docs/api/endpoints/user_data/post_users_alias_update)
* [users/identify](https://www.braze.com/docs/api/endpoints/user_data/post_user_identify)
* [users/track](https://www.braze.com/docs/api/endpoints/user_data/post_user_track)
* [users/track/sync](https://www.braze.com/docs/api/endpoints/user_data/post_user_track_synchronous)
* [users/delete](https://www.braze.com/docs/api/endpoints/user_data/post_user_delete)
* [users/merge](https://www.braze.com/docs/api/endpoints/user_data/post_users_merge)
* [users/external\_ids/rename](https://www.braze.com/docs/api/endpoints/user_data/external_id_migration/post_external_ids_rename)
* [users/external\_ids/remove](https://www.braze.com/docs/api/endpoints/user_data/external_id_migration/post_external_ids_remove)

### Example integration

For an example manifest file of a Braze integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/braze/amp.yaml).

## Before You Get Started

### Creating an API key for Braze

[Click here](https://www.braze.com/docs/api/basics/#creating-rest-api-keys) for more information about generating an API key for Braze. The UI components will display this link, so that your users can successfully create API keys.

The Rest Instance ID can also be found on the same page.

<img alt="Braze API key" />

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. Provider apps are only required for providers that use OAuth2 Authorization Code grant type.

To start integrating with Braze:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/braze/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Breakcold
Source: https://docs.ampersand.ai/provider-guides/breakcold

Connect Breakcold to Ampersand with an API key to read leads, workspaces, and members, write notes, tags, lists, and reminders, and make proxy calls.

## What's Supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.breakcold.com/rest`.

### Supported Objects

The Breakcold connector supports reading from the following objects:

* [status](https://developer.breakcold.com/v3/api-reference/status/list-status)
* [workspaces](https://developer.breakcold.com/v3/api-reference/workspaces/get-user-workspaces)
* [members](https://developer.breakcold.com/v3/api-reference/members/get-members-of-a-workspace)
* [leads](https://developer.breakcold.com/v3/api-reference/leads/list-leads-with-pagination-and-filters)
* [tags](https://developer.breakcold.com/v3/api-reference/tags/list-tags)
* [lists](https://developer.breakcold.com/v3/api-reference/lists/get-all-lists)
* [notes](https://developer.breakcold.com/v3/api-reference/notes/list-notes)
* [reminders](https://developer.breakcold.com/v3/api-reference/reminders/list-reminders-with-filters-and-pagination)

The Breakcold connector supports writing to the following objects:

* [status](https://developer.breakcold.com/v3/api-reference/status/create-a-status)
* [tags](https://developer.breakcold.com/v3/api-reference/tags/create-a-tag)
* [lists](https://developer.breakcold.com/v3/api-reference/lists/create-a-list)
* [notes](https://developer.breakcold.com/v3/api-reference/notes/create-a-note)
* [reminders](https://developer.breakcold.com/v3/api-reference/reminders/create-a-reminder)
* [attribute](https://developer.breakcold.com/v3/api-reference/attributes/create-an-attributes)
* [lead](https://developer.breakcold.com/v3/api-reference/leads/create-a-lead)
* [leads/all-list](https://developer.breakcold.com/v3/api-reference/leads/add-a-list-to-leads)

### Example integration

For an example manifest file of a Breakcold integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/breakcold/amp.yaml).

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with breakcold:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Calls](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Breakcold

1. Log in to your [Breakcold account](https://app.breakcold.com/signin).
2. Click settings > API Keys > Create API key.

<img alt="Generate Token" />


# Breezy
Source: https://docs.ampersand.ai/provider-guides/breezy

Connect Breezy to Ampersand with an API key to read positions, pipelines, and templates, write draft positions, and make proxy calls to the Breezy API.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Incremental read is supported for `positions` only. For all other objects, a full read will be done on each scheduled read.
* [Write Actions](/write-actions) (create/update) for `positions` only.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.breezy.hr`.
* Subscribe Actions are not currently supported.

### Supported objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

For objects and fields, you can also use Ampersand’s [Object Metadata APIs](/reference/objects-&-fields/get-object-metadata-via-connection) to inspect what’s available for a specific connection.

### Notes and limitations

* **Published vs draft positions**: Write **create** leaves new positions in **draft**. The `positions` Read object returns **published** job postings only. The connector does **not** auto-publish on create. When the customer is ready to go live, publish via [Proxy Actions](/proxy-actions): `PUT /v3/company/{company_id}/position/{position_id}/state` with `{"state":"published"}`. Until published, the job will not appear in Read webhooks. Publish is intentional — Breezy does not support unpublishing.
* **Incremental read**: Incremental read is supported for `positions` only (filtered by `updated_date`). Scheduled reads emit only positions updated since the last sync. `companies`, `pipelines`, `categories`, `departments`, `questionnaires`, and `templates` are read in full on each scheduled read.
* **Pipelines**: Breezy returns a map of pipeline id → pipeline object (e.g. `default`, `default_pool`).
* **API key expiry**: Breezy access tokens from `/v3/signin` expire after approximately 30 days.

### Example integration

To define an integration for Breezy, use a manifest file (`amp.yaml`). For a complete example, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/breezy/amp.yaml).

## Before you get started

To connect *Breezy* with *Ampersand*, you will need [a Breezy account](https://breezy.hr/).

Once your account is created, you'll need to obtain an **API Key** — a Breezy access token used as the `Authorization` header on API requests.

Your customers enter this when they install the integration via the InstallIntegration UI.

### Create a Breezy account

Here's how you can sign up for a Breezy account:

* Sign up at [Breezy](https://breezy.hr/).

### Obtain API credentials

Follow the steps below to obtain your API key from Breezy:

1. Call Breezy's [sign-in endpoint](https://developer.breezy.hr/reference/signin) with a user that has API access. See [Authorization](https://developer.breezy.hr/reference/authorization).

   ```bash theme={"dark"}
   curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"email":"user@example.com","password":"YOUR_PASSWORD"}' \
     https://api.breezy.hr/v3/signin
   ```

   Use the `access_token` value from the response as the API key.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

The API key is sent in the `Authorization` header with no prefix, per [Breezy’s documentation](https://developer.breezy.hr/reference/authorization).

To start integrating with Breezy:

* Create a manifest file; see [Example integration](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls. Ampersand will automatically attach the API key for the connected account.


# Brevo
Source: https://docs.ampersand.ai/provider-guides/brevo

Use the Brevo connector with API key auth to read and write contacts, companies, CRM deals, notes, tasks, and email campaigns, plus proxy calls to Brevo.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Brevo instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.brevo.com`.

### Supported Objects

The Brevo connector supports the following objects:

* [categories](https://developers.brevo.com/reference/getcategories) (read and write)
* [categories/batch](https://developers.brevo.com/reference/categoriesbatchpost) (write only)
* [companies](https://developers.brevo.com/reference/get_companies) (read and write)
* [companies/import](https://developers.brevo.com/reference/post_companies-import) (write only)
* [companies/attributes](https://developers.brevo.com/reference/get_crm-attributes-companies) (read only)
* [conversations/agentOnlinePing](https://developers.brevo.com/reference/post_conversations-agentonlineping) (write only)
* [conversations/messages](https://developers.brevo.com/reference/post_conversations-messages) (write only)
* [conversations/pushedMessages](https://developers.brevo.com/reference/post_conversations-pushedmessages) (write only)
* [contacts](https://developers.brevo.com/reference/getcontacts-1) (read and write)
* [contacts/doubleOptinConfirmation](https://developers.brevo.com/reference/createdoicontact) (write only)
* [contacts/export](https://developers.brevo.com/reference/requestcontactexport-1) (write only)
* [contacts/folders](https://developers.brevo.com/reference/getfolders-1) (read only)
* [contacts/import](https://developers.brevo.com/reference/importcontacts-1) (write only)
* [coupons](https://developers.brevo.com/reference/getcouponcollections) (read only)
* [crm/deals](https://developers.brevo.com/reference/get_crm-deals) (read and write)
* [crm/deals/import](https://developers.brevo.com/reference/post_crm-deals-import) (write only)
* [crm/notes](https://developers.brevo.com/reference/get_crm-notes) (read and write)
* [crm/tasks](https://developers.brevo.com/reference/get_crm-tasks) (read and write)
* [crm/attributes](https://developers.brevo.com/reference/get_crm-attributes-companies) (read only)
* [emailCampaigns](https://developers.brevo.com/reference/getemailcampaigns-1) (read and write)
* [emailCampaigns/images](https://developers.brevo.com/reference/uploadimagetogallery) (write only)
* [ecommerce/activate](https://developers.brevo.com/reference/post_ecommerce-activate) (write only)
* [ecommerce/config/displayCurrency](https://developers.brevo.com/reference/setconfigdisplaycurrency) (write only)
* [events](https://developers.brevo.com/reference/createevent) (write only)
* [externalFeeds](https://developers.brevo.com/reference/getallexternalfeeds) (read only)
* [files](https://developers.brevo.com/reference/get_crm-files) (read only)
* [feeds](https://developers.brevo.com/reference/createexternalfeed) (write only)
* [folders](https://developers.brevo.com/reference/getfolders-1) (read only)
* [ips](https://developers.brevo.com/reference/getips) (read only)
* [inbound/events](https://developers.brevo.com/reference/getinboundemailevents) (read only)
* [loyalty/config/programs](https://developers.brevo.com/reference/createnewlp) (write only)
* [lists](https://developers.brevo.com/reference/getlists-1) (read only)
* [orders/status](https://developers.brevo.com/reference/createorder) (write only)
* [orders/status/batch](https://developers.brevo.com/reference/createbatchorder) (write only)
* [products](https://developers.brevo.com/reference/getproducts) (read and write)
* [senders](https://developers.brevo.com/reference/getsenders-1) (read and write)
* [senders/domains](https://developers.brevo.com/reference/createdomain) (write only)
* [smtp/statistics/events](https://developers.brevo.com/reference/getemaileventreport-1) (read only)
* [smtp/statistics/reports](https://developers.brevo.com/reference/getsmtpreport-1) (read only)
* [smsCampaigns](https://developers.brevo.com/reference/getsmscampaigns-1) (read only)
* [subAccount](https://developers.brevo.com/reference/get_corporate-subaccount) (read only)
* [templates](https://developers.brevo.com/reference/getsmtptemplates) (read only)
* [transactionalSMS/statistics/events](https://developers.brevo.com/reference/getsmsevents-1) (read only)
* [transactionalSMS/statistics/reports](https://developers.brevo.com/reference/gettransacsmsreport-1) (read only)
* [webhooks](https://developers.brevo.com/reference/getwebhooks) (read and write)
* [webhooks/export](https://developers.brevo.com/reference/exportwebhookshistory) (write only)

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Brevo:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/brevo/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Brevo

[Click here](https://developers.brevo.com/docs/getting-started) for more information about generating an API key for Brevo. The UI components will display this link, so that your users can successfully create API keys.


# Bynder
Source: https://docs.ampersand.ai/provider-guides/bynder

Set up Bynder proxy actions in Ampersand by creating an OAuth app in your Bynder portal and adding its Client ID, Client Secret, and scopes to Ampersand.

## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.bynder.com/api`.

## Before You Get Started

To connect Bynder with Ampersand, you will need [a Bynder Account](https://www.bynder.com/en/).

Once your account is created, you'll need to create an app in your Bynder portal, configure the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Bynder Account

To create an account for your organization, you need to contact the [Bynder Support](https://www.bynder.com/en/) team. An active account is required to log into your portal.

### Creating a Bynder App

Once your Bynder account is set up, you can follow the steps below to create a Bynder app:

1. Log in to your [Bynder Portal](https://portal.bynder.com/).

2. Navigate to `Settings >> Advanced Settings >> Portal Settings`.

3. Go to **Oauth Apps**.

4. Click the **Add new app** button.

5. Enter the following details to register your **Oauth** app:
   1. **Application Name**: The name of your app.
   2. **Homepage URL**: The URL of your app's homepage.
   3. **Application Description**: A brief description of your app.
   4. **Integration**: Type of integration (e.g., API, SDK).
   5. **Integration Name**: Specific name for your integration.
   6. **Grant Type**: Choose between Authorization Code or Client Credentials.
   7. **Authorization Redirect URIs**: URL(s) for Bynder to redirect after authorization. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

6. Select the scopes for your application. Bynder will authorize access to the selected scopes for your application.

7. Click **Register Application.**

<img alt="Bynder App Creation" />

You will find the **Client ID** and **Client Secret** in the app details. Note these credentials, as you will need them to connect your app to Ampersand.

<br />

## Add Your Bynder App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Bynder integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Bynder** from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in *Bynder*.

   <img alt="Ampersand Integration" />

7. Click **Save Changes**.


# Calendly
Source: https://docs.ampersand.ai/provider-guides/calendly

Connect Calendly to Ampersand to read scheduled events and event types, write invitees, shares, and webhook subscriptions, and create a Calendly app.

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for `event_types` only.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.calendly.com`.

### Supported Objects

The Calendly connector supports reading from the following objects:

* [activity\_log\_entries](https://developer.calendly.com/api-docs/d37c7f031f339-list-activity-log-entries)
* [user\_availability\_schedules](https://developer.calendly.com/api-docs/8098de44af94c-list-user-availability-schedules)
* [event\_types](https://developer.calendly.com/api-docs/25a4ece03c1bc-list-user-s-event-types)
* [group\_relationships](https://developer.calendly.com/api-docs/4674a12f55f82-list-group-relationships)
* [groups](https://developer.calendly.com/api-docs/6rb6dtdln74sy-list-groups)
* [locations](https://developer.calendly.com/api-docs/fd0b55ed06014-list-user-meeting-locations)
* [organization\_memberships](https://developer.calendly.com/api-docs/eaed2e61a6bc3-list-organization-memberships)
* [outgoing\_communications](https://developer.calendly.com/api-docs/9f56d7339ee2e-list-outgoing-communications)
* [routing\_forms](https://developer.calendly.com/api-docs/9fe7334bec6ad-list-routing-forms)
* [scheduled\_events](https://developer.calendly.com/api-docs/2d5ed9bbd2952-list-events)

The Calendly connector supports writing to the following objects:

* [event\_types](https://developer.calendly.com/api-docs/nuowpx7qfagsc-create-event-type)
* [one\_off\_event\_types](https://developer.calendly.com/api-docs/v1yuxil3cpmxq-create-one-off-event-type)
* [invitees](https://developer.calendly.com/api-docs/p3ghrxrwbl8kqe-create-event-invitee)
* [invitee\_no\_shows](https://developer.calendly.com/api-docs/cebd8c3170790-create-invitee-no-show)
* [scheduling\_links](https://developer.calendly.com/api-docs/4b8195084e287-create-single-use-scheduling-link)
* [shares](https://developer.calendly.com/api-docs/fdcac06abfc8c-create-share)
* [webhook\_subscriptions](https://developer.calendly.com/api-docs/c1ddc06ce1f1b-create-webhook-subscription)

### Example integration

For an example manifest file of a Calendly integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/calendly/amp.yaml).

## Before You Get Started

To connect *Calendly* with *Ampersand*, you will need [a Calendly Account](#create-a-calendly-account).

Once your account is created, you'll need to configure an app in Calendly and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a Calendly Account

Here's how you can sign up for a Calendly Developer account:

* Go to the [Calendly Sign Up page](https://login.calendly.com/signin/register).
* Sign up using your preferred method.

### Creating a Calendly App

Follow the steps below to create a Calendly app and add the Ampersand redirect URL in the app:

1. Log in to your [Calendly Developer Dashboard](https://login.calendly.com/).
2. Click **Create new app**.
3. Enter the **App Name**.
4. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` in the Redirect URI section.

<img alt="Alt text" />

You'll find the **Client ID** and **Client Secret** keys for your app in the following section. Note these credentials as they are necessary for connecting your app to Ampersand.

## Add Your Calendly App info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Calendly integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Calendly* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save changes**.


# CallRail
Source: https://docs.ampersand.ai/provider-guides/callRail

Integrate CallRail with Ampersand using an API v3 key to read and write calls, form submissions, text messages, trackers, and users, with proxy support.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the CallRail instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.callrail.com`.
* Subscribe Actions are not currently supported.

### Supported objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
      </tr>
    </thead>
  </table>
</div>

### Example integration

For an example manifest file of a CallRail integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/callrail/amp.yaml).

## Before you get started

To connect CallRail with Ampersand, you will need a [CallRail account](https://www.callrail.com/).

### Creating an API key for CallRail

1. Log in to your [CallRail account](https://app.callrail.com/).
2. Go to **Account Settings**, then select **API Keys** under **Data Access**.
3. Select **Create New API v3 Key** and give the key a name.
4. Copy the key and store it somewhere secure — CallRail displays it only once. See [CallRail's API](https://support.callrail.com/hc/en-us/articles/5711821845389-CallRail-s-API) for more detail.

Your customers enter this API key when they install the integration. Ampersand sends it as `Authorization: Token token=<API key>`, as described in [CallRail's Getting Started guide](https://apidocs.callrail.com/#getting-started).

You do not need to collect an account ID from your customer. After the connection is created, Ampersand calls `GET /v3/a.json` and stores the account's numeric ID, then uses it in every request path.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with CallRail:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls. Note that CallRail paths include the account ID, for example `GET /v3/a/{account_id}/calls.json`.


# Campaign Monitor
Source: https://docs.ampersand.ai/provider-guides/campaignMonitor

Connect Campaign Monitor to Ampersand to read and write clients and admins, make proxy calls, and register a Campaign Monitor OAuth app for credentials.

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.createsend.com`.

### Supported Objects

The Campaign Monitor connector supports reading and writing from the following objects:

* [clients](https://www.campaignmonitor.com/api/v3-3/account/#getting-your-clients)
* [admins](https://www.campaignmonitor.com/api/v3-3/account/#getting-administrators)

### Example integration

For an example manifest file of a Campaign Monitor integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/campaignmonitor/amp.yaml).

## Before You Get Started

To integrate CampaignMonitor with Ampersand, you will need [a CampaignMonitor Account](https://www.campaignmonitor.com/).

Once your account is created, you'll need to register an OAuth app and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a CampaignMonitor Account

Here's how you can sign up for a CampaignMonitor account:

1. Go to the [CampaignMonitor Sign Up](https://www.campaignmonitor.com/signup/?sv=f_email-signup) page.
2. Fill out the form with your details and create your account.

### Creating a CampaignMonitor OAuth App

Follow the steps below to create a CampaignMonitor OAuth app:

1. Log in to your [CampaignMonitor](https://login.createsend.com/l) account.
2. Go to the **Integrations** page.
3. Click **Oauth Registration**.
4. Fill in the required details:
   * **Integration Name:** Choose a name for your integration.
   * **Description:** Integration description.
   * **URLs:** Enter your application's website URL.
   * **Redirect URI:** Enter `https://api.withampersand.com/callbacks/v1/oauth`.
5. Click **Register** to create your OAuth app.

<img alt="Alt text" />

Once your OAuth app is created, you can view the **Client ID** and **Client Secret**. Note these credentials, as you'll need them to connect to Ampersand.

## Add Your CampaignMonitor OAuth Credentials to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a *CampaignMonitor* integration.
3. Select **Provider Apps**.
4. Select *CampaignMonitor* from the **Provider** list.
5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.
6. Enter the scopes set for your application in *Campaign Monitor*.

<img alt="Alt text" />

7. Click **Save Changes**.

## Using the connector

To start integrating with Campaign Monitor:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/campaignmonitor/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Capsule
Source: https://docs.ampersand.ai/provider-guides/capsule

Integrate Capsule CRM with Ampersand to read and write opportunities, parties, projects, and tasks with incremental reads, then create a Capsule CRM app.

## What's Supported

### Supported Actions

This connector supports:

* [Write Actions](/write-actions).
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.capsulecrm.com/api`.

### Supported Objects

The Capsule connector supports reading from and writing to the following objects:

* [activitytypes](https://developer.capsulecrm.com/v2/models/activity_type)
* [boards](https://developer.capsulecrm.com/v2/models/board)
* [categories](https://developer.capsulecrm.com/v2/models/category)
* [countries](https://developer.capsulecrm.com/v2/models/country)
* [lostreasons](https://developer.capsulecrm.com/v2/models/lost_reason)
* [milestones](https://developer.capsulecrm.com/v2/models/milestone)
* [opportunities](https://developer.capsulecrm.com/v2/models/opportunity)
* [projects](https://developer.capsulecrm.com/v2/models/project)
* [parties](https://developer.capsulecrm.com/v2/models/party)
* [pipelines](https://developer.capsulecrm.com/v2/models/pipeline)
* [stages](https://developer.capsulecrm.com/v2/models/stage)
* [tasks](https://developer.capsulecrm.com/v2/models/task)
* [teams](https://developer.capsulecrm.com/v2/models/team)
* [titles](https://developer.capsulecrm.com/v2/models/title)
* [trackdefinitions](https://developer.capsulecrm.com/v2/models/track_definition)
* [users](https://developer.capsulecrm.com/v2/models/user)

## Before You Get Started

To integrate Capsule CRM with Ampersand, you will need [a Capsule CRM Developer Account](https://developer.capsulecrm.com/).

Once your account is created, you'll need to create an app in Capsule CRM, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials and scopes to connect your application to Ampersand.

### Create a Capsule CRM Account

Here's how you can sign up for a Capsule CRM account:

* Go to the [Capsule CRM Developer portal](https://developer.capsulecrm.com/) and sign up using your *Github* account.

### Creating a Capsule CRM App

Follow the steps below to create a Capsule CRM app:

1. Log in to your [Capsule CRM Developer account](https://capsulecrm.com/developers).

2. Click **Your Applications**.

3. Click **New Application**.

4. Enter the following details in the *Create a new application* form:

   1. **Name**: Enter the name of your Capsule CRM account or organization.
   2. **Description**: Provide a brief overview of your application's functionality and purpose.
   3. **URL**: Specify the URL of your application's landing page.
   4. **Redirect URIs**: Use `https://api.withampersand.com/callbacks/v1/oauth` as the Redirect URI.
   5. **Contact Email**: Provide the email address linked to your Capsule CRM account. This will be used for any communication regarding your app.
   6. **Application Type**: Choose the type of application you are developing.

5. Click **Save**. You will see the **Client ID** and **Client Secret** in the app details. Note these credentials, as you will need them to connect your app to Ampersand.

<img alt="Capsule CRM App Creation" />

<br />

## Add Your Capsule CRM App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Capsule CRM integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Capsule CRM* from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in *Capsule CRM*.

<img alt="Ampersand Integration" />

7. Click **Save Changes**.


# ChargeOver
Source: https://docs.ampersand.ai/provider-guides/chargeOver

Make proxy calls to the ChargeOver API through Ampersand using Basic Auth, after enabling REST API support in ChargeOver to get your username and password.

## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.domain}}.chargeover.com`.

### Example integration

To define an integration for ChargeOver, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: chargeOver-integration
    displayName: My ChargeOver Integration
    provider: chargeOver
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with ChargeOver:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their domain, username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://{{.domain}}.chargeover.com`.

## Creating Basic Auth credentials

To begin using the API in your ChargeOver account, you need to enable REST API support:

* Navigate to Settings.
* Click on Developers > More Dev Tools.
* Click the Get Started button under REST API.
* Enable the REST API. Once enabled, your username and password for Basic Authentication will be displayed.

<img alt="ChargeOver Credentials" />


# Chargebee
Source: https://docs.ampersand.ai/provider-guides/chargebee

Connect Chargebee with Basic auth to read subscriptions, invoices, and customers, write quotes and orders, and run incremental reads on many objects.

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.chargebee.com/api`.

### Supported objects

The Chargebee connector supports reading from the following objects:

* [attached\_items](https://apidocs.chargebee.com/docs/api/attached_items)
* [business\_entities/transfers](https://apidocs.chargebee.com/docs/api/business_entities)
* [comments](https://apidocs.chargebee.com/docs/api/comments)
* [coupon\_codes](https://apidocs.chargebee.com/docs/api/coupon_codes)
* [coupon\_sets](https://apidocs.chargebee.com/docs/api/coupon_sets)
* [coupons](https://apidocs.chargebee.com/docs/api/coupons)
* [credit\_notes](https://apidocs.chargebee.com/docs/api/credit_notes)
* [currencies](https://apidocs.chargebee.com/docs/api/currencies)
* [customers](https://apidocs.chargebee.com/docs/api/customers)
* [entitlements](https://apidocs.chargebee.com/docs/api/entitlements)
* [events](https://apidocs.chargebee.com/docs/api/events)
* [features](https://apidocs.chargebee.com/docs/api/features)
* [gifts](https://apidocs.chargebee.com/docs/api/gifts)
* [hosted\_pages](https://apidocs.chargebee.com/docs/api/hosted_pages)
* [invoices](https://apidocs.chargebee.com/docs/api/invoices)
* [item\_families](https://apidocs.chargebee.com/docs/api/item_families)
* [item\_prices](https://apidocs.chargebee.com/docs/api/item_prices)
* [items](https://apidocs.chargebee.com/docs/api/items)
* [omnichannel\_one\_time\_orders](https://apidocs.chargebee.com/docs/api/omnichannel_transactions)
* [omnichannel\_subscriptions](https://apidocs.chargebee.com/docs/api/omnichannel_subscriptions)
* [orders](https://apidocs.chargebee.com/docs/api/orders)
* [payment\_sources](https://apidocs.chargebee.com/docs/api/payment_sources)
* [plans](https://apidocs.chargebee.com/docs/api/plans)
* [promotional\_credits](https://apidocs.chargebee.com/docs/api/promotional_credits)
* [quotes](https://apidocs.chargebee.com/docs/api/quotes)
* [subscriptions](https://apidocs.chargebee.com/docs/api/subscriptions)
* [transactions](https://apidocs.chargebee.com/docs/api/transactions)
* [unbilled\_charges](https://apidocs.chargebee.com/docs/api/unbilled_charges)
* [usages](https://apidocs.chargebee.com/docs/api/usages)
* [virtual\_bank\_accounts](https://apidocs.chargebee.com/docs/api/virtual_bank_accounts)
* [webhook\_endpoints](https://apidocs.chargebee.com/docs/api/webhook_endpoints)

### Objects supporting incremental read:

* `coupons`
* `credit_notes`
* `customers`
* `hosted_pages`
* `invoices`
* `item_prices`
* `items`
* `orders`
* `payment_sources`
* `quotes`
* `subscriptions`
* `transactions`
* `usages`
* `virtual_bank_accounts`

For all other objects, a full read of the Chargebee instance will be done per scheduled read.

The Chargebee connector supports writing to the following objects:

* [comments](https://apidocs.chargebee.com/docs/api/comments)
* [coupons](https://apidocs.chargebee.com/docs/api/coupons)
* [coupon\_sets](https://apidocs.chargebee.com/docs/api/coupon_sets)
* [credit\_notes](https://apidocs.chargebee.com/docs/api/credit_notes)
* [currencies](https://apidocs.chargebee.com/docs/api/currencies)
* [customers](https://apidocs.chargebee.com/docs/api/customers)
* [estimates](https://apidocs.chargebee.com/docs/api/estimates)
* [features](https://apidocs.chargebee.com/docs/api/features)
* [invoices](https://apidocs.chargebee.com/docs/api/invoices)
* [item\_families](https://apidocs.chargebee.com/docs/api/item_families)
* [item\_prices](https://apidocs.chargebee.com/docs/api/item_prices)
* [items](https://apidocs.chargebee.com/docs/api/items)
* [offer\_events](https://apidocs.chargebee.com/docs/api/offer_events)
* [offer\_fulfillments](https://apidocs.chargebee.com/docs/api/offer_fulfillments)
* [orders](https://apidocs.chargebee.com/docs/api/orders)
* [payment\_intents](https://apidocs.chargebee.com/docs/api/payment_intents)
* [payment\_schedule\_schemes](https://apidocs.chargebee.com/docs/api/payment_schedule_schemes)
* [payment\_vouchers](https://apidocs.chargebee.com/docs/api/payment_vouchers)
* [portal\_sessions](https://apidocs.chargebee.com/docs/api/portal_sessions)
* [promotional\_credits](https://apidocs.chargebee.com/docs/api/promotional_credits)
* [quotes](https://apidocs.chargebee.com/docs/api/quotes)
* [recorded\_purchases](https://apidocs.chargebee.com/docs/api/recorded_purchases)
* [transactions](https://apidocs.chargebee.com/docs/api/transactions)
* [unbilled\_charges](https://apidocs.chargebee.com/docs/api/unbilled_charges)
* [virtual\_bank\_accounts](https://apidocs.chargebee.com/docs/api/virtual_bank_accounts)
* [webhook\_endpoints](https://apidocs.chargebee.com/docs/api/webhook_endpoints)

### Example integration

For an example manifest file of a Chargebee integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/chargebee/amp.yaml).

## Using the connector

This connector uses Basic auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Chargebee:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username, password and site name.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://{{.site}}.chargebee.com/api`.

## Creating Basic Auth Credentials for Chargebee

Chargebee uses the API Key as the username when authenticating with Basic Auth. The password field should be left blank.

[Click here](https://www.chargebee.com/docs/billing/2.0/site-configuration/api_keys) for more information about generating an API key for Chargebee. The UI components will display this link, so that your users can successfully create API keys.


# ChartMogul
Source: https://docs.ampersand.ai/provider-guides/chartMogul



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.chartmogul.com`.

### Example integration

To define an integration for ChartMogul, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: chartMogul-integration
    displayName: My ChartMogul Integration
    provider: chartMogul
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with ChartMogul:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://api.chartmogul.com`.


# ChiliPiper
Source: https://docs.ampersand.ai/provider-guides/chilipiper



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Chilipiper instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://fire.chilipiper.com`.

### Supported Objects

The Chilipiper connector supports reading from the following objects:

* [workspace](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Read%20all%20workspaces)
* [team](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Read%20all%20teams)
* [distribution](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/List%20all%20distributions)
* [workspace/users](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Read%20all%20users%20\(or%20in%20a%20workspace\))

The Chilipiper connector supports writing to the following objects:

* [distribution](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Update%20distribution%20and%20publish%20it)
* [user/invite](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Invites%20new%20user%20to%20the%20organization)
* [user/licenses](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Updates%20licenses%20for%20users)
* [team/users/add](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Add%20users%20to%20a%20team)
* [team/users/remove](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Remove%20users%20from%20a%20team)
* [workspace/users/add](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Add%20users%20to%20a%20workspace)
* [workspace/users/remove](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Remove%20users%20from%20a%20workspace)
* [workspace/users/remove-from-all](https://fire.chilipiper.com/api/fire-edge/public/org/docs/index.html#operation/Remove%20users%20from%20all%20workspaces)

### Example integration

For an example manifest file of a ChiliPiper integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/chilipiper/amp.yaml).

## Before You Get Started

### Creating an API key for ChiliPiper

* Log in to your chilipiper instance
* Go to Integrations
* Click on the *API Access Tokens*
* Click On *Generate Token*

<img alt="ChiliPiper API Key Creation" />

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider Apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with ChiliPiper:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/chilipiper/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Chorus
Source: https://docs.ampersand.ai/provider-guides/chorus



<Note>
  The Chorus connector is in beta. If you have any feedback or experience any issues, please contact [support@withampersand.com](mailto:support@withampersand.com)
</Note>

## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `emails` and `scorecards` only. For all other objects, a full read of the Chorus instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://chorus.ai`.

### Supported Objects

The Chorus connector supports reading from the following objects:

* [emails](https://api-docs.chorus.ai/#3d962146-73fc-42db-afda-a943971ab1c4)
* [filters](https://api-docs.chorus.ai/#68ee2093-f321-4564-b342-5520f974a1b7)
* [playlists](https://api-docs.chorus.ai/#f8b34d44-df36-47eb-a42e-a112aa0ec474)
* [scorecards](https://api-docs.chorus.ai/#4dc74394-9852-4b6b-9555-cb8ce951557b)
* [teams](https://api-docs.chorus.ai/#894c7066-c68f-4c8a-9470-d1b2c998dd36)

The Chorus connector supports writing to the following objects:

* [filters](https://api-docs.chorus.ai/#610860f7-6eaf-4ca1-81d4-15c9b45eb005)
* [playlists](https://api-docs.chorus.ai/#139f8088-3c9b-42aa-bee4-0820142dd08b)
* [moments](https://api-docs.chorus.ai/#c33b52cc-0443-4c2a-9d63-0308989b7233)
* [smart\_playlists](https://api-docs.chorus.ai/#fce98614-e4b5-4d03-adbc-830daafbe2ed)
* [playlists/moments](https://api-docs.chorus.ai/#123c5ee2-402c-45b4-85f8-b1a1be8b9415)
* [scorecards:export](https://api-docs.chorus.ai/#a10eb090-a5da-4c3c-b1a6-7adb2e62c726)
* [video\_conferences](https://api-docs.chorus.ai/#2fbb92e0-59e7-4702-98ec-0496a379eb18)
* [conversations:validate](https://api-docs.chorus.ai/#17f15cef-eabe-440e-ad16-0d0bbc0910fb)
* [conversations:export](https://api-docs.chorus.ai/#04e72d8e-81fa-49f5-901e-29ccce832a21)
* [join](https://api-docs.chorus.ai/#206f6045-5c4d-4fed-b086-051903cae649)

### Example integration

For an example manifest file of a Chorus integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/chorus/amp.yaml).

## Using the connector

This connector uses Basic auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Chorus:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/chorus/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username, password.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Clari
Source: https://docs.ampersand.ai/provider-guides/clari



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.clari.com`.

### Example integration

To define an integration for Clari, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: clari-integration
    displayName: My Clari Integration
    provider: clari
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Clari:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.clari.com`.

## Creating an API key for Clari

[Click here](https://developer.clari.com/documentation/external_spec) for more information about generating an API key for Clari. The UI components will display this link, so that your users can successfully create API keys.


# Clari Copilot
Source: https://docs.ampersand.ai/provider-guides/clariCopilot



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `calls`, currently. For all other objects, a full read of the Clari Copilot instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://rest-api.copilot.clari.com`.

> **Important Note on Incremental Reads for Calls**: The incremental read functionality for `calls` is based on the `last_modified_time` field. However, this timestamp only updates when the call's status changes, not when other fields (like name, email, etc.) are modified. This means that incremental reads may miss updates to non-status fields that occur between scheduled reads.

### Supported Objects

The Clari Copilot connector supports reading from the following objects:

* [accounts](https://api-doc.copilot.clari.com/#tag/account/paths/~1create-account/post) (write)
* [calls](https://api-doc.copilot.clari.com/#tag/call/paths/~1calls/get) (read, write)
* [contacts](https://api-doc.copilot.clari.com/#tag/contact/paths/~1create-contact/post) (write)
* [deals](https://api-doc.copilot.clari.com/#tag/deal/paths/~1create-deal/post) (write)
* [users](https://api-doc.copilot.clari.com/#tag/user) (read)
* [topics](https://api-doc.copilot.clari.com/#tag/topics/paths/~1v2~1topics/get) (read)
* [scorecard](https://api-doc.copilot.clari.com/#tag/scorecard) (read)
* [scorecard-template](https://api-doc.copilot.clari.com/#tag/scorecard) (read)

### Example integration

For an example manifest file of a Clari Copilot integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/clariCopilot/amp.yaml).

## Using the connector

This connector uses API Key auth along with an API Secret, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Clari Copilot:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API Key and API Secret.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach both required authentication headers supplied by the customer. Please note that this connector's base URL is `https://rest-api.copilot.clari.com`.

### Creating API credentials

1. Log in to your Clari Copilot account.
2. Navigate to **Workspace Settings** > **Integrations** > **Clari Copilot API**.
   <img alt="Clari Copilot API Settings" />
3. You'll find both your API Key and API Secret in this section.

## API documentation

For more detailed information about Clari Copilot API, refer to the [Clari Copilot API documentation](https://api-doc.copilot.clari.com/).


# ClickUp
Source: https://docs.ampersand.ai/provider-guides/clickup



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the ClickUp instance will be done for each scheduled read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.clickup.com`.

### Supported Objects

The ClickUp connector supports reading from the following objects:

* [team](https://developer.clickup.com/reference/getauthorizedteams) (Read only)

## Before you get started

To integrate ClickUp with Ampersand, you will need [a ClickUp Account](https://app.clickup.com/signup).

Once your account is created, you'll need to create an app in ClickUp and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a ClickUp Account

Here's how you can sign up for a ClickUp account:

* Go to the [ClickUp Sign Up page](https://app.clickup.com/signup) and create an account.
* Sign up using your preferred method.

### Creating a ClickUp App

Follow the steps below to create a ClickUp app and add the Ampersand redirect URL in the app:

1. Log in to your [ClickUp](https://app.clickup.com/settings/apps) account.
2. Click **+Create an App**.
3. Enter your **App Name**.
4. Enter the Ampersand's **Redirect URL**: `https://api.withampersand.com/callbacks/v1/oauth`.
5. Click **Create App**.

   <img alt="Alt text" />

On the next screen, you'll see a **Client ID** and **Client Secret** have been generated.

You'll use these credentials while connecting your app to Ampersand.

## Add Your ClickUp App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a ClickUp integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *ClickUp* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save changes**.

## Using the connector

To start integrating with ClickUp:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/clickup/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Close
Source: https://docs.ampersand.ai/provider-guides/close



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read support is available in **Leads**, **Contacts** and **Opportunities** objects only.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.close.com/api`.

### Supported Objects

The Close connector supports reading from the following objects:

* [Leads](https://developer.close.com/resources/leads/#list-leads)
* [Contacts](https://developer.close.com/resources/contacts/#list-contacts)
* [Activities](https://developer.close.com/resources/activities/#list-or-filter-all-activity-types)
* [Opportunities](https://developer.close.com/resources/opportunities/#list-or-filter-opportunities)
* [Tasks](https://developer.close.com/resources/tasks/#list-or-filter-tasks)
* [Users](https://developer.close.com/resources/users/)
* [Roles](https://developer.close.com/resources/roles/#list-all-the-roles-defined-for-your-organization)
* [Pipelines](https://developer.close.com/resources/pipelines/#list-pipelines-for-your-organization)
* [Groups](https://developer.close.com/resources/groups/#list-groups-for-your-organization)
* [Email Templates](https://developer.close.com/resources/email-templates/#list-email-templates)
* [SMS Templates](https://developer.close.com/resources/sms-templates/#list-sms-templates)
* [Connected Accounts](https://developer.close.com/resources/connected-accounts/#list-all-the-connected-accounts-you-can-use-in-your-organization)
* [Send As](https://developer.close.com/resources/send-as/#list-all-send-as-associations-by-allowing-or-allowed-user)
* [Sequences](https://developer.close.com/resources/sequences/#list-sequences)
* [Dialer](https://developer.close.com/resources/dialer/#list-or-filter-all-dialer-sessions)
* [Smart Views](https://developer.close.com/resources/smart-views/#list-smart-views)
* [Integration Links](https://developer.close.com/resources/integration-links/#get-all-integration-links-for-your-organization)
* [Phone numbers](https://developer.close.com/resources/phone-numbers/#list-or-search-for-phone-numbers)
* [Comment Thread](https://developer.close.com/resources/comments/#fetch-multiple-comment-threads)
* [Webhook Subscriptions](https://developer.close.com/resources/webhook-subscriptions/#list-webhook-subscriptions)
* [User Scheduling Links](https://developer.close.com/resources/scheduling-links/user-scheduling-links/#list-user-scheduling-links)
* [Shared Scheduling Links](https://developer.close.com/resources/scheduling-links/shared-scheduling-links/#list-shared-scheduling-links)
* [Custom Activity Types](https://developer.close.com/resources/custom-activities/custom-activity-types/#list-custom-activity-types)
* [Custom Object Types](https://developer.close.com/resources/custom-objects/custom-object-types/#list-custom-object-types)

The Close connector supports writing to the following objects:

* [Leads](https://developer.close.com/resources/leads/#create-a-new-lead)
* [contacts](https://developer.close.com/resources/contacts/#create-a-new-contact)
* [accounts](https://apolloio.github.io/apollo-api-docs/?shell#accounts-api)
* [Opportunities](https://developer.close.com/resources/opportunities/#create-an-opportunity)
* [Tasks](https://developer.close.com/resources/tasks/#create-a-task)
* [Membership](https://developer.close.com/resources/memberships/#create-or-activate-a-membership-for-the-given-email)
* [Roles](https://developer.close.com/resources/roles/#create-a-new-role)
* [Pipelines](https://developer.close.com/resources/pipelines/#create-a-pipeline)
* [Groups](https://developer.close.com/resources/groups/#create-a-group)
* [Email Templates](https://developer.close.com/resources/email-templates/#create-an-email-template)
* [SMS Templates](https://developer.close.com/resources/sms-templates/#create-an-sms-template)
* [Send As Association](https://developer.close.com/resources/send-as/#create-a-send-as-association)
* [Sequences](https://developer.close.com/resources/sequences/#create-a-sequence)
* [Contact Smart View](https://developer.close.com/resources/smart-views/#create-a-contact-smart-view)
* [Integration Link](https://developer.close.com/resources/integration-links/#create-an-integration-link)
* [Comment](https://developer.close.com/resources/comments/#create-a-comment)
* [Webhook](https://developer.close.com/resources/webhook-subscriptions/#create-new-webhook-subscription)
* [User Scheduling link](https://developer.close.com/resources/scheduling-links/user-scheduling-links/#create-a-user-scheduling-link)
* [Shared Scheduling Link](https://developer.close.com/resources/scheduling-links/shared-scheduling-links/#create-a-shared-scheduling-link)
* [Custom Activity Type](https://developer.close.com/resources/custom-activities/custom-activity-types/#create-new-custom-activity-type)
* [Custom Object Type](https://developer.close.com/resources/custom-objects/custom-object-types/#create-new-custom-object-type)
* [Custom Object Instance](https://developer.close.com/resources/custom-objects/custom-object-instances/#create-a-new-custom-object-instance)

### Example integration

For an example manifest file of a CloseCRM integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/close/amp.yaml).

## Before You Get Started

To integrate Close with Ampersand, you need to [Create a Close Account](#create-a-close-account) and obtain the following credentials from your Close App:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Close Account

You need a **Close** account to connect with Ampersand. If you do not have a Close account, here's how you can sign up:

* Go to the [Close site](https://close.com/) and sign up for a free account.
* Sign up using your preferred method.

### Creating an OAuth app in Close

Once your Close account is ready, you need to create an OAuth application to connect with Ampersand. Follow the steps below to create the OAuth app:

1. Log in to Your [Close Account](https://app.close.com/login/).

2. Go to **Settings**.

3. On the *Settings* page, click **Developer** under the **Connect** section.

4. Go to the **OAuth Apps** tab.

5. Click the **Create App** button.

6. Enter the following details in the **Create OAuth App** form:

   1. **App Name**: The name of the OAuth app.
   2. **App Description**: Description for the OAuth app.
   3. **Redirect URL**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`

7. Click **Create**.

You'll find the **Client ID** and **Client Secret** keys in your Oauth app details. These credentials are required for connecting your app to Ampersand, so be sure to note them carefully.

<img alt="Close CRM API Key Details" />

## Add Close App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Close App.

   <img alt="Ampersand Project Selection" />

3. Navigate to the **Provider Apps** section.

4. Select **Close** from the Provider list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in **Close**.

   <img alt="Ampersand Project Selection" />

7. Click **Save Changes**.


# CloudTalk
Source: https://docs.ampersand.ai/provider-guides/cloudtalk



## What's Supported

### Supported Actions

This connector supports:

* [Read Action](/read-actions), including full historic backfill. Incremental read is supported only for `Calls` and `Activities`. Note that for all other objects, a full read of the CloudTalk instance will be done for each scheduled read.
* [Write Action](/write-actions).
* [Proxy Action](/proxy-actions), using the base URL `https://my.cloudtalk.io/api`.

### Supported Objects

The CloudTalk connector supports writing to and reading from the following objects:

* [Activity](https://developers.cloudtalk.io/reference/activity#tag/Contacts/paths/~1activity~1index.json/get) (`activity`)
* [Agent](https://developers.cloudtalk.io/reference/agents#tag/Agents) (`agents`)
* [Blacklist](https://developers.cloudtalk.io/reference/blacklist#tag/Other/paths/~1blacklist~1index.json/get) (`blacklist`)
* [Call](https://developers.cloudtalk.io/reference/calls#tag/Calls) (`calls`)
* [Campaign](https://developers.cloudtalk.io/reference/campaigns#tag/Campaigns) (`campaigns`)
* [Contact](https://developers.cloudtalk.io/reference/contacts#tag/Contacts) (`contacts`)
* [Group](https://developers.cloudtalk.io/reference/groups#tag/Groups) (`groups`)
* [Note](https://developers.cloudtalk.io/reference/notes#tag/Contacts/paths/~1notes~1index.json/get) (`notes`)
* [Number](https://developers.cloudtalk.io/reference/numbers#tag/Numbers) (`numbers`)
* [Tag](https://developers.cloudtalk.io/reference/tags#tag/Tags) (`tags`)

## Before You Get Started

To integrate **CloudTalk** with **Ampersand**, you need your **Access Key ID** and **Access Key Secret**. To obtain these:

1. Log in to your [CloudTalk Dashboard](https://my.cloudtalk.io/login).
2. Navigate to **Account** > **Settings** > **API Keys**.
3. Click **Add API Key** to generate a new pair of credentials.
   <img alt="CloudTalk API Keys" />

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with CloudTalk:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/cloudtalk/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their Access Key ID and Access Key Secret.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Coda
Source: https://docs.ampersand.ai/provider-guides/coda



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://coda.io/apis`.

### Example integration

To define an integration for Coda, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: coda-integration
    displayName: My Coda Integration
    provider: coda
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Coda:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://coda.io/apis`.

## Creating an API key for Coda

1. Log in to your [Coda Account](https://coda.io/signin).

2. Navigate to [**Account settings**](https://coda.io/account) > **API settings**

3. Click **Generate an API Token**.

4. Provide a *name* and click **Generate API token**

<img alt="Alt text" />


# ConnectWise
Source: https://docs.ampersand.ai/provider-guides/connectWise



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read. Please note that incremental read is unreliable due to ConnectWise API limitations. You may get more data than what is within the time range.
* [Subscribe Actions](/subscribe-actions).
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.region}}.myconnectwise.net`.

The ConnectWise connector supports reading from all standard objects and writing to most standard objects, including the following:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

See the official [OpenAPI](https://developer.connectwise.com/Products/ConnectWise_PSA/REST) file for the complete list. (Requires ConnectWise Developer Network account)

Connector supports write operations using a [JSON Patch document](https://datatracker.ietf.org/doc/html/rfc6902#section-3) passed in `record.patch`.
When performing an update, `record.id` must also be provided so the connector can resolve which record to patch.

Write payload example for the `contacts` object:

```json theme={"dark"}
{
  "groupRef": "{{connectWiseGroupID}}",
  "type": "update",
  "record": {
    "id": "58016",
    "patch": [
      {"op": "replace", "path": "/firstName", "value": "John"}
    ]
  }
}
```

### Custom Fields

The connector supports reading and writing custom fields on supported objects, and they behave like native fields.
For reads, they're available through scheduled reads, historical backfills, and subscriptions.

Each custom field is exposed as `customField<ID>`. Map it to a more readable name in your configuration with `mapToName`.

> Example: a field with ID `59` representing a marketing preference is selected as `customField59` and can be mapped to `marketingEmailOn`.

```yaml theme={"dark"}
read:
  objects:
    - objectName: contacts
      requiredFields:
        - fieldName: customField59
          mapToName: marketingEmailOn
        - fieldName: customField83
          mapToName: hobby
```

For writes, provide custom fields as if they were native fields; the connector converts them to the ConnectWise format automatically:

```json theme={"dark"}
{
  "firstName": "Estella",
  "customField59": true,
  "customField83": "Traveling"
}
```

You only need to include the custom fields you want to set or change. To clear a field, set its value to `null`.

To find a custom field's ID, check a read response; custom fields are returned with their IDs in the `customFields` array.

### Example integration

For an example manifest file of a ConnectWise integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/connectwise/amp.yaml).

### Contact Communication Items

ConnectWise stores a contact's email, phone, and fax numbers inside a nested `communicationItems` array, which isn't directly mappable.
To make these easy to read and write, the connector exposes the **default** email, phone, and fax of a contact
as flat fields, which you can map like any other contact field.

| Field | Description |
| - | - |
| `AMPERSAND-defaultEmail` | The contact's default email address |
| `AMPERSAND-defaultEmailId` | The communication type of that email |
| `AMPERSAND-defaultPhone` | The contact's default phone number |
| `AMPERSAND-defaultPhoneId` | The communication type of that phone |
| `AMPERSAND-defaultFax` | The contact's default fax number |
| `AMPERSAND-defaultFaxId` | The communication type of that fax |

Only the **default** item of each category is exposed. If a contact has several emails, only the one marked as default appears in `AMPERSAND-defaultEmail`.

#### Reading

Map these fields in a read action just like standard contact fields:

```yaml theme={"dark"}
read:
  objects:
    - objectName: contacts
      requiredFields:
        - fieldName: AMPERSAND-defaultEmail
```

A contact whose default email is `john@example.com` reads back as:

```json theme={"dark"}
{
  "AMPERSAND-defaultEmail": "john@example.com",
  "AMPERSAND-defaultEmailId": "15"
}
```

The `...Id` field identifies which communication type the default value belongs to. This matters when a contact has more than one item in the same category.

#### Writing

Map a value to `AMPERSAND-defaultEmail` (or phone/fax) to set it when creating or updating a contact:

* Set just the value, and the connector uses the customer's default type for that category.
* Set the matching `...Id` field too if you want to target a specific type (for example, a Work email vs a Home email).
  The value is applied to that type and marked as the default.

Updates replace the fields you send. Any fields you omit will be cleared.
For partial updates, see the [JSON Patch section below](#advanced-partial-updates-with-json-patch).

Example -- replace a contact:

```json theme={"dark"}
{
  "firstName": "John",
  "lastName": "Smith",
  "AMPERSAND-defaultEmail": "john@example.com"
}
```

<Note>
  The `...Id` fields refer to ConnectWise "communication types" configured in the customer's ConnectWise account.
  You only need them when a contact has more than one email, phone, or fax and you want to target a specific one.
</Note>

#### Advanced: partial updates with JSON Patch

If you call the write API directly, you can send a JSON Patch to change a single field, including these virtual fields:

```json theme={"dark"}
{
  "type": "update",
  "record": {
    "id": "58117",
    "patch": [
      { "op": "replace", "path": "/AMPERSAND-defaultEmail", "value": "john@example.com" }
    ]
  }
}
```

* `replace` on a value updates the current default item.
* `replace` on an `...Id` field switches which communication type is the default,
  (used together with `AMPERSAND-defaultEmail`, etc.)
* `remove` deletes the current default item for that category.

The connector translates these into the correct changes on the underlying `communicationItems` array.

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with ConnectWise:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://{{.region}}.myconnectwise.net`.

## Credential format for ConnectWise

ConnectWise uses a non-standard format for Basic Auth. The username and password fields do not correspond to the actual username and password that a customer uses to log in. Instead:

* **Username**: The username will always begin with `CompanyId+` (the plus sign is literal) and then use either the `public key`, `integrator username`, or `MemberId` (e.g. `mycompany+8mr4fDio4MBPsER2`).
* **Password**: The password will be the `private key`, `integrator password`, or `member hash`.

[Click here](https://developer.connectwise.com/Products/Manage/REST/Authentication) for more information about the expected credential format for ConnectWise. The UI components will display this link, so that your users can successfully provide their credentials.


# Constant Contact
Source: https://docs.ampersand.ai/provider-guides/constantContact



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Constant Contact instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.cc.email`.

The Constant Contact connector supports writing to and reading from the following objects:

* [account\_emails](https://v3.developer.constantcontact.com/api_reference/index.html#!/Account_Services/retrieveEmailAddresses)
* [activities](https://v3.developer.constantcontact.com/api_reference/index.html#!/Bulk_Activities/getActivityStatusCollection) (read only)
* [contact\_lists](https://v3.developer.constantcontact.com/api_reference/index.html#!/Contact_Lists/getLists)
* [contact\_tags](https://v3.developer.constantcontact.com/api_reference/index.html#!/Contact_Tags/getTags)
* [contacts](https://v3.developer.constantcontact.com/api_reference/index.html#!/Contacts/getContacts)
* [email\_campaign\_summaries](https://v3.developer.constantcontact.com/api_reference/index.html#!/Email_Reporting/getAllBulkEmailCampaignSummaries) (read only)
* [email\_campaign\_activities](https://v3.developer.constantcontact.com/api_reference/index.html#!/Email_Campaigns/updateEmailCampaignActivityUsingPUT) (write only)
* [email\_campaigns](https://v3.developer.constantcontact.com/api_reference/index.html#!/Email_Campaigns/retrieveEmailCampaignsUsingGET)
* [privileges](https://v3.developer.constantcontact.com/api_reference/index.html#!/Account_Services/getUserPrivileges) (read only)
* [segments](https://v3.developer.constantcontact.com/api_reference/index.html#!/Segments/getAccountSegments)

## Before you get started

To integrate Constant Contact with Ampersand, you must have a Constant Contact Developer account and obtain the necessary credentials.

Once your account is set up, you'll need to create an app in Constant Contact to get the following credentials:

* **Client ID**
* **Client Secret**

You will use these credentials to connect your application to Ampersand.

### Create a Constant Contact account

Here's how to sign up for a Constant Contact account:

1. Go to the [Constant Contact Sign Up page](https://v3.developer.constantcontact.com/login/index.html?_ga=2.74994962.1095369080.1723052125-94b8f87f-e462-4b81-9771-2b211eac0567&_gac=1.89512297.1720021371.Cj0KCQjw7ZO0BhDYARIsAFttkCjWgg2zwOvaQdS8IlbZamQr4AT9C2j_7t1Xm6EFPKJSJ7W0PHnV6gQaAi1WEALw_wcB).
2. Sign up using your preferred method and follow the instructions to create your account.

### Creating a Constant Contact app

Follow these steps to create an app in Constant Contact and add the Ampersand redirect URL:

1. Log in to your [Constant Contact Developer Account](https://v3.developer.constantcontact.com/login).

2. Go to **My Applications**.

3. Click the **New Application** button.

4. In the **New Application** dialog box, enter an **Application Name** for your app.

5. Select an **OAuth2 Flow**.

6. Choose a **Refresh Token** type.

7. Click **Create**.

<img alt="Constant Contact Client ID and Secret" />

### Adding Ampersand redirect URL in your app

Once your app is created, you will be redirected to the **My Applications** page. Select your newly created application from the list and add the following details to your application to set up OAuth in your app.

1. In the **Redirect URLs** section, click **Add another redirect URL**.
2. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
3. Click **Confirm**.
4. You will find your *Client ID* in the *API Key (Client ID)* section. Click **Generate Client Secret** to create a *Client Secret* key for your app. Be sure to note both the *Client ID* and *Client Secret*, as you will need these to connect your app to Ampersand.

<img alt="Constant Contact Client ID and Secret" />

<br />

### Add your Constant Contact app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Constant Contact integration.

   <img alt="Ampersand Project" />

3. Select **Provider apps**.

4. Select *Constant Contact* from the **Provider** list.

5. Enter the previously obtained **Client ID** and **Client Secret** in the respective fields.

   <img alt="Ampersand Constant Contact Integration" />

6. Click **Save Changes** to finalize the integration.


# Copper
Source: https://docs.ampersand.ai/provider-guides/copper



## What's Supported

### Supported Actions

This connector supports:

* [Write Actions](/write-actions).
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.copper.com/developer_api`.

### Supported Objects

The Copper connector supports reading from and writing to the following objects:

* [activities](https://developer.copper.com/activities/overview.html)
* [companies](https://developer.copper.com/companies/overview.html)
* [leads](https://developer.copper.com/leads/overview.html)
* [opportunities](https://developer.copper.com/opportunities/overview.html)
* [people](https://developer.copper.com/people/overview.html)
* [projects](https://developer.copper.com/projects/overview.html)
* [tasks](https://developer.copper.com/tasks/overview.html)

The Copper connector supports reading from the following objects:

* [activity\_types](https://developer.copper.com/activities/list-activity-types.html)
* [contact\_types](https://developer.copper.com/people/list-contact-types.html)
* [customer\_sources](https://developer.copper.com/leads/list-customer-sources.html#__tabbed_1_1)
* [lead\_statuses](https://developer.copper.com/leads/list-lead-statuses.html)
* [loss\_reasons](https://developer.copper.com/opportunities/list-loss-reasons.html)
* [pipeline\_stages](https://developer.copper.com/opportunities/list-pipeline-stages.html)
* [pipelines](https://developer.copper.com/opportunities/list-pipelines.html)
* [tags](https://developer.copper.com/tags/overview.html)
* [users](https://developer.copper.com/account-and-users/overview.html)

#### Custom Fields

In addition to standard fields, the connector supports any **custom fields** created through the Copper API.
They behave the same way as built-in fields and can be queried alongside them.

Copper does not provide a dedicated "field name" for custom fields.
To represent them, the connector uses the **display name** rather than the numeric ID, and exposes it with the prefix `custom_field_`.

* **Prefix**: Names always start with `custom_field_`.
* **Display name**: Human-readable display names are used instead of IDs, with spaces replaced by underscores.

> Example: A custom field with display name `Contract Start Date` in Copper is exposed as `custom_field_contract_start_date`.

## Before You Get Started

To integrate Copper CRM with Ampersand, you must register a *Copper CRM Oauth2* application. To register the application, you must contact `partners@copper.com` and provide the following details:

* **Name** and **Purpose** of your application.
* **URL** for an HTTPS endpoint that will handle the secure callback. If you want to connect via Ampersand, use the following callback URL: `https://api.withampersand.com/callbacks/v1/oauth`.

After registering your application, you'll receive two credentials: **client\_id** and **client\_secret**. These are required to connect with Ampersand.

## Add Your Copper CRM App Info to Ampersand

Once you have your Copper app set up and registered, you can proceed to connect it with Ampersand by following these steps:

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Copper CRM integration.

   <img alt="Ampersand Project Selection" />

3. Navigate to **Provider Apps**.

4. Select **Copper CRM** from the **Provider** list.

5. Enter the **Client ID** obtained from Copper in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Specify the scopes set for your application in Copper CRM.

7. Click **Save Changes** to complete the integration.


# Coupa
Source: https://docs.ampersand.ai/provider-guides/coupa



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}`.

### Example integration

To define an integration for Coupa, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: coupa-integration
    displayName: My Coupa Integration
    provider: coupa
    proxy:
      enabled: true
```

## Before you get started

To connect *Coupa* with *Ampersand*, you will need a [Coupa account](https://www.coupa.com).

Once your account is ready, you'll need to create a Coupa OAuth2 app and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will also need your **Coupa instance domain** (the `workspace` value), which is your Coupa instance URL (e.g., `mycompany.coupahost.com`).

### Creating a Coupa app

1. Log in to your Coupa instance as an administrator.
2. Navigate to **Setup** → **Oauth2 / OpenID Connect Clients**.
3. Click **Create** to register a new OAuth2 client.
4. Fill in the application name and description.
5. Under **Redirect URI**, add the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
6. Select the scopes your integration requires.
7. Click **Save**.
8. Copy the generated **Client ID** and **Client Secret**.

For more details, refer to the [Coupa API get started guide](https://compass.coupa.com/en-us/products/product-documentation/integration-technical-documentation/the-coupa-core-api/get-started-with-the-api).

### Add your Coupa app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a Coupa integration.
   <img alt="Ampersand Project Selection" />
3. Select **Provider apps**.
4. Select *Coupa* from the **Provider** list.
5. Enter the **Client ID** and **Client Secret** you copied earlier.
6. Enter the scopes your integration requires.
7. Click **Save changes**.

## Using the connector

To start integrating with Coupa:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization and their Coupa instance domain.
* Start using the connector!
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

Please note that this connector's base URL is `https://{{.workspace}}`, where `workspace` is your Coupa instance domain (e.g., `mycompany.coupahost.com`).


# Crunchbase
Source: https://docs.ampersand.ai/provider-guides/crunchbase



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.crunchbase.com`.

### Example integration

To define an integration for Crunchbase, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: crunchbase-integration
    displayName: My Crunchbase Integration
    provider: crunchbase
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Crunchbase:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.crunchbase.com`.

## Creating an API key for Crunchbase

[Click here](https://data.crunchbase.com/docs/getting-started) for more information about generating an API key for Crunchbase. The UI components will display this link, so that your users can successfully create API keys.


# Customer.io Journeys App
Source: https://docs.ampersand.ai/provider-guides/customerJourneysApp



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Customer Journeys App instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.customer.io`.

The Customer Journeys App connector supports writing to and reading from the following objects:

* [activities](https://docs.customer.io/api/app/#operation/listActivities) (read)
* [broadcasts](https://docs.customer.io/api/app/#operation/listBroadcasts) (read)
* [collections](https://docs.customer.io/api/app/#operation/getCollections) (read,create,update)
* [exports](https://docs.customer.io/api/app/#operation/listExports) (read)
* [messages](https://docs.customer.io/api/app/#operation/listMessages) (read)
* [newsletters](https://docs.customer.io/api/app/#operation/listNewsletters) (read)
* [object\_types](https://docs.customer.io/api/app/#operation/getObjectTypes) (read)
* [reporting\_webhooks](https://docs.customer.io/api/app/#operation/listWebhooks) (read,create,update)
* [segments](https://docs.customer.io/api/app/#operation/listSegments) (read,create)
* [sender\_identities](https://docs.customer.io/api/app/#operation/listSenders) (read)
* [snippets](https://docs.customer.io/api/app/#operation/listSnippets) (read,create)
* [subscription\_topics](https://docs.customer.io/api/app/#operation/getTopics) (read)
* [transactional](https://docs.customer.io/api/app/#operation/listTransactional) (read)
* [workspaces](https://docs.customer.io/api/app/#operation/listWorkspaces) (read)

Write-only objects:

* [customer\_exports](https://docs.customer.io/api/app/#operation/exportPeopleData) (create)
* [deliveries\_exports](https://docs.customer.io/api/app/#operation/exportDeliveriesData) (create)
* [imports](https://docs.customer.io/api/app/#operation/import) (create)

### Example integration

To define an integration for Customer.io Journeys App, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: customerJourneysApp-integration
    displayName: My Customer.io Journeys App Integration
    provider: customerJourneysApp
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Customer.io Journeys App:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.customer.io`.

## Creating an API key for Customer.io Journeys App

[Click here](https://customer.io/docs/api/app/#section/Authentication) for more information about generating an API key for Customer.io Journeys App. The UI components will display this link, so that your users can successfully create API keys.


# Customer.io Journeys Track
Source: https://docs.ampersand.ai/provider-guides/customerJourneysTrack



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://track.customer.io`.

### Example integration

To define an integration for Customer.io Journeys Track, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: customerJourneysTrack-integration
    displayName: My Customer.io Journeys Track Integration
    provider: customerJourneysTrack
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Customer.io Journeys Track:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://track.customer.io`.

## Credential format for Customer.io Journeys Track

Customer.io Journeys Track uses a non-standard format for Basic Auth, which means that the username and password fields do not correspond to the actual username and password that a customer uses to log in. [Click here](https://customer.io/docs/api/track/#section/Authentication) for more information about the expected credential format for Customer.io Journeys Track. The UI components will display this link, so that your users can successfully provide their credentials.


# Delighted
Source: https://docs.ampersand.ai/provider-guides/delighted



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL ` https://api.delighted.com`.

### Example integration

To define an integration for Delighted, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: Delighted-integration
    displayName: My Delighted Integration
    provider: delighted
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Delighted:

* Create a manifest file like the [example](#example-integration) above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is ` https://api.delighted.com`.


# DevRev
Source: https://docs.ampersand.ai/provider-guides/devrev



## What's Supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.devrev.ai`.

### Incremental read

Incremental read is available for every object that supports read, except the following. For these objects, each scheduled read is a full read.

* `articles`
* `auth-tokens`
* `code-changes`
* `directories`
* `org-schedules`
* `question-answers`
* `schemas.subtypes`
* `webhooks`
* `vistas.groups`

### Supported Objects

The DevRev connector supports the following objects.

* [accounts](https://developer.devrev.ai/api-reference/accounts/list) (read, write)
* [articles](https://developer.devrev.ai/api-reference/articles/list-articles) (read, write)
* [auth-tokens](https://developer.devrev.ai/api-reference/auth-tokens/list) (read, write)
* [dev-orgs.auth-connections](https://developer.devrev.ai/beta/api-reference/auth-connections/dev-org-auth-connections-list) (read, write)
* [chats](https://developer.devrev.ai/api-reference/chats/create) (write)
* [code-changes](https://developer.devrev.ai/api-reference/code-changes/list) (read, write)
* [commands](https://developer.devrev.ai/api-reference/commands/list) (read, write)
* [content-template](https://developer.devrev.ai/beta/api-reference/notifications/content-template-list) (read, write)
* [conversations](https://developer.devrev.ai/api-reference/conversations/list) (read, write)
* [custom-objects](https://developer.devrev.ai/api-reference/customization/custom-objects-create) (write)
* [dev-users](https://developer.devrev.ai/api-reference/dev-users/list) (read, write)
* [directories](https://developer.devrev.ai/api-reference/directory/directories-list) (read, write)
* [engagements](https://developer.devrev.ai/api-reference/works/list) (read, write)
* [groups](https://developer.devrev.ai/api-reference/groups/list) (read, write)
* [incidents](https://developer.devrev.ai/api-reference/works/list) (read, write)
* [link-types.custom](https://developer.devrev.ai/api-reference/links/list) (read, write)
* [meetings](https://developer.devrev.ai/api-reference/meetings/list) (read, write)
* [metric-definitions](https://developer.devrev.ai/api-reference/works/list) (read, write)
* [org-schedule-fragments](https://developer.devrev.ai/api-reference/schedules/org-schedule-fragments-create) (write)
* [org-schedules](https://developer.devrev.ai/api-reference/schedules/org-schedules-list) (read, write)
* [parts](https://developer.devrev.ai/api-reference/parts/list) (read, write)
* [question-answers](https://developer.devrev.ai/api-reference/surveys/list) (read, write)
* [rev-orgs](https://developer.devrev.ai/api-reference/rev-orgs/list) (read, write)
* [rev-users](https://developer.devrev.ai/api-reference/rev-users/list) (read, write)
* [roles](https://developer.devrev.ai/api-reference/dev-users/list) (write)
* [schemas.custom](https://developer.devrev.ai/beta/api-reference/customization/custom-schema-fragments-list) (read, write)
* [schemas.stock](https://developer.devrev.ai/beta/api-reference/customization/stock-schema-fragments-list) (read, write)
* [schemas.subtypes](https://developer.devrev.ai/beta/api-reference/customization/subtypes-list) (read, write)
* [sla-trackers](https://developer.devrev.ai/api-reference/slas/sla-trackers-list) (read, write)
* [service-accounts](https://developer.devrev.ai/beta/api-reference/service-accounts/create) (write)
* [slas](https://developer.devrev.ai/api-reference/slas/list) (read, write)
* [snap-widgets](https://developer.devrev.ai/beta/api-reference/snap-widgets/create) (write)
* [stage-diagrams](https://developer.devrev.ai/api-reference/works/list) (read, write)
* [stages.custom](https://developer.devrev.ai/api-reference/works/list) (read, write)
* [states.custom](https://developer.devrev.ai/api-reference/works/list) (read, write)
* [surveys](https://developer.devrev.ai/api-reference/surveys/list) (read, write)
* [surveys.responses](https://developer.devrev.ai/api-reference/surveys/list) (read, write)
* [sys-users](https://developer.devrev.ai/api-reference/sys-users/list) (read, write)
* [tags](https://developer.devrev.ai/api-reference/tags/list) (read, write)
* [uoms](https://developer.devrev.ai/api-reference/works/list) (read, write)
* [vistas](https://developer.devrev.ai/api-reference/vistas/list) (read)
* [vistas.groups](https://developer.devrev.ai/api-reference/vistas/list) (read)
* [web-crawler-jobs](https://developer.devrev.ai/api-reference/web-crawler-job/list-web-crawler-jobs) (read, write)
* [webhooks](https://developer.devrev.ai/api-reference/webhooks/list) (read, write)
* [works](https://developer.devrev.ai/api-reference/works/list) (read, write)

### Example integration

For an example manifest file of a DevRev integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/devrev/amp.yaml).

## Before you get started

To use the DevRev connector, you'll need a Personal Access Token (PAT) from your DevRev account. Here's how to get it:

1. In the DevRev app, go to the relevant dev org.
2. Go to **Settings** > **Account** > **Personal Access Token**.
3. Click **New token** and follow the workflow to create your PAT.

<img alt="DevRev API Key" />

For more details, see the [DevRev Authentication documentation](https://developer.devrev.ai/about/authentication).

## Using the connector

This connector uses Personal Access Token (PAT) authentication, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with DevRev:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/devrev/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Discord
Source: https://docs.ampersand.ai/provider-guides/discord



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://discord.com`.

## Before You Get Started

To connect Discord with Ampersand, you will need [a Discord Account](#create-a-discord-account).

Once your account is created, you'll need to configure an app in Discord and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a Discord Account

Here's how you can sign up for a Discord Developer account:

* Go to the [Discord Sign Up page](https://discord.com/register) and create an account.
* Sign up using your preferred method.

### Creating a Discord App

Follow the steps below to create a Discord app and add the Ampersand redirect URL in the app:

1. Log in to your [Discord Developer Portal](https://discord.com/developers/applications).
2. Click **New Application**.
3. Enter the **App Name** and click **Create**.
4. Enter in your app details and click the **Save changes** button.

   <img alt="Alt text" />
5. Go to the **OAuth2** tab.
6. In the **Redirects** section, click the **Add Redirect** button.
7. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` in the text field in the *Redirects* section.
8. Select the necessary scopes for your app from the **Scopes** section
9. Click **Save Changes**.

<img alt="Alt text" />

The **Oauth2** section displays **Client ID** and **Client Secret** keys for your app. You'll use these credentials to connect your app to [Ampersand](/provider-guides/discord#add-your-discord-app-info-to-ampersand).

## Add Your Discord App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Discord integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Discord* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Click **Save changes**.


# Discourse
Source: https://docs.ampersand.ai/provider-guides/discourse



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}`, where `workspace` is your Discourse-hosted domain.

### Example integration

To define an integration for Discourse, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: discourse-integration
    displayName: My Discourse Integration
    provider: discourse
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth along with an API Username, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

<Note>
  The API Username is currently set to `system` for everyone. Please use `system` as the username when configuring your integration. For more information, see the [Discourse API documentation](https://docs.discourse.org/).
</Note>

To start integrating with Discourse:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key and API Username supplied by the customer. Please note that this connector's base URL is `https://{{.workspace}}`.

## Creating an API key for Discourse

[Click here](https://docs.discourse.org/) for more information about generating an API key for Discourse.


# Dixa
Source: https://docs.ampersand.ai/provider-guides/dixa



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Dixa instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://dev.dixa.io`.

### Supported Objects

The Dixa connector supports reading from the following objects:

* [agents](https://docs.dixa.io/openapi/dixa-api/v1/tag/Agents/#tag/Agents/operation/getAgents)
* [knowledge/collections](https://docs.dixa.io/openapi/dixa-api/v1/tag/Knowledge/#tag/Knowledge/operation/getKnowledgeCollections)
* [custom-attributes](https://docs.dixa.io/openapi/dixa-api/v1/tag/Custom-Attributes/#tag/Custom-Attributes/operation/getCustom-attributes)
* [endusers](https://docs.dixa.io/openapi/dixa-api/v1/tag/End-Users/#tag/End-Users/operation/getEndusers)
* [conversations/flows](https://docs.dixa.io/openapi/dixa-api/v1/tag/Conversations/#tag/Conversations/operation/getConversationsFlows)
* [agents/presence](https://docs.dixa.io/openapi/dixa-api/v1/tag/Agents/#tag/Agents/operation/getAgentsPresence)
* [queues](https://docs.dixa.io/openapi/dixa-api/v1/tag/Queues/#tag/Queues/operation/getQueues)
* [analytics/records](https://docs.dixa.io/openapi/dixa-api/v1/tag/Analytics/#tag/Analytics/operation/getAnalyticsRecords)
* [tags](https://docs.dixa.io/openapi/dixa-api/v1/tag/Tags/#tag/Tags/operation/getTags)
* [teams](https://docs.dixa.io/openapi/dixa-api/v1/tag/Teams/#tag/Teams/operation/getTeams)
* [webhooks](https://docs.dixa.io/openapi/dixa-api/v1/tag/Webhooks/#tag/Webhooks/operation/getWebhooks)
* [contact-endpoints](https://docs.dixa.io/openapi/dixa-api/v1/tag/Contact-Endpoints/#tag/Contact-Endpoints/operation/getContact-endpoints)
* [business-hours/schedules](https://docs.dixa.io/openapi/dixa-api/v1/tag/Business-Hours/#tag/Business-Hours/operation/getBusiness-hoursSchedules)
* [templates](https://docs.dixa.io/openapi/dixa-api/v1/tag/Templates/#tag/Templates/operation/getTemplates)

The Dixa connector supports writing to the following objects:

* [agents](https://docs.dixa.io/openapi/dixa-api/v1/tag/Agents/#tag/Agents/operation/postAgents)
* [conversations](https://docs.dixa.io/openapi/dixa-api/v1/tag/Conversations/#tag/Conversations/operation/postConversations)
* [conversations/import](https://docs.dixa.io/openapi/dixa-api/v1/tag/Conversations/#tag/Conversations/operation/postConversationsImport)
* [queues](https://docs.dixa.io/openapi/dixa-api/v1/tag/Queues/#tag/Queues/operation/postQueues)
* [tags](https://docs.dixa.io/openapi/dixa-api/v1/tag/Tags/#tag/Tags/operation/postTags)
* [teams](https://docs.dixa.io/openapi/dixa-api/v1/tag/Teams/#tag/Teams/operation/postTeams)
* [webhooks](https://docs.dixa.io/openapi/dixa-api/v1/tag/Webhooks/#tag/Webhooks/operation/postWebhooks)
* [endusers](https://docs.dixa.io/openapi/dixa-api/v1/tag/End-Users/#tag/End-Users/operation/postEndusers)

### Example integration

For an example manifest file of a Dixa integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/dixa/amp.yaml).

## Before You Get Started

### Creating an API key for Dixa

[Click here](https://docs.dixa.io/docs/api-standards-rules/#authentication) for more information about generating an API key for Dixa. The UI components will display this link, so that your users can successfully create API keys.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Dixa:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/dixa/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Docusign
Source: https://docs.ampersand.ai/provider-guides/docusign



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.server}}.docusign.net`.

## Before You Get Started

To integrate with DocuSign, you will need a [DocuSign Developer Account](https://developers.docusign.com/). This account allows you to create and test your app in an isolated environment. Once your account is created, you'll need to create an app in DocuSign, configure the necessary settings, and obtain the following credentials from your app:

* Integration Key (Client ID)
* Secret Key
* Scopes

### Create a DocuSign Developer Account

Here's how you can sign up for a DocuSign Developer account:

* Go to the [DocuSign Developer Center](https://developers.docusign.com/).
* Click on **Developer Account** at the top of the page, then choose **Create Account**.
* Sign up using your preferred method.

### Creating a DocuSign App

Follow the steps below to create a DocuSign app and obtain the necessary keys.

1. Log in to your [DocuSign Developer](https://account-d.docusign.com/oauth/auth?response_type=code\&redirect_uri=https%3A%2F%2Fdevelopers.docusign.com%2Fauth%2Fdocusign-demo%2Fcallback\&scope=manage_app_keys%20signature%20openid%20cors%20click.manage%20click.send%20organization_read%20group_read%20permission_read%20user_read%20user_write%20account_read%20domain_read%20identity_provider_read%20user_data_redact%20dtr.rooms.read%20dtr.rooms.write%20dtr.documents.read%20dtr.documents.write%20dtr.profile.read%20dtr.profile.write%20dtr.company.read%20dtr.company.write%20room_forms%20notary_write%20notary_read%20spring_read%20spring_write%20webforms_read%20webforms_instance_read%20webforms_instance_write%20aow_manage\&state=https%3A%2F%2Fdevelopers.docusign.com%2F\&client_id=f0f27f0e-857d-4a71-a4da-32cecae3a978) account.
2. Click on your profile icon, and select **Apps and Keys**.
3. Navigate to **Apps and Keys** under **My Apps**.
4. Click **Add App and Integration Key**.
5. Enter **App Name** and click **Create**.
6. Uncheck the **Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows** checkbox.
7. Click **Add Secret Key**.

> 🗒️ Please note down your **Integration Key** and **Secret Key** as you will need these keys to connect your DocuSign app with Ampersand.

8. In the **Additional Settings** section, click **Add URI** and enter the Ampersand Redirect URI: `https://api.withampersand.com/callbacks/v1/oauth`.

<img alt="Alt text" />

9. Click **Save**.

## Connecting Your Docusign Developer App to Ampersand

Follow the steps below to connect your Docusign Developer App to Ampersand:

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Docusign integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Docusign Developer* from the **Provider** list.

5. Enter the previously obtained *Integration Key* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Enter the scopes for your app. Go to [Scopes](https://developers.docusign.com/platform/auth/reference/scopes/) for more details on the authentication scopes.

7. Click **Save changes**.

## Connecting Your Docusign Production App to Ampersand

When you're ready to launch your app in a production environment, you need to promote your integration key from your developer account to a production DocuSign account. Refer to the [Go Live](https://developers.docusign.com/docs/esign-rest-api/go-live/) documentation to learn how to launch your app in the production environment.

With this, you'll be able to successfully create, test, and promote your DocuSign app to a production environment.

Once your application is promoted to a production environment, follow the steps below to connect your Docusign Production App to Ampersand:

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Docusign integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Docusign* from the **Provider** list.

5. Enter the previously obtained *Integration Key* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Enter the scopes for your app. Go to [Scopes](https://developers.docusign.com/platform/auth/reference/scopes/) for more details on the authentication scopes.

7. Click **Save changes**.


# Domo
Source: https://docs.ampersand.ai/provider-guides/domo



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.domo.com`.

## Before you get started

To connect Domo with Ampersand, you will need a [Domo account](https://www.domo.com/).

### Example integration

To define an integration for Domo, create a manifest file that looks like this:

```YAML theme={"dark"}
#amp.yaml
specVersion: 1.0.0
integrations: 
  - name: domoIntegration
    displayName: Domo
    provider: domo
    proxy:
      enabled: true
```

## Creating a Domo client application

Follow these steps to create a client application in Domo:

1. Log in to your [Domo Developer Portal](https://developer.domo.com/).
2. Navigate to **My Account**
3. Click **New Client**.
4. Enter a name for your application and select the appropriate scopes based on your integration needs.
5. Click **Create**.

## Using the connector

This connector uses OAuth2 Client Credentials grant type, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Domo:

* Create a manifest file using the [example](#example-integration) above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically handle the authentication with Domo.

## API documentation

For more information about the Domo API, refer to the [Domo API documentation](https://developer.domo.com/portal/8ba9aedad3679-ap-is).


# Dovetail
Source: https://docs.ampersand.ai/provider-guides/dovetail



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://dovetail.com/api`.

### Supported objects

Dovetail is supported through Proxy Actions only. Use the proxy to call any [Dovetail Public API](https://developers.dovetail.com/reference) endpoint, for example `GET /v1/projects`.

## Before you get started

This connector uses API Key authentication. You do not need to create a provider app in the Ampersand Dashboard.

### Create a Dovetail API token

1. Go to your [Dovetail account settings](https://dovetail.com/settings/user/account).
2. Enter a label for the key and create it.
3. Copy the token and store it securely. Dovetail shows it only once.

<img alt="Dovetail API token creation" />

Dovetail API tokens are prefixed with `api.`. For details, see Dovetail's [authorization documentation](https://developers.dovetail.com/docs/authorization).

## Using the connector

To start integrating with Dovetail:

* Create a manifest file using the [proxy-only example](https://github.com/amp-labs/samples/blob/main/dovetail/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their Dovetail API token.
* Start making [Proxy Actions](/proxy-actions) API calls against `https://dovetail.com/api`.


# Drift
Source: https://docs.ampersand.ai/provider-guides/drift



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Drift instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://driftapi.com`.

### Supported Objects

The Drift connector supports reading from the following objects:

* [users](https://devdocs.drift.com/docs/listing-users)
* [conversations](https://devdocs.drift.com/docs/list-conversations)
* [teams/org](https://devdocs.drift.com/docs/listing-teams-org)
* [users/meetings/org](https://devdocs.drift.com/docs/get-booked-meetings)
* [playbooks](https://devdocs.drift.com/docs/get-playbooks)
* [playbooks/clp](https://devdocs.drift.com/docs/retrieve-conversational-landing-pages)
* [conversations/stats](https://devdocs.drift.com/docs/bulk-conversation-statuses)
* [scim/Users](https://devdocs.drift.com/docs/searching)

The Drift connector supports writing to the following objects:

* [contacts](https://devdocs.drift.com/docs/creating-a-contact)
* [contacts/timeline](https://devdocs.drift.com/docs/posting-timeline-events)
* [emails/unsubscribe](https://devdocs.drift.com/docs/unsubscribe-contacts-from-emails)
* [conversations](https://devdocs.drift.com/docs/creating-a-conversation)
* [accounts/create](https://devdocs.drift.com/docs/creating-an-account)
* [accounts/update](https://devdocs.drift.com/docs/updating-accounts)
* [scim/Users](https://devdocs.drift.com/docs/searching)

### Example integration

For an example manifest file of a Drift integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/drift/amp.yaml).

## Before You Get Started

To integrate Drift with Ampersand, you will need [a Drift Account](https://app.drift.com/signup).

Once your account is created, you'll need to create an app in Drift, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Drift Account

Here's how you can sign up for a Drift account:

* Go to the [Drift Sign Up page](https://app.drift.com/signup).
* Sign up using your preferred method.

### Creating a Drift App

Follow the steps below to create a Drift app and add the Ampersand redirect URL.

1. Log in to your [Drift](https://app.drift.com/login) account.

2. Navigate to the [Drift Developer Portal](https://dev.drift.com/).

3. Click the **Build Your App** button under Your Apps to create a new app.

4. Enter the app details in the **Display Information** section, including the app's name, description, and icon.

<img alt="Alt text" />

5. Go to the **OAuth and Scopes** section.
6. In the **Allowed Oauth Redirect URIs** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
7. Click **Add**.
8. Select the necessary permission scopes to your app from the **Drift Scopes** section.

<img alt="Alt text" />

9. Under the **Activate Your App** section, click the **Install App to Drift** button.

Your app is now ready to connect to Ampersand.

The **App Credentials** section displays **Client ID** and **Client Secret** keys for your app. You'll use these credentials to connect your app to [Ampersand](/provider-guides/drift#add-your-drift-app-info-to-ampersand).

## Add Your Drift App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Drift integration.

   <img alt="Alt text" />

3. Select **Provider Apps**.

4. Select *Drift* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save Changes**.


# Drip
Source: https://docs.ampersand.ai/provider-guides/drip



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.getdrip.com`.

## Before You Get Started

To connect Drip with Ampersand, you need [a Drip Account](https://www.drip.com/signup).

Once your account is created, you'll need to contact the support team to enable OAuth, and you'll also need to create an app in Drip to obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Drip Account

Here's how you can sign up for a Drip account:

* Go to the [Drip Sign Up page](https://www.drip.com/signup).
* Sign up using your preferred method.

### Creating a Drip App

Follow the steps below to create a Drip app and add the Ampersand redirect URL.

1. Log in to your [Drip](https://login.getdrip.com) account.

2. Go to **Settings > User Settings > OAuth Applications** in your Drip account.

3. Enter the application name in the **Application Name** section.

4. Click the **Create Application**.

5. In the **Callback URIs** section, add the Ampersand Redirect URI: [https://api.withampersand.com/callbacks/v1/oauth](https://api.withampersand.com/callbacks/v1/oauth).

6. Multiple URLs can be entered in the **Callback URI** field by separating each URL with a space.

7. Click **Save**. Next, you will need to **Activate** the app.

   <img alt="Drip App Creation" />

## Add Your Drip App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Drip integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Drip* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Ampersand Integration" />


# Dropbox
Source: https://docs.ampersand.ai/provider-guides/dropbox



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.dropboxapi.com`.

## Before You Get Started

To integrate Dropbox with Ampersand, you will need a [Dropbox Account](https://www.dropbox.com/register).

Once your account is created, you'll need to create an app in Dropbox, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* App Key
* App Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Dropbox Account

Here's how you can sign up for a Dropbox account:

* Go to the [Dropbox Sign Up page](https://www.dropbox.com/register) and create an account.
* Sign up using your preferred method.

### Creating a Dropbox App

Follow the steps below to create a Dropbox app:

1. Log in to your [Dropbox Developer Console](https://www.dropbox.com/developers/apps).
2. Click **Create app**.
3. Select **Scoped access**. This defines the level of scopes for your app.
4. Choose the type of access your app needs (*Full Dropbox* or *App folder*).
5. Enter the **Name of your app**.

<br />

<img alt="Alt text" />

6. Accept the **Dropbox API Terms and Conditions**.
7. Click **Create app**.

You'll find the **App Key** and **App Secret** keys for your app in the app **Settings** section. Note these credentials as they are necessary for connecting your app to Ampersand.

### Setting Scopes for Your Dropbox App

1. In the **Permissions** section, check the boxes next to the scopes that you need for your application.

<img alt="Alt text" />

### Adding Ampersand Redirect URI

1. In the **OAuth 2 Redirect URIs** section, enter the Ampersand **Redirect URI**: `https://api.withampersand.com/callbacks/v1/oauth`.

<img alt="Alt text" />

<br />

## Add Your Dropbox App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Dropbox integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Dropbox* from the **Provider** list.

5. Enter the previously obtained *App Key* in the **Client ID** field and the *App Secret* in the **Client Secret** field.

<img alt="Alt text" />

6. Click **Save changes**.


# Dropbox Sign
Source: https://docs.ampersand.ai/provider-guides/dropboxsign



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Dropbox Sign instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.hellosign.com`.

### Supported objects

The Dropbox Sign connector supports reading from the following objects:

* [api\_app](https://developers.hellosign.com/api/reference/operation/apiAppList/)
* [bulk\_send\_job](https://developers.hellosign.com/api/reference/operation/bulkSendJobList/)
* [fax](https://developers.hellosign.com/api/reference/operation/faxList/)
* [fax\_line](https://developers.hellosign.com/api/reference/operation/faxLineList/)
* [signature](https://developers.hellosign.com/api/reference/operation/signatureRequestList/)
* [template](https://developers.hellosign.com/api/reference/operation/templateList/)

The Dropbox Sign connector supports writing to the following objects:

* [account](https://developers.hellosign.com/api/reference/operation/accountCreate/)
* [api\_app](https://developers.hellosign.com/api/reference/operation/apiAppCreate/)
* [draft](https://developers.hellosign.com/api/reference/operation/unclaimedDraftCreate/)
* [fax\_line](https://developers.hellosign.com/api/reference/operation/faxLineCreate/)
* [report](https://developers.hellosign.com/api/reference/operation/reportCreate/)
* [signature/embedded](https://developers.hellosign.com/api/reference/operation/signatureRequestCreateEmbedded/)
* [signature/embedded\_with\_template](https://developers.hellosign.com/api/reference/operation/signatureRequestCreateEmbeddedWithTemplate/)
* [team](https://developers.hellosign.com/api/reference/operation/teamCreate/)
* [template](https://developers.hellosign.com/api/reference/operation/templateCreate/)

### Example integration

For an example manifest file of a Dropbox Sign integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/dropbox-sign/amp.yaml).

## Before You Get Started

To integrate Dropbox Sign with Ampersand, you will need a [Dropbox Sign Account](https://sign.dropbox.com/).

Once your account is created, you'll need to create an app in Dropbox Sign, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Oauth Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Dropbox Account

Here's how you can sign up for a Dropbox account:

* Create an account from the [Dropbox Sign](https://sign.dropbox.com/) page.
* Sign up using your preferred method.

### Creating a Dropbox App

Follow the steps below to create a Dropbox app:

1. Log in to your [Dropbox Sign Account](https://app.hellosign.com/).
2. Go to **API**.
3. Click **Create app**.
4. Enter the following details in the **General Information** section:
   * **Name**: Enter a unique name for your app.
   * **Domain**: Enter the app domain.
5. In the **Oauth** section, select the **Enable OAuth for this app** checkbox.
6. In the **OAuth Callback** textbox, enter the **Ampersand** redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
7. Select the applicable scopes.
8. Click **CREATE APPLICATION**.

<img alt="Alt text" />

Once the app is created, you'll find the **Client ID** and **OAuth Secret** keys for your app in the app **Details** section of your app. Note these credentials as they are necessary for connecting your app to Ampersand.

## Add Your Dropbox Sign App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Dropbox integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Dropbox* from the **Provider** list.

5. Enter the previously obtained *App Key* in the **Client ID** field and the *App Secret* in the **Client Secret** field.

<img alt="Alt text" />

6. Click **Save changes**.

## Using the connector

To start integrating with Dropbox Sign:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Dynamics 365 Business Central
Source: https://docs.ampersand.ai/provider-guides/dynamicsBusinessCentral



## What's Supported

### Supported Actions

This connector supports:

* [Write Actions](/write-actions).
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.businesscentral.dynamics.com`.

### Supported Objects

The Dynamics 365 Business Central connector supports reading from and writing to a wide range of objects. Notable examples include:

* [accounts](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_account#properties)
* [attachments](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_attachment#properties)
* [balanceSheets](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_balancesheet#properties)
* [companies](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_company#properties)
* [dimensions](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_dimension#properties)
* [employees](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_employee#properties)
* [itemCategories](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_itemcategory#properties)
* [journals](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_journal#properties)
* [locations](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_location#properties)
* [paymentMethods](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_paymentmethod#properties)
* [projects](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_project#properties)
* [purchaseInvoices](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_purchaseinvoice#properties)
* [purchaseReceipts](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_purchasereceipt#properties)
* [salesInvoices](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_salesinvoice#properties)
* [salesOrders](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_salesorder#properties)
* [salesQuotes](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_salesquote#properties)
* [shipmentMethods](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_shipmentmethod#properties)
* [taxGroups](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_taxgroup#properties)
* [vendors](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_vendor#properties)

Note: Letter casing for object names is not case-sensitive. For example, `balanceSheets`, `BalanceSheets`, and `balancesheets` are treated the same.

## Before You Get Started

To connect **Microsoft Dynamics 365 Business Central** with **Ampersand**, you will need an active [Microsoft Dynamics 365 Business Central Account](https://dynamics.microsoft.com/en-us/crm/).

Once your account is set up, you'll need to register an application in the **Microsoft Entra** developer portal. After registering your app, you will need to configure it and obtain the following credentials:

* **Application (client) ID**
* **Client Secret**

You will then use these credentials to connect Dynamics 365 CRM to Ampersand.

### Create a Microsoft Dynamics 365 Business Central Account

Here's how you can sign up for a Microsoft Dynamics 365 Business Central account:

* Go to the [Microsoft Dynamics 365 Business Central website](https://www.microsoft.com/en-us/dynamics-365/products/business-central) and sign up for a new account or start a free trial.
* If you don't have a **Microsoft Entra** (formerly Azure Active Directory) tenant, follow the instructions in [Set up Microsoft Entra ID access for your Developer Site](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-create-new-tenant) to associate your Microsoft 365 subscription with an Azure subscription.

### Register a Microsoft Dynamics 365 Business Central App

Follow the steps below to register a **Microsoft Dynamics 365 Business Central** app:

1. Go to the [Microsoft Azure portal](https://portal.azure.com/#home) and sign in with an administrator account from your Microsoft 365 subscription.
2. On the Home page, under **Azure services**, select **Microsoft Entra ID**.
3. In the left navigation pane, select **App registrations**.
4. Click **+ New registration**.
5. Enter Application Details:
   * **Name**: Enter a meaningful name for the application.
   * **Supported account types**: Select **Accounts in any or this organizational directory**.
6. In the **Redirect URIs** section, enter the **Ampersand** redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
7. In the left navigation panel, select **API permissions** > **Add a permission**.
8. Under the **APIs my organization uses** tab, select **Microsoft Dynamics 365 Business Central**.
9. Select the applicable permissions.

<img alt="MS Dynamics App Creation" />

### Obtain Client ID and Client Secret

1. On the **Overview** page, you'll find the **Application (client) ID**. Copy it.
2. In the left navigation pane, select **Certificates & secrets**.
3. Click **+ New client secret**, provide a description and expiration period, then click **Add**. Copy the client secret value.

<img alt="MS Dynamics App Creation" />

## Add Your Dynamics 365 CRM App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Dynamics 365 CRM integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Dynamics 365** from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

   <img alt="Ampersand Project Selection" />

6. In the **Scopes** field, enter the scopes your integration requires.

   <Warning>You must include `offline_access` in the Scopes field. Without it, Ampersand will not receive a refresh token and your customers will need to reauthenticate each time their access token expires.</Warning>

   <Info>
     Dynamics requires certain scopes to have the resource prefixed to the scope, which in this case is the consumer's instance URL. Ampersand will prefix the instance URL for you, so you only need to provide the scope name.

     For example, if you provide `.default` as the scope name and your customer's Dynamics instance URL is `https://tenant.api.dynamics.com`, then Ampersand will transform this scope to be `https://tenant.api.dynamics.com/.default`.
   </Info>

7. Click **Save Changes**.


# Dynamics 365 CRM
Source: https://docs.ampersand.ai/provider-guides/dynamicsCRM



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the DynamicsCRM instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.api.crm.dynamics.com/api/data`.

### Supported Objects

The Microsoft Dynamics 365 CRM connector supports reading from and writing to all available objects in the
Microsoft Dynamics 365 Sales, Customer Service, and Field Service modules,
which together contain more than 1000 tables, some examples include:

* [catalogs](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/catalog?view=dataverse-latest) ([read-only fields](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/reference/entities/catalog#read-only-columnsattributes), [write-only fields](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/reference/entities/catalog#writable-columnsattributes))
* [contacts](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/contact?view=dataverse-latest) ([read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/contact#read-only-columnsattributes), [writable fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/contact#writable-columnsattributes))
* discounts ([read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/discount#read-only-columnsattributes), [writable fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/discount#writable-columnsattributes))
* [goal](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/goal?view=dataverse-latest) ([read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/goal#read-only-columnsattributes), [writable fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/goal#writable-columnsattributes))
* leads ([read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/lead#read-only-columnsattributes), [writable fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/lead#writable-columnsattributes))
* lists (Marketing list [read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/list#read-only-columnsattributes), [writable fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/list#writable-columnsattributes))
* [msdyn\_aitemplates](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/msdyn_aitemplate?view=dataverse-latest) ([read-only fields](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/reference/entities/msdyn_aitemplate#read-only-columnsattributes), [write-only fields](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/reference/entities/msdyn_aitemplate#writable-columnsattributes))
* opportunities ([read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/opportunity#read-only-columnsattributes), [write-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/opportunity#writable-columnsattributes))
* products ([read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/product#read-only-columnsattributes), [write-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/product#writable-columnsattributes))
* quotes ([read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/quote#read-only-columnsattributes), [write-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/quote#writable-columnsattributes))
* salesorders ([read-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/salesorder#read-only-columnsattributes), [write-only fields](https://learn.microsoft.com/en-us/dynamics365/sales/developer/entities/salesorder#writable-columnsattributes))

Product‑specific objects are supported:

* Objects in the [Dynamics 365 Sales tables reference](https://learn.microsoft.com/en-us/dynamics365/sales/developer/about-entity-reference)
* Objects in the [Dynamics 365 Customer Service tables reference](https://learn.microsoft.com/en-us/dynamics365/customer-service/develop/reference/about-entity-reference)
* Objects in the [Dynamics 365 Field Service tables reference](https://learn.microsoft.com/en-us/dynamics365/field-service/developer/reference/about-entity-reference)

In addition, the connector supports all the objects in the [Dataverse tables reference](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/reference/about-entity-reference),
which are available in every Dynamics 365 environment regardless of the specific app you have licensed, you can think of them as core out-of-the-box objects.

### Example Integration

For an example manifest file of a Dynamics CRM integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/dynamicsCRM/%20amp.yaml).

## Before You Get Started

To connect **Microsoft Dynamics 365 CRM** with **Ampersand**, you will need an active [Microsoft Dynamics 365 CRM Account](https://dynamics.microsoft.com/en-us/crm/).

Once your account is set up, you'll need to register an application in the **Microsoft Entra** developer portal. After registering your app, you will need to configure it and obtain the following credentials:

* **Application (client) ID**
* **Client Secret**

You will then use these credentials to connect Dynamics 365 CRM to Ampersand.

### Create a Microsoft Dynamics 365 CRM Account

Here's how you can sign up for a Microsoft Dynamics 365 CRM account:

* Go to the [Microsoft Dynamics 365 CRM website](https://www.microsoft.com/en-us/dynamics-365/free-trial) and sign up for a new account or start a free trial.
* If you don't have a **Microsoft Entra** (formerly Azure Active Directory) tenant, follow the instructions in [Set up Microsoft Entra ID access for your Developer Site](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-create-new-tenant) to associate your Microsoft 365 subscription with an Azure subscription.

### Register a Microsoft Dynamics 365 CRM App

Follow the steps below to register a **Microsoft Dynamics 365 CRM** app:

1. Go to the [Microsoft Azure portal](https://portal.azure.com/#home) and sign in with an administrator account from your Microsoft 365 subscription.
2. On the Home page, under **Azure services**, select **Microsoft Entra ID**.
3. In the left navigation pane, select **App registrations**.
4. Click **+ New registration**.
5. Enter Application Details:
   * **Name**: Enter a meaningful name for the application.
   * **Supported account types**: Select **Accounts in any or this organizational directory**.
6. In the **Redirect URIs** section, enter the **Ampersand** redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
7. In the left navigation panel, select **API permissions > Add a permission**.
8. Under the **APIs my organization uses** tab, select **Microsoft Dynamics 365 CRM**.
9. Select the applicable permissions.

<img alt="MS Dynamics App Creation" />

### Obtain Client ID and Client Secret

1. On the **Overview** page, you'll find the **Application (client) ID**. Copy it.
2. In the left navigation pane, select **Certificates & secrets**.
3. Click **+ New client secret**, provide a description and expiration period, then click **Add**. Copy the client secret value.

## Add Your Dynamics 365 CRM App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Dynamics 365 CRM integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Dynamics 365** from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

   <img alt="Ampersand Project Selection" />

6. In the **Scopes** field, enter the scopes your integration requires.

   <Warning>You must include `offline_access` in the Scopes field. Without it, Ampersand will not receive a refresh token and your customers will need to reauthenticate each time their access token expires.</Warning>

   <Info>
     Dynamics requires certain scopes to have the resource prefixed to the scope, which in this case is the consumer's instance URL. Ampersand will prefix the instance URL for you, so you only need to provide the scope name.

     For example, if you provide `.default` as the scope name and your customer's Dynamics instance URL is `https://org.crm.dynamics.com`, then Ampersand will transform this scope to be `https://org.crm.dynamics.com/.default`.
   </Info>

7. Click **Save Changes**.

## Using the connector

To start integrating with Dynamics CRM:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/dynamicsCRM/%20amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# EmailBison
Source: https://docs.ampersand.ai/provider-guides/emailBison



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}/api`.

### Example integration

To define an integration for EmailBison, create a manifest file that looks like this:

```YAML theme={"dark"}
#amp.yaml
specVersion: 1.0.0
integrations: 
  - name: emailbison-integration
    displayName: EmailBison
    provider: emailBison
    proxy:
      enabled: true
```

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with EmailBison:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key provided by the customer. Please note that this connector's base URL is `https://{{.workspace}}/api`.

## Creating an API key for EmailBison

1. Log in to your EmailBison account.
2. Click **Settings** and navigate to **Developer API**.
3. Click **New API Token**.
4. Enter the token name in the **Token Name** section.
5. Select the **Token Type** then click **Generate Token**.
   <img alt="Generate Token" />


# Fathom
Source: https://docs.ampersand.ai/provider-guides/fathom



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `meetings` currently. For all other objects, a full read of the Fathom instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.fathom.ai`.

### Supported Objects

The Fathom connector supports writing to and reading from the following objects:

* [meetings](https://docs.fathom.ai/api-reference/meetings/list-meetings) (read)
* [teams](https://docs.fathom.ai/api-reference/teams/list-teams) (read)
* [team\_members](https://docs.fathom.ai/api-reference/team-members/list-team-members) (read)
* [webhooks](https://docs.fathom.ai/api-reference/webhooks/create-webhook) (write)

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. Provider apps are only required for providers that use OAuth2 Authorization Code grant type.

To start integrating with Fathom:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/fathom/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Fathom

* Log in to your Fathom account
* Go to **Settings** > **Integrations**
* Click on the *Add* in API Access
* Click on **Generate API Key**

## API documentation

For more detailed information about Fathom API, refer to the [Fathom API documentation](https://docs.fathom.ai).


# Figma
Source: https://docs.ampersand.ai/provider-guides/figma



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.figma.com`.

## Before You Get Started

To integrate Figma with Ampersand, you will need a [Figma Account](https://www.figma.com/signup).

Once your account is created, you'll need to create an app in Figma, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials and scopes to connect your application to Ampersand.

### Create a Figma Account

Here's how you can sign up for a Figma account:

* Go to the [Figma Sign Up page](https://www.figma.com/signup) and create an account.
* Sign up using your preferred method.

### Creating a Figma App

Follow the steps below to create a Figma app:

1. Log in to your [Figma Developer Console](https://www.figma.com/developers).
2. Click **My Apps**.
3. Click **Create a new app**.
4. Enter the **App Name** and **Website URL**.
5. Load your App **Logo**.
6. In the **Callbacks** section, click **Add Callback** and enter the Ampersand **Callback URI**: `https://api.withampersand.com/callbacks/v1/oauth`.
7. Click **Save**.

<img alt="Alt text" />

You'll find the **Client ID** and **Client Secret** keys for your app in the following section. Note these credentials as they are necessary for connecting your app to Ampersand.

<br />

## Add Your Figma App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Figma integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Figma* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Enter the scopes set for your application in *Figma*. For more details on the scopes, go to [Figma Authentication Scopes](https://www.figma.com/developers/api#authentication-scopes) document.

   <img alt="Alt text" />

7. Click **Save changes**.


# Fireflies
Source: https://docs.ampersand.ai/provider-guides/fireflies



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `transcripts` and `analytics` objects.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.fireflies.ai`.

<Note>
  You will need to use the `graphql` endpoint to make proxy requests. (i.e. `https://proxy.withampersand.com/graphql`)
</Note>

### Supported Objects

The Fireflies connector supports reading from the following objects:

* [users](https://docs.fireflies.ai/graphql-api/query/users)
* [transcripts](https://docs.fireflies.ai/graphql-api/query/transcripts)
* [bites](https://docs.fireflies.ai/graphql-api/query/bites)
* [userGroups](https://docs.fireflies.ai/graphql-api/query/user-groups)
* [activeMeetings](https://docs.fireflies.ai/graphql-api/query/active-meetings)
* [analytics](https://docs.fireflies.ai/graphql-api/query/analytics)

The Fireflies connector supports writing to the following objects:

* [transcripts](https://docs.fireflies.ai/graphql-api/mutation/delete-transcript)
* [bites](https://docs.fireflies.ai/graphql-api/mutation/create-bite)
* [liveMeetings](https://docs.fireflies.ai/graphql-api/mutation/add-to-live)
* [meetingTitle](https://docs.fireflies.ai/graphql-api/mutation/update-meeting-title)
* [userRole](https://docs.fireflies.ai/graphql-api/mutation/set-user-role)
* [audio](https://docs.fireflies.ai/graphql-api/mutation/upload-audio)
* [meetingPrivacy](https://docs.fireflies.ai/graphql-api/mutation/update-meeting-privacy)

### Example integration

For an example manifest file of a Fireflies integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/fireflies/amp.yaml).

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with Fireflies:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start using the connector!
* If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Fireflies

1. Log in to your [Fireflies account](https://app.fireflies.ai/login).
2. Navigate to **Integrations** and select **Fireflies API**.
3. Click on **Get API Key**

<img alt="Generate Token" />


# Flatfile
Source: https://docs.ampersand.ai/provider-guides/flatfile



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental reading is only supported for `events`. For all other objects, a full read of the Flatfile instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.x.flatfile.com`.

### Supported Objects

The Flatfile connector supports reading from the following objects:

* [apps](https://reference.flatfile.com/api-reference/apps/list)
* [prompts](https://reference.flatfile.com/api-reference/assistant/list)
* [environments](https://reference.flatfile.com/api-reference/environments/list)
* [events](https://reference.flatfile.com/api-reference/events/list)
* [files](https://reference.flatfile.com/api-reference/files/list)
* [jobs](https://reference.flatfile.com/api-reference/jobs/list)
* [mapping](https://reference.flatfile.com/api-reference/mapping/list-mapping-programs)
* [roles](https://reference.flatfile.com/api-reference/roles/list)
* [spaces](https://reference.flatfile.com/api-reference/spaces/list)
* [users](https://reference.flatfile.com/api-reference/users/list)
* [workbooks](https://reference.flatfile.com/api-reference/workbooks/list)

The Flatfile connector supports writing to the following objects:

* [apps](https://reference.flatfile.com/api-reference/apps/create)
* [prompts](https://reference.flatfile.com/api-reference/assistant/create)
* [environments](https://reference.flatfile.com/api-reference/environments/create)
* [events](https://reference.flatfile.com/api-reference/events/create)
* [files](https://reference.flatfile.com/api-reference/files/upload)
* [jobs](https://reference.flatfile.com/api-reference/jobs/create)
* [mapping](https://reference.flatfile.com/api-reference/mapping/create-mapping-program)
* [spaces](https://reference.flatfile.com/api-reference/spaces/create)
* [workbooks](https://reference.flatfile.com/api-reference/workbooks/create)

## Before you get started

This connector uses API Key authentication. You do not need to create a provider app in the Ampersand Dashboard.

Flatfile distinguishes a **Secret key** from a **Publishable key**. Server-side access through Ampersand uses the Secret key.

### Create a Flatfile secret key

1. Log in to your [Flatfile account](https://platform.flatfile.com/).
2. Navigate to your developer or API key settings.
3. Copy the Secret key for the environment you want to connect.
4. Store the key securely.

<img alt="Flatfile secret key creation" />

For details, see Flatfile's [authentication documentation](https://reference.flatfile.com/overview/auth).

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. Provider apps are only required for providers that use OAuth2 Authorization Code grant type.

To start integrating with Flatfile:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/flatfile/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## API documentation

For more detailed information about Flatfile API, refer to the [Flatfile API documentation](https://reference.flatfile.com/overview/welcome).


# Formstack
Source: https://docs.ampersand.ai/provider-guides/formstack



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://www.formstack.com/api`.

## Before You Get Started

To connect Formstack with Ampersand, you will need [a Formstack Account](https://www.formstack.com/).

Once your account is created, you'll need to register an app in the Formstack developer portal, configure the app, and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Formstack Account

Here's how you can sign up for a Formstack account:

* Go to the [Formstack website](https://www.formstack.com/) and sign up for a new account.

### Register a Formstack OAuth App

Follow the steps below to register a Formstack OAuth app:

1. Log in to your [Formstack account](https://www.formstack.com/login).
2. Go to **Forms**.
3. Select your name, and choose **API** from the dropdown list.
4. Click on **Create New Application**.
5. Enter the following details in the create application form:
   1. **Application Name**: Enter a name for your app.
   2. **Description**: Provide a brief description of your app.
   3. **Redirect URI**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
6. Click **Create App**.

<img alt="Ampersand Project Selection" />

Once your app is created, you can access the **Client ID** and **Client Secret** credentials. Note these down, as you will need them to connect your app to Ampersand.

<br />

<img alt="Ampersand Project Selection" />

## Add Your Formstack App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a Formstack integration.\\
   <img alt="Ampersand Project Selection" />
3. Select **Provider Apps**.
4. Select **Formstack** from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

   <br />

   <img alt="Ampersand Project Selection" />
6. Click **Save Changes**.


# Four/Four
Source: https://docs.ampersand.ai/provider-guides/fourFour



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental reading is only supported for `Insights`, `Topics`, `TopicModels`, `Chats`, `ChatMessages`, `Accounts`, `Contacts`, `Cases`, `Calls`, `Owners`, `Opportunities`, `Leads`, `Objects`, `TrackerProjects`, `TrackerIssues`, and `TrackerComments`. For all other objects, a full read of the Four/Four instance will be done per scheduled read.
* [Proxy Actions](/proxy-actions), using the base URL `https://fourfour.ai`.

### Supported objects

The Four/Four connector supports reading from the following objects:

* [Accounts](https://fourfour.ai/developers/api#tag/Accounts/paths/~1Accounts/get) (supports incremental read)
* [CalendarEvents](https://fourfour.ai/developers/api#tag/CalendarEvents/paths/~1CalendarEvents/get)
* [Cases](https://fourfour.ai/developers/api#tag/Cases/paths/~1Cases/get) (supports incremental read)
* [Calls](https://fourfour.ai/developers/api#tag/Calls/paths/~1Calls/get) (supports incremental read)
* [ChatMessages](https://fourfour.ai/developers/api#tag/ChatMessages/paths/~1ChatMessages/get) (supports incremental read)
* [Chats](https://fourfour.ai/developers/api#tag/Chats/paths/~1Chats/get) (supports incremental read)
* [Contacts](https://fourfour.ai/developers/api#tag/Contacts/paths/~1Contacts/get) (supports incremental read)
* [Conversations](https://fourfour.ai/developers/api#tag/Conversations/paths/~1Conversations/get)
* [Fragments](https://fourfour.ai/developers/api#tag/Fragments/paths/~1Fragments/get)
* [Insights](https://fourfour.ai/developers/api#tag/Insights/paths/~1Insights/get) (supports incremental read)
* [Labels](https://fourfour.ai/developers/api#tag/Labels/paths/~1Labels/get)
* [Leads](https://fourfour.ai/developers/api#tag/Leads/paths/~1Leads/get) (supports incremental read)
* [Objects](https://fourfour.ai/developers/api#tag/Objects/paths/~1Objects/get) (supports incremental read)
* [Opportunities](https://fourfour.ai/developers/api#tag/Opportunities/paths/~1Opportunities/get) (supports incremental read)
* [Owners](https://fourfour.ai/developers/api#tag/Owners/paths/~1Owners/get) (supports incremental read)
* [Participants](https://fourfour.ai/developers/api#tag/Participants/paths/~1Participants/get)
* [TopicModels](https://fourfour.ai/developers/api#tag/TopicModels/paths/~1TopicModels/get) (supports incremental read)
* [Topics](https://fourfour.ai/developers/api#tag/Topics/paths/~1Topics/get) (supports incremental read)
* [TrackerComments](https://fourfour.ai/developers/api#tag/TrackerComments/paths/~1TrackerComments/get) (supports incremental read)
* [TrackerIssues](https://fourfour.ai/developers/api#tag/TrackerIssues/paths/~1TrackerIssues/get) (supports incremental read)
* [TrackerProjects](https://fourfour.ai/developers/api#tag/TrackerProjects/paths/~1TrackerProjects/get) (supports incremental read)

### Example integration

For an example manifest file of a Four/Four integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/fourfour/amp.yaml).

## Before you get started

To connect *Four/Four* with *Ampersand*, you will need a [Four/Four account](https://fourfour.ai).

Once your account is ready, you'll need to create a Four/Four OAuth2 app and obtain the following credentials:

* Client ID
* Client Secret

### Creating a Four/Four app

1. [Sign in](https://fourfour.ai/login) to your Four/Four account as an admin user.
2. Go to **Settings** > **Connections** > **OAuth clients**.
3. Click **ADD CLIENT** and fill in the form.
4. Under **Redirect URI**, add the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
5. Save your app settings.
6. Copy the generated **Client ID** and **Client Secret**.

## Add your Four/Four app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Four/Four integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Four/Four* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save changes**.

## Using the connector

To start integrating with Four/Four:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/fourfour/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component prompts the customer for OAuth authorization.
* Start using the connector.
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Freshchat
Source: https://docs.ampersand.ai/provider-guides/freshchat



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.freshchat.com`.

### Example integration

To define an integration for Freshchat, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: freshchat-integration
    displayName: My Freshchat Integration
    provider: freshchat
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key authentication, which means that you do not need to set up a Provider App before getting started. Provider apps are only required for providers that use OAuth2 Authorization Code grant type.

To start integrating with Freshchat:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://{{.workspace}}.freshchat.com`.

## Creating an API key for Freshchat

[Freshchat API key documentation](https://developers.freshchat.com/api) for more information on generating API keys for Freshchat.


# Freshdesk
Source: https://docs.ampersand.ai/provider-guides/freshdesk



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `companies`, `tickets` and `contacts` currently. For all other objects, a full read of the Freshdesk instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.freshdesk.com`.

### Supported Objects

The Freshdesk connector supports reading from the following objects:

* [agents](https://developers.freshdesk.com/api/#agents)
* [business\_hours](https://developers.freshdesk.com/api/#business-hours)
* [canned\_response\_folders](https://developers.freshdesk.com/api/#canned-responses)
* [companies](https://developers.freshdesk.com/api/#companies)
* [company-fields](https://developers.freshdesk.com/api/#company-fields)
* [contacts](https://developers.freshdesk.com/api/#contacts)
* [contact-fields](https://developers.freshdesk.com/api/#contact-fields)
* [email\_configs](https://developers.freshdesk.com/api/#email-configs)
* [groups](https://developers.freshdesk.com/api/#admin-groups)
* [mailboxes](https://developers.freshdesk.com/api/#email-mailboxes)
* [products](https://developers.freshdesk.com/api/#products)
* [roles](https://developers.freshdesk.com/api/#roles)
* [scenario\_automations](https://developers.freshdesk.com/api/#scenario-automations)
* [sla\_policies](https://developers.freshdesk.com/api/#sla-policies)
* [skills](https://developers.freshdesk.com/api/#skills)
* [tickets](https://developers.freshdesk.com/api/#tickets)
* [ticket-fields](https://developers.freshdesk.com/api/#ticket-fields)
* [ticket-forms](https://developers.freshdesk.com/api/#ticket-forms)
* [time\_entries](https://developers.freshdesk.com/api/#time-entries)

The Freshdesk connector supports writing to the following objects:

* [agents](https://developers.freshdesk.com/api/#create_agent)
* [canned\_responses](https://developers.freshdesk.com/api/#create_canned_response)
* [canned\_response\_folders](https://developers.freshdesk.com/api/#create_canned_response_folder)
* [companies](https://developers.freshdesk.com/api/#create_company)
* [company-fields](https://developers.freshdesk.com/api/#create_company_field)
* [contacts](https://developers.freshdesk.com/api/#create_contact)
* [contact-fields](https://developers.freshdesk.com/api/#create_contact)
* [contact-activities](https://developers.freshdesk.com/api/#omnichannel-activities)
* [groups](https://developers.freshdesk.com/api/#create_group)
* [mailboxes](https://developers.freshdesk.com/api/#create_email_mailbox)
* [skills](https://developers.freshdesk.com/api/#create_skill)
* [sla\_policies](https://developers.freshdesk.com/api/#create_sla_policy)
* [thread](https://developers.freshdesk.com/api/#create_a_thread)
* [tickets](https://developers.freshdesk.com/api/#create_ticket)
* [ticket-fields](https://developers.freshdesk.com/api/#create_ticket_field)
* [ticket-forms](https://developers.freshdesk.com/api/#create_ticket_form)

### Example integration

To define an integration for Freshdesk, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: Freshdesk-integration
    displayName: My Freshdesk Integration
    provider: freshdesk
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Freshdesk:

* Create a manifest file like the [example](#example-integration) above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username, password and domain.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://{{.workspace}}.freshdesk.com`.


# Front
Source: https://docs.ampersand.ai/provider-guides/front



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for `contacts` only.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api2.frontapp.com`.

### Supported Objects

The Front connector supports reading from the following objects:

* [accounts](https://dev.frontapp.com/reference/list-accounts)
* [channels](https://dev.frontapp.com/reference/channels)
* [contacts](https://dev.frontapp.com/reference/contacts)
* [contact\_lists](https://dev.frontapp.com/reference/contact-lists)
* [conversations](https://dev.frontapp.com/reference/conversations)
* [events](https://dev.frontapp.com/reference/events)
* [inboxes](https://dev.frontapp.com/reference/inboxes)
* [knowledge\_bases](https://dev.frontapp.com/reference/knowledge-bases)
* [links](https://dev.frontapp.com/reference/links)
* [rules](https://dev.frontapp.com/reference/rules)
* [message\_templates](https://dev.frontapp.com/reference/message-templates)
* [message\_template\_folders](https://dev.frontapp.com/reference/list-folders)
* [tags](https://dev.frontapp.com/reference/tags)
* [teammates](https://dev.frontapp.com/reference/teammates)
* [teammate\_groups](https://dev.frontapp.com/reference/teammate-groups)
* [teams](https://dev.frontapp.com/reference/teams)

The Front connector supports writing to the following objects:

* [accounts](https://dev.frontapp.com/reference/list-accounts)
* [contacts](https://dev.frontapp.com/reference/contacts)
* [contact\_lists](https://dev.frontapp.com/reference/contact-lists)
* [conversations](https://dev.frontapp.com/reference/conversations)
* [inboxes](https://dev.frontapp.com/reference/inboxes)
* [channels](https://dev.frontapp.com/reference/channels)
* [comments](https://dev.frontapp.com/reference/comments)
* [knowledge\_bases](https://dev.frontapp.com/reference/knowledge-bases)
* [links](https://dev.frontapp.com/reference/links)
* [message\_templates](https://dev.frontapp.com/reference/message-templates)
* [message\_template\_folders](https://dev.frontapp.com/reference/list-folders)
* [shifts](https://dev.frontapp.com/reference/shifts)
* [tags](https://dev.frontapp.com/reference/tags)
* [teammate\_groups](https://dev.frontapp.com/reference/teammate-groups)
* [teammate](https://dev.frontapp.com/reference/teammates)
* [signatures](https://dev.frontapp.com/reference/get-signatures)

### Example integration

For an example manifest file of a Front integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/front/amp.yaml).

## Before You Get Started

### Creating an API key for Front

[Click here](https://dev.frontapp.com/docs/create-and-revoke-api-tokens) for more information about generating an API key for Front. The UI components will display this link, so that your users can successfully create API keys.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Front:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/front/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# G2
Source: https://docs.ampersand.ai/provider-guides/g2



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://data.g2.com`.

## Before You Get Started

### Creating an API key for G2

[Click here](https://www.g2.com/static/integrations) for more information about generating an API key for G2. The UI components will display this link, so that your users can successfully create API keys.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with G2:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://data.g2.com`.

## Creating an API key for G2

[Click here](https://data.g2.com/api/docs?shell#g2-v2-api) for more information about generating an API key for G2. The UI components will display this link, so that your users can successfully create API keys.


# Geckoboard
Source: https://docs.ampersand.ai/provider-guides/geckoboard



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.geckoboard.com`.

### Example integration

To define an integration for Geckoboard, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: geckoboard-integration
    displayName: My Geckoboard Integration
    provider: geckoboard
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Geckoboard:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://api.geckoboard.com`.


# GetResponse
Source: https://docs.ampersand.ai/provider-guides/getResponse



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions) (create/update).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.getresponse.com`.
* Subscribe Actions are not currently supported.

### Supported objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Contacts">contacts</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Campaigns">campaigns</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Tags">tags</a></td><td><Cross /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Newsletters">newsletters</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Autoresponders">autoresponders</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Forms">forms</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Landing-Pages">landing-pages</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Custom-Events">custom-events</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://apireference.getresponse.com/#tag/Webinars">webinars</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

### Notes and limitations

* **Write support**: `contacts` and `campaigns` support create and update. For `tags`, create is supported; the update operation is deprecated by GetResponse.
* **contacts**: Must be associated with an existing campaign on creation (a `campaignId` is required).
* **Incremental read (implementation)**: For `contacts`, the connector uses GetResponse’s `query[createdOn][from/to]` filters. For all other readable objects, it uses each record’s `createdOn` field to determine what changed since the last read.

### Example integration

To define an integration for GetResponse, use a manifest file (`amp.yaml`). For a complete example, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/getresponse/amp.yaml).

## Before you get started

To integrate GetResponse with Ampersand, you will need a [GetResponse account](https://www.getresponse.com/).

Once your account is created, you'll need to create an app in GetResponse and obtain the following credentials:

* **Client ID**
* **Client Secret**

You will then use these credentials to connect your application to Ampersand.

### Create a GetResponse account

Here's how to sign up for a GetResponse account:

1. Go to the [GetResponse sign up page](https://www.getresponse.com/start-free?version=centered\&pageinfo=homepage).
2. Sign up using your preferred method.

### Create an app in GetResponse

Follow the steps below to create an OAuth app in GetResponse and obtain your credentials:

1. Log in to your [GetResponse account](https://app.getresponse.com/login).

2. Navigate to **Tools > Integrations and API** and click **Custom Apps**.

3. Click the **Add new app** button.

4. Enter the following details for your app:
   1. **Application name**: Name for your app.
   2. **Description**: Description of what your app does.
   3. **Redirect URL**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`

5. Click **Add**.

Once the app is created, you will be able to view the **Client ID** and **Client Secret**. Copy these credentials — you will need them in the next step.

<img alt="Creating a GetResponse custom OAuth app" />

### Add your GetResponse app to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a GetResponse integration.

   <img alt="Ampersand Project" />

3. Select **Provider apps**.

4. Select **GetResponse** from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained in the previous step.

   <img alt="Ampersand GetResponse Integration" />

6. Click **Save Changes**.

## Using the connector

This connector uses OAuth 2.0 (Authorization Code), which means that you must set up a Provider App before getting started.

To start integrating with GetResponse:

* Create a manifest file; see [Example integration](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt your customers to authorize their GetResponse account.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# GitHub
Source: https://docs.ampersand.ai/provider-guides/github



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `gists`, `gists/starred`, `issues`, `gists/public`, `repos` and `user/issues` currently. For all other objects, a full read of the Github instance will be done per scheduled read.
* [Write Actions](/write-actions)
* [Proxy Actions](/proxy-actions), using the base URL `https://api.github.com`

### Supported Objects

The GitHub connector supports the following objects:

* [advisories](https://docs.github.com/en/rest/security-advisories/security-advisories) (Read)
* [blocks](https://docs.github.com/en/rest/users/blocking?apiVersion=2022-11-28#list-users-blocked-by-the-authenticated-user) (Read)
* [classrooms](https://docs.github.com/en/rest/classroom/classroom) (Read)
* [codes\_of\_conduct](https://docs.github.com/en/rest/codes-of-conduct) (Read)
* [conflicts](https://docs.github.com/en/rest/packages/packages?apiVersion=2022-11-28#get-list-of-conflicting-packages-during-docker-migration-for-authenticated-user) (Read)
* [deliveries](https://docs.github.com/en/rest/apps/webhooks?#list-deliveries-for-an-app-webhook) (Read)
* [events](https://docs.github.com/en/rest/activity/events?#list-public-events) (Read)
* [followers](https://docs.github.com/en/rest/users/followers?#list-followers-of-the-authenticated-user) (Read)
* [following](https://docs.github.com/en/rest/users/followers?#list-the-people-the-authenticated-user-follows) (Read)
* [gists](https://docs.github.com/en/rest/gists/gists) (Read, Write)
* [gists/public](https://docs.github.com/en/rest/gists/gists?#list-public-gists) (Read)
* [gists/starred](https://docs.github.com/en/rest/gists/gists?#list-starred-gists) (Read)
* [installation-requests](https://docs.github.com/en/rest/apps/apps?#list-installation-requests-for-the-authenticated-app) (Read)
* [installation/repositories](https://docs.github.com/en/rest/apps/installations?#list-repositories-accessible-to-the-app-installation) (Read)
* [issues](https://docs.github.com/en/rest/issues/issues?#list-issues-assigned-to-the-authenticated-user) (Read)
* [licenses](https://docs.github.com/en/rest/licenses/licenses?#get-all-commonly-used-licenses) (Read)
* [marketplace\_listing/plans](https://docs.github.com/en/rest/apps/marketplace?#list-plans) (Read)
* [marketplace\_listing/stubbed/plans](https://docs.github.com/en/rest/apps/marketplace?#list-plans-stubbed) (Read)
* [marketplace\_purchases](https://docs.github.com/en/rest/apps/marketplace?#list-subscriptions-for-the-authenticated-user) (Read)
* [migration](https://docs.github.com/en/rest/migrations/users?#list-user-migrations) (Read)
* [organizations](https://docs.github.com/en/rest/orgs/orgs) (Read)
* [orgs](https://docs.github.com/en/rest/orgs/orgs) (Read)
* [packages](https://docs.github.com/en/rest/packages) (Read)
* [public\_emails](https://docs.github.com/en/rest/users/emails?#list-public-email-addresses-for-the-authenticated-user) (Read)
* [repos](https://docs.github.com/en/rest/repos/repos?#list-repositories-for-the-authenticated-user) (Read)
* [repositories](https://docs.github.com/en/rest/repos/repos?#list-public-repositories) (Read)
* [repository\_invitations](https://docs.github.com/en/rest/collaborators/invitations?#list-repository-invitations-for-the-authenticated-user) (Read)
* [secrets](https://docs.github.com/en/rest/codespaces/secrets) (Read)
* [stubbed](https://docs.github.com/en/rest/apps/marketplace?#list-subscriptions-for-the-authenticated-user-stubbed) (Read)
* [subscriptions](https://docs.github.com/en/rest/activity/watching?#list-repositories-watched-by-the-authenticated-user) (Read)
* [teams](https://docs.github.com/en/rest/teams/teams?#list-teams-for-the-authenticated-user) (Read)
* [user/codespaces](https://docs.github.com/en/rest/codespaces) (Read, Write)
* [user/emails](https://docs.github.com/en/rest/users/emails?#list-email-addresses-for-the-authenticated-user) (Read, Write)
* [user/keys](https://docs.github.com/en/rest/users/keys) (Read, Write)
* [user/gpg\_keys](https://docs.github.com/en/rest/users/gpg-keys) (Read, Write)
* [user/installations](https://docs.github.com/en/rest/apps/installations?#list-app-installations-accessible-to-the-user-access-token) (Read)
* [user/issues](https://docs.github.com/en/rest/issues/issues?#list-user-account-issues-assigned-to-the-authenticated-user) (Read)
* [user/memberships/orgs](https://docs.github.com/en/rest/orgs/members?#list-organization-memberships-for-the-authenticated-user) (Read)
* [user/starred](https://docs.github.com/en/rest/activity/starring?#list-repositories-starred-by-the-authenticated-user) (Read)
* [user/ssh\_signing\_keys](https://docs.github.com/en/rest/users/ssh-signing-keys) (Read, Write)
* [user/social\_accounts](https://docs.github.com/en/rest/users/social-accounts) (Read, Write)
* [users](https://docs.github.com/en/rest/users/users) (Read)

## Before you get started

To integrate GitHub with Ampersand, you will need a [GitHub Account](https://github.com/signup).

Once your account is created, you'll need to create a GitHub OAuth app and obtain the following credentials:

* OAuth Client ID
* OAuth Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a GitHub OAuth App

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Click on "OAuth Apps" in the sidebar
3. Click "New OAuth App"
4. Fill in the application details:
   * **Application name**: Your application name
   * **Homepage URL**: Your application's homepage URL
   * **Application description**: (Optional) Description of your application
   * **Authorization callback URL**: `https://api.withampersand.com/callbacks/v1/oauth`
5. Click "Register application"
6. On the next screen, click "Generate a new client secret"
7. Save your Client ID and Client Secret - you'll need these for the next step

## Add your GitHub App info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com)
2. Select your project
   <img alt="Alt text" />
3. Go to **Provider apps**
4. Select **GitHub** from the **Provider list**
5. Enter your OAuth app credentials:
   * Client ID
   * Client Secret
     <img alt="Alt text" />
6. Click **Save changes**

## Using the connector

To start integrating with Github:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/github/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# GitLab
Source: https://docs.ampersand.ai/provider-guides/gitlab



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for most of the supported objects.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://gitlab.com`.

### Supported Objects

The GitLab connector supports reading from the following objects:

* [admin/search/migrations](https://docs.gitlab.com/api/admin/search_migrations)
* [application/appearance](https://docs.gitlab.com/api/appearance/#get-details-on-current-application-appearance)
* [application/plan\_limits](https://docs.gitlab.com/api/plan_limits)
* [application/settings](https://docs.gitlab.com/api/settings)
* [applications](https://docs.gitlab.com/api/applications)
* [audit\_events](https://docs.gitlab.com/api/audit_events)
* [broadcast\_messages](https://docs.gitlab.com/api/broadcast_messages)
* [bulk\_imports](https://docs.gitlab.com/api/bulk_imports)
* [bulk\_imports/entities](https://docs.gitlab.com/api/bulk_imports/#list-group-or-project-migration-entities)
* [deploy\_keys](https://docs.gitlab.com/api/deploy_keys)
* [deploy\_tokens](https://docs.gitlab.com/api/deploy_tokens)
* [events](https://docs.gitlab.com/api/events)
* [experiments](https://docs.gitlab.com/api/experiments)
* [geo\_nodes/status](https://docs.gitlab.com/api/geo_nodes#status)
* [geo\_sites](https://docs.gitlab.com/api/geo_sites)
* [geo\_sites/status](https://docs.gitlab.com/api/geo_sites#status)
* [groups](https://docs.gitlab.com/api/groups)
* [hooks](https://docs.gitlab.com/api/system_hooks)
* [issues](https://docs.gitlab.com/api/issues)
* [issues\_statistics](https://docs.gitlab.com/api/issues_statistics)
* [license](https://docs.gitlab.com/api/license)
* [licenses](https://docs.gitlab.com/api/templates/licenses)
* [member\_roles](https://docs.gitlab.com/api/member_roles)
* [merge\_requests](https://docs.gitlab.com/api/merge_requests)
* [metadata](https://docs.gitlab.com/api/metadata)
* [namespaces](https://docs.gitlab.com/api/namespaces)
* [pages/domains](https://docs.gitlab.com/api/pages_domains/)
* [personal\_access\_tokens](https://docs.gitlab.com/api/personal_access_tokens)
* [personal\_access\_tokens/self/associations](https://docs.gitlab.com/api/personal_access_tokens/#list-all-token-associations)
* [project\_aliases](https://docs.gitlab.com/api/project_aliases)
* [project\_repository\_storage\_moves](https://docs.gitlab.com/api/project_repository_storage_moves)
* [projects](https://docs.gitlab.com/api/projects)
* [runners](https://docs.gitlab.com/api/runners)
* [runners/all](https://docs.gitlab.com/api/runners/#list-all-runners)
* [service\_accounts](https://docs.gitlab.com/api/service_accounts)
* [sidekiq/compound\_metrics](https://docs.gitlab.com/api/sidekiq_metrics)
* [sidekiq/job\_stats](https://docs.gitlab.com/api/sidekiq_metrics/#get-the-current-job-statistics)
* [sidekiq/process\_metrics](https://docs.gitlab.com/api/sidekiq_metrics/#get-the-current-process-metrics)
* [sidekiq/queue\_metrics](https://docs.gitlab.com/api/sidekiq_metrics)
* [snippet\_repository\_storage\_moves](https://docs.gitlab.com/api/snippet_repository_storage_moves)
* [snippets](https://docs.gitlab.com/api/snippets)
* [snippets/all](https://docs.gitlab.com/api/snippets/#list-all-snippets)
* [snippets/public](https://docs.gitlab.com/api/snippets/#list-all-public-snippets)
* [templates/dockerfiles](https://docs.gitlab.com/api/templates/dockerfiles)
* [templates/gitignores](https://docs.gitlab.com/api/templates/gitignores)
* [templates/gitlab\_ci\_ymls](https://docs.gitlab.com/api/templates/gitlab_ci_ymls)
* [templates/licenses](https://docs.gitlab.com/api/templates/licenses)
* [todos](https://docs.gitlab.com/api/todos)
* [topics](https://docs.gitlab.com/api/topics)
* [users](https://docs.gitlab.com/api/users)

The GitLab connector supports writing to the following objects:

* [applications](https://docs.gitlab.com/api/applications)
* [broadcast\_messages](https://docs.gitlab.com/api/broadcast_messages)
* [chat/completions](https://docs.gitlab.com/api/chat)
* [code\_suggestions/completions](http://docs.gitlab.com/api/suggestions/)
* [deploy\_keys](https://docs.gitlab.com/api/deploy_keys)
* [geo\_nodes](https://docs.gitlab.com/api/geo_nodes)
* [geo\_sites](https://docs.gitlab.com/api/geo_sites)
* [group\_repository\_storage\_moves](https://docs.gitlab.com/api/group_repository_storage_moves)
* [groups](https://docs.gitlab.com/api/groups)
* [hooks](https://docs.gitlab.com/administration/system_hooks/)
* [member\_roles](https://docs.gitlab.com/api/member_roles/#create-a-instance-member-role)
* [organizations](https://docs.gitlab.com/api/organizations)
* [project\_aliases](https://docs.gitlab.com/api/project_aliases)
* [project\_repository\_storage\_moves](https://docs.gitlab.com/api/project_repository_storage_moves)
* [projects](https://docs.gitlab.com/api/projects)
* [runners](https://docs.gitlab.com/api/runners)
* [security/vulnerability\_exports](https://docs.gitlab.com/api/vulnerability_exports/)
* [service\_accounts](https://docs.gitlab.com/api/service_accounts/)
* [snippets](https://docs.gitlab.com/api/snippets)
* [todos/mark\_as\_done](https://docs.gitlab.com/api/todos/#mark-all-to-do-items-as-done)
* [topics](https://docs.gitlab.com/api/topics)
* [user/emails](https://docs.gitlab.com/api/user_email_addresses/#add-an-email-address)
* [user/gpg\_keys](https://docs.gitlab.com/api/user/gpg_keys)
* [user/keys](https://docs.gitlab.com/api/user/keys)
* [user/runners](https://docs.gitlab.com/api/user/runners)
* [user/support\_pin](https://docs.gitlab.com/api/users/#create-a-support-pin)
* [users](https://docs.gitlab.com/api/users)

### Example integration

For an example manifest file of a GitLab integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/gitlab/amp.yaml).

## Using the connector

This connector uses GitLab Access Tokens for authentication, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

Your customer can pick between:

* [Personal access tokens](https://docs.gitlab.com/user/profile/personal_access_tokens/)
* [Project access tokens](https://docs.gitlab.com/user/project/settings/project_access_tokens/)
* [Group access tokens](https://docs.gitlab.com/user/group/settings/group_access_tokens/)

To start integrating with GitLab:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/gitlab/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an Access token.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# GoTo
Source: https://docs.ampersand.ai/provider-guides/goTo



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for `historicalMeetings`, `webinars`, and `sessions`. For all other objects, a full read of the GoTo instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.getgo.com`.

### Supported objects

The GoTo connector supports reading from the following objects:

* [admin/groups](https://developer.goto.com/admin#tag/Groups/operation/Get%20Groups)
* [admin/users](https://developer.goto.com/admin#tag/Users/operation/Get%20Users)
* [attributes](https://developer.goto.com/admin#tag/Attributes/operation/Get%20All%20Attributes)
* [groups](https://developer.goto.com/Scim#tag/Groups/operation/getGroups)
* [historicalMeetings](https://developer.goto.com/GoToMeetingV1/#tag/Meetings/operation/getHistoricalMeetings)
* [licenses](https://developer.goto.com/admin#tag/Licenses/operation/Get%20Licenses)
* [portals](https://developer.goto.com/g2a-c#tag/Portals/paths/~1portals~1pages/get)
* [representatives](https://developer.goto.com/g2a-c#tag/Representatives/paths/~1representatives~1pages/get)
* [rolesets](https://developer.goto.com/admin#tag/Role-Sets/operation/Get%20Role%20Sets)
* [sessions](https://developer.goto.com/g2a-rs#tag/Sessions/paths/~1G2A~1rest~1v1~1sessions/get)
* [teams](https://developer.goto.com/g2a-c#tag/Teams/paths/~1teams~1pages/get)
* [upcomingMeetings](https://developer.goto.com/GoToMeetingV1/#tag/Meetings/operation/getUpcomingMeetings)
* [userSubscriptions](https://developer.goto.com/GoToWebinarV2/#tag/Webhooks/operation/getUserSubscriptions)
* [users](https://developer.goto.com/Scim#tag/Users/operation/getUsers)
* [webhooks](https://developer.goto.com/GoToWebinarV2/#tag/Webhooks/operation/getWebhooks)
* [webinars](https://developer.goto.com/GoToWebinarV2/#tag/Webinars/operation/getAllAccountWebinars)

The GoTo connector supports writing to the following objects:

* [admin/groups](https://developer.goto.com/admin#tag/Groups/operation/Add%20Group)
* [admin/users](https://developer.goto.com/admin#tag/Users/operation/Add%20Users)
* [groups](https://developer.goto.com/Scim#tag/Groups/operation/createGroup)
* [meetings](https://developer.goto.com/GoToMeetingV1/#tag/Meetings)
* [representatives](https://developer.goto.com/g2a-c#tag/Representatives/paths/~1representatives/post)
* [rolesets](https://developer.goto.com/admin#tag/Role-Sets/operation/Add%20Role%20Set)
* [teams](https://developer.goto.com/g2a-c#tag/Teams/paths/~1teams/post)
* [tickets](https://developer.goto.com/LogMeInResolve/#tag/Ticketing)
* [users](https://developer.goto.com/Scim#tag/Users/operation/createUsers)
* [userSubscriptions](https://developer.goto.com/GoToWebinarV2#tag/Webhooks/operation/createUserSubscriptions)
* [webhooks](https://developer.goto.com/GoToWebinarV2#tag/Webhooks/operation/createWebhooks)

### Example integration

For an example manifest file of a GoTo integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/goto/amp.yaml).

## Before you get started

To integrate GoTo with Ampersand, you need to [Create a GoTo Account](https://developer.goto.com/signup/) and obtain the following credentials from your GoTo App:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a GoTo account

Here's how you can sign up for a GoTo account:

1. Go to the [GoTo sign-up page](https://developer.goto.com/signup/).
2. Fill in the necessary details and register your account.

### Creating a GoTo OAuth app

Once your GoTo account is ready, create an OAuth application for Ampersand:

1. Log in to your [GoTo account](https://identity.goto.com/login).
2. Go to [GoTo developer clients](https://developer.logmeininc.com/clients).
3. Click **Create a new client**.
4. Open the **OAuth Apps** tab.
5. Click **Create App**.
6. Fill in the app details:
   1. **App Name**: Choose a name for the OAuth app.
   2. **App Description**: Add a short description.
   3. **Redirect URL**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
7. Click **Next**.
8. Select the permissions your app needs.
9. Click **Save**.

You'll find the **Client ID** and **Client Secret** keys in your OAuth app details. These credentials are required for connecting your app to Ampersand, so be sure to note them carefully.

<img alt="GoTo OAuth App Creation" />

### Add your GoTo app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the GoTo app.

   <img alt="Ampersand Project Selection" />

3. Navigate to the **Provider Apps** section.

4. Select **GoTo** from the provider list.

5. Enter the **Client ID** and **Client Secret** from your GoTo OAuth app.

   <img alt="Ampersand Project Selection" />

6. Click **Save Changes**.

## Using the connector

To start integrating with GoTo:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component prompts the customer for GoTo OAuth authorization.
* Start using the connector.
  * If your integration has [Read Actions](/read-actions), Ampersand delivers webhook messages.
  * If your integration has [Write Actions](/write-actions), call the Write API.
  * If your integration has [Proxy Actions](/proxy-actions), call Proxy API requests against `https://api.getgo.com`.


# Gong
Source: https://docs.ampersand.ai/provider-guides/gong



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.gong.io`.
* [Read Actions](/read-actions)
* [Subscribe Actions](/subscribe-actions). Please note that [special set up](#set-up-subscribe-actions) is needed for Gong.

### Supported Objects

| Object | Read | Write | Subscribe |
| - | - | - | - |
| Users | ✓ (full read only) | | |
| Workspaces | ✓ (full read only) | | |
| Flows | ✓ (full read only) | | |
| Calls | ✓ (incremental in private preview¹) | ✓ | ✓ (`call.created` only) |
| Transcripts | ✓ (incremental in private preview¹) | | |

¹ Contact [support@withampersand.com](mailto:support@withampersand.com) to enable incremental read for Calls and Transcripts.

<Note>
  **Gong processing latency.** Gong takes time to process recordings before they become available, which delays both Read Actions and Subscribe webhooks:

  * **Calls** are available through Read and Subscribe Actions after they have finished processing in Gong, which may take up to **1 hour** after a call ends.
  * **Transcripts** may not be available for up to **24 hours** after a call ends.
</Note>

### Example Integration

For an example manifest file of a Gong integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/gong/amp.yaml).

## Before you get started

To connect Gong with Ampersand, you must complete the [Gong partnership process](https://www.gong.io/partners/) and obtain a *Gong Sandbox* environment.

After your account is set up, you will need to acquire the following credentials from your Gong app:

* Client ID
* Client Secret
* Scopes

> **Important:** To read `Calls`, ensure that your Gong application includes the `api:calls:read:extensive` scope.

In the **Redirect URI** section, add the Ampersand Callback URL: `https://api.withampersand.com/callbacks/v1/oauth`.

<img alt="Alt text" />

You will then use these credentials to connect your application to Ampersand.

Learn more about the Gong Partnership process [here](https://help.gong.io/docs/how-to-use-the-gong-developers-hub).

### Allowlist Ampersand's IP addresses

Gong is now requesting that the IP addresses making API calls on behalf of your app are added to an allowlist. Add [Ampersand's outgoing IP addresses](/security/outgoing-ip-addresses) to your Gong app's allowlist so that API requests made by Ampersand on behalf of your integration are not blocked:

Learn more about how Gong restricts API access to trusted IP addresses in [Gong's API key documentation](https://help.gong.io/docs/receive-access-to-the-api).

## Add Gong App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Gong App.

3. Select **Provider apps**.

4. Select Gong from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field, the *Client Secret* in the **Client Secret** field, and the requested scopes in the **Permissions** field.

   <br />

   <img alt="Alt text" />

6. Enter the scopes set for your application in *Gong*.

7. Click **Save Changes**.

## Set up Subscribe Actions

1. **Define the subscribe action** in your `amp.yaml` and deploy it with the [amp CLI](/cli/overview). Gong only supports the `call.created` event, so the `calls` object should subscribe to `createEvent` only.

   ```yaml theme={"dark"}
   specVersion: 1.0.0
   integrations:
     - name: subscribeToGong
       provider: gong
       subscribe:
         objects:
           - objectName: calls
             destination: gongWebhook
             inheritFieldsAndMapping: true
             createEvent:
               enabled: always
       read: 
         objects:
           - objectName: calls
             destination: gongWebhook
             requiredFields:
               ...
   ```

2. **Construct a webhook URL for your customer** in this format:

   ```
   https://subscribe-receiver.withampersand.com/zt1secx7jknlhb/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
   ```

3. **Share the [Gong customer guide](/customer-guides/gong)** with your customer along with the webhook URL from Step 2. Your customer will create an automation rule in Gong that fires a webhook when a new call is created.


# Google
Source: https://docs.ampersand.ai/provider-guides/google



The Google connector supports Google products which have APIs with the root URL `googleapis.com`, these include:

* Calendar
* Gmail
* Google Drive

## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://www.googleapis.com`.

The **Calendar** module supports:

* [Read Actions](/read-actions), including historical backfill. Please note that incremental
  read **is only supported for the Calendar `Events` object**; otherwise, a full read of the Google instance will be performed for each scheduled run.
* [Subscribe Actions](/subscribe-actions) for the `events` object — see [Calendar Subscribe Actions](#calendar-subscribe-actions).
* [Write Actions](/write-actions).

> **Important Note on Events Backfill**: The `events` object has a 28-day cap for historic backfill and does not support full history, due to limitations in the Google API. When syncing events data, ensure your backfill period does not exceed 28 days.

The **Gmail** module supports:

* [Read Actions](/read-actions), including historical backfill. Please note that incremental read and pagination
  **are only supported for `Drafts`, `Messages`, and `Threads` objects**; otherwise, a full read of the Gmail instance will be performed for each scheduled run.
* [Subscribe Actions](/subscribe-actions) for the `messages` object. Please note that [special set up](#set-up-gmail-push-notifications-for-subscribe-actions) is needed for Gmail.
* [Write Actions](/write-actions).

### Supported Calendar objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://developers.google.com/workspace/calendar/api/v3/reference/acl">acl</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/calendar/api/v3/reference/calendarList#resource-representations">calendarList</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/calendar/api/v3/reference/events">events</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/calendar/api/v3/reference/settings">settings</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

### Supported Gmail objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.delegates/list">delegates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts#Draft">drafts</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.filters/list">filters</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.forwardingAddresses/list">forwardingAddresses</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.cse.identities/list">identities</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.cse.keypairs/list">keypairs</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/list">labels</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message">messages</a></td><td><Check /></td><td><Cross /></td><td><Check /><br /><a href="#set-up-gmail-push-notifications-for-subscribe-actions">(Setup required)</a></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.sendAs/list">sendAs</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/list">threads</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

*\[1] `drafts` supports nested fields, e.g. `"$['message']['payload']['body']"`.*

*\[2] `messages` supports nested fields, e.g. `"$['payload']['body']"`.*

### Example integration

Example manifest files can be found in our samples repository on GitHub:

* [Google Calendar example](https://github.com/amp-labs/samples/blob/main/google-calendar/amp.yaml)
* [Gmail example](https://github.com/amp-labs/samples/blob/main/google-gmail/amp.yaml)

## Before you get started

To integrate Google with Ampersand, you will need a [Google Cloud account](https://cloud.google.com/).

Once your account is created, you'll need to create a Google app, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Google Cloud account

You can sign up for a [free Google Cloud account here](https://cloud.google.com/free).

### Enable the appropriate APIs

Go to the [API Library page](https://console.cloud.google.com/apis/library) of Google Cloud Console and search for the APIs your integration will need. For example, if you are building a Google Drive integration, type "Google Drive", select the right API and click the "Enable" button.

<img alt="API Library" />

Repeat this process for all the APIs your integration will need.

### Creating a Google App

Follow the steps below to create a Google App:

1. Go to the [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) page, pick "External" as the User Type.

<img alt="OAuth Consent" />

<br />

2. Enter the information required on the next page, click "Save and Continue".

**Important information about App Logo**: when you are creating a Google app for development purposes, do not upload a logo. Uploading a logo will trigger an app verification process. When you are ready to submit your app for review by Google, then you can come back to this page and upload a logo.

<img alt="App Logo" />

3. On the Scopes page, click "Add or Remove Scopes", and then select the scopes that your integration will need. For example, if you are integrating with Google Drive, type "Google Drive" into the search box and select the scopes you will need. If the scopes you require are not popping up, ensure that you've enabled the appropriate APIs (previous step), and then refresh the page.

<img alt="Scopes" />

4. On the Test Users page, click "+ Add Users" to add up to 100 email addresses, and then click "Save and Continue".

<img alt="Add Users" />

### Creating Client ID and Client Secret

1. Once your Google App has been created, go to the [Credentials page](https://console.cloud.google.com/apis/credentials) of Google Cloud Console. Click on "Create Credentials" and then select "OAuth Client ID".

<img alt="Create Credentials" />

2. Click "Web Application" from the Application Type dropdown menu.

<img alt="Web Application" />

3. In the name box, write down a descriptive name like "Ampersand Integration". Under "Authorized redirect URIs", add `https://api.withampersand.com/callbacks/v1/oauth`. Click "Create".

<img alt="Authorized Redirect URIs" />

4. There will be a popup which displays the Client ID and Client Secret, you'll need to add these to the Ampersand Dashboard in the next step. You can either copy and paste these values, or click "Download JSON".

<img alt="Client ID and Client Secret" />

## Add Your Google App info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Google integration.

   <img alt="Ampersand Project" />

3. Select **Provider apps**.

4. Select *Google* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field. In the **Scopes** field, enter each of your scopes on a separate line.

* For Google Calendar, add `https://www.googleapis.com/auth/calendar`
* For Gmail, add `https://mail.google.com`

<img alt="Scopes" />

6. Click **Save changes**.

## Calendar Subscribe Actions

Ampersand creates and manages the webhook subscriptions on your behalf when the customer installs your integration — no manual webhook setup is required.

To receive events, you must explicitly define a `subscribe` section for the `events` object in your integration's [`amp.yaml`](https://github.com/amp-labs/samples/blob/main/google-calendar/amp.yaml) manifest, alongside a corresponding read action. See [Subscribe Actions](/subscribe-actions) for the manifest format.

### Caveats

* **`events` is the only supported object.** Changes to `acl`, `calendarList`, and `settings` are not delivered as Subscribe events.
* **Primary calendar only.** Only changes on the connected user's primary calendar are delivered.
* **No historical backfill via Subscribe.** Subscribe events start from the moment the watch channel is created. To sync existing events, combine your Subscribe action with a [Read action](/read-actions) that has `backfill` configured (note the 28-day cap on `events` backfill mentioned above).

## Set up Gmail push notifications for Subscribe Actions

To receive real-time Subscribe events from Gmail, you need to own a Google Cloud Pub/Sub topic that Gmail can publish to, and a push subscription that forwards those messages to Ampersand.

<Note>
  Gmail requires the Pub/Sub topic to live in the **same Google Cloud project** as the OAuth app you created in [Creating a Google App](#creating-a-google-app).
</Note>

### Prerequisites

* A Google Cloud project with billing enabled (the same project that owns your Google OAuth app).
* The [`gcloud` CLI](https://cloud.google.com/sdk/docs/install) installed.
* Your user account needs the following IAM roles on the project (or equivalent permissions via a custom role):
  * `roles/pubsub.admin` — required to create the topic, create the push subscription, and add the IAM binding that grants Gmail publish access (the `add-iam-policy-binding` step requires `pubsub.topics.setIamPolicy`, which `roles/pubsub.editor` alone does not cover).
  * `roles/serviceusage.serviceUsageAdmin` — required to enable the Pub/Sub API if it is not already enabled. You can skip this role if the API is already on.
  * Project `roles/owner` covers all of the above if you'd rather not manage individual roles.

<Note>
  Org-level access does not automatically grant resource-creation permission on individual projects. If you have access to the organization but not the project, you'll see `User not authorized to perform this action` when running the commands below.
</Note>

### 1. Log into gcloud CLI

Replace `PROJECT_ID` with your Google Cloud project ID.

```bash theme={"dark"}
gcloud auth login
gcloud config set project PROJECT_ID
```

### 2. Enable the Pub/Sub API

```bash theme={"dark"}
gcloud services enable pubsub.googleapis.com
```

### 3. Create a Pub/Sub topic

Replace `TOPIC_NAME` with a name of your choice (e.g. `gmail-push`).

```bash theme={"dark"}
gcloud pubsub topics create TOPIC_NAME
```

### 4. Grant Gmail permission to publish to the topic

Gmail publishes push notifications using a Google-managed service account. Grant it the `Pub/Sub Publisher` role on your topic. **Without this grant Gmail will reject the `watch` call with a permission error.**

```bash theme={"dark"}
gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher
```

### 5. Create a push subscription to Ampersand

Create a push subscription that forwards every notification to Ampersand's receiver endpoint. Replace `SUBSCRIPTION_NAME` with a name of your choice (e.g. `gmail-push-to-ampersand`).

```bash theme={"dark"}
gcloud pubsub subscriptions create SUBSCRIPTION_NAME \
  --topic=TOPIC_NAME \
  --push-endpoint=https://subscribe-receiver.withampersand.com/zt1secx7jknlhb/v1 \
  --ack-deadline=60 \
  --message-retention-duration=7d
```

### 6. Pre-authorize Ampersand's service account

Grant Ampersand's Gmail Subscribe service account a resource-scoped role on your topic:

```bash theme={"dark"}
gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
  --member=serviceAccount:gmail-subscribe@ampersand-prod.iam.gserviceaccount.com \
  --role=roles/pubsub.editor
```

This role is scoped to this single topic, and grants no access elsewhere in your project.

### 7. Update your Google provider app in Ampersand

Ampersand needs to know which topic to wire new installations to. Go back to your [Ampersand Dashboard](https://dashboard.withampersand.com), open **Provider apps** → **Google** (the same provider app where you entered your Client ID and Client Secret in [Add Your Google App info to Ampersand](#add-your-google-app-info-to-ampersand)), and set the following fields:

* **GCP Project ID**: `PROJECT_ID`
* **GCP Pub/Sub Topic Name**: `TOPIC_NAME`

Click **Save changes**.

<img alt="Google provider app Gmail subscribe fields" />

Once saved, every new installation with a Gmail Subscribe action in its `amp.yaml` will automatically register a Gmail `watch` for that mailbox, pointing at your topic. Events then flow:

1. A new message arrives in the **Gmail mailbox**.
2. Gmail publishes a notification to **your Pub/Sub topic**.
3. **Your push subscription** forwards the notification to Ampersand.
4. **Ampersand** hydrates the message and processes the event.
5. The event is delivered to **your destination**.

### Caveats

* **7-day history horizon.** Gmail only retains mailbox history for about 7 days. If a mailbox has not received or sent emails for 7 days, Ampersand will miss events from before the gap and resume from the next incoming notification.
* **Delete events carry only `messageId`.** When a message is deleted, Gmail's history API does not return the message body — only its ID. Your destination will receive a `delete` subscribe event without `fields` or `mappedFields` populated.
* **`messages` is the only supported object.** Changes to Gmail labels, drafts, filters, threads, and other objects are not delivered as Subscribe events.
* **Inbox only by default.** Ampersand currently watches the `INBOX` label only, so you'll only receive events for messages entering, leaving, or being relabeled within the inbox. If you need notifications for other labels (e.g. `SENT`, `TRASH`, or custom labels), contact [support@withampersand.com](mailto:support@withampersand.com) and we can configure additional labels on our end.
* **No historical backfill via Subscribe.** Subscribe events start from the moment the `watch` is created. To sync existing mailbox contents, combine your Subscribe action with a [Read action](/read-actions) that has `backfill` configured.
* **One installation per mailbox per project.** Connecting the same Gmail account to multiple installations in the same Ampersand project is not supported for Subscribe. When a second OAuth connection is created for a mailbox that already has one, Google can invalidate the earlier connection's refresh token, which breaks token refresh on the older installation and stops its events from flowing.

## Ship your integration to production

When you are ready to use your integration with external customers, you'll need to go through the Google App verification process.

1. Go back to the [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) page, click on "Edit App" to upload a logo and fill out all the form fields (such as Privacy Page, Terms of Service).
2. After saving your changes, click on the "Publish App" button under "Publishing Status".

<img alt="Publish App" />

3. Then click on the "Prepare for Verification" button that should now be visible, follow the instructions on the screen.

<img alt="Prepare for Verification" />

For more information about the Google verification process, see [Google Support docs](https://support.google.com/cloud/answer/13463073?sjid=12970809243513943038-NC)


# Google (workspace delegation)
Source: https://docs.ampersand.ai/provider-guides/google-workspace-delegation



The Google (Workspace Delegation) connector authenticates using a Google Workspace service account with [domain-wide delegation](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority) instead of the standard Authorization Code flow. A Workspace admin authorizes the service account once, and Ampersand can then access any user's Gmail, Calendar, or Contacts data in that domain without requiring each user to go through an individual OAuth flow.

Please note that the standard [Google connector](/provider-guides/google) is a more convenient experience for individual consumers; it uses a standard OAuth 2.0 authentication scheme where each user logs in and approves the app. This connector is intended for builders who need bulk programmatic access across many users in a Workspace domain (for example, syncing calendars for every member of an organization).

## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://www.googleapis.com`.

The **Calendar** module supports:

* [Read Actions](/read-actions), including historical backfill. Incremental read is only supported for the Calendar `Events` object; otherwise, a full read of the Google instance will be performed for each scheduled run.
* [Write Actions](/write-actions).

> **Important Note on Events Backfill**: The `events` object has a 28-day cap for historic backfill and does not support full history, due to limitations in the Google API. When syncing events data, ensure your backfill period does not exceed 28 days.

The **Gmail** module supports:

* [Read Actions](/read-actions), including historical backfill. Incremental read and pagination are only supported for `Drafts`, `Messages`, and `Threads` objects; otherwise, a full read of the Gmail instance will be performed for each scheduled run.
* [Write Actions](/write-actions).

### Supported modules & objects

The supported modules and objects are the same as the standard [Google connector](/provider-guides/google#supported-calendar-objects). See that guide for the full list of Calendar and Gmail objects.

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: google-workspace-delegation-integration
    provider: googleWorkspaceDelegation
    ...
```

## Before you get started

This connector uses a GCP service account with domain-wide delegation. There is no interactive login - your customer's Google Workspace administrator will pre-authorize your service account's client ID with the required API scopes, and Ampersand will sign JWT assertions impersonating each user to obtain access tokens.

### Creating an installation per user

Each connection on Ampersand represents one user's access. Because domain-wide delegation can impersonate any user in the domain, you create one connection per Workspace user you want to sync — each connection shares the same service account key but carries a different user email.

#### 1. Collect information from your customer

Share the [Google Workspace Delegation customer guide](/customer-guides/google-workspace-delegation) with your customer's Google Workspace Admin. Then collect the following information from them either manually or via a UI in your application:

* Base64 encoded service account key
* List of email addresses of users whose data this integration should have access to
* Scopes that they authorized

<Note>The scopes must be a subset of what the Google Workspace admin authorized in the Admin console (Security > API controls > Domain-wide delegation). Google's JWT bearer flow requires scopes to be declared in every token request and will reject the exchange if any requested scope is not authorized. The same also applies to the user's email - it is required when impersonating a user.</Note>

#### 2. Bulk create connections and integrations

For each user whose data this integration needs to access, call the [Generate Connection endpoint](/reference/connection/generate-a-new-connection) and [Create Installation endpoint](/reference/installation/create-a-new-installation).

When using these endpoints, use the following values:

* `groupRef`: this should be the same for all the users within a Google Workspace, this can be an org ID or team ID used by your application.
* `consumerRef`: this should be different for each user, this can be a user ID from your application or any other unique ID.

Here's an example API request body for creating the connection using [Generate Connection API](/reference/connection/generate-a-new-connection) for a user with email `user@example.com`:

```json theme={"dark"}
{
  "provider": "googleWorkspaceDelegation",
  "groupRef": "g0-ref",
  "groupName": "g0-name",
  "consumerRef": "c0-ref",
  "consumerName": "c0-name",
  "providerMetadata": {
    "userEmail": {
        "value": "user@example.com"
    }
  },
  "customAuth": {
    "serviceAccountKey": "<base64-encoded JSON key>",
    "scopes": [
        "https://www.googleapis.com/auth/contacts"
    ]
  }
}
```

The API response includes an `id` field — that value is the Connection ID.

```json theme={"dark"}
{
  "id": "acde070d-8c4c-4f0d-9d8a-162843c10333"
}
```

Use the Connection ID when calling the [Create Installation endpoint](/reference/installation/create-a-new-installation), here is a sample request:

```json theme={"dark"}
{
  "groupRef": "g0-ref",
  "connectionId": "FROM_STEP_ABOVE",
  "config": {
    "content": {
      "provider": "googleWorkspaceDelegation",
      "proxy": {
        "enabled": true
      }
    }
  }
}
```

Repeat the above steps for each user in the Google Workspace whose data this integration needs to access.

## Using the connector

To start integrating with Google (Workspace Delegation):

* Create a manifest file like the [Google Calendar example](https://github.com/amp-labs/samples/blob/main/google-calendar/amp.yaml), using `googleWorkspaceDelegation` as the provider instead of `google`.
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Collect your customer's service account key, then create one connection per Workspace user (service account key + user email + scopes).
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Customer guide

The [Google workspace delegation customer guide](/customer-guides/google-workspace-delegation) is a guide that can be shared with your customers to help them set up a service account and authorize domain-wide delegation.


# Gorgias
Source: https://docs.ampersand.ai/provider-guides/gorgias



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported. A full read of the Gorgias instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.gorgias.com`.

### Supported Objects

The Gorgias connector supports reading from the following objects:

* [account/settings](https://developers.gorgias.com/reference/list-account-settings)
* [customers](https://developers.gorgias.com/reference/list-customers)
* [custom-fields](https://developers.gorgias.com/reference/list-custom-fields)
* [events](https://developers.gorgias.com/reference/list-events)
* [integrations](https://developers.gorgias.com/reference/list-integrations)
* [jobs](https://developers.gorgias.com/reference/list-jobs)
* [macros](https://developers.gorgias.com/reference/list-macros)
* [rules](https://developers.gorgias.com/reference/list-rules)
* [satisfaction-surveys](https://developers.gorgias.com/reference/list-satisfaction-surveys)
* [tags](https://developers.gorgias.com/reference/list-tags)
* [teams](https://developers.gorgias.com/reference/list-teams)
* [tickets](https://developers.gorgias.com/reference/list-tickets)
* [messages](https://developers.gorgias.com/reference/list-messages)
* [users](https://developers.gorgias.com/reference/list-users)
* [views](https://developers.gorgias.com/reference/list-views)
* [phone/voice-calls](https://developers.gorgias.com/reference/list-voice-calls)
* [phone/voice-call-recordings](https://developers.gorgias.com/reference/list-voice-call-recordings)
* [phone/voice-call-events](https://developers.gorgias.com/reference/list-voice-call-events)
* [widgets](https://developers.gorgias.com/reference/list-widgets)

The Gorgias connector supports writing to the following objects:

* [account/settings](https://developers.gorgias.com/reference/update-account-settings)
* [customers](https://developers.gorgias.com/reference/create-customer)
* [custom-fields](https://developers.gorgias.com/reference/create-custom-field)
* [integrations](https://developers.gorgias.com/reference/create-integration)
* [jobs](https://developers.gorgias.com/reference/create-job)
* [macros](https://developers.gorgias.com/reference/create-macro)
* [rules](https://developers.gorgias.com/reference/create-rule)
* [satisfaction-surveys](https://developers.gorgias.com/reference/create-satisfaction-survey)
* [search](https://developers.gorgias.com/reference/search-1)
* [tags](https://developers.gorgias.com/reference/create-tag)
* [teams](https://developers.gorgias.com/reference/create-team)
* [tickets](https://developers.gorgias.com/reference/create-ticket)
* [users](https://developers.gorgias.com/reference/create-user)
* [views](https://developers.gorgias.com/reference/create-view)
* [widgets](https://developers.gorgias.com/reference/create-widget)

### Example integration

To define an integration for Gorgias, create a manifest file that looks like this: [https://github.com/amp-labs/samples/blob/main/gorgias/amp.yaml](https://github.com/amp-labs/samples/blob/main/gorgias/amp.yaml)

## Before You Get Started

To integrate Gorgias with Ampersand, you will need [a Gorgias Account](https://www.gorgias.com/).

Once your account is created, you'll need to register an OAuth app and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Gorgias Developer Account

Here's how you can sign up for a Gorgias account:

* Go to the [Gorgias Developer Sign Up](https://partners.gorgias.com/login) page.
* Sign up using your preferred method.

### Creating a Gorgias OAuth App

Follow the steps below to create a Gorgias OAuth app:

1. Log in to your Gorgias account.

2. Go to **Settings** > **REST API**.

3. In the OAuth 2.0 section, click on **Add new application**.

4. Enter the following details:
   1. **Application name:** Choose a name for your integration.
   2. **Application Tagline:** Enter a tagline for your integration.
   3. **App Icon:** Upload the app icon.
   4. **App URL:** Enter the app URL.
   5. **Redirect URI:** Enter `https://api.withampersand.com/callbacks/v1/oauth`.

5. Click **Create**.

<img alt="Alt text" />

You will see the **Client ID** and **Client Secret** in the app details. Note these credentials, as you will need them to connect your app to Ampersand.

## Add Your Gorgias App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a *Gorgias* integration.
3. Select **Provider Apps**.
4. Select *Gorgias* from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

<img alt="Alt text" />

6. Enter the scopes set for your application in *Gorgias*.

7. Click **Save Changes**.

## Using the connector

To start integrating with Gorgias:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/gorgias/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Granola
Source: https://docs.ampersand.ai/provider-guides/granola



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://public-api.granola.ai`.

### Supported Objects

The Granola connector supports only reading from the following objects:

* [notes](https://docs.granola.ai/api-reference/get-note)

### Example integration

For an example manifest file of a Granola integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/granola/amp.yaml).

## Before you get started

To use the Granola connector, you’ll need an API key from your Granola account. Here’s how to get it:

1. Navigate to **Settings** → **Workspaces**.
2. Select the **API** tab.
3. Click **Generate API Key**.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To integrate with Granola:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Groove
Source: https://docs.ampersand.ai/provider-guides/groove



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Groove instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.groovehq.com`.

### Supported Objects

The groove connector supports reading from the following objects:

* [tickets](https://doc.groovehq.com/tickets#listing-tickets)
* [customers](https://doc.groovehq.com/customers#listing-all-customers)
* [mailboxes](https://doc.groovehq.com/mailboxes#listing-mailboxes)
* [folders](https://doc.groovehq.com/folders#listing-folders)
* [agents](https://doc.groovehq.com/agents#listing-agents)
* [groups](https://doc.groovehq.com/groups#listing-groups)
* [kb/themes](https://doc.groovehq.com/knowledge-base-themes#listing-themes)
* [widgets](https://doc.groovehq.com/widgets#listing-widgets)
* [kb](https://doc.groovehq.com/knowledge-bases#listing-knowledge-bases)
* [tickets/count](https://doc.groovehq.com/ticket-counts#listing-ticket-counts)

The groove connector supports writing to the following objects:

* [tickets](https://doc.groovehq.com/tickets#creating-a-new-ticket)
* [webhooks](https://doc.groovehq.com/webhooks#creating-a-webhook)
* [groups](https://doc.groovehq.com/groups#creating-a-new-group)
* [widgets](https://doc.groovehq.com/widgets#creating-a-widget)

### Example integration

For an example manifest file of a Groove integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/groove/amp.yaml).

## Before You Get Started

To integrate Groove with Ampersand, you must register a Groove OAuth2 application. To do this, contact [support@groovehq.com](mailto:support@groovehq.com) and provide the following details:

* **Redirect/Callback URL** is an HTTPS endpoint that will handle the secure callback. For an Ampersand integration, use the following callback URL: [https://api.withampersand.com/callbacks/v1/oauth](https://api.withampersand.com/callbacks/v1/oauth).
* You can also provide additional callback URLs to be added, but only HTTPS URLs are allowed.

Once your application is registered, you will receive two credentials: **client\_id** and **client\_secret.** These credentials are required to connect Groove with Ampersand.

## Add Your Groove App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Groove integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Groove* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Ampersand Integration" />


# Guru
Source: https://docs.ampersand.ai/provider-guides/guru



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.getguru.com`.

### Example integration

To define an integration for Guru, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: guru-integration
    displayName: My Guru Integration
    provider: guru
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Guru:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://api.getguru.com`.


# Gusto
Source: https://docs.ampersand.ai/provider-guides/gusto



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Gusto instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.gusto.com`.

### Supported objects

The Gusto connector supports reading from the following objects:

* [admins](https://docs.gusto.com/app-integrations/reference)
* [companies](https://docs.gusto.com/app-integrations/reference)
* [company\_benefits](https://docs.gusto.com/app-integrations/reference)
* [contractor\_payments](https://docs.gusto.com/app-integrations/reference)
* [contractors](https://docs.gusto.com/app-integrations/reference)
* [custom\_fields](https://docs.gusto.com/app-integrations/reference)
* [departments](https://docs.gusto.com/app-integrations/reference)
* [earning\_types](https://docs.gusto.com/app-integrations/reference)
* [employee\_benefits](https://docs.gusto.com/app-integrations/reference)
* [employees](https://docs.gusto.com/app-integrations/reference)
* [garnishments](https://docs.gusto.com/app-integrations/reference)
* [home\_addresses](https://docs.gusto.com/app-integrations/reference)
* [jobs](https://docs.gusto.com/app-integrations/reference)
* [locations](https://docs.gusto.com/app-integrations/reference)
* [pay\_periods](https://docs.gusto.com/app-integrations/reference)
* [pay\_schedules](https://docs.gusto.com/app-integrations/reference)
* [payrolls](https://docs.gusto.com/app-integrations/reference)
* [time\_off\_activities](https://docs.gusto.com/app-integrations/reference)
* [work\_addresses](https://docs.gusto.com/app-integrations/reference)

The Gusto connector supports writing to the following objects:

* [admins](https://docs.gusto.com/app-integrations/reference)
* [companies](https://docs.gusto.com/app-integrations/reference)
* [company\_benefits](https://docs.gusto.com/app-integrations/reference)
* [compensations](https://docs.gusto.com/app-integrations/reference)
* [contractor\_payments](https://docs.gusto.com/app-integrations/reference)
* [contractors](https://docs.gusto.com/app-integrations/reference)
* [departments](https://docs.gusto.com/app-integrations/reference)
* [earning\_types](https://docs.gusto.com/app-integrations/reference)
* [employee\_benefits](https://docs.gusto.com/app-integrations/reference)
* [employees](https://docs.gusto.com/app-integrations/reference)
* [garnishments](https://docs.gusto.com/app-integrations/reference)
* [home\_addresses](https://docs.gusto.com/app-integrations/reference)
* [jobs](https://docs.gusto.com/app-integrations/reference)
* [locations](https://docs.gusto.com/app-integrations/reference)
* [pay\_periods](https://docs.gusto.com/app-integrations/reference)
* [pay\_schedules](https://docs.gusto.com/app-integrations/reference)
* [payrolls](https://docs.gusto.com/app-integrations/reference)
* [work\_addresses](https://docs.gusto.com/app-integrations/reference)

### Example integration

For an example manifest file of a Gusto integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/gusto/amp.yaml).

## Before you get started

To connect Gusto with Ampersand, you will need a [Gusto Developer Account](https://dev.gusto.com/).

Once your account is created, you'll need to register an application in the Gusto Developer Portal and obtain the following credentials:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Gusto app

1. Log in to the [Gusto Developer Portal](https://dev.gusto.com/).

2. Navigate to the **Applications** tab and click **Create Application**.

3. Enter the following details for your application:
   * **Application Name**: The name of your app.
   * **Purpose**: A description of your integration.

4. Under **Redirect URIs**, add: `https://api.withampersand.com/callbacks/v1/oauth`

5. Click **Create**. Note the **Client ID** and **Client Secret**. You will need these to connect your app to Ampersand.

For more details, see the [Gusto Authentication documentation](https://docs.gusto.com/app-integrations/docs/authentication).

### Add your Gusto app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Gusto integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Gusto** from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from your Gusto app.

6. Click **Save Changes**.

## Using the connector

To start integrating with Gusto:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# HappyFox
Source: https://docs.ampersand.ai/provider-guides/happyfox



## What's Supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported. A full read of the HappyFoxChat instance will be done for each scheduled read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.happyfoxchat.com`.

### Supported Objects

The HappyFox connector supports reading from the following objects:

* [agents](https://developer.happyfoxchat.com/#get-all-agents)
* [visitors](https://developer.happyfoxchat.com/#get-all-visitors)
* [profiles](https://developer.happyfoxchat.com/#get-all-profiles)
* [departments](https://developer.happyfoxchat.com/#get-all-departments48)
* [canned-responses](https://developer.happyfoxchat.com/#get-all-canned-responses)
* [custom-fields](https://developer.happyfoxchat.com/#custom-fields)
* [triggered-chats](https://developer.happyfoxchat.com/#get-all-triggers)

### Example integration

For an example manifest file of a HappyFox integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/happyfox/amp.yaml).

To define an integration for HappyFox, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations: 
  - name: proxy-happyfox
    displayName: HappyFox
    provider: happyfox
    proxy:
      enabled: true
```

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with HappyFox:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key provided by the customer. Please note that this connector's base URL is `https://api.happyfoxchat.com`.

## Creating an API key for HappyFox

1. Log in to your [HappyFox account](https://app.happyfoxchat.com/b/login) and head on over to **Apps**.
2. In **Apps**, Navigate to **Goodies** and select **Rest API**.
3. In **Rest API**, click **Manage**, where you can create new API keys.
4. In **Manage**, click **Generate a new API token** and an API Key Configuration Modal will appear.
5. Enter a Name for the API key, configure the required access permissions, and click **Generate**.

<img alt="Generate Token" />


# Help Scout Mailbox
Source: https://docs.ampersand.ai/provider-guides/helpScoutMailbox



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Helpscout instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.helpscout.net`.

### Supported Objects

The HelpscoutMailbox connector supports reading from the following objects:

* [conversations](https://developer.helpscout.com/mailbox-api/endpoints/conversations/list/)
* [customers](https://developer.helpscout.com/mailbox-api/endpoints/customers/list/)
* [mailboxes](https://developer.helpscout.com/mailbox-api/endpoints/inboxes/list/)
* [customer-properties](https://developer.helpscout.com/mailbox-api/endpoints/properties/list/)
* [tags](https://developer.helpscout.com/mailbox-api/endpoints/tags/list/)
* [teams](https://developer.helpscout.com/mailbox-api/endpoints/teams/list-teams/)
* [users](https://developer.helpscout.com/mailbox-api/endpoints/users/list/)
* [webhooks](https://developer.helpscout.com/mailbox-api/endpoints/webhooks/list/)
* [workflows](https://developer.helpscout.com/mailbox-api/endpoints/workflows/list/)

The HelpscoutMailbox connector supports writing to the following objects:

* [conversations](https://developer.helpscout.com/mailbox-api/endpoints/conversations/create/)
* [customers](https://developer.helpscout.com/mailbox-api/endpoints/customers/create/)
* [customer-properties](https://developer.helpscout.com/mailbox-api/endpoints/properties/create/)
* [webhooks](https://developer.helpscout.com/mailbox-api/endpoints/webhooks/create/)

## Before You Get Started

To connect Help Scout Mailbox with Ampersand, you will need [a Help Scout Account](https://www.helpscout.com/).

Once your account is created, you'll need to create an app in the Help Scout developer portal, configure the app, and obtain the following credentials from your app:

* App ID
* App Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Help Scout Account

Here's how you can sign up for a Help Scout account:

* Go to the [Help Scout website](https://www.helpscout.com/) and register for a new account.

### Create a Help Scout App

Follow the steps below to create a Help Scout API app:

1. Log in to your Help Scout account.
2. Navigate to the Help Scout Developer Portal.
3. From the main page, go to **Manage → My Apps → Create My App**.
4. Enter the **App Name** and **Redirection URL**.
5. Click **Create**.

   <br />

   <img alt="Ampersand Project Selection" />

Upon creation, the app will display the necessary credentials: **Client ID (App ID)** and **Client Secret (App Secret).** Note these down, as you will need them to connect your app to Ampersand.

<br />

## Add Your Help Scout App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a Help Scout integration.\\
   <img alt="Ampersand Project Selection" />
3. Select **Provider Apps**.
4. Select **Help Scout Mailbox** from the **Provider** list.
5. Enter the previously obtained **App ID** in the **Client ID** field and the **App Secret** in the **Client Secret** field.

   <img alt="Ampersand Project Selection" />
6. Click **Save Changes**.


# HeyReach
Source: https://docs.ampersand.ai/provider-guides/heyreach



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Heyreach instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.heyreach.io/api`.

### Supported Objects

The heyreach connector supports reading from the following objects:

* [campaign/GetAll](https://documenter.getpostman.com/view/23808049/2sA2xb5F75#4aaf461e-54c4-4447-beb6-eb5ccca53fb3)
* [li\_account/GetAll](https://documenter.getpostman.com/view/23808049/2sA2xb5F75#8a4d2924-d46c-443f-a4df-65216988a091)
* [list/GetAll](https://documenter.getpostman.com/view/23808049/2sA2xb5F75#c8ef68b4-c329-41ae-8298-72f2336bbb78)

The heyreach connector supports writing to the following objects:

* [list/CreateEmptyList](https://documenter.getpostman.com/view/23808049/2sA2xb5F75#69288286-5cfd-4d5b-9a7e-e758ebbdc988)
* [campaign/AddLeadsToCampaignV2](https://documenter.getpostman.com/view/23808049/2sA2xb5F75#9071e40e-3f6f-473c-b107-b07d36c25d29)
* [list/AddLeadsToListV2](https://documenter.getpostman.com/view/23808049/2sA2xb5F75#b1c5d588-09e6-4085-aafc-5a1b3a92d81a)
* [inbox/SendMessage](https://documenter.getpostman.com/view/23808049/2sA2xb5F75#6e32c3b6-bffc-4ea7-8a51-0e6416dad1df)

### Example integration

To define an integration for HeyReach, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: heyreach-integration
    displayName: My HeyReach Integration
    provider: heyreach
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with HeyReach:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/heyreach/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Calls](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for HeyReach

1. Log in to your [HeyReach Dashboard](https://app.heyreach.io/app/dashboard).

2. Navigate to **Integrations**.

3. Select **Get API Key**.

4. Click **New API Key**.

<img alt="Alt text" />


# HighLevel
Source: https://docs.ampersand.ai/provider-guides/highlevel



## What's Supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://services.leadconnectorhq.com`.

### Supported Objects

The HighLevel connector supports writing to and reading from the following objects:

* [businesses](https://highlevel.stoplight.io/docs/integrations/bb6b717cac89c-business-api) (read, write)
* [calendars](https://highlevel.stoplight.io/docs/integrations/5339a7ea3f2f2-calendars-api) (read, write)
* [calendars/groups](https://highlevel.stoplight.io/docs/integrations/5339a7ea3f2f2-calendars-api) (read, write)
* [campaigns](https://highlevel.stoplight.io/docs/integrations/35a5ad3408e98-campaigns-api) (read)
* [conversations/search](https://highlevel.stoplight.io/docs/integrations/d45ae3189eea8-search-conversations) (read)
* [emails/schedule](https://highlevel.stoplight.io/docs/integrations/aa18a7110c584-get-campaigns) (read)
* [forms/submissions](https://highlevel.stoplight.io/docs/integrations/a6114bd7685d1-get-forms-submissions) (read)
* [forms](https://highlevel.stoplight.io/docs/integrations/49e29c1716c61-get-forms) (read)
* [invoices](https://highlevel.stoplight.io/docs/integrations/dcaf05eb72b81-invoice-api) (read, write)
* [invoices/template](https://highlevel.stoplight.io/docs/integrations/dcaf05eb72b81-invoice-api) (read, write)
* [invoices/schedule](https://highlevel.stoplight.io/docs/integrations/dcaf05eb72b81-invoice-api) (read, write)
* [invoices/estimate/list](https://highlevel.stoplight.io/docs/integrations/18211945fb8f5-list-estimates) (read)
* [invoices/estimate/template](https://highlevel.stoplight.io/docs/integrations/dcaf05eb72b81-invoice-api) (read, write)
* [links](https://highlevel.stoplight.io/docs/integrations/85c4db13a5d69-links-api) (read, write)
* [blogs/authors](https://highlevel.stoplight.io/docs/integrations/2ad8896e803e7-get-all-authors) (read)
* [blogs/categories](https://highlevel.stoplight.io/docs/integrations/8ebd3128ee462-get-all-categories) (read)
* [funnels/lookup/redirect/list](https://highlevel.stoplight.io/docs/integrations/a1a9c79cd27ed-fetch-list-of-redirects) (read)
* [funnels/funnel/list](https://highlevel.stoplight.io/docs/integrations/80d7ad39f1e90-fetch-list-of-funnels) (read)
* [opportunities/pipelines](https://highlevel.stoplight.io/docs/integrations/a163e98c45b8d-search-opportunity) (read)
* [payments/orders](https://highlevel.stoplight.io/docs/integrations/378562f514a17-list-orders) (read)
* [payments/transactions](https://highlevel.stoplight.io/docs/integrations/4d127e6508f0a-list-transactions) (read)
* [payments/subscriptions](https://highlevel.stoplight.io/docs/integrations/33c965c6cb9da-list-subscriptions) (read)
* [payments/coupon/list](https://highlevel.stoplight.io/docs/integrations/f1a58fadab467-list-coupons) (read)
* [products](https://highlevel.stoplight.io/docs/integrations/486b7c90818f4-products-api) (read, write)
* [products/inventory](https://highlevel.stoplight.io/docs/integrations/2c26c555258c6-list-inventory) (read)
* [products/collections](https://highlevel.stoplight.io/docs/integrations/486b7c90818f4-products-api) (read, write)
* [products/reviews](https://highlevel.stoplight.io/docs/integrations/1c3f34f44689a-fetch-product-reviews) (read)
* [proposals/document](https://highlevel.stoplight.io/docs/integrations/60ec57df068f6-list-documents) (read)
* [proposals/templates](https://highlevel.stoplight.io/docs/integrations/da393f098cd9e-list-templates) (read)
* [store/shipping-zone](https://highlevel.stoplight.io/docs/integrations/8994a68c52c5c-store-api) (read, write)
* [store/shipping-carrier](https://highlevel.stoplight.io/docs/integrations/caea983361099-list-shipping-carriers) (read, write)
* [store/store-setting](https://highlevel.stoplight.io/docs/integrations/2625702057180-get-store-settings) (read)
* [surveys](https://highlevel.stoplight.io/docs/integrations/1e9fdbe3f2013-get-surveys) (read)
* [users](https://highlevel.stoplight.io/docs/integrations/7f581f780cf2f-users-api) (read, write)
* [workflows](https://highlevel.stoplight.io/docs/integrations/070d2f9be5549-get-workflow) (read)
* [locations/search](https://highlevel.stoplight.io/docs/integrations/12f3fb56990d3-search) (read)
* [custom-menus](https://highlevel.stoplight.io/docs/integrations/e377daf40adc8-custom-menus-api) (read, write)
* [marketplace/billing/charges](https://highlevel.stoplight.io/docs/integrations/c8ed91df11efc-get-all-wallet-charges) (read)
* [calendars/events/appointments](https://highlevel.stoplight.io/docs/integrations/a192f863cad27-create-appointment) (write)
* [calendars/events/block-slots](https://highlevel.stoplight.io/docs/integrations/5a52896a68879-create-block-slot) (write)
* [contacts](https://highlevel.stoplight.io/docs/integrations/4c8362223c17b-create-contact) (write)
* [objects](https://highlevel.stoplight.io/docs/integrations/ef91fb5866e4c-create-custom-object) (read, write)
* [associations](https://highlevel.stoplight.io/docs/integrations/e4e2b47e593b3-create-association) (write)
* [associations/relations](https://highlevel.stoplight.io/docs/integrations/706670bc1dafa-create-relation-for-you-associated-entities) (write)
* [custom-fields](https://highlevel.stoplight.io/docs/integrations/55c9675bf56ce-create-custom-field) (write)
* [custom-fields/folder](https://highlevel.stoplight.io/docs/integrations/52e9e97f3c50a-create-custom-field-folder) (write)
* [conversations](https://highlevel.stoplight.io/docs/integrations/8d0b19e09176e-create-conversation) (write)
* [conversations/messages](https://highlevel.stoplight.io/docs/integrations/5853cb0a54971-send-a-new-message) (write)
* [conversations/messages/inbound](https://highlevel.stoplight.io/docs/integrations/3c9036411fcc3-add-an-inbound-message) (write)
* [conversations/messages/outbound](https://highlevel.stoplight.io/docs/integrations/d032812b4e850-add-an-external-outbound-call) (write)
* [conversations/messages/upload](https://highlevel.stoplight.io/docs/integrations/cd0f7973ec1b6-upload-file-attachments) (write)
* [emails/builder](https://highlevel.stoplight.io/docs/integrations/cfa78da1d70d7-create-a-new-template) (write)
* [invoices/text2pay](https://highlevel.stoplight.io/docs/integrations/e739c3a249591-create-and-send) (write)
* [invoices/estimate](https://highlevel.stoplight.io/docs/integrations/2c9fa98b3c6e1-create-new-estimate) (write)
* [locations](https://highlevel.stoplight.io/docs/integrations/7cfc7963eda7c-create-sub-account-formerly-location) (write)
* [blogs/posts](https://highlevel.stoplight.io/docs/integrations/c24ff055e7cf8-create-blog-post) (write)
* [funnels/lookup/redirect](https://highlevel.stoplight.io/docs/integrations/98aaa4819e58b-create-redirect) (write)
* [opportunities](https://highlevel.stoplight.io/docs/integrations/802093aa63900-create-opportunity) (write)
* [payments/coupon](https://highlevel.stoplight.io/docs/integrations/d681ddae80b59-create-coupon) (write)

### Example integration

For an example manifest file of a HighLevel integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/highlevel/amp.yaml).

## Before You Get Started

To connect HighLevel with Ampersand, you need [a HighLevel Account](https://marketplace.gohighlevel.com/signup).

Once your account is created, you'll need to create an app in HighLevel and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a HighLevel Account

Here's how you can sign up for a HighLevel account:

* Go to the [HighLevel Sign Up page](https://marketplace.gohighlevel.com/signup).
* Sign up using your preferred method.

### Creating a HighLevel App

Follow the steps below to create a HighLevel app and add the Ampersand redirect URL.

1. Log in to your [HighLevel](https://marketplace.gohighlevel.com/login) account.

2. Navigate to **App Dashboard** and Click **Create App** then **Create an app** modal will open.

3. In the modal, enter the **App Name**.

4. Select **App Type**: Public, select **Distribution Type** and select the **Listing Type**.

5. Click **Create App**.

   <img alt="App creation" />

### Creating Client ID and Client Secret

1. Click **Advanced Settings -> Auth**, select the necessary **Scopes** and enter the **Redirect URL**.

2. Click **Add** under **Client Keys** section, enter the Client Name and click **Add**.

   <img alt="OAuth Creation" />

   Provide all the required details and submit them for review. Once the review is complete, your application will go live.

## Add Your HighLevel App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a HighLevel integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *HighLevel* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

To start integrating with HighLevel:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/highlevel/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Hightouch
Source: https://docs.ampersand.ai/provider-guides/hightouch



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.hightouch.com`.

### Example integration

To define an integration for Hightouch, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: hightouch-integration
    displayName: My Hightouch Integration
    provider: hightouch
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Hightouch:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.hightouch.com`.

## Creating an API key for Hightouch

[Click here](https://hightouch.com/docs/api-reference) for more information about generating an API key for Hightouch.


# Hive
Source: https://docs.ampersand.ai/provider-guides/hive



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://app.hive.com`.

### Example integration

To define an integration for Hive, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: hive-integration
    displayName: My Hive Integration
    provider: hive
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Hive:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://app.hive.com`.

## Creating an API key for Hive

[Click here](https://developers.hive.com/reference/api-keys-and-auth) for more information about generating an API key for Hive. The UI components will display this link, so that your users can successfully create API keys.


# Housecall Pro
Source: https://docs.ampersand.ai/provider-guides/housecallPro



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. **Please note that incremental read is not supported for all objects.**
* [Write Actions](/write-actions).
* [Subscribe Actions](/subscribe-actions). Please note that [special set up](#set-up-subscribe-actions) is needed for Housecall Pro.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.housecallpro.com`.

### Supported Objects

| Object | Read | Write | Subscribe | Notes |
| - | - | - | - | - |
| [customers](https://docs.housecallpro.com/docs/housecall-public-api/042bd3bf861ae-get-customers) | ✓ (incremental) | ✓ | ✓ | |
| [employees](https://docs.housecallpro.com/docs/housecall-public-api/303ee235f23fa-get-employees) | ✓ | | ✓ | ¹ |
| [estimates](https://docs.housecallpro.com/docs/housecall-public-api/e430ba3d520a0-get-estimates) | ✓ (incremental) | ✓ | ✓ | |
| [events](https://docs.housecallpro.com/docs/housecall-public-api/5f8b2b787f4ba-get-events) | ✓ (incremental) | | | |
| [jobs](https://docs.housecallpro.com/docs/housecall-public-api/6c97704da8bf3-get-jobs) | ✓ (incremental) | ✓ | ✓ | |
| [job\_fields/job\_types](https://docs.housecallpro.com/docs/housecall-public-api/0c6fb36d5730d-get-job-types) | ✓ | ✓ | | |
| [leads](https://docs.housecallpro.com/docs/housecall-public-api/278974bc87e32-get-leads) | ✓ | ✓ | ✓ | ² |
| [lead\_sources](https://docs.housecallpro.com/docs/housecall-public-api/7444a4f65ed77-get-lead-sources) | ✓ | ✓ | | |
| [price\_book/materials](https://docs.housecallpro.com/docs/housecall-public-api/e404d4b30ea0d-create-material) | | ✓ | | |
| [price\_book/material\_categories](https://docs.housecallpro.com/docs/housecall-public-api/77aaf46f5b3db-get-material-categories) | ✓ (incremental) | ✓ | | |
| [price\_book/price\_forms](https://docs.housecallpro.com/docs/housecall-public-api/e9b15f38e151b-get-price-forms) | ✓ | ✓ | | |
| [price\_book/services](https://docs.housecallpro.com/docs/housecall-public-api/b68be85878ece-get-price-book-services) | ✓ | | | |
| [service\_zones](https://docs.housecallpro.com/docs/housecall-public-api/38b31504822e9-get-service-zones) | ✓ | | | |
| [routes](https://docs.housecallpro.com/docs/housecall-public-api/8d0d12e41a38b-get-routes) | ✓ | | | |
| [tags](https://docs.housecallpro.com/docs/housecall-public-api/e8fa7b29f8a8b-get-tags) | ✓ | ✓ | | |
| [invoices](https://docs.housecallpro.com/docs/housecall-public-api/65ce9f430d605-get-invoices) | ✓ | | ✓ | |
| [job.appointments](https://docs.housecallpro.com/docs/housecall-public-api/46e9e1be07621-webhooks#job-appointment-webhook-events) | | | ✓ | ³ |

¹ Subscribe only via [`otherEvents`](/subscribe-actions#other-events). In Housecall Pro's webhook UI, this event appears as `pro.created`, but the actual payload uses `employee.created`. Example fragment:

```yaml theme={"dark"}
- objectName: employee
  destination: housecallProWebhook
  otherEvents:
    - employee.created
```

² Delete events for `leads` are not reliable due to Housecall Pro platform limitations.

³ Subscribe only via [`otherEvents`](/subscribe-actions#other-events). Standard events are not supported. Example fragment:

```yaml theme={"dark"}
- objectName: job.appointments
  destination: housecallProWebhook
  otherEvents:
    - job.appointment.scheduled
    - job.appointment.rescheduled
    - job.appointment.appointment_discarded
    - job.appointment.appointment_pros_assigned
    - job.appointment.appointment_pros_unassigned
```

### Example integration

For an example manifest file of a Housecall Pro integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/housecallPro/amp.yaml).

## Before you get started

To use the Housecall Pro connector, you'll need an API Key from your Housecall Pro account. Here's how to get it:

1. Sign into your Housecall Pro account and go to App Store.
2. Find the API Key Management under My Apps, and click on it.
3. On the right-hand side, click Generate API Key.
4. Name your API Key.
5. Copy the API Key.

<img alt="Housecall Pro API Key" />

For more details, see the [Housecall Pro Authentication documentation](https://docs.housecallpro.com/docs/housecall-public-api/b87d37ae48a0d-authentication).

## Using the connector

This connector uses API Key authentication, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To integrate with Housecall Pro:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/housecallPro/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions or Subscribe Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Set up Subscribe Actions

To receive subscribe events from Housecall Pro, the **customer** will enable webhooks in their Housecall Pro UI using a webhook URL you provide.

The flow:

1. **Define the subscribe action** in your `amp.yaml` and deploy it with the [amp CLI](/cli/overview).

2. **Generate a webhook URL for each customer** in this format:

   ```
   https://subscribe-receiver.withampersand.com/zt1secx7jknlhb/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
   ```

3. **Share the [Housecall Pro customer guide](/customer-guides/housecallPro#2-set-up-webhooks-for-real-time-updates-subscribe-actions)** with the customer and the webhook URL from Step 2. The customer will paste the webhook URL into the Housecall Pro UI and enable the events your integration subscribes to.


# HubSpot
Source: https://docs.ampersand.ai/provider-guides/hubspot



## What's Supported

### Supported Actions

The Hubspot connector supports:

* [Read Actions](/read-actions), including full historic backfill, incremental reads, and filters.
* [Subscribe Actions](/subscribe-actions). Please note that [special set up](#set-up-subscribe-actions) is needed for HubSpot.
* [Write Actions](/write-actions), including Bulk Write and Delete.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.hubapi.com`.

### Supported Objects

#### CRM Objects

The connector supports reading from and writing to the following *CRM objects*,
including [standard fields](https://docs.google.com/spreadsheets/d/1FGc9zT_J9dyGghDxvqeioAva-5Gj7-2DQzKNMrbrPvw/view?usp=sharing) and custom fields:

* [calls](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/calls/guide)
* [companies](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/companies/guide)
* [contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/guide)
* [deals](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/deals/guide)
* [emails](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/emails/guide)
* [meetings](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/meetings/guide)
* [notes](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/notes/guide)
* All other [standard CRM objects](https://developers.hubspot.com/docs/guides/crm/understanding-the-crm#object-type-ids)
* Custom CRM objects

The connector only supports reading from:

* [lists](https://developers.hubspot.com/docs/api-reference/latest/crm/lists/guide) (note: incremental reads not supported for Lists)
* Users and owners ([see below](#reading-users-and-owners))

#### Marketing Objects

The connector supports reading from:

* [marketing-campaigns](https://developers.hubspot.com/docs/api-reference/latest/marketing/campaigns/guide)
* [marketing-forms](https://developers.hubspot.com/docs/api-reference/2026-09-beta/marketing/forms/guide)
* [marketing-events](https://developers.hubspot.com/docs/api-reference/latest/marketing/marketing-events/guide)
* [marketing-emails](https://developers.hubspot.com/docs/api-reference/latest/marketing/marketing-emails/guide)

#### Conversation Objects

The connector supports reading from:

* [channel-accounts](https://developers.hubspot.com/docs/api-reference/2026-09-beta/conversations/conversations/channel-accounts/get-channel-accounts)
* [channels](https://developers.hubspot.com/docs/api-reference/2026-09-beta/conversations/conversations/channels/get-channels)
* [custom-channels](https://developers.hubspot.com/docs/api-reference/latest/conversations/custom-channels/channels/get-custom-channels)
* [inboxes](https://developers.hubspot.com/docs/api-reference/2026-09-beta/conversations/conversations/inbox/get-inboxes)
* [threads](https://developers.hubspot.com/docs/api-reference/2026-09-beta/conversations/conversations/threads/get-threads)

#### Communication Objects

The connector supports reading from:

* [communication-preferences](https://developers.hubspot.com/docs/api-reference/latest/communication-preferences/guide)

#### Scheduler Objects

The connector supports reading from:

* [meeting-links](https://developers.hubspot.com/docs/api-reference/latest/scheduler/meetings/get-meeting-links)

#### Event Occurrences

Event occurrences represent specific actions captured at a point in time, such as form submissions, email delivery,
sequence activity, and other **behavioral changes**. They are useful to understand when an event
happened and how that event may relate to automation or downstream workflows.

To find the event type you are interested in, use the HubSpot Events API's
[list event types endpoint](https://developers.hubspot.com/docs/api-reference/latest/events/retrieve-events/get-event-types)
and [list custom event definitions](https://developers.hubspot.com/docs/api-reference/latest/events/define-events/create-event-definition).
Standard event type names begin with `e_`, while customer-specific custom event definitions use the `fullyQualifiedName` property with a `pe{HubId}_` prefix.
Standard events are safe to use across all customers,
while custom event definitions apply only to the specific customer account where they are defined.

The HubSpot connector exposes event types as individual objects
that follow the convention `AMPERSAND-event-occurrences-<EVENT_TYPE>`.

<Note>
  Note that **occurrences** is spelled with two c's and two r's.
</Note>

Here are a few examples of the objects you would read for different event types -

* `AMPERSAND-event-occurrences-e_call_ended`
* `AMPERSAND-event-occurrences-e_form_submission`
* `AMPERSAND-event-occurrences-e_mta_bounced_email_v2`
* `AMPERSAND-event-occurrences-e_visited_page`
* `AMPERSAND-event-occurrences-pe148543157_this_is_my_event`

#### Reading users and owners

To read users from your customer's HubSpot workspace, enable the `crm.objects.users.read` scope and add `users` as an object in `amp.yaml`:

```YAML theme={"dark"}
- objectName: users
  destination: defaultWebhook
  schedule: "0 0 * * *"
  requiredFields:
    - fieldName: hs_object_id
      mapToName: userId
    - fieldName: hubspot_owner_id
      mapToName: ownerId
    - fieldName: hs_email
      mapToName: emailAddress
```

### Associations

<Note>
  HubSpot associations is a private preview feature where you can retrieve associated records when using Read Actions or Subscribe Actions. Please contact [support@withampersand.com](mailto:support@withampersand.com) if you wish to use it.
</Note>

### Example Integration

For an example manifest file, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/hubspot/amp.yaml).

## Before You Get Started

If you don't already have one, sign up for a [free HubSpot developer account](https://app.hubspot.com/signup-hubspot/crm?intent=developer).

## Create a HubSpot App

### Method 1: New Project Apps

New Project Apps are [limited to 25 installs](https://developers.hubspot.com/changelog/new-marketplace-distribution-app-install-limits), until the app is listed on the HubSpot Marketplace. We recommend starting the process to [publish to HubSpot marketplace](#publish-to-hubspot-marketplace) as soon as you've finished building your integration and tested it internally or with a customer.

To create a New Project App:

1. **Open** the terminal

2. **Install** the HubSpot CLI: `npm install -g @hubspot/cli`

3. **Authenticate** using `hs account auth` and select open HubSpot to get your key

   <img alt="Alt text" />

   If you already have a personal access key, select "Enter existing personal
   access key" and skip to [Step 7](#create-project).

4. **Select** your account (if prompted)

<Note>
  If you have multiple accounts, make sure to select the developer account.
</Note>

5. **Create** your Personal Access Key and copy it
   <img alt="Alt text" />

6. **Go back** to terminal, **paste** the key and **hit Enter**
   <img alt="Alt text" />

7. <span>Create a project</span>:

Copy and paste this command in the terminal:

```
hs project create --name your-project-name --project-base app --distribution marketplace --auth oauth --features
```

8. Configure OAuth redirect URL and scopes

Open the folder where the HubSpot project was created and edit `src/app/app-hsmeta.json`.

Replace the `auth` section of the file with the snippet below. If you wish to read or write to more objects than **contacts**, then add more scopes. For example, if you also want to read **companies**, then you can add the following scopes:

* crm.objects.companies.read

For a full list of HubSpot scopes, please refer to [HubSpot documentation](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/scopes#list-of-available-scopes).

```json theme={"dark"}
{
  "auth": {
   "type": "oauth",
   "redirectUrls": ["https://api.withampersand.com/callbacks/v1/oauth"],
   "requiredScopes": [
      "oauth",
      "crm.objects.contacts.read",
      "crm.objects.contacts.write"
   ],
   "optionalScopes": [],
   "conditionallyRequiredScopes": []   
  }
}
```

9. **Deploy**: run the following command

```
hs project upload
```

You will be prompted to create the new project, select "yes".

<img alt="Alt text" />

10. Accept HubSpot's Acceptable Use Policy

If this is your first time creating a HubSpot app, you will need to accept HubSpot's Acceptable Use Policy before any users can install your integration.

* Log into HubSpot
* Select **Development** from the bottom of the left nav bar.

<img alt="Dev tab" />

* Select the project you just created

<img alt="Select Project" />

* In the **Project Components** section, click on the app.

<img alt="Select App" />

* Navigate to the **Distribution** tab, click on "Begin Publishing" and complete the first step "Agree to HubSpot's Acceptable Use Policy". You do not need to complete the rest of the steps right now.

<img alt="Acceptable Use Policy" />

11. Get Client ID and Client Secret

* Follow the steps from Step 10 above to navigate to your HubSpot app.
* Go to the **Auth** tab to find your **Client ID** and **Client Secret**

<img alt="Auth" />

12. Jump to [Add App to Ampersand](#add-app-to-ampersand).

### Method 2: Legacy Apps

<Note>
  Legacy Apps have no install limits but [won't receive
  new HubSpot
  features](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/overview).
  When you migrate a Legacy App to a new Project App, you will be subject to the 25 install limit until your app is listed in the HubSpot marketplace. Please see [HubSpot changelog](https://developers.hubspot.com/changelog/new-marketplace-distribution-app-install-limits) for more details.
</Note>

Depending on when you created your HubSpot developer account, you will see different UI.

#### Developer accounts created after September 2025

1. Log in to your HubSpot developer account
2. Navigate to **Development** → **Legacy apps**
   <img alt="Alt text" />

<Note>
  If you don't see the Development menu, you need Super Admin permissions.
</Note>

3. Click **Create** → Select **Public**

   <img alt="Alt text" />

4. Enter **Public app name** and go to the **Auth** tab

   Add Redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` and click "Create app"

   <img alt="Alt text" />

5. Go to the Scopes section, click "Add new scope" and **select your required scopes**
   <img alt="Alt text" />

6. **Copy your Client ID and Client Secret** from the Auth tab
   <img alt="Alt text" />

Jump to [Add App to Ampersand](#add-app-to-ampersand).

#### Developer accounts created before September 2025

1. Log in to your [HubSpot Developer Dashboard](https://app.hubspot.com/signup-hubspot/developers)
2. Click **Create an app**
   <img alt="Alt text" />
3. Enter **Public app name**, click the **Auth** tab, add Redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` and click "Create app"
   <img alt="Alt text" />
4. Go to the **Scopes** tab and select your required scopes
   <img alt="Alt text" />
5. Copy your **Client ID** and **Client Secret** from the Auth tab
   <img alt="Alt text" />

Jump to [Add App to Ampersand](#add-app-to-ampersand)

## Add App to Ampersand

After creating your app using any method above:

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com)
2. Select your project → **Provider apps**
3. Select **HubSpot** from the Provider list
4. Enter your **Client ID**, **Client Secret**, and **Scopes** and click **Save changes**.

<Note>
  These scopes must match the exact set of scopes defined in your HubSpot app.
</Note>

<img alt="Alt text" />

## Using the connector

To start integrating with HubSpot:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/hubspot/amp.yaml)
* Deploy it using the [amp CLI](/cli/overview)
* If using Read or Subscribe Actions, create a [destination](/destinations)
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component
* Start using the connector!

## Set up Subscribe Actions

<Note>
  HubSpot subscribe actions cannot notify you of changes to custom fields. There is a workaround that requires additional set up, please contact [support@withampersand.com](mailto:support@withampersand.com) for details.
</Note>

To enable HubSpot subscribe actions, you will need to:

* Define the subscribe action in your `amp.yaml` file and then deploy it. See the [Subscribe Actions documentation](/subscribe-actions) for details.
* Make modifications to the HubSpot app (see below).

### New project apps

If you are using a new project app (that was created with the HubSpot CLI), then follow the instructions below. If you don't have any apps yet, follow the instructions in [Method 1: New Project Apps](#method-1-new-project-apps) above to create one.

#### Create webhooks-hsmeta.json file

Go to the directory that contains your HubSpot app, and add a file called `your-project-name/src/app/webhooks/webhooks-hsmeta.json`. So your directory should end up like this:

```
/your-project-name
  /src/app
    /webhooks
      webhooks-hsmeta.json
    app-hsmeta.json
  hsproject.json
```

Replace `targetUrl` in the example `webhooks-hsmeta.json` file below with the one that is for your integration. It should follow the format:

```
"https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID"
```

* Replace `PROJECT_ID` with your Ampersand project ID, which can be found in the Dashboard's [General Settings page](https://dashboard.withampersand.com/projects/_/settings).
* Replace `INTEGRATION_ID` with your integration's ID, which can be found in the Dashboard's [Home page](https://dashboard.withampersand.com/projects/_).

You can also edit the file with the desired objects and events you want to subscribe to. You can refer to [HubSpot documentation](https://developers.hubspot.com/docs/apps/developer-platform/add-features/configure-webhooks#webhook-configuration) for the syntax of this file.

Example `webhooks-hsmeta.json`:

```
{
  "uid": "ampersand_subscribe_actions",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "SEE_INSTRUCTIONS_ABOVE",
      "maxConcurrentRequests": 50
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        },
        {
          "subscriptionType": "object.propertyChange",
          "objectType": "contact",
          "propertyName": "firstname",
          "active": true
        },
        {
          "subscriptionType": "object.propertyChange",
          "objectType": "contact",
          "propertyName": "lastname",
          "active": true
        },
        {
          "subscriptionType": "object.deletion",
          "objectType": "contact",
          "active": true
        }
      ]
    }
  }
}
```

#### Deploy changes to HubSpot

Once you are done editing `webhooks-hsmeta.json`, deploy it using the following command:

```
hs project upload
```

### Legacy apps

If you have a legacy app (that was created in the HubSpot UI), follow the instructions below.

1. Log in to your HubSpot account.
2. Go to the **Apps** section.
3. Select your connected app.
4. Click on **Webhooks**.
5. Enter the Target URL:

```
  https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID
```

* Replace `PROJECT_ID` with your Ampersand project ID, which can be found in the Dashboard's [General Settings page](https://dashboard.withampersand.com/projects/_/settings).
* Replace `INTEGRATION_ID` with your integration's ID, which can be found in the Dashboard's [Home page](https://dashboard.withampersand.com/projects/_).

7. Click **Create Subscription**.
8. Select object types, event types, and properties.
9. Select the required checkboxes for all objects.
10. Click **Activate**.

<img alt="Subscribe actions HubSpot" />

## Customer guide

Share the [HubSpot customer guide](/customer-guides/hubspot) with your customers to help them use your integration.

## Publish to HubSpot Marketplace

When you are ready to list on the HubSpot marketplace, follow the instructions in the [HubSpot documentation](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app).

* For the **App Information** section, you should use information about your company, not about Ampersand.
* For **Install Button URL**, use the URL of your application that users go to in order to start the installation process (this is usually where you've embedded the Ampersand UI Component).


# Hunter
Source: https://docs.ampersand.ai/provider-guides/hunter



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Hunter instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.hunter.io`.

### Supported Objects

The Hunter connector supports reading from the following objects:

* [leads](https://hunter.io/api-documentation#list-leads)
* [leads\_custom\_attributes](https://hunter.io/api-documentation#custom-attributes)
* [leads\_lists](https://hunter.io/api-documentation#list-leads-lists)
* [campaigns](https://hunter.io/api-documentation#list-campaigns)
* [account](https://hunter.io/api-documentation#account)

The Hunter connector supports writing to the following objects:

* [leads](https://hunter.io/api-documentation#create-lead)
* [leads\_custom\_attributes](https://hunter.io/api-documentation#create-custom-attribute)
* [leads\_lists](https://hunter.io/api-documentation#create-leads-list)

### Example integration

To define an integration for Hunter, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: hunter-integration
    displayName: My Hunter Integration
    provider: hunter
    proxy:
      enabled: true
```

## Before you get started

To use the Hunter connector, you'll need an API key from your Hunter account. Here's how to get it:

1. Log in to your [Hunter account](https://hunter.io/).
2. Go to the [API](https://hunter.io/api-keys) section by clicking on it from the left sidebar.
3. Generate a new API key.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Hunter:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.hunter.io`.

For detailed information about available endpoints, refer to the [Hunter API Reference](https://hunter.io/api-documentation/v2).


# Insightly
Source: https://docs.ampersand.ai/provider-guides/insightly



## What's supported

### Supported actions

This connector supports:

* [Write Actions](/write-actions).
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.insightly.com`.

### Supported Objects

The Insightly connector supports reading from and writing to the following objects:

* [ActivitySets](https://api.insightly.com/v3.1/Help#!/ActivitySets/GetActivitySets)
* [CommunityComments](https://api.insightly.com/v3.1/Help#!/ForumComments/GetEntities)
* [CommunityForums](https://api.insightly.com/v3.1/Help#!/Forums/GetEntities)
* [CommunityPosts](https://api.insightly.com/v3.1/Help#!/ForumPosts/GetEntities)
* [Contacts](https://api.insightly.com/v3.1/Help#!/Contacts/GetEntities)
* [Countries](https://api.insightly.com/v3.1/Help#!/Countries/GetCountries)
* [Currencies](https://api.insightly.com/v3.1/Help#!/Currencies/GetCurrencies)
* [CustomObjects](https://api.insightly.com/v3.1/Help#!/CustomObjects/GetCustomObjects)
* [DocumentTemplates](https://api.insightly.com/v3.1/Help#!/DocumentTemplates/GetEntities)
* [Emails](https://api.insightly.com/v3.1/Help#!/Emails/GetEntities)
* [Events](https://api.insightly.com/v3.1/Help#!/Events/GetEntities)
* [FileCategories](https://api.insightly.com/v3.1/Help#!/FileCategories/GetFileCategories)
* [Follows](https://api.insightly.com/v3.1/Help#!/Follows/GetFollows)
* [ForumCategories](https://api.insightly.com/v3.1/Help#!/ForumCategories/GetEntities)
* [KnowledgeArticle](https://api.insightly.com/v3.1/Help#!/KnowledgeArticles/GetEntities)
* [KnowledgeArticleCategory](https://api.insightly.com/v3.1/Help#!/KnowledgeArticleCategories/GetEntities)
* [KnowledgeArticleFolder](https://api.insightly.com/v3.1/Help#!/KnowledgeArticleFolders/GetEntities)
* [LeadSources](https://api.insightly.com/v3.1/Help#!/LeadSources/GetLeadSources)
* [LeadStatuses](https://api.insightly.com/v3.1/Help#!/LeadStatuses/GetLeadStatuses)
* [Leads](https://api.insightly.com/v3.1/Help#!/Leads/GetEntities)
* [MarketingVisits](https://api.insightly.com/v3.1/Help#!/MarketingVisits/GetMarketingVisits)
* [Milestones](https://api.insightly.com/v3.1/Help#!/Milestones/GetEntities)
* [Notes](https://api.insightly.com/v3.1/Help#!/Notes/GetEntities)
* [Opportunities](https://api.insightly.com/v3.1/Help#!/Opportunities/GetEntities)
* [OpportunityCategories](https://api.insightly.com/v3.1/Help#!/OpportunityCategories/GetOpportunityCategories)
* [OpportunityLineItem](https://api.insightly.com/v3.1/Help#!/OpportunityProducts/GetEntities)
* [OpportunityStateReasons](https://api.insightly.com/v3.1/Help#!/OpportunityStateReasons/GetOpportunityStateReasons)
* [Organisations](https://api.insightly.com/v3.1/Help#!/Organisations/GetEntities)
* [Permissions](https://api.insightly.com/v3.1/Help#!/Permissions/GetPermissions)
* [PipelineStages](https://api.insightly.com/v3.1/Help#!/PipelineStages/GetPipelineStages)
* [Pipelines](https://api.insightly.com/v3.1/Help#!/Pipelines/GetPipelines)
* [Pricebook](https://api.insightly.com/v3.1/Help#!/PriceBooks/GetEntitiesBySearch)
* [PricebookEntry](https://api.insightly.com/v3.1/Help#!/PriceBookEntries/GetEntities)
* [Product](https://api.insightly.com/v3.1/Help#!/Products/GetEntities)
* [ProjectCategories](https://api.insightly.com/v3.1/Help#!/ProjectCategories/GetProjectCategories)
* [Projects](https://api.insightly.com/v3.1/Help#!/Projects/GetEntities)
* [Prospect](https://api.insightly.com/v3.1/Help#!/Prospects/GetEntities)
* [Quotation](https://api.insightly.com/v3.1/Help#!/Quotes/GetEntities)
* [QuotationLineItem](https://api.insightly.com/v3.1/Help#!/QuoteProducts/GetEntitiesBySearch)
* [Relationships](https://api.insightly.com/v3.1/Help#!/Relationships/GetRelationships)
* [TaskCategories](https://api.insightly.com/v3.1/Help#!/TaskCategories/GetTaskCategories)
* [Tasks](https://api.insightly.com/v3.1/Help#!/Tasks/GetEntities)
* [TeamMembers](https://api.insightly.com/v3.1/Help#!/TeamMembers/GetTeamMembers)
* [Teams](https://api.insightly.com/v3.1/Help#!/Teams/GetTeams)
* [Ticket](https://api.insightly.com/v3.1/Help#!/Tickets/GetEntities)
* [Users](https://api.insightly.com/v3.1/Help#!/Users/GetUsers)

#### Custom Objects and Fields

In addition to standard objects, the connector fully supports any custom objects you have created in your Insightly dashboard.
Custom objects are treated as first-class citizens and can be read from and written to like any standard entity.
For each supported object — standard or custom — you can select and request any built-in fields listed in the Insightly API
documentation as well as any custom fields you have defined.

### Example integration

To define an integration for Insightly, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: insightly-integration
    displayName: My Insightly Integration
    provider: insightly
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Insightly:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://api.insightly.com`.


# Instantly
Source: https://docs.ampersand.ai/provider-guides/instantly



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.instantly.ai/api`.

### Supported Objects

The Instantly connector supports reading from the following objects:

* [accounts](https://developer.instantly.ai/api/v2/account/listaccount)
* [campaigns](https://developer.instantly.ai/api/v2/campaign/listcampaign)
* [emails](https://developer.instantly.ai/api/v2/email/listemail)
* [lead-lists](https://developer.instantly.ai/api/v2/leadlist/listleadlist)
* [inbox-placement-tests](https://developer.instantly.ai/api/v2/inboxplacementtest/listinboxplacementtest)
* [background-jobs](https://developer.instantly.ai/api/v2/backgroundjob/listbackgroundjob)
* [custom-tags](https://developer.instantly.ai/api/v2/customtag/listcustomtag)
* [block-lists-entries](https://developer.instantly.ai/api/v2/blocklistentry/listblocklistentry)
* [lead-labels](https://developer.instantly.ai/api/v2/leadlabel/listleadlabel)
* [workspace-group-members](https://developer.instantly.ai/api/v2/workspacegroupmember/listworkspacegroupmember)
* [workspace-members](https://developer.instantly.ai/api/v2/workspacemember/listworkspacemember)
* [leads/list](https://developer.instantly.ai/api/v2/lead/listleads)
* [campaigns/analytics](https://developer.instantly.ai/api/v2/analytics/getcampaignanalytics)
* [campaigns/analytics/daily](https://developer.instantly.ai/api/v2/analytics/getdailycampaignanalytics)
* [campaigns/analytics/steps](https://developer.instantly.ai/api/v2/analytics/getcampaignstepsanalytics)
* [inbox-placement-tests/email-service-provider-options](https://developer.instantly.ai/api/v2/inboxplacementtest/getinboxplacementtestespoptions)
* [audit logs](https://developer.instantly.ai/api/v2/auditlog)

The Instantly connector supports writing to the following objects:

* [accounts](https://developer.instantly.ai/api/v2/account/createaccount)
* [campaigns](https://developer.instantly.ai/api/v2/campaign/createcampaign)
* [emails/reply](https://developer.instantly.ai/api/v2/email/replytoemail)
* [lead-lists](https://developer.instantly.ai/api/v2/leadlist/createleadlist)
* [inbox-placement-tests](https://developer.instantly.ai/api/v2/inboxplacementtest/createinboxplacementtest)
* [custom-tags](https://developer.instantly.ai/api/v2/customtag/createcustomtag)
* [block-lists-entries](https://developer.instantly.ai/api/v2/blocklistentry/createblocklistentry)
* [lead-labels](https://developer.instantly.ai/api/v2/leadlabel/createleadlabel)
* [workspace-group-members](https://developer.instantly.ai/api/v2/workspacegroupmember/createworkspacegroupmember)
* [workspace-members](https://developer.instantly.ai/api/v2/workspacemember/createworkspacemember)
* [email-verification](https://developer.instantly.ai/api/v2/emailverification/createemailverification)
* [leads/merge](https://developer.instantly.ai/api/v2/lead/mergeleads)
* [leads/update-interest-status](https://developer.instantly.ai/api/v2/lead/updateleadintereststatus)
* [leads/subsequence/remove](https://developer.instantly.ai/api/v2/lead/removeleadfromsubsequence)
* [leads/move](https://developer.instantly.ai/api/v2/lead/moveleads)
* [leads/export](https://developer.instantly.ai/api/v2/lead/exportleads)
* [leads/subsequence/move](https://developer.instantly.ai/api/v2/lead/moveleadtosubsequence)
* [custom-tags/toggle-resource](https://developer.instantly.ai/api/v2/customtag/toggletagresource)
* [workspaces/current](https://developer.instantly.ai/api/v2/workspace/patchworkspace)

### Example integration

For an example manifest file of an Instantly integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/instantly/amp.yaml).

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Instantly:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/instantly/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Calls](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Instantly:

1. Log in to your [Instantly Account](https://app.instantly.ai/auth/login).

2. Navigate to **settings**.

3. Click **Integrations** and navigate to **APIKeys**.

4. Click **Create API Key**.

<img alt="Alt text" />


# Intercom
Source: https://docs.ampersand.ai/provider-guides/intercom



## What's Supported

### Supported Actions

The Intercom connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `conversations`, `contacts`, `activity_logs` and `tickets` currently. For all other objects, a full read of the Intercom instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.intercom.io`.

### Supported Objects

The Intercom connector supports writing to and reading from the following objects:

* [Activity Logs](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/models/activity_log) (incremental read)
* [Admins](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/admins/admin)
* [Articles](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/articles/article)
* [Collections](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/help-center/collection)
* [Companies](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/companies/company)
* [Contacts](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/contacts/contact) (incremental read)
* [Conversations](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/conversations/conversation) (incremental read)
* [Data Attributes](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/data-attributes/data_attribute)
* [Events](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/models/data_event_summary)
* [Help Centers](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/help-center/help_center)
* [News Items](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/news/news_item)
* [Newsfeeds](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/news/newsfeed)
* [Segments](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/segments/segment)
* [Subscription Types](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/subscription-types/subscription_type)
* [Tags](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/tags/tag)
* [Teams](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/teams/team)
* [Ticket Types](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/tickets/ticket_type)
* [Tickets](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/tickets/ticket) (incremental read)

### Example Integration

For an example manifest file of an Intercom integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/intercom/amp.yaml).

## Before You Get Started

To integrate Intercom with Ampersand, you need to [Create an Intercom Account](#create-an-intercom-account) and obtain the following credentials from an Intercom App:

* Client ID
* Client Secret

### Create an Intercom Account

You need an **Intercom** account to connect with Ampersand. If you do not have an Intercom account, here's how you can sign up:

* Go to the [Intercom Developer site](https://developers.intercom.com/building-apps/docs/getting-started) and sign up for a free developer account.

## Creating an Intercom App

Once your Intercom Developer account is ready, you need to create an Intercom application. Learn more about creating an Intercom application [here](https://developers.intercom.com/building-apps/docs/setting-up-your-app-on-intercom).

1. Log in to Your [Intercom Developer Dashboard](https://app.intercom.io/a/apps/_YOUR_APP_ID_/developer).
2. Click **New App** and follow the prompts to create your app.
3. Click **Create App**.

<img alt="Alt text" />

### Adding Ampersand Redirect URL to Intercom App

Ampersand uses a redirect URL to integrate with your Intercom app.

Follow the steps below to add the Ampersand URL to Intercom:

1. Go to your [Intercom developer dashboard](https://developers.intercom.com/) and select your application.

2. Navigate to `Configure > Authentication` and click **Edit**.

3. Enable the **Use OAuth** option.

4. In the **Redirect URL** section, click **Add URL** and add the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

   <img alt="Alt text" />

<br />

### Accessing Client ID and Client Secret

Once your app is created, Intercom provides your *Client ID* and *Client Secret* which are used to add your Intercom App to Ampersand.

Here's how you can obtain the credentials you'll need:

1. Go to your [Intercom developer dashboard](https://developers.intercom.com/) and select your application.
2. You will find your *Client ID* and *Client Secret* under the **Basic Information** section.

You can now add your Intercom App Details to Ampersand.

## Add Intercom App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to add the Intercom App.

   <img alt="Alt text" />

   <br />
3. Select **Provider apps**.
4. Select *Intercom* from the **Provider** list.
5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <br />

   <img alt="Alt text" />
6. Click **Save Changes**.

## Using the connector

To start integrating with Intercom:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/intercom/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Ironclad
Source: https://docs.ampersand.ai/provider-guides/ironclad



## What's Supported

### Supported Actions

This connector supports:

* **Proxy Actions**, using the base URL `https://ironcladapp.com`.

## Before You Get Started

To integrate Ironclad with Ampersand, you will need [an Ironclad Account](https://ironcladapp.com/).

Once your account is created, you'll need to register an OAuth app and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create an Ironclad Account

Here's how you can sign up for an Ironclad account:

1. Go to the [Ironclad Sign Up](https://ironcladapp.com/signin) page.
2. Fill out the form to request a demo or contact Ironclad's sales team to set up an account.

### Creating an Ironclad OAuth App

Follow the steps below to create an Ironclad OAuth app:

1. Log in to your [Ironclad](https://ironcladapp.com/signin) account.
2. Navigate to the `Company Settings >> API` section.
3. Click **Create new app**.
4. Enter a name for your application, and click **Create app**.

You'll see your **Client ID** and **Client Secret**. Note these credentials, as you'll need them to connect to Ampersand.

5. Click **Continue.**
6. In the **Redirect URIs** section, add the ampersand redirect URI: `https://api.withampersand.com/callbacks/v1/oauth`.
7. In the **Scopes** section, select the scopes applicable for your application.
8. Click **Save Changes**.

<img alt="Alt text" />

## Add Your Ironclad OAuth Credentials to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create an *Ironclad* integration.
3. Select **Provider Apps**.
4. Select *Ironclad* from the **Provider** list.
5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.
6. Enter the scopes set for your application in *Ironclad*.

<img alt="Alt text" />

7. Click **Save Changes**.


# Iterable
Source: https://docs.ampersand.ai/provider-guides/iterable



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Iterable instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.iterable.com`.

The Iterable connector supports writing to and reading from the following objects:

* [campaigns](https://api.iterable.com/api/docs#campaigns_campaigns)
* [catalogs](https://api.iterable.com/api/docs#catalogs_listCatalogs)
* [lists](https://api.iterable.com/api/docs#lists_getLists)
* [webhooks](https://api.iterable.com/api/docs#webhooks_getWebhooks)

Iterable allows the following objects to only be read, and not written to:

* [channels](https://api.iterable.com/api/docs#channels_channels)
* [jobs](https://api.iterable.com/api/docs#export_getExportJobs)
* [journeys](https://api.iterable.com/api/docs#workflows_getJourneys)
* [messageTypes](https://api.iterable.com/api/docs#messageTypes_messageTypes)
* [messages](https://api.iterable.com/api/docs#Embedded_Messaging_messages)
* [metadata](https://api.iterable.com/api/docs#metadata_list_tables)
* [templates](https://api.iterable.com/api/docs#templates_getTemplates)

Iterable allows the following objects to only be written to:

* [templatesEmail](https://api.iterable.com/api/docs#templates_upsertEmailTemplate)
* [templatesInApp](https://api.iterable.com/api/docs#templates_upsertInAppTemplate)
* [templatesPush](https://api.iterable.com/api/docs#templates_upsertPushTemplate)
* [templatesSMS](https://api.iterable.com/api/docs#templates_upsertSMSTemplate)
* [users](https://api.iterable.com/api/docs#users_updateUser)

### Example integration

For an example manifest file of an Iterable integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/iterable/amp.yaml).

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Iterable:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.iterable.com`.

## Creating an API key for Iterable

[Click here](https://app.iterable.com/settings/apiKeys) for more information about generating an API key for Iterable. The UI components will display this link, so that your users can successfully create API keys.


# Jira
Source: https://docs.ampersand.ai/provider-guides/jira



Jira is supported in the Atlassian provider, please refer to the [Atlassian guide](/provider-guides/atlassian).


# Jobber
Source: https://docs.ampersand.ai/provider-guides/jobber



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for the following objects: `capitalLoans`, `clients`, `expenses`, `invoices`, `jobs`, `payoutRecords`, `quotes`, `requests`, `tasks`, `timeSheetEntries`, and `visits`. For all other objects, a full read of the Jobber instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Subscribe Actions](/subscribe-actions). Ampersand creates and manages the Jobber webhook subscriptions on your behalf when the customer installs your integration — no manual webhook setup is required in the Jobber UI.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.getjobber.com/api/graphql`.

### Supported Objects

The Jobber connector supports the following objects:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

<Note>
  For detailed information about available objects, refer to the [Jobber Developer Documentation](https://developer.getjobber.com/docs/).
  The full list of read and write objects can be retrieved after logging in. To explore them, go to "Manage Apps", click "Actions" from the respective app, and then click "Test in GraphiQL".
</Note>

### Subscribe events

All 12 subscribe-enabled objects in the table above support **create**, **update**, and **delete** events, with one exception: `users` has no delete event.

Please note that:

* **Watched fields are not supported.** Jobber webhook payloads do not include changed-field data, so field-level update filtering (`requiredWatchFields`) is not available. Use `watchFieldsAuto: all` for update events — they will fire on any change to the record.
* **Scopes gate event delivery.** Jobber only delivers events for an object if your Jobber app holds the matching read scope (e.g. `read_clients` for client events). Make sure the scopes selected when [creating your Jobber app](#creating-a-jobber-app) cover every object you subscribe to.

In addition to create, update, and delete, Jobber emits a few non-CRUD lifecycle topics. You can subscribe to these on the owning object via [`otherEvents`](/subscribe-actions#other-events):

| Object | Pass-through events |
| - | - |
| quotes | `QUOTE_SENT`, `QUOTE_APPROVED` |
| jobs | `JOB_CLOSED` |
| visits | `VISIT_COMPLETE` |

For example:

```yaml theme={"dark"}
subscribe:
  objects:
    - objectName: quotes
      destination: jobberWebhook
      inheritFieldsAndMapping: true
      createEvent:
        enabled: always
      updateEvent:
        enabled: always
        watchFieldsAuto: all
      deleteEvent:
        enabled: always
      otherEvents:
        - QUOTE_SENT
        - QUOTE_APPROVED
```

Jobber also emits a handful of account-level topics that don't map to a subscribable object: `PAYMENT_CREATE`, `PAYMENT_UPDATE`, `PAYMENT_DESTROY`, `APP_CONNECT`, `APP_DISCONNECT`, `ON_MY_WAY_TRACKING_LINK_REQUEST`, and `MARKETING_ITEM_UPDATE`. These can be added to the `otherEvents` list of any subscribed object.

### Example integration

For an example manifest file of a Jobber integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/jobber/amp.yaml).

## Before you get started

To connect Jobber with Ampersand, you will need a [Jobber Account](https://www.getjobber.com/).

Once your account is created, you'll need to [Create a Jobber Developer Account](https://developer.getjobber.com) and obtain the following credentials from your Jobber App:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

<Note>
  Jobber uses GraphQL for all API operations. When making proxy calls, you must include the `X-JOBBER-GRAPHQL-VERSION` header with the API version (e.g., `2025-01-20`) in all requests, as this is mandatory for Jobber's GraphQL API. You can find the latest API version information in the [Jobber API Changelog](https://developer.getjobber.com/docs/changelog/).
</Note>

### Create a Jobber developer account

Here's how you can sign up for a Jobber account:

* Go to the [Jobber Developer Center](https://developer.getjobber.com/signup/) and create a developer account.
* Complete the registration process and verify your email.

## Creating a Jobber app

Once your Jobber Developer account is ready, you need to create a Jobber application:

1. Log in to your [Jobber Developer Center](https://developer.getjobber.com/).

2. Navigate to the [Apps page](https://developer.getjobber.com/apps).

3. Click **NEW** to create your first app.

4. Fill in the required information:
   * **App name** (required)
   * **Developer name** (required)
   * **OAuth Callback URL**: Use `https://api.withampersand.com/callbacks/v1/oauth`
   * **App description** (required)
   * **Scopes** (required) - Select the data access permissions your app needs

5. Click **Save** to create your app.

Upon creation, the app will display the necessary credentials: **Client ID** and **Client Secret.** Note these down, as you will need them to connect your app to Ampersand.

## Add your Jobber app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a Jobber integration.\\
   <img alt="Ampersand Project Selection" />
3. Select **Provider apps**.
4. Select **Jobber** from the **Provider** list.
5. Enter the previously obtained **Client ID** and **Client Secret**.
6. Click **Save changes**.

## Using the connector

To start integrating with Jobber:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/jobber/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions or Subscribe Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Join.me
Source: https://docs.ampersand.ai/provider-guides/joinMe



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL [https://api.join.me](https://api.join.me).

## Before You Get Started

To connect Join.me with Ampersand, you need [a Join.me Account](https://developer.join.me/).

Once your account is created, you'll need to create an app in Join.me and obtain the following credentials from your app:

* Key(Client ID)
* Secret(Client Secret)

You will then use these credentials to connect your application to Ampersand.

### Creating a Join.me App

Follow the steps below to create a Join.me app and add the Ampersand redirect URL.

1. Log in to your [Join.me](https://developer.join.me/login) account.

2. Once logged in, click on the **Login Credentials** link located in the upper-right corner of your Join.me account.

3. Click on the **Applications -> Create a New Application**

4. Enter Application Name in the **Name of the Application** section.

5. Enter website url in the **Web site** section and describe what the application does in the **Description** section.

6. Enter the Ampersand Callback URI: `https://api.withampersand.com/callbacks/v1/oauth` in the **Register Callback URL** section.

7. Agree to the terms of service and then, Click the **Register Application**.

   <img alt="Join.me OAuth Creation" />

### Example integration

To define an integration for Join.me, create a manifest file that looks like this:

```YAML theme={"dark"}
#amp.yaml
specVersion: 1.0.0
integrations: 
  - name: joinMeIntegration
    displayName: Join Me
    provider: joinMe
    proxy:
      enabled: true
```

## Add Your Join.me App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Join.me integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select Join Me from the **Provider** list.

5. Enter the previously obtained Client ID in the **Client ID** field, the Client Secret in the **Client Secret** field and scopes in the **Scopes** field.

   <img alt="Ampersand Integration" />


# Jotform
Source: https://docs.ampersand.ai/provider-guides/jotform



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.jotform.com`.

### Example integration

To define an integration for Jotform, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: jotform-integration
    displayName: My Jotform Integration
    provider: jotform
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Jotform:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.jotform.com`.

## Creating an API key for Jotform

[Click here](https://api.jotform.com/docs/#authentication) for more information about generating an API key for Jotform. The UI components will display this link, so that your users can successfully create API keys.


# Jump
Source: https://docs.ampersand.ai/provider-guides/jump



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://my.jumpapp.com/enterprise/graphql`.

### Example integration

To define an integration for Jump, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: jumpIntegration
    displayName: Jump Integration
    provider: jump
    proxy:
      enabled: true
```

## Before You Get Started

To use the Jump connector, you'll need an API Key from your Jump account. Here's how to get it:

1. Sign in to the [Jump homepage](https://my.jumpapp.com).
2. In the lower-right corner of the homepage, click **Profile & settings**.
3. Click **Account settings**.
4. Navigate to **API**.
5. Click **Create API Key**.
6. Enter a name and select scopes.
7. Save the key, then copy the generated key.

<img alt="Jump API Key" />

For more details, see the [Jump Authentication documentation](https://my.jumpapp.com/enterprise/documentation/authentication).

## Using the connector

This connector uses API Key authentication, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To integrate with Jump:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API Key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API Key supplied by the customer.


# JustCall
Source: https://docs.ampersand.ai/provider-guides/justCall



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `calls` and `texts` objects.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.justcall.io`.

### Supported Objects

The JustCall connector supports reading from the following objects:

* [contacts](https://developer.justcall.io/reference/contacts_list_v21)
* [calls](https://developer.justcall.io/reference/call_list_v21)
* [texts](https://developer.justcall.io/reference/texts_list_v21)
* [users](https://developer.justcall.io/reference/users_list_v21)
* [tags](https://developer.justcall.io/reference/texts_tags_list_v21)
* [sales\_dialer/contacts](https://developer.justcall.io/reference/sales_dialer_campaign_contacts_list_v21)
* [sales\_dialer/calls](https://developer.justcall.io/reference/sales_dialer_call_list_v21)

The JustCall connector supports writing to the following objects:

* [contacts](https://developer.justcall.io/reference/create_contact_v21) (create/update)
* [calls](https://developer.justcall.io/reference/call_update_v21) (update only)
* [texts](https://developer.justcall.io/reference/texts_new_v21) (send SMS)

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with JustCall:

* Create a manifest file for your integration.
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for their API key and secret.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for JustCall

1. Log in to your [JustCall account](https://app.justcall.io/).
2. Click on your profile icon, then navigate to **API and Webhooks** (or go directly to [API Settings](https://app.justcall.io/app/settings/api)).
3. Copy your existing API key and secret, or generate a new pair.

<img alt="JustCall API Key" />

For more details, see the [JustCall Authentication documentation](https://developer.justcall.io/reference/authentication).


# Kaseya VSAX
Source: https://docs.ampersand.ai/provider-guides/kaseyaVSAX



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}`.

### Example integration

To define an integration for Kaseya VSAX, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: kaseyaVSAX-integration
    displayName: My kaseyaVSAX Integration
    provider: kaseyaVSAX
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Kaseya VSAX:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://{{.workspace}}`.


# Keap
Source: https://docs.ampersand.ai/provider-guides/keap



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for contacts.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.infusionsoft.com`.

The Keap connector supports writing to and reading from the following objects:

* [automationCategory](https://developer.keap.com/docs/restv2/#tag/AutomationCategory/operation/listCategoriesUsingGET)
* [automations](https://developer.keap.com/docs/restv2/#tag/Automation/operation/listAutomationsUsingGET)
* [campaigns](https://developer.keap.com/docs/restv2/#tag/Campaign/operation/listCampaignsUsingGET_1)
* [companies](https://developer.keap.com/docs/restv2/#tag/Company/operation/listCompaniesUsingGET_1)
* [contacts/links/types](https://developer.keap.com/docs/restv2/#tag/Contact/operation/listContactLinkTypesUsingGET)
* [contacts](https://developer.keap.com/docs/restv2/#tag/Contact/operation/listContactsUsingGET_1) (with incremental read)
* [tags/categories](https://developer.keap.com/docs/restv2/#tag/Tags/operation/listTagCategoriesUsingGET)
* [tags](https://developer.keap.com/docs/restv2/#tag/Tags/operation/listTagsUsingGET_1)
* [tasks](https://developer.keap.com/docs/restv2/#tag/Task/operation/listTasksUsingGET_1)

The Keap connector only supports modifying the following objects:

* [affiliates](https://developer.keap.com/docs/restv2/#tag/Affiliate/operation/addAffiliateUsingPOST)
* [emails](https://developer.keap.com/docs/restv2/#tag/Email/operation/createEmailUsingPOST_1)
* [paymentMethodConfigs](https://developer.keap.com/docs/restv2/#tag/Payment-Method-Configs/operation/createPaymentMethodConfigUsingPOST)
* [subscriptions](https://developer.keap.com/docs/restv2/#tag/Subscriptions/operation/createSubscriptionV2UsingPOST)

Custom fields are returned just like any other field on objects that support them.

## Before you get started

To integrate Keap with Ampersand, you will need a [Keap Developer Account](https://developer.infusionsoft.com/).

Once your account is created, you'll need to create an app in Keap and obtain the following credentials from your app:

* App ID
* Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Keap account

Here's how you can sign up for a Keap account:

* Go to the [Keap Developer Portal](https://developer.infusionsoft.com/).
* Sign up using your preferred method and complete any necessary verification.

### Creating a Keap app

Follow the steps below to create a Keap app and add the Ampersand redirect URL.

1. Log in to your [Keap Developer Portal](https://developer.infusionsoft.com/).

2. Click **Apps** from your account drop-down menu.

3. Enter the following app details:

* **App Name**: The name of your app.
* **App Description**: A brief description of your app and its purpose.

4. Select **Enable** button for the given Keap API.
5. Click **Save**.

<img alt="Keap App Creation" />

You will find the **App ID** and **Secret** in the app details. Note these credentials, as you will need them to connect your app to Ampersand.

## Add your Keap app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Keap integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Keap* from the **Provider** list.

5. Enter the previously obtained **App ID** in the **Client ID** field and **Secret** in the **Client Secret** field.

   <img alt="Ampersand Integration" />

6. Click **Save Changes**.


# Kit
Source: https://docs.ampersand.ai/provider-guides/kit



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported. A full read of the Kit instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.kit.com`.

### Supported Objects

The Kit connector supports reading from the following objects:

* [Broadcasts](https://developers.kit.com/v4#list-broadcasts)
* [CustomFields](https://developers.kit.com/v4#list-custom-fields)
* [Forms](https://developers.kit.com/v4#list-forms)
* [Subscribers](https://developers.kit.com/v4#list-subscribers)
* [Tags](https://developers.kit.com/v4#list-tags)
* [EmailTemplates](https://developers.kit.com/v4#list-email-templates)
* [Purchases](https://developers.kit.com/v4#list-purchases)
* [Segments](https://developers.kit.com/v4#list-segments)
* [Sequences](https://developers.kit.com/v4#list-sequences)
* [Webhooks](https://developers.kit.com/v4#list-webhooks)

The Kit connector supports writing to the following objects:

* [Broadcasts](https://developers.kit.com/v4#create-a-broadcast)
* [CustomFields](https://developers.kit.com/v4#create-a-custom-field)
* [Subscribers](https://developers.kit.com/v4#create-a-subscriber)
* [Tags](https://developers.kit.com/v4#create-a-tag)
* [Purchases](https://developers.kit.com/v4#create-a-purchase)
* [Webhooks](https://developers.kit.com/v4#create-a-webhook)

### Example integration

To define an integration for Kit, create a manifest file that looks like this: [https://github.com/amp-labs/samples/blob/main/kit/amp.yaml](https://github.com/amp-labs/samples/blob/main/kit/amp.yaml)

## Before You Get Started

To connect Kit with Ampersand, you will need [a Kit Account](https://app.kit.com/users/signup).

Once your account is created, you'll need to create an app in Kit and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Kit Account

Here's how you can sign up for a Kit account:

* Go to the [Kit Sign Up page](https://app.kit.com/users/signup).
* Sign up using your preferred method.

### Creating a Kit App

Follow the steps below to create a Kit app and add the Ampersand redirect URL.

1. Log in to your [Kit](https://app.kit.com/users/login) account.

2. Click the **Profile** icon, then click on **Settings** and go to **Developer**.

3. Click on **Create a new app**.

4. In the **Create a new app** pop-up window, enter the **App name**.

5. You can also add:

* **Summary**
* **Logo**
* **Website URL**
* **Support URL**
* **Knowledge base URL**
* **Privacy policy URL**
* **Images**
* **Access required**
* **Categories**

6. Click **Save**. Next, you will need to **Configure** the app.

   <img alt="Kit App Creation" />

7. Enter the Authorization URL: `https://app.kit.com/oauth/authorize` in the **Authorization URL** section.

8. Enter `https://api.withampersand.com/callbacks/v1/oauth` in the **Redirect URIs** section.

9. Click **Continue**.

   <img alt="Kit App Creation" />

## Add Your Kit App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Kit integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Kit* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Ampersand Integration" />

## Using the connector

To start integrating with Kit:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/kit/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Klaviyo
Source: https://docs.ampersand.ai/provider-guides/klaviyo



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://a.klaviyo.com`.

The Klaviyo connector supports writing to and reading from the following objects:

* [catalog-categories](https://developers.klaviyo.com/en/reference/get_catalog_categories)
* [catalog-items](https://developers.klaviyo.com/en/reference/get_catalog_items)
* [catalog-variants](https://developers.klaviyo.com/en/reference/get_catalog_variants)
* [images](https://developers.klaviyo.com/en/reference/get_images)
* [lists](https://developers.klaviyo.com/en/reference/get_lists)
* [profiles](https://developers.klaviyo.com/en/reference/get_profiles)
* [segments](https://developers.klaviyo.com/en/reference/get_segments)
* [template-universal-content](https://developers.klaviyo.com/en/reference/get_all_universal_content)
* [templates](https://developers.klaviyo.com/en/reference/get_templates)
* [webhooks](https://developers.klaviyo.com/en/reference/get_webhooks)

Objects with partial support are as follows:

* [accounts](https://developers.klaviyo.com/en/reference/get_accounts) (read backfill only; no write)
* [catalog-category-bulk-create-jobs](https://developers.klaviyo.com/en/reference/get_create_categories_jobs) (read/create)
* [catalog-category-bulk-delete-jobs](https://developers.klaviyo.com/en/reference/get_delete_categories_jobs) (read/create)
* [catalog-category-bulk-update-jobs](https://developers.klaviyo.com/en/reference/get_update_categories_jobs) (read/create)
* [catalog-item-bulk-create-jobs](https://developers.klaviyo.com/en/reference/get_bulk_create_catalog_items_jobs) (read/create)
* [catalog-item-bulk-delete-jobs](https://developers.klaviyo.com/en/reference/get_bulk_delete_catalog_items_jobs) (read/create)
* [catalog-item-bulk-update-jobs](https://developers.klaviyo.com/en/reference/get_bulk_update_catalog_items_jobs) (read/create)
* [catalog-variant-bulk-create-jobs](https://developers.klaviyo.com/en/reference/get_create_variants_jobs) (read/create)
* [catalog-variant-bulk-delete-jobs](https://developers.klaviyo.com/en/reference/get_delete_variants_jobs) (read/create)
* [catalog-variant-bulk-update-jobs](https://developers.klaviyo.com/en/reference/get_update_variants_jobs) (read/create)
* [coupon-code-bulk-create-jobs](https://developers.klaviyo.com/en/reference/get_bulk_create_coupon_code_jobs) (read/create)
* [coupons](https://developers.klaviyo.com/en/reference/get_coupons) (read backfill only, write)
* [events](https://developers.klaviyo.com/en/reference/get_events) (read/create)
* [flows](https://developers.klaviyo.com/en/reference/get_flows) (read/update)
* [metrics](https://developers.klaviyo.com/en/reference/get_metrics) (read)
* [profile-bulk-import-jobs](https://developers.klaviyo.com/en/reference/get_bulk_import_profiles_jobs) (read/create)
* [profile-suppression-bulk-create-jobs](https://developers.klaviyo.com/en/reference/get_bulk_suppress_profiles_jobs) (read/create)
* [profile-suppression-bulk-delete-jobs](https://developers.klaviyo.com/en/reference/get_bulk_unsuppress_profiles_jobs) (read/create)
* [tag-groups](https://developers.klaviyo.com/en/reference/get_tag_groups) (read backfill only; write)
* [tags](https://developers.klaviyo.com/en/reference/get_tags) (read backfill only; write)

Objects with write-only support are as follows:

* [back-in-stock-subscriptions](https://developers.klaviyo.com/en/reference/create_back_in_stock_subscription) (create)
* [campaign-message-assign-template](https://developers.klaviyo.com/en/reference/assign_template_to_campaign_message) (create)
* [campaign-messages](https://developers.klaviyo.com/en/reference/update_campaign_message) (update)
* [campaign-send-jobs](https://developers.klaviyo.com/en/reference/send_campaign) (write)
* [client-back-in-stock-subscriptions](https://developers.klaviyo.com/en/reference/create_client_back_in_stock_subscription) (create)
* [client-event-bulk-create](https://developers.klaviyo.com/en/reference/bulk_create_client_events) (create)
* [client-events](https://developers.klaviyo.com/en/reference/bulk_create_client_events) (create)
* [client-profiles](https://developers.klaviyo.com/en/reference/create_client_profile) (create)
* [client-push-token-unregister](https://developers.klaviyo.com/en/reference/unregister_client_push_token) (create)
* [client-push-tokens](https://developers.klaviyo.com/en/reference/create_client_push_token) (create)
* [client-subscriptions](https://developers.klaviyo.com/en/reference/create_client_subscription) (create)
* [data-privacy-deletion-jobs](https://developers.klaviyo.com/en/reference/request_profile_deletion) (create)
* [event-bulk-create-jobs](https://developers.klaviyo.com/en/reference/bulk_create_events) (create)
* [image-upload](https://developers.klaviyo.com/en/reference/upload_image_from_file) (create)
* [metric-aggregates](https://developers.klaviyo.com/en/reference/query_metric_aggregates) (create)
* [profile-subscription-bulk-create-jobs](https://developers.klaviyo.com/en/reference/bulk_subscribe_profiles) (create)
* [profile-subscription-bulk-delete-jobs](https://developers.klaviyo.com/en/reference/bulk_unsubscribe_profiles) (create)
* [push-tokens](https://developers.klaviyo.com/en/reference/create_push_token) (create)

Please reach out to us if there are more objects that you need support for.

### Example integration

For an example manifest file of a Klaviyo integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/klaviyo/amp.yaml).

## Before you get started

To connect Klaviyo with Ampersand, you need to [Create a Klaviyo Account](#create-a-klaviyo-account) and obtain the following credentials from your Klaviyo App:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Klaviyo account

You need a **Klaviyo** account to connect with Ampersand. If you do not have a Klaviyo account, here's how you can sign up:

* Go to the [Klaviyo site](https://www.klaviyo.com/) and sign up for a free account using your preferred method.

### Creating a Klaviyo app

Once your Klaviyo account is ready, you need to create a Klaviyo application. Learn more about creating a Klaviyo application [here](https://developers.klaviyo.com/en/docs/create_a_public_oauth_app).

1. Log in to the [Klaviyo dashboard](https://www.klaviyo.com/login).

2. Then visit [Manage Apps](https://www.klaviyo.com/manage-apps) to create a new app.
   Alternatively, this can be found by clicking on avatar, go to **Integrations**, click on **Developers** dropdown and then select **Manage apps**.

3. On the Create a New App form, enter your application name. <img alt="Create App Form" />
   You can find the **Client ID** and **Client Secret** keys on the app details page. Note these keys, as they are essential for connecting your app to Ampersand.

4. Click **Create**. <img alt="Application Info" />

5. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` in the **Redirect URI** section.

6. Choose the scopes that are applicable for your application. [Available API scopes](https://developers.klaviyo.com/en/docs/authenticate_)

7. Click **Review submission**. Review that all sections are completed and proceed with **Submit**.

## Add Klaviyo app details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Klaviyo App.

   <img alt="Ampersand Project Selection" />

3. Navigate to the **Provider Apps** section.

4. Select **Klaviyo** from the Provider list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in **Klaviyo**.

   <img alt="Ampersand Project Selection" />

7. Click **Save Changes**.


# Lemlist
Source: https://docs.ampersand.ai/provider-guides/lemlist



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Lemlist instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.lemlist.com`.

### Supported Objects

The Lemlist connector supports reading from the following objects:

* [team](https://developer.lemlist.com/#d5c38ed4-53b5-4ec4-8263-06beb1d292c2)
* [team/senders](https://developer.lemlist.com/#28a4c41b-ef65-423f-b414-a6d32b1120c2)
* [team/credits](https://developer.lemlist.com/#c9af1cf3-8d3d-469e-a548-268b579d2cb3)
* [campaigns](https://developer.lemlist.com/#32ab1bf9-9b2f-40ed-9bbd-0b8370fed3d9)
* [activities](https://developer.lemlist.com/#3e612a7c-dd67-42dd-95be-0eeac119cc6b)
* [unsubscribes](https://developer.lemlist.com/#e4dca828-d9a8-4e93-a56d-2ec0b1ae7af5)
* [hooks](https://developer.lemlist.com/#94e49f1f-1819-4b09-839f-92f3af41c945)
* [database/filters](https://developer.lemlist.com/#4a01ffe0-2b44-4707-ba60-4afb77541cbc)
* [schema/people](https://developer.lemlist.com/#0a3cfde2-5d79-4dd1-be47-68aef46234a3)
* [schema/companies](https://developer.lemlist.com/#042141e3-bd1b-4e56-811d-7302964de3ea)
* [schedules](https://developer.lemlist.com/#ce46ed06-ee02-49d7-b8f3-0d9960fe1143)

The Lemlist connector supports writing to the following objects:

* [campaigns](https://developer.lemlist.com/#7297cf35-8b42-4838-bae7-aeb2f9f75d5e)
* [schedules](https://developer.lemlist.com/#94448a9e-90be-402b-bbd2-75556dc27b9a)
* [hooks](https://developer.lemlist.com/#b7dba842-902b-441b-8c64-829c6a09c70c)
* [database/people](https://developer.lemlist.com/#cf6deb22-a090-46b4-938b-bde8704ae4ee)
* [database/companies](https://developer.lemlist.com/#6a5f198a-b970-4eca-90fd-6d8a4f283f3d)
* [tasks](https://developer.lemlist.com/#6df3a460-3dd6-4cc2-822d-4035fe766866)
* [tasks/ignore](https://developer.lemlist.com/#1f3a7136-3729-4c0c-b17d-a5dc73abc3e6)

### Example integration

To define an integration for LemList, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: lemlist-integration
    displayName: My Lemlist Integration
    provider: lemlist
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Lemlist:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [Install Integration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.lemlist.com`.

## Creating an API key for Lemlist

[Click here](https://developer.lemlist.com/#authentication) for more information on generating API keys for Lemlist. The UI components will display this link, so that your users can successfully create API keys.

Note: The API responds with a 200 OK status code for unknown or undefined resources. You may have to inspect the response body for more details.


# Lever
Source: https://docs.ampersand.ai/provider-guides/lever



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.lever.co`.

### Supported Objects

The Lever connector supports reading from the following objects:

* [archive\_reasons](https://hire.lever.co/developer/documentation#archive-reasons)
* [audit\_events](https://hire.lever.co/developer/documentation#audit-events)
* [sources](https://hire.lever.co/developer/documentation#sources)
* [stages](https://hire.lever.co/developer/documentation#stages)
* [tags](https://hire.lever.co/developer/documentation#tags)
* [users](https://hire.lever.co/developer/documentation#users)
* [feedback\_templates](https://hire.lever.co/developer/documentation#feedback-templates)
* [opportunities](https://hire.lever.co/developer/documentation#opportunities)
* [postings](https://hire.lever.co/developer/documentation#postings)
* [form\_templates](https://hire.lever.co/developer/documentation#profile-form-templates)
* [requisitions](https://hire.lever.co/developer/documentation#requisitions)
* [requisition\_fields](https://hire.lever.co/developer/documentation#requisition-fields)

The Lever connector supports writing to the following objects:

* [form\_templates](https://hire.lever.co/developer/documentation#profile-form-templates)
* [requisitions](https://hire.lever.co/developer/documentation#requisitions)
* [requisition\_fields](https://hire.lever.co/developer/documentation#requisition-fields)
* [uploads](https://hire.lever.co/developer/documentation#uploads)
* [users](https://hire.lever.co/developer/documentation#users)
* [feedback\_templates](https://hire.lever.co/developer/documentation#feedback-templates)
* [contacts](https://hire.lever.co/developer/documentation#contacts)

### Example integration

For an example manifest file of a Lever integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/lever/amp.yaml).

## Before You Get Started

To connect Lever with Ampersand, you need [a Lever Account](https://www.lever.co/demo/).

Once your account is created, you'll need to contact the support team to enable the OAuth option, and you'll need to create an app in Lever and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Lever App

Follow the steps below to create a Lever app and add the Ampersand redirect URL.

1. Log in to your [Lever](https://hire.lever.co/auth/login) account.

2. Go to **Settings > Integrations and API > OAuth** in your Lever account.

3. Enter the integration name in the **Integration Name** section.

4. In the **Integration Description** section, enter the description for the OAuth application.

5. Enter the Ampersand Callback URI: `https://api.withampersand.com/callbacks/v1/oauth` in the **Callback URI** section.

6. Provide the URL for the **Square logo URI**.

7. Enable the required **scopes**. For each module, enable both read and write access. A maximum of 20 scopes can be selected.

8. Click the **Submit**.

   <img alt="Lever OAuth Creation" />

## Add Your Lever App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Lever integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select Lever from the **Provider** list.

5. Enter the previously obtained Client ID in the **Client ID** field and the Client Secret in the **Client Secret** field.

   <img alt="Ampersand Integration" />

To start integrating with Lever:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/lever/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Lightfield
Source: https://docs.ampersand.ai/provider-guides/lightfield



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for all supported objects.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.lightfield.app`.

### Notes

* Lightfield requires a `Lightfield-Version: 2026-03-01` header on every API request. Read Actions send it for you; Proxy calls must include it themselves.

### Supported objects

The Lightfield connector supports reading from the following objects:

* [accounts](https://docs.lightfield.app/api/resources/account/methods/list/)
* [contacts](https://docs.lightfield.app/api/resources/contact/methods/list/)
* [members](https://docs.lightfield.app/api/resources/member/methods/list/)
* [opportunities](https://docs.lightfield.app/api/resources/opportunity/methods/list/)

### Example integration

To define an integration for Lightfield, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: lightfieldIntegration
    displayName: My Lightfield Integration
    provider: lightfield
    read:
      objects:
        - objectName: accounts
          destination: myWebhook
    proxy:
      enabled: true
```

## Before you get started

To connect Lightfield with Ampersand, you will need a [Lightfield account](https://lightfield.app).

### Creating an API key for Lightfield

1. Sign in to Lightfield as an admin (only admins can manage API keys).
2. Open the [API keys settings page](https://crm.lightfield.app/crm/settings/api-keys) and create a key.
3. Grant the read scopes for the objects you need: `accounts:read`, `contacts:read`, `opportunities:read` and `members:read`.
4. Copy the key. Lightfield shows it only once.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Lightfield:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Linear
Source: https://docs.ampersand.ai/provider-guides/linear



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.linear.app/graphql`.

### Supported Objects

The Linear connector supports reading from the following objects:

* [attachments](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [auditEntries](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [comments](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [customers](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [cycles](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [documents](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [favorites](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [initiatives](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [issues](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [notifications](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [projects](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [projectStatuses](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [teamMemberships](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [teams](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [triageResponsibilities](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [users](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [workflowStates](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)

The Linear connector supports writing to the following objects:

* [attachments](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [comments](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [customers](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [cycles](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [documents](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [issues](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [projects](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)
* [teams](https://studio.apollographql.com/public/Linear-API/variant/current/explorer)

### Example integration

For an example manifest file of a Linear integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/linear/amp.yaml).

## Before you get started

To connect Linear with Ampersand, you need [a Linear Account](https://linear.app/signup).

Once your account is created, you'll need to create an app in Linear and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Linear App

Follow the steps below to create a Linear app.

1. Log in to your [Linear](https://linear.app/login) account.

2. Once logged in, Click the dropdown next to your **workspace name** in the top-left corner, then select **Settings** from the menu.

3. Navigate to **API** menu under **Administration** section.

4. Click **New OAuth Application**.

5. Enter the Application name, Developer name and Developer URL in the respective sections.

6. Enter the Ampersand Callback URLs: `https://api.withampersand.com/callbacks/v1/oauth` in the **Callback URLs** section.

7. \[Optional] Enable the **Public** option if you wish to allow this app to be installed by other workspaces.

   <img alt="Linear OAuth Creation" />

## Add Your Linear App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Linear integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select Linear from the **Provider** list.

5. Enter the previously obtained Client ID in the **Client ID** field and the Client Secret in the **Client Secret** field.

6. For Scopes you can start with `write` (*which grants the app write access to all objects*) or use more targeted scopes `issues:create` or `comments:create`.

<Note>Check [Linear's documentation](https://linear.app/developers/oauth-2-0-authentication#redirect-user-access-requests-to-linear) for more details.</Note>

<img alt="Ampersand Integration" />

To start integrating with Linear:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/linear/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# LinkedIn
Source: https://docs.ampersand.ai/provider-guides/linkedin



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is only supported for the `adAnalytics` object.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.linkedin.com`.

### Supported Objects

The LinkedIn connector supports reading from the following objects:

* [adTargetingFacets](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/advertising-targeting/ads-targeting?view=li-lms-2025-09\&tabs=http#ad-targeting-facets)
* [dmpEngagementSourceTypes](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/advertising-targeting/engagement-retargeting?view=li-lms-2025-09\&tabs=http#get-all-supported-engagement-source-types)
* [adCampaignGroups](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/account-structure/create-and-manage-campaign-groups?view=li-lms-2025-09\&tabs=http#search-for-campaign-groups)
* [adCampaigns](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/account-structure/create-and-manage-campaigns?view=li-lms-2025-09\&tabs=http#search-for-campaigns)
* [adAccounts](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/account-structure/create-and-manage-accounts?view=li-lms-2025-09\&tabs=http#search-for-accounts)
* [dmpSegments](https://learn.microsoft.com/en-us/linkedin/marketing/matched-audiences/create-and-manage-segments?view=li-lms-2025-09\&tabs=curl#find-dmp-segments-by-account)
* [adAnalytics](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting?view=li-lms-2025-09\&tabs=curl#analytics-finder)

The LinkedIn connector supports writing to the following objects:

* [adCampaignGroups](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/account-structure/create-and-manage-campaign-groups?view=li-lms-2025-09\&tabs=http#create-a-campaign-group)
* [adCampaigns](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/account-structure/create-and-manage-campaigns?view=li-lms-2025-09\&tabs=http#create-a-campaign)
* [adAccounts](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/account-structure/create-and-manage-accounts?view=li-lms-2025-09\&tabs=http#create-ad-account)
* [adTargetTemplates](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/advertising-targeting/saved-audience-templates?view=li-lms-2025-09\&tabs=http#sample-request)
* [adPublisherRestrictions](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/advertising-targeting/manage-audience-restrictions?view=li-lms-2025-09\&tabs=http#create-the-publisher-restriction)
* [inmailContents](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/advertising-targeting/version/message-ads-integrations?view=li-lms-2025-09\&tabs=http#create-inmail-content)
* [conversationAds](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/advertising-targeting/version/conversation-ads-integrations?view=li-lms-2025-09\&tabs=http#create-a-sponsored-conversation)
* [adLiftTests](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/experimentation/brand-lift-testing/ad-lift-tests?view=li-lms-2025-09#create-ad-lift-tests)
* [adExperiments](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/experimentation/ab-testing/ab-testing?view=li-lms-2025-09#create-experiments)
* [conversions](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversion-tracking?view=li-lms-2025-09\&tabs=https#create-a-conversion)
* [thirdPartyTrackingTags](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/third-party-tracking?view=li-lms-2025-09\&tabs=http#create-third-party-tracking-tag)
* [events](https://learn.microsoft.com/en-us/linkedin/marketing/event-management/events?view=li-lms-2025-09\&tabs=http#create-event)
* [insightTags](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversion-tracking?view=li-lms-2025-09\&tabs=https#create-an-insight-tag)
* [adPageSets](https://learn.microsoft.com/en-us/linkedin/marketing/matched-audiences/website-visitors-retargeting?view=li-lms-2025-09\&tabs=http#create-ad-page-set)
* [dmpSegments](https://learn.microsoft.com/en-us/linkedin/marketing/matched-audiences/create-and-manage-segments?view=li-lms-2025-09\&tabs=http#create-dmp-segment)
* [leadForms](https://learn.microsoft.com/en-us/linkedin/marketing/lead-sync/leadsync?view=li-lms-2025-09\&tabs=http#creating-lead-forms)
* [posts](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/posts-api?view=li-lms-2025-09\&tabs=http#create-a-post)
* [creatives](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/advertising-targeting/version/spotlight-ads?view=li-lms-2025-09\&tabs=http#create-a-dynamic-spotlight-ad-creative)

### Example integration

For an example manifest file of a LinkedIn integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/linkedin/amp.yaml).

## Before You Get Started

To connect *LinkedIn* with *Ampersand*, you will need [a LinkedIn Account](https://www.linkedin.com/).

Once your account is created, you'll need to configure an app in LinkedIn and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a LinkedIn Account

Here's how you can sign up for a LinkedIn Developer account:

* Go to the [LinkedIn Sign up page](https://www.linkedin.com/signup/cold-join?source=guest_homepage-basic_nav-header-signin).
* Sign up using your preferred method.

### Creating a LinkedIn App

Follow the steps below to create a LinkedIn app and add the Ampersand redirect URL in the app:

1. Log in to your [LinkedIn Developer Dashboard](https://developer.linkedin.com/).
2. Go to **My Apps**.
3. Click **Create app**.
4. Enter the **App Name**.
5. Connect your LinkedIn profile in the **LinkedIn Page** section.
6. Provide the privacy policy.
7. Select a logo for your app.
8. Check the LinkedIn developer agreement.
9. Click **Create App**.
10. Once your app is created, you'll find the **Client ID** and **Client Secret** keys for your app in the **Auth** section. Note these credentials as they are necessary for connecting your app to Ampersand.
11. In the **OAuth 2.0 settings**, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

<img alt="Alt text" />

## Add Your LinkedIn App info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a LinkedIn integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *LinkedIn* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save changes**.

To start integrating with LinkedIn:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/linkedin/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Livestorm
Source: https://docs.ampersand.ai/provider-guides/livestorm



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL [https://api.livestorm.co](https://api.livestorm.co).

## Before You Get Started

To integrate Livestorm with Ampersand, you must register a Livestorm OAuth2 application. To do this, contact [help@livestorm.co](mailto:help@livestorm.co) and provide the following details:

* **Redirect URL**: Please provide a unique HTTPS redirect URL for your app. **Note** that dynamic URLs are not supported at this time.
* **App Logo**: Provide a logo for your app. The image should be square with a maximum size of 500px x 500px.
* **Scope**: Specify the scope required for your app to function.

Once your application is registered, you will receive two credentials: **client\_id** and **client\_secret.** These credentials are required to connect Livestorm with Ampersand.

### Example integration

To define an integration for livestorm, create a manifest file that looks like this:

```YAML theme={"dark"}
#amp.yaml
specVersion: 1.0.0
integrations: 
  - name: livestormIntegration
    displayName: Livestorm
    provider: livestorm
    proxy:
      enabled: true
```

## Add Your Livestorm App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Livestorm integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select Livestorm from the **Provider** list.

5. Enter the previously obtained Client ID in the **Client ID** field, the Client Secret in the **Client Secret** field and scopes in the **Scopes** field.

   <img alt="Ampersand Integration" />


# Lob
Source: https://docs.ampersand.ai/provider-guides/lob



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.lob.com`.

The Lob connector supports reading from all standard objects and writing to most standard objects, including the following:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

### Example integration

For an example manifest file of a Lob integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/lob/amp.yaml).

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Lob:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://api.lob.com`.

## Credential format for Lob

Lob uses HTTP Basic Authentication with a non-standard credential format.
The fields in the installation UI do not correspond to a Lob account email address and password. Instead:

* **Username**: Enter the Lob API key from the [Lob Dashboard API key settings](https://dashboard.lob.com/settings/api-keys).
* **Password**: Leave this field empty.

When making proxy calls, Ampersand encodes these values as a Basic Auth header and attaches it automatically.
Choose the API key appropriate for the environment you are integrating with. For example, choose
a **test key** for Lob’s test environment and a **live key** for production use.

For more detail, see [Lob's authentication documentation](https://docs.lob.com/#tag/Authentication)
and [API key documentation](https://docs.lob.com/#tag/Authentication/API-Keys).


# Loxo
Source: https://docs.ampersand.ai/provider-guides/loxo



## What's Supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `email_tracking`, `person_events` and `sms` currently. For all other objects, a full read of the Loxo instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.domain}}/api/{{.agency_slug}}`.

### Supported Objects

The Loxo connector supports writing and reading from the following objects:

* [activity\_types](https://loxo.readme.io/reference/activity_typesindex) (read)
* [address\_types](https://loxo.readme.io/reference/address_typesindex) (read)
* [bonus\_payment\_types](https://loxo.readme.io/reference/bonus_payment_typesindex) (read)
* [bonus\_types](https://loxo.readme.io/reference/bonus_typesindex) (read)
* [companies](https://loxo.readme.io/reference/companiescreate) (read, write)
* [company\_global\_statuses](https://loxo.readme.io/reference/company_global_statusesindex) (read)
* [company\_types](https://loxo.readme.io/reference/company_typesindex) (read)
* [compensation\_types](https://loxo.readme.io/reference/compensation_typesindex) (read)
* [countries](https://loxo.readme.io/reference/countriesindex) (read)
* [currencies](https://loxo.readme.io/reference/currenciesindex) (read)
* [deal\_workflows](https://loxo.readme.io/reference/deal_workflowsindex) (read)
* [deals](https://loxo.readme.io/reference/dealsindex) (read, write)
* [disability\_statuses](https://loxo.readme.io/reference/disability_statusesindex) (read)
* [diversity\_types](https://loxo.readme.io/reference/diversity_typesindex) (read)
* [dynamic\_fields](https://loxo.readme.io/reference/dynamic_fieldsindex) (read)
* [education\_types](https://loxo.readme.io/reference/education_typesindex) (read)
* [email\_tracking](https://loxo.readme.io/reference/email_trackingindex) (read)
* [email\_types](https://loxo.readme.io/reference/email_typesindex) (read)
* [equity\_types](https://loxo.readme.io/reference/equity_typesindex) (read)
* [ethnicities](https://loxo.readme.io/reference/ethnicitiesindex) (read)
* [fee\_types](https://loxo.readme.io/reference/fee_typesindex) (read)
* [form\_templates](https://loxo.readme.io/reference/form_templatesindex) (read)
* [forms](https://loxo.readme.io/reference/formscreate) (read, write)
* [genders](https://loxo.readme.io/reference/gendersindex) (read)
* [job\_categories](https://loxo.readme.io/reference/job_categoriesindex) (read)
* [job\_contact\_types](https://loxo.readme.io/reference/job_contact_typesindex) (read)
* [job\_owner\_types](https://loxo.readme.io/reference/job_owner_typesindex) (read)
* [job\_statuses](https://loxo.readme.io/reference/job_statusesindex) (read)
* [job\_types](https://loxo.readme.io/reference/job_typesindex) (read)
* [jobs](https://loxo.readme.io/reference/jobscreate) (read, write)
* [people](https://loxo.readme.io/reference/peoplecreate) (read, write)
* [person\_events](https://loxo.readme.io/reference/person_eventsindex) (read, write)
* [person\_global\_statuses](https://loxo.readme.io/reference/person_global_statusesindex) (read)
* [person\_lists](https://loxo.readme.io/reference/person_listsindex) (read)
* [person\_share\_field\_types](https://loxo.readme.io/reference/person_share_field_typesindex) (read)
* [person\_types](https://loxo.readme.io/reference/person_typesindex) (read)
* [phone\_types](https://loxo.readme.io/reference/phone_typesindex) (read)
* [placements](https://loxo.readme.io/reference/placementscreate) (read, write)
* [pronouns](https://loxo.readme.io/reference/pronounsindex) (read)
* [question\_types](https://loxo.readme.io/reference/question_typesindex) (read)
* [schedule\_items](https://loxo.readme.io/reference/schedule_itemsindex) (read)
* [scorecards](https://loxo.readme.io/reference/scorecardsindex) (read, write)
* [scorecards/scorecard\_recommendation\_types](https://loxo.readme.io/reference/scorecard_recommendation_typesindex) (read)
* [scorecards/scorecard\_types](https://loxo.readme.io/reference/scorecard_typesindex) (read)
* [scorecards/scorecard\_templates](https://loxo.readme.io/reference/scorecard_templatescreate) (read, write)
* [scorecards/scorecard\_visibility\_types](https://loxo.readme.io/reference/scorecard_visibility_typesindex) (read)
* [seniority\_levels](https://loxo.readme.io/reference/seniority_levelsindex) (read)
* [sms](https://loxo.readme.io/reference/smsindex) (read, write)
* [social\_profile\_types](https://loxo.readme.io/reference/social_profile_typesindex) (read)
* [source\_types](https://loxo.readme.io/reference/source_typescreate) (read, write)
* [users](https://loxo.readme.io/reference/usersindex) (read)
* [veteran\_statuses](https://loxo.readme.io/reference/veteran_statusesindex) (read)
* [workflow\_stages](https://loxo.readme.io/reference/workflow_stagesindex) (read)
* [workflows](https://loxo.readme.io/reference/workflowsindex) (read)

### Example integration

For an example manifest file of a Loxo integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/loxo/amp.yaml).

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

<Note>
  **Note:**

  > * To get the **domain**, log in to your Loxo account and check the URL in your browser’s address bar. It usually follows this pattern: `https://[your-domain-here]`.
  > * To get the **agency\_slug**, go to **Settings > General** under **Workspace**. In the **Agency Info** section, look at the **Resume Forwarding Address** — the part before the @ symbol is the **agency\_slug** value.
</Note>

To integrate with Loxo:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Loxo

1. Log in to your [Loxo account](https://app.loxo.co/login).
2. Navigate to **settings** and click **API Keys** under **Workspace**.
3. Click **Add** Button.

<img alt="Generate Token" />


# Mailgun
Source: https://docs.ampersand.ai/provider-guides/mailgun



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.mailgun.net`.

### Example integration

To define an integration for Mailgun, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: mailgun-integration
    displayName: My Mailgun Integration
    provider: mailgun
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Mailgun:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://api.mailgun.net`.

## Credential format for Mailgun

Mailgun uses a non-standard format for Basic Auth, which means that the username and password fields do not correspond to the actual username and password that a customer uses to log in. [Click here](https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/) for more information about the expected credential format for Mailgun. The UI components will display this link, so that your users can successfully provide their credentials.


# Marketo
Source: https://docs.ampersand.ai/provider-guides/marketo



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for `leads` and `activities` only.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.mktorest.com`.

### Supported Objects

The Marketo connector supports reading from the following objects:

* [campaigns](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/assets/smart-campaigns#query)
* [companies](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/companies#query)
* [customobjects](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/custom-objects#list)
* [leads](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/leads#query)
* [lists](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/assets/static-lists#query)
* [salespersons](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/sales-persons#query)
* [activities](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/activities#query)

<Note>`activities` is supported in private preview only. Please reach out to `support@withampersand.com` for more information.</Note>

The Marketo connector supports writing to the following objects:

* [companies](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/companies#create-and-update)
* [leads](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/leads#create-and-update)
* [namedAccountLists](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/named-account-lists#create-and-update)
* [namedaccounts](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/named-accounts#create-and-update)
* [opportunities](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/opportunities#create-and-update)
* [salespersons](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/sales-persons#create-and-update)
* [custom activities](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/activities#create-type)
* [activity type](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/lead-database/activities#custom-activity-type-attributes)

## Using the connector

This connector uses OAuth2 Client Credentials grant type, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Marketo:

* Create a manifest file.
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Meta
Source: https://docs.ampersand.ai/provider-guides/meta



The Meta connector supports Meta products which have APIs with the root URL `https://graph.facebook.com`, these include:

* Facebook
* Meta Ads (Marketing API)
* WhatsApp

## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://graph.facebook.com`.

### Modules

| Module | Use case | Proxy |
| - | - | - |
| `ads` (default) | Marketing / Ads API and other Graph proxy calls | Yes |
| `whatsapp` | WhatsApp Cloud API (requires WABA ID and Phone Number ID at connect time) | Yes |

To use WhatsApp, add `module: whatsapp` to your integration in `amp.yaml`:

```yaml theme={"dark"}
integrations:
  - name: my-meta-whatsapp
    provider: meta
    module: whatsapp
    proxy:
      enabled: true
```

For Meta Ads, use the default `ads` module (or set it explicitly):

```yaml theme={"dark"}
integrations:
  - name: my-meta-ads
    provider: meta
    module: ads
    proxy:
      enabled: true
```

## Before You Get Started

To connect Meta with Ampersand, you will need [a Meta Developer Account](https://developers.facebook.com/).

Once your account is created, you'll need to create an app in Meta, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* App ID
* App Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Meta Developer Account

Here's how you can sign up for a Meta Developer account:

* Go to the [Meta for Developers Sign Up page](https://developers.facebook.com/).
* Sign up using your Facebook account.

### Creating a Meta App

Follow the steps below to create a Meta app and add the Ampersand redirect URL.

1. Log in to your [Meta Developer Account](https://developers.facebook.com/).

2. Click **My Apps**.

3. Click the **Create App** button.

4. Select a business portfolio if you have one and click **Next**.

5. Select a use case. For OAuth application it's best to use the **Other** option.

6. Click **Next**.

7. Select an app type.

8. Click **Next**.

9. Enter the following app details:
   1. **App Name**: The name of your app.
   2. **Contact Email**: Select a contact email for the app.

10. Click **Create app**.

<img alt="Alt text" />

In the **Settings** > **Basic** section of your app's dashboard, you will find the **App ID** and **App Secret** keys. Note these keys, as they are essential for connecting your app to Ampersand.

The above steps are enough for the Facebook product. To add the WhatsApp product, follow the steps below.

11. Move to the **Add Product** under **Products** and choose the WhatsApp product then configure it.

12. Scroll to the **Client OAuth Settings** section.

13. In the **Valid OAuth Redirect URIs** field, enter the exact Callback URI: [https://api.withampersand.com/callbacks/v1/oauth](https://api.withampersand.com/callbacks/v1/oauth).

<img alt="Alt text" />

## Add Your Meta App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Meta integration.

   <img alt="Alt text" />

3. Select **Provider Apps**.

4. Select **Facebook** from the **Provider** list.

5. Enter the previously obtained **App ID** in the **Client ID** field and **App Secret** in the **Client Secret** field.

6. Enter the permissions (scopes) required for your application in **Permissions**. For details on permissions, refer to the [Meta Permissions](https://developers.facebook.com/docs/permissions) guide.

   <img alt="Alt text" />

7. Click **Save Changes**.


# Microsoft
Source: https://docs.ampersand.ai/provider-guides/microsoft



The Microsoft connector supports all products which are a part of the Microsoft Graph API. These include:

* OneDrive
* SharePoint
* Outlook
* OneNote
* Teams

For a full list of supported products, refer to [Microsoft documentation](https://learn.microsoft.com/en-us/graph/overview-major-services).

We also have connectors for:

* [Dynamics CRM](/provider-guides/dynamicsCRM)
* [Dynamics Business Central](/provider-guides/dynamicsBusinessCentral)

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://graph.microsoft.com`.

### Supported Objects

The Microsoft Graph connector supports **many Microsoft Graph API objects** including but not limited to:

* [users](https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0)
* [calendars](https://learn.microsoft.com/en-us/graph/api/resources/calendar?view=graph-rest-1.0)
* [me/events](https://learn.microsoft.com/en-us/graph/api/resources/event?view=graph-rest-1.0)
* [me/messages](https://learn.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0)

For the complete list of supported Graph API resources, refer to the [Microsoft Graph API documentation](https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0).

To figure out the exact OAuth scope you will require based on the objects you need to integrate with, you can use a tool such as [Graph Permissions Explorer](https://graphpermissions.merill.net/permission/).

### Example Integration

For an example manifest file of a Microsoft integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/microsoft/amp.yaml).

## Before You Get Started

To connect Microsoft services with Ampersand, you will need [a Microsoft Account](https://aka.ms/AppRegistrations/?referrer=https%3A%2F%2Fdev.onedrive.com).

Once your account is created, you'll need to create an app in the Azure portal, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Microsoft Account

Here's how you can sign up for a Microsoft account:

* Go to the [Microsoft Sign up page](https://signup.live.com/signup?sru=https%3a%2f%2flogin.live.com%2foauth20_authorize.srf%3flc%3d1033%26client_id%3d51483342-085c-4d86-bf88-cf50c7252078%26cobrandid%3ded5d1924-9524-4e70-8f68-5ee5e35afbef%26mkt%3dEN-US%26opid%3dE962B0DAAE1D7D3B%26opidt%3d1721584016%26uaid%3d20aa40834b4b4f60a5f6d0caefa69aab%26contextid%3d8123EC532BFC171F%26opignore%3d1\&mkt=EN-US\&uiflavor=web\&lw=1\&fl=easi2\&cobrandid=ed5d1924-9524-4e70-8f68-5ee5e35afbef\&client_id=51483342-085c-4d86-bf88-cf50c7252078\&uaid=20aa40834b4b4f60a5f6d0caefa69aab\&suc=c44b4083-3bb0-49c1-b47d-974e53cbdf3c\&lic=1).
* Sign up using your preferred method and verify your email.

### Creating a Microsoft App

Follow the steps below to create a Microsoft app and add the Ampersand redirect URL.

1. Log in to your [Azure Portal](https://portal.azure.com/).

2. Navigate to **Azure Active Directory** > **App registrations**.

3. Click the **New registration** button.

4. In the **Register an application** window, enter the **Name** and select the **Supported account types**.

5. In the **Redirect URI** section, select **Web** and enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

6. Click **Register**.

7. In the left-hand sidebar, navigate to **Certificates & secrets**.

8. Click **New client secret** and provide a description and expiration period.

9. Click Add. Note the Client Secret value. You will need it later.

10. In the left-hand sidebar, navigate to **Manage >> API permissions**.

11. Click **Add a permission** and choose the required scopes. You must include the **offline\_access** scope.

12. Generate

    <img alt="Microsoft App Creation" />

## Add Your Microsoft App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Microsoft integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Microsoft** from the **Provider** list.

5. Enter the previously generated Client Secret in the **Client Secret** field.

6. For the **Client ID** field, go to the Overview page in your Microsoft application, and copy the **Application ID**.

7. Enter the exact set of scopes that you had previously configured in your Microsoft app.

8. Click **Save Changes**.

## Using the connector

To start integrating with Microsoft:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/microsoft/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

<Warning>In order to receive a refresh token and be able to access your customers' Microsoft Graph APIs without reauthenticating, you must include the `offline_access` permission when registering the app with Ampersand</Warning>


# Microsoft (Admin consent)
Source: https://docs.ampersand.ai/provider-guides/microsoftAdminConsent



The Microsoft (Admin consent) connector provides application-level access to the Microsoft Graph API. A tenant administrator grants consent once for the whole organization, so Ampersand can call Graph without any individual user signing in. Depending on your tenant's setup, granting consent for application permissions may require an administrator with elevated privileges (such as a Global Administrator).

Use this connector for org-wide, app-level access. For access scoped to an individual signed-in user, use the [Microsoft](/provider-guides/microsoft) connector instead.

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://graph.microsoft.com`.

### Supported Objects

This connector supports **many Microsoft Graph API objects** including but not limited to:

* [users](https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0)
* [calendars](https://learn.microsoft.com/en-us/graph/api/resources/calendar?view=graph-rest-1.0)
* [events](https://learn.microsoft.com/en-us/graph/api/resources/event?view=graph-rest-1.0)
* [messages](https://learn.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0)

For the complete list, refer to the [Microsoft Graph API documentation](https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0). To find the exact **Application** permission each object requires, you can use a tool such as the [Graph Permissions Explorer](https://graphpermissions.merill.net/permission/).

## Before You Get Started

To connect Microsoft services with Ampersand, you will need [a Microsoft Account](https://aka.ms/AppRegistrations).

Once your account is created, you'll need to create an app in the Azure portal, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Microsoft App

Follow the steps below to create a Microsoft app and add the Ampersand redirect URL.

1. Log in to your [Azure Portal](https://portal.azure.com/).

2. Navigate to **Microsoft Entra ID** (Azure Active Directory) > **App registrations**.

3. Click the **New registration** button.

4. In the **Register an application** window, enter the **Name** and select the **Supported account types** that fit your scenario — if your customers will connect from their own Microsoft tenants, choose an option that includes multiple organizations. Then click **Register**.

5. In the left-hand sidebar, navigate to **Manage > Authentication** > **Add a platform** > **Web**, and enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/custom-auth/default`.

6. In the left-hand sidebar, navigate to **Certificates & secrets** > **New client secret**, provide a description and expiration period, and click **Add**. Note the Client Secret value. You will need it later.

7. In the left-hand sidebar, navigate to **Manage > API permissions** > **Add a permission** > **Microsoft Graph** > **Application permissions**, and choose the permissions your integration requires.

<Warning>You must add **Application permissions**, not **Delegated permissions**. Application-level access via admin consent uses application permissions; delegated permissions will not work with this connector.</Warning>

## Add Your Microsoft App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Microsoft integration.

3. Select **Provider Apps**.

4. Select **Microsoft (Admin consent)** from the **Provider** list.

5. Enter the previously generated Client Secret in the **Client Secret** field.

6. For the **Client ID** field, go to the Overview page in your Microsoft application, and copy the **Application ID**.

7. Click **Save Changes**.

## Using the connector

To start integrating with Microsoft:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/microsoftAdminConsent/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Miro
Source: https://docs.ampersand.ai/provider-guides/miro



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.miro.com`.

## Before You Get Started

To connect Miro with Ampersand, you will need a [Miro Account](https://miro.com/index/).

Once your account is created, you'll need to configure an app in Miro and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a Miro Account

Here's how you can sign up for a Miro account:

1. Go to the [Miro Sign Up page](https://miro.com/signup/).
2. Sign up using your preferred method.

### Creating a Miro App

Follow the steps below to create a Miro app and add the Ampersand redirect URL:

1. Log in to your [Miro](https://miro.com/login) account.

2. In [Miro Dashboard](https://miro.com/app/dashboard/), click on your profile icon in the top-right corner and select **Settings** from the dropdown menu.

3. Go to the **Your apps** tab.

4. Click **Create new app** to create a new app under your account.

5. In the **Create new app** dialog, provide the following details:
   1. **App Name**: Enter a descriptive name for your application.
   2. Select your development team from the menu.

6. Click **Create app** to proceed.

7. In the **App Credentials** section, the **Client ID** and **Client Secret** will be generated automatically.

**Note**: Make sure to note the **Client ID** and **Client Secret** as you will need these to connect your app to Ampersand.

<img alt="Miro App Credentials" />

8. In the **Redirect URI** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`
9. Under **Permissions**, select the appropriate scopes for your app.

<img alt="Miro Created App" />

### Add Your Miro App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Miro integration.

   <img alt="Ampersand Project" />

3. Select **Provider apps**.

4. Select *Miro* from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and **Client Secret** in the **Client Secret** field.

   <img alt="Adding Miro Credentials" />

<br />

6. Click **Save changes** to finalize the integration.


# Mixmax
Source: https://docs.ampersand.ai/provider-guides/mixmax



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Mixmax instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.mixmax.com`.

### Supported Objects

The Mixmax connector supports reading from the following objects:

* [appointmentlinks/me](https://developer.mixmax.com/reference/appointmentlinksme)
* [userpreferences/me](https://developer.mixmax.com/reference/userpreferencesme)
* [users/me](https://developer.mixmax.com/reference/user)
* [codesnippets](https://developer.mixmax.com/reference/codesnippets)
* [filerequests](https://developer.mixmax.com/reference/filerequests)
* [insightsreports](https://developer.mixmax.com/reference/insightsreports)
* [integrations/commands](https://developer.mixmax.com/reference/integrationscommands)
* [integrations/enhancements](https://developer.mixmax.com/reference/integrationsenhancements)
* [integrations/linkresolvers](https://developer.mixmax.com/reference/integrationslinkresolvers)
* [integrations/sidebars](https://developer.mixmax.com/reference/integrationssidebars)
* [livefeed](https://developer.mixmax.com/reference/livefeed)
* [meetinginvites](https://developer.mixmax.com/reference/meetinginvites-1)
* [meetingtypes](https://developer.mixmax.com/reference/meetingtypes)
* [messages](https://developer.mixmax.com/reference/messages)
* [polls](https://developer.mixmax.com/reference/polls)
* [qa](https://developer.mixmax.com/reference/qa)
* [rules](https://developer.mixmax.com/reference/rules)
* [sequences](https://developer.mixmax.com/reference/sequences)
* [sequencefolders](https://developer.mixmax.com/reference/sequencefolders)
* [snippets](https://developer.mixmax.com/reference/snippets)
* [snippettags](https://developer.mixmax.com/reference/snippettags)
* [teams](https://developer.mixmax.com/reference/teams)
* [unsubscribes](https://developer.mixmax.com/reference/unsubscribes)
* [yesno](https://developer.mixmax.com/reference/yesno)

The Mixmax connector supports writing to the following objects:

* [codesnippets](https://developer.mixmax.com/reference/codesnippets-1)
* [insightsreports](https://developer.mixmax.com/reference/insightsreports-1)
* [integrations/commands](https://developer.mixmax.com/reference/integrationscommands-1)
* [integrations/enhancements](https://developer.mixmax.com/reference/integrationsenhancements-1)
* [integrations/linkresolvers](https://developer.mixmax.com/reference/integrationslinkresolvers-1)
* [integrations/sidebars](https://developer.mixmax.com/reference/integrationssidebars-1)
* [livefeedsearches](https://developer.mixmax.com/reference/livefeedsearches-1)
* [meetingtypes](https://developer.mixmax.com/reference/meetingtypes-1)
* [meetinginvites](https://developer.mixmax.com/reference/meetinginvitesid-1)
* [messages](https://developer.mixmax.com/reference/messages-create)
* [messages/test](http://developer.mixmax.com/reference/messagestest)
* [reports/data/table](https://developer.mixmax.com/reference/reportsdatatable)
* [rules](https://developer.mixmax.com/reference/rules-1)
* [send](https://developer.mixmax.com/reference/send-post)
* [sequences/cancel](https://developer.mixmax.com/reference/sequencescancel)
* [sequencefolders](https://developer.mixmax.com/reference/sequencefolders-1)
* [snippettags](https://developer.mixmax.com/reference/snippettags-post)
* [teams](https://developer.mixmax.com/reference/teams-post)
* [unsubscribes](https://developer.mixmax.com/reference/unsubscribes-2)
* [userpreferences/me](https://developer.mixmax.com/reference/userpreferencesme-1)

### Example integration

For an example manifest file of a Mixmax integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/mixmax/amp.yaml).

## Before You Get Started

### Creating an API key for Mixmax

[Click here](https://developer.mixmax.com/reference/getting-started-with-the-api) for more information about generating an API key for Mixmax. The UI components will display this link, so that your users can successfully create API keys.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Mixmax:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/mixmax/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Mixpanel
Source: https://docs.ampersand.ai/provider-guides/mixpanel



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{subdomain}.mixpanel.com`, where `{subdomain}` is the subdomain for a particular API.

## Before You Get Started

To integrate Mixpanel with Ampersand, you will need [a Mixpanel Account](https://mixpanel.com).

### Example integration

To define an integration for Mixpanel, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: mixpanel-integration
    displayName: My mixpanel Integration
    provider: mixpanel
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Mixpanel:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. This UI component will prompt the customer for their subdomain, username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://{subdomain}.mixpanel.com`.

## Creating Basic Auth credentials

To begin using the API in your Mixpanel account, you need to create service account credentials:

* Navigate to Settings.
* Click on Organization Settings > Service Accounts.
* Click the Add Service Account button in the top right corner.
* Provide the required field details. Once done, your username and password for Basic Authentication will be displayed.

<img alt="Mixpanel Credentials" />


# Monaco
Source: https://docs.ampersand.ai/provider-guides/monaco



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.monaco.com`.

### Example integration

To define an integration for Monaco, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: monaco-integration
    displayName: My Monaco Integration
    provider: monaco
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Monaco:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.monaco.com`.

## Creating an API key for Monaco

1. Log in to your Monaco account.
2. Navigate to **Settings** and select **API Keys**.
3. Create a new key and copy its value. Monaco API keys are prefixed with `mks_`.

[Click here](https://docs.monaco.com/auth) for more information about generating an API key for Monaco. The UI components will display this link, so that your users can successfully create API keys.


# Monday
Source: https://docs.ampersand.ai/provider-guides/monday



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.monday.com`.
* [Read Actions](/read-actions) including historical backfill (incremental read will soon be supported)
* [Write Actions](/write-actions)

### Supported Objects

The Monday connector supports reading from the following objects:

* [Boards](https://developer.monday.com/api-reference/reference/boards)
* [Users](https://developer.monday.com/api-reference/reference/users)

The Monday connector supports writing to the following objects:

* [Boards](https://developer.monday.com/api-reference/reference/boards)

## Before you get started

This connector uses API Key authentication. You do not need to create a provider app in the Ampersand Dashboard.

### Create an API token for Monday

1. In your monday.com account, click your profile picture in the top right corner.
2. Select **Developers**. This will open the Developer Center in another tab.
3. Click **API token > Show**.
4. Copy your personal token and store it securely.

<img alt="Monday API token creation" />

For details, including the admin path, see Monday's [authentication documentation](https://developer.monday.com/api-reference/docs/authentication).

## Using the connector

To start integrating with Monday:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/monday/amp.yml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their Monday API token.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Mural
Source: https://docs.ampersand.ai/provider-guides/mural



## What's Supported

### Supported Actions

This connector supports:

* **Proxy Actions**, using the base URL `https://app.mural.co/api`.

## Before You Get Started

To integrate Mural with Ampersand, you will need [a Mural account](https://www.mural.co/).
Once your account is created, you'll need to create a Mural application and obtain the following credentials:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Mural Account

Here's how you can sign up for a Mural account:

* Go to the [Mural Sign Up page](https://app.mural.co/signup).
* Sign up using your preferred method and complete any necessary verification.

### Creating a Mural Application

Follow the steps below to create a Mural application:

1. Log in to your [Mural](https://app.mural.co/signin?returnUrl=%2Fdashboard) account.
2. From *Profile and Account*, click **Create and manage apps**.
3. Click on **Create New App**.
4. Fill in the required information:
   * **App Name:** Choose a name for your application
   * **Description:** Briefly describe your app's purpose
   * **Redirect URI:** Enter `https://api.withampersand.com/callbacks/v1/oauth`
   * Select the appropriate scopes for your application.
5. Click **Create App**.

<img alt="Alt text" />

You will see the **Client ID** and **Client Secret** for your new app. Note these credentials, as you will need them to connect your app to Ampersand.

## Add Your Mural App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a *Mural* integration.
3. Select **Provider Apps**.
4. Select *Mural* from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.
6. Enter the scopes set for your application in *Mural*.

<img alt="Alt text" />

7. Click **Save Changes**.


# NetSuite
Source: https://docs.ampersand.ai/provider-guides/netsuite



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{account_id}.suitetalk.api.netsuite.com`, where `{account_id}` is your NetSuite account ID.

### Supported Modules & Objects

The NetSuite connector supports the following modules:

1. SuiteQL (referred to as `suiteql` in `amp.yaml`)
   * This is a read-only module that allows you to read data from NetSuite using [SuiteQL](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156257770590.html).
   * This module supports nearly all of the records documented in the [NetSuite Record Browser](https://system.netsuite.com/help/helpcenter/en_US/srbrowser/Browser2024_2/script/record/account.html).

2. REST API (referred to as `restapi` in `amp.yaml`)
   * This module allows you to read and write data to NetSuite using the REST API.
   * It supports all the resources documented in the [NetSuite REST API Reference](https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2024.2/index.html).

3. RESTlet (In private preview)
   * This module allows you to install an Ampersand RESTlet into your customer's NetSuite instance, giving you deep read & write access.
   * This module is currently in private preview. Please get in touch with us at [support@withampersand.com](mailto:support@withampersand.com) to learn more.

By default, the connector will use the `restapi` module. To deploy the connector with the `suiteql` module, you will need to specify the `module` field in the YAML manifest file.

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: netsuite-suiteql-integration
    provider: netsuite
    module: suiteql # default is restapi
    ...
```

For an example manifest file of a NetSuite integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/netsuite/amp.yaml).

## Before You Get Started

To integrate NetSuite with Ampersand, you will need [a NetSuite Account](https://www.netsuite.com/portal/home.shtml).

Once your account is created, you'll need to create an OAuth 2.0 application in NetSuite, configure the Ampersand redirect URI within the application, and obtain the following credentials from your application:

* OAuth Client ID
* OAuth Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a NetSuite Account

Here's how you can sign up for a NetSuite account:

* Go to the [NetSuite website](https://www.netsuite.com/portal/home.shtml).
* Sign up using your preferred method or contact NetSuite sales for enterprise accounts.

### Creating a NetSuite Integration

Follow the steps below to create a NetSuite integration and add the Ampersand redirect URL.

1. Log in to your NetSuite account as an Administrator.
2. Navigate to **Setup** > **Integration** > **Manage Integrations**.
3. Click the **New** button to create a new integration.
4. Enter the following integration details:
   1. **Name**: The name of your integration.
   2. **Description**: A description of your integration.
   3. **Callback URL**: Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
5. Under the **Authentication** tab:
   1. Check **Authorization Code Grant**.
   2. Check **REST Web Services** to allow REST API access.
   3. Uncheck any other authentication methods (TBA, etc.)
   4. Check **Public Client** to allow OAuth 2.0 public clients.
6. Click **Save**.

After saving, NetSuite will generate:

* **Consumer Key** (this is your OAuth Client ID)
* **Consumer Secret** (this is your OAuth Client Secret)

Make note of these credentials as they are necessary for connecting your app to Ampersand.

## Add Your NetSuite Integration Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a NetSuite integration.

3. Select **Provider Apps**.

4. Select *NetSuite* from the **Provider** list.

5. Enter the previously obtained *Consumer Key* in the **Client ID** field and *Consumer Secret* in the **Client Secret** field.

6. Enter the `rest_webservices` scope in the **Scopes** field.

7. Click **Save Changes**.

## Using the connector

To start integrating with NetSuite:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/netsuite/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# NetSuite (M2M)
Source: https://docs.ampersand.ai/provider-guides/netsuite-m2m



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Search Actions](/search-actions)
* [Proxy Actions](/proxy-actions), using the base URL `https://{account_id}.suitetalk.api.netsuite.com`, where `{account_id}` is your NetSuite account ID.

### Supported Modules & Objects

The NetSuite (M2M) connector supports the following modules:

1. SuiteQL (referred to as `suiteql` in `amp.yaml`)
   * This is a read-only module that allows you to read data from NetSuite using [SuiteQL](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156257770590.html).
   * This module supports nearly all of the records documented in the [NetSuite Record Browser](https://system.netsuite.com/help/helpcenter/en_US/srbrowser/Browser2024_2/script/record/account.html).

2. REST API (referred to as `restapi` in `amp.yaml`)
   * This module allows you to read and write data to NetSuite using the REST API.
   * It supports all the resources documented in the [NetSuite REST API Reference](https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2024.2/index.html).

3. RESTlet (referred to as `restlet` in `amp.yaml`)
   * This module allows you to install an Ampersand RESTlet into your customer’s NetSuite instance, giving you deep read & write access.
   * This module is currently in private preview. Please get in touch with us at [support@withampersand.com](mailto:support@withampersand.com) to learn more.

By default, the connector will use the `restapi` module. To deploy the connector with a different module, specify the `module` field in the YAML manifest file.

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: netsuite-m2m-integration
    provider: netsuiteM2M
    module: restlet # default is restapi
    ...
```

You can use [this sample](https://github.com/amp-labs/samples/blob/main/netsuiteM2M/amp.yaml) to get started.

## Before You Get Started

This connector uses OAuth 2.0 machine-to-machine (M2M) authentication with certificate-based credentials.

To integrate NetSuite with Ampersand, your customer's NetSuite administrator will need to complete the setup steps in the [customer guide](/customer-guides/netsuite) and provide you with the following credentials:

* Account ID
* Client ID
* Certificate ID
* EC Private Key (PEM format)

If you are using the RESTlet module, your customer will also need to install the Ampersand RESTlet bundle and provide:

* RESTlet deployment URL

### Creating a NetSuite Integration

Your customer's NetSuite administrator creates the integration record and M2M certificate mapping. The full steps are documented in the [customer guide](/customer-guides/netsuite).

## Using the connector

To start integrating with NetSuite:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/netsuite/amp.yaml), using `netsuiteM2M` as the provider.
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Collect your customer's credentials (Account ID, Client ID, Certificate ID, EC Private Key) and create a connection.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.

## Customer guide

The [Netsuite customer guide](/customer-guides/netsuite) is a guide that can be shared with your customers to help them be successful in using your integration.


# Notion
Source: https://docs.ampersand.ai/provider-guides/notion



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.notion.com`.

## Before You Get Started

To integrate Notion with Ampersand, you will need [a Notion Account](https://www.notion.so/signup).

Once your account is created, you'll need to create an integration in Notion, configure the Ampersand redirect URI within the integration, and obtain the following credentials from your integration:

* OAuth Client ID
* OAuth Client Secret

You will then use this token to connect your application to Ampersand.

### Create a Notion Account

Here's how you can sign up for a Notion account:

* Go to the [Notion Sign Up page](https://www.notion.so/signup).
* Sign up using your preferred method.

### Creating a Notion Integration

Follow the steps below to create a Notion integration and add the Ampersand redirect URL.

1. Log in to the [Notion Integrations](https://www.notion.so/login?redirectURL=%2Fprofile%2Fintegrations) page.
2. Click the **New Integration** button.
3. Enter the following integration details:
   1. **Integration Name**: The name of your integration.
   2. **Associated Workspace**: The workspace linked to your integration.
   3. **Integration Type**: Select **Public**.
   4. **Website**: URL of your website.
   5. **Privacy Policy URL**: URL for your privacy policy.
   6. **Terms of Use URL**: URL for your terms of use.
   7. **Email**: Contact email.
   8. **Upload**: Icon or image representing your integration.
   9. **Redirect URIs**: Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

<img alt="Alt text" />

<br />

4. Click **Save**.

You'll see the option to **Configure integration settings** for your app. Clicking this button will display the **OAuth Client ID** and **OAuth Client Secret** keys, which are necessary for connecting your app to Ampersand.

<img alt="Alt text" />

## Add Your Notion Integration Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Notion integration.

   <img alt="Alt text" />

3. Select **Provider Apps**.

4. Select *Notion* from the **Provider** list.

5. Enter the previously obtained *OAuth Client ID* in the **Client ID** field and *OAuth Client Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save Changes**.


# Nutshell
Source: https://docs.ampersand.ai/provider-guides/nutshell



## What's supported

### Supported actions

This connector supports:

* [Write Actions](/write-actions).
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://app.nutshell.com/api/v1`.

### Supported Objects

The Nutshell connector supports reading from and writing to the following objects:

* [accounts/list](https://developers.nutshell.com/reference/get_accounts-list-2)
* [accounts](https://developers.nutshell.com/reference/get_accounts) (incremental read)
* [accounttypes](https://developers.nutshell.com/reference/get_accounttypes-3)
* [activities](https://developers.nutshell.com/reference/get_activities-1) (incremental read)
* [activitytypes](https://developers.nutshell.com/reference/get_activitytypes-1)
* [audiences](https://developers.nutshell.com/reference/get_audiences-1)
* [competitormaps](https://developers.nutshell.com/reference/get_competitormaps)
* [competitors](https://developers.nutshell.com/reference/get_competitors)
* [contacts/list](https://developers.nutshell.com/reference/get_contacts-list-2)
* [contacts](https://developers.nutshell.com/reference/get_contacts) (incremental read)
* [deleted](https://developers.nutshell.com/reference/get_events-deleted)
* [events](https://developers.nutshell.com/reference/get_events) (incremental read)
* [forms](https://developers.nutshell.com/reference/get_forms)
* [industries](https://developers.nutshell.com/reference/get_industries-1)
* [leads/list](https://developers.nutshell.com/reference/get_leads-list-4)
* [leads](https://developers.nutshell.com/reference/get_leads) (incremental read)
* [notes](https://developers.nutshell.com/reference/get_notes)
* [productmaps](https://developers.nutshell.com/reference/get_productmaps)
* [products](https://developers.nutshell.com/reference/get_products)
* [report](https://developers.nutshell.com/reference/get_leads-report-1)
* [sources](https://developers.nutshell.com/reference/get_sources)
* [stages](https://developers.nutshell.com/reference/get_stages)
* [stagesets](https://developers.nutshell.com/reference/get_stagesets-1)
* [tags](https://developers.nutshell.com/reference/get_tags)
* [territories](https://developers.nutshell.com/reference/get_territories)
* [users](https://developers.nutshell.com/reference/get_users)

### Example integration

To define an integration for Nutshell, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: nutshell-integration
    displayName: My Nutshell Integration
    provider: nutshell
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Nutshell:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://app.nutshell.com/api/v1`.


# Odoo
Source: https://docs.ampersand.ai/provider-guides/odoo



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}`.

### Example integration

To define an integration for Odoo, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: odooIntegration
    displayName: Odoo Integration
    provider: odoo
    proxy:
      enabled: true
```

## Before You Get Started

To use the Odoo connector, you'll need an API Key from your Odoo account. Here's how to get it:

1. Sign in to your Odoo instance, then open Preferences.
2. Open the Account security tab.
3. In the API Keys section, click New API Key.
4. Enter a description and set a duration.
5. Click Generate Key, then copy the API Key.

<img alt="Odoo API Key" />

For more details, see the [Odoo Authentication documentation](https://www.odoo.com/documentation/19.0/developer/reference/external_api.html#configuration).

## Using the connector

This connector uses API Key authentication, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To integrate with Odoo:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API Key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API Key supplied by the customer.


# Okta
Source: https://docs.ampersand.ai/provider-guides/okta



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Incremental reading is supported for the objects listed below. For all other objects, a full read of the Okta instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.okta.com`.

### Supported objects

The Okta connector supports reading from the following objects:

* [apps](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/) (supports incremental read)
* [authenticators](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Authenticator/) (supports incremental read)
* [authorizationServers](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/AuthorizationServer/) (supports incremental read)
* [brands](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Brands/)
* [devices](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/) (supports incremental read)
* [domains](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/CustomDomain/)
* [eventHooks](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/EventHook/) (supports incremental read)
* [features](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Feature/)
* [groups](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/) (supports incremental read)
* [idps](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/IdentityProvider/) (supports incremental read)
* [logs](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/SystemLog/) (supports incremental read)
* [policies](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Policy/) (supports incremental read)
* [trustedOrigins](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/TrustedOrigin/) (supports incremental read)
* [users](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/) (supports incremental read)
* [zones](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/NetworkZone/) (supports incremental read)

The Okta connector supports writing to the following objects:

* [groups](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/)
* [users](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/)

### Example integration

For an example manifest file of an Okta integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/okta/amp.yaml).

## Before you get started

To connect Okta with Ampersand, you will need an [Okta account](https://developer.okta.com/signup/).

Once your account is created, you'll need to create an OAuth 2.0 app in Okta and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will use these credentials to connect your application to Ampersand.

### Create an Okta account

Here's how you can sign up for an Okta developer account:

1. Go to the [Okta Developer Sign Up page](https://developer.okta.com/signup/) and create an account.
2. Complete the registration process and verify your email.

### Creating an Okta app

Follow the steps below to create an OAuth 2.0 app in Okta:

1. Sign in to your [Okta Admin Console](https://login.okta.com/).
2. Navigate to **Applications** > **Applications** in the left sidebar.
3. Click **Create App Integration**.
4. Select **OIDC - OpenID Connect** as the sign-in method.
5. Select **Web Application** as the application type and click **Next**.
6. Enter a descriptive **App integration name**.
7. In the **Sign-in redirect URIs** field, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`
8. Click **Save**.

The **Client ID** and **Client Secret** will be displayed in the **Client Credentials** section. Note these credentials, as you will need them to connect your app to Ampersand.

To configure scopes, navigate to the **Okta API Scopes** tab and click **Grant** next to each scope your integration requires.

<img alt="Okta App Creation" />

### Add your Okta app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create an Okta integration.

   <img alt="Ampersand project selection" />

3. Select **Provider Apps**.

4. Select **Okta** from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from your Okta app.

6. Enter the scopes set for your application in *Okta*. For a list of available scopes, refer to the [Okta documentation](https://developer.okta.com/docs/guides/implement-oauth-for-okta/main/#scopes-and-supported-endpoints).

   <img alt="Okta Ampersand integration" />

7. Click **Save Changes**.

## Using the connector

To start integrating with Okta:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# OpenAI
Source: https://docs.ampersand.ai/provider-guides/openAI



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.openai.com`.

### Example integration

To define an integration for OpenAI, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: openAI-integration
    displayName: My OpenAI Integration
    provider: openAI
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with OpenAI:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.openai.com`.

## Creating an API key for OpenAI

[Click here](https://platform.openai.com/docs/api-reference/api-keys) for more information about generating an API key for OpenAI. The UI components will display this link, so that your users can successfully create API keys.


# Outplay
Source: https://docs.ampersand.ai/provider-guides/outplay



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `call`, `prospectmails` and `callanalysis` currently. For all other objects, a full read of the Outplay instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}-api.outplayhq.com`.

### Supported objects

The Outplay connector supports writing and reading from the following objects:

* [prospect](https://documenter.getpostman.com/view/16947449/TzsikPV1#21e32202-0bb8-411c-a46d-58da59313f49) (read, write)
* [prospectaccount](https://documenter.getpostman.com/view/16947449/TzsikPV1#fd2bbb37-649b-43ce-b7ee-2485682d781b) (read, write)
* [sequence](https://documenter.getpostman.com/view/16947449/TzsikPV1#46779d31-ea51-4872-8cc9-59aafc7a7102) (read, write)
* [call](https://documenter.getpostman.com/view/16947449/TzsikPV1#b28babe6-9349-45dc-91a2-ef7dffcc6793) (read)
* [task](https://documenter.getpostman.com/view/16947449/TzsikPV1#a23ee5cd-758c-43d6-a356-34b4d0859cb5) (read, write)
* [callanalysis](https://documenter.getpostman.com/view/16947449/TzsikPV1#c44371cf-0819-4eb9-805a-7fdde9b4f9dc) (read)
* [prospectmails](https://documenter.getpostman.com/view/16947449/TzsikPV1#dd63ab01-f0f9-4f18-b94f-e0bcdd4ac926) (read)
* [note](https://documenter.getpostman.com/view/16947449/TzsikPV1#486b3fa0-4ea2-4b3e-aa1d-fcdeff0dd833) (write)

<Note>
  **Note:**
  The `call` object requires incremental read to be configured. Without it, only records from the last 30 days will be read.
</Note>

### Example integration

For an example manifest file of an Outplay integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/outplay/amp.yaml).

## Before you get started

You'll need an Outplay account and API credentials to use this connector.

### Creating Outplay credentials

1. Log into your Outplay account.
2. Navigate to **Settings** → **API Settings**.
3. Generate an API key if you haven't already.
4. Note your workspace identifier - this is the subdomain in your Outplay URL (e.g., if your Outplay URL is `https://mycompany-api.outplayhq.com`, your workspace is `mycompany`).

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Outplay:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If using Read or Write actions: create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API credentials and workspace location.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Outreach
Source: https://docs.ampersand.ai/provider-guides/outreach



## What's Supported

### Supported Actions

The Outreach connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for most of the supported objects. Note: Incremental reads are only supported on a per-day basis
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.outreach.io`.
* [Subscribe Actions](/subscribe-actions).

### Supported Objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Account/#tag/Account">accounts</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Audit-Log/#tag/Audit-Log/paths/~1auditLogs/get">auditLogs</a> \*</td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Call/#tag/Call">calls</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Call-Disposition/#tag/Call-Disposition">callDispositions</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Call-Purpose/#tag/Call-Purpose">callPurposes</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Compliance-Request/#tag/Compliance-Request">complianceRequests</a> \*</td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Content-Category">contentCategories</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Content-Category-Membership">contentCategoryMemberships</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Content-Category-Ownership/#tag/Content-Category-Ownership">contentCategoryOwnerships</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Currency-Type/#tag/Currency-Type">currencyTypes</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Custom-Duty/#tag/Custom-Duty/paths/~1customDuties/post">customDuties</a></td><td><Cross /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Dated-Conversion-Rate/#tag/Dated-Conversion-Rate">datedConversionRates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Duty/#tag/Duty/paths/~1duties/get">duties</a> \*</td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Email-Address/#tag/Email-Address">emailAddresses</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Event/#tag/Event/paths/~1events/get">events</a> \*</td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Favorite/#tag/Favorite">favorites</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td>import</td><td><Cross /></td><td><Cross /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Mail-Alias/#tag/Mail-Alias/paths/~1mailAliases/get">mailAliases</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Mailbox/#tag/Mailbox">mailboxes</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Mailing/#tag/Mailing">mailings</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Opportunity/#tag/Opportunity/paths">opportunities</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Opportunity-Prospect-Role/#tag/Opportunity-Prospect-Role">opportunityProspectRoles</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Opportunity-Stage/#tag/Opportunity-Stage">opportunityStages</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Persona/#tag/Persona">personas</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Phone-Number/#tag/Phone-Number">phoneNumbers</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Product/#tag/Product">products</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Profile/#tag/Profile">profiles</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Prospect/#tag/Prospect">prospects</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Purchase/#tag/Purchase">purchases</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Recipient/#tag/Recipient">recipients</a> \*</td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Role/#tag/Role">roles</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Ruleset/#tag/Ruleset">rulesets</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Sequence/#tag/Sequence">sequences</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Sequence-State/#tag/Sequence-State">sequenceStates</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Sequence-Step/#tag/Sequence-Step">sequenceSteps</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Sequence-Template/#tag/Sequence-Template">sequenceTemplates</a> \*</td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Snippet/#tag/Snippet">snippets</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Stage/#tag/Stage">stages</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Task/#tag/Task">tasks</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Task-Disposition/#tag">taskDispositions</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Task-Priority/#tag/Task-Priority/paths/~1taskPriorities/get">taskPriorities</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Task-Purpose/#tag/Task-Purpose">taskPurposes</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Team/#tag/Team">teams</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Template/#tag/Template">templates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/User/#tag/User">users</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.outreach.io/api/reference/tag/Webhook/#tag/Webhook">webhooks</a> \*</td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

*\* Only supports a full read each time, not incremental read.*

### Example Integration

For an example manifest file of an Outreach integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/outreach/amp.yaml).

## Before You Get Started

Before creating an **Outreach** app, you must complete the Outreach partnership process to obtain a sandbox instance. Please ensure that you add `https://api.withampersand.com/callbacks/v1/oauth` as a callback URL for the Outreach app.

After your account is set up, you will need to acquire the following credentials from your Outreach app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

## Add Outreach App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Outreach App.

3. Select **Provider apps**.

4. Select Outreach from the **Provider** list.

5. Enter the Outreach Application ID in the **Client ID** field, the Outreach Application Secret in the **Client Secret** field, and the requested scopes in the **Permissions** field.

6. Enter the scopes defined for the *Outreach* application.

<Note>
  For each object that you want to read, you need to add a scope for it, for example: `accounts.all`.
  If your integration uses Subscribe Actions, you also need to add the `webhooks.all` scope.
</Note>

<br />

<img alt="Alt text" />

7. Click **Save Changes**.

## Using the connector

To start integrating with Outreach:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/outreach/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Publish your Outreach app

When you are ready to publish your Outreach app to the Outreach Marketplace, follow the instructions on the [Outreach documentation](https://developers.outreach.io/guides/managing-apps/#publishing-apps).

## Limitations of development credentials

Please note that until you publish your app, there are limitations on the credentials you obtain via your Ampersand integration. While an unpublished app can be used to connect to other Outreach workspaces, such as those of your customers, Outreach will expire those credentials weekly. This means that your customers will need to re-install their integrations weekly. Refer to the [Outreach documentation](https://developers.outreach.io/api/oauth/#limitations-of-development-credentials) for more details.

Even after you publish your Outreach app, be sure to select the "Production" tab and use the Application ID and Secret from that tab for your Ampersand Provider App.

<img />


# Browse supported provider integrations
Source: https://docs.ampersand.ai/provider-guides/overview

Browse provider guides for CRMs, ERPs, help desks, and warehouses, split into deep connectors that read, write, and subscribe and auth and proxy connectors.

<div>
  <section>
    <div>
      <div>Integrations</div>
      <h1>Connect to the systems your customers <span>already run.</span></h1>
      <p>Explore integrations across CRMs, ERPs, communication tools, help desks, warehouses, and more. Each provider guide details supported objects, available actions, and prerequisite steps.</p>

      <div>
        <input type="search" placeholder="Search providers…" aria-label="Search providers" />

        <div />
      </div>
    </div>

    <div>
      <a href="#browse-by-category">
        <b>All</b><i>providers</i>
      </a>

      <div>
        <a href="/provider-guides/salesforce">
          <img alt="" />

          <span>Salesforce</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/hubspot">
          <img alt="" />

          <span>HubSpot</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/netsuite">
          <img alt="" />

          <span>NetSuite</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/dynamicsCRM">
          <img alt="" />

          <span>Dynamics 365 CRM</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/zoho">
          <img alt="" />

          <span>Zoho</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/google">
          <img alt="" />

          <span>Google</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/microsoft">
          <img alt="" />

          <span>Microsoft</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/pipedrive">
          <img alt="" />

          <span>Pipedrive</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/gong">
          <img alt="" />

          <span>Gong</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/chorus">
          <img alt="" />

          <span>Chorus</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/zendeskSupport">
          <img alt="" />

          <span>Zendesk Support</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/intercom">
          <img alt="" />

          <span>Intercom</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/outreach">
          <img alt="" />

          <span>Outreach</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/salesloft">
          <img alt="" />

          <span>Salesloft</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/stripe">
          <img alt="" />

          <span>Stripe</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/sageIntacct">
          <img alt="" />

          <span>Sage Intacct</span>
        </a>
      </div>

      <div>
        <a href="/provider-guides/shopify">
          <img alt="" />

          <span>Shopify</span>
        </a>
      </div>
    </div>
  </section>

  <section>
    <div>
      <h2>Deep connectors</h2>
      <span>Read, write, search, and subscribe. Check guide for supported actions and objects.</span>
    </div>

    <div>
      <div>
        <div>
          <span />

          <span>Enterprise CRM</span>
        </div>

        <div>
          <a href="/provider-guides/dynamicsCRM">Dynamics 365 CRM</a>
          <a href="/provider-guides/hubspot">HubSpot</a>
          <a href="/provider-guides/salesforce">Salesforce</a>
          <a href="/provider-guides/salesforce-jwt">Salesforce (JWT authentication)</a>
        </div>

        <div>
          <div>
            <span />

            <span>SMB CRM</span>
          </div>

          <div>
            <a href="/provider-guides/attio">Attio</a>
            <a href="/provider-guides/breakcold">Breakcold</a>
            <a href="/provider-guides/capsule">Capsule</a>
            <a href="/provider-guides/close">Close</a>
            <a href="/provider-guides/copper">Copper</a>
            <a href="/provider-guides/insightly">Insightly</a>
            <a href="/provider-guides/keap">Keap</a>
            <a href="/provider-guides/lightfield">Lightfield</a>
            <a href="/provider-guides/nutshell">Nutshell</a>
            <a href="/provider-guides/pipedrive">Pipedrive</a>
            <a href="/provider-guides/salesflare">Salesflare</a>
            <a href="/provider-guides/sellsy">Sellsy</a>
            <a href="/provider-guides/teamleader">Teamleader</a>
            <a href="/provider-guides/zoho">Zoho</a>
          </div>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Vertical CRM</span>
        </div>

        <div>
          <a href="/provider-guides/accuLynx">AccuLynx</a>
          <a href="/provider-guides/bentley">Bentley</a>
          <a href="/provider-guides/blackbaud">Blackbaud</a>
          <a href="/provider-guides/highlevel">HighLevel</a>
          <a href="/provider-guides/housecallPro">Housecall Pro</a>
          <a href="/provider-guides/jobber">Jobber</a>
          <a href="/provider-guides/loxo">Loxo</a>
          <a href="/provider-guides/procore">Procore</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>ERP and accounting</span>
        </div>

        <div>
          <a href="/provider-guides/dynamicsBusinessCentral">Dynamics 365 Business Central</a>
          <a href="/provider-guides/netsuite">NetSuite</a>
          <a href="/provider-guides/netsuite-m2m">NetSuite (M2M)</a>
          <a href="/provider-guides/quickbooks">QuickBooks</a>
          <a href="/provider-guides/sageIntacct">Sage Intacct</a>
          <a href="/provider-guides/xero">Xero</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Other financial tools</span>
        </div>

        <div>
          <a href="/provider-guides/braintree">Braintree</a>
          <a href="/provider-guides/chargebee">Chargebee</a>
          <a href="/provider-guides/paddle">Paddle</a>
          <a href="/provider-guides/ramp">Ramp</a>
          <a href="/provider-guides/recurly">Recurly</a>
          <a href="/provider-guides/revenuecat">RevenueCat</a>
          <a href="/provider-guides/shopify">Shopify</a>
          <a href="/provider-guides/square">Square</a>
          <a href="/provider-guides/stripe">Stripe</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Call recording, email, and calendar</span>
        </div>

        <div>
          <a href="/provider-guides/acuityScheduling">Acuity Scheduling</a>
          <a href="/provider-guides/avoma">Avoma</a>
          <a href="/provider-guides/calendly">Calendly</a>
          <a href="/provider-guides/callRail">CallRail</a>
          <a href="/provider-guides/chilipiper">ChiliPiper</a>
          <a href="/provider-guides/chorus">Chorus</a>
          <a href="/provider-guides/clariCopilot">Clari Copilot</a>
          <a href="/provider-guides/fathom">Fathom</a>
          <a href="/provider-guides/fireflies">Fireflies</a>
          <a href="/provider-guides/fourFour">Four/Four</a>
          <a href="/provider-guides/front">Front</a>
          <a href="/provider-guides/gong">Gong</a>
          <a href="/provider-guides/google">Google</a>
          <a href="/provider-guides/google-workspace-delegation">Google (workspace delegation)</a>
          <a href="/provider-guides/granola">Granola</a>
          <a href="/provider-guides/microsoft">Microsoft</a>
          <a href="/provider-guides/microsoftAdminConsent">Microsoft (Admin consent)</a>
          <a href="/provider-guides/mixmax">Mixmax</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Support, IT, and security</span>
        </div>

        <div>
          <a href="/provider-guides/aws">AWS</a>
          <a href="/provider-guides/connectWise">ConnectWise</a>
          <a href="/provider-guides/dixa">Dixa</a>
          <a href="/provider-guides/freshdesk">Freshdesk</a>
          <a href="/provider-guides/gorgias">Gorgias</a>
          <a href="/provider-guides/groove">Groove</a>
          <a href="/provider-guides/happyfox">HappyFox</a>
          <a href="/provider-guides/helpScoutMailbox">Help Scout Mailbox</a>
          <a href="/provider-guides/intercom">Intercom</a>
          <a href="/provider-guides/okta">Okta</a>
          <a href="/provider-guides/pylon">Pylon</a>
          <a href="/provider-guides/serviceNow">ServiceNow</a>
          <a href="/provider-guides/solarwindsServiceDesk">SolarWinds Service Desk</a>
          <a href="/provider-guides/zendeskSupport">Zendesk Support</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Sales and marketing</span>
        </div>

        <div>
          <a href="/provider-guides/apollo">Apollo</a>
          <a href="/provider-guides/blueshift">Blueshift</a>
          <a href="/provider-guides/braze">Braze</a>
          <a href="/provider-guides/brevo">Brevo</a>
          <a href="/provider-guides/campaignMonitor">Campaign Monitor</a>
          <a href="/provider-guides/constantContact">Constant Contact</a>
          <a href="/provider-guides/customerJourneysApp">Customer.io Journeys App</a>
          <a href="/provider-guides/drift">Drift</a>
          <a href="/provider-guides/getResponse">GetResponse</a>
          <a href="/provider-guides/heyreach">HeyReach</a>
          <a href="/provider-guides/hunter">Hunter</a>
          <a href="/provider-guides/instantly">Instantly</a>
          <a href="/provider-guides/iterable">Iterable</a>
          <a href="/provider-guides/kit">Kit</a>
          <a href="/provider-guides/klaviyo">Klaviyo</a>
          <a href="/provider-guides/lemlist">Lemlist</a>
          <a href="/provider-guides/linkedin">LinkedIn</a>
          <a href="/provider-guides/marketo">Marketo</a>
          <a href="/provider-guides/outplay">Outplay</a>
          <a href="/provider-guides/outreach">Outreach</a>
          <a href="/provider-guides/pinterest">Pinterest</a>
          <a href="/provider-guides/salesfinity">Salesfinity</a>
          <a href="/provider-guides/salesloft">Salesloft</a>
          <a href="/provider-guides/seismic">Seismic</a>
          <a href="/provider-guides/sendGrid">SendGrid</a>
          <a href="/provider-guides/smartlead">Smartlead</a>
          <a href="/provider-guides/snapchatAds">Snapchat Ads</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Project and product</span>
        </div>

        <div>
          <a href="/provider-guides/aha">Aha!</a>
          <a href="/provider-guides/asana">Asana</a>
          <a href="/provider-guides/clickup">ClickUp</a>
          <a href="/provider-guides/jira">Jira</a>
          <a href="/provider-guides/linear">Linear</a>
          <a href="/provider-guides/monday">Monday</a>
          <a href="/provider-guides/teamwork">Teamwork</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Developer tools</span>
        </div>

        <div>
          <a href="/provider-guides/atlassian">Atlassian</a>
          <a href="/provider-guides/bitbucket">Bitbucket</a>
          <a href="/provider-guides/devrev">DevRev</a>
          <a href="/provider-guides/flatfile">Flatfile</a>
          <a href="/provider-guides/github">GitHub</a>
          <a href="/provider-guides/gitlab">GitLab</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Data and analytics</span>
        </div>

        <div>
          <a href="/provider-guides/amplitude">Amplitude</a>
          <a href="/provider-guides/bigquery">BigQuery</a>
          <a href="/provider-guides/snowflake">Snowflake</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Communication and messaging</span>
        </div>

        <div>
          <a href="/provider-guides/aircall">Aircall</a>
          <a href="/provider-guides/cloudtalk">CloudTalk</a>
          <a href="/provider-guides/goTo">GoTo</a>
          <a href="/provider-guides/justCall">JustCall</a>
          <a href="/provider-guides/lob">Lob</a>
          <a href="/provider-guides/phoneBurner">PhoneBurner</a>
          <a href="/provider-guides/ringCentral">RingCentral</a>
          <a href="/provider-guides/slack">Slack</a>
          <a href="/provider-guides/talkdesk">Talkdesk</a>
          <a href="/provider-guides/webex">Webex</a>
          <a href="/provider-guides/zoom">Zoom</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Content and documents</span>
        </div>

        <div>
          <a href="/provider-guides/dropboxsign">Dropbox Sign</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>Surveys and feedback</span>
        </div>

        <div>
          <a href="/provider-guides/surveyMonkey">SurveyMonkey</a>
        </div>
      </div>

      <div>
        <div>
          <span />

          <span>HR and recruiting</span>
        </div>

        <div>
          <a href="/provider-guides/ashby">Ashby</a>
          <a href="/provider-guides/breezy">Breezy</a>
          <a href="/provider-guides/gusto">Gusto</a>
          <a href="/provider-guides/lever">Lever</a>
        </div>
      </div>
    </div>
  </section>

  <section>
    <div>
      <div>
        <span />

        <h2>Auth and proxy</h2>
        <span>Managed authentication and proxy access to the provider's API.</span>
      </div>

      <div>
        <a href="/provider-guides/airtable">Airtable</a>
        <a href="/provider-guides/amplemarket">Amplemarket</a>
        <a href="/provider-guides/anthropic">Anthropic</a>
        <a href="/provider-guides/aweber">AWeber</a>
        <a href="/provider-guides/basecamp">Basecamp</a>
        <a href="/provider-guides/bird">Bird (MessageBird)</a>
        <a href="/provider-guides/blueshiftEU">Blueshift (EU)</a>
        <a href="/provider-guides/box">Box</a>
        <a href="/provider-guides/bynder">Bynder</a>
        <a href="/provider-guides/chargeOver">ChargeOver</a>
        <a href="/provider-guides/chartMogul">ChartMogul</a>
        <a href="/provider-guides/clari">Clari</a>
        <a href="/provider-guides/coda">Coda</a>
        <a href="/provider-guides/coupa">Coupa</a>
        <a href="/provider-guides/crunchbase">Crunchbase</a>
        <a href="/provider-guides/customerJourneysTrack">Customer.io Journeys Track</a>
        <a href="/provider-guides/delighted">Delighted</a>
        <a href="/provider-guides/discord">Discord</a>
        <a href="/provider-guides/discourse">Discourse</a>
        <a href="/provider-guides/docusign">Docusign</a>
        <a href="/provider-guides/domo">Domo</a>
        <a href="/provider-guides/dovetail">Dovetail</a>
        <a href="/provider-guides/drip">Drip</a>
        <a href="/provider-guides/dropbox">Dropbox</a>
        <a href="/provider-guides/emailBison">EmailBison</a>
        <a href="/provider-guides/figma">Figma</a>
        <a href="/provider-guides/formstack">Formstack</a>
        <a href="/provider-guides/freshchat">Freshchat</a>
        <a href="/provider-guides/g2">G2</a>
        <a href="/provider-guides/geckoboard">Geckoboard</a>
        <a href="/provider-guides/guru">Guru</a>
        <a href="/provider-guides/hightouch">Hightouch</a>
        <a href="/provider-guides/hive">Hive</a>
        <a href="/provider-guides/ironclad">Ironclad</a>
        <a href="/provider-guides/joinMe">Join.me</a>
        <a href="/provider-guides/jotform">Jotform</a>
        <a href="/provider-guides/jump">Jump</a>
        <a href="/provider-guides/kaseyaVSAX">Kaseya VSAX</a>
        <a href="/provider-guides/livestorm">Livestorm</a>
        <a href="/provider-guides/mailgun">Mailgun</a>
        <a href="/provider-guides/meta">Meta</a>
        <a href="/provider-guides/miro">Miro</a>
        <a href="/provider-guides/mixpanel">Mixpanel</a>
        <a href="/provider-guides/monaco">Monaco</a>
        <a href="/provider-guides/mural">Mural</a>
        <a href="/provider-guides/notion">Notion</a>
        <a href="/provider-guides/odoo">Odoo</a>
        <a href="/provider-guides/openAI">OpenAI</a>
        <a href="/provider-guides/paddleSandbox">Paddle Sandbox</a>
        <a href="/provider-guides/pipeliner">Pipeliner</a>
        <a href="/provider-guides/podium">Podium</a>
        <a href="/provider-guides/productBoard">Productboard</a>
        <a href="/provider-guides/rebilly">Rebilly</a>
        <a href="/provider-guides/reply">Reply</a>
        <a href="/provider-guides/segment">Segment</a>
        <a href="/provider-guides/smartsheet">Smartsheet</a>
        <a href="/provider-guides/superSend">SuperSend</a>
        <a href="/provider-guides/timely">Timely</a>
        <a href="/provider-guides/tipalti">Tipalti</a>
        <a href="/provider-guides/vtiger">Vtiger</a>
        <a href="/provider-guides/wealthbox">Wealthbox</a>
        <a href="/provider-guides/webflow">Webflow</a>
        <a href="/provider-guides/whereby">Whereby</a>
        <a href="/provider-guides/wordpress">WordPress</a>
        <a href="/provider-guides/workday">Workday</a>
        <a href="/provider-guides/wrike">Wrike</a>
        <a href="/provider-guides/zoominfo">ZoomInfo</a>
      </div>
    </div>
  </section>

  <section>
    <div>
      <h2>More resources</h2>
    </div>

    <div>
      <a href="/customer-guides/overview">
        <div>Customer guides</div>
        <div>Docs for your customers</div>
        <div>Helpful instructions and tips to help your customers set up a successful integration.</div>
        <div>Read the guides →</div>
      </a>

      <a href="https://www.ampersand.ai/demo?cta=docs_integrations">
        <div>Request a connector</div>
        <div>Missing a provider or need a deeper integration?</div>
        <div>We can build it for you. Tell us which provider, objects, and actions you need.</div>
        <div>Chat with an engineer →</div>
      </a>
    </div>
  </section>
</div>


# Paddle
Source: https://docs.ampersand.ai/provider-guides/paddle



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental reading is only supported for `transactions`. For all other objects, a full read of the Paddle instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.paddle.com`.

### Supported objects

The Paddle connector supports reading from the following objects:

* [adjustments](https://developer.paddle.com/api-reference/adjustments/list-adjustments)
* [client-tokens](https://developer.paddle.com/api-reference/client-tokens/list-client-tokens)
* [customers](https://developer.paddle.com/api-reference/customers/list-customers)
* [discount-groups](https://developer.paddle.com/api-reference/discounts/list-discount-groups)
* [discounts](https://developer.paddle.com/api-reference/discounts/list-discounts)
* [event-types](https://developer.paddle.com/api-reference/events/list-event-types)
* [events](https://developer.paddle.com/api-reference/events/list-events)
* [notification-settings](https://developer.paddle.com/api-reference/notifications/list-notification-settings)
* [notifications](https://developer.paddle.com/api-reference/notifications/list-notifications)
* [prices](https://developer.paddle.com/api-reference/prices/list-prices)
* [products](https://developer.paddle.com/api-reference/products/list-products)
* [reports](https://developer.paddle.com/api-reference/reports/list-reports)
* [simulation-types](https://developer.paddle.com/api-reference/simulations/list-simulation-types)
* [simulations](https://developer.paddle.com/api-reference/simulations/list-simulations)
* [subscriptions](https://developer.paddle.com/api-reference/subscriptions/list-subscriptions)
* [transactions](https://developer.paddle.com/api-reference/transactions/list-transactions)

The Paddle connector supports writing to the following objects:

* [adjustments](https://developer.paddle.com/api-reference/adjustments/create-adjustment)
* [client-tokens](https://developer.paddle.com/api-reference/client-tokens/create-client-token)
* [customers](https://developer.paddle.com/api-reference/customers/create-customer)
* [discount-groups](https://developer.paddle.com/api-reference/discounts/create-discount-group)
* [discounts](https://developer.paddle.com/api-reference/discounts/create-discount)
* [notification-settings](https://developer.paddle.com/api-reference/notifications/create-notification-setting)
* [prices](https://developer.paddle.com/api-reference/prices/create-price)
* [products](https://developer.paddle.com/api-reference/products/create-product)
* [reports](https://developer.paddle.com/api-reference/reports/create-report)
* [simulations](https://developer.paddle.com/api-reference/simulations/create-simulation)
* [transactions](https://developer.paddle.com/api-reference/transactions/create-transaction)

### Example integration

For an example manifest file of a Paddle integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/paddle/amp.yaml).

## Creating an API key

[Click here](https://developer.paddle.com/api-reference/about/authentication) for more information about generating an API key for Paddle.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Paddle:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/paddle/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Paddle Sandbox
Source: https://docs.ampersand.ai/provider-guides/paddleSandbox



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://sandbox-api.paddle.com`.

### Example integration

To define an integration for Paddle Sandbox, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: paddleSandbox-integration
    displayName: My Paddle Sandbox Integration
    provider: paddleSandbox
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Paddle Sandbox:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://sandbox-api.paddle.com`.

## Creating an API key for Paddle Sandbox

[Click here](https://developer.paddle.com/api-reference/about/authentication) for more information about generating an API key for Paddle Sandbox. The UI components will display this link, so that your users can successfully create API keys.


# PhoneBurner
Source: https://docs.ampersand.ai/provider-guides/phoneBurner



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `contacts`, `dialsession`, `members`, and `voicemails` currently. For all other objects, a full read of the PhoneBurner instance will be done per scheduled read.
* [Write Actions](/write-actions) (create/update).
* [Proxy Actions](/proxy-actions), using the base URL `https://www.phoneburner.com`.
* Subscribe Actions are not currently supported.

### Supported objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Metadata</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://www.phoneburner.com/developer/route_list#contacts">contacts</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.phoneburner.com/developer/route_list#folders">folders</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.phoneburner.com/developer/route_list#members">members</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.phoneburner.com/developer/route_list#dialsession">dialsession</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.phoneburner.com/developer/route_list#voicemails">voicemails</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.phoneburner.com/developer/route_list#tags">tags</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

### Notes and limitations

* **Write support**:
  * `contacts`, `folders`, `members`: create + update
  * `dialsession`: create only
* **Read-only objects**: `voicemails`, `tags`

### Example integration

To define an integration for PhoneBurner, create a manifest file that looks like this. For a complete example, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/phoneBurner/amp.yaml).

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: phone-burner-integration
    displayName: My PhoneBurner Integration
    provider: phoneBurner
    read:
      objects:
        - objectName: contacts
          destination: defaultWebhook
          schedule: "*/30 * * * *"
    write:
      objects:
        - objectName: contacts
          inheritMapping: true
    proxy:
      enabled: true
```

## Before You Get Started

To connect *PhoneBurner* with *Ampersand*, you will need [a PhoneBurner Account](https://www.phoneburner.com/).

Once your account is created, you'll need to configure an app in *PhoneBurner* and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a PhoneBurner account

Here's how you can sign up for a **PhoneBurner Developer** account:

* Visit the [Get Developer Account page](https://www.phoneburner.com/developer/getting_started#developer_account) and follow the step-by-step instructions to create your account.

### Creating a PhoneBurner App

Follow the steps below to create a *PhoneBurner* app and add the Ampersand redirect URL in the app:

1. Log in to your [PhoneBurner Developer Account](https://www.phoneburner.com/homepage/login).

2. Click your avatar and select **My Account**

3. Open the **Integrations** tab.

4. From the left menu, select **Custom Applications**.

5. Click **Register new application**.

6. Enter the **Application Name** and **Contact** details.

7. In the **OAuth2 Redirect URL** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

8. Enter application **Description**.

   <img alt="PhoneBurner App Creation" />

9. Click **Register application**.

You'll see the details of your newly created application. Note the **Client ID** and **Client Secret** keys as they are necessary for connecting your app to Ampersand.

<img alt="PhoneBurner App Credentials" />

## Add your PhoneBurner app info to Ampersand

1. Log in to your [Ampersand Console](https://console.withampersand.com).

2. Select the project where you want to create a PhoneBurner integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider apps**.

4. Select *PhoneBurner* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="PhoneBurner Integration in Ampersand" />

6. Click **Save changes**.

## Using the connector

To start integrating with PhoneBurner:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Pinterest
Source: https://docs.ampersand.ai/provider-guides/pinterest



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Pinterest instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.pinterest.com`.

### Supported objects

The Pinterest connector supports reading from the following objects:

* [pins](https://developers.pinterest.com/docs/api/v5/pins-list)
* [boards](https://developers.pinterest.com/docs/api/v5/boards-list)
* [media](https://developers.pinterest.com/docs/api/v5/media-list)
* [ad\_accounts](https://developers.pinterest.com/docs/api/v5/ad_accounts-list)
* [catalogs](https://developers.pinterest.com/docs/api/v5/catalogs-list)
* [employers](https://developers.pinterest.com/docs/api/v5/get-business_employers)
* [feeds](https://developers.pinterest.com/docs/api/v5/feeds-list)
* [product\_groups](https://developers.pinterest.com/docs/api/v5/catalogs_product_groups-list)
* [integrations](https://developers.pinterest.com/docs/api/v5/integrations-get_list)
* [stats](https://developers.pinterest.com/docs/api/v5/reports-stats)

The Pinterest connector supports writing to the following objects:

* [pins](https://developers.pinterest.com/docs/api/v5/pins-create)
* [boards](https://developers.pinterest.com/docs/api/v5/boards-create)
* [media](https://developers.pinterest.com/docs/api/v5/media-create)
* [ad\_accounts](https://developers.pinterest.com/docs/api/v5/ad_accounts-create)
* [catalogs](https://developers.pinterest.com/docs/api/v5/catalogs-create)
* [feeds](https://developers.pinterest.com/docs/api/v5/feeds-create)
* [product\_groups](https://developers.pinterest.com/docs/api/v5/catalogs_product_groups-create)
* [websites](https://developers.pinterest.com/docs/api/v5/verify_website-update)
* [commerce](https://developers.pinterest.com/docs/api/v5/integrations_commerce-post)
* [logs](https://developers.pinterest.com/docs/api/v5/integrations_logs-post)
* [reports](https://developers.pinterest.com/docs/api/v5/reports-create)

### Example integration

For an example manifest file of a Pinterest integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/pinterest/amp.yaml).

## Before you get started

To integrate Pinterest with Ampersand, you will need a [Pinterest Developer Account](https://developers.pinterest.com/).

Once your account is created, you'll need to create an app in Pinterest, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* App ID
* App Secret
* Scopes

You will then use these credentials and scopes to connect your application to Ampersand.

### Create a Pinterest account

Here's how you can sign up for a Pinterest account:

* Go to the [Pinterest Sign Up page](https://www.pinterest.com/join/) and create a business account.
* Verify your account's email address.
* [Sign In](https://developers.pinterest.com/) to the newly created account and go to **My apps**.
* Click through to accept Pinterest Developer Terms of Service.

### Creating a Pinterest app

Follow the steps below to create a Pinterest app:

1. Log in to your [Pinterest Developer Console](https://developers.pinterest.com/).
2. Click **My Apps**.
3. Click **Connect App**.
4. Enter the app details and click **Submit**.

<img alt="Alt text" />

> 📔 Note
>
> You must submit your app for trial access. Once your access is approved, you can log in to manage your app details on the **My Apps** page, where you can find your app ID and secret.

### Adding Ampersand redirect URL to Pinterest app

1. Log in to your [Pinterest developer console](https://developers.pinterest.com/).

2. Go to **My apps** and select **Manage** for the app you want to configure.

3. On the **Configure** tab scroll to the **Redirect URIs** section and enter the Ampersand **Callback URI**: `https://api.withampersand.com/callbacks/v1/oauth`.

4. Select **Add** to save your changes

<img alt="Alt text" />

You'll find the **App ID**, **App Secret**, and **Scopes** keys in the **Configure** section of your app. These credentials are required for connecting your app to Ampersand, so be sure to note them carefully.

## Add Your Pinterest app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Pinterest integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Pinterest* from the **Provider** list.

5. Enter the previously obtained *App ID* in the **App ID** field and the *App Secret* in the **App Secret** field.

6. Enter the scopes set for your application in *Pinterest*. For more details on the scopes, go to the [Pinterest API Scopes](https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/) documentation.

   <img alt="Alt text" />

7. Click **Save changes**.

## Using the connector

To start integrating with Pinterest:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/pinterest/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Pipedrive
Source: https://docs.ampersand.ai/provider-guides/pipedrive



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions) including full historic backfill. Incremental read is supported for select objects using the v2 API (see [v2 API Objects](#supported-objects-for-v2-api) below). For all other objects, a full read of the Pipedrive instance will be done for each scheduled read.
* [Write Actions](/write-actions)
* [Proxy Actions](/proxy-actions), using the base URL `https://api.pipedrive.com`.

Pipedrive has a v1 and v2 API, if you would like to opt into the v2 API, then add `module: crm` to your amp.yaml file. If you would like to use v1 API, add `module: legacy` to your amp.yaml file. If you do not specify a module, v1 API is used. You can learn more about the difference between v1 and v2 API in [Pipedrive documentation](https://pipedrive.readme.io/docs/pipedrive-api-v2-migration-guide).

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: read-write-pipedrive
    provider: pipedrive
    module: "crm" # The CRM module uses v2 APIs
```

### Supported Objects for V2 API

The Pipedrive connector supports reading and writing to the following objects.

| Object | Incremental Read |
| - | :-: |
| [Activities](https://developers.pipedrive.com/docs/api/v1/Activities) | Yes |
| [Deals](https://developers.pipedrive.com/docs/api/v1/Deals) | Yes |
| [Organizations](https://developers.pipedrive.com/docs/api/v1/Organizations) | Yes |
| [Persons](https://developers.pipedrive.com/docs/api/v1/Persons) | Yes |
| [Pipelines](https://developers.pipedrive.com/docs/api/v1/Pipelines) | No |
| [Products](https://developers.pipedrive.com/docs/api/v1/Products) | No |
| [Stages](https://developers.pipedrive.com/docs/api/v1/Stages) | No |

#### Reading Deal Products

If you would like to read Products associated with Deals, add `products` as a field in `deals`.

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: read-write-pipedrive
    provider: pipedrive
    # The CRM module uses v2 APIs, which is required for to read deal products
    module: "crm"
    read:
      objects:
        - objectName: deals
          destination: pipedrive-webhook
          schedule: "*/10 * * * *" # Every 10 minutes
          requiredFields:
            - fieldName: id
            - fieldName: products # Add products as a field
```

#### Example Integration

For an example manifest file of a Pipedrive v2 integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/pipedrive/v2/amp.yaml).

### Supported Objects for V1 API

The Pipedrive connector supports reading from the following objects using the v1 API:

* [Activities](https://developers.pipedrive.com/docs/api/v1/Activities#getActivities)
* [Activity Fields](https://developers.pipedrive.com/docs/api/v1/ActivityFields#getActivityFields)
* [Activity Types](https://developers.pipedrive.com/docs/api/v1/ActivityTypes#getActivityTypes)
* [Call Logs](https://developers.pipedrive.com/docs/api/v1/CallLogs#getUserCallLogs)
* [Currencies](https://developers.pipedrive.com/docs/api/v1/Currencies#getCurrencies)
* [Deals](https://developers.pipedrive.com/docs/api/v1/Deals#getDeals)
* [Deal Fields](https://developers.pipedrive.com/docs/api/v1/DealFields#getDealFields)
* [Files](https://developers.pipedrive.com/docs/api/v1/Files#getFiles)
* [Filters](https://developers.pipedrive.com/docs/api/v1/Filters#getFilters)
* [Leads](https://developers.pipedrive.com/docs/api/v1/Leads#getLeads)
* [Lead Labels](https://developers.pipedrive.com/docs/api/v1/LeadLabels#getLeadLabels)
* [Lead Sources](https://developers.pipedrive.com/docs/api/v1/LeadSources#getLeadSources)
* [LegacyTeams](https://developers.pipedrive.com/docs/api/v1/LegacyTeams#getTeams)
* [Mail Threads](https://developers.pipedrive.com/docs/api/v1/Mailbox#getMailThreads) (use `mailThreads` in amp.yaml, no incremental read)
* [Notes](https://developers.pipedrive.com/docs/api/v1/Notes#getNotes)
* [Note Fields](https://developers.pipedrive.com/docs/api/v1/NoteFields#getNoteFields)
* [Organizations](https://developers.pipedrive.com/docs/api/v1/Organizations#getOrganizations)
* [Organization Fields](https://developers.pipedrive.com/docs/api/v1/OrganizationFields)
* [Organization Relationships](https://developers.pipedrive.com/docs/api/v1/OrganizationRelationships#getOrganizationRelationships)
* [Permission Sets](https://developers.pipedrive.com/docs/api/v1/PermissionSets#getPermissionSets)
* [Persons](https://developers.pipedrive.com/docs/api/v1/Persons#getPersons)
* [Person Fields](https://developers.pipedrive.com/docs/api/v1/PersonFields#getPersonFields)
* [Pipelines](https://developers.pipedrive.com/docs/api/v1/Pipelines#getPipeline)
* [Products](https://developers.pipedrive.com/docs/api/v1/Products#getProducts)
* [Product Fields](https://developers.pipedrive.com/docs/api/v1/ProductFields#getProductFields)
* [Projects](https://developers.pipedrive.com/docs/api/v1/Projects#getProjects)
* [Project Templates](https://developers.pipedrive.com/docs/api/v1/ProjectTemplates#getProjectTemplates)
* [Recents](https://developers.pipedrive.com/docs/api/v1/Recents#getRecents)
* [Roles](https://developers.pipedrive.com/docs/api/v1/Roles#getRoles)
* [Stages](https://developers.pipedrive.com/docs/api/v1/Stages#getStages)
* [Tasks](https://developers.pipedrive.com/docs/api/v1/Tasks#getTasks)
* [Users](https://developers.pipedrive.com/docs/api/v1/Users#getUsers)
* [User Connections](https://developers.pipedrive.com/docs/api/v1/UserConnections#getUserConnections)
* [User Settings](https://developers.pipedrive.com/docs/api/v1/UserSettings#getUserSettings)
* [Webhooks](https://developers.pipedrive.com/docs/api/v1/Webhooks#getWebhooks)

The Pipedrive connector supports writing to the following objects:

* [Activities](https://developers.pipedrive.com/docs/api/v1/Activities#addActivity)
* [Activity Types](https://developers.pipedrive.com/docs/api/v1/ActivityTypes#addActivityType)
* [Call Logs](https://developers.pipedrive.com/docs/api/v1/CallLogs#addCallLog)
* [Channels](https://developers.pipedrive.com/docs/api/v1/Channels#addChannel)
* [Currencies](https://developers.pipedrive.com/docs/api/v1/Currencies)
* [Deals](https://developers.pipedrive.com/docs/api/v1/Deals#getDeals)
* [Deal Fields](https://developers.pipedrive.com/docs/api/v1/DealFields#addDealField)
* [Files](https://developers.pipedrive.com/docs/api/v1/Files#addFile)
* [Filters](https://developers.pipedrive.com/docs/api/v1/Filters#addFilter)
* [Leads](https://developers.pipedrive.com/docs/api/v1/Leads#addLead)
* [Lead Labels](https://developers.pipedrive.com/docs/api/v1/LeadLabels#addLeadLabel)
* [legacy Teams](https://developers.pipedrive.com/docs/api/v1/LegacyTeams#addTeam)
* [Notes](https://developers.pipedrive.com/docs/api/v1/Notes#addNote)
* [Organizations](https://developers.pipedrive.com/docs/api/v1/Organizations#addOrganization)
* [Organization Fields](https://developers.pipedrive.com/docs/api/v1/OrganizationFields#addOrganizationField)
* [Organization Relationship](https://developers.pipedrive.com/docs/api/v1/OrganizationRelationships#addOrganizationRelationship)
* [Person](https://developers.pipedrive.com/docs/api/v1/Persons#addPerson)
* [Person Fields](https://developers.pipedrive.com/docs/api/v1/PersonFields#addPersonField)
* [Pipelines](https://developers.pipedrive.com/docs/api/v1/Pipelines#addPipeline)
* [Products](https://developers.pipedrive.com/docs/api/v1/Products#addProduct)
* [Product Fields](https://developers.pipedrive.com/docs/api/v1/ProductFields#addProductField)
* [Projects](https://developers.pipedrive.com/docs/api/v1/Projects#addProject)
* [Roles](https://developers.pipedrive.com/docs/api/v1/Roles#addRole)
* [Stages](https://developers.pipedrive.com/docs/api/v1/Stages#addStage)
* [Tasks](https://developers.pipedrive.com/docs/api/v1/Tasks#addTask)
* [Users](https://developers.pipedrive.com/docs/api/v1/Users#addUser)
* [Webhooks](https://developers.pipedrive.com/docs/api/v1/Webhooks#addWebhook)

#### Example Integration

For an example manifest file of a Pipedrive v1 integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/pipedrive/v1/amp.yaml).

## Before You Get Started

To integrate Pipedrive with Ampersand, you will need [a Pipedrive Account](https://www.pipedrive.com/signup).

Once your account is created, you'll need to create an app in Pipedrive, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* OAuth Client ID
* OAuth Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Pipedrive Account

Here's how you can sign up for a Pipedrive account:

* Go to the [Pipedrive Sign Up page](https://www.pipedrive.com/signup).
* Sign up using your preferred method.

### Creating a Pipedrive App

Follow the steps below to create a Pipedrive app and add the Ampersand redirect URL.

1. Log in to your [Pipedrive](https://app.pipedrive.com/login) account.
2. Go to [Developer Hub](https://marketplace.pipedrive.com/app/manage).
3. Click the **Create an app** button.
4. Select **Create private app**.
5. Enter the following app details:
   * **App Name**: The name of your app.
   * **Callback URL**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
6. In the **OAuth and access scopes** section, select the relevant scopes for your app.
7. Click **Save**.

<img alt="Alt text" />

In the **Client ID** section of **OAuth and access scopes**, you will find the **Client ID** and **Client Secret** keys. Note these keys, as they are essential for connecting your app to Ampersand.

<img alt="Alt text" />

## Add Your Pipedrive App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Pipedrive integration.

   <img alt="Alt text" />

3. Select **Provider Apps**.

4. Select *Pipedrive* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and *Client Secret* in the **Client Secret** field.

6. Click **Save Changes**.


# Pipeliner
Source: https://docs.ampersand.ai/provider-guides/pipeliner



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://eu-central.api.pipelinersales.com`.

### Supported Objects

The Pipeliner connector supports writing to and reading from all 195 objects available within the Pipeliner API, including:

* [Accounts](https://pipeliner.stoplight.io/docs/api-docs/elt527zmm4t7z-account)
* [Account KPIs](https://pipeliner.stoplight.io/docs/api-docs/i4eiukx6ow3mg-account-kpi)
* [Activities](https://pipeliner.stoplight.io/docs/api-docs/mlkdfymyzgyal-activity)
* [Activity Comments](https://pipeliner.stoplight.io/docs/api-docs/52fjjbc6ati70-activity-comment)
* [API Accesses](https://pipeliner.stoplight.io/docs/api-docs/dit5z42yttr4t-api-access)
* [Appointments](https://pipeliner.stoplight.io/docs/api-docs/tdq08v2gpkuh6-appointment)
* [Appointment Schedules](https://pipeliner.stoplight.io/docs/api-docs/bfwixqvyout0g-appointment-schedule)
* [Approvals](https://pipeliner.stoplight.io/docs/api-docs/7ccaqcemtypdg-approval)
* [Calls](https://pipeliner.stoplight.io/docs/api-docs/mjyjv4a5b3stg-call)
* [Clients](https://pipeliner.stoplight.io/docs/api-docs/ze1uoa5rd5kew-client)
* [Cloud Objects](https://pipeliner.stoplight.io/docs/api-docs/1nxekntag985c-cloud-object)
* [Cloud Object Templates](https://pipeliner.stoplight.io/docs/api-docs/ohd4s54k5g5uo-cloud-object-template)
* [Contacts](https://pipeliner.stoplight.io/docs/api-docs/y823u6p018div-contact)
* [Data](https://pipeliner.stoplight.io/docs/api-docs/3my1sz5yg556x-data)
* [Data Relations](https://pipeliner.stoplight.io/docs/api-docs/kngvj3c7pgnvs-data-relation)
* [Emails](https://pipeliner.stoplight.io/docs/api-docs/04pfaheaosg5p-email)
* [Entities](https://pipeliner.stoplight.io/docs/api-docs/aut7fgwkmid6o-entity)
* [Fields](https://pipeliner.stoplight.io/docs/api-docs/hnuueunrms0ht-field)
* [Forecasts](https://pipeliner.stoplight.io/docs/api-docs/58tgf0wd5m13a-forecast)
* [FormViews](https://pipeliner.stoplight.io/docs/api-docs/7bsx03uaegxnd-form-view)
* [Leads](https://pipeliner.stoplight.io/docs/api-docs/10fn36vhvnwpt-lead)
* [Notes](https://pipeliner.stoplight.io/docs/api-docs/alos8ba6krg22-note)
* [Online Forms](https://pipeliner.stoplight.io/docs/api-docs/kkhpv5viecu6l-online-form)
* [Opportunities](https://pipeliner.stoplight.io/docs/api-docs/0wiyusit6ajet-opportunity)
* [Phones](https://pipeliner.stoplight.io/docs/api-docs/3jo5gp2m7fp8e-phone)
* [Pipelines](https://pipeliner.stoplight.io/docs/api-docs/9o7fias1do16v-pipeline)
* [Processes](https://pipeliner.stoplight.io/docs/api-docs/he5d4vh9wekkg-process)
* [Products](https://pipeliner.stoplight.io/docs/api-docs/69wlbhvsyt7hw-product)
* [Profiles](https://pipeliner.stoplight.io/docs/api-docs/osdd7b6kt8rb4-profile)
* [Projects](https://pipeliner.stoplight.io/docs/api-docs/2jrox8wxdgfca-project)
* [Quotes](https://pipeliner.stoplight.io/docs/api-docs/joav0xhmva6fi-quote)
* [Reports](https://pipeliner.stoplight.io/docs/api-docs/ll1lfl4ipyi92-report)
* [Sales Units](https://pipeliner.stoplight.io/docs/api-docs/1hu89yk8ksap3-sales-unit)
* [Steps](https://pipeliner.stoplight.io/docs/api-docs/190bhebglfl85-step)
* [Tags](https://pipeliner.stoplight.io/docs/api-docs/9rk7d1eyzf81t-tag)
* [Targets](https://pipeliner.stoplight.io/docs/api-docs/4lqi9jnjdlvpq-target)
* [Tasks](https://pipeliner.stoplight.io/docs/api-docs/0p6z0evhpta5x-task)
* [Text Messages](https://pipeliner.stoplight.io/docs/api-docs/n5k5pqrahrbc1-text-message)
* [Webhooks](https://pipeliner.stoplight.io/docs/api-docs/vjcbqy57drdrw-webhook)
* [Web Resources](https://pipeliner.stoplight.io/docs/api-docs/yp4ku0yx9315r-webresource)
* All other objects in [Pipeliner API](https://pipeliner.stoplight.io/docs/api-docs)

### Example integration

To define an integration for Pipeliner, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: pipeliner-integration
    displayName: My Pipeliner Integration
    provider: pipeliner
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Pipeliner:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that this connector's base URL is `https://eu-central.api.pipelinersales.com`.


# Podium
Source: https://docs.ampersand.ai/provider-guides/podium



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.podium.com`.

## Before You Get Started

To connect Podium with Ampersand, you will need [a Podium Developer Account](https://developer.podium.com/).

Once your account is created, you'll need to register an app in the Podium developer portal, configure the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Podium Account

Here's how you can sign up for a Podium account:

* Go to the [Podium Developer website](https://developer.podium.com/) and sign up for an account.

### Register a Podium App

Follow the steps below to register a Podium app:

1. Log into your [Podium Developer account](https://developer.podium.com/).
2. Click on **Create App**.
3. Enter your app name and click **Create app**.
4. Navigate to the **Oauth** tab in your app.
5. In the **Redirect URI** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
6. In the **Scopes** section, select the necessary scopes for your application.
7. Click **Save**.

<img alt="Ampersand Project Selection" />

You will find the **Client ID** and **Client Secret** keys for your application in the **Credentials** section. Note these down, as you will need them to connect your app to Ampersand.

## Add Your Podium App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a Podium integration.\\
   <img alt="Ampersand Project Selection" />
3. Select **Provider Apps**.
4. Select **Podium** from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.
6. Enter the scopes set for your application in *Podium*.

   <img alt="Ampersand Project Selection" />
7. Click **Save Changes**.


# Procore
Source: https://docs.ampersand.ai/provider-guides/procore



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Incremental reading is supported for the objects listed below. For all other objects, a full read of the Procore instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.procore.com`.

### Notes

* During installation, you must provide your Procore company ID. You can find your company ID in the Procore URL after login. For example, in `https://procore.com/4283186/company/home/thumbnail`, the company ID is `4283186`.
* Use the Procore Sandbox connector when you want to test against `https://sandbox.procore.com`.

### Supported objects

The Procore connector supports reading from and writing to the following objects:

#### Read objects

* [action\_plans/plan\_types](https://developers.procore.com/reference/rest/v1/action-plans) (supports incremental read)
* [action\_plans/verification\_methods](https://developers.procore.com/reference/rest/v1/action-plans) (supports incremental read)
* [app\_configurations](https://developers.procore.com/reference/rest/v1/app-configurations)
* [bid\_packages](https://developers.procore.com/reference/rest/v1/bid-packages)
* [change\_order/statuses](https://developers.procore.com/reference/rest/v1/change-order-statuses)
* [change\_order\_change\_reasons](https://developers.procore.com/reference/rest/v1/change-order-change-reasons)
* [change\_types](https://developers.procore.com/reference/rest/v1/change-types)
* [checklist/alternative\_response\_sets](https://developers.procore.com/reference/rest/v1/checklists)
* [checklist/item/response\_sets](https://developers.procore.com/reference/rest/v1/checklists) (supports incremental read)
* [checklist/list\_templates](https://developers.procore.com/reference/rest/v1/checklists) (supports incremental read)
* [checklist/responses](https://developers.procore.com/reference/rest/v1/checklists)
* [company/projects](https://developers.procore.com/reference/rest/v1/projects) (supports incremental read)
* [configurable\_field\_sets](https://developers.procore.com/reference/rest/v1/configurable-field-sets)
* [contributing\_behaviors](https://developers.procore.com/reference/rest/v1/incident-filter-options) (supports incremental read)
* [contributing\_conditions](https://developers.procore.com/reference/rest/v1/incident-filter-options) (supports incremental read)
* [currency\_configuration/exchange\_rates](https://developers.procore.com/reference/rest/v1/currency-configuration)
* [custom-fields](https://developers.procore.com/reference/rest/v1/configurable-field-sets)
* [custom\_field\_definitions](https://developers.procore.com/reference/rest/project-fields?version=2.0#list-project-fields)
* [custom\_field\_metadata](https://developers.procore.com/reference/rest/project-fields?version=2.0#list-project-fields)
* [custom\_fields\_sections](https://developers.procore.com/reference/rest/v1/custom-fields-sections)
* [departments](https://developers.procore.com/reference/rest/v1/departments)
* [distribution\_groups](https://developers.procore.com/reference/rest/v1/distribution-groups)
* [equipment\_register](https://developers.procore.com/reference/rest/v2/equipment-register)
* [estimating/bid\_board\_projects](https://developers.procore.com/reference/rest/v2/estimating)
* [estimating/catalogs](https://developers.procore.com/reference/rest/v2/estimating)
* [form\_templates](https://developers.procore.com/reference/rest/v1/form-templates) (supports incremental read)
* [generic\_tools](https://developers.procore.com/reference/rest/v1/correspondences?version=1.0#list-generic-tools)
* [generic\_tools/default\_types](https://developers.procore.com/reference/rest/v1/correspondences?version=1.0#list-generic-tools)
* [gps\_positions](https://developers.procore.com/reference/rest/v1/locations) (supports incremental read)
* [groups](https://developers.procore.com/reference/rest/v1/groups)
* [hazards](https://developers.procore.com/reference/rest/v1/incident-filter-options) (supports incremental read)
* [incidents/action\_types](https://developers.procore.com/reference/rest/v1/incident-picker-options) (supports incremental read)
* [incidents/affliction\_types](https://developers.procore.com/reference/rest/v1/affliction-types) (supports incremental read)
* [incidents/body\_parts](https://developers.procore.com/reference/rest/v1/incident-picker-options)
* [incidents/environmental\_types](https://developers.procore.com/reference/rest/v1/incident-picker-options)
* [incidents/harm\_sources](https://developers.procore.com/reference/rest/v1/harm-sources) (supports incremental read)
* [incidents/injury\_filing\_types](https://developers.procore.com/reference/rest/v1/incident-picker-options)
* [incidents/severity\_levels](https://developers.procore.com/reference/rest/v1/incident-picker-options)
* [incidents/statuses](https://developers.procore.com/reference/rest/v1/incident-picker-options)
* [incidents/work\_activities](https://developers.procore.com/reference/rest/v1/work-activities) (supports incremental read)
* [inspection\_types](https://developers.procore.com/reference/rest/v1/inspection-types)
* [insurances](https://developers.procore.com/reference/rest/v1/company-vendor-insurances)
* [meeting\_templates](https://developers.procore.com/reference/rest/v1/meeting-templates)
* [notification-profiles](https://developers.procore.com/reference/rest/v1/notification-profiles)
* [observation\_types](https://developers.procore.com/reference/rest/v1/observations)
* [offices](https://developers.procore.com/reference/rest/v1/company-offices)
* [operations](https://developers.procore.com/reference/rest/v2/operations)
* [people](https://developers.procore.com/reference/rest/v1/project-users)
* [people/inactive](https://developers.procore.com/reference/rest/v1/project-users)
* [pdf\_template\_configs](https://developers.procore.com/reference/rest/v1/pdf-template-configs)
* [payments/beneficiaries](https://developers.procore.com/reference/rest/v1/payments)
* [payments/early\_pay\_programs](https://developers.procore.com/reference/rest/v1/early-pay-programs)
* [payments/projects](https://developers.procore.com/reference/rest/v1/payments)
* [permission\_templates](https://developers.procore.com/reference/rest/v1/permission-templates)
* [project\_bid\_types](https://developers.procore.com/reference/rest/v1/project-bid-types)
* [project\_owner\_types](https://developers.procore.com/reference/rest/v1/project-owner-types)
* [project\_regions](https://developers.procore.com/reference/rest/v1/project-regions)
* [project\_stages](https://developers.procore.com/reference/rest/v1/project-stages)
* [project\_templates](https://developers.procore.com/reference/rest/v1/project-templates)
* [project\_types](https://developers.procore.com/reference/rest/v1/project-types)
* [projects](https://developers.procore.com/reference/rest/v1/projects) (supports incremental read)
* [programs](https://developers.procore.com/reference/rest/v1/programs)
* [recycle\_bin/action\_plans/plan\_template\_item\_assignees](https://developers.procore.com/reference/rest/v1/action-plans) (supports incremental read)
* [recycle\_bin/action\_plans/plan\_template\_items](https://developers.procore.com/reference/rest/v1/action-plans) (supports incremental read)
* [recycle\_bin/action\_plans/plan\_template\_references](https://developers.procore.com/reference/rest/v1/action-plans) (supports incremental read)
* [recycle\_bin/action\_plans/plan\_template\_sections](https://developers.procore.com/reference/rest/v1/action-plans) (supports incremental read)
* [recycle\_bin/action\_plans/plan\_template\_test\_record\_requests](https://developers.procore.com/reference/rest/v1/action-plans) (supports incremental read)
* [recycle\_bin/action\_plans/plan\_templates](https://developers.procore.com/reference/rest/v1/action-plans) (supports incremental read)
* [recycle\_bin/checklist/list\_templates](https://developers.procore.com/reference/rest/v1/checklists)
* [roles](https://developers.procore.com/reference/rest/v2/roles)
* [schedule/resources](https://developers.procore.com/reference/rest/v1/schedule/resources)
* [settings/permissions](https://developers.procore.com/reference/rest/v1/configurable-field-sets)
* [submittal\_statuses](https://developers.procore.com/reference/rest/v1/submittal-statuses)
* [submittal\_types](https://developers.procore.com/reference/rest/v1/submittal-types)
* [tags](https://developers.procore.com/reference/rest/v1/tags)
* [tax\_codes](https://developers.procore.com/reference/rest/v1/tax-codes)
* [tax\_types](https://developers.procore.com/reference/rest/v1/tax-types)
* [timecard\_time\_types](https://developers.procore.com/reference/rest/v1/timecard-time-types)
* [timesheets/filters/crews](https://developers.procore.com/reference/rest/v1/timesheets)
* [trades](https://developers.procore.com/reference/rest/v1/trades) (supports incremental read)
* [uom\_categories](https://developers.procore.com/reference/rest/v1/uom-categories)
* [uoms](https://developers.procore.com/reference/rest/v1/uoms)
* [users](https://developers.procore.com/reference/rest/v1/company-users) (supports incremental read)
* [users/inactive](https://developers.procore.com/reference/rest/v1/company-users)
* [vendors](https://developers.procore.com/reference/rest/v1/company-vendors) (supports incremental read)
* [vendors/inactive](https://developers.procore.com/reference/rest/v1/company-vendors)
* [webhooks/hooks](https://developers.procore.com/documentation/webhooks)
* [work\_classifications](https://developers.procore.com/reference/rest/v1/work-classifications)
* [workflow\_instances](https://developers.procore.com/reference/rest/v1/workflow-instances?version=1.0)
* [workflows/bulk\_replace\_requests](https://developers.procore.com/reference/rest/v2/workflows)
* [workflows/tools](https://developers.procore.com/reference/rest/v1/correspondences?version=1.0#list-generic-tools)

#### Write objects

* [action\_plans/plan\_types](https://developers.procore.com/reference/rest/v1/action-plans)
* [action\_plans/verification\_methods](https://developers.procore.com/reference/rest/v1/action-plans)
* [app\_configurations](https://developers.procore.com/reference/rest/v1/app-configurations)
* [bim\_levels](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_levels/batch](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_mint\_tokens](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_model\_revision\_plans](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_model\_revision\_plans/batch](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_model\_revision\_viewpoints/batch](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_model\_revisions](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_models](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_plans](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_plans/batch](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_view\_folders](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_viewpoints](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [bim\_viewpoints/batch](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [budget\_view\_snapshots](https://developers.procore.com/reference/rest/v1/budget-views?version=1.0)
* [change\_order\_change\_reasons](https://developers.procore.com/reference/rest/v1/change-order-change-reasons)
* [checklist/item/response\_sets](https://developers.procore.com/reference/rest/v1/checklists)
* [checklist/list\_templates](https://developers.procore.com/reference/rest/v1/checklists)
* [checklist/responses](https://developers.procore.com/reference/rest/v1/checklists)
* [company/projects](https://developers.procore.com/reference/rest/v1/projects)
* [configurable\_field\_sets](https://developers.procore.com/reference/rest/v1/configurable-field-sets)
* [contributing\_behaviors](https://developers.procore.com/reference/rest/v1/incident-filter-options)
* [contributing\_conditions](https://developers.procore.com/reference/rest/v1/incident-filter-options)
* [contexts](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [contexts/get\_or\_create](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [coordination\_issues](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [coordination\_issues/bulk\_delete](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [currency\_configuration](https://developers.procore.com/reference/rest/v1/currency-configuration)
* [currency\_configuration/exchange\_rates](https://developers.procore.com/reference/rest/v1/currency-configuration)
* [custom-fields](https://developers.procore.com/reference/rest/v1/configurable-field-sets)
* [custom\_field\_metadata](https://developers.procore.com/reference/rest/project-fields?version=2.0#list-project-fields)
* [custom\_fields\_sections](https://developers.procore.com/reference/rest/v1/custom-fields-sections)
* [departments](https://developers.procore.com/reference/rest/v1/departments)
* [equipment\_register](https://developers.procore.com/reference/rest/v2/equipment-register)
* [equipment\_register/associate](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [equipment\_register\_categories](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [equipment\_register\_makes](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [equipment\_register\_models](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [equipment\_register/statuses](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [equipment\_register\_types](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [estimating/catalogs](https://developers.procore.com/reference/rest/v2/estimating)
* [files](https://developers.procore.com/reference/rest/v1/project-folders-and-files)
* [form\_templates](https://developers.procore.com/reference/rest/v1/form-templates)
* [generic\_tools](https://developers.procore.com/reference/rest/v1/correspondences?version=1.0#list-generic-tools)
* [gps\_positions](https://developers.procore.com/reference/rest/v1/locations)
* [groups](https://developers.procore.com/reference/rest/v1/groups)
* [hazards](https://developers.procore.com/reference/rest/v1/incident-filter-options)
* [incidents/action\_types](https://developers.procore.com/reference/rest/v1/incident-picker-options)
* [incidents/affliction\_types](https://developers.procore.com/reference/rest/v1/affliction-types)
* [incidents/harm\_sources](https://developers.procore.com/reference/rest/v1/harm-sources)
* [incidents/work\_activities](https://developers.procore.com/reference/rest/v1/work-activities)
* [inspection\_types](https://developers.procore.com/reference/rest/v1/inspection-types)
* [installation\_requests](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [insurances](https://developers.procore.com/reference/rest/v1/company-vendor-insurances)
* [job-titles](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [meeting\_categories](https://developers.procore.com/reference/rest/v1/meeting-categories)
* [nested\_bim\_view\_folders](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [nested\_bim\_view\_folders/batch](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [observations/items](https://developers.procore.com/reference/rest/v1/observations)
* [offices](https://developers.procore.com/reference/rest/v1/company-offices)
* [people](https://developers.procore.com/reference/rest/v1/project-users)
* [pdf\_template\_configs](https://developers.procore.com/reference/rest/v1/pdf-template-configs)
* [permission\_templates](https://developers.procore.com/reference/rest/v1/permission-templates)
* [payments/early\_pay\_programs](https://developers.procore.com/reference/rest/v1/early-pay-programs)
* [programs](https://developers.procore.com/reference/rest/v1/programs)
* [project\_bid\_types](https://developers.procore.com/reference/rest/v1/project-bid-types)
* [project\_owner\_types](https://developers.procore.com/reference/rest/v1/project-owner-types)
* [project\_regions](https://developers.procore.com/reference/rest/v1/project-regions)
* [project\_stages](https://developers.procore.com/reference/rest/v1/project-stages)
* [project\_types](https://developers.procore.com/reference/rest/v1/project-types)
* [projects](https://developers.procore.com/reference/rest/v1/projects)
* [punch\_item\_types](https://developers.procore.com/reference/rest/v1/punch-item-types)
* [punch\_items](https://developers.procore.com/reference/rest/v1/punch-items)
* [recycle\_bin/action\_plans/plan\_template\_item\_assignees](https://developers.procore.com/reference/rest/v1/action-plans)
* [recycle\_bin/action\_plans/plan\_template\_items](https://developers.procore.com/reference/rest/v1/action-plans)
* [recycle\_bin/action\_plans/plan\_template\_references](https://developers.procore.com/reference/rest/v1/action-plans)
* [recycle\_bin/action\_plans/plan\_template\_sections](https://developers.procore.com/reference/rest/v1/action-plans)
* [recycle\_bin/action\_plans/plan\_template\_test\_record\_requests](https://developers.procore.com/reference/rest/v1/action-plans)
* [recycle\_bin/action\_plans/plan\_templates](https://developers.procore.com/reference/rest/v1/action-plans)
* [recycle\_bin/action\_plans/plan\_template\_references/bulk\_create](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [rounding\_configuration](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [roles](https://developers.procore.com/reference/rest/v2/roles)
* [support\_pins](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [tags](https://developers.procore.com/reference/rest/v1/tags)
* [tax\_codes](https://developers.procore.com/reference/rest/v1/tax-codes)
* [tax\_types](https://developers.procore.com/reference/rest/v1/tax-types)
* [timecard\_entries](https://developers.procore.com/reference/rest/v1/timecard-entries)
* [timesheets/timesheet\_to\_budget\_configuration](https://developers.procore.com/reference/rest/docs/rest-api-overview)
* [trades](https://developers.procore.com/reference/rest/v1/trades)
* [uoms](https://developers.procore.com/reference/rest/v1/uoms)
* [uploads](https://developers.procore.com/reference/rest/document-uploads?version=2.0)
* [users](https://developers.procore.com/reference/rest/v1/company-users)
* [vendors](https://developers.procore.com/reference/rest/v1/company-vendors)
* [webhooks/hooks](https://developers.procore.com/documentation/webhooks)
* [work\_classifications](https://developers.procore.com/reference/rest/v1/work-classifications)
* [workflows/bulk\_replace\_requests](https://developers.procore.com/reference/rest/v2/workflows)

### Example integration

For an example manifest file of a Procore integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/procore/amp.yaml).

## Before you get started

To integrate Procore with Ampersand, you will need a [Procore developer account](https://developers.procore.com/).

Once your account is created, you'll need to create an app in Procore, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Procore app

Here's how you can sign up for a Procore account:

1. Sign in to the [Procore developer portal](https://developers.procore.com/).
2. Create a new OAuth 2.0 application.
3. Add the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
4. Save the app and copy the Client ID and Client Secret.

### Add your Procore app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Choose the project where you want to integrate Procore.

   <img alt="Ampersand Project" />

3. Navigate to the **Provider Apps** section.

4. Select *Procore* from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from Procore into the respective fields in Ampersand.

   <img alt="Dashboard" />

6. Click **Save Changes**.

## Using the connector

To start integrating with Procore:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/procore/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using [Read Actions](/read-actions) or [Write Actions](/write-actions), create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component prompts the customer for their Procore authorization and company ID (the numeric segment in their Procore URL, for example `4283186` in `https://procore.com/4283186/company/home/thumbnail`).
* Start using the connector.
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Productboard
Source: https://docs.ampersand.ai/provider-guides/productBoard



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.productboard.com`.

## Before You Get Started

To connect Productboard with Ampersand, you will need [a Productboard Account](https://app.productboard.com/register).

Once your account is created, you'll need to create an app in Productboard and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Productboard Account

Here's how you can sign up for a Productboard account:

* Go to the [Productboard Sign Up page](https://app.productboard.com/register).
* Sign up using your preferred method.

### Creating a Productboard App

Follow the steps below to create a Productboard app and add the Ampersand redirect URL.

1. Log in to your [Productboard](https://app.productboard.com/login) account.

2. Then visit [My OAuth2 Applications](https://app.productboard.com/oauth2/applications) to create a new app.

3. Click **New OAuth2 Application**.

4. Enter the **Name** of the OAuth Application.

5. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` in the **Redirect URI** section.

6. Choose the **scopes** that are applicable to your application.

   <img alt="Productboard App Creation" />

7. Add in other details like the tagline, description & the icon for the OAuth Application.

8. Click **Create Application**.

## Add Your Productboard App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project in which you want to create a Productboard integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Productboard* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Ampersand Integration" />


# Pylon
Source: https://docs.ampersand.ai/provider-guides/pylon



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `issues` currently. For all other objects, a full read of the Pylon instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.usepylon.com`.

> **Important Note on Issues Backfill**: The `issues` object has a 30-day limitation for historic backfill. To avoid timezone or timing issues, we recommend setting your backfill period to 29 days or less when syncing issues data.

### Supported Objects

The Pylon connector supports reading from the following objects:

* [accounts](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/accounts#get-accounts)
* [contacts](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/contacts#get-contacts)
* [issues](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/issues#get-issues)
* [knowledge-bases](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/knowledge-base#get-knowledge-bases)
* [tags](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/tags#get-tags)
* [teams](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/teams#get-teams)
* [ticket-forms](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/ticket-forms#get-ticket-forms)
* [user-roles](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/user-roles)
* [users](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/users#get-users)

The Pylon connector supports writing to the following objects:

* [attachments](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/attachments)
* [accounts](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/accounts#post-accounts)
* [contacts](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/contacts#post-contacts)
* [issues](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/issues#post-issues)
* [tasks](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/tasks-and-projects#post-tasks)
* [teams](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/teams#post-teams)
* [projects](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/projects#post-projects)
* [tags](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/tags#post-tags)

### Example integration

For an example manifest file of a Pylon integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/pylon/amp.yaml).

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Pylon:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/pylon/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API Key.
* Start making [Read Actions](/read-actions), [Write Actions](/write-actions), and [Proxy Calls](/proxy-actions). Ampersand will automatically attach the required authentication headers supplied by the customer. Please note that this connector's base URL is `https://api.usepylon.com`.

## API documentation

For more detailed information about Pylon API, refer to the [Pylon API documentation](https://docs.usepylon.com/pylon-docs/developer/api).


# QuickBooks
Source: https://docs.ampersand.ai/provider-guides/quickbooks



## What's Supported

QuickBooks is available as two connectors:

| Environment | Provider name | Base URL |
| - | - | - |
| Production | `quickbooks` | `https://quickbooks.api.intuit.com` |
| Sandbox | `quickbooksSandbox` | `https://sandbox-quickbooks.api.intuit.com` |

Both connectors share the same supported actions, objects, and OAuth2 configuration — the only difference is the base URL used for API calls.
Use the **sandbox connector** during development and testing with your [QuickBooks sandbox company](https://developer.intuit.com/app/developer/qbo/docs/develop/sandboxes), and switch to the **production connector** when going live.

### Supported actions

* [Read Actions](/read-actions), including full historic backfill and incremental reads.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://quickbooks.api.intuit.com` (production) or `https://sandbox-quickbooks.api.intuit.com` (sandbox).

### Supported Objects

The QuickBooks connector supports reading from and writing to the following objects:

* [account](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account#query-an-account)
* [attachable](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/attachable#query-an-attachable)
* [bill](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/bill#query-a-bill)
* [billPayment](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/billpayment#query-a-billpayment)
* [budget](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/budget#query-a-budget)
* [class](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/class#query-a-class)
* [companyCurrency](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/companycurrency#query-a-companycurrency)
* [creditMemo](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/creditmemo#query-a-credit-memo)
* [creditCardPayment](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/creditcardpayment#query-a-creditcardpayment)
* [customer](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/customer#query-a-customer)
* [department](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/department#query-a-department)
* [deposit](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/deposit#query-a-deposit)
* [employee](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/employee#query-an-employee)
* [estimate](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/estimate#query-an-estimate)
* [invoice](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/invoice#query-an-invoice)
* [item](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/item#query-an-item)
* [journalCode](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/journalcode#query-a-journalcode)
* [journalEntry](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/journalentry#query-a-journalentry)
* [payment](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/payment#query-a-payment)
* [paymentMethod](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/paymentmethod#query-a-paymentmethod)
* [purchase](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/purchase#query-a-purchase)
* [purchaseOrder](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/purchaseorder#query-a-purchaseorder)
* [recurringTransaction](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/recurringtransaction#query-a-recurring-transaction)
* [refundReceipt](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/refundreceipt#query-a-refundreceipt)
* [salesReceipt](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/salesreceipt#query-a-salesreceipt)
* [taxAgency](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/taxagency#query-a-taxagency)
* [term](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/term#query-a-term)
* [timeActivity](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/timeactivity#query-a-timeactivity-object)
* [transfer](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/transfer#query-a-transfer)
* [vendor](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/vendor#query-a-vendor)
* [vendorCredit](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/vendorcredit#query-a-vendorcredit)

The QuickBooks connector supports reading from the following objects (read-only):

* [customerType](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/customertype#query-a-customertype)
* [exchangeRate](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/exchangerate#query-exchangerate-objects)
* [reimburseCharge](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/reimbursecharge#query-a-reimbursecharge)
* [taxCode](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/taxcode#query-a-taxcode)
* [taxPayment](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/taxpayment#query-taxpayment)
* [taxRate](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/taxrate#query-a-taxrate)

The QuickBooks connector supports writing to the following objects (write-only):

* [inventoryadjustment](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/inventoryadjustment#create-an-inventory-adjustment)
* [taxservice/taxcode](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/taxservice#create-a-taxservice)

### Example Integration

For example manifest files, visit our samples repo on Github:

* [Production (quickbooks)](https://github.com/amp-labs/samples/blob/main/quickbooks/amp.yaml)
* [Sandbox (quickbooksSandbox)](https://github.com/amp-labs/samples/blob/main/quickbooks/sandbox/amp.yaml)

## Before you get started

You'll need a QuickBooks account and will need to create a QuickBooks app to obtain the necessary OAuth2 credentials.

### Creating a QuickBooks App

1. Go to the [Intuit Developer Dashboard](https://developer.intuit.com/)
2. Sign in with your Intuit account or create one if needed
3. Click **Create an app**
4. Choose **QuickBooks Online Accounting API**
5. Provide your app details:
   * **App name**: Choose a descriptive name for your app
   * **Description**: Brief description of your integration
6. Click **Create app**
7. Once created, navigate to the **Keys & OAuth** tab
8. Note down your credentials for both environments:
   * **Development (Sandbox)**: Client ID and Client Secret listed under the **Development** section — use these with the `quickbooksSandbox` provider.
   * **Production**: Client ID and Client Secret listed under the **Production** section — use these with the `quickbooks` provider.
9. Under **Redirect URIs**, add: `https://api.withampersand.com/callbacks/v1/oauth`

Common scopes include:

* `com.intuit.quickbooks.accounting` - Full access to accounting data
* `com.intuit.quickbooks.payment` - Access to payment data

For details on scopes, refer to the [QuickBooks Scopes](https://developer.intuit.com/app/developer/qbo/docs/learn/scopes) guide.

### Add your QuickBooks app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a QuickBooks integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *QuickBooks* from the **Provider** list, or *QuickBooks Sandbox* if you are setting up a development integration.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Enter the **scopes** required for your application in **Scopes**.

   <img alt="Alt text" />

7. Click **Save Changes**.

## Using the connector

To start integrating with QuickBooks:

* Create a manifest file as shown in the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

<Note>
  QuickBooks API returns XML responses by default. To receive JSON responses, make sure to set the `Accept` header to `application/json` in your proxy API calls.
</Note>

## API documentation

* [QuickBooks API](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account#the-account-object)


# Ramp
Source: https://docs.ampersand.ai/provider-guides/ramp



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Incremental reading is supported for the objects marked in the table below, a full read of the Ramp instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.ramp.com`.

### Supported objects

The Ramp connector supports the following objects:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Incremental read</th>
      </tr>
    </thead>
  </table>
</div>

### Example integration

For an example manifest file of a Ramp integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/ramp/amp.yaml).

## Before you get started

To connect Ramp with Ampersand, you will need [a Ramp account](https://app.ramp.com).

Once your account is created, you'll need to create an app in your Ramp portal, configure the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Ramp account

To create an account for your organization, you need to apply here [Ramp Support](https://app.ramp.com/sign-up). An active account is required to log into your portal.

### Creating a Ramp app

Once your Ramp account is set up, you can follow the steps below to create a Ramp app:

1. Log in to your [Ramp Portal](https://app.ramp.com/sign-in).

2. Navigate to `https://app.ramp.com/ramp-developer`.

3. Click the **New app**.

4. Enter the following details to register your **Oauth** app:
   1. **App Name**: The name of your app.

5. Click the **Create App.**

6. Add **Redirect URIs**: `https://api.withampersand.com/callbacks/v1/oauth`

7. Select the scopes for your application. Ramp will authorize access to the selected scopes for your application. Make sure to select a scope for every object your integration reads from or writes to — for example, `transactions:read` for reading `transactions`, and `bills:write` for writing `bills`.

<img alt="Ramp App Creation" />

You will find the **Client ID** and **Client Secret** in the app details. Note these credentials, as you will need them to connect your app to Ampersand.

### Add your Ramp app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Ramp integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Ramp** from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in *Ramp*.

   <img alt="Ampersand Integration" />

## Using the connector

To start integrating with Ramp:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Rebilly
Source: https://docs.ampersand.ai/provider-guides/rebilly



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.rebilly.com`.

### Example integration

To define an integration for Rebilly, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: rebilly-integration
    displayName: My Rebilly Integration
    provider: rebilly
    proxy:
      enabled: true
```

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Rebilly:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.rebilly.com`.

## Creating an API key for Rebilly

[Click here](https://www.rebilly.com/catalog/all/section/authentication/manage-api-keys) for more information about generating an API key for Rebilly. The UI components will display this link, so that your users can successfully create API keys.


# Recurly
Source: https://docs.ampersand.ai/provider-guides/recurly



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental reading is only supported for `accounts`, `acquisitions`, `subscriptions`, `items`, `plans`, `add_ons`, `measured_units`, `coupons`, `invoices`, `line_items`, `credit_payments`, `transactions`, `custom_field_definitions` and `shipping_methods`. For all other objects, a full read of the Recurly instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://v3.recurly.com`.

### Supported objects

The Recurly connector supports reading from the following objects:

* [accounts](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_accounts)
* [acquisitions](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_account_acquisition)
* [add\_ons](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_add_ons)
* [business\_entities](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_business_entities)
* [coupons](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_coupons)
* [credit\_payments](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_credit_payments)
* [custom\_field\_definitions](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_custom_field_definitions)
* [dunning\_campaigns](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_dunning_campaigns)
* [external\_invoices](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_external_invoices)
* [external\_products](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_external_products)
* [external\_subscriptions](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_external_subscriptions)
* [general\_ledger\_accounts](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_general_ledger_accounts)
* [gift\_cards](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_gift_cards)
* [invoices](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_invoices)
* [items](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_items)
* [line\_items](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_line_items)
* [measured\_units](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_measured_unit)
* [performance\_obligations](https://recurly.com/developers/api/v2021-02-25/index.html#operation/get_performance_obligations)
* [plans](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_plans)
* [price\_segments](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_price_segments)
* [shipping\_methods](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_shipping_methods)
* [sites](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_sites)
* [subscriptions](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_subscriptions)
* [transactions](https://recurly.com/developers/api/v2021-02-25/index.html#operation/list_transactions)

The Recurly connector supports writing to the following objects:

* [accounts](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_account)
* [coupons](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_coupon)
* [external\_products](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_external_product)
* [external\_subscriptions](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_external_subscription)
* [general\_ledger\_accounts](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_general_ledger_account)
* [gift\_cards](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_gift_card)
* [items](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_item)
* [measured\_units](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_measured_unit)
* [plans](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_plan)
* [shipping\_methods](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_shipping_method)
* [subscriptions](https://recurly.com/developers/api/v2021-02-25/index.html#operation/create_subscription)

### Example integration

For an example manifest file of a Recurly integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/recurly/amp.yaml).

## Before you get started

To integrate Recurly with Ampersand, you will need a Recurly API Key.

### Creating a Recurly API key

1. Log in to your [Recurly account](https://app.recurly.com/).
2. Navigate to **Integrations** > **API Credentials**.
3. Click **Add Private API Key**.
4. Provide a name for your API key and select the appropriate permissions.
5. Click **Save** to generate the key.
6. Copy and securely store the API key.

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Recurly:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password. Enter the API key as the username and leave the password field blank.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Reply
Source: https://docs.ampersand.ai/provider-guides/reply



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.reply.io`.

### Example integration

To define an integration for Reply, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: replyIntegration
    displayName: My Reply Integration
    provider: reply
    proxy:
      enabled: true
```

## Before you get started

To connect Reply with Ampersand, you will need a [Reply account](https://reply.io/). Reply offers a free trial that includes API access.

### Creating an API key for Reply

1. Sign in to your [Reply account](https://run.reply.io).
2. Go to **Settings**, then select **API keys**.
3. Click **Create My API key** and enter a descriptive name for the key.
4. Leave the expiration date empty for a key that never expires, or set a date to make the key expire.
5. Set the permission sliders to cover the scopes that your integration needs. The sliders default to **None**, and a key created without permissions returns `401 Unauthorized` on every request.
6. Click **Create key**, then copy the key.

<img alt="Creating a Reply API key" />

[Click here](https://docs.reply.io/api-reference/authentication) for more information about generating an API key for Reply. The UI components will display this link, so that your users can successfully create API keys.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Reply:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by API Key auth. Please note that this connector's base URL is `https://api.reply.io`.


# RevenueCat
Source: https://docs.ampersand.ai/provider-guides/revenuecat



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read. Incremental read is supported for `apps`, `customers`, `entitlements`, `integrations_webhooks`, `metrics_overview`, `offerings`, `products`, and `purchases` when a time window is used; for `subscriptions`, a full read is done per scheduled read.
* [Write Actions](/write-actions) (create/update).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.revenuecat.com`.
* Subscribe Actions are not currently supported.

### Supported objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/App">apps</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/Customer">customers</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/Entitlement">entitlements</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/Integration">integrations\_webhooks</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/Charts-and-Metrics">metrics\_overview</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/Offering">offerings</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/Product">products</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/Purchase">purchases</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.revenuecat.com/docs/api-v2#tag/Subscription">subscriptions</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

### Notes and limitations

* **Write support**: `apps`, `customers`, `entitlements`, `integrations_webhooks`, `offerings`, and `products` support create, update, and delete. Single-record operations only (no bulk write).
* **Read-only objects**: `subscriptions`, `purchases`, and `metrics_overview` are read-only (store-derived or aggregated data).
* **Incremental read**: When a time window is used, incremental read is supported for all objects except `subscriptions`, which uses a full read per schedule.
* This connector uses the [RevenueCat API v2](https://www.revenuecat.com/docs/api-v2) only; v1 API keys are not valid.

### Example integration

To define an integration for RevenueCat, use a manifest file (`amp.yaml`). For a complete example, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/revenuecat/amp.yaml).

## Before you get started

To connect *RevenueCat* with *Ampersand*, you will need [a RevenueCat account](https://www.revenuecat.com/).

Once your account is created, you'll need to obtain the following from your project:

* **API Key** — Secret API key (v2) for server-side use. The connector sends it as `Authorization: Bearer <key>`.
* **Project ID** — Your project identifier (typically starts with `proj_`). This is required as metadata when using the connector.

Your customers enter these when they install the integration via the InstallIntegration UI.

### Create a RevenueCat account

Here's how you can sign up for a RevenueCat account:

* Sign up at [RevenueCat](https://www.revenuecat.com/) and create a project.

### Obtain API credentials

Follow the steps below to obtain your Secret API key (v2) and Project ID from RevenueCat:

1. Log in to the [RevenueCat dashboard](https://app.revenuecat.com).
2. Select your project.
3. **Project ID**: Go to **Project settings** → **General**. Copy the **Project ID** (it typically starts with `proj_`).
4. **Secret API key (v2)**: Go to **API keys**. Click **+ New Secret API key**, choose **V2**, set the desired permissions, then **Generate**. Copy the secret key.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with RevenueCat:

* Create a manifest file; see [Example integration](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API key and Project ID.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# RingCentral
Source: https://docs.ampersand.ai/provider-guides/ringCentral



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `webinars`, `webinar/recordings`,`webinar/company/recordings`, `call-log`,`call-log-sync`,`message-sync` ,`message-store`, `a2p-sms/batches`, and `a2p-sms/messages` only. For all other objects, a full read of the RingCentral instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://platform.ringcentral.com`.

### Supported Objects

The RingCentral connector supports writing to and reading from the following objects:

* [caller-blocking/phone-numbers](https://developers.ringcentral.com/api-reference/Call-Blocking/listBlockedAllowedNumbers)
* [forwarding-number](https://developers.ringcentral.com/api-reference/Call-Forwarding/listForwardingNumbers)
* [answering-rule](https://developers.ringcentral.com/api-reference/Call-Handling-Rules/listAnsweringRules)
* [company-answering-rule](https://developers.ringcentral.com/api-reference/Call-Handling-Rules/listCompanyAnsweringRules)
* [comm-handling/states](https://developers.ringcentral.com/api-reference/States/listCicStates)
* [comm-handling/voice/state-rules](https://developers.ringcentral.com/api-reference/State-based-Rules/listVoiceStateBasedRules)
* [comm-handling/voice/interaction-rules](https://developers.ringcentral.com/api-reference/Interaction-Rules/listVoiceInteractionRules)
* [comm-handling/voice/forwarding-targets](https://developers.ringcentral.com/api-reference/Forwarding-Targets/listExtensionsUsingForwardingDeviceTarget)
* [call-flip-numbers](https://developers.ringcentral.com/api-reference/Call-Flip/readCallFlipSettings)
* [call-monitoring-groups](https://developers.ringcentral.com/api-reference/Call-Monitoring-Groups/listCallMonitoringGroups)
* [call-queues](https://developers.ringcentral.com/api-reference/Call-Queues/listCallQueues)
* [dictionary/greeting](https://developers.ringcentral.com/api-reference/Greetings/listStandardGreetings)
* [custom-greetings](https://developers.ringcentral.com/api-reference/Greetings/createCustomUserGreeting)
* [ivr-prompts](https://developers.ringcentral.com/api-reference/IVR/listIvrPrompts)
* [ivr-menus](https://developers.ringcentral.com/api-reference/IVR/readIVRMenuList)
* [message-store](https://developers.ringcentral.com/api-reference/Message-Store/listMessages)
* [a2p-sms/batches](https://developers.ringcentral.com/api-reference/High-Volume-SMS/listA2PBatches)
* [message-store-templates](https://developers.ringcentral.com/api-reference/SMS-Templates/listCompanyMessageTemplates)
* [user-message-store-templates](https://developers.ringcentral.com/api-reference/SMS-Templates/createUserMessageTemplate)
* [sms/consents](https://developers.ringcentral.com/api-reference/SMS-Consents/listSmsConsentRecords)
* [events](https://developers.ringcentral.com/api-reference/Calendar-Events/readGlipEventsNew)
* [conversations](https://developers.ringcentral.com/api-reference/Conversations/createGlipConversationNew)
* [data-export](https://developers.ringcentral.com/api-reference/Compliance-Exports/listDataExportTasksNew)
* [webhooks](https://developers.ringcentral.com/api-reference/Incoming-Webhooks/listGlipGroupWebhooksNew)
* [teams](https://developers.ringcentral.com/api-reference/Teams/listGlipTeamsNew)
* [webinars](https://developers.ringcentral.com/api-reference/Webinars-and-Sessions/rcwConfigCreateWebinar)
* [webinar/recordings](https://developers.ringcentral.com/api-reference/Historical-Recordings/rcwHistoryListRecordings)
* [webinar/company/recordings](https://developers.ringcentral.com/api-reference/Historical-Recordings/rcwHistoryAdminListRecordings)
* [webinar/subscriptions](https://developers.ringcentral.com/api-reference/Webinar-Subscriptions/rcwN11sListSubscriptions)
* [custom-fields](https://developers.ringcentral.com/api-reference/Custom-Fields/listCustomFields)
* [sites](https://developers.ringcentral.com/api-reference/Multi-Site/listSites)
* [accounts/phone-numbers](https://developers.ringcentral.com/api-reference/Phone-Numbers/listAccountPhoneNumbersV2)
* [account/presence](https://developers.ringcentral.com/api-reference/Presence/readAccountPresence)
* [call-queue-presence](https://developers.ringcentral.com/api-reference/Presence/readExtensionCallQueuePresence)
* [emergency-locations](https://developers.ringcentral.com/api-reference/Automatic-Location-Updates/listEmergencyLocations)
* [user/emergency-locations](https://developers.ringcentral.com/api-reference/Automatic-Location-Updates/getExtensionEmergencyLocations)
* [users](https://developers.ringcentral.com/api-reference/Automatic-Location-Updates/listAutomaticLocationUpdatesUsers)
* [wireless-points](https://developers.ringcentral.com/api-reference/Automatic-Location-Updates/listWirelessPoints)
* [networks](https://developers.ringcentral.com/api-reference/Automatic-Location-Updates/listNetworks)
* [devices](https://developers.ringcentral.com/api-reference/Automatic-Location-Updates/listDevicesAutomaticLocationUpdates)
* [switches](https://developers.ringcentral.com/api-reference/Automatic-Location-Updates/listAccountSwitches)
* [extension/devices](https://developers.ringcentral.com/api-reference/Devices/listExtensionDevices)
* [extensions](https://developers.ringcentral.com/api-reference/Extensions/listExtensions)
* [scim/users](https://developers.ringcentral.com/api-reference/SCIM/scimSearchViaGet2)
* [direct-routing/users](https://developers.ringcentral.com/api-reference/MS-Teams-Direct-Routing/listTeamsUsers)
* [contacts](https://developers.ringcentral.com/api-reference/External-Contacts/listContacts)
* [favorite/contacts](https://developers.ringcentral.com/api-reference/External-Contacts/listFavoriteContacts)
* [user/assigned-role](https://developers.ringcentral.com/api-reference/Role-Management/listUserAssignedRoles)
* [company/user-role](https://developers.ringcentral.com/api-reference/Role-Management/listUserRoles)
* [assignable-roles](https://developers.ringcentral.com/api-reference/Role-Management/listOfAvailableForAssigningRoles)
* [administered-sites](https://developers.ringcentral.com/api-reference/Site-Administration/listAdministeredSites)
* [subscriptions](https://developers.ringcentral.com/api-reference/Subscriptions/listSubscriptions)

The RingCentral connector supports reading only from the following objects:

* [call-log](https://developers.ringcentral.com/api-reference/Call-Log/readUserCallLog)
* [active-calls](https://developers.ringcentral.com/api-reference/Call-Log/listCompanyActiveCalls)
* [company-call-log](https://developers.ringcentral.com/api-reference/Call-Log/readCompanyCallLog)
* [company-active-calls](https://developers.ringcentral.com/api-reference/Call-Log/listCompanyActiveCalls)
* [call-log-sync](https://developers.ringcentral.com/api-reference/Call-Log/syncUserCallLog)
* [company-call-log-sync](https://developers.ringcentral.com/api-reference/Call-Log/syncAccountCallLog)
* [call-log-extract-sync](https://developers.ringcentral.com/api-reference/Call-Log/extractSyncAccountCallLog)
* [fax-cover-page](https://developers.ringcentral.com/api-reference/Fax/listFaxCoverPages)
* [message-sync](https://developers.ringcentral.com/api-reference/Message-Store/syncMessages)
* [a2p-sms/messages](https://developers.ringcentral.com/api-reference/High-Volume-SMS/listA2PSMS)
* [sms-registration-brands](https://developers.ringcentral.com/api-reference/SMS-Brands-Campaigns/listAllTcrBrands)
* [chats](https://developers.ringcentral.com/api-reference/Chats/listGlipChatsNew)
* [recent/chats](https://developers.ringcentral.com/api-reference/Chats/listRecentChatsNew)
* [favorites](https://developers.ringcentral.com/api-reference/Chats/listFavoriteChatsNew)
* [delegators](https://developers.ringcentral.com/api-reference/Delegation-Management/rcvListDelegators)
* [meetings](https://developers.ringcentral.com/api-reference/Meetings-History/listAccountMeetings)
* [history/meetings](https://developers.ringcentral.com/api-reference/Meetings-History/listVideoMeetings)
* [recordings](https://developers.ringcentral.com/api-reference/Meeting-Recordings/getAccountRecordings)
* [extension-recordings](https://developers.ringcentral.com/api-reference/Meeting-Recordings/getExtensionRecordings)
* [configuration/sessions](https://developers.ringcentral.com/api-reference/Webinars-and-Sessions/rcwConfigListAllSessions)
* [company/sessions](https://developers.ringcentral.com/api-reference/Webinars-and-Sessions/rcwConfigListAllCompanySessions)
* [extension/phone-number](https://developers.ringcentral.com/api-reference/Phone-Numbers/listExtensionPhoneNumbers)
* [company/phone-number](https://developers.ringcentral.com/api-reference/Phone-Numbers/listAccountPhoneNumbers)
* [languages](https://developers.ringcentral.com/api-reference/Regional-Settings/listLanguages)
* [countries](https://developers.ringcentral.com/api-reference/Regional-Settings/listCountries)
* [locations](https://developers.ringcentral.com/api-reference/Regional-Settings/listLocations)
* [states](https://developers.ringcentral.com/api-reference/Regional-Settings/listStates)
* [timezones](https://developers.ringcentral.com/api-reference/Regional-Settings/listTimezones)
* [permissions](https://developers.ringcentral.com/api-reference/User-Permissions/listPermissions)
* [permission-category](https://developers.ringcentral.com/api-reference/User-Permissions/listPermissionCategories)
* [extension/grant](https://developers.ringcentral.com/api-reference/User-Settings/listExtensionGrants)
* [user/features](https://developers.ringcentral.com/api-reference/User-Settings/readExtensionFeatures)
* [user/templates](https://developers.ringcentral.com/api-reference/Extensions/listUserTemplates)
* [resoureTpes](https://developers.ringcentral.com/api-reference/SCIM/scimListResourceTypes2)
* [schemas](https://developers.ringcentral.com/api-reference/SCIM/scimListSchemas2)
* [directory/entries](https://developers.ringcentral.com/api-reference/Internal-Contacts/listDirectoryEntries)
* [directory/federation](https://developers.ringcentral.com/api-reference/Internal-Contacts/readDirectoryFederation)
* [company/assigned-role](https://developers.ringcentral.com/api-reference/Role-Management/listAssignedRoles)
* [user-role](https://developers.ringcentral.com/api-reference/Role-Management/listStandardUserRole)

The RingCentral connector supports writing only to the following objects:

* [telephony/call-out](https://developers.ringcentral.com/api-reference/Call-Control/createCallOutCallSession)
* [client-info/sip-provision](https://developers.ringcentral.com/api-reference/Device-SIP-Registration/createSIPRegistration)
* [ring-out](https://developers.ringcentral.com/api-reference/RingOut/createRingOutCall)
* [fax](https://developers.ringcentral.com/api-reference/Fax/createFaxMessage)
* [message-store-report](https://developers.ringcentral.com/api-reference/Message-Exports/createMessageStoreReport)
* [company-pager](https://developers.ringcentral.com/api-reference/Pager-Messages/createInternalTextMessage)
* [sms](https://developers.ringcentral.com/api-reference/SMS/createSMSMessage)
* [mms](https://developers.ringcentral.com/api-reference/SMS/createMMS)
* [adaptive-cards](https://developers.ringcentral.com/api-reference/Adaptive-Cards/updateGlipAdaptiveCardNew)
* [bridges](https://developers.ringcentral.com/api-reference/Bridge-Management/createBridge)

### Example integration

For an example manifest file of a RingCentral integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/ringcentral/amp.yaml).

## Before You Get Started

To connect RingCentral with Ampersand, you will need [a RingCentral Developer Account](https://developers.ringcentral.com/sign-up).

Once your account is created, you'll need to create an app in RingCentral, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a RingCentral Account

Here's how you can sign up for a RingCentral account:

* Go to the [RingCentral Sign Up page](https://developers.ringcentral.com/sign-up).
* Choose your preferred environment and sign up using your preferred method and verify your email.

### Creating a RingCentral App

Follow the steps below to create a RingCentral app and add the Ampersand redirect URL.

1. Log in to your [RingCentral Developer](https://developers.ringcentral.com/login) account.

2. Click **Console** and then select **Register App** in the **Apps** section.

3. Select the **App Type**: Rest API App and click **Next** Button.

4. Enter the **App Name**, **App Description**.

5. Choose **3-legged OAuth flow authorization code** in the Auth section.

6. Enter callback URI as **[https://api.withampersand.com/callbacks/v1/oauth](https://api.withampersand.com/callbacks/v1/oauth)** in the **OAuth Redirect URI** field.

7. For the **Issue refresh tokens?** Select **Yes** to enable refresh token issuance or **No** to disable it, allowing users to maintain their session without re-authentication.

8. For the **Application Scopes** in the **Security** section, select the required scopes.

9. For the question **Who will be authorized to access your app?**, choose 'Public' to make the app accessible to all RingCentral customers or 'Private' to restrict access to the same RingCentral account.

10. Click **Create**.

<img alt="RingCentral OAuth Creation" />

## Add Your RingCentral App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a RingCentral integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select RingCentral from the **Provider** list.

5. Enter the previously obtained Client ID in the **Client ID** field and the Client Secret in the **Client Secret** field.

   <img alt="Ampersand Integration" />

## Using the connector

To start integrating with RingCentral:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://platform.ringcentral.com`.


# Sage Intacct
Source: https://docs.ampersand.ai/provider-guides/sageIntacct



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Sage Intacct instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.intacct.com`.

### Supported objects

The Sage Intacct connector supports reading and writing from the following objects:

* [accounts-payable/account-label](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.account-label/tag/Account-labels/#tag/Account-labels/operation/list-accounts-payable-account-label)
* [accounts-payable/adjustment](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.adjustment/tag/Adjustments/#tag/Adjustments/operation/list-accounts-payable-adjustment)
* [accounts-payable/adjustment-line](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.adjustment-line/tag/Adjustment-lines/#tag/Adjustment-lines/operation/list-accounts-payable-adjustment-line)
* [accounts-payable/adjustment-summary](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.adjustment-summary/tag/Adjustment-summaries/#tag/Adjustment-summaries/operation/list-accounts-payable-adjustment-summary)
* [accounts-payable/adjustment-tax-entry](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.adjustment-tax-entry/tag/Adjustment-tax-entries/#tag/Adjustment-tax-entries/operation/list-accounts-payable-adjustment-tax-entry)
* [accounts-payable/advance](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.advance/tag/Advances/#tag/Advances/operation/list-accounts-payable-advance)
* [accounts-payable/advance-line](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.advance-line/tag/Advance-lines/#tag/Advance-lines/operation/list-accounts-payable-advance-line)
* [accounts-payable/bill](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.bill/tag/Bills/#tag/Bills/operation/list-accounts-payable-bill)
* [accounts-payable/bill-line](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.bill-line/tag/Bill-lines/#tag/Bill-lines/operation/list-accounts-payable-bill-line)
* [accounts-payable/bill-summary](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.bill-summary/tag/Bill-summaries/#tag/Bill-summaries/operation/list-accounts-payable-bill-summary)
* [accounts-payable/bill-tax-entry](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.bill-tax-entry/tag/Bill-tax-entries/#tag/Bill-tax-entries/operation/list-accounts-payable-bill-tax-entry)
* [accounts-payable/check-run](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.check-run/tag/Check-runs/#tag/Check-runs/operation/list-accounts-payable-check-run)
* [accounts-payable/joint-payee](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.joint-payee/tag/Joint-payees/#tag/Joint-payees/operation/list-accounts-payable-joint-payee)
* [accounts-payable/payment](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.payment/tag/Payments/#tag/Payments/operation/list-accounts-payable-payment)
* [accounts-payable/payment-detail](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.payment-detail/tag/Payment-details/#tag/Payment-details/operation/list-accounts-payable-payment-detail)
* [accounts-payable/payment-line](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.payment-line/tag/Payment-lines/#tag/Payment-lines/operation/list-accounts-payable-payment-line)
* [accounts-payable/recurring-bill](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.recurring-bill/tag/Recurring-bills/#tag/Recurring-bills/operation/list-accounts-payable-recurring-bill)
* [accounts-payable/recurring-bill-line](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.recurring-bill-line/tag/Recurring-bill-lines/#tag/Recurring-bill-lines/operation/list-accounts-payable-recurring-bill-line)
* [accounts-payable/recurring-bill-tax-entry](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.recurring-bill-tax-entry/tag/Recurring-bill-tax-entries/#tag/Recurring-bill-tax-entries/operation/list-accounts-payable-recurring-bill-tax-entry)
* [accounts-payable/summary](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.summary/tag/Summaries/#tag/Summaries/operation/list-accounts-payable-summary)
* [accounts-payable/term](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.term/tag/Terms/#tag/Terms/operation/list-accounts-payable-term)
* [accounts-payable/vendor](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor/tag/Vendors/#tag/Vendors/operation/list-accounts-payable-vendor)
* [accounts-payable/vendor-account-number](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-account-number/tag/Vendor-account-numbers/#tag/Vendor-account-numbers/operation/list-accounts-payable-vendor-account-number)
* [accounts-payable/vendor-bank-file-setup](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-bank-file-setup/tag/Vendor-bank-file-setups/#tag/Vendor-bank-file-setups/operation/list-accounts-payable-vendor-bank-file-setup)
* [accounts-payable/vendor-contact](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-contact/tag/Vendor-contacts/#tag/Vendor-contacts/operation/list-accounts-payable-vendor-contact)
* [accounts-payable/vendor-email-template](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-email-template/tag/Vendor-email-templates/#tag/Vendor-email-templates/operation/list-accounts-payable-vendor-email-template)
* [accounts-payable/vendor-group](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-group/tag/Vendor-groups/#tag/Vendor-groups/operation/list-accounts-payable-vendor-group)
* [accounts-payable/vendor-payment-provider](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-payment-provider/tag/Vendor-payment-providers/#tag/Vendor-payment-providers/operation/list-accounts-payable-vendor-payment-provider)
* [accounts-payable/vendor-restricted-department](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-restricted-department/tag/Vendor-restricted-departments/#tag/Vendor-restricted-departments/operation/list-accounts-payable-vendor-restricted-department)
* [accounts-payable/vendor-restricted-location](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-restricted-location/tag/Vendor-restricted-locations/#tag/Vendor-restricted-locations/operation/list-accounts-payable-vendor-restricted-location)
* [accounts-payable/vendor-total](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-total/tag/Vendor-totals/#tag/Vendor-totals/operation/list-accounts-payable-vendor-total)
* [accounts-payable/vendor-type](https://developer.sage.com/intacct/docs/openapi/ap/accounts-payable.vendor-type/tag/Vendor-types/#tag/Vendor-types/operation/list-accounts-payable-vendor-type)
* [accounts-receivable/account-label](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.account-label/tag/Account-labels/#tag/Account-labels/operation/list-accounts-receivable-account-label)
* [accounts-receivable/adjustment](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.adjustment/tag/Adjustments/#tag/Adjustments/operation/list-accounts-receivable-adjustment)
* [accounts-receivable/adjustment-line](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.adjustment-line/tag/Adjustment-lines/#tag/Adjustment-lines/operation/list-accounts-receivable-adjustment-line)
* [accounts-receivable/adjustment-tax-entry](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.adjustment-tax-entry/tag/Adjustment-tax-entries/#tag/Adjustment-tax-entries/operation/list-accounts-receivable-adjustment-tax-entry)
* [accounts-receivable/advance](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.advance/tag/Advances/#tag/Advances/operation/list-accounts-receivable-advance)
* [accounts-receivable/advance-line](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.advance-line/tag/Advance-lines/#tag/Advance-lines/operation/list-accounts-receivable-advance-line)
* [accounts-receivable/billback-template](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.billback-template/tag/Billback-templates/#tag/Billback-templates/operation/list-accounts-receivable-billback-template)
* [accounts-receivable/billback-template-line](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.billback-template-line/tag/Billback-template-lines/#tag/Billback-template-lines/operation/list-accounts-receivable-billback-template-line)
* [accounts-receivable/customer](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer/tag/Customers/#tag/Customers/operation/list-accounts-receivable-customer)
* [accounts-receivable/customer-account-group](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-account-group/tag/Customer-account-groups/#tag/Customer-account-groups/operation/list-accounts-receivable-customer-account-group)
* [accounts-receivable/customer-contact](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-contact/tag/Customer-contacts/#tag/Customer-contacts/operation/list-accounts-receivable-customer-contact)
* [accounts-receivable/customer-email-template](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-email-template/tag/Customer-email-templates/#tag/Customer-email-templates/operation/list-accounts-receivable-customer-email-template)
* [accounts-receivable/customer-group](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-group/tag/Customer-groups/#tag/Customer-groups/operation/list-accounts-receivable-customer-group)
* [accounts-receivable/customer-item-cross-reference](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-item-cross-reference/tag/Customer-item-cross-references/#tag/Customer-item-cross-references/operation/list-accounts-receivable-customer-item-cross-reference)
* [accounts-receivable/customer-message](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-message/tag/Customer-messages/#tag/Customer-messages/operation/list-accounts-receivable-customer-message)
* [accounts-receivable/customer-restricted-department](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-restricted-department/tag/Customer-restricted-departments/#tag/Customer-restricted-departments/operation/list-accounts-receivable-customer-restricted-department)
* [accounts-receivable/customer-restricted-location](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-restricted-location/tag/Customer-restricted-locations/#tag/Customer-restricted-locations/operation/list-accounts-receivable-customer-restricted-location)
* [accounts-receivable/customer-total](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-total/tag/Customer-totals/#tag/Customer-totals/operation/list-accounts-receivable-customer-total)
* [accounts-receivable/customer-type](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.customer-type/tag/Customer-types/#tag/Customer-types/operation/list-accounts-receivable-customer-type)
* [accounts-receivable/delivery-history](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.delivery-history/tag/Delivery-histories/#tag/Delivery-histories/operation/list-accounts-receivable-delivery-history)
* [accounts-receivable/dunning-customer](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.dunning-customer/tag/Dunning-customers/#tag/Dunning-customers/operation/list-accounts-receivable-dunning-customer)
* [accounts-receivable/dunning-invoice](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.dunning-invoice/tag/Dunning-invoices/#tag/Dunning-invoices/operation/list-accounts-receivable-dunning-invoice)
* [accounts-receivable/dunning-level](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.dunning-level/tag/Dunning-levels/#tag/Dunning-levels/operation/list-accounts-receivable-dunning-level)
* [accounts-receivable/dunning-notice](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.dunning-notice/tag/Dunning-notices/#tag/Dunning-notices/operation/list-accounts-receivable-dunning-notice)
* [accounts-receivable/invoice](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.invoice/tag/Invoices/#tag/Invoices/operation/list-accounts-receivable-invoice)
* [accounts-receivable/invoice-line](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.invoice-line/tag/Invoice-lines/#tag/Invoice-lines/operation/list-accounts-receivable-invoice-line)
* [accounts-receivable/invoice-summary](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.invoice-summary/tag/Invoice-summaries/#tag/Invoice-summaries/operation/list-accounts-receivable-invoice-summary)
* [accounts-receivable/invoice-tax-entry](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.invoice-tax-entry/tag/Invoice-tax-entries/#tag/Invoice-tax-entries/operation/list-accounts-receivable-invoice-tax-entry)
* [accounts-receivable/manual-deposit](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.manual-deposit/tag/Manual-deposits/#tag/Manual-deposits/operation/list-accounts-receivable-manual-deposit)
* [accounts-receivable/manual-deposit-line](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.manual-deposit-line/tag/Manual-deposit-lines/#tag/Manual-deposit-lines/operation/list-accounts-receivable-manual-deposit-line)
* [accounts-receivable/manual-deposit-summary](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.manual-deposit-summary/tag/Manual-deposit-summaries/#tag/Manual-deposit-summaries/operation/list-accounts-receivable-manual-deposit-summary)
* [accounts-receivable/payment](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.payment/tag/Payments/#tag/Payments/operation/list-accounts-receivable-payment)
* [accounts-receivable/payment-detail](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.payment-detail/tag/Payment-details/#tag/Payment-details/operation/list-accounts-receivable-payment-detail)
* [accounts-receivable/payment-line](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.payment-line/tag/Payment-lines/#tag/Payment-lines/operation/list-accounts-receivable-payment-line)
* [accounts-receivable/payment-summary](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.payment-summary/tag/Payment-summaries/#tag/Payment-summaries/operation/list-accounts-receivable-payment-summary)
* [accounts-receivable/recurring-invoice](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.recurring-invoice/tag/Recurring-invoices/#tag/Recurring-invoices/operation/list-accounts-receivable-recurring-invoice)
* [accounts-receivable/recurring-invoice-line](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.recurring-invoice-line/tag/Recurring-invoice-lines/#tag/Recurring-invoice-lines/operation/list-accounts-receivable-recurring-invoice-line)
* [accounts-receivable/recurring-invoice-tax-entry](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.recurring-invoice-tax-entry/tag/Recurring-invoice-tax-entries/#tag/Recurring-invoice-tax-entries/operation/list-accounts-receivable-recurring-invoice-tax-entry)
* [accounts-receivable/revenue-recognition-template](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.revenue-recognition-template/tag/Revenue-recognition-templates/#tag/Revenue-recognition-templates/operation/list-accounts-receivable-revenue-recognition-template)
* [accounts-receivable/shipping-method](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.shipping-method/tag/Shipping-methods/#tag/Shipping-methods/operation/list-accounts-receivable-shipping-method)
* [accounts-receivable/summary](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.summary/tag/Summaries/#tag/Summaries/operation/list-accounts-receivable-summary)
* [accounts-receivable/term](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.term/tag/Terms/#tag/Terms/operation/list-accounts-receivable-term)
* [accounts-receivable/territory](https://developer.sage.com/intacct/docs/openapi/ar/accounts-receivable.territory/tag/Territories/#tag/Territories/operation/list-accounts-receivable-territory)
* [cash-management/ar-advance-txn-line-template](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.ar-advance-txn-line-template/tag/Ar-advance-txn-line-templates/#tag/Ar-advance-txn-line-templates/operation/list-cash-management-ar-advance-txn-line-template)
* [cash-management/ar-advance-txn-template](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.ar-advance-txn-template/tag/Ar-advance-txn-templates/#tag/Ar-advance-txn-templates/operation/list-cash-management-ar-advance-txn-template)
* [cash-management/bank-fee](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-fee/tag/Bank-fees/#tag/Bank-fees/operation/list-cash-management-bank-fee)
* [cash-management/bank-fee-line](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-fee-line/tag/Bank-fee-lines/#tag/Bank-fee-lines/operation/list-cash-management-bank-fee-line)
* [cash-management/bank-fee-tax-entry](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-fee-tax-entry/tag/Bank-fee-tax-entries/#tag/Bank-fee-tax-entries/operation/list-cash-management-bank-fee-tax-entry)
* [cash-management/bank-file](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-file/tag/Bank-files/#tag/Bank-files/operation/list-cash-management-bank-file)
* [cash-management/bank-file-detail](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-file-detail/tag/Bank-file-details/#tag/Bank-file-details/operation/list-cash-management-bank-file-detail)
* [cash-management/bank-txn-assignment-rule](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-txn-assignment-rule/tag/Bank-txn-assignment-rules/#tag/Bank-txn-assignment-rules/operation/list-cash-management-bank-txn-assignment-rule)
* [cash-management/bank-txn-assignment-rule-filter](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-txn-assignment-rule-filter/tag/Bank-txn-assignment-rule-filters/#tag/Bank-txn-assignment-rule-filters/operation/list-cash-management-bank-txn-assignment-rule-filter)
* [cash-management/bank-txn-rule](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-txn-rule/tag/Bank-txn-rules/#tag/Bank-txn-rules/operation/list-cash-management-bank-txn-rule)
* [cash-management/bank-txn-rule-filter](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-txn-rule-filter/tag/Bank-txn-rule-filters/#tag/Bank-txn-rule-filters/operation/list-cash-management-bank-txn-rule-filter)
* [cash-management/bank-txn-rule-group](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-txn-rule-group/tag/Bank-txn-rule-groups/#tag/Bank-txn-rule-groups/operation/list-cash-management-bank-txn-rule-group)
* [cash-management/bank-txn-rule-map](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-txn-rule-map/tag/Bank-txn-rule-maps/#tag/Bank-txn-rule-maps/operation/list-cash-management-bank-txn-rule-map)
* [cash-management/bank-txn-rule-match](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-txn-rule-match/tag/Bank-txn-rule-matches/#tag/Bank-txn-rule-matches/operation/list-cash-management-bank-txn-rule-match)
* [cash-management/bank-txn-rule-set](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.bank-txn-rule-set/tag/Bank-txn-rule-sets/#tag/Bank-txn-rule-sets/operation/list-cash-management-bank-txn-rule-set)
* [cash-management/checking-account](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.checking-account/tag/Checking-accounts/#tag/Checking-accounts/operation/list-cash-management-checking-account)
* [cash-management/credit-card-account](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-account/tag/Credit-card-accounts/#tag/Credit-card-accounts/operation/list-cash-management-credit-card-account)
* [cash-management/credit-card-fee](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-fee/tag/Credit-card-fees/#tag/Credit-card-fees/operation/list-cash-management-credit-card-fee)
* [cash-management/credit-card-fee-line](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-fee-line/tag/Credit-card-fee-lines/#tag/Credit-card-fee-lines/operation/list-cash-management-credit-card-fee-line)
* [cash-management/credit-card-fee-tax-entry](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-fee-tax-entry/tag/Credit-card-fee-tax-entries/#tag/Credit-card-fee-tax-entries/operation/list-cash-management-credit-card-fee-tax-entry)
* [cash-management/credit-card-txn](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-txn/tag/Credit-card-txns/#tag/Credit-card-txns/operation/list-cash-management-credit-card-txn)
* [cash-management/credit-card-txn-line](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-txn-line/tag/Credit-card-txn-lines/#tag/Credit-card-txn-lines/operation/list-cash-management-credit-card-txn-line)
* [cash-management/credit-card-txn-line-template](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-txn-line-template/tag/Credit-card-txn-line-templates/#tag/Credit-card-txn-line-templates/operation/list-cash-management-credit-card-txn-line-template)
* [cash-management/credit-card-txn-tax-entry](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-txn-tax-entry/tag/Credit-card-txn-tax-entries/#tag/Credit-card-txn-tax-entries/operation/list-cash-management-credit-card-txn-tax-entry)
* [cash-management/credit-card-txn-template](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.credit-card-txn-template/tag/Credit-card-txn-templates/#tag/Credit-card-txn-templates/operation/list-cash-management-credit-card-txn-template)
* [cash-management/deposit](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.deposit/tag/Deposits/#tag/Deposits/operation/list-cash-management-deposit)
* [cash-management/deposit-detail](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.deposit-detail/tag/Deposit-details/#tag/Deposit-details/operation/list-cash-management-deposit-detail)
* [cash-management/deposit-line](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.deposit-line/tag/Deposit-lines/#tag/Deposit-lines/operation/list-cash-management-deposit-line)
* [cash-management/financial-institution](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.financial-institution/tag/Financial-institutions/#tag/Financial-institutions/operation/list-cash-management-financial-institution)
* [cash-management/funds-transfer](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.funds-transfer/tag/Funds-transfers/#tag/Funds-transfers/operation/list-cash-management-funds-transfer)
* [cash-management/funds-transfer-line](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.funds-transfer-line/tag/Funds-transfer-lines/#tag/Funds-transfer-lines/operation/list-cash-management-funds-transfer-line)
* [cash-management/journal-entry-line-template](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.journal-entry-line-template/tag/Journal-entry-line-templates/#tag/Journal-entry-line-templates/operation/list-cash-management-journal-entry-line-template)
* [cash-management/journal-entry-template](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.journal-entry-template/tag/Journal-entry-templates/#tag/Journal-entry-templates/operation/list-cash-management-journal-entry-template)
* [cash-management/other-receipt](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.other-receipt/tag/Other-receipts/#tag/Other-receipts/operation/list-cash-management-other-receipt)
* [cash-management/other-receipt-line](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.other-receipt-line/tag/Other-receipt-lines/#tag/Other-receipt-lines/operation/list-cash-management-other-receipt-line)
* [cash-management/other-receipt-tax-entry](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.other-receipt-tax-entry/tag/Other-receipt-tax-entries/#tag/Other-receipt-tax-entries/operation/list-cash-management-other-receipt-tax-entry)
* [cash-management/payment-provider](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.payment-provider/tag/Payment-providers/#tag/Payment-providers/operation/list-cash-management-payment-provider)
* [cash-management/payment-provider-bank-account](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.payment-provider-bank-account/tag/Payment-provider-bank-accounts/#tag/Payment-provider-bank-accounts/operation/list-cash-management-payment-provider-bank-account)
* [cash-management/provider-payment-method](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.provider-payment-method/tag/Provider-payment-methods/#tag/Provider-payment-methods/operation/list-cash-management-provider-payment-method)
* [cash-management/savings-account](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.savings-account/tag/Savings-accounts/#tag/Savings-accounts/operation/list-cash-management-savings-account)
* [cash-management/undeposited-fund](https://developer.sage.com/intacct/docs/openapi/cm/cash-management.undeposited-fund/tag/Undeposited-funds/#tag/Undeposited-funds/operation/list-cash-management-undeposited-fund)
* [company-config/advanced-audit-history](https://developer.sage.com/intacct/docs/openapi/co/company-config.advanced-audit-history/tag/Advanced-audit-histories/#tag/Advanced-audit-histories/operation/list-company-config-advanced-audit-history)
* [company-config/affiliate-entity](https://developer.sage.com/intacct/docs/openapi/co/company-config.affiliate-entity/tag/Affiliate-entities/#tag/Affiliate-entities/operation/list-company-config-affiliate-entity)
* [company-config/affiliate-entity-group](https://developer.sage.com/intacct/docs/openapi/co/company-config.affiliate-entity-group/tag/Affiliate-entity-groups/#tag/Affiliate-entity-groups/operation/list-company-config-affiliate-entity-group)
* [company-config/attachment](https://developer.sage.com/intacct/docs/openapi/co/company-config.attachment/tag/Attachments/#tag/Attachments/operation/list-company-config-attachment)
* [company-config/audit-history](https://developer.sage.com/intacct/docs/openapi/co/company-config.audit-history/tag/Audit-histories/#tag/Audit-histories/operation/list-company-config-audit-history)
* [company-config/class](https://developer.sage.com/intacct/docs/openapi/co/company-config.class/tag/Classes/#tag/Classes/operation/list-company-config-class)
* [company-config/cloud-storage](https://developer.sage.com/intacct/docs/openapi/co/company-config.cloud-storage/tag/Cloud-storages/#tag/Cloud-storages/operation/list-company-config-cloud-storage)
* [company-config/contact](https://developer.sage.com/intacct/docs/openapi/co/company-config.contact/tag/Contacts/#tag/Contacts/operation/list-company-config-contact)
* [company-config/department](https://developer.sage.com/intacct/docs/openapi/co/company-config.department/tag/Departments/#tag/Departments/operation/list-company-config-department)
* [company-config/department-group](https://developer.sage.com/intacct/docs/openapi/co/company-config.department-group/tag/Department-groups/#tag/Department-groups/operation/list-company-config-department-group)
* [company-config/department-group-member](https://developer.sage.com/intacct/docs/openapi/co/company-config.department-group-member/tag/Department-group-members/#tag/Department-group-members/operation/list-company-config-department-group-member)
* [company-config/document-sequence](https://developer.sage.com/intacct/docs/openapi/co/company-config.document-sequence/tag/Document-sequences/#tag/Document-sequences/operation/list-company-config-document-sequence)
* [company-config/document-sequence-rollover](https://developer.sage.com/intacct/docs/openapi/co/company-config.document-sequence-rollover/tag/Document-sequence-rollovers/#tag/Document-sequence-rollovers/operation/list-company-config-document-sequence-rollover)
* [company-config/earning-type](https://developer.sage.com/intacct/docs/openapi/co/company-config.earning-type/tag/Earning-types/#tag/Earning-types/operation/list-company-config-earning-type)
* [company-config/email-delivery-record](https://developer.sage.com/intacct/docs/openapi/co/company-config.email-delivery-record/tag/Email-delivery-records/#tag/Email-delivery-records/operation/list-company-config-email-delivery-record)
* [company-config/email-template](https://developer.sage.com/intacct/docs/openapi/co/company-config.email-template/tag/Email-templates/#tag/Email-templates/operation/list-company-config-email-template)
* [company-config/employee](https://developer.sage.com/intacct/docs/openapi/co/company-config.employee/tag/Employees/#tag/Employees/operation/list-company-config-employee)
* [company-config/employee-bank-file-setup](https://developer.sage.com/intacct/docs/openapi/co/company-config.employee-bank-file-setup/tag/Employee-bank-file-setups/#tag/Employee-bank-file-setups/operation/list-company-config-employee-bank-file-setup)
* [company-config/employee-group](https://developer.sage.com/intacct/docs/openapi/co/company-config.employee-group/tag/Employee-groups/#tag/Employee-groups/operation/list-company-config-employee-group)
* [company-config/employee-rate](https://developer.sage.com/intacct/docs/openapi/co/company-config.employee-rate/tag/Employee-rates/#tag/Employee-rates/operation/list-company-config-employee-rate)
* [company-config/employee-type](https://developer.sage.com/intacct/docs/openapi/co/company-config.employee-type/tag/Employee-types/#tag/Employee-types/operation/list-company-config-employee-type)
* [company-config/entity](https://developer.sage.com/intacct/docs/openapi/co/company-config.entity/tag/Entities/#tag/Entities/operation/list-company-config-entity)
* [company-config/exchange-rate](https://developer.sage.com/intacct/docs/openapi/co/company-config.exchange-rate/tag/Exchange-rates/#tag/Exchange-rates/operation/list-company-config-exchange-rate)
* [company-config/exchange-rate-line](https://developer.sage.com/intacct/docs/openapi/co/company-config.exchange-rate-line/tag/Exchange-rate-lines/#tag/Exchange-rate-lines/operation/list-company-config-exchange-rate-line)
* [company-config/exchange-rate-type](https://developer.sage.com/intacct/docs/openapi/co/company-config.exchange-rate-type/tag/Exchange-rate-types/#tag/Exchange-rate-types/operation/list-company-config-exchange-rate-type)
* [company-config/folder](https://developer.sage.com/intacct/docs/openapi/co/company-config.folder/tag/Folders/#tag/Folders/operation/list-company-config-folder)
* [company-config/location](https://developer.sage.com/intacct/docs/openapi/co/company-config.location/tag/Locations/#tag/Locations/operation/list-company-config-location)
* [company-config/location-group](https://developer.sage.com/intacct/docs/openapi/co/company-config.location-group/tag/Location-groups/#tag/Location-groups/operation/list-company-config-location-group)
* [company-config/location-group-member](https://developer.sage.com/intacct/docs/openapi/co/company-config.location-group-member/tag/Location-group-members/#tag/Location-group-members/operation/list-company-config-location-group-member)
* [company-config/permission](https://developer.sage.com/intacct/docs/openapi/co/company-config.permission/tag/Permissions/#tag/Permissions/operation/list-company-config-permission)
* [company-config/role](https://developer.sage.com/intacct/docs/openapi/co/company-config.role/tag/Roles/#tag/Roles/operation/list-company-config-role)
* [company-config/role-permission-assignment](https://developer.sage.com/intacct/docs/openapi/co/company-config.role-permission-assignment/tag/Role-permission-assignments/#tag/Role-permission-assignments/operation/list-company-config-role-permission-assignment)
* [company-config/role-user-group-map](https://developer.sage.com/intacct/docs/openapi/co/company-config.role-user-group-map/tag/Role-user-group-maps/#tag/Role-user-group-maps/operation/list-company-config-role-user-group-map)
* [company-config/role-user-map](https://developer.sage.com/intacct/docs/openapi/co/company-config.role-user-map/tag/Role-user-maps/#tag/Role-user-maps/operation/list-company-config-role-user-map)
* [company-config/user](https://developer.sage.com/intacct/docs/openapi/co/company-config.user/tag/Users/#tag/Users/operation/list-company-config-user)
* [company-config/user-group](https://developer.sage.com/intacct/docs/openapi/co/company-config.user-group/tag/User-groups/#tag/User-groups/operation/list-company-config-user-group)
* [construction-forecasting/wip-forecast-detail](https://developer.sage.com/intacct/docs/openapi/cf/construction-forecasting.wip-forecast-detail/tag/WIP-forecast-details/#tag/WIP-forecast-details/operation/list-construction-forecasting-wip-forecast-detail)
* [construction-forecasting/wip-period](https://developer.sage.com/intacct/docs/openapi/cf/construction-forecasting.wip-period/tag/WIP-periods/#tag/WIP-periods/operation/list-construction-forecasting-wip-period)
* [construction-forecasting/wip-project](https://developer.sage.com/intacct/docs/openapi/cf/construction-forecasting.wip-project/tag/WIP-projects/#tag/WIP-projects/operation/list-construction-forecasting-wip-project)
* [construction-forecasting/wip-project-manager-forecast](https://developer.sage.com/intacct/docs/openapi/cf/construction-forecasting.wip-project-manager-forecast/tag/WIP-project-manager-forecasts/#tag/WIP-project-manager-forecasts/operation/list-construction-forecasting-wip-project-manager-forecast)
* [construction-forecasting/wip-setup](https://developer.sage.com/intacct/docs/openapi/cf/construction-forecasting.wip-setup/tag/WIP-setups/#tag/WIP-setups/operation/list-construction-forecasting-wip-setup)
* [construction-forecasting/wip-setup-account](https://developer.sage.com/intacct/docs/openapi/cf/construction-forecasting.wip-setup-account/tag/WIP-setup-accounts/#tag/WIP-setup-accounts/operation/list-construction-forecasting-wip-setup-account)
* [construction/accumulation-type](https://developer.sage.com/intacct/docs/openapi/cre/construction.accumulation-type/tag/Accumulation-types/#tag/Accumulation-types/operation/list-construction-accumulation-type)
* [construction/ap-releasable-retainage](https://developer.sage.com/intacct/docs/openapi/cre/construction.ap-releasable-retainage/tag/Ap-releasable-retainages/#tag/Ap-releasable-retainages/operation/list-construction-ap-releasable-retainage)
* [construction/ap-retainage-release](https://developer.sage.com/intacct/docs/openapi/cre/construction.ap-retainage-release/tag/Ap-retainage-releases/#tag/Ap-retainage-releases/operation/list-construction-ap-retainage-release)
* [construction/ap-retainage-release-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.ap-retainage-release-line/tag/Ap-retainage-release-lines/#tag/Ap-retainage-release-lines/operation/list-construction-ap-retainage-release-line)
* [construction/ar-releasable-retainage](https://developer.sage.com/intacct/docs/openapi/cre/construction.ar-releasable-retainage/tag/Ar-releasable-retainages/#tag/Ar-releasable-retainages/operation/list-construction-ar-releasable-retainage)
* [construction/ar-retainage-release](https://developer.sage.com/intacct/docs/openapi/cre/construction.ar-retainage-release/tag/Ar-retainage-releases/#tag/Ar-retainage-releases/operation/list-construction-ar-retainage-release)
* [construction/ar-retainage-release-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.ar-retainage-release-line/tag/Ar-retainage-release-lines/#tag/Ar-retainage-release-lines/operation/list-construction-ar-retainage-release-line)
* [construction/change-request](https://developer.sage.com/intacct/docs/openapi/cre/construction.change-request/tag/Change-requests/#tag/Change-requests/operation/list-construction-change-request)
* [construction/change-request-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.change-request-line/tag/Change-request-lines/#tag/Change-request-lines/operation/list-construction-change-request-line)
* [construction/change-request-status](https://developer.sage.com/intacct/docs/openapi/cre/construction.change-request-status/tag/Change-request-statuses/#tag/Change-request-statuses/operation/list-construction-change-request-status)
* [construction/change-request-type](https://developer.sage.com/intacct/docs/openapi/cre/construction.change-request-type/tag/Change-request-types/#tag/Change-request-types/operation/list-construction-change-request-type)
* [construction/cost-type](https://developer.sage.com/intacct/docs/openapi/cre/construction.cost-type/tag/Cost-types/#tag/Cost-types/operation/list-construction-cost-type)
* [construction/cost-type-observed-percent-completed](https://developer.sage.com/intacct/docs/openapi/cre/construction.cost-type-observed-percent-completed/tag/Cost-type-observed-percent-completeds/#tag/Cost-type-observed-percent-completeds/operation/list-construction-cost-type-observed-percent-completed)
* [construction/employee-position](https://developer.sage.com/intacct/docs/openapi/cre/construction.employee-position/tag/Employee-positions/#tag/Employee-positions/operation/list-construction-employee-position)
* [construction/labor-class](https://developer.sage.com/intacct/docs/openapi/cre/construction.labor-class/tag/Labor-classes/#tag/Labor-classes/operation/list-construction-labor-class)
* [construction/labor-shift](https://developer.sage.com/intacct/docs/openapi/cre/construction.labor-shift/tag/Labor-shifts/#tag/Labor-shifts/operation/list-construction-labor-shift)
* [construction/labor-union](https://developer.sage.com/intacct/docs/openapi/cre/construction.labor-union/tag/Labor-unions/#tag/Labor-unions/operation/list-construction-labor-union)
* [construction/project-change-order](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-change-order/tag/Project-change-orders/#tag/Project-change-orders/operation/list-construction-project-change-order)
* [construction/project-contract](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-contract/tag/Project-contracts/#tag/Project-contracts/operation/list-construction-project-contract)
* [construction/project-contract-billing-invoice-detail](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-contract-billing-invoice-detail/tag/Project-contract-billing-invoice-details/#tag/Project-contract-billing-invoice-details/operation/list-construction-project-contract-billing-invoice-detail)
* [construction/project-contract-billing-invoice-summary](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-contract-billing-invoice-summary/tag/Project-contract-billing-invoice-summaries/#tag/Project-contract-billing-invoice-summaries/operation/list-construction-project-contract-billing-invoice-summary)
* [construction/project-contract-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-contract-line/tag/Project-contract-lines/#tag/Project-contract-lines/operation/list-construction-project-contract-line)
* [construction/project-contract-line-entry](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-contract-line-entry/tag/Project-contract-line-entries/#tag/Project-contract-line-entries/operation/list-construction-project-contract-line-entry)
* [construction/project-contract-type](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-contract-type/tag/Project-contract-types/#tag/Project-contract-types/operation/list-construction-project-contract-type)
* [construction/project-estimate](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-estimate/tag/Project-estimates/#tag/Project-estimates/operation/list-construction-project-estimate)
* [construction/project-estimate-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-estimate-line/tag/Project-estimate-lines/#tag/Project-estimate-lines/operation/list-construction-project-estimate-line)
* [construction/project-estimate-type](https://developer.sage.com/intacct/docs/openapi/cre/construction.project-estimate-type/tag/Project-estimate-types/#tag/Project-estimate-types/operation/list-construction-project-estimate-type)
* [construction/rate-table](https://developer.sage.com/intacct/docs/openapi/cre/construction.rate-table/tag/Rate-tables/#tag/Rate-tables/operation/list-construction-rate-table)
* [construction/rate-table-accounts-payable-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.rate-table-accounts-payable-line/tag/Rate-table-accounts-payable-lines/#tag/Rate-table-accounts-payable-lines/operation/list-construction-rate-table-accounts-payable-line)
* [construction/rate-table-credit-card-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.rate-table-credit-card-line/tag/Rate-table-credit-card-lines/#tag/Rate-table-credit-card-lines/operation/list-construction-rate-table-credit-card-line)
* [construction/rate-table-employee-expense-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.rate-table-employee-expense-line/tag/Rate-table-employee-expense-lines/#tag/Rate-table-employee-expense-lines/operation/list-construction-rate-table-employee-expense-line)
* [construction/rate-table-journal-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.rate-table-journal-line/tag/Rate-table-journal-lines/#tag/Rate-table-journal-lines/operation/list-construction-rate-table-journal-line)
* [construction/rate-table-purchasing-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.rate-table-purchasing-line/tag/Rate-table-purchasing-lines/#tag/Rate-table-purchasing-lines/operation/list-construction-rate-table-purchasing-line)
* [construction/rate-table-timesheet-line](https://developer.sage.com/intacct/docs/openapi/cre/construction.rate-table-timesheet-line/tag/Rate-table-timesheet-lines/#tag/Rate-table-timesheet-lines/operation/list-construction-rate-table-timesheet-line)
* [construction/standard-cost-type](https://developer.sage.com/intacct/docs/openapi/cre/construction.standard-cost-type/tag/Standard-cost-types/#tag/Standard-cost-types/operation/list-construction-standard-cost-type)
* [construction/standard-task](https://developer.sage.com/intacct/docs/openapi/cre/construction.standard-task/tag/Standard-tasks/#tag/Standard-tasks/operation/list-construction-standard-task)
* [contracts/billing-price-list](https://developer.sage.com/intacct/docs/openapi/contract/contracts.billing-price-list/tag/Billing-price-lists/#tag/Billing-price-lists/operation/list-contracts-billing-price-list)
* [contracts/billing-price-list-entry](https://developer.sage.com/intacct/docs/openapi/contract/contracts.billing-price-list-entry/tag/Billing-price-list-entries/#tag/Billing-price-list-entries/operation/list-contracts-billing-price-list-entry)
* [contracts/billing-price-list-entry-line](https://developer.sage.com/intacct/docs/openapi/contract/contracts.billing-price-list-entry-line/tag/Billing-price-list-entry-lines/#tag/Billing-price-list-entry-lines/operation/list-contracts-billing-price-list-entry-line)
* [contracts/billing-price-list-entry-line-tier](https://developer.sage.com/intacct/docs/openapi/contract/contracts.billing-price-list-entry-line-tier/tag/Billing-price-list-entry-line-tiers/#tag/Billing-price-list-entry-line-tiers/operation/list-contracts-billing-price-list-entry-line-tier)
* [contracts/billing-schedule](https://developer.sage.com/intacct/docs/openapi/contract/contracts.billing-schedule/tag/Billing-schedules/#tag/Billing-schedules/operation/list-contracts-billing-schedule)
* [contracts/billing-schedule-line](https://developer.sage.com/intacct/docs/openapi/contract/contracts.billing-schedule-line/tag/Billing-schedule-lines/#tag/Billing-schedule-lines/operation/list-contracts-billing-schedule-line)
* [contracts/billing-template](https://developer.sage.com/intacct/docs/openapi/contract/contracts.billing-template/tag/Billing-templates/#tag/Billing-templates/operation/list-contracts-billing-template)
* [contracts/billing-template-line](https://developer.sage.com/intacct/docs/openapi/contract/contracts.billing-template-line/tag/Billing-template-lines/#tag/Billing-template-lines/operation/list-contracts-billing-template-line)
* [contracts/contract](https://developer.sage.com/intacct/docs/openapi/contract/contracts.contract/tag/Contracts/#tag/Contracts/operation/list-contracts-contract)
* [contracts/contract-line](https://developer.sage.com/intacct/docs/openapi/contract/contracts.contract-line/tag/Contract-lines/#tag/Contract-lines/operation/list-contracts-contract-line)
* [contracts/contract-type](https://developer.sage.com/intacct/docs/openapi/contract/contracts.contract-type/tag/Contract-types/#tag/Contract-types/operation/list-contracts-contract-type)
* [contracts/contract-usage](https://developer.sage.com/intacct/docs/openapi/contract/contracts.contract-usage/tag/Contract-usages/#tag/Contract-usages/operation/list-contracts-contract-usage)
* [contracts/expense-template](https://developer.sage.com/intacct/docs/openapi/contract/contracts.expense-template/tag/Expense-templates/#tag/Expense-templates/operation/list-contracts-expense-template)
* [contracts/expense-template-line](https://developer.sage.com/intacct/docs/openapi/contract/contracts.expense-template-line/tag/Expense-template-lines/#tag/Expense-template-lines/operation/list-contracts-expense-template-line)
* [contracts/mea-category](https://developer.sage.com/intacct/docs/openapi/contract/contracts.mea-category/tag/Mea-categories/#tag/Mea-categories/operation/list-contracts-mea-category)
* [contracts/mea-price-list](https://developer.sage.com/intacct/docs/openapi/contract/contracts.mea-price-list/tag/Mea-price-lists/#tag/Mea-price-lists/operation/list-contracts-mea-price-list)
* [contracts/mea-price-list-entry](https://developer.sage.com/intacct/docs/openapi/contract/contracts.mea-price-list-entry/tag/Mea-price-list-entries/#tag/Mea-price-list-entries/operation/list-contracts-mea-price-list-entry)
* [contracts/mea-price-list-entry-line](https://developer.sage.com/intacct/docs/openapi/contract/contracts.mea-price-list-entry-line/tag/Mea-price-list-entry-lines/#tag/Mea-price-list-entry-lines/operation/list-contracts-mea-price-list-entry-line)
* [contracts/revenue-schedule](https://developer.sage.com/intacct/docs/openapi/contract/contracts.revenue-schedule/tag/Revenue-schedules/#tag/Revenue-schedules/operation/list-contracts-revenue-schedule)
* [contracts/revenue-schedule-line](https://developer.sage.com/intacct/docs/openapi/contract/contracts.revenue-schedule-line/tag/Revenue-schedule-lines/#tag/Revenue-schedule-lines/operation/list-contracts-revenue-schedule-line)
* [contracts/revenue-template](https://developer.sage.com/intacct/docs/openapi/contract/contracts.revenue-template/tag/Revenue-templates/#tag/Revenue-templates/operation/list-contracts-revenue-template)
* [core/user-view](https://developer.sage.com/intacct/docs/openapi/co/core.user-view/tag/User-views/#tag/User-views/operation/list-core-user-view)
* [expenses/electronic-receipt](https://developer.sage.com/intacct/docs/openapi/ee/expenses.electronic-receipt/tag/Electronic-receipts/#tag/Electronic-receipts/operation/list-expenses-electronic-receipt)
* [expenses/electronic-receipt-line](https://developer.sage.com/intacct/docs/openapi/ee/expenses.electronic-receipt-line/tag/Electronic-receipt-lines/#tag/Electronic-receipt-lines/operation/list-expenses-electronic-receipt-line)
* [expenses/employee-expense](https://developer.sage.com/intacct/docs/openapi/ee/expenses.employee-expense/tag/Employee-expenses/#tag/Employee-expenses/operation/list-expenses-employee-expense)
* [expenses/employee-expense-adjustment](https://developer.sage.com/intacct/docs/openapi/ee/expenses.employee-expense-adjustment/tag/Employee-expense-adjustments/#tag/Employee-expense-adjustments/operation/list-expenses-employee-expense-adjustment)
* [expenses/employee-expense-adjustment-line](https://developer.sage.com/intacct/docs/openapi/ee/expenses.employee-expense-adjustment-line/tag/Employee-expense-adjustment-lines/#tag/Employee-expense-adjustment-lines/operation/list-expenses-employee-expense-adjustment-line)
* [expenses/employee-expense-line](https://developer.sage.com/intacct/docs/openapi/ee/expenses.employee-expense-line/tag/Employee-expense-lines/#tag/Employee-expense-lines/operation/list-expenses-employee-expense-line)
* [expenses/employee-expense-payment-type](https://developer.sage.com/intacct/docs/openapi/ee/expenses.employee-expense-payment-type/tag/Employee-expense-payment-types/#tag/Employee-expense-payment-types/operation/list-expenses-employee-expense-payment-type)
* [expenses/employee-expense-summary](https://developer.sage.com/intacct/docs/openapi/ee/expenses.employee-expense-summary/tag/Employee-expense-summaries/#tag/Employee-expense-summaries/operation/list-expenses-employee-expense-summary)
* [expenses/employee-expense-type](https://developer.sage.com/intacct/docs/openapi/ee/expenses.employee-expense-type/tag/Employee-expense-types/#tag/Employee-expense-types/operation/list-expenses-employee-expense-type)
* [expenses/expense-to-approve](https://developer.sage.com/intacct/docs/openapi/ee/expenses.expense-to-approve/tag/Expense-to-approves/#tag/Expense-to-approves/operation/list-expenses-expense-to-approve)
* [expenses/expense-to-approve-line](https://developer.sage.com/intacct/docs/openapi/ee/expenses.expense-to-approve-line/tag/Expense-to-approve-lines/#tag/Expense-to-approve-lines/operation/list-expenses-expense-to-approve-line)
* [expenses/unit-rate](https://developer.sage.com/intacct/docs/openapi/ee/expenses.unit-rate/tag/Unit-rates/#tag/Unit-rates/operation/list-expenses-unit-rate)
* [fixed-assets/asset](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.asset/tag/Assets/#tag/Assets/operation/list-fixed-assets-asset)
* [fixed-assets/asset-classification](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.asset-classification/tag/Asset-classifications/#tag/Asset-classifications/operation/list-fixed-assets-asset-classification)
* [fixed-assets/asset-depreciation-rule](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.asset-depreciation-rule/tag/Asset-depreciation-rules/#tag/Asset-depreciation-rules/operation/list-fixed-assets-asset-depreciation-rule)
* [fixed-assets/classification-depreciation-rule](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.classification-depreciation-rule/tag/Classification-depreciation-rules/#tag/Classification-depreciation-rules/operation/list-fixed-assets-classification-depreciation-rule)
* [fixed-assets/depreciation-method](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.depreciation-method/tag/Depreciation-methods/#tag/Depreciation-methods/operation/list-fixed-assets-depreciation-method)
* [fixed-assets/depreciation-schedule](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.depreciation-schedule/tag/Depreciation-schedules/#tag/Depreciation-schedules/operation/list-fixed-assets-depreciation-schedule)
* [fixed-assets/depreciation-schedule-entry](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.depreciation-schedule-entry/tag/Depreciation-schedule-entries/#tag/Depreciation-schedule-entries/operation/list-fixed-assets-depreciation-schedule-entry)
* [fixed-assets/setup](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.setup/tag/Setups/#tag/Setups/operation/list-fixed-assets-setup)
* [fixed-assets/setup-posting-rule](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.setup-posting-rule/tag/Setup-posting-rules/#tag/Setup-posting-rules/operation/list-fixed-assets-setup-posting-rule)
* [fixed-assets/transfer-history](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.transfer-history/tag/Transfer-histories/#tag/Transfer-histories/operation/list-fixed-assets-transfer-history)
* [fixed-assets/transfer-journal-entry-map](https://developer.sage.com/intacct/docs/openapi/fa/fixed-assets.transfer-journal-entry-map/tag/Transfer-journal-entry-maps/#tag/Transfer-journal-entry-maps/operation/list-fixed-assets-transfer-journal-entry-map)
* [general-ledger/account](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account/tag/Accounts/#tag/Accounts/operation/list-general-ledger-account)
* [general-ledger/account-allocation](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-allocation/tag/Account-allocations/#tag/Account-allocations/operation/list-general-ledger-account-allocation)
* [general-ledger/account-allocation-basis](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-allocation-basis/tag/Account-allocation-bases/#tag/Account-allocation-bases/operation/list-general-ledger-account-allocation-basis)
* [general-ledger/account-allocation-group](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-allocation-group/tag/Account-allocation-groups/#tag/Account-allocation-groups/operation/list-general-ledger-account-allocation-group)
* [general-ledger/account-allocation-group-member](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-allocation-group-member/tag/Account-allocation-group-members/#tag/Account-allocation-group-members/operation/list-general-ledger-account-allocation-group-member)
* [general-ledger/account-allocation-reverse](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-allocation-reverse/tag/Account-allocation-reverses/#tag/Account-allocation-reverses/operation/list-general-ledger-account-allocation-reverse)
* [general-ledger/account-allocation-run](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-allocation-run/tag/Account-allocation-runs/#tag/Account-allocation-runs/operation/list-general-ledger-account-allocation-run)
* [general-ledger/account-allocation-source](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-allocation-source/tag/Account-allocation-sources/#tag/Account-allocation-sources/operation/list-general-ledger-account-allocation-source)
* [general-ledger/account-allocation-target](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-allocation-target/tag/Account-allocation-targets/#tag/Account-allocation-targets/operation/list-general-ledger-account-allocation-target)
* [general-ledger/account-category](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-category/tag/Account-categories/#tag/Account-categories/operation/list-general-ledger-account-category)
* [general-ledger/account-group](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-group/tag/Account-groups/#tag/Account-groups/operation/list-general-ledger-account-group)
* [general-ledger/account-group-category-member](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-group-category-member/tag/Account-group-category-members/#tag/Account-group-category-members/operation/list-general-ledger-account-group-category-member)
* [general-ledger/account-group-computation](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-group-computation/tag/Account-group-computations/#tag/Account-group-computations/operation/list-general-ledger-account-group-computation)
* [general-ledger/account-group-member](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-group-member/tag/Account-group-members/#tag/Account-group-members/operation/list-general-ledger-account-group-member)
* [general-ledger/account-group-purpose](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-group-purpose/tag/Account-group-purposes/#tag/Account-group-purposes/operation/list-general-ledger-account-group-purpose)
* [general-ledger/account-range](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.account-range/tag/Account-ranges/#tag/Account-ranges/operation/list-general-ledger-account-range)
* [general-ledger/budget](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.budget/tag/Budgets/#tag/Budgets/operation/list-general-ledger-budget)
* [general-ledger/budget-detail](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.budget-detail/tag/Budget-details/#tag/Budget-details/operation/list-general-ledger-budget-detail)
* [general-ledger/journal](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.journal/tag/Journals/#tag/Journals/operation/list-general-ledger-journal)
* [general-ledger/journal-entry](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.journal-entry/tag/Journal-entries/#tag/Journal-entries/operation/list-general-ledger-journal-entry)
* [general-ledger/journal-entry-line](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.journal-entry-line/tag/Journal-entry-lines/#tag/Journal-entry-lines/operation/list-general-ledger-journal-entry-line)
* [general-ledger/journal-entry-tax-entry](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.journal-entry-tax-entry/tag/Journal-entry-tax-entries/#tag/Journal-entry-tax-entries/operation/list-general-ledger-journal-entry-tax-entry)
* [general-ledger/reporting-period](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.reporting-period/tag/Reporting-periods/#tag/Reporting-periods/operation/list-general-ledger-reporting-period)
* [general-ledger/statistical-account](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.statistical-account/tag/Statistical-accounts/#tag/Statistical-accounts/operation/list-general-ledger-statistical-account)
* [general-ledger/statistical-adjustment-journal](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.statistical-adjustment-journal/tag/Statistical-adjustment-journals/#tag/Statistical-adjustment-journals/operation/list-general-ledger-statistical-adjustment-journal)
* [general-ledger/statistical-journal](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.statistical-journal/tag/Statistical-journals/#tag/Statistical-journals/operation/list-general-ledger-statistical-journal)
* [general-ledger/statistical-journal-entry](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.statistical-journal-entry/tag/Statistical-journal-entries/#tag/Statistical-journal-entries/operation/list-general-ledger-statistical-journal-entry)
* [general-ledger/statistical-journal-entry-line](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.statistical-journal-entry-line/tag/Statistical-journal-entry-lines/#tag/Statistical-journal-entry-lines/operation/list-general-ledger-statistical-journal-entry-line)
* [general-ledger/txn-allocation-template](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.txn-allocation-template/tag/Txn-allocation-templates/#tag/Txn-allocation-templates/operation/list-general-ledger-txn-allocation-template)
* [general-ledger/txn-allocation-template-line](https://developer.sage.com/intacct/docs/openapi/gl/general-ledger.txn-allocation-template-line/tag/Txn-allocation-template-lines/#tag/Txn-allocation-template-lines/operation/list-general-ledger-txn-allocation-template-line)
* [inventory-control/aisle](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.aisle/tag/Aisles/#tag/Aisles/operation/list-inventory-control-aisle)
* [inventory-control/bin](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.bin/tag/Bins/#tag/Bins/operation/list-inventory-control-bin)
* [inventory-control/bin-face](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.bin-face/)
* [inventory-control/bin-size](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.bin-size/)
* [inventory-control/cycle](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.cycle/)
* [inventory-control/document](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.document/)
* [inventory-control/document-history](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.document-history/)
* [inventory-control/document-line](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.document-line/)
* [inventory-control/document-line-detail](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.document-line-detail/)
* [inventory-control/document-subtotal](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.document-subtotal/)
* [inventory-control/item](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.item/tag/Items/#tag/Items/operation/list-inventory-control-item)
* [inventory-control/item-cross-reference](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.item-cross-reference/)
* [inventory-control/item-gl-group](https://developer.sage.com/intacct/docs/openapi/ic/inventory-control.item-gl-group/)
* [inventory-control/item-group](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.item-group/tag/Item-groups/#tag/Item-groups/operation/list-inventory-control-item-group)
* [inventory-control/item-group-member](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.item-group-member/tag/Item-group-members/#tag/Item-group-members/operation/list-inventory-control-item-group-member)
* [inventory-control/item-landed-cost](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.item-landed-cost/tag/Item-landed-costs/#tag/Item-landed-costs/operation/list-inventory-control-item-landed-cost)
* [inventory-control/item-vendor](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.item-vendor/tag/Item-vendors/#tag/Item-vendors/operation/list-inventory-control-item-vendor)
* [inventory-control/item-warehouse-inventory](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.item-warehouse-inventory/tag/Item-warehouse-inventories/#tag/Item-warehouse-inventories/operation/list-inventory-control-item-warehouse-inventory)
* [inventory-control/item-warehouse-standard-cost](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.item-warehouse-standard-cost/tag/Item-warehouse-standard-costs/#tag/Item-warehouse-standard-costs/operation/list-inventory-control-item-warehouse-standard-cost)
* [inventory-control/item-warehouse-vendor](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.item-warehouse-vendor/tag/Item-warehouse-vendors/#tag/Item-warehouse-vendors/operation/list-inventory-control-item-warehouse-vendor)
* [inventory-control/kit-component](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.kit-component/tag/Kit-components/#tag/Kit-components/operation/list-inventory-control-kit-component)
* [inventory-control/posting-summary](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.posting-summary/tag/Posting-summaries/#tag/Posting-summaries/operation/list-inventory-control-posting-summary)
* [inventory-control/price-list](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.price-list/tag/Price-lists/#tag/Price-lists/operation/list-inventory-control-price-list)
* [inventory-control/price-list-entry](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.price-list-entry/tag/Price-list-entries/#tag/Price-list-entries/operation/list-inventory-control-price-list-entry)
* [inventory-control/product-line](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.product-line/tag/Product-lines/#tag/Product-lines/operation/list-inventory-control-product-line)
* [inventory-control/row](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.row/tag/Rows/#tag/Rows/operation/list-inventory-control-row)
* [inventory-control/stockable-kit-document](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.stockable-kit-document/tag/Stockable-kit-documents/#tag/Stockable-kit-documents/operation/list-inventory-control-stockable-kit-document)
* [inventory-control/stockable-kit-document-line](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.stockable-kit-document-line/tag/Stockable-kit-document-lines/#tag/Stockable-kit-document-lines/operation/list-inventory-control-stockable-kit-document-line)
* [inventory-control/total](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.total/tag/Totals/#tag/Totals/operation/list-inventory-control-total)
* [inventory-control/txn-definition](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.txn-definition/tag/Txn-definitions/#tag/Txn-definitions/operation/list-inventory-control-txn-definition)
* [inventory-control/txn-definition-cogs-gl-detail](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.txn-definition-cogs-gl-detail/tag/Txn-definition-cogs-gl-details/#tag/Txn-definition-cogs-gl-details/operation/list-inventory-control-txn-definition-cogs-gl-detail)
* [inventory-control/txn-definition-entity-detail](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.txn-definition-entity-detail/tag/Txn-definition-entity-details/#tag/Txn-definition-entity-details/operation/list-inventory-control-txn-definition-entity-detail)
* [inventory-control/txn-definition-source](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.txn-definition-source/tag/Txn-definition-sources/#tag/Txn-definition-sources/operation/list-inventory-control-txn-definition-source)
* [inventory-control/txn-definition-subtotal-detail](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.txn-definition-subtotal-detail/tag/Txn-definition-subtotal-details/#tag/Txn-definition-subtotal-details/operation/list-inventory-control-txn-definition-subtotal-detail)
* [inventory-control/txn-definition-total-detail](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.txn-definition-total-detail/tag/Txn-definition-total-details/#tag/Txn-definition-total-details/operation/list-inventory-control-txn-definition-total-detail)
* [inventory-control/unit-of-measure](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.unit-of-measure/tag/Unit-of-measures/#tag/Unit-of-measures/operation/list-inventory-control-unit-of-measure)
* [inventory-control/unit-of-measure-group](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.unit-of-measure-group/tag/Unit-of-measure-groups/#tag/Unit-of-measure-groups/operation/list-inventory-control-unit-of-measure-group)
* [inventory-control/warehouse](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.warehouse/tag/Warehouses/#tag/Warehouses/operation/list-inventory-control-warehouse)
* [inventory-control/warehouse-transfer](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.warehouse-transfer/tag/Warehouse-transfers/#tag/Warehouse-transfers/operation/list-inventory-control-warehouse-transfer)
* [inventory-control/warehouse-transfer-line](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.warehouse-transfer-line/tag/Warehouse-transfer-lines/#tag/Warehouse-transfer-lines/operation/list-inventory-control-warehouse-transfer-line)
* [inventory-control/zone](https://developer.sage.com/intacct/docs/openapi/inv/inventory-control.zone/tag/Zones/#tag/Zones/operation/list-inventory-control-zone)
* [order-entry/document](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.document/tag/Documents/#tag/Documents/operation/list-order-entry-document)
* [order-entry/document-history](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.document-history/tag/Document-histories/#tag/Document-histories/operation/list-order-entry-document-history)
* [order-entry/document-line](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.document-line/tag/Document-lines/#tag/Document-lines/operation/list-order-entry-document-line)
* [order-entry/document-line-detail](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.document-line-detail/tag/Document-line-details/#tag/Document-line-details/operation/list-order-entry-document-line-detail)
* [order-entry/document-line-subtotal](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.document-line-subtotal/tag/Document-line-subtotals/#tag/Document-line-subtotals/operation/list-order-entry-document-line-subtotal)
* [order-entry/document-subtotal](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.document-subtotal/tag/Document-subtotals/#tag/Document-subtotals/operation/list-order-entry-document-subtotal)
* [order-entry/price-list](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.price-list/tag/Price-lists/#tag/Price-lists/operation/list-order-entry-price-list)
* [order-entry/price-list-entry](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.price-list-entry/tag/Price-list-entries/#tag/Price-list-entries/operation/list-order-entry-price-list-entry)
* [order-entry/price-schedule](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.price-schedule/tag/Price-schedules/#tag/Price-schedules/operation/list-order-entry-price-schedule)
* [order-entry/recurring-document](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.recurring-document/tag/Recurring-documents/#tag/Recurring-documents/operation/list-order-entry-recurring-document)
* [order-entry/recurring-document-line](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.recurring-document-line/tag/Recurring-document-lines/#tag/Recurring-document-lines/operation/list-order-entry-recurring-document-line)
* [order-entry/recurring-document-subtotal](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.recurring-document-subtotal/tag/Recurring-document-subtotals/#tag/Recurring-document-subtotals/operation/list-order-entry-recurring-document-subtotal)
* [order-entry/recurring-schedule](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.recurring-schedule/tag/Recurring-schedules/#tag/Recurring-schedules/operation/list-order-entry-recurring-schedule)
* [order-entry/renewal-template](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.renewal-template/tag/Renewal-templates/#tag/Renewal-templates/operation/list-order-entry-renewal-template)
* [order-entry/subtotal-template](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.subtotal-template/tag/Subtotal-templates/#tag/Subtotal-templates/operation/list-order-entry-subtotal-template)
* [order-entry/subtotal-template-line](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.subtotal-template-line/tag/Subtotal-template-lines/#tag/Subtotal-template-lines/operation/list-order-entry-subtotal-template-line)
* [order-entry/txn-definition](https://developer.sage.com/intacct/docs/openapi/sales/order-entry.txn-definition/tag/Txn-definitions/#tag/Txn-definitions/operation/list-order-entry-txn-definition)
* [projects/position-skill](https://developer.sage.com/intacct/docs/openapi/pa/projects.position-skill/tag/Position-skills/#tag/Position-skills/operation/list-projects-position-skill)
* [projects/project](https://developer.sage.com/intacct/docs/openapi/pa/projects.project/tag/Projects/#tag/Projects/operation/list-projects-project)
* [projects/project-group](https://developer.sage.com/intacct/docs/openapi/pa/projects.project-group/tag/Project-groups/#tag/Project-groups/operation/list-projects-project-group)
* [projects/project-resource](https://developer.sage.com/intacct/docs/openapi/pa/projects.project-resource/tag/Project-resources/#tag/Project-resources/operation/list-projects-project-resource)
* [projects/project-status](https://developer.sage.com/intacct/docs/openapi/pa/projects.project-status/tag/Project-statuses/#tag/Project-statuses/operation/list-projects-project-status)
* [projects/project-type](https://developer.sage.com/intacct/docs/openapi/pa/projects.project-type/tag/Project-types/#tag/Project-types/operation/list-projects-project-type)
* [projects/task](https://developer.sage.com/intacct/docs/openapi/pa/projects.task/tag/Tasks/#tag/Tasks/operation/list-projects-task)
* [purchasing/document](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.document/tag/Documents/#tag/Documents/operation/list-purchasing-document)
* [purchasing/document-history](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.document-history/tag/Document-histories/#tag/Document-histories/operation/list-purchasing-document-history)
* [purchasing/document-line](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.document-line/tag/Document-lines/#tag/Document-lines/operation/list-purchasing-document-line)
* [purchasing/document-line-detail](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.document-line-detail/tag/Document-line-details/#tag/Document-line-details/operation/list-purchasing-document-line-detail)
* [purchasing/document-line-subtotal](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.document-line-subtotal/tag/Document-line-subtotals/#tag/Document-line-subtotals/operation/list-purchasing-document-line-subtotal)
* [purchasing/document-subtotal](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.document-subtotal/tag/Document-subtotals/#tag/Document-subtotals/operation/list-purchasing-document-subtotal)
* [purchasing/price-list](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.price-list/tag/Price-lists/#tag/Price-lists/operation/list-purchasing-price-list)
* [purchasing/price-list-entry](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.price-list-entry/tag/Price-list-entries/#tag/Price-list-entries/operation/list-purchasing-price-list-entry)
* [purchasing/price-schedule](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.price-schedule/tag/Price-schedules/#tag/Price-schedules/operation/list-purchasing-price-schedule)
* [purchasing/recurring-document](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.recurring-document/tag/Recurring-documents/#tag/Recurring-documents/operation/list-purchasing-recurring-document)
* [purchasing/recurring-document-line](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.recurring-document-line/tag/Recurring-document-lines/#tag/Recurring-document-lines/operation/list-purchasing-recurring-document-line)
* [purchasing/recurring-document-subtotal](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.recurring-document-subtotal/tag/Recurring-document-subtotals/#tag/Recurring-document-subtotals/operation/list-purchasing-recurring-document-subtotal)
* [purchasing/secondary-vendor](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.secondary-vendor/tag/Secondary-vendors/#tag/Secondary-vendors/operation/list-purchasing-secondary-vendor)
* [purchasing/subtotal-template](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.subtotal-template/tag/Subtotal-templates/#tag/Subtotal-templates/operation/list-purchasing-subtotal-template)
* [purchasing/subtotal-template-line](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.subtotal-template-line/tag/Subtotal-template-lines/#tag/Subtotal-template-lines/operation/list-purchasing-subtotal-template-line)
* [purchasing/txn-definition](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.txn-definition/tag/Txn-definitions/#tag/Txn-definitions/operation/list-purchasing-txn-definition)
* [purchasing/txn-definition-additional-gl-detail](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.txn-definition-additional-gl-detail/tag/Transaction-definition-additional-GL-account-details/#tag/Transaction-definition-additional-GL-account-details/operation/list-purchasing-txn-definition-additional-gl-detail)
* [purchasing/vendor-gl-group](https://developer.sage.com/intacct/docs/openapi/purchasing/purchasing.vendor-gl-group/tag/Vendor-GL-groups/#tag/Vendor-GL-groups/operation/list-purchasing-vendor-gl-group)
* [tax/account-label-tax-group](https://developer.sage.com/intacct/docs/openapi/tax/tax.account-label-tax-group/tag/Account-label-tax-groups/#tag/Account-label-tax-groups/operation/list-tax-account-label-tax-group)
* [tax/contact-tax-group](https://developer.sage.com/intacct/docs/openapi/tax/tax.contact-tax-group/tag/Contact-tax-groups/#tag/Contact-tax-groups/operation/list-tax-contact-tax-group)
* [tax/item-tax-group](https://developer.sage.com/intacct/docs/openapi/tax/tax.item-tax-group/tag/Item-tax-groups/#tag/Item-tax-groups/operation/list-tax-item-tax-group)
* [tax/order-entry-tax-detail](https://developer.sage.com/intacct/docs/openapi/tax/tax.order-entry-tax-detail/tag/Order-Entry-tax-details/#tag/Order-Entry-tax-details/operation/list-tax-order-entry-tax-detail)
* [tax/order-entry-tax-schedule](https://developer.sage.com/intacct/docs/openapi/tax/tax.order-entry-tax-schedule/tag/Order-Entry-tax-schedules/#tag/Order-Entry-tax-schedules/operation/list-tax-order-entry-tax-schedule)
* [tax/order-entry-tax-schedule-detail](https://developer.sage.com/intacct/docs/openapi/tax/tax.order-entry-tax-schedule-detail/tag/Order-Entry-tax-schedule-details/#tag/Order-Entry-tax-schedule-details/operation/list-tax-order-entry-tax-schedule-detail)
* [tax/purchasing-tax-detail](https://developer.sage.com/intacct/docs/openapi/tax/tax.purchasing-tax-detail/tag/Purchasing-tax-details/#tag/Purchasing-tax-details/operation/list-tax-purchasing-tax-detail)
* [tax/purchasing-tax-schedule](https://developer.sage.com/intacct/docs/openapi/tax/tax.purchasing-tax-schedule/tag/Purchasing-tax-schedules/#tag/Purchasing-tax-schedules/operation/list-tax-purchasing-tax-schedule)
* [tax/purchasing-tax-schedule-detail](https://developer.sage.com/intacct/docs/openapi/tax/tax.purchasing-tax-schedule-detail/tag/Purchasing-tax-schedule-details/#tag/Purchasing-tax-schedule-details/operation/list-tax-purchasing-tax-schedule-detail)
* [tax/tax-authority](https://developer.sage.com/intacct/docs/openapi/tax/tax.tax-authority/tag/Tax-authorities/#tag/Tax-authorities/operation/list-tax-tax-authority)
* [tax/tax-detail](https://developer.sage.com/intacct/docs/openapi/tax/tax.tax-detail/tag/Tax-details/#tag/Tax-details/operation/list-tax-tax-detail)
* [tax/tax-record](https://developer.sage.com/intacct/docs/openapi/tax/tax.tax-record/tag/Tax-records/#tag/Tax-records/operation/list-tax-tax-record)
* [tax/tax-return](https://developer.sage.com/intacct/docs/openapi/tax/tax.tax-return/tag/Tax-returns/#tag/Tax-returns/operation/list-tax-tax-return)
* [tax/tax-solution](https://developer.sage.com/intacct/docs/openapi/tax/tax.tax-solution/tag/Tax-solutions/#tag/Tax-solutions/operation/list-tax-tax-solution)
* [time/time-type](https://developer.sage.com/intacct/docs/openapi/time/time.time-type/tag/Time-types/#tag/Time-types/operation/list-time-time-type)
* [time/timesheet](https://developer.sage.com/intacct/docs/openapi/time/time.timesheet/tag/Timesheets/#tag/Timesheets/operation/list-time-timesheet)
* [time/timesheet-approval-record](https://developer.sage.com/intacct/docs/openapi/time/time.timesheet-approval-record/tag/Timesheet-approval-records/#tag/Timesheet-approval-records/operation/list-time-timesheet-approval-record)
* [time/timesheet-line](https://developer.sage.com/intacct/docs/openapi/time/time.timesheet-line/tag/Timesheet-lines/#tag/Timesheet-lines/operation/list-time-timesheet-line)
* [time/timesheet-rule](https://developer.sage.com/intacct/docs/openapi/time/time.timesheet-rule/tag/Timesheet-rules/#tag/Timesheet-rules/operation/list-time-timesheet-rule)
* [time/timesheet-to-approve](https://developer.sage.com/intacct/docs/openapi/time/time.timesheet-to-approve/tag/Approve-timesheet/#tag/Approve-timesheet/operation/list-time-timesheet-to-approve)

### Example integration

For an example manifest file of a Sage Intacct integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/sageintacct/amp.yaml).

## Before you get started

To integrate Sage Intacct with Ampersand, you will need access to a [Sage Developer Account](https://developer.sage.com/intacct/).

Once you have access, you'll need to create an app in Sage Intacct, configure the Ampersand redirect URI within the app, and obtain the following credentials from your Sage Intacct instance:

* Client ID
* Secret Key

You will then use these credentials to connect your application to Ampersand.

### Create a Sage Intacct app

* Log in to your [Sage Developer Account](https://developer.sage.com/intacct/).
* From the navigation menu, select **Applications** > **New Application**.
* Select **Sage Intacct** and select **Continue**.
* Enter the app details and click **Continue**.
* In the **Redirect URIs** section, enter the Ampersand **Callback URI**: `https://api.withampersand.com/callbacks/v1/oauth`.
* Add your Intacct Web Services License Password
* From the Client Scope dropdown list, choose the environment type that the application will be used with.
* Click **Create Application**.
* After creating the application, you will see the **Client ID** and **Secret Key**. Make sure to copy these values as you will need them later.

## Add Your Sage Intacct app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Sage Intacct integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Sage Intacct* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

<img alt="Ampersand Project Selection" />

6. Click **Save changes**.

## Using the connector

To start integrating with Sage Intacct:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/sageintacct/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Salesfinity
Source: https://docs.ampersand.ai/provider-guides/salesfinity



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://client-api.salesfinity.co`.

### Supported Objects

The Salesfinity connector supports writing to and reading from the following objects:

* [contact-lists](https://docs.salesfinity.ai/api-reference/endpoint/get-contact-lists)

The Salesfinity connector supports only reading from the following objects:

* [call-log](https://docs.salesfinity.ai/api-reference/endpoint/call-log)
* [contact-lists/csv](https://docs.salesfinity.ai/api-reference/endpoint/get-contact-lists-csv)
* [sdr-performance](https://docs.salesfinity.ai/api-reference/endpoint/analytics-sdr-performance)
* [list-performance](https://docs.salesfinity.ai/api-reference/endpoint/analytics-list-performance)

### Example integration

To define an integration for Salesfinity, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: salesfinityIntegration
    displayName: Salesfinity Integration
    provider: salesfinity
    proxy:
      enabled: true
```

## Before you get started

To use the Salesfinity connector, you'll need an API key from your Salesfinity account. Here's how to get it:

1. Log in to your Salesfinity account.
2. Go to **Settings** and head over to **Connections & API**.
3. Generate a new API key.

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Salesfinity:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Salesflare
Source: https://docs.ampersand.ai/provider-guides/salesflare



## What's supported

### Supported actions

This connector supports:

* [Write Actions](/write-actions).
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.salesflare.com`.

### Supported Objects

The Salesflare connector supports reading from and writing to the following objects:

* [accounts](https://api.salesflare.com/docs#operation/getAccounts)
* [contacts](https://api.salesflare.com/docs#operation/getContacts)
* [currencies](https://api.salesflare.com/docs#operation/getCurrencies) (read only)
* [email](https://api.salesflare.com/docs#operation/getDatasourcesEmail)
* [groups](https://api.salesflare.com/docs#operation/getGroups) (read only)
* [me/contacts](https://api.salesflare.com/docs#operation/getMeContacts) (read only)
* [opportunities](https://api.salesflare.com/docs#operation/getOpportunities)
* [persons](https://api.salesflare.com/docs#operation/getPersons) (read only)
* [pipelines](https://api.salesflare.com/docs#operation/getPipelines) (read only)
* [stages](https://api.salesflare.com/docs#operation/getStages) (read only)
* [tags](https://api.salesflare.com/docs#operation/getTags)
* [tasks](https://api.salesflare.com/docs#operation/getTasks)
* [users](https://api.salesflare.com/docs#operation/getUsers) (read only)
* [workflows](https://api.salesflare.com/docs#operation/getWorkflows)

### Example integration

To define an integration for Salesflare, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: salesflare-integration
    displayName: My Salesflare Integration
    provider: salesflare
    proxy:
      enabled: true
```

## Before You Get Started

To use the Salesflare connector, you'll need an API key from your Salesflare account. Here's how to get it:

1. Log in to your [Salesflare account](https://app.salesflare.com/).
2. Go to Settings > API Keys.
3. Generate a new API key.

For more information about authentication, see the [Salesflare API documentation](https://api.salesflare.com/docs#section/Introduction/Authentication).

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Salesflare:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.salesflare.com`.

For detailed information about available endpoints and request formats, refer to the [Salesflare API Reference](https://api.salesflare.com/docs).


# Salesforce
Source: https://docs.ampersand.ai/provider-guides/salesforce



The Salesforce connector supports:

* **CRM**
* **Account Engagement** (formerly Pardot)

## What's supported

### Supported actions

This connector has two modules, with CRM as the default.

The **CRM** module supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.my.salesforce.com`.
* [Read Actions](/read-actions), including full historic backfill, incremental read, and filters.
* [Subscribe Actions](/subscribe-actions).
* [Write Actions](/write-actions), including Bulk Write and Delete.

The **Account Engagement** module supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.my.salesforce.com`.
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).

### Supported CRM objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_account.htm">Account</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_campaign.htm">Campaign</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_case.htm">Case</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contact.htm">Contact</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_event.htm">Event</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_lead.htm">Lead</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_opportunity.htm">Opportunity</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product.htm">Product</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_task.htm">Task</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_user.htm">User</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>All other <a href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_list.htm">standard objects</a></td><td><Check /></td><td><Check /></td><td><Maybe /><br /><a href="https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/cdc_object_support.htm">(See the full list\*)</a></td></tr>
      <tr><td>All custom objects</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
    </tbody>
  </table>
</div>

*\* Only some standard objects are available for subscribe action. Check here for the [full list](https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/cdc_object_support.htm) of supported objects.*

For each of these CRM objects, the connector supports:

* Standard fields
* Custom fields

### Supported Account Engagement objects

The Salesforce connector supports the following **Account Engagement** module objects:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/campaign-v5.html">campaigns</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/custom-redirect-v5.html">custom-redirects</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/dynamic-content-v5.html">dynamic-contents</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/dynamic-content-variation.html">dynamic-content-variations</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/email-template-v5.html">email-templates</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/email-v5.html">emails</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/engagement-studio-program-v5.html">engagement-studio-programs</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/file-v5.html">files</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/folder-contents-v5.html">folder-contents</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/folder-v5.html">folders</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/form-field-v5.html">form-fields</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/form-handler-field-v5.html">form-handler-fields</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/form-handler-v5.html">form-handlers</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/form-v5.html">forms</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/landing-page-v5.html">landing-pages</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/layout-template-v5.html">layout-templates</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/lifecycle-history-v5.html">lifecycle-histories</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/lifecycle-stage-v5.html">lifecycle-stages</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/list-email-v5.html">list-emails</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/list-membership-v5.html">list-memberships</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/list-v5.html">lists</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/opportunity-v5.html">opportunities</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/prospect-account-v5.html">prospect-accounts</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/prospect-v5.html">prospects</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/tag-v5.html">tags</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/tagged-object-v5.html">tagged-objects</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/tracker-domain-v5.html">tracker-domains</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/user-v5.html">users</a></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/visit-v5.html">visits</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/visitor-activity-v5.html">visitor-activities</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/visitor-page-view-v5.html">visitor-page-views</a></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developer.salesforce.com/docs/marketing/pardot/guide/visitor-v5.html">visitors</a></td><td><Check /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

*\* Because Salesforce's [bulk Prospect Query endpoint](https://developer.salesforce.com/docs/marketing/pardot/guide/prospect-v5.html#requesting-custom-fields) does not support `Multi-Select` or `Checkbox` custom fields on `prospects`, these field types will not appear in the Ampersand field mapping UI and cannot be read or written through standard Read or Write Actions.*

### Example integration

Example manifest files can be found in our samples repository on GitHub:

* [Salesforce CRM example](https://github.com/amp-labs/samples/blob/main/salesforce/amp.yaml)
* [Salesforce Account Engagement example](https://github.com/amp-labs/samples/blob/main/salesforce-account-engagement-demo/amp.yaml)

## Before you get started

### Salesforce orgs needed

You will need two separate Salesforce orgs to complete this process:

1. **Dev Hub Org**: A Salesforce org with Dev Hub enabled. You will create the External Client App inside this org.

2. **Namespace Org**: A Developer Edition Salesforce org that is only used to register a namespace. You will link this namespace to the Dev Hub Org.

### 1. Enable Dev Hub

First you need to choose the Salesforce org to make into your "Dev Hub Org".

**If you intend to become a Salesforce partner and distribute via AppExchange later:**

* You can sign up for a [trial Salesforce Partner Business Org](https://partners.salesforce.com/pdx/s/trial-org-request), which is essentially a trial of a regular Salesforce org (typically 12 months long). Once you become an official partner, Salesforce will grant you two free Sales Cloud licenses. You can [request an extension of the trial or purchase more licenses](https://help.salesforce.com/s/articleView?id=000380510\&type=1).

* Alternatively, if you are already a Salesforce customer, then you can use your existing Salesforce org, and Salesforce will add these free licenses to your existing org when you are accepted as a partner. Please see [Salesforce documentation](https://partners.salesforce.com/s/education/general/Partner_Business_Org) for more information.

**If you don't intend to become a Salesforce partner:**

* You can sign up for a [free Developer Edition Salesforce org](https://developer.salesforce.com/signup) and use it as your Dev Hub Org. Please note that even though Developer Edition orgs are subject to deletion when there is inactivity, this [does not apply if you have an External Client App](https://help.salesforce.com/s/articleView?id=xcloud.admin_de_org_expiration.htm\&type=5) in the org, so it is safe to use a free Developer Edition org as your Dev Hub Org.

Once you have chosen the Salesforce org you will use as your Dev Hub org, you can enable Dev Hub by following these steps:

1. Log in to your Salesforce org.
2. From **Setup**, enter **Dev Hub** in the Quick Find box and select **Dev Hub**.
3. Select **Enable Dev Hub**.
4. Select **Enable Unlocked Packages and Second-Generation Managed Packages**.

<img alt="Enable Dev Hub" />

### 2. Register a namespace

Please note that namespaces cannot be created in the Dev Hub Org you just enabled in the step above. You must use a separate Salesforce Developer Edition org (we will call this org the "Namespace Org").

1. Sign up for a free [Developer Edition org](https://developer.salesforce.com/signup).

2. Navigate to the gear icon in the top right corner and select **Setup**.

   <img alt="Alt text" />

3. In the quick search box at the top, type in **Package Manager** in the Quick Find box and select **Package Manager**. In **Namespace Settings**, click **Edit**.

4. Enter a namespace and select **Check Availability**. We recommend picking a namespace that is your product name or a shortened version of your product name.

5. When prompted to select a package to associate with this namespace, select **None**, then click **Review**.

6. Review your selections and click **Save**.

<img alt="Create Namespace" />

### 3. Link namespace to Dev Hub Org

* Log in to the Dev Hub Org from Step 1.
* Open **App Launcher** (9 dots at the top left), and search for **Namespace Registries**.
* Click **Link Namespace** on the top right.
* When prompted to authenticate, log into the Namespace Org from Step 2. If you are having trouble with this step, try again in an incognito window.
* After linking, select **All Namespace Registries** filter to view the namespace.

<img alt="Link namespace" />

<img alt="View namespaces" />

### 4. Create External Client App

In order to connect with your customer's Salesforce instances, you'll need to create a Salesforce External Client App by following the steps below:

1. Log in to your Dev Hub Org that you created above.

2. Navigate to the gear icon in the top right corner and select **Setup**.

   <img alt="Alt text" />

3. Search for **External Client App Manager**.

4. Click **New External Client App**.

<img alt="New ECA" />

* Enter a **name** for the External Client App. This should match your product name.
* Specify a **contact email**; this should be your support email address.
* Set **Distribution State** to **"Packaged"**.
* Enable **OAuth settings**.
* In **callback URL** put `https://api.withampersand.com/callbacks/v1/oauth`.
* Add the following **OAuth scopes** at the minimum:
  * Perform requests at any time (`refresh_token`, `offline_access`)
  * Manage user data via APIs (`api`)

> ✅ For more details on which OAuth scopes to include, refer to the [OAuth Tokens and Scopes](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_tokens_scopes.htm\&language=en_US\&type=5) guide.

* Uncheck the box for `Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows`
* Check the box for `Enable Authorization Code and Credentials Flow`

<img alt="Create ECA" />

5. Go to the Policies tab, expand “OAuth Policies”, and click the edit button. In the “App Authorization” box, make the following modifications:

* In “Refresh Token Policy”, select “Refresh token is valid until revoked”
* In “IP Relaxation”, select “Relax IP restrictions”

<img />

> **Note:** "Relax IP restrictions" applies to the IP address your customer's browser authorizes from, not to the IP addresses Ampersand makes API calls from. Leave it relaxed. See [IP restrictions](#ip-restrictions) for how customers can still restrict API access by IP address.

6. Go to the Settings tab, expand “OAuth Settings”. Click on “Consumer Key and Secret”.

<img />

### 5. Package the External Client App

In order for your External Client App to be able to make API calls to your customers' Salesforce instances, Salesforce requires that you create a package version, and have your customers install your package in their Salesforce org.

1. **Install the Salesforce CLI** using npm or [another supported method](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm):

```bash theme={"dark"}
npm install -g @salesforce/cli
```

2. **Create a Salesforce DX project.** From a new directory, generate a project:

```bash theme={"dark"}
sf project generate --name MySalesforcePackage
```

Replace `MySalesforcePackage` with a name that fits your integration, such as your product name.

3. **Authenticate with your Dev Hub Org.** From the project directory you just created, log in to your Dev Hub Org (the org where you created the External Client App):

```bash theme={"dark"}
sf org login web --set-default-dev-hub --alias DevHubOrg
```

A browser window will open for you to sign in.

4. **Set the namespace in the project.** Edit `sfdx-project.json` in the project root. Set the `namespace` value to the namespace you registered and linked to your Dev Hub earlier:

```json theme={"dark"}
{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true
    }
  ],
  "namespace": "MY_NAMESPACE",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "59.0"
}
```

Replace `MY_NAMESPACE` with your actual namespace prefix.

5. **Create the managed package.** Use the command below and replace these flags with actual values that are applicable to you:

* `name`: replace with your product name
* `error-notification-username`: this must match the email address of one of the users in the Dev Hub Org. For example, you can use your own email here. This is the email address that will receive notifications from Salesforce about errors in the package.

```bash theme={"dark"}
sf package create \
  --name "My Package" \
  --package-type Managed \
  --path force-app \
  --target-dev-hub DevHubOrg \
  --error-notification-username your-notification-email@company.com
```

6. **Pull External Client App metadata into the project.** Run this command to programmatically fetch the settings that you had just configured for your External Client App:

```bash theme={"dark"}
sf project retrieve start --metadata ExternalClientApplication ExtlClntAppOauthSettings --target-org DevHubOrg
```

This creates (or updates) metadata under:

* `force-app/main/default/extlClntAppOauthSettings/`
* `force-app/main/default/externalClientApps/`

If you have several External Client Apps and only want to package one, remove the XML files for the apps you do not want in the package.

7. **Build and promote a package version.** Create a new package version (this can take several minutes). Replace `My Package` with the name you supplied in the `name` flag of the `sf package create` command above.

```bash theme={"dark"}
sf package version create \
  --package "My Package" \
  --installation-key-bypass \
  --wait 20 \
  --code-coverage
```

When it finishes, note the **Subscriber Package Version ID** that is printed. Please note that two IDs will be printed, you want the “Subscriber Package Version ID”, not the “Package Version”.

8. Promote that version so it can be installed by customers:

```bash theme={"dark"}
sf package version promote --package SUBSCRIBER_PACKAGE_VERSION_ID --no-prompt
```

Replace `SUBSCRIBER_PACKAGE_VERSION_ID` with the ID from the previous step.

### 6. Build the Package Install URL

1. **Build the package install URL.** Use the Subscriber Package Version ID from Step 7 above to build the install URL for your package.

For production orgs:

```text theme={"dark"}
https://login.salesforce.com/packaging/installPackage.apexp?p0=SUBSCRIBER_PACKAGE_VERSION_ID
```

For sandbox orgs:

```text theme={"dark"}
https://test.salesforce.com/packaging/installPackage.apexp?p0=SUBSCRIBER_PACKAGE_VERSION_ID
```

2. **Ensure customers install the package**

*If you are using `@amp-labs/react` **v2.14.1** or above*:

Once you create the Provider App with the package install URL (in the next step), the UI library will automatically prompt your user to install the package on their Salesforce instance.

<img />

Clicking on **Install Salesforce Package** will open up a new tab that has the Salesforce UI for them to install the package. Instruct your customers to go to the package install URL and click "Install for All Users".

<img />

They should see a screen like this after they are successful.

<img />

*If you are using `@amp-labs/react` versions below **2.14.1**:*

The UI library will not prompt your users to install the package, you must independently share the Package Install URL with them, and they must complete the installation process **before** they connect their Salesforce using the Ampersand UI components.

### 7. Create Provider App in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Salesforce integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Salesforce* from the **Provider** list.

5. Enter the following information:
   * *Client ID*: enter the Consumer Key for the External Client App, obtained from [Step 4. Create External Client App](#4-create-external-client-app).
   * *Client Secret*: enter the Consumer Secret for the External Client App, obtained from [Step 4. Create External Client App](#4-create-external-client-app)
   * *Package Install URL*: enter the Package Install URL, obtained from [Step 6. Build the Package Install URL](#6-build-the-package-install-url)

## Migrating Connected App to External Client App

Salesforce no longer supports the creation of new Connected Apps. If you had previously created a Connected App to be used for Ampersand integrations, it will continue to work for your existing and new customers as long as their user profile has the `Approve Uninstalled Connected Apps` or `Use Any API Client` permissions. See [Salesforce customer guide](/customer-guides/salesforce#required-system-permissions) for details.

Whenever you would like to, you can follow these steps to migrate a Connected App to an External Client App:

1. Open Salesforce **Setup** and search for **Manage Connected Apps** and select the Connected App that you want to convert. Click **Migrate To External Client Application**.

<img alt="Migrate connected app 1" />

2. Check both required checkboxes to confirm migration.

<img alt="Migrate connected app 2" />

3. Click **Migrate**.

<img alt="Migrate connected app 3" />

4. Click **OK**.

<img alt="Migrate connected app 4" />

5. A **confirmation message** will appear.

<img alt="Migrate connected app 5" />

6. Open **External Client App Manager**.

<img alt="Migrate connected app 6" />

7. Select your app, go to the **Settings** tab and set "Distribution State" to **Packaged**.

<img alt="Migrate connected app 7" />

8. Go to the Policies tab, expand “OAuth Policies”, and click the edit button. In the “App Authorization” box, make the following modifications:

* In “Refresh Token Policy”, select “Refresh token is valid until revoked”
* In “IP Relaxation”, select “Relax IP restrictions”

<img />

> **Note:** "Relax IP restrictions" applies to the IP address your customer's browser authorizes from, not to the IP addresses Ampersand makes API calls from. Leave it relaxed. See [IP restrictions](#ip-restrictions) for how customers can still restrict API access by IP address.

9. [Enable Dev Hub](#1-enable-dev-hub) on your Salesforce org that is hosting the Connected App (which is now an External Client App).

10. Create a new Developer Edition Salesforce org and [register a namespace](#2-register-a-namespace), then [link the namespace](#3-link-namespace-to-dev-hub-org) to the Dev Hub Org.

11. Package the External Client App by [following these instructions](#5-package-the-external-client-app).

## IP restrictions

Salesforce has several IP controls, and they apply at different points.

### IP Relaxation on your External Client App

The **IP Relaxation** setting in your app's OAuth policies applies to the IP address the **browser** connects from when one of your customers signs in and authorizes the app. Your customers authorize from their own machines, on IP addresses you cannot predict. When they connect through the [embeddable UI components](/embeddable-ui-components), the sign-in originates from the end user's browser, not from Ampersand.

For that reason, leave this set to **Relax IP restrictions**. Enforcing IP restrictions here blocks the OAuth flow for any customer signing in from outside their org's allowed ranges.

### If a customer asks about restricting access by IP address

Security reviews often ask whether the integration can be locked to a known set of IP addresses. It can, but not through the setting above. Salesforce has three controls whose names sound alike:

* **IP Relaxation** (on your External Client App, or on a Connected App) applies to the IP address the browser connects from at authorization time. It has to stay relaxed, for the reason above.
* **Login IP Ranges** on a user's profile **deny** access from any address outside the ranges listed. This is the control that actually restricts access.
* **Trusted IP Ranges** (**Setup** → **Security** → **Network Access**) are **not** a restriction. Logins from those addresses skip identity verification, but logins from other addresses are still allowed, so these alone do not block a stolen token.

Once a token has been minted, every API request Ampersand makes to Salesforce originates from a [fixed set of IP addresses](/security/outgoing-ip-addresses). A customer can restrict the profile of the user that connects the integration so that it can only log in from those addresses. This is configured in the customer's Salesforce org, not in your External Client App, so it requires no change on your side.

Point customers at [Restrict API access by IP address](/customer-guides/salesforce#restrict-api-access-by-ip-address) in the Salesforce customer guide.

## Using the connector

To start integrating with Salesforce:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/salesforce/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions or Subscribe Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Raw filters (SOQL)

[Read actions](/read-actions#filter-with-a-raw-filter) and [search](/search-actions#search-with-a-raw-filter) accept a raw filter of type `soql`: a SOQL condition, as it would appear after `WHERE`.

```json theme={"dark"}
"rawFilter": {
  "type": "soql",
  "filter": "Status = 'Qualified' AND (Country = 'US' OR Country = 'CA')"
}
```

<Tip>
  To try out a raw filter, run it with the [Search API](/search-actions#search-with-a-raw-filter) first. A search applies the filter the same way a read does and returns the matching records right away.
</Tip>

### Deleted and archived records

Reads and searches with a raw filter use Salesforce's `queryAll` endpoint instead of `query`. Unlike `query`, `queryAll` also returns deleted records that are still in the Recycle Bin, and archived Task and Event records. Your filter decides whether they're returned:

| Filter | Returns |
| - | - |
| `IsDeleted = false` | Active records only, the same as reading without a raw filter |
| `IsDeleted = true` | Deleted records only |
| `IsDeleted = true OR IsDeleted = false` | Both deleted and active records |
| `Status = 'Qualified'` | Qualified records, **including deleted ones** |

To tell deleted records apart from active ones, add `IsDeleted` to the object's `requiredFields` or `optionalFields`. A raw filter doesn't add any fields to what's read, and without `IsDeleted` a deleted record looks the same as an active one.

Deleting a record, or restoring it from the Recycle Bin, updates its `SystemModstamp`. So when the raw filter includes deleted records, the next incremental read delivers the record again, with `isdeleted` set to `true` after a delete and `false` after a restore.

<Note>
  Salesforce keeps deleted records in the Recycle Bin for 15 days. Once they're purged, `queryAll` no longer returns them.
</Note>

### Filter rules

* The filter can only use fields the object has. Setup objects such as User, Profile and RecordType have no `IsDeleted` field, so a filter that uses it fails.
* The filter must be a condition only, as it would appear after `WHERE`. Clauses such as `LIMIT`, `ORDER BY` or `GROUP BY` aren't allowed. Subqueries are, for example `Id IN (SELECT ContactId FROM CampaignMember WHERE Status = 'Sent')`.
* Raw filters are only supported by the CRM module.

## Customer guide

The [Salesforce customer guide](/customer-guides/salesforce) is a guide that can be shared with your customers to help them be successful in using your integration.

## Troubleshooting

For common errors and how to resolve them, see the [Salesforce troubleshooting guide](/troubleshooting-guides/salesforce).


# Salesforce (JWT authentication)
Source: https://docs.ampersand.ai/provider-guides/salesforce-jwt



The Salesforce (JWT) connector authenticates using the [OAuth 2.0 JWT Bearer Flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm\&language=en_US\&type=5) instead of the standard Authorization Code flow. This is a headless, server-to-server flow that is well suited for long-running, unattended integrations where an interactive OAuth login is impractical.

Please note that the standard [Salesforce connector](/provider-guides/salesforce) is a more convenient experience for your customers; it uses a standard OAuth 2.0 authentication scheme, and prompts your users for their Salesforce username and password. We recommend it for most use cases.

## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions), including Bulk Write and Delete.
* [Subscribe Actions](/subscribe-actions).
* [Search Actions](/search-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.my.salesforce.com`.

### Supported Modules & Objects

The Salesforce (JWT) connector currently supports the **CRM** module (referred to as `crm` in `amp.yaml`). The same standard and custom objects supported by the standard Salesforce connector are available — see the [Supported CRM objects](/provider-guides/salesforce#supported-crm-objects) section of the Salesforce provider guide for the full list.

The Account Engagement (Pardot) module is not currently supported under JWT Bearer authentication.

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforce-jwt-integration
    provider: salesforceJWT
    ...
```

## Before You Get Started

This connector uses OAuth 2.0 JWT Bearer authentication with an RSA key pair. There is no interactive login — your customer's Salesforce administrator will pre-authorize a designated integration user on an External Client App, and Ampersand will sign JWT assertions on their behalf to obtain access tokens.

To integrate Salesforce (JWT) with Ampersand, your customer's Salesforce administrator will need to complete the setup steps in the [customer guide](/customer-guides/salesforce-jwt) and provide you with the following credentials:

* Consumer Key (from the External Client App)
* Salesforce Username (the integration user)
* RSA Private Key (base64-encoded PEM)
* Salesforce My Domain subdomain (workspace)

### Creating the Salesforce app for JWT Bearer

Your customer's Salesforce administrator creates an **External Client App** with JWT Bearer flow enabled, uploads an X.509 certificate, and associates a Permission Set that pre-authorizes the integration user. The full steps are documented in the [customer guide](/customer-guides/salesforce-jwt).

<Note>Salesforce requires an RSA key (2048-bit minimum). ECDSA keys are not supported for the JWT Bearer flow.</Note>

## Using the connector

To start integrating with Salesforce (JWT):

* Create a manifest file like the [Salesforce example](https://github.com/amp-labs/samples/blob/main/salesforce/amp.yaml), using `salesforceJWT` as the provider instead of `salesforce`.
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions or Subscribe Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, passing the name of your `salesforceJWT` integration as the `integration` prop. The UI component prompts the customer for their Consumer Key, Salesforce Username, Private Key, and Subdomain instead of showing a Salesforce login screen. If you already embed `InstallIntegration` for the standard Salesforce connector, you only need to point it at the new integration name.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Customer guide

The [Salesforce (JWT) customer guide](/customer-guides/salesforce-jwt) is a guide that can be shared with your customers to help them be successful in using your integration.


# Salesloft
Source: https://docs.ampersand.ai/provider-guides/salesloft



## What's Supported

### Supported Actions

The Salesloft connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.salesloft.com`.
* [Subscribe Actions](/subscribe-actions).

<Note>
  If you are using Subscribe Actions, `watchFieldsAuto` is required to be set to `all` for Salesloft subscribe actions in your manifest [`amp.yaml`](https://github.com/amp-labs/samples/blob/main/salesloft/amp.yaml).
</Note>

### Example Integration

For an example manifest file of a Salesloft integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/salesloft/amp.yaml).

### Supported Objects

Refer to the [Salesloft API documentation](https://developers.salesloft.com/docs/api) for a description of each object.

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://developers.salesloft.com/docs/api/account-stages-index">Account Stages</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/account-tiers-index">Account Tiers</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/accounts-index">Accounts</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/actions-index">Actions</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/bulk-jobs-index">Bulk Jobs</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/cadence-memberships-index">Cadence Memberships</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/cadences-index">Cadences</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/calendar-events-index">Calendar Events</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/call-data-records-index">Call Data Records</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/call-dispositions-index">Call Dispositions</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/action-details-call-instructions-index">Call Instructions</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/call-sentiments-index">Call Sentiments</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/phone-numbers-caller-ids-index">Caller Ids</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/activities-calls-index">Calls</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Conversation Recordings</td><td><Cross /></td><td><Cross /></td><td><Check /></td></tr>
      <tr><td>Conversation Transcripts</td><td><Cross /></td><td><Cross /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/conversations-find-all">Conversations</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/account-team-member-roles-index">Crm Account Team Member Roles</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/crm-account-team-members-index">Crm Account Team Members</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/crm-activities-index">Crm Activities</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/crm-activity-fields-index">Crm Activity Fields</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/crm-users-index">Crm Users</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/custom-fields-index">Custom Fields</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/custom-roles-index">Custom Roles</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/email-template-attachments-index">Email Template Attachments</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/email-templates-index">Email Templates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/activities-emails-index">Emails</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/groups-index">Groups</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/imports-index">Imports</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td>Links</td><td><Cross /></td><td><Cross /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/meetings-index">Meetings</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/notes-index">Notes</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/opportunities-index">Opportunities</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/opportunity-people-index">Opportunity And Person Associations</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/opportunity-stages-index">Opportunity Stages</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/activity-histories-index">Past Activities</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/pending-emails-index">Pending Emails</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/people-index">People</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/person-stages-index">Person Stages</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/phone-number-assignments-index">Phone Number Assignments</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/integrations-signals-registrations-plays-index">Play Registrations</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/data-control-requests-index">Requests</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/saved-list-views-index">Saved List Views</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/integrations-signals-registrations-index">Signal Registrations</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/steps-index">Steps</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/successes-index">Successes</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/tasks-index">Tasks</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/external-configurations-index">Team Configurations</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/external-mappings-index">Team Mappings</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/tags-index">Team Tags</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/team-template-attachments-index">Team Template Attachments</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/team-templates-index">Team Templates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/conversations-transcriptions-find-all-transcripts">Transcriptions</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/users-index">Users</a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://developers.salesloft.com/docs/api/webhook-subscriptions-index">Webhook Subscriptions</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

## Before You Get Started

Before creating a **Salesloft** app, you need to sign up for a *Salesloft Developer License*. This license grants you the access and permissions needed to set up your development environment and manage your Salesloft applications.

To get started, simply contact the Salesloft team at [partners@salesloft.com](mailto:partners@salesloft.com) and get your Developer License.

After your account is set up, you will need to create a Salesloft app and acquire the following credentials from your Salesloft app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Salesloft App

Once your Salesloft account is ready, you need to create a Salesloft application.

1. Log in to your **Salesloft** account.

2. Navigate to **Salesloft OAuth Applications**. You can do this by selecting the OAuth Applications section from your Salesloft developer dashboard.

3. If this is your first app, click **Create your first app**. Click **Create New** under OAuth applications if you have already created an app before.

4. Enter the following details for the new app:
   * **Name**: The name of your product
   * **Redirect URI**: `https://api.withampersand.com/callbacks/v1/oauth`
   * **Application Type**: select "Yes, this will be a public application"

5. Once the app is created, note down the **Application ID** and **Secret**. You will need these to connect your app with Ampersand.

## Add Salesloft App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Salesloft App.

3. Select **Provider apps**.

4. Select *Salesloft* from the **Provider** list.

5. Enter the previously obtained *Application ID* in the **Client ID** field, the *Secret* in the **Client Secret** field, and the requested scopes in the **Permissions** field. See [Salesloft API Scopes](https://developers.salesloft.com/docs/platform/api-basics/scopes/) for more details on available scopes. If you are using Subscribe Actions, you will need additional scopes for webhooks; see [Salesloft Webhook Event Types](https://developers.salesloft.com/docs/platform/webhooks/event-types/) for more information.

   <img alt="Add Salesloft App Details" />

6. Click **Save Changes**.

## Using the connector

To start integrating with Salesloft:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/salesloft/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions or Subscribe Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Segment
Source: https://docs.ampersand.ai/provider-guides/segment



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.segmentapis.com`.

### Example integration

To define an integration for segment, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: segment-integration
    displayName: My Segment Integration
    provider: segment
    proxy:
      enabled: true
```

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with Segment:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key provided by the customer. Please note that this connector's base URL is `https://api.segmentapis.com`.

## Creating an API key for Segment

1. Log in to the Segment App, and choose the Workspace you want to generate a token for. Each Segment Workspace requires a separate token
2. Click **Settings** in the left menu to access Workspace Settings. Navigate to the **Access Management** tab, and click **Tokens**. This tab lists any existing tokens created for the Workspace.
3. Click **+Create Token**, and follow the prompts to generate a new token. Be sure to select a Public API token, and not a Config API token. Once generated, store the token somewhere safe, like a password store or other secrets manager


# Seismic
Source: https://docs.ampersand.ai/provider-guides/seismic



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.seismic.com`.

### Supported Objects

The Seismic connector supports reading from the following objects:

* [adminImpersonationSessions](https://developer.seismic.com/seismicsoftware/reference/reporting-adminimpersonationsessionsget)
* [aiActivity](https://developer.seismic.com/seismicsoftware/reference/reporting-aiactivityget)
* [aiGeneratedText](https://developer.seismic.com/seismicsoftware/reference/reporting-aigeneratedtextget)
* [aiGeneratedTextUserFeedback](https://developer.seismic.com/seismicsoftware/reference/reporting-aigeneratedtextuserfeedbackget)
* [aiSuggestedContentProperties](https://developer.seismic.com/seismicsoftware/reference/reporting-aisuggestedcontentpropertiesget)
* [announcements](https://developer.seismic.com/seismicsoftware/reference/reporting-announcementsget)
* [answers](https://developer.seismic.com/seismicsoftware/reference/reporting-answersget)
* [assignments](https://developer.seismic.com/seismicsoftware/reference/reporting-assignmentsget)
* [channels](https://developer.seismic.com/seismicsoftware/reference/reporting-channelsget)
* [contentActivities](https://developer.seismic.com/seismicsoftware/reference/reporting-contentactivitiesget)
* [contentAskExperts](https://developer.seismic.com/seismicsoftware/reference/reporting-contentaskexpertsget)
* [contentInsertInstances](https://developer.seismic.com/seismicsoftware/reference/reporting-contentinsertinstancesget)
* [contentPages](https://developer.seismic.com/seismicsoftware/reference/reporting-contentpagesget)
* [contentProfiles](https://developer.seismic.com/seismicsoftware/reference/reporting-contentprofilesget)
* [contentProfileAssignments](https://developer.seismic.com/seismicsoftware/reference/reporting-contentprofileassignmentsget)
* [contentProfileAssignmentsHistory](https://developer.seismic.com/seismicsoftware/reference/reporting-contentprofileassignmentshistoryget)
* [contentProperties](https://developer.seismic.com/seismicsoftware/reference/reporting-contentpropertiesget)
* [contentPropertyAssignments](https://developer.seismic.com/seismicsoftware/reference/reporting-contentpropertyassignmentsget)
* [contentReviews](https://developer.seismic.com/seismicsoftware/reference/reporting-contentreviewsget)
* [contentSlideInsertInstances](https://developer.seismic.com/seismicsoftware/reference/reporting-contentslideinsertinstancesget)
* [contentUsageHistory](https://developer.seismic.com/seismicsoftware/reference/reporting-contentusagehistoryget)
* [contentVersions](https://developer.seismic.com/seismicsoftware/reference/reporting-contentversionsget)
* [contentViewHistory](https://developer.seismic.com/seismicsoftware/reference/reporting-contentviewhistoryget)
* [copilotForSalesDsrRecommendations](https://developer.seismic.com/seismicsoftware/reference/reporting-copilotforsalesdsrrecommendationsget)
* [copilotForSalesRecommendations](https://developer.seismic.com/seismicsoftware/reference/reporting-copilotforsalesrecommendationsget)
* [customContents](https://developer.seismic.com/seismicsoftware/reference/reporting-customcontentsget)
* [customContentTypeFields](https://developer.seismic.com/seismicsoftware/reference/reporting-customcontenttypefieldsget)
* [customContentTypes](https://developer.seismic.com/seismicsoftware/reference/reporting-customcontenttypesget)
* [customProperties](https://developer.seismic.com/seismicsoftware/reference/reporting-custompropertiesget)
* [customPropertyAssignments](https://developer.seismic.com/seismicsoftware/reference/reporting-custompropertyassignmentsget)
* [customUserFields](https://developer.seismic.com/seismicsoftware/reference/reporting-customuserfieldsget)
* [customUserFieldValues](https://developer.seismic.com/seismicsoftware/reference/reporting-customuserfieldvaluesget)
* [dailyActiveUsers](https://developer.seismic.com/seismicsoftware/reference/reporting-dailyactiveusersget)
* [digitalSalesRoomTemplates](https://developer.seismic.com/seismicsoftware/reference/reporting-digitalsalesroomtemplatesget)
* [digitalSalesRoomTemplateVersions](https://developer.seismic.com/seismicsoftware/reference/reporting-digitalsalesroomtemplateversionsget)
* [digitalSalesRoomViewingSessions](https://developer.seismic.com/seismicsoftware/reference/reporting-digitalsalesroomviewingsessionsget)
* [digitalSalesRooms](https://developer.seismic.com/seismicsoftware/reference/reporting-digitalsalesroomsget)
* [distributionApprovalWorkflowStepsHistory](https://developer.seismic.com/seismicsoftware/reference/reporting-distributionapprovalworkflowstepshistoryget)
* [distributionApprovalWorkflows](https://developer.seismic.com/seismicsoftware/reference/reporting-distributionapprovalworkflowsget)
* [emails](https://developer.seismic.com/seismicsoftware/reference/reporting-emailsget)
* [emailTemplateInstances](https://developer.seismic.com/seismicsoftware/reference/reporting-emailtemplateinstancesget)
* [emailTemplateSectionSelections](https://developer.seismic.com/seismicsoftware/reference/reporting-emailtemplatesectionselectionsget)
* [emailTemplateStaticImages](https://developer.seismic.com/seismicsoftware/reference/reporting-emailtemplatestaticimagesget)
* [emailTemplateVariableValues](https://developer.seismic.com/seismicsoftware/reference/reporting-emailtemplatevariablevaluesget)
* [entitlementRoles](https://developer.seismic.com/seismicsoftware/reference/reporting-entitlementrolesget)
* [externalContentDetails](https://developer.seismic.com/seismicsoftware/reference/reporting-externalcontentdetailsget)
* [externalUsers](https://developer.seismic.com/seismicsoftware/reference/reporting-externalusersget)
* [favoriteStatus](https://developer.seismic.com/seismicsoftware/reference/reporting-favoritestatusget)
* [feedbackCriteria](https://developer.seismic.com/seismicsoftware/reference/reporting-feedbackcriteriaget)
* [followStatus](https://developer.seismic.com/seismicsoftware/reference/reporting-followstatusget)
* [generatedLivedocComponents](https://developer.seismic.com/seismicsoftware/reference/reporting-generatedlivedoccomponentsget)
* [generatedLivedocFields](https://developer.seismic.com/seismicsoftware/reference/reporting-generatedlivedocfieldsget)
* [generatedLivedocOutputFormats](https://developer.seismic.com/seismicsoftware/reference/reporting-generatedlivedocoutputformatsget)
* [generatedLivedocSlides](https://developer.seismic.com/seismicsoftware/reference/reporting-generatedlivedocslidesget)
* [generatedLivedocs](https://developer.seismic.com/seismicsoftware/reference/reporting-generatedlivedocsget)
* [groupManagers](https://developer.seismic.com/seismicsoftware/reference/reporting-groupmanagersget)
* [groupMembers](https://developer.seismic.com/seismicsoftware/reference/reporting-groupmembersget)
* [groups](https://developer.seismic.com/seismicsoftware/reference/reporting-groupsget)
* [indirectGroupManagers](https://developer.seismic.com/seismicsoftware/reference/reporting-indirectgroupmanagersget)
* [indirectGroupMembers](https://developer.seismic.com/seismicsoftware/reference/reporting-indirectgroupmembersget)
* [instructorLedTrainingEventAttendance](https://developer.seismic.com/seismicsoftware/reference/reporting-instructorledtrainingeventattendanceget)
* [instructorLedTrainingEventContentAssignments](https://developer.seismic.com/seismicsoftware/reference/reporting-instructorledtrainingeventcontentassignmentsget)
* [instructorLedTrainingEventSessions](https://developer.seismic.com/seismicsoftware/reference/reporting-instructorledtrainingeventsessionsget)
* [instructorLedTrainingEvents](https://developer.seismic.com/seismicsoftware/reference/reporting-instructorledtrainingeventsget)
* [interactionContexts](https://developer.seismic.com/seismicsoftware/reference/reporting-interactioncontextsget)
* [interactionRecipients](https://developer.seismic.com/seismicsoftware/reference/reporting-interactionrecipientsget)
* [learningJourneys](https://developer.seismic.com/seismicsoftware/reference/reporting-learningjourneysget)
* [learningJourneySteps](https://developer.seismic.com/seismicsoftware/reference/reporting-learningjourneystepsget)
* [learningJourneyTasks](https://developer.seismic.com/seismicsoftware/reference/reporting-learningjourneytasksget)
* [learningProgress](https://developer.seismic.com/seismicsoftware/reference/reporting-learningprogressget)
* [learningStatuses](https://developer.seismic.com/seismicsoftware/reference/reporting-learningstatusesget)
* [lessonTags](https://developer.seismic.com/seismicsoftware/reference/reporting-lessontagsget)
* [lessonVersions](https://developer.seismic.com/seismicsoftware/reference/reporting-lessonversionsget)
* [lessons](https://developer.seismic.com/seismicsoftware/reference/reporting-lessonsget)
* [libraryContentExpertAssociations](https://developer.seismic.com/seismicsoftware/reference/reporting-librarycontentexpertassociationsget)
* [libraryContentVersions](https://developer.seismic.com/seismicsoftware/reference/reporting-librarycontentversionsget)
* [libraryContents](https://developer.seismic.com/seismicsoftware/reference/reporting-librarycontentsget)
* [livedocCustomContentDataSourceRetrieveDataRequests](https://developer.seismic.com/seismicsoftware/reference/reporting-livedoccustomcontentdatasourceretrievedatarequestsget)
* [livedocDataSourceInfo](https://developer.seismic.com/seismicsoftware/reference/reporting-livedocdatasourceinfoget)
* [livedocDataSourceRetrieveDataRequests](https://developer.seismic.com/seismicsoftware/reference/reporting-livedocdatasourceretrievedatarequestsget)
* [livedocGlobalVariableRequests](https://developer.seismic.com/seismicsoftware/reference/reporting-livedocglobalvariablerequestsget)
* [livesendCommentMentions](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendcommentmentionsget)
* [livesendCommentReactions](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendcommentreactionsget)
* [livesendComments](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendcommentsget)
* [livesendContentViewingSessions](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendcontentviewingsessionsget)
* [livesendLinkContents](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendlinkcontentsget)
* [livesendLinkMeetingContents](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendlinkmeetingcontentsget)
* [livesendLinkMembers](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendlinkmembersget)
* [livesendLinks](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendlinksget)
* [livesendPageViews](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendpageviewsget)
* [livesendViewingSessions](https://developer.seismic.com/seismicsoftware/reference/reporting-livesendviewingsessionsget)
* [meetingAgendaUpdates](https://developer.seismic.com/seismicsoftware/reference/reporting-meetingagendaupdatesget)
* [meetingContentPagePresentations](https://developer.seismic.com/seismicsoftware/reference/reporting-meetingcontentpagepresentationsget)
* [meetingContentPresentations](https://developer.seismic.com/seismicsoftware/reference/reporting-meetingcontentpresentationsget)
* [meetingGeneralNotesUpdates](https://developer.seismic.com/seismicsoftware/reference/reporting-meetinggeneralnotesupdatesget)
* [meetingKeywords](https://developer.seismic.com/seismicsoftware/reference/reporting-meetingkeywordsget)
* [meetingParticipants](https://developer.seismic.com/seismicsoftware/reference/reporting-meetingparticipantsget)
* [meetingQuestions](https://developer.seismic.com/seismicsoftware/reference/reporting-meetingquestionsget)
* [meetingTrackers](https://developer.seismic.com/seismicsoftware/reference/reporting-meetingtrackersget)
* [meetings](https://developer.seismic.com/seismicsoftware/reference/reporting-meetingsget)
* [microappScreenViews](https://developer.seismic.com/seismicsoftware/reference/reporting-microappscreenviewsget)
* [microappScreens](https://developer.seismic.com/seismicsoftware/reference/reporting-microappscreensget)
* [notificationFrequencySettings](https://developer.seismic.com/seismicsoftware/reference/reporting-notificationfrequencysettingsget)
* [notificationStatus](https://developer.seismic.com/seismicsoftware/reference/reporting-notificationstatusget)
* [pageClicks](https://developer.seismic.com/seismicsoftware/reference/reporting-pageclicksget)
* [pageContentHistory](https://developer.seismic.com/seismicsoftware/reference/reporting-pagecontenthistoryget)
* [paths](https://developer.seismic.com/seismicsoftware/reference/reporting-pathsget)
* [pathContents](https://developer.seismic.com/seismicsoftware/reference/reporting-pathcontentsget)
* [pathTags](https://developer.seismic.com/seismicsoftware/reference/reporting-pathtagsget)
* [postContents](https://developer.seismic.com/seismicsoftware/reference/reporting-postcontentsget)
* [posts](https://developer.seismic.com/seismicsoftware/reference/reporting-postsget)
* [proficiencyLevels](https://developer.seismic.com/seismicsoftware/reference/reporting-proficiencylevelsget)
* [programAssociations](https://developer.seismic.com/seismicsoftware/reference/reporting-programassociationsget)
* [programDates](https://developer.seismic.com/seismicsoftware/reference/reporting-programdatesget)
* [programItems](https://developer.seismic.com/seismicsoftware/reference/reporting-programitemsget)
* [programRequestDates](https://developer.seismic.com/seismicsoftware/reference/reporting-programrequestdatesget)
* [programRequests](https://developer.seismic.com/seismicsoftware/reference/reporting-programrequestsget)
* [programTaskDates](https://developer.seismic.com/seismicsoftware/reference/reporting-programtaskdatesget)
* [programTasks](https://developer.seismic.com/seismicsoftware/reference/reporting-programtasksget)
* [publishingApprovalWorkflowAcknowledgements](https://developer.seismic.com/seismicsoftware/reference/reporting-publishingapprovalworkflowacknowledgementsget)
* [publishingApprovalWorkflowStepsHistory](https://developer.seismic.com/seismicsoftware/reference/reporting-publishingapprovalworkflowstepshistoryget)
* [publishingApprovalWorkflows](https://developer.seismic.com/seismicsoftware/reference/reporting-publishingapprovalworkflowsget)
* [questions](https://developer.seismic.com/seismicsoftware/reference/reporting-questionsget)
* [searchClickMatchDetails](https://developer.seismic.com/seismicsoftware/reference/reporting-searchclickmatchdetailsget)
* [searchClicks](https://developer.seismic.com/seismicsoftware/reference/reporting-searchclicksget)
* [searchFacets](https://developer.seismic.com/seismicsoftware/reference/reporting-searchfacetsget)
* [searchHistory](https://developer.seismic.com/seismicsoftware/reference/reporting-searchhistoryget)
* [searchWords](https://developer.seismic.com/seismicsoftware/reference/reporting-searchwordsget)
* [skillAssessments](https://developer.seismic.com/seismicsoftware/reference/reporting-skillassessmentsget)
* [skillProfiles](https://developer.seismic.com/seismicsoftware/reference/reporting-skillprofilesget)
* [skillProfileDetails](https://developer.seismic.com/seismicsoftware/reference/reporting-skillprofiledetailsget)
* [skillRatings](https://developer.seismic.com/seismicsoftware/reference/reporting-skillratingsget)
* [skillRequests](https://developer.seismic.com/seismicsoftware/reference/reporting-skillrequestsget)
* [skillReviews](https://developer.seismic.com/seismicsoftware/reference/reporting-skillreviewsget)
* [skillTags](https://developer.seismic.com/seismicsoftware/reference/reporting-skilltagsget)
* [skillUserProfiles](https://developer.seismic.com/seismicsoftware/reference/reporting-skilluserprofilesget)
* [skills](https://developer.seismic.com/seismicsoftware/reference/reporting-skillsget)
* [teamsites](https://developer.seismic.com/seismicsoftware/reference/reporting-teamsitesget)
* [trainingGroupManagers](https://developer.seismic.com/seismicsoftware/reference/reporting-traininggroupmanagersget)
* [trainingGroupMembers](https://developer.seismic.com/seismicsoftware/reference/reporting-traininggroupmembersget)
* [trainingGroups](https://developer.seismic.com/seismicsoftware/reference/reporting-traininggroupsget)
* [userActivity](https://developer.seismic.com/seismicsoftware/reference/reporting-useractivityget)
* [userEntitlementRoleAssignments](https://developer.seismic.com/seismicsoftware/reference/reporting-userentitlementroleassignmentsget)
* [userGroupsList](https://developer.seismic.com/seismicsoftware/reference/reporting-usergroupslistget)
* [userProperties](https://developer.seismic.com/seismicsoftware/reference/reporting-userpropertiesget)
* [userPropertyAssignments](https://developer.seismic.com/seismicsoftware/reference/reporting-userpropertyassignmentsget)
* [users](https://developer.seismic.com/seismicsoftware/reference/reporting-usersget)
* [virusScanAuditLog](https://developer.seismic.com/seismicsoftware/reference/reporting-virusscanauditlogget)
* [watermarks](https://developer.seismic.com/seismicsoftware/reference/reporting-watermarksget)
* [workspaceContentVersions](https://developer.seismic.com/seismicsoftware/reference/reporting-workspacecontentversionsget)
* [workspaceContents](https://developer.seismic.com/seismicsoftware/reference/reporting-workspacecontentsget)

### Example Integration

For an example manifest file of a Seismic integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/seismic/amp.yaml).

## Before You Get Started

To connect Seismic with Ampersand, you will need [a Seismic Account](https://seismic.com/).

Once your account is created, you'll need to configure an app in Seismic and obtain the following credentials from your app:

* App ID
* Signing Secret

You will use these credentials to connect your application to Ampersand.

### Create a Seismic Account

Here's how you can sign up for a Seismic account:

* Go to the [Seismic Sign Up page](https://Seismic.com/register) and create an account.
* Sign up using your preferred method.

### Creating a Seismic App

Follow the steps below to create a Seismic app and add the Ampersand redirect URL in the app:

1. Log in to your [Seismic Developer Portal](https://apps.seismic.com/apps).
2. Click **Create an app**.
3. Enter an **App Name** and click **Create app**.
4. In the **Authentication** section on your app, enable the **Do you need authentication for your app?** button.
5. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` in the *Oauth2 Information* section.
6. Select the necessary scopes for your app from the **Scopes** section.
7. Click **Save Changes**.

<img alt="Alt text" />

### Obtain Client ID and Client Secret

1. Navigate to the **Basic Information** tab of your app, where you'll find the **App ID**.
2. In the **Signing Secret** section, click **Generate** to create your client secret key.

Be sure to copy both the App ID and the Signing Secret as you'll need these credentials to connect to Ampersand.

## Add Your Seismic App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Seismic integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Seismic* from the **Provider** list.

5. Enter the previously obtained *App ID* in the **Client ID** field and the *Signing Secret* in the **Client Secret** field.

   <img alt="Alt text" />

6. Click **Save changes**.


# Sellsy
Source: https://docs.ampersand.ai/provider-guides/sellsy



## What's Supported

### Supported Actions

This connector supports:

* [Write Actions](/write-actions).
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://api.sellsy.com`.

### Supported Objects

The Sellsy connector supports reading from and writing to objects such as:

* [calendar-events](https://docs.sellsy.com/api/v2/#operation/search-calendar-events)
* [comments](https://docs.sellsy.com/api/v2/#operation/search-comments)
* [companies](https://docs.sellsy.com/api/v2/#operation/search-companies)
* [contacts](https://docs.sellsy.com/api/v2/#operation/search-contacts)
* [credit-notes](https://docs.sellsy.com/api/v2/#operation/search-credit-notes)
* [custom-activities](https://docs.sellsy.com/api/v2/#operation/post-custom-activities-search)
* [custom-activity-types](https://docs.sellsy.com/api/v2/#operation/get-custom-activity-types)
* [deposit-invoices](https://docs.sellsy.com/api/v2/#operation/search-deposit-invoices)
* [documents/models](https://docs.sellsy.com/api/v2/#operation/search-models)
* [estimates](https://docs.sellsy.com/api/v2/#operation/search-estimates)
* [individuals](https://docs.sellsy.com/api/v2/#operation/search-individuals)
* [invoices](https://docs.sellsy.com/api/v2/#operation/search-invoices)
* [opportunities](https://docs.sellsy.com/api/v2/#operation/search-opportunities)
* [orders](https://docs.sellsy.com/api/v2/#operation/search-orders)
* [phone-calls](https://docs.sellsy.com/api/v2/#operation/search-phone-calls)
* [staffs](https://docs.sellsy.com/api/v2/#operation/search-staffs)
* [subscriptions](https://docs.sellsy.com/api/v2/#operation/search-subscriptions)
* [tasks](https://docs.sellsy.com/api/v2/#operation/search-tasks)
* [webhooks](https://docs.sellsy.com/api/v2/#operation/search-webhooks)

Read-only objects include:

* [notifications](https://docs.sellsy.com/api/v2/#operation/search-notifications)
* [pur-invoice](https://docs.sellsy.com/api/v2/#operation/search-ocr-pur-invoice)

## Before You Get Started

To connect Sellsy with Ampersand, you will need [a Sellsy Account](https://www.sellsy.com/onboarding/quicktrial).

Once your account is created, you'll need to create an app in Sellsy and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Sellsy Account

Here's how you can sign up for a Sellsy account:

* Go to the [Sellsy Sign Up page](https://www.sellsy.com/onboarding/quicktrial).
* Sign up using your preferred method.

### Creating a Sellsy App

Follow the steps below to create & configure a Sellsy app.

1. Log in to your [Sellsy](https://login.sellsy.com/login) account.

2. Go to **Menu**, **Settings**, and select **Developer Portal** in your Sellsy account.

3. Click the **API V2 (beta)** tab, then click **Create API Access** and select the **API access type** as *Private*.

4. Enter your application's name as the **Access name**.

5. In the **Redirect URLs** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

6. Choose the **scopes** that are applicable to your application.

   <img alt="Sellsy App Creation" />

7. Make sure to click **Save**.

## Add Your Sellsy App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project you want to create a Sellsy integration in.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select *Sellsy* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Ampersand Integration" />


# SendGrid
Source: https://docs.ampersand.ai/provider-guides/sendGrid



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill for all supported objects below. Incremental read is not currently supported.
* [Write Actions](/write-actions) (create/update/delete).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.sendgrid.com`.
* Subscribe Actions are not currently supported.

### Supported objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/contacts/get-sample-contacts">contacts</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/lists/get-all-lists">lists</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/segmenting-contacts/get-list-of-segments">segments</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/single-sends/get-all-single-sends">singlesends</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/templates-api/retrieve-all-templates">templates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/custom-fields/get-all-field-definitions">field\_definitions</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/sender-verification/get-all-verified-senders">verified\_senders</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/sender-identities-api/get-all-senders">senders</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/bounces-api/retrieve-all-bounces">bounces</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/blocks-api/retrieve-all-blocks">blocks</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/spam-reports-api/retrieve-all-spam-reports">spam\_reports</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/suppressions-global-suppressions/retrieve-all-global-suppressions">unsubscribes</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/invalid-emails-api/retrieve-all-invalid-emails">invalid\_emails</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/suppressions-unsubscribe-groups/retrieve-all-suppression-groups">asm\_groups</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/categories/retrieve-all-categories">categories</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.twilio.com/docs/sendgrid/api-reference/subusers-api/list-all-subusers">subusers</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

### Example integration

For an example manifest file of a SendGrid integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/sendGrid/amp.yaml).

## Before you get started

To connect SendGrid with Ampersand, you will need a [SendGrid account](https://signup.sendgrid.com/).

This connector uses **API key** authentication. You do **not** need to create a Provider App in Ampersand before getting started (Provider apps are only required for OAuth2 Authorization Code providers).

Each customer supplies their own SendGrid API key during installation via the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.

### Create a SendGrid API key

Follow SendGrid’s documentation to create an API key with the scopes your integration needs:

1. Log in to your [SendGrid account](https://app.sendgrid.com/).
2. Go to **Settings → API Keys**.
3. Click **Create API Key**.
4. Choose **Restricted Access** and grant the minimum scopes required for your integration (for example, Marketing Campaigns for `lists`, Template Engine for `templates`, and Suppressions for `asm_groups` and suppression reads).
5. Copy the API key — SendGrid shows the full key only once.

SendGrid documentation: [Create and manage API keys](https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys).

## Using the connector

To start integrating with SendGrid:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/sendGrid/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their SendGrid API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls. Ampersand will automatically attach the customer's API key.


# ServiceNow
Source: https://docs.ampersand.ai/provider-guides/serviceNow



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `lead`, `contact`, `consumer`, `case`, `change` and `account` only. For all other objects, a full read of the ServiceNow instance will be done for each scheduled read.

* [Write Actions](/write-actions).

- **Proxy Actions**, using the base URL `https://{{.workspace}}.service-now.com`.

### Supported Objects

The ServiceNow connector supports reading and writing to and from the following objects:

* `lead` ([lead API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/lead-api.html))
* `contact` ([Contact API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/contact-api.html))
* `consumer` ([Consumer API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/consumer-api.html))
* `alarm` ([Alarm Management Open API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/alarm-open-api.html))
* `case` ([Case API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/case-api.html))
* `change` ([Change Management API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/change-management-api.html))

The ServiceNow connector only supports reading from the following objects:

* `account` ([Account API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/account-api.html))

The ServiceNow connector only supports writing to the following objects:

* `order` ([Order API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/order_csm-api.html))
* `email` ([Email API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/email-api.html))
* `entitlement` ([Entitlement API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/entitlement-api.html))
* `ai_prompt` ([AI Assets API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/ai-assets-api.html#title_ai-asset-POST-ai-prompt))
* `ai_model` ([AI Assets API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/ai-assets-api.html#title_ai-asset-ai-model-POST))
* `ai_dataset` ([AI Assets API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/ai-assets-api.html#title_ai-asset-dataset-POST-ai_dataset))
* `ai_system` ([AI Assets API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/concept/ai-assets-api.html#title_ai-asset-system-POST))

### Example Integration

For an example manifest file of a ServiceNow integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/servicenow/amp.yaml).

## Before You Get Started

To integrate ServiceNow with Ampersand, you will need [a ServiceNow Instance](https://www.servicenow.com/).

Once your instance is set up, you'll need to create a ServiceNow application and obtain the following credentials:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a ServiceNow Instance

If you don't already have a ServiceNow instance:

* Go to the [ServiceNow Developer Portal](https://developer.servicenow.com/dev.do#!/home).
* Sign up for a Personal Developer Instance (PDI).

### Creating a ServiceNow Application

Follow the steps below to create a ServiceNow application:

1. Log in to your **ServiceNow** instance.
2. Navigate to **System OAuth** > **Application Registry**.
3. Click **New** to create a new application.
4. Choose **Create an OAuth API endpoint for external clients**.
5. Fill in the required fields:
   * Name: Your application name
   * Client ID: Will be auto-generated
   * Client Secret: Will be auto-generated
6. In the **Redirect URL** field, enter: `https://api.withampersand.com/callbacks/v1/oauth`
7. Set the appropriate access and refresh token lifespan.
8. Click **Submit**.

<img alt="Alt text" />

Note the **Client ID** and **Client Secret**, as you will need them to connect your app to Ampersand.

## Add Your ServiceNow App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a *ServiceNow* integration.
3. Select **Provider Apps**.
4. Select *ServiceNow* from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field.
6. Enter the **Client Secret** in the **Client Secret** field.

<img alt="Alt text" />

7. Click **Save Changes**.


# Shopify
Source: https://docs.ampersand.ai/provider-guides/shopify



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for all supported objects.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.myshopify.com`.

### Supported objects

The Shopify connector supports reading from and writing to the following objects:

* [customers](https://shopify.dev/docs/api/admin-rest/latest/resources/customer)
* [orders](https://shopify.dev/docs/api/admin-rest/latest/resources/order)
* [products](https://shopify.dev/docs/api/admin-rest/latest/resources/product)

All supported objects support incremental read.

For objects and fields, you can also use Ampersand’s [Object Metadata APIs](/reference/objects-&-fields/get-object-metadata-via-connection) to inspect what’s available for a specific connection.

## Example integration

For an example manifest file of a Shopify integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/shopify/amp.yaml).

## Before you get started

To connect Shopify with Ampersand, you will need:

* A Shopify Partner account (to create an app): [Shopify Partners](https://partners.shopify.com/)
* A Shopify store to install and test the app. For development and testing, we recommend using a Shopify dev store. See Shopify’s documentation: [Create dev stores](https://shopify.dev/docs/apps/build/dev-dashboard/development-stores).

## Create a Shopify app

Shopify uses OAuth 2.0 (authorization code grant) for apps created in the Partner Dashboard.

For Shopify’s full, up-to-date instructions for creating an app and configuring OAuth, see Shopify’s documentation: [Create an app](https://shopify.dev/docs/apps/build/dev-dashboard/create-apps-using-dev-dashboard).

At a high level:

1. Log in to the [Shopify Partners portal](https://partners.shopify.com/) and open **Apps**.
   <img alt="Shopify Partners dashboard (Apps)" />
2. Create an app. After the app is created, you’ll land on **Create a version**.
   <img alt="Shopify Partners dashboard (Apps)" />
3. Configure the access scopes your integration needs.
   <img alt="Shopify Partners dashboard (Apps)" />
4. Configure the OAuth redirect URL:
   * `https://api.withampersand.com/callbacks/v1/oauth`
     <img alt="Shopify Partners dashboard (Apps)" />
5. Release the version. Then go to the app’s settings page and note the **Client ID** and **Client Secret**.
   <img alt="Shopify Partners dashboard (Apps)" />

### Protected customer data / approvals

Some Shopify scopes and objects (especially those that expose customer data) can require additional approval and compliance steps before Shopify will allow access.

If you see errors like “This app is not approved to access the Customer object”, use the checklist below.

* **Confirm you actually need protected customer data**: only request the minimum scopes and data required for your integration.
* **Complete Shopify’s protected customer data requirements**: follow Shopify’s guidance for requesting access and meeting the required compliance steps: [Work with protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).

#### Access to older orders

Shopify may restrict access to older orders unless you request additional scopes (for example, `read_all_orders`). See Shopify’s [Orders API documentation](https://shopify.dev/docs/api/admin-rest/latest/resources/order) for details.

## App distribution

Your app’s distribution method determines which stores can install it.

* **For installs across multiple Shopify stores**: use **Public distribution** and publish an App Store listing.
* **To keep the app from being searchable**: set the App Store listing to **limited visibility**. Merchants can still install the app from the listing URL.

Shopify documentation:

* [About app distribution](https://shopify.dev/docs/apps/launch/distribution)
* [Select a distribution method](https://shopify.dev/docs/apps/launch/distribution/select-distribution-method)
* [App listing visibility](https://shopify.dev/docs/apps/launch/distribution/visibility)
* [Submit your app for review](https://shopify.dev/docs/apps/launch/app-store-review/submit-app-for-review)

<Note>
  Shopify also supports **custom distribution** install links, but this method is limited to a single store or stores within the same Plus organization (and certain development stores). For general third-party installs, follow the public distribution path described in the section below.
</Note>

## Share your Shopify app so merchants can install it

For a merchant to connect their Shopify store, they must install and authorize your Shopify app. That install step is what grants OAuth access for their store.

If you want your app to be installable by multiple merchants, you must use **Public distribution** (an App Store listing).

If you don’t want your app to appear in Shopify App Store search results, set the listing to **limited visibility**. Merchants can still install the app using the **App Store listing URL** (available after approval).

### Make the app installable (public, limited visibility)

1. From your app’s home page, go to **App distribution**.
   <img alt="Open App distribution" />
2. Select a distribution method and choose **Public distribution**:
   * Shopify guide: [Select a distribution method](https://shopify.dev/docs/apps/launch/distribution/select-distribution-method)
     <img alt="Select Public distribution" />
3. Create an App Store listing and complete Shopify’s requirements:
   * Shopify guide: [App Store requirements](https://shopify.dev/docs/apps/launch/shopify-app-store/app-store-requirements)
     <img alt="Create App Store listing" />
4. Tell them about your business and add a credit card to pay the \$19 one-time app store registration fee.
   <img alt="Create App Store listing" />
5. Set your app listing visibility to **limited visibility** (not searchable):
   * Shopify guide: [App listing visibility](https://shopify.dev/docs/apps/launch/distribution/visibility)
6. Submit your app for review:
   * Shopify guide: [Submit your app for review](https://shopify.dev/docs/apps/launch/app-store-review/submit-app-for-review)
7. After Shopify approves your app, share the **App Store listing URL** so merchants can install it.
   <img alt="Copy App Store listing URL" />
8. Ask your customers to install the app from the App Store listing URL. For example:

```text theme={"dark"}
https://apps.shopify.com/YOUR_APP_HANDLE
```

After installation, they can complete the OAuth flow in your app (via the embedded [Install Integration](/embeddable-ui-components#install-integration) component).

## Add your Shopify app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a Shopify integration.
   <img alt="Ampersand Project Selection" />
3. Select **Provider apps**.
4. Select *Shopify* from the **Provider** list.
5. Enter the **Client ID** and **Client Secret** from your Shopify app and click **Save changes**.

## Using the connector

To start integrating with Shopify:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/shopify/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer to connect their Shopify store via OAuth.
* If your integration has [Read Actions](/read-actions), you’ll start getting webhook messages.
* If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
* If your integration has [Proxy Actions](/proxy-actions), start making Proxy API calls. Ampersand will automatically attach the OAuth credentials for the connected store.


# Slack
Source: https://docs.ampersand.ai/provider-guides/slack



## What's supported

### Supported actions

The Slack integration is available through two connectors:

* **Bot connector** — provider name: `slack`. This connector uses Slack bot token scopes.
* **User connector** — provider name: `slackUserScope`. This connector uses Slack user token scopes.

Both connectors support:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Subscribe Actions](/subscribe-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://slack.com/api`.

Both connectors use the same Slack app, OAuth configuration, client ID, client secret, and Ampersand redirect URI.
The difference between them is the Slack token type and the scopes configured for that token.

Choose the connector whose supported objects and operations match your use case.
The required Slack scopes depend on the connector and the Slack API methods used.

### Supported objects

The following matrix shows object and operation support for each Slack connector:

* **✅** — supported.
* **🚫** — the connector supports the object, but not that operation. Write may mean both or one of create/update.
* **empty** — the object is not available through that connector.

Write indicates support for one or both of the following operations: create and update.
Object access also depends on the Slack scopes granted to the installed app and, where applicable, the authorizing user's Slack permissions.

<div>
  <table>
    <thead>
      <tr>
        <th>
          Object
        </th>

        <th>
          Bot connector
        </th>

        <th>
          User connector
        </th>
      </tr>

      <tr>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>

        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

### Choose a connector

Use the **Bot connector** (`slack`) when your integration needs to operate with Slack bot token scopes.
This is the typical choice for integrations that act as an installed Slack app or bot.

Use the **User connector** (`slackUserScope`) when your integration needs to use Slack user token scopes
and perform actions on behalf of the authorizing Slack user.

### Example integration

For an example manifest file of a Slack integration, visit our [samples repo on Github](https://github.com/amp-labs/samples).
Use the sample corresponding to the connector you want to install:

| Connector | Provider name | Example manifest |
| - | - | - |
| Bot connector | `slack` | [Bot connector sample](https://github.com/amp-labs/samples/blob/main/slack/amp.yaml) |
| User connector | `slackUserScope` | [User connector sample](https://github.com/amp-labs/samples/blob/main/slack-user/amp.yaml) |

The two manifests use different provider names.

## Before you get started

To connect Slack with Ampersand, you will need [a Slack Developer Account](https://api.slack.com/developer-program/join).

Once your account is created, you'll need to create an app in Slack, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* **Bot scopes** and/or **User scopes**

You will then use these credentials to connect your application to Ampersand.

### Create a Slack Account

Here's how you can sign up for a Slack account:

* Go to the [Slack Sign Up page](https://api.slack.com/developer-program/join).
* Sign up using your preferred method and verify your email.

### Creating a Slack App

Follow the steps below to create a Slack app and add the Ampersand redirect URL.

1. Log in to your [Slack Developer](https://slack.com/signin) account.

2. Click **Your Apps**.

3. Click the **Create New App** button.

4. In the **Create a Slack App** pop-up window, enter the **App Name** and select the **Development Slack Workspace** where you want to develop your app. Click **Create App**.

5. In the left-hand sidebar, navigate to **OAuth & Permissions**.

6. In the **Redirect URLs** section, click **Add a Redirect URL** and enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

7. Click **Add** and then **Save URLs**.

8. In the **Scopes** section, add the necessary **Bot Token Scopes**/**User Token Scopes** for your app by clicking on **Add an OAuth Scope** and selecting the required scopes.

   <img alt="Slack App Creation" />

   You will find the **Client ID** and **Client Secret** in the **Basic Information** section. Note these credentials, as you will need them to connect your app to Ampersand.

## Add Your Slack App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Slack integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Slack Bot Scope** or **Slack User Scope** from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the **bot scopes** or **user scopes** set for your application in *Slack*.

   <img alt="Ampersand Integration" />

7. Click **Save Changes**.

## Using the connector

To start integrating with Slack:

* Create a manifest file like the [example above](https://github.com/amp-labs/samples/blob/main/slack/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using [Read Actions](/read-actions), create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their Slack authorization.
* Start using the connector.
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Smartlead
Source: https://docs.ampersand.ai/provider-guides/smartlead



## What's supported

### Supported actions

The Smartlead connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Smartlead instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://server.smartlead.ai/api`.

### Supported Objects

The Smartlead connector supports writing to and reading from the following objects:

* [Campaigns](https://api.smartlead.ai/reference/fetch-campaign-sequence-by-campaign-id)
* [Email Accounts](https://api.smartlead.ai/reference/fetch-all-email-accounts-associated-to-a-user)
* [Client](https://api.smartlead.ai/reference/fetch-all-clients)

### Example Integration

For an example manifest file of a Smartlead integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/smartlead/amp.yaml).

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Smartlead:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/smartlead/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Smartlead

[Click here](https://api.smartlead.ai/reference/authentication) for more information about generating an API key for Smartlead. The UI components will display this link, so that your users can successfully create API keys.


# Smartsheet
Source: https://docs.ampersand.ai/provider-guides/smartsheet



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.smartsheet.com`.

## Before You Get Started

To integrate Smartsheet with Ampersand, you need to [Create a Smartsheet Developer Account](https://developers.smartsheet.com/register/) and obtain the following credentials from your Smartsheet App:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Smartsheet Account

You need a **Smartsheet** account to connect with Ampersand. If you do not have a Smartsheet account, here's how you can sign up:

* Go to the [Smartsheet Developer site](https://developers.smartsheet.com/register/) and sign up with Smartsheet.
* Go to the registered email account and follow the activation process.

### Creating a Smartsheet App

Once your Smartsheet account is ready, you need to create a Smartsheet application. Follow the steps below to create a Smartsheet app:

1. Log in to your [Smartsheet Account](https://developers.smartsheet.com/).

2. Go to `Account → Developer Tools`.

3. Click **Create New App**.

4. On the *Create New App* form, enter the following details:
   1. **App Name**: The name of the app.
   2. **App Description**: A brief description of the app.
   3. **App URL**: The URL of the app.
   4. **App Contact/Support**: Contact or support information for the app.
   5. **App Redirect URL**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`
   6. **Logo**: Select an app logo.

5. Click **Create**.

<img alt="Smartsheet App Creation" />

The **Client ID** and **Client Secret** keys will be displayed on the app details page. Note these keys, as they are essential for connecting your app to Ampersand.

## Add Smartsheet App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Smartsheet App.

   <img alt="Ampersand Project Selection" />

3. Navigate to the **Provider Apps** section.

4. Select **Smartsheet** from the Provider list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in **Smartsheet**.

   <img alt="Ampersand Project Selection" />

7. Click **Save Changes**.


# Snapchat Ads
Source: https://docs.ampersand.ai/provider-guides/snapchatAds



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is only supported for the `transactions` object.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://adsapi.snapchat.com`.

### Supported Objects

The Snapchat Ads connector supports writing to and reading from the following objects:

* [fundingsources](https://developers.snap.com/api/marketing-api/Ads-API/funding-sources) (read)
* [billingcenters](https://developers.snap.com/api/marketing-api/Ads-API/billing-centers) (read, write)
* [transactions](https://developers.snap.com/api/marketing-api/Ads-API/transactions) (read)
* [adaccounts](https://developers.snap.com/api/marketing-api/Ads-API/ad-accounts) (read, write)
* [members](https://developers.snap.com/api/marketing-api/Ads-API/members) (read, write)
* [roles](https://developers.snap.com/api/marketing-api/Ads-API/roles) (read, write)
* [targeting/demographics/age\_group](https://developers.snap.com/api/marketing-api/Ads-API/targeting#demographics---age-groups) (read)
* [targeting/demographics/gender](https://developers.snap.com/api/marketing-api/Ads-API/targeting#demographics---gender) (read)
* [targeting/demographics/languages](https://developers.snap.com/api/marketing-api/Ads-API/targeting#demographics---language) (read)
* [targeting/demographics/advanced\_demographics](https://developers.snap.com/api/marketing-api/Ads-API/targeting#demographics---advanced-demographics) (read)
* [targeting/device/connection\_type](https://developers.snap.com/api/marketing-api/Ads-API/targeting#device---connection-type) (read)
* [targeting/device/os\_type](https://developers.snap.com/api/marketing-api/Ads-API/targeting#device---os-type) (read)
* [targeting/device/carrier](https://developers.snap.com/api/marketing-api/Ads-API/targeting#device---carrier) (read)
* [targeting/device/marketing\_name](https://developers.snap.com/api/marketing-api/Ads-API/targeting#device---make) (read)
* [targeting/geo/country](https://developers.snap.com/api/marketing-api/Ads-API/targeting#geolocation---country) (read)
* [targeting/interests/dlxs](https://developers.snap.com/api/marketing-api/Ads-API/targeting#interests---oracle-datalogix-dlx) (read)
* [targeting/interests/dlxc](https://developers.snap.com/api/marketing-api/Ads-API/targeting#get-oracle-datalogix-dlxc-interest-targeting-options) (read)
* [targeting/interests/dlxp](https://developers.snap.com/api/marketing-api/Ads-API/targeting#get-oracle-datalogix-dlxp-interest-targeting-options) (read)
* [targeting/interests/nln](https://developers.snap.com/api/marketing-api/Ads-API/targeting#get-nielsen-interest-targeting-options) (read)
* [targeting/location/categories\_loi](https://developers.snap.com/api/marketing-api/Ads-API/targeting#location---categories) (read)

### Example Integration

For an example manifest file of a Snapchat Ads integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/snapchatAds/amp.yaml).

## Before You Get Started

To integrate Snapchat Ads with Ampersand, you will need [a Snapchat Business Account](https://business.snapchat.com/).

Once your account is created, you'll need to create a Snapchat Ads app and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Snapchat Business Account

If you don't already have a Snapchat Business Account:

* Go to the [Snapchat Business website](https://business.snapchat.com/).
* Click on **Get Started** and follow the prompts to create your account.

### Creating a Snapchat Ads App

Follow the steps below to create a Snapchat Ads app:

1. Go to the [Snapchat Business Manager](https://business.snapchat.com/7f8bde4a-1c58-4472-aa24-5df12d43b474/dashboard).

2. Navigate to **Business Settings** > **Business Details**.

3. Under **Oauth Apps**, click **+ Oauth App**.

4. Fill in the required information:
   * App Name
   * OAuth 2.0 Redirect URI: Enter `https://api.withampersand.com/callbacks/v1/oauth`

5. Click **Create Oauth App**.

<img alt="Alt text" />

You will see the **Client ID** and **Client Secret** for your new app. Note these credentials, as you will need them to connect your app to Ampersand.

## Add Your Snapchat Ads App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a *Snapchat Ads* integration.
3. Select **Provider Apps**.
4. Select *Snapchat Ads* from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

<img alt="Alt text" />

6. Enter the scopes set for your application in *Snapchat*.
7. Click **Save Changes**.

## Using the connector

To start integrating with Snapchat Ads:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/snapchatAds/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Snowflake
Source: https://docs.ampersand.ai/provider-guides/snowflake



This provider is currently in private preview. Please reach out to us at [support@withampersand.com](mailto:support@withampersand.com) to get access.


# SolarWinds Service Desk
Source: https://docs.ampersand.ai/provider-guides/solarwindsServiceDesk



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `incidents` only. For all other objects, a full read of the SolarwindsServiceDesk instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.samanage.com`.

### Supported Objects

The SolarwindsServiceDesk connector supports writing to and reading from the following objects:

* [incidents](https://apidoc.samanage.com/#tag/Incident/operation/getIncidents)
* [users](https://apidoc.samanage.com/#tag/User/operation/getUsers)
* [roles](https://apidoc.samanage.com/#tag/Role/operation/getRoles)
* [problems](https://apidoc.samanage.com/#tag/Problem/operation/getProblems)
* [changes](https://apidoc.samanage.com/#tag/Change/operation/getChanges)
* [change\_catalogs](https://apidoc.samanage.com/#tag/Change-Catalog/operation/getChangeCatalogs)
* [releases](https://apidoc.samanage.com/#tag/Release/operation/getRelease)
* [solutions](https://apidoc.samanage.com/#tag/Solution/operation/getSolutions)
* [catalog\_items](https://apidoc.samanage.com/#tag/Catalog-Item/operation/getCatalogItems)
* [configuration\_items](https://apidoc.samanage.com/#tag/Configuration-Item/operation/getConfigurationItems)
* [sites](https://apidoc.samanage.com/#tag/Site/operation/getSites)
* [departments](https://apidoc.samanage.com/#tag/Department/operation/getDepartments)
* [groups](https://apidoc.samanage.com/#tag/Group/operation/getGroups)
* [categories](https://apidoc.samanage.com/#tag/Category/operation/getCategories)
* [hardwares](https://apidoc.samanage.com/#tag/Hardware/operation/getHardwares)
* [mobiles](https://apidoc.samanage.com/#tag/Mobile-Device/operation/getMobiles)
* [other\_assets](https://apidoc.samanage.com/#tag/Other-Asset/operation/getAssets)
* [contracts](https://apidoc.samanage.com/#tag/Contract/operation/getContracts)
* [purchase\_orders](https://apidoc.samanage.com/#tag/Purchase-Order/operation/getCPurchaseOrders)
* [vendors](https://apidoc.samanage.com/#tag/Vendor/operation/getVendors)

The SolarwindsServiceDesk connector supports writing only to the following objects:

* [memberships](https://apidoc.samanage.com/#tag/Membership/operation/createMembership)

The SolarwindsServiceDesk connector supports reading only from the following objects:

* [softwares](https://apidoc.samanage.com/#tag/Software/operation/getSoftwares)
* [printers](https://apidoc.samanage.com/#tag/Printer/operation/getPrinters)
* [audits](https://apidoc.samanage.com/#tag/Audit/operation/getAudits)
* [risks](https://apidoc.samanage.com/#tag/Risk/operation/getRisks)

### Example Integration

For an example manifest file of a SolarWinds Service Desk integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/solarwindsServiceDesk/amp.yaml).

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with SolarWinds Service Desk:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key provided by the customer. Please note that this connector's base URL is `https://api.samanage.com`.

## Creating an API key for SolarWinds Service Desk

1. Log in to your [SolarWinds Service Desk account](https://app.samanage.com/login).
2. Navigate to **Setup > Users & Groups > Users** and locate your **User Detail Page** (not your User Profile Card).
3. From the **User detail** page, click **Actions** and select **Generate JSON Web Token** from the dropdown menu. (SWSD administrator rights required.)
4. Under **JSON Web Token**, click **Copy** to save the token for use.

<img alt="Generate Token" />


# Square
Source: https://docs.ampersand.ai/provider-guides/square



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `gift_cards/activities`, `payments`, `payouts` and `refunds` currently. For all other objects, a full read of the Square instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://connect.squareup.com`.

### Supported objects

The Square connector supports reading from and writing to the following objects:

#### Read objects

* [bank\_accounts](https://developer.squareup.com/reference/square/bank-accounts-api)
* [bookings](https://developer.squareup.com/reference/square/bookings-api)
* [bookings/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/booking-custom-attributes-api)
* [bookings/location\_booking\_profiles](https://developer.squareup.com/reference/square/bookings-api)
* [bookings/team\_member\_booking\_profiles](https://developer.squareup.com/reference/square/bookings-api)
* [cards](https://developer.squareup.com/reference/square/cards-api)
* [catalog](https://developer.squareup.com/reference/square/catalog-api)
* [channels](https://developer.squareup.com/reference/square/channels-api)
* [customers](https://developer.squareup.com/reference/square/customers-api)
* [customers/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/customer-custom-attributes-api)
* [customers/groups](https://developer.squareup.com/reference/square/customer-groups-api)
* [customers/segments](https://developer.squareup.com/reference/square/customer-segments-api)
* [devices](https://developer.squareup.com/reference/square/devices-api)
* [devices/codes](https://developer.squareup.com/reference/square/devices-api)
* [disputes](https://developer.squareup.com/reference/square/disputes-api)
* [events/types](https://developer.squareup.com/reference/square/events-api)
* [gift\_cards](https://developer.squareup.com/reference/square/gift-cards-api)
* [gift\_cards/activities](https://developer.squareup.com/reference/square/gift-card-activities-api)
* [labor/break\_types](https://developer.squareup.com/reference/square/labor-api)
* [labor/team\_member\_wages](https://developer.squareup.com/reference/square/labor-api)
* [labor/workweek\_configs](https://developer.squareup.com/reference/square/labor-api)
* [locations](https://developer.squareup.com/reference/square/locations-api)
* [locations/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/location-custom-attributes-api)
* [loyalty/programs](https://developer.squareup.com/reference/square/loyalty-api)
* [merchants](https://developer.squareup.com/reference/square/merchants-api)
* [merchants/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/merchant-custom-attributes-api)
* [online\_checkout/payment\_links](https://developer.squareup.com/reference/square/checkout-api)
* [orders/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/order-custom-attributes-api)
* [payments](https://developer.squareup.com/reference/square/payments-api)
* [payouts](https://developer.squareup.com/reference/square/payouts-api)
* [refunds](https://developer.squareup.com/reference/square/refunds-api)
* [sites](https://developer.squareup.com/reference/square/sites-api)
* [team\_members/jobs](https://developer.squareup.com/reference/square/team-api)
* [webhooks/event\_types](https://developer.squareup.com/reference/square/webhook-subscriptions-api)
* [webhooks/subscriptions](https://developer.squareup.com/reference/square/webhook-subscriptions-api)

#### Write objects

* [bookings](https://developer.squareup.com/reference/square/bookings-api)
* [bookings/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/booking-custom-attributes-api)
* [cards](https://developer.squareup.com/reference/square/cards-api)
* [catalog](https://developer.squareup.com/reference/square/catalog-api)
* [customers](https://developer.squareup.com/reference/square/customers-api)
* [customers/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/customer-custom-attributes-api)
* [customers/groups](https://developer.squareup.com/reference/square/customer-groups-api)
* [devices/codes](https://developer.squareup.com/reference/square/devices-api)
* [gift\_cards](https://developer.squareup.com/reference/square/gift-cards-api)
* [gift\_cards/activities](https://developer.squareup.com/reference/square/gift-card-activities-api)
* [labor/break\_types](https://developer.squareup.com/reference/square/labor-api)
* [labor/workweek\_configs](https://developer.squareup.com/reference/square/labor-api)
* [locations](https://developer.squareup.com/reference/square/locations-api)
* [locations/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/location-custom-attributes-api)
* [merchants/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/merchant-custom-attributes-api)
* [online\_checkout/payment\_links](https://developer.squareup.com/reference/square/checkout-api)
* [orders/custom\_attribute\_definitions](https://developer.squareup.com/reference/square/order-custom-attributes-api)
* [payments](https://developer.squareup.com/reference/square/payments-api)
* [refunds](https://developer.squareup.com/reference/square/refunds-api)
* [team\_members/jobs](https://developer.squareup.com/reference/square/team-api)
* [webhooks/subscriptions](https://developer.squareup.com/reference/square/webhook-subscriptions-api)

### Example integration

For an example manifest file of a Square integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/square/amp.yaml).

<Note>
  For testing against Square's [sandbox environment](https://developer.squareup.com/docs/devtools/sandbox/overview), set `provider: squareSandbox` in your manifest file. This is identical to `square` except that it uses the base URL `https://connect.squareupsandbox.com`.
</Note>

## Before you get started

To integrate Square with Ampersand, you will need a [Square account](https://squareup.com/signup).

Once your account is created, you'll need to create a Square app and obtain the following credentials from it:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Square app

1. Log in to the [Square developer portal](https://developer.squareup.com/apps).
2. Click **+** to create a new application and give it a name.
3. Open the application and select the **OAuth** tab.
4. Set the redirect/callback URL to: `https://api.withampersand.com/callbacks/v1/oauth`
5. Copy the **Application ID** (Client ID) and **Application Secret** (Client Secret) from the **OAuth** page.
6. Note the [OAuth permissions (scopes)](https://developer.squareup.com/docs/oauth-api/square-permissions) your integration requires.

   <img alt="Square OAuth" />

### Add your Square app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Square integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Square** from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from your Square app.

6. Enter the scopes your integration requires.

7. Click **Save Changes**.

<img alt="Ampersand Project Selection" />

## Using the connector

To start integrating with Square:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Stripe
Source: https://docs.ampersand.ai/provider-guides/stripe



## What's supported

### Supported actions

The Stripe connector supports:

* [Read Actions](/read-actions), including full historic backfill.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.stripe.com`.

### Supported Objects

> Note: In theory, nested fields can be used with all Stripe objects.
> However, the objects marked as supporting nested fields in the tables also enable automatic expansion of related data
> via Stripe's [expand feature](https://docs.stripe.com/api/expanding_objects). For those objects,
> the connector can fetch extra fields that are not returned by default, and surface them. Field example for object `balance_transactions`: `"$['source']['payment_intent']['currency']"`.

The Stripe connector supports reading and writing to and from the following objects:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Nested Field</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

#### Treasury API

The Stripe connector supports reading and writing to and from the following Treasury API objects:

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Nested Field</th>
        <th>Subscribe</th>
      </tr>
    </thead>
  </table>
</div>

### Example integration

For an example manifest file of a Stripe integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/stripe/amp.yaml).

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Stripe:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/stripe/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Creating an API key for Stripe

[Click here](https://docs.stripe.com/keys) for more information about generating an API key for Stripe. The UI components will display this link, so that your users can successfully create API keys.


# SuperSend
Source: https://docs.ampersand.ai/provider-guides/superSend



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.supersend.io`.

### Example integration

To define an integration for SuperSend, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: superSend-integration
    displayName: My SuperSend Integration
    provider: superSend
    proxy:
      enabled: true
```

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with SuperSend:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for their API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.supersend.io`.

## Creating an API key for SuperSend

1. Log in to your [SuperSend account](https://app.supersend.io/).
2. Navigate to **Admin** > **System** tab.
3. Copy your API key from the settings.

<img alt="SuperSend API Key" />

For more details, see the [SuperSend Authentication documentation](https://docs.supersend.io/docs/authentication).


# SurveyMonkey
Source: https://docs.ampersand.ai/provider-guides/surveyMonkey



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill.
* [Write Actions](/write-actions) (create, update, and delete — depending on the object).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.surveymonkey.com`.
* Subscribe Actions are not currently supported.

### Supported objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Metadata</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-benchmark_bundles">benchmark\_bundles</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-contact_fields">contact\_fields</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-contact_lists">contact\_lists</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-contacts">contacts</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-groups">groups</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-organizations">organizations</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-question_bank-questions">question\_bank\_questions</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-roles">roles</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-survey_categories">survey\_categories</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-survey_folders">survey\_folders</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-survey_languages">survey\_languages</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-survey_templates">survey\_templates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-surveys">surveys</a></td><td><Check /></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-team_survey_templates">team\_survey\_templates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://api.surveymonkey.com/v3/docs#api-endpoints-get-workgroups">workgroups</a></td><td><Check /></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

### Notes and limitations

* **Write support**
  * `contacts`, `contact_lists`, `surveys`: create, update, and delete
  * `survey_folders`: create only
  * `contact_fields`: update only (label)
* **Not available as objects:** survey responses, collectors, survey pages, survey questions, and webhooks. Use [Proxy Actions](/proxy-actions) if you need access to other SurveyMonkey API endpoints.

### Example integration

For an example manifest file of a SurveyMonkey integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/surveyMonkey/amp.yaml).

## Before you get started

To connect SurveyMonkey with Ampersand, you need to [create a SurveyMonkey account](#create-a-surveymonkey-account) and obtain the following credentials from your SurveyMonkey app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a SurveyMonkey account

You need a **SurveyMonkey** account to connect with Ampersand. If you do not have a SurveyMonkey account, here's how you can sign up:

* Go to the [SurveyMonkey site](https://www.surveymonkey.com/).
* Sign up for a free account using your preferred method.

### Creating a SurveyMonkey app

1. Log in to the [SurveyMonkey Developer Portal](https://developer.surveymonkey.com/).

2. Click the **Create a New App** button.

3. On the *Create a New App* form, enter the following details:
   1. **App Name**: The name of the app.
   2. **App Creator**: Email address of the app owner.
   3. **Select an app type**: Specify whether the application should be private or public.

4. Click **Create App**.

   <img alt="SurveyMonkey App Details" />

   <br />

5. Click **Settings** on your app details.

6. In the Redirect URL section, click **Add Additional Redirect URL** and enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

7. Click **Submit changes**.

8. From the **Scopes** section, select the scopes required for your application. Common scopes include:
   * **View Surveys** / **Create/Modify Surveys** — for reading and writing surveys
   * **View Contacts** / **Create/Modify Contacts** — for reading and writing contacts and contact lists

9. Click **Update Scopes**.

   <img alt="SurveyMonkey App Details" />

   <br />

You can find the **Client ID** and **Client Secret** keys on the **Overview** page of your application. Note these keys, as they are essential for connecting your app to Ampersand.

Some scopes require a paid SurveyMonkey plan or additional approval for public apps. Configure only the scopes your integration uses.

## Add your SurveyMonkey app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the SurveyMonkey app.

   <img alt="Ampersand Project Selection" />

3. Navigate to the **Provider Apps** section.

4. Select **SurveyMonkey** from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

   <img alt="SurveyMonkey Integration in Ampersand" />

6. Click **Save Changes**.

## Using the connector

To start integrating with SurveyMonkey:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/surveyMonkey/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If using Read or Write actions: create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## API documentation

* [SurveyMonkey API v3](https://api.surveymonkey.com/v3/docs)


# Talkdesk
Source: https://docs.ampersand.ai/provider-guides/talkdesk



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported for `do-not-call-lists`, `record-lists`, `prompts` and `campaigns` only. For all other objects, a full read of the Talkdesk instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.talkdeskapp.com`.

### Supported Objects

The Talkdesk connector supports reading from the following objects:

* [contacts](https://docs.talkdesk.com/reference/contacts)
* [ring-groups](https://docs.talkdesk.com/reference/list-all-ring-groups)
* [do-not-call-lists](https://docs.talkdesk.com/reference/do-not-call-lists)
* [campaigns](https://docs.talkdesk.com/reference/campaigns-list)
* [record-lists](https://docs.talkdesk.com/reference/record-lists)
* [identity/activities](https://docs.talkdesk.com/reference/activities-list)
* [attributes](https://docs.talkdesk.com/reference/attributes-list)
* [attributes-categories](https://docs.talkdesk.com/reference/attributes-categories-list)
* [fsi/contacts](https://docs.talkdesk.com/reference/fetch-contacts)
* [prompts](https://docs.talkdesk.com/reference/list-a-prompt)
* [prompts-usage](https://docs.talkdesk.com/reference/get-a-prompt-usage)
* [live-queries](https://docs.talkdesk.com/reference/list-available-queries)
* [guardian/users](https://docs.talkdesk.com/reference/guardianusers)
* [guardian/logs/sessions](https://docs.talkdesk.com/reference/guardianlogssessions)
* [guardian/cases](https://docs.talkdesk.com/reference/guardian-cases)
* [guardian/calls/call-quality](https://docs.talkdesk.com/reference/calls-quality)
* [users](https://docs.talkdesk.com/reference/users)
* [scim/v2/Users](https://docs.talkdesk.com/reference/get-users)
* [scim/v2/ResourceTypes](https://docs.talkdesk.com/reference/get-service-providers-resource-types)
* [scim/v2/ResourceTypes/User](https://docs.talkdesk.com/reference/check-user-resource-type)
* [scim/v2/ServiceProviderConfig](https://docs.talkdesk.com/reference/get-service-provider-configurations)
* [account](https://docs.talkdesk.com/reference/account)
* [account/wallets](https://docs.talkdesk.com/reference/account-wallet-list)
* [account/bucket-configurations](https://docs.talkdesk.com/reference/bucket-configurations)
* [cm/core/va/cases](https://docs.talkdesk.com/reference/get-case-list)
* [cm/meta/va/fields](https://docs.talkdesk.com/reference/get-a-list-of-case-fields)
* [bulk-imports/users](https://docs.talkdesk.com/reference/get-list-of-imports)
* [cfm/flows/external/results](https://docs.talkdesk.com/reference/collect-feedback-data)
* [express/accounts](https://docs.talkdesk.com/reference/billing-insights-get-accounts)
* [express/products](https://docs.talkdesk.com/reference/billing-insights-get-products)
* [express/subscriptions](https://docs.talkdesk.com/reference/billing-insights-get-subscriptions)
* [express/invoices](https://docs.talkdesk.com/reference/billing-insights-get-invoices)
* [express/usage/month](https://docs.talkdesk.com/reference/billing-insights-get-monthly-usage)
* [industries-scheduler/teams](https://docs.talkdesk.com/reference/get-teams)
* [industries-scheduler/appointments](https://docs.talkdesk.com/reference/get-appointments)

The Talkdesk connector supports writing to the following objects:

* [do-not-call-lists](https://docs.talkdesk.com/reference/do-not-call-lists-1)
* [campaigns](https://docs.talkdesk.com/reference/createduplicate-campaign)
* [record-lists](https://docs.talkdesk.com/reference/record-lists-1)
* [digital-connect/conversations](https://docs.talkdesk.com/reference/start-conversation)
* [attributes](https://docs.talkdesk.com/reference/new-attribute)
* [attributes-categories](https://docs.talkdesk.com/reference/new-attribute-category)
* [wfm/aion/externals/schedules/time-offs](https://docs.talkdesk.com/reference/create-a-time-off)
* [fsi-workspace/contacts/synchronizations-from-core](https://docs.talkdesk.com/reference/sync-a-talkdesk-contact)
* [fsi/transfers/internal](https://docs.talkdesk.com/reference/create-transfer-internal)
* [fsi/transfers/external](https://docs.talkdesk.com/reference/create-a-transfer-external)
* [fsi/transfers/international](https://docs.talkdesk.com/reference/create-a-transfer-international)
* [prompts](https://docs.talkdesk.com/reference/create-a-prompt)
* [prompts-requests](https://docs.talkdesk.com/reference/request-link-to-upload-audio-file)
* [live-subscriptions](https://docs.talkdesk.com/reference/subscribe-to-a-new-stream)
* [interaction-custom-fields](https://docs.talkdesk.com/reference/interaction-custom-fields)
* [scim/v2/Users](https://docs.talkdesk.com/reference/create-user)
* [cm/core/va/cases](https://docs.talkdesk.com/reference/create-a-new-case)
* [express/provisioning/account](https://docs.talkdesk.com/reference/instantiate-a-trial)
* [eas/simulated-emails](https://docs.talkdesk.com/reference/send-a-simulated-message)
* [industries-scheduler/availabilities](https://docs.talkdesk.com/reference/collecting-user-availability)
* [industries-scheduler/appointment](https://docs.talkdesk.com/reference/create-calendar-event)

### Example integration

For an example manifest file of a Talkdesk integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/talkdesk/amp.yaml).

## Before You Get Started

To integrate Talkdesk with Ampersand, you will need [a Talkdesk Account](https://www.Talkdesk.com/).

Once your account is created, you'll need to register an OAuth app and obtain the following credentials:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Talkdesk OAuth App

Follow the steps below to create a Talkdesk OAuth app:

1. Log in to your Talkdesk workspace.
2. Go to **Builder** > **OAuth Clients**.
3. In the OAuth 2.0 section, click on **Create OAuth client**.
4. Enter the following details:
   1. **OAuth client name:** Choose a name for your OAuth client.
   2. **Grant type:** Select the Authorization Code and Refresh Token as grant type.
   3. **Redirect URI:** Enter `https://api.withampersand.com/callbacks/v1/oauth`.
   4. **Scopes:** Select the scopes you want to use for your application from the list of available scopes.
5. Click **Create**.

<img alt="Alt text" />

You will see the **Client ID** and **Client Secret** in a popup. Note these credentials, as you will need them to connect your app to Ampersand.

## Add Your Talkdesk App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a *Talkdesk* integration.
3. Select **Provider Apps**.
4. Select *Talkdesk* from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

<img alt="Alt text" />

6. Enter the scopes set for your application in *Talkdesk*.
7. Click **Save Changes**.


# Teamleader
Source: https://docs.ampersand.ai/provider-guides/teamleader



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `companies`, `contacts`, `creditNotes`, `deals`, `invoices`, `products` and `projects` currently. For all other objects, a full read of the Teamleader instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.focus.teamleader.eu`.

### Supported objects

The teamleader connector supports reading from the following objects:

* [activityTypes](https://developer.focus.teamleader.eu/docs/api/activity-types-list)
* [callOutcomes](https://developer.focus.teamleader.eu/docs/api/call-outcomes-list)
* [calls](https://developer.focus.teamleader.eu/docs/api/calls-list)
* [closingDays](https://developer.focus.teamleader.eu/docs/api/closing-days-list)
* [commercialDiscounts](https://developer.focus.teamleader.eu/docs/api/commercial-discounts-list)
* [companies](https://developer.focus.teamleader.eu/docs/api/companies-list)
* [contacts](https://developer.focus.teamleader.eu/docs/api/contacts-list)
* [creditNotes](https://developer.focus.teamleader.eu/docs/api/credit-notes-list)
* [customFieldDefinitions](https://developer.focus.teamleader.eu/docs/api/custom-field-definitions-list)
* [dealPhases](https://developer.focus.teamleader.eu/docs/api/deal-phases-list)
* [dealPipelines](https://developer.focus.teamleader.eu/docs/api/deal-pipelines-list)
* [dealSources](https://developer.focus.teamleader.eu/docs/api/deal-sources-list)
* [deals](https://developer.focus.teamleader.eu/docs/api/deals-list)
* [departments](https://developer.focus.teamleader.eu/docs/api/departments-list)
* [events](https://developer.focus.teamleader.eu/docs/api/events-list)
* [files](https://developer.focus.teamleader.eu/docs/api/files-list)
* [invoices](https://developer.focus.teamleader.eu/docs/api/invoices-list)
* [mailTemplates](https://developer.focus.teamleader.eu/docs/api/mail-templates-list)
* [meetings](https://developer.focus.teamleader.eu/docs/api/meetings-list)
* [milestones](https://developer.focus.teamleader.eu/docs/api/milestones-list)
* [orders](https://developer.focus.teamleader.eu/docs/api/orders-list)
* [paymentMethods](https://developer.focus.teamleader.eu/docs/api/payment-methods-list)
* [priceLists](https://developer.focus.teamleader.eu/docs/api/price-lists-list)
* [productCategories](https://developer.focus.teamleader.eu/docs/api/product-categories-list)
* [products](https://developer.focus.teamleader.eu/docs/api/products-list)
* [projects](https://developer.focus.teamleader.eu/docs/api/projects-list)
* [quotations](https://developer.focus.teamleader.eu/docs/api/quotations-list)
* [subscriptions](https://developer.focus.teamleader.eu/docs/api/subscriptions-list)
* [tags](https://developer.focus.teamleader.eu/docs/api/tags-list)
* [tasks](https://developer.focus.teamleader.eu/docs/api/tasks-list)
* [taxRates](https://developer.focus.teamleader.eu/docs/api/tax-rates-list)
* [teams](https://developer.focus.teamleader.eu/docs/api/teams-list)
* [tickets](https://developer.focus.teamleader.eu/docs/api/tickets-list)
* [ticketStatus](https://developer.focus.teamleader.eu/docs/api/ticket-status-list)
* [timeTracking](https://developer.focus.teamleader.eu/docs/api/time-tracking-list)
* [unitsOfMeasure](https://developer.focus.teamleader.eu/docs/api/units-of-measure-list)
* [users](https://developer.focus.teamleader.eu/docs/api/users-list)
* [withholdingTaxRates](https://developer.focus.teamleader.eu/docs/api/withholding-tax-rates-list)
* [workTypes](https://developer.focus.teamleader.eu/docs/api/work-types-list)

The teamleader connector supports writing to the following objects:

* [calls](https://developer.focus.teamleader.eu/docs/api/calls-add)
* [contacts](https://developer.focus.teamleader.eu/docs/api/contacts-add)
* [companies](https://developer.focus.teamleader.eu/docs/api/companies-add)
* [deals](https://developer.focus.teamleader.eu/docs/api/deals-create)
* [events](https://developer.focus.teamleader.eu/docs/api/events-create)
* [dealPipelines](https://developer.focus.teamleader.eu/docs/api/deal-pipelines-create)
* [dealPhases](https://developer.focus.teamleader.eu/docs/api/deal-phases-create)
* [quotations](https://developer.focus.teamleader.eu/docs/api/quotations-create)
* [subscriptions](https://developer.focus.teamleader.eu/docs/api/subscriptions-create)
* [tasks](https://developer.focus.teamleader.eu/docs/api/tasks-create)
* [timeTracking](https://developer.focus.teamleader.eu/docs/api/time-tracking-add)
* [tickets](https://developer.focus.teamleader.eu/docs/api/tickets-create)

## Before You Get Started

To connect Teamleader with Ampersand, you will need a [Teamleader Account](https://www.teamleader.eu/).

Once your account is created, you'll need to configure an app in Teamleader and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a Teamleader Account

Here's how you can sign up for a Teamleader account:

1. Go to the [Teamleader Sign Up page](https://signup.focus.teamleader.eu/?_gl=1*9qfeak*_gcl_au*Mjc4MzM1MzY4LjE3MjI0MTA5MDU.).
2. Sign up using your preferred method.

### Creating a Teamleader App

Follow the steps below to create a Teamleader app and add the Ampersand redirect URL:

1. Log in to your [Teamleader Marketplace](https://marketplace.teamleader.eu/eu/en/build) account using your credentials.

2. Click **Develop Your Integration**.

3. Go to the **My Apps** tab.

4. Click **Create New Integration**.

5. Enter a name for the integration and click **Create Integration**.

6. In the **Oauth2 Credentials >> Valid redirect URIs**, enter the Ampersand redirect URL `https://api.withampersand.com/callbacks/v1/oauth`.\
   **Note:** The *Oauth2 Credentials* section also displays the **Client ID** and **Client Secret** of your application. Note these keys, as they are essential for connecting your app to Ampersand.

7. Select the necessary scopes based on your App's requirements.

8. Click **Save**.\\
   <img alt="Ampersand Project" />

### Add Your Teamleader App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Choose the project where you want to integrate Teamleader.

   <img alt="Ampersand Project" />

3. Navigate to the **Provider Apps** section.

4. Select *Teamleader* from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from Teamleader into the respective fields in Ampersand.

   <img alt="Dashboard" />

6. Click **Save Changes**.

To start integrating with teamleader:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/teamleader/amp.yml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Teamwork
Source: https://docs.ampersand.ai/provider-guides/teamwork



## What's Supported

### Supported Actions

This connector supports:

* [Write Actions](/write-actions).
* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.teamwork.com`.

### Supported Objects

The Teamwork connector supports reading from and writing to the following objects:

* [categories](https://apidocs.teamwork.com/docs/teamwork/v3/categories/get-projects-api-v3-projects-teamwork-categories-json)
* [comments](https://apidocs.teamwork.com/docs/teamwork/v3/comments/get-projects-api-v3-comments-json)
* [companies](https://apidocs.teamwork.com/docs/teamwork/v3/companies/get-projects-api-v3-companies-json)
* [dashboards](https://apidocs.teamwork.com/docs/teamwork/v3/dashboards/get-projects-api-v3-dashboards-json)
* [forms](https://apidocs.teamwork.com/docs/teamwork/v3/forms/get-projects-api-v3-forms-json)
* [jobroles](https://apidocs.teamwork.com/docs/teamwork/v3/job-roles/get-projects-api-v3-jobroles-json)
* [me/timers](https://apidocs.teamwork.com/docs/teamwork/v3/time-tracking/get-projects-api-v3-me-timers-json)
* [messages](https://apidocs.teamwork.com/docs/teamwork/v3/messages/get-projects-api-v3-messages-json)
* [milestones](https://apidocs.teamwork.com/docs/teamwork/v3/milestones/get-projects-api-v3-milestones-json)
* [notebooks](https://apidocs.teamwork.com/docs/teamwork/v3/notebooks/get-projects-api-v3-notebooks-json)
* [people](https://apidocs.teamwork.com/docs/teamwork/v3/people/get-projects-api-v3-people-json)
* [projects](https://apidocs.teamwork.com/docs/teamwork/v3/projects/get-projects-api-v3-projects-json)
* [tags](https://apidocs.teamwork.com/docs/teamwork/v3/tags/get-projects-api-v3-tags-json)
* [tasklists](https://apidocs.teamwork.com/docs/teamwork/v3/task-lists/get-projects-api-v3-tasklists)
* [tasks](https://apidocs.teamwork.com/docs/teamwork/v3/tasks/get-projects-api-v3-tasks-json)
* [time](https://apidocs.teamwork.com/docs/teamwork/v3/time-tracking/get-projects-api-v3-time-json)
* [timers](https://apidocs.teamwork.com/docs/teamwork/v3/time-tracking/get-projects-api-v3-timers-json)
* [timesheets](https://apidocs.teamwork.com/docs/teamwork/v3/timesheets/get-projects-api-v3-timesheets-json)
* [updates](https://apidocs.teamwork.com/docs/teamwork/v3/project-updates/get-projects-api-v3-projects-updates-json)

## Before You Get Started

To connect Teamwork with Ampersand, you will need a [Teamwork Account](https://www.teamwork.com/signup/).

Once your account is created, you'll need to configure an app in Teamwork and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a Teamwork Account

Here's how you can sign up for a Teamwork account:

1. Go to the [Teamwork Sign Up page](https://www.teamwork.com/signup/).
2. Sign up using your preferred method.

### Creating a Teamwork App

Follow the steps below to create a Teamwork app and add the Ampersand redirect URL:

1. Log in to the [Teamwork Developer Portal](https://www.teamwork.com/launchpad/login/developer/).

2. Click on **Create New App**.

3. Enter App Details:
   * **App Name:** Enter a descriptive name for your application.
   * **Description:** Provide a brief description of what your app does.
   * **Redirect URI:** Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`

4. Click **Create App**.

Once your app is created, you can click on the app and go to the **Credentials** tab to get **Client ID** and **Client Secret** for your app.

**Note:** Make sure to securely note down the **Client ID** and **Client Secret** as you will need these credentials to connect your app to Ampersand.

<img alt="Teamwork App Credentials" />

### Add Your Teamwork App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a *Teamwork* integration.

   <img alt="Ampersand Project" />

3. Select **Provider apps**.

4. Select *Teamwork* from the **Provider** list.

5. Enter the previously obtained **Client ID** and **Client Secret** in the respective fields.

   <img alt="Ampersand Constant Contact Integration" />

6. Click **Save Changes**.


# Timely
Source: https://docs.ampersand.ai/provider-guides/timely



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.timelyapp.com`.

## Before You Get Started

To connect Timely with Ampersand, you will need a [Timely Account](https://app.timelyapp.com/join).

Once your account is created, you'll need to create an app in Timely, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Timely Account

Here's how you can sign up for a Timely account:

* Go to the [Timely Sign Up page](https://app.timelyapp.com/join).
* Sign up using your preferred method and verify your email.

### Creating a Timely App

Follow the steps below to create a Timely app and add the Ampersand redirect URL.

1. Log in to your [Timely](https://auth.memory.ai/login) account.

2. Click **Devs**.

3. Click the **New Application** button.

4. In the **Register New OAuth application** window, enter the **App Name**. Enter the Ampersand redirect URL in **Redirect URL**: `https://api.withampersand.com/callbacks/v1/oauth`.

5. Click **Submit**.

   <img alt="Timely App Creation" />

   You will find the **Client ID** and **Client Secret** in the **Basic Information** section. Keep these credentials handy to connect your app to Ampersand later.

## Add Your Timely App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Timely integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Timely** from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

   <img alt="Ampersand Integration" />

6. Click **Save Changes**.


# Tipalti
Source: https://docs.ampersand.ai/provider-guides/tipalti



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api-p.tipalti.com`.

### Example integration

To define an integration for Tipalti, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: tipalti-integration
    displayName: My Tipalti Integration
    provider: tipalti
    proxy:
      enabled: true
```

## Before You Get Started

To connect Tipalti with Ampersand, you will need a [Tipalti Account](https://tipalti.com/).

Once your account is created, you'll need to configure an app in Tipalti and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Creating a Tipalti App

Follow the steps below to create a Tipalti app and add the Ampersand redirect URL:

1. Log in to your [Tipalti SSO Portal](https://login.tipalti.com/login/hub).

2. Navigate to **Administration** in the left sidebar.

3. Click on **API Management** or **Developer Settings**.

4. Click the **Register New Application** button.

5. In the application registration form, enter the following details:
   * **Application Name**: Enter a descriptive name for your application
   * **Application Description**: Provide a brief description of your integration
   * **Redirect URI**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`
   * **Scopes**: Select the required permissions for your integration

6. Click **Register Application**.

7. Once your app is registered, you'll be redirected to the application details page where you can find your **Client ID** and **Client Secret**.

**Note**: Make sure to securely store the **Client ID** and **Client Secret** as you will need these credentials to connect your app to Ampersand.

### Add Your Tipalti App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Tipalti integration.

   <img alt="Ampersand Project" />

3. Select **Provider apps**.

4. Select *Tipalti* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Click **Save changes**.

## Using the connector

To start integrating with Tipalti:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## API documentation

For more information on the Tipalti API, visit the [Tipalti API documentation](https://documentation.tipalti.com/docs/getting-started).


# Vtiger
Source: https://docs.ampersand.ai/provider-guides/vtiger



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions).
  * If your instance name is **your\_instance.odx**, the base URL for API requests will be: https\://your\_instance.odx/restapi.

### Example integration

To define an integration for vtiger, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: vtiger-integration
    displayName: Vtiger
    provider: vtiger
    proxy:
      enabled: true
```

## Using the connector

This connector uses Basic Auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with vtiger:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their username and password.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the correct header required by Basic Auth. Please note that if your instance name is **your\_instance.odx**, then the connector's base URL will be: https\://your\_instance.odx/restapi.


# Wealthbox
Source: https://docs.ampersand.ai/provider-guides/wealthbox



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.crmworkspace.com`.

### Example integration

To define an integration for Wealthbox, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: wealthbox-integration
    displayName: My Wealthbox Integration
    provider: wealthbox
    proxy:
      enabled: true
```

## Before You Get Started

To use the Wealthbox connector, your customer will need a Wealthbox **API access token**.

Here's how a user can create one:

1. Log in to [Wealthbox](https://app.crmworkspace.com/).
2. Open **Settings** from the three-dot menu.
3. Go to **API Access** (`https://app.crmworkspace.com/settings/access_tokens`).
4. Click **Create Access Token**.
5. Enter a label for the token and click **Save**.
6. Copy the generated token — this is the value your customer will supply to Ampersand.

<Note>
  If **API Access** isn't available on the account, the customer must email `support@wealthbox.com` to request access.
</Note>

For more information, see the [Wealthbox API documentation](https://dev.wealthbox.com/) and their [help article on creating an API access token](https://help.wealthbox.com/hc/en-us/articles/29980458723739-How-do-I-create-an-API-access-token).

## Using the connector

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)

To start integrating with Wealthbox:

* Create a manifest file like the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their API access token.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.crmworkspace.com`.

For detailed information about available endpoints and request formats, refer to the [Wealthbox API Reference](https://dev.wealthbox.com/).


# Webex
Source: https://docs.ampersand.ai/provider-guides/webex



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historical backfill and incremental read.
* [Write Actions](/write-actions), including create and update operations.
* [Proxy Actions](/proxy-actions), using the base URL `https://webexapis.com`.

### Supported Objects

The Webex connector supports the following objects from the API:

* [people](https://developer.webex.com/docs/api/v1/people/list-people) (Read, Write)
* [groups](https://developer.webex.com/admin/docs/api/v1/groups) (Read, Write)
* [roles](https://developer.webex.com/docs/api/v1/roles/list-roles) (Read only)
* [events](https://developer.webex.com/docs/api/v1/events/list-events) (Read only)
* [organizations](https://developer.webex.com/docs/api/v1/organizations/list-organizations) (Read only)
* [reports](https://developer.webex.com/admin/docs/api/v1/reports/list-reports) (Read only)
* [meetings](https://developer.webex.com/meeting/docs/meetings) (Read, Write)

## Before you get started

To integrate Webex with Ampersand, you will need [a Cisco Webex Account](https://www.webex.com/signup).

Once your account is created, you'll need to create an integration in Webex and obtain the following credentials from your integration:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a Webex Integration

<Note>
  The Admin API is a superset of user-level APIs. Some objects (such as events,
  organizations, and reports) require organization-level admin scopes, while
  others (such as meetings) can be accessed with user-level scopes. Refer to the
  [Webex API documentation](https://developer.webex.com) to determine which
  account type and scopes are required for your use case.
</Note>

Follow the steps below to create a Cisco Webex integration and add the Ampersand redirect URL to the integration:

1. Log in to your [Webex Developer Portal](https://developer.webex.com/) account.

2. Click **My Apps** in the top navigation.

3. Click **Create a New App**.

4. Select **Integration** as the app type.

5. Enter your **App Name**.

6. Enter a **Description** for your integration.

7. Enter Ampersand's **Redirect URI**: `https://api.withampersand.com/callbacks/v1/oauth`.

8. Under **Scopes**, select the necessary [Scopes](https://developer.webex.com/create/docs/integrations#scopes) for your integration.

9. Click **Add Integration**.

<img alt="Alt text" />

On the next screen, you'll see a **Client ID** and **Client Secret** have been generated.

You'll use these credentials while connecting your app to Ampersand.

## Add Your Webex App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Webex integration.

<img alt="Ampersand Project Selection" />

3. Select **Provider apps**.

4. Select *Webex* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Click **Save changes**.

## Using the connector

To start integrating with Webex:

* Create a manifest file.

* Deploy it using the [amp CLI](/cli/overview).

* If you're using Read Actions, create a [destination](/destinations).

* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. This UI component will prompt the customer for OAuth authorization.

* Start using the connector!

  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Webflow
Source: https://docs.ampersand.ai/provider-guides/webflow



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.webflow.com`.

## Before You Get Started

To connect Webflow with Ampersand, you need to [Create a Webflow Account](#create-a-webflow-account) and obtain the following credentials from your Webflow App:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Webflow Account

You need a **Webflow** account to connect with Ampersand. If you do not have a Webflow account, here's how you can sign up:

* Go to the [Webflow site](https://webflow.com/) and sign up for a free account using your preferred method.

### Creating a Webflow App

Once your Webflow account is ready, you need to create a Webflow application. Learn more about creating a Webflow application [here](https://developers.webflow.com/).

1. Log in to the [Webflow Developer Portal](https://developers.webflow.com/).

2. Go to **App and Integrations**.

3. Click on **Create a New App**.

4. On the Create a New App form, enter the following details:
   1. **App Name**: The name of the app.
   2. **App Description**: Description for the app.
   3. **App icon**: Select an app icon.
   4. **App homepage URL**: Enter an app homepage URL.

5. Click **Continue**.

6. Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` in the **Redirect URI** section.

7. Choose the scopes that are applicable for your application.

8. Click **Create App**.

You can find the **Client ID** and **Client Secret** keys on the app details page. Note these keys, as they are essential for connecting your app to Ampersand.

## Add Webflow App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Webflow App.

3. Navigate to the **Provider Apps** section.

4. Select **Webflow** from the Provider list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in **Webflow**.

7. Click **Save Changes**.


# Whereby
Source: https://docs.ampersand.ai/provider-guides/whereby



## What's Supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.whereby.dev`.

### Example integration

To define an integration for Whereby, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations: 
  - name: whereBy-integration
    displayName: Whereby
    provider: whereby
    proxy:
      enabled: true
```

## Using the connector

This connector uses **API Key authentication**, so you do not need to configure a Provider App before getting started. (Provider Apps are only required for providers using the **OAuth2 Authorization Code grant type**.)

To integrate with Whereby:

* Create a manifest file similar to the example above.
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component, which will prompt the customer for an API key.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key provided by the customer. Please note that this connector's base URL is `https://api.whereby.dev`.

## Creating an API key for Whereby

1. Log in to your [Whereby account](https://whereby.com/user/login).
2. Navigate to **Configure** and click **Generate Key**.
3. Add **Key name** and click **save**

<img alt="Generate Token" />


# WordPress
Source: https://docs.ampersand.ai/provider-guides/wordpress



## What's Supported

### Supported Actions

This connector supports:

* **Proxy Actions**, using the base URL `https://public-api.wordpress.com`.

## Before You Get Started

To integrate WordPress with Ampersand, you will need [a WordPress](https://wordpress.com/home/mywebsite4128.wordpress.com) Account.

Once your account is created, you'll need to register an OAuth app and obtain the following credentials:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a WordPress Account

Here's how you can sign up for a WordPress account:

* Go to the [WordPress.com Sign Up page](https://wordpress.com/start/user-social?ref=logged-out-homepage-lp).
* Sign up using your preferred method and complete any necessary verification.

### Creating a WordPress OAuth App

Follow the steps below to create a WordPress OAuth app:

1. Go to the [WordPress Developer](https://developer.wordpress.com/apps/) and log in using your credentials.
2. Click on **Create New Application**.
3. Enter the following details:
   1. **Name:** Choose a name for your application.
   2. **Description:** Provide a brief description of your app's purpose.
   3. **Website URL:** Enter your application's website URL.
   4. **Redirect URL:** Enter `https://api.withampersand.com/callbacks/v1/oauth`.
   5. **Type:** Select "Web" as the application type.
   6. **OAuth2 Grant Type:** Choose **Authorization Code Grant**.
4. Select the appropriate permissions for your application.
5. Click **Create**.

<img alt="Alt text" />

You will see the **Client ID** and **Client Secret** in the app details. Note these credentials, as you will need them to connect your app to Ampersand.

## Add Your WordPress App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a *WordPress* integration.
3. Select **Provider Apps**.
4. Select *WordPress* from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.
6. Enter the scopes set for your application in *Wordpress*.

<img alt="Alt text" />

7. Click **Save Changes**.


# Workday
Source: https://docs.ampersand.ai/provider-guides/workday



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.workday.com`.

### Example integration

To define an integration for Workday, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: workday-integration
    displayName: My Workday Integration
    provider: workday
    proxy:
      enabled: true
```

## Before you get started

To connect Workday with Ampersand, you will need a Workday tenant with administrator access.

Once your tenant is set up, you'll need to register an API client in Workday and obtain the following credentials:

* Client ID
* Client Secret

You will also need the following information about your Workday environment:

* **Workday Host**: Your Workday implementation hostname (e.g., `wd2-impl-services1`).
* **Tenant Name**: The name of your Workday tenant.

You will then use these credentials to connect your application to Ampersand.

### Creating a Workday API client

1. Log in to your **Workday** tenant as an administrator.

2. Search for the **Register API Client** task in the Workday search bar.

3. Enter the following details:
   * **Client Name**: The name of your integration.
   * **Grant Type**: Select **Authorization Code Grant**.

4. Under **Redirection URIs**, add: `https://api.withampersand.com/callbacks/v1/oauth`

5. Select the **Scope (Functional Areas)** required for your integration.

6. Click **Done**. Note the **Client ID** and **Client Secret**. You will need these to connect your app to Ampersand.

For more details, see the [Workday documentation](https://doc.workday.com/).

### Add your Workday app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Workday integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Workday** from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from your Workday API client.

6. Click **Save Changes**.

## Using the connector

To start integrating with Workday:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their Workday Host and Tenant Name, then guide them through OAuth authorization.
* Start using the connector!
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.


# Wrike
Source: https://docs.ampersand.ai/provider-guides/wrike



## What's Supported

### Supported Actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://www.wrike.com/api`.

## Before You Get Started

To connect Wrike with Ampersand, you will need [a Wrike Account](https://www.wrike.com/vaq/).

Once your account is created, you'll need to register an app in the Wrike portal, configure the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials to connect your application to Ampersand.

### Create a Wrike Account

Here's how you can sign up for a Wrike account:

* Go to the [Wrike developers page](https://developers.wrike.com/getting-started).
* Click "Start Building" and register for a free account using your preferred method.

### Register a Wrike App

Follow the steps below to register a Wrike app:

1. Go to [Wrike Developers](https://developers.wrike.com/).

2. Enter the following details in the **Register your app** section:
   1. **Full name**: Enter your name.
   2. **Business email**: Enter the email associated with your Wrike account.
   3. **App name**: Enter your app name.
   4. **Your App description**: Enter your app description.

3. Accept the Wrike Developer privacy policy statement.

4. Click **Register app**.

   <br />

   <img alt="Wrike App Creation" />

### Configure your Wrike App

1. Log in to your [Wrike Account](https://www.wrike.com/).

2. Navigate to `Settings >> Apps and Integrations >> API`.

3. Click **Configure** in your app.

4. In the **Redirect URI** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

5. Click **Save**.

You will find the **Client ID** and **Client Secret** in the **Oauth** section. Note these credentials, as you will need them to connect your app to Ampersand.

<img alt="Wrike App Creation" />

## Add Your Wrike App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Wrike integration.

   <img alt="Ampersand Project Selection" />

3. Select **Provider Apps**.

4. Select **Wrike** from the **Provider** list.

5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.

6. Enter the scopes set for your application in *Wrike*.

   <img alt="Ampersand Integration" />

7. Click **Save Changes**.


# Xero
Source: https://docs.ampersand.ai/provider-guides/xero



## What's supported

### Supported actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is supported only for `accounts`, `contacts`, `bankTransactions`, `bankTransfers`, `batchPayments`, `creditNotes`, `items`, `journals`, `manualJournals`, `overpayments`, `payments`, `prepayments`, `purchaseOrders` and `users`. For all other objects, a full read of the Xero instance will be done per scheduled read.
* [Write Actions](/write-actions).

### Supported objects

The Xero connector supports reading from the following objects:

* [accounts](https://developer.xero.com/documentation/api/accounting/accounts)
* [contacts](https://developer.xero.com/documentation/api/accounting/contacts)
* [bankTransactions](https://developer.xero.com/documentation/api/accounting/banktransactions)
* [bankTransfers](https://developer.xero.com/documentation/api/accounting/banktransfers)
* [batchPayments](https://developer.xero.com/documentation/api/accounting/batchpayments)
* [brandingThemes](https://developer.xero.com/documentation/api/accounting/brandingthemes)
* [budgets](https://developer.xero.com/documentation/api/accounting/budgets)
* [contactGroups](https://developer.xero.com/documentation/api/accounting/contactgroups)
* [creditNotes](https://developer.xero.com/documentation/api/accounting/creditnotes)
* [currencies](https://developer.xero.com/documentation/api/accounting/currencies)
* [invoices](https://developer.xero.com/documentation/api/accounting/invoices)
* [items](https://developer.xero.com/documentation/api/accounting/items)
* [journals](https://developer.xero.com/documentation/api/accounting/journals)
* [linkedTransactions](https://developer.xero.com/documentation/api/accounting/linkedtransactions)
* [manualJournals](https://developer.xero.com/documentation/api/accounting/manualjournals)
* [organisation](https://developer.xero.com/documentation/api/accounting/organisation)
* [overpayments](https://developer.xero.com/documentation/api/accounting/overpayments)
* [paymentServices](https://developer.xero.com/documentation/api/accounting/paymentservices)
* [payments](https://developer.xero.com/documentation/api/accounting/payments)
* [prepayments](https://developer.xero.com/documentation/api/accounting/prepayments)
* [purchaseOrders](https://developer.xero.com/documentation/api/accounting/purchaseorders)
* [quotes](https://developer.xero.com/documentation/api/accounting/quotes)
* [repeatingInvoices](https://developer.xero.com/documentation/api/accounting/repeatinginvoices)
* [reports](https://developer.xero.com/documentation/api/accounting/reports)
* [taxRates](https://developer.xero.com/documentation/api/accounting/taxrates)
* [trackingCategories](https://developer.xero.com/documentation/api/accounting/trackingcategories)
* [users](https://developer.xero.com/documentation/api/accounting/users)

The Xero connector supports writing to the following objects:

* [bankTransactions](https://developer.xero.com/documentation/api/accounting/banktransactions)
* [bankTransfers](https://developer.xero.com/documentation/api/accounting/banktransfers)
* [contactGroups](https://developer.xero.com/documentation/api/accounting/contactgroups)
* [trackingCategories](https://developer.xero.com/documentation/api/accounting/trackingcategories)
* [taxRates](https://developer.xero.com/documentation/api/accounting/taxrates)
* [quotes](https://developer.xero.com/documentation/api/accounting/quotes)
* [purchaseOrders](https://developer.xero.com/documentation/api/accounting/purchaseorders)
* [paymentServices](https://developer.xero.com/documentation/api/accounting/paymentservices)
* [manualJournals](https://developer.xero.com/documentation/api/accounting/manualjournals)
* [linkedTransactions](https://developer.xero.com/documentation/api/accounting/linkedtransactions)
* [items](https://developer.xero.com/documentation/api/accounting/items)
* [invoices](https://developer.xero.com/documentation/api/accounting/invoices)
* [currencies](https://developer.xero.com/documentation/api/accounting/currencies)
* [creditNotes](https://developer.xero.com/documentation/api/accounting/creditnotes)
* [contacts](https://developer.xero.com/documentation/api/accounting/contacts)

### Example integration

For an example manifest file of a Xero integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/xero/amp.yaml).

## Before you get started

To integrate Xero with Ampersand, you will need a [Xero developer account](https://developer.xero.com/).

Once your account is created, you'll need to create an app in Xero, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* [Scopes](https://developer.xero.com/documentation/guides/oauth2/scopes)

You will then use these credentials and scopes to connect your application to Ampersand.

### Creating a Xero app

Follow the steps below to create a Xero app in the Xero developer console:

1. Sign in to the [Xero developer portal](https://developer.xero.com/).
2. Open the [My apps](https://developer.xero.com/app/manage) page.
3. Click **New app** (or **Create app**).
4. Enter your app name, company/website, and set the Redirect URI to the Ampersand callback URI: `https://api.withampersand.com/callbacks/v1/oauth`.
5. Save the app and copy the **Client ID** and **Client Secret** shown on the app details page.
   <img alt="Alt text" />

## Add Your Xero app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Xero integration.

   <img alt="Alt text" />

3. Select **Provider apps**.

4. Select *Xero* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Enter the [scopes](https://developer.xero.com/documentation/oauth2/scopes) set for your application.

7. Click **Save changes**.

<img alt="Alt text" />

## Using the connector

To start integrating with Xero:

* Create a manifest file using the [example](https://github.com/amp-labs/samples/blob/main/xero/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.


# Zendesk Support
Source: https://docs.ampersand.ai/provider-guides/zendeskSupport



## What's Supported

### Supported Actions

The Zendesk Support connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental reads for several objects.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.zendesk.com`.

### Supported Objects

The Zendesk Support connector supports incremental read for the following objects:

* [Attributes](https://developer.zendesk.com/api-reference/ticketing/ticket-management/skill_based_routing/#list-account-attributes)
* [Instance Values](https://developer.zendesk.com/api-reference/ticketing/ticket-management/skill_based_routing/#list-agent-attribute-values)
* [Organizations](https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#json-format)
* [Ticket Events](https://developer.zendesk.com/api-reference/ticketing/ticket-management/incremental_exports/#incremental-ticket-event-export)
* [Ticket Metrics](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_metrics/#json-format)
* [Tickets](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#json-format)
* [Users](https://developer.zendesk.com/api-reference/ticketing/users/users/#json-format)

The Zendesk Support connector supports reading from and writing to the following 48 objects:

* [Ticket Forms](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#json-format)
* [Ticket Fields](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#json-format)
* [Ticket Audits](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_audits/#json-format)
* [Suspended Tickets](https://developer.zendesk.com/api-reference/ticketing/tickets/suspended_tickets/#json-format)
  All others in alphabetical order:
* [Activities](https://developer.zendesk.com/api-reference/ticketing/tickets/activity_stream/#json-format)
* [Audit Logs](https://developer.zendesk.com/api-reference/ticketing/account-configuration/audit_logs/#json-format)
* [Automations](https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/#json-format)
* [Bookmarks](https://developer.zendesk.com/api-reference/ticketing/ticket-management/bookmarks/#json-format)
* [Brands](https://developer.zendesk.com/api-reference/ticketing/account-configuration/brands/#json-format)
* [Custom Roles](https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#json-format)
* [Custom Statuses](https://developer.zendesk.com/api-reference/ticketing/tickets/custom_ticket_statuses/#json-format)
* [Deletion Schedules](https://developer.zendesk.com/api-reference/ticketing/business-rules/deletion_schedules/#json-format)
* [Group Memberships](https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#json-format)
* [Groups](https://developer.zendesk.com/api-reference/ticketing/groups/groups/#json-format)
* [Job Statuses](https://developer.zendesk.com/api-reference/ticketing/ticket-management/job_statuses/#json-format)
* [Locales](https://developer.zendesk.com/api-reference/ticketing/account-configuration/locales/#json-format)
* [Macros](https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#json-format)
* [Organization Fields](https://developer.zendesk.com/api-reference/ticketing/organizations/organization_fields/#json-format)
* [Organization Memberships](https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/#json-format)
* [Organization Subscriptions](https://developer.zendesk.com/api-reference/ticketing/organizations/organization_subscriptions/#json-format)
* [Recipient Addresses](https://developer.zendesk.com/api-reference/ticketing/account-configuration/support_addresses/#json-format)
* [Requests](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-requests/#json-format)
* [Resource Collections](https://developer.zendesk.com/api-reference/ticketing/ticket-management/resource_collections/#json-format)
* [Satisfaction Ratings](https://developer.zendesk.com/api-reference/ticketing/ticket-management/satisfaction_ratings/)
* [Sessions](https://developer.zendesk.com/api-reference/ticketing/account-configuration/sessions/#json-format)
* [Sharing Agreements](https://developer.zendesk.com/api-reference/ticketing/tickets/sharing_agreements/#json-format)
* [Tags](https://developer.zendesk.com/api-reference/ticketing/ticket-management/tags/#json-format)
* [Target Failures](https://developer.zendesk.com/api-reference/ticketing/targets/target_failures/#json-format)
* [Targets](https://developer.zendesk.com/api-reference/ticketing/targets/targets/#json-format)
* [Trigger Categories](https://developer.zendesk.com/api-reference/ticketing/business-rules/trigger_categories/#json-format)
* [Triggers](https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/#json-format)
* [User Fields](https://developer.zendesk.com/api-reference/ticketing/users/user_fields/#json-format)
* [Views](https://developer.zendesk.com/api-reference/ticketing/business-rules/views/#json-format)
* [Workspaces](https://developer.zendesk.com/api-reference/ticketing/ticket-management/workspaces/#json-format)

### Example Integration

For an example manifest file of a Zendesk Support integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/zendeskSupport/amp.yaml).

## Before You Get Started

To integrate Zendesk with Ampersand, you need to [Create a Zendesk Account](#create-a-zendesk-account) and obtain the following credentials from your Zendesk App:

* Client ID/Unique identifier
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Create a Zendesk Account

You need a **Zendesk** account to connect with Ampersand.

* Follow instructions for [Getting a trial account or sponsored account for development](https://developer.zendesk.com/documentation/api-basics/getting-started/getting-a-trial-or-sponsored-account-for-development/)
* Ensure that your subdomain starts with the `d3v-` prefix. This is crucial for ensuring that you can [request a global OAuth client](https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/set-up-a-global-oauth-client/#requesting-a-global-oauth-client) later, which will allow you to connect to your customer's Zendesk instances.

### Creating a Zendesk App

1. Log in to Your [Zendesk Account](https://www.zendesk.com/login/).

2. Go to **Admin Center**.

3. On the *Admin Center* page, click **Apps and integrations**.

4. Under the **APIs** heading in the left navbar, click on "Zendesk API".

5. Click on **OAuth Clients** tab.

6. On the *OAuth Clients* page, click **Add OAuth client**.

<img alt="Zendesk Create OAuth Client" />

7. On the *Add OAuth client* form, enter the following details:

   1. **Client name**: The name of the OAuth client that will be shown to your users in the OAuth popup.
   2. **Unique identifier**: Ensure that you enter a name that is prefixed with `zdg-`, this allows you to [request a global OAuth client](https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/set-up-a-global-oauth-client/#requesting-a-global-oauth-client) later. This identifier is also what you will enter in the Provider Apps tab of the Ampersand dashboard in the next step.
   3. **Client kind**: Select "Confidential"
   4. **Redirect URLs**: Enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`

8. Click **Save**.

<img alt="Zendesk App Set Up" />

## Add Zendesk App Details in Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to add the Zendesk App.

   <img alt="Ampersand Project Selection" />

3. Navigate to the **Provider Apps** section.

4. Select **Zendesk** from the Provider list.

5. Enter the previously obtained **Unique identifier** in the **Client ID** field and the **Client Secret** in the **Client Secret** field. For a list of valid scopes, refer to the [Zendesk documentation](https://developer.zendesk.com/api-reference/ticketing/oauth/oauth_tokens/#scopes). Enter each scope in a separate line.

   <img alt="Ampersand Project Selection" />

6. Click **Save Changes**.

## Using the connector

<Note>Please note that due to Zendesk's API permission requirements, this integration requires credentials from a Zendesk admin.</Note>

To start integrating with Zendesk Support:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/zendeskSupport/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.

## Launch your Zendesk app to production

In order to connect to your customer's Zendesk instances, you will need to [request a global OAuth client](https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/set-up-a-global-oauth-client/#requesting-a-global-oauth-client). Please note that once you complete this process, you will need to reach out to the Zendesk team in order to edit your app (e.g. adding new scopes, modifying name).


# Zoho
Source: https://docs.ampersand.ai/provider-guides/zoho



The Zoho connector supports the following Zoho products:

* Zoho CRM (default)
* Zoho Desk
* Zoho Mail

## Zoho CRM

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://www.zohoapis.com`.
* [Subscribe Actions](/subscribe-actions).

### Supported Objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td>Leads</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Accounts</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Contacts</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Deals</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Campaigns</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Tasks</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Cases</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Events</td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td>Meetings</td><td><Cross /></td><td><Cross /></td><td><Check /></td></tr>
      <tr><td>Calls</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Solutions</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Products</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Vendors</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Price Books</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Quotes</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Sales Orders</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Purchase Orders</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Invoices</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Appointments</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Appointments Rescheduled History</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Services</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Custom</td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td>Users</td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

### Example Integration

For an example manifest file of a Zoho CRM integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/zoho/crm/amp.yaml).

## Zoho Desk

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill and incremental read for most objects.
* [Write Actions](/write-actions).

### Supported Objects

The Zoho connector allows you to read from and write to these objects:

* [organizations](https://desk.zoho.com/DeskAPIDocument#Organizations#Organizations_Getallorganizations)
* [agents](https://desk.zoho.com/DeskAPIDocument#Agents#Agents_Listagents)
* [profiles](https://desk.zoho.com/DeskAPIDocument#Profiles#Profiles_Listprofiles)
* [roles](https://desk.zoho.com/DeskAPIDocument#Roles#Roles_Listroles)
* [departments](https://desk.zoho.com/DeskAPIDocument#Departments#Departments_Listdepartments)
* [channels](https://desk.zoho.com/DeskAPIDocument#Channels#Channels_Listconfiguredchannels)
* [tickets](https://desk.zoho.com/DeskAPIDocument#Tickets)
* [contacts](https://desk.zoho.com/DeskAPIDocument#Contacts#Contacts_Listcontacts)
* [accounts](https://desk.zoho.com/DeskAPIDocument#Accounts#Accounts_Listaccounts)
* [tasks](https://desk.zoho.com/DeskAPIDocument#Tasks#Tasks_Gettask)
* [products](https://desk.zoho.com/DeskAPIDocument#Products#Products_Listproducts)
* [helpCenters](https://desk.zoho.com/DeskAPIDocument#HelpCenter#HelpCenter_Listhelpcenters)
* [users](https://desk.zoho.com/DeskAPIDocument#Users#Users_Listhelpcenterusers)
* [labels](https://desk.zoho.com/DeskAPIDocument#Labels#Labels_Listlabels)
* [groups](https://desk.zoho.com/DeskAPIDocument#Groups#Groups_Listgroups)
* [articles](https://desk.zoho.com/DeskAPIDocument#Articles#Articles_Listarticles)
* [articleFeedbacks](https://desk.zoho.com/DeskAPIDocument#ArticleFeedback#ArticleFeedback_Listfeedbackcomments)
* [kbRootCategories](https://desk.zoho.com/DeskAPIDocument#KBCategory#KBCategory_Listrootcategories)
* [contracts](https://desk.zoho.com/DeskAPIDocument#Contracts#Contracts_Listallcontracts)
* [ticketTemplates](https://desk.zoho.com/DeskAPIDocument#TicketTemplates#TicketTemplates_Listtickettemplates)
* [calls](https://desk.zoho.com/DeskAPIDocument#Calls#Calls_Listcalls)
* [events](https://desk.zoho.com/DeskAPIDocument#Events#Events_Listevents)
* [organizationModules](https://desk.zoho.com/DeskAPIDocument#Modules#Modules_GetAllModules)
* [languages](https://desk.zoho.com/DeskAPIDocument#Locales#Locales_Listalllanguages)
* [countries](https://desk.zoho.com/DeskAPIDocument#Locales#Locales_Listallcountries)
* [timeZones](https://desk.zoho.com/DeskAPIDocument#Locales#Locales_Listalltimezones)
* [businessHours](https://desk.zoho.com/DeskAPIDocument#Businesshours#Businesshours_Listbusinesshoursets)
* [domains](https://desk.zoho.com/DeskAPIDocument#DomainMapping#DomainMapping_Listdomains)
* [holidayList](https://desk.zoho.com/DeskAPIDocument#HolidayList#HolidayList_Listholidaylists)
* [im/channels](https://desk.zoho.com/DeskAPIDocument#IMChannel#IMChannel_ListChannels)
* [im/sessions](https://desk.zoho.com/DeskAPIDocument#IMSession#IMSession_ListSessions)

### Example Integration

For an example manifest file of a Zoho Desk integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/zoho/desk/amp.yaml).

## Zoho Mail

To use Zoho Mail, add `module: mail` to your integration definition in `amp.yaml`:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: myZohoMailIntegration
    provider: zoho
    module: mail
```

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported, a full read of the Zoho Mail instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Subscribe Actions](/subscribe-actions). Please note that [special set up](#set-up-subscribe-actions-for-zoho-mail) is needed for Zoho Mail: Zoho Mail has no API to create or manage webhook subscriptions, so your customer configures an outgoing webhook by hand in the Zoho Mail console, and Ampersand verifies and processes the delivered events.

### Supported Objects

<div>
  <table>
    <thead>
      <tr>
        <th>Object</th>
        <th>Read</th>
        <th>Write</th>
        <th>Subscribe</th>
      </tr>
    </thead>

    <tbody>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-users-accounts.html"><code>accounts</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-folder-details.html"><code>accounts/folders</code></a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-label-details.html"><code>accounts/labels</code></a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-collections.html"><code>collections</code></a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-custom-status-of-task.html"><code>customStatus</code></a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-group-collections-api.html"><code>groups/collections</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-bookmarks.html"><code>links</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-favorite-bookmarks-api.html"><code>links/favorites</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-link-groups.html"><code>links/groups</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-bookmarks.html"><code>links/me</code></a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-bookmarks-in-trash-api.html"><code>links/trash</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-emails-list.html"><code>messages</code></a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-notes.html"><code>notes</code></a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-books.html"><code>notes/books</code></a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-favourite-notes.html"><code>notes/favorites</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-groups.html"><code>notes/groups</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-shared-notes.html"><code>notes/sharedtome</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-user-signature.html"><code>signature</code></a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-all-group-or-personal-tasks.html"><code>tasks</code></a></td><td><Check /></td><td><Check /></td><td><Check /></td></tr>
      <tr><td><a href="https://www.zoho.com/mail/help/api/get-group-details.html"><code>tasks/groups</code></a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
    </tbody>
  </table>
</div>

### Subscribe events

Ampersand supports two of Zoho Mail's outgoing-webhook entities, delivered to the same endpoint:

* **messages**: fires when a new email is received. When configuring the webhook, your customer can optionally narrow it with conditions (e.g. sender or subject filters) or tags; a webhook also fires when a matching tag is manually applied to an email. All mail deliveries surface as `createEvent` — Zoho Mail does not send webhooks for message updates or deletions.
* **tasks**: fires on task activity in groups your customer owns or moderates. Supports `createEvent`, `updateEvent`, and `deleteEvent`, mapped from the task action that triggered the webhook.

Zoho Mail's third outgoing-webhook entity, Streams Posts, is not supported.

### Set up Subscribe Actions for Zoho Mail

Zoho Mail has no API for creating webhook subscriptions, so unlike Zoho CRM, Ampersand cannot register the webhook on your customer's behalf. Instead:

1. **Define the subscribe action** in your `amp.yaml` and deploy it with the [amp CLI](/cli/overview):

   ```yaml theme={"dark"}
   specVersion: 1.0.0
   integrations:
     - name: subscribeToZohoMail
       provider: zoho
       module: mail
       read: # Read action is required for subscribe actions
         objects:
           - objectName: messages
             destination: mailWebhook
             requiredFields:
               - fieldName: messageId
               - fieldName: subject
               - fieldName: fromAddress
               - fieldName: receivedTime
             optionalFields:
               - fieldName: toAddress
               - fieldName: summary
           - objectName: tasks
             destination: mailWebhook
             requiredFields:
               - fieldName: id
               - fieldName: title
             optionalFieldsAuto: all
       subscribe:
         objects:
           # Zoho Mail only sends webhooks for newly received emails, so
           # messages support createEvent only.
           - objectName: messages
             destination: mailWebhook
             inheritFieldsAndMapping: true
             createEvent:
               enabled: always
           # Task webhooks fire on group task activity; the task action is
           # mapped to create/update/delete events.
           - objectName: tasks
             destination: mailWebhook
             inheritFieldsAndMapping: true
             createEvent:
               enabled: always
             updateEvent:
               enabled: always
               watchFieldsAuto: all
             deleteEvent:
               enabled: always
   ```

2. **Construct a webhook URL for your customer** in this format:

   ```
   https://subscribe-receiver.withampersand.com/zt1secx7jknlhb/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
   ```

3. **Share the [Zoho customer guide](/customer-guides/zoho)** with your customer along with the webhook URL from Step 2. Your customer will create an outgoing webhook in the Zoho Mail console (**Settings** > **Developer Space** > **Webhooks** > **Outgoing Webhooks** > **Create new configuration**) that delivers events to this URL. See the [Zoho Mail webhook documentation](https://www.zoho.com/mail/help/dev-platform/webhook.html) for details.

### Example Integration

For an example manifest file of a Zoho Mail integration, visit our [samples repo on GitHub](https://github.com/amp-labs/samples/blob/main/zoho/mail/amp.yaml).

## Before You Get Started

To connect Zoho with Ampersand, you will need an account in an appropriate Zoho product:

* [Zoho CRM Account](https://www.zoho.com/crm/)
* [Zoho Desk Account](https://www.zoho.com/desk/)
* [Zoho Mail Account](https://www.zoho.com/mail/)

Once your account is created, you'll need to configure an app in Zoho and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will use these credentials to connect your application to Ampersand.

### Create a Zoho Account

Go to the particular Zoho product sign-up page and create an account:

* [Zoho CRM Sign Up page](https://www.zoho.com/crm/signup.html)
* [Zoho Desk Sign Up page](https://www.zoho.com/desk/signup.html)
* [Zoho Mail Sign Up page](https://www.zoho.com/mail/signup.html)

### Creating a Zoho App

Follow the steps below to create a Zoho app and add the Ampersand redirect URL:

1. Log in to the [Zoho API Console Account](https://api-console.zoho.com/) using your Zoho account.
2. Click **Get Started** to create your first app. If you have already created an application, click **Add Client** to create a new app.
3. Select **Server-based Applications**.
4. Enter the following details:
   * **Client Name**: Name of the client app
   * **Homepage URL**: The home page URL of your app
   * **Authorized Redirect URIs**: The Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`
5. Click **Create**.

You'll see the details of your newly created application. Note the **Client ID** and **Client Secret** keys as they are necessary for connecting your app to Ampersand.

<img alt="Alt text" />

6. Select the checkbox "Use the same OAuth credentials for all data centers" in the settings tab. Also toggle all regions where you expect to have customers.
   <img alt="Toggle regions" />

## Add Your Zoho App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).
2. Select the project where you want to create a Zoho integration.
   <img alt="Alt text" />
3. Select **Provider apps**.
4. Select **Zoho** from the **Provider** list.
5. Enter the previously obtained **Client ID** in the **Client ID** field and the **Client Secret** in the **Client Secret** field.
6. In the **Scopes** field, enter the list of desired scopes for your integration. We recommend the following scopes. If you want more granular scopes, please refer to the [Zoho documentation](https://www.zoho.com/accounts/protocol/oauth/scope.html) for syntax.

**Zoho CRM:**

```
ZohoCRM.modules.ALL
ZohoCRM.settings.ALL
```

In case you are using **Subscribe** action with Zoho CRM, additional scope is required

```
ZohoCRM.notifications.ALL
```

**Zoho Desk:**

```
Desk.basic.READ 
Desk.settings.ALL 
```

**Zoho Mail:**

```
ZohoMail.accounts.ALL
ZohoMail.folders.ALL
ZohoMail.tags.ALL
ZohoMail.messages.ALL
ZohoMail.tasks.ALL
ZohoMail.notes.ALL
ZohoMail.links.ALL
```

The accounts scope is always required (`ZohoMail.accounts.READ` is sufficient): Ampersand uses it after authentication to resolve your customer's Zoho Mail account ID, which account-scoped objects (`messages`, `accounts/folders`, `accounts/labels`) depend on. You can drop the scopes for object families you don't use.

7. Click **Save changes**.

## Customer Guide

The [Zoho Customer Guide](/customer-guides/zoho) can be shared with your customers to help them successfully use your integration.

## List on Zoho Marketplace

The final step, which is optional, is to list your application on the Zoho Marketplace. Follow the steps below to list your application:

1. Sign up and create a company profile on the [Zoho Marketplace](https://marketplace.zoho.com/home).
2. Click on the profile icon on the home page and select **Partner Console**.
3. Select **Company Profile** on the left panel.
4. Provide your company details. Note that these are your own company's details, not Ampersand's.
   <img alt="Zoho marketplace" />
5. After successful registration, go to **Apps** on the left sidebar and click **Submit App**.
6. Complete the process by adding your app's details and submitting it.


# Zoom
Source: https://docs.ampersand.ai/provider-guides/zoom



## What's Supported

### Supported Actions

This connector supports:

* [Read Actions](/read-actions), including full historic backfill for most objects. Incremental read is supported for `recordings`, `archive_files`, `meeting_summaries`, `activities_report`, `meetings`, `users_report`, `recordings_report`, `meetings_report`, `operation_logs_report`, `meeting_activities_report`, `telephone_report`, and `upcoming_events_report`. For all other objects, a full read of the Zoom instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.zoom.us`.

<Note>
  The following objects don't support historic backfill: `users_report`, `recordings_report`, `meetings_report`, `operation_logs_report`, `meeting_activities_report`, `telephone_report`, `upcoming_events_report`, and `recordings`. By default, the last 29 days are read. To retrieve more historical data, specify higher `defaultPeriod` in your read configuration.
</Note>

### Supported Objects

The Zoom connector supports writing to and reading from the following objects:

* [activities\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/GET/report/activities) (read only)
* [archive\_files](https://developers.zoom.us/docs/api/meetings/#tag/archiving/GET/archive_files) (read only)
* [billing\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/GET/report/billing) (read only)
* [contacts\_groups](https://developers.zoom.us/docs/api/users/#tag/contact-groups/get/contacts/groups) (read and write)
* [devices](https://developers.zoom.us/docs/api/meetings/#tag/devices/GET/devices) (read and write)
* [devices\_groups](https://developers.zoom.us/docs/api/meetings/#tag/devices/get/devices/groups) (read only)
* [groups](https://developers.zoom.us/docs/api/users/#tag/groups/get/groups) (read and write)
* [h323\_devices](https://developers.zoom.us/docs/api/meetings/#tag/h323-devices/POST/h323/devices) (read and write)
* [meeting\_activities\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/get/report/meeting_activities) (read only)
* [meeting\_summaries](https://developers.zoom.us/docs/api/meetings/#tag/summaries/get/meetings/meeting_summaries) (read only)
* [meeting\_templates](https://developers.zoom.us/docs/api/meetings/#tag/templates/get/users/\{userId}/meeting_templates) (read only)
* [meetings](https://developers.zoom.us/docs/api/meetings/#tag/meetings/get/users/\{userId}/meetings) (read and write)
* [meetings\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/get/report/users/\{userId}/meetings) (read only)
* [operation\_logs\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/get/report/operationlogs) (read only)
* [phones](https://developers.zoom.us/docs/api/meetings/#tag/sip-phone/get/sip_phones/phones) (read only)
* [recordings](https://developers.zoom.us/docs/api/meetings/#tag/cloud-recording/get/users/\{userId}/recordings) (read only)
* [recordings\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/get/report/cloud_recording) (read only)
* [telephone\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/get/report/telephone) (read only)
* [tracking\_fields](https://developers.zoom.us/docs/api/meetings/#tag/tracking-field) (read and write)
* [tsp](https://developers.zoom.us/docs/api/meetings/#tag/tsp/get/users/\{userId}/tsp) (read and write)
* [upcoming\_events\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/get/report/upcoming_events) (read only)
* [upcoming\_meetings](https://developers.zoom.us/docs/api/meetings/#tag/meetings/get/users/\{userId}/upcoming_meetings) (read only)
* [users](https://developers.zoom.us/docs/api/users/#tag/users/get/users) (read and write)
* [users\_report](https://developers.zoom.us/docs/api/meetings/#tag/reports/get/report/users) (read only)
* [webinars](https://developers.zoom.us/docs/api/meetings/#tag/webinars/get/users/\{userId}/webinars) (read and write)

### Example integration

For an example manifest file of a Zoom integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/zoom/amp.yaml).

## Before You Get Started

To connect Zoom with Ampersand, you will need [a Zoom Account](#create-a-zoom-account).

Once your account is created, you'll need to configure an app in Zoom and obtain the following credentials from your app:

* Client ID
* Client Secret

You will use these credentials to connect your application to Ampersand.

### Create a Zoom Account

Here's how you can sign up for a Zoom account:

1. Go to the [Zoom Sign Up page](https://zoom.us/signup) and create an account.
2. Sign up using your preferred method.

### Creating a Zoom App

Follow the steps below to create a Zoom app and add the Ampersand redirect URL:

1. Log in to your [Zoom Marketplace](https://marketplace.zoom.us/) account.

2. Click on **Develop** in the top-right corner and select **Build App**.

3. Choose the type of app you want to create. For this integration, select **General App**.

4. Click **Create**.

5. In the **OAuth Information** section, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.

   <br />

   <img alt="Creating Zoom App" />

6. Click **Continue** and go to **Scopes**.

7. Select the applicable scopes for your app.

8. Click Continue and in the Add your app section, click Add app to finalize your app setup.

You can find the **Client ID** and **Client Secret** in the **Basic Information** section of the app. You'll use these credentials to connect your app to [Ampersand](#add-your-zoom-app-info-to-ampersand).

<img alt="Ampersand Project" />

### Add Your Zoom App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Zoom integration.

   <img alt="Ampersand Project" />

3. Select **Provider apps**.

4. Select *Zoom* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

   <img alt="Adding Zoom Credentials" />

6. Click **Save changes**.


# ZoomInfo
Source: https://docs.ampersand.ai/provider-guides/zoominfo



## What's supported

### Supported actions

This connector supports:

* [Proxy Actions](/proxy-actions), using the base URL `https://api.zoominfo.com`.

### Example integration

To define an integration for ZoomInfo, create a manifest file that looks like this:

```YAML theme={"dark"}
# amp.yaml
specVersion: 1.0.0
integrations:
  - name: zoominfo-integration
    displayName: My ZoomInfo Integration
    provider: zoominfo
    proxy:
      enabled: true
```

## Before you get started

To connect ZoomInfo with Ampersand, you will need a ZoomInfo account with access to the [ZoomInfo Developer Portal](https://developer.zoominfo.com).

Once your account is created, you'll need to register an app in the Developer Portal and obtain the following credentials:

* Client ID
* Client Secret

You will then use these credentials to connect your application to Ampersand.

### Creating a ZoomInfo app

1. Log in to the [ZoomInfo Developer Portal](https://developer.zoominfo.com).

2. Click **Create App**.

3. Enter a descriptive name for your application, and select **OAuth 2.0 Authorization Code** as the authentication type.

4. Under redirect URIs, add: `https://api.withampersand.com/callbacks/v1/oauth`

5. Assign the OAuth scopes that your integration needs. Scopes define the specific types of data and actions your application can access.

6. Note the **Client ID** and **Client Secret**. You will need these to connect your app to Ampersand.

For more details, see the [ZoomInfo App Creation guide](https://docs.zoominfo.com/docs/app-creation-developer-portal-guide).

### Add your ZoomInfo app info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a ZoomInfo integration.

3. Select **Provider Apps**.

4. Select **ZoomInfo** from the **Provider** list.

5. Enter the **Client ID** and **Client Secret** obtained from your ZoomInfo app.

6. Click **Save Changes**.

## Using the connector

To start integrating with ZoomInfo:

* Create a manifest file like the [example above](#example-integration).
* Deploy it using the [amp CLI](/cli/overview).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for OAuth authorization.
* Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the access token to your requests.


# Proxy actions
Source: https://docs.ampersand.ai/proxy-actions



A proxy action allows you to make passthrough API calls to the SaaS provider's API. Ampersand will attach the right authentication headers and also take care of token refreshes when necessary. To define a proxy action, add `proxy` as a key in your integration defined in `amp.yaml`:

```YAML YAML theme={"dark"}
specVersion: 1.0.0
integrations: 
  - name: proxy-intercom
    displayName: Proxy to Intercom
    provider: intercom
    proxy:
      enabled: true
```

## Make API calls

All proxy actions expose an API with the base of `https://proxy.withampersand.com`. When making a passthrough call, simply replace the base URL with the Ampersand proxy URL. For example, instead of making a request to `https://subdomain.my.salesforce.com/services/data/v56.0/sobjects/Account`, make the same request to `https://proxy.withampersand.com/services/data/v56.0/sobjects/Account`.

Please refer to the [provider guides](/provider-guides/overview) for the base URL of each connector.

Keep the request body and HTTP verb the same, and add these additional headers so Ampersand knows how to deliver the API request:

* `x-amp-proxy-version`: this should always be 1
* `x-amp-project-id`: your Ampersand project ID, not the project name. You can find it on your project's [General Settings page](https://dashboard.withampersand.com/projects/_/settings).
* `x-api-key`: your Ampersand API key, if you don't have one yet, create one in the Ampersand Dashboard's [API Keys page](https://dashboard.withampersand.com/projects/_/api-keys).

In order for Ampersand to know which SaaS instance to make the API call against, you'll need to provide either:

* `x-amp-installation-id`: the installation ID, you'll get this from the [InstallIntegration](/embeddable-ui-components#install-integration) component's success callback functions.
* or both of the following:
  * `x-amp-integration-name`: the integration name that you wrote in the `amp.yaml` file
  * `x-amp-group-ref`: the ID for the user group that you used in the InstallIntegration React component's `groupRef` property.

If all 3 headers (`x-amp-installation-id`, `x-amp-integration-name` & `x-amp-group-ref`) are provided, then the installation ID is used.

Here is an example API call:

```bash theme={"dark"}
curl --location --request PUT 'https://proxy.withampersand.com/services/data/v56.0/sobjects/Account' \
--header 'Content-Type: application/json' \ # Other content types are supported
--header 'x-amp-project-id: <PROJECT_UUID>' \
--header 'x-api-key: my-api-key' \
--header 'x-amp-proxy-version: 1' \
--header 'x-amp-integration-name: my-salesforce-integration' \
--header 'x-amp-group-ref: company-id-from-my-app' \
--data '{
    # Same request body as if you are sending the request to Salesforce
}'
```

## Use Ampersand to manage API rate limits

If you want Ampersand to help you with managing rate limits from provider APIs, set the `X-Amp-Rate-Limiter-Mode` request header to `throttle`. This means that if we receive a 429 HTTP status code from a provider, we will return information to you about when you should retry the request again. If you make another request before the suggested retry time, then we will not pass the request to the provider API. We do this because many providers penalize you for hitting too many 429 responses in a row.

In the API response, if you receive a 429 status code, you will find 2 additional headers:

* `X-Amp-Retry-After`: this includes a UTC timestamp of when Ampersand recommends you retry the request. For example: `Thu, 06 Mar 2025 22:09:49 UTC`.
* `X-Amp-Retryable`: this is a boolean that indicates whether the request is retryable. Most 429 requests are retryable, however some API providers may "lock out" a particular token after too many unsuccessful requests, so that retrying isn't possible.


# Quickstart
Source: https://docs.ampersand.ai/quickstart

Build your first integration end to end: define a manifest, deploy it, and embed the install UI.

For this Quickstart, we are going to build integrations for a cool new app called MailMonkey, an AI-powered email campaign manager that integrates with Salesforce. You can see the final `amp.yaml` file on [Github](https://github.com/amp-labs/samples/blob/main/quickstart/amp.yaml).

<Frame>
  <img alt="MailMonkey logo" />
</Frame>

## Create an Ampersand org and project

Sign up for an [Ampersand account](https://dashboard.withampersand.com/sign-up), and then follow the steps on the screen to create an org and then a project. Each org can have multiple projects, this is helpful for separating development and production environments.

## Claim your domain

Claim your domain to let teammates auto-join your organization when they sign up. As an org owner, you can do this in the dashboard under org settings. Once enabled, anyone signing up with a `@yourcompany.com` email joins your org automatically, so teammates do not need an invite.

## Create a provider app

We'll first set up a Salesforce Connected App and put the Client ID and Client Secret inside of Ampersand Dashboard. See the [Salesforce guide](/provider-guides/salesforce) for more information.

## Create a destination

Next, we create a webhook destination for Ampersand to send data that it reads from Salesforce. See [Destinations](/destinations/overview) for more details.

## Define the integrations

To make MailMonkey interoperate seamlessly with our customers' Salesforce, we will create an integration which will:

1. **Read Contacts and Leads**: pull all Contacts and Leads from a customer's Salesforce into MailMonkey.
2. **Create Leads**: create a new Lead in Salesforce whenever somebody replies to a MailMonkey email campaign.

Let's create a folder called `source`, with a file inside called `amp.yaml`, this is where we will define our integration. Later on, you can refer to the [Manifest Reference](/manifest-reference) for a comprehensive guide to this file.

### Read Contacts and Leads

Our integration will have a [Read Action](/read-actions). We'll read 2 objects from Salesforce: contacts and leads.

```yaml amp.yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: mailmonkey-salesforce
    displayName: MailMonkey Salesforce Integration
    provider: salesforce
    read:
      objects:
        - objectName: contact
          destination: contactWebhook
          schedule: "*/30 * * * *" # every 30 minutes
          backfill:
            defaultPeriod:
              fullHistory: true
          # Always read these fields
          requiredFields:
            - fieldName: firstname
            - fieldName: lastname
            - fieldName: email
          # Customer can decide if they want us to read these fields.
          optionalFields:
            - fieldName: salutation
        - objectName: lead
          destination: leadsWebhook
          schedule: "*/30 * * * *" # every 30 minutes
          backfill:
            defaultPeriod:
              fullHistory: true
          requiredFields:
            - fieldName: firstname
            - fieldName: lastname
            - fieldName: email
            - fieldName: isconverted
            # Allow the customer to pick a field to map to priority score
            - mapToName: priority
              mapToDisplayName: Priority Score
              prompt: Which field do you use to track the priority of a lead?
          # All other fields in a Lead are optional,
          # Customers can pick from all of them.
          optionalFieldsAuto: all
```

### Create Leads

Next we will add a [Write Action](/write-actions). We want to insert new leads into our customer's Salesforce.

```yaml amp.yaml theme={"dark"}
...
    # Append to the integration definition from above.
    write:
      objects:
        # Create a new lead in Salesforce whenever we make an API request.
        - objectName: lead
```

Once a customer installs our integration, MailMonkey's application backend will make an API call to Ampersand to create the new lead whenever there's an email reply that we detect.

### Deploy the completed manifest

You can see the final `amp.yaml` file on [Github](https://github.com/amp-labs/samples/blob/main/quickstart/amp.yaml).

Once we are happy with the definition of our integrations, we can deploy them with the [amp CLI](/cli/overview):

```bash Deploy theme={"dark"}
amp login
# Our amp.yaml file is located in a folder called source.
amp deploy source --project=my-project-id-or-name
```

## Embed UI components

Next, we will use Ampersand's react library to embed ready-made UI components into our app, so that our customers can start using our shiny new integrations! We'll use the `InstallIntegration` component for the auth flow and configuration steps. Check out [Embed UI components](/embeddable-ui-components) for more details on this component and other components to help your users set up and manage their integrations. If you don't already have a frontend codebase, you can use our [starter project](/starter-project).

Here's a simplified version of what our frontend code would look like:

```tsx App.tsx theme={"dark"}
import { AmpersandProvider, InstallIntegration } from '@amp-labs/react';

const options = {
  project: 'my-project', // Your Ampersand project name or ID.
  apiKey: 'API_KEY',// Your Ampersand API key, created in the Dashboard.
};

function App() {
  return (
    <AmpersandProvider options={options}>
      <InstallIntegration 
        // The name of the integration from amp.yaml
        integration = "mailmonkey-salesforce"
        // The ID that your app uses to identify this end user.
        consumerRef = {userId}
        // The display name that your app uses for this end user.
        consumerName = {userName}
        // The ID that your app uses to identify the user's company, org, or team.
        groupRef = {groupId}
        // The display name that your app uses for this company, org or team.
        groupName = {groupName}
      />
    </AmpersandProvider>
  )
}
```


# Read actions
Source: https://docs.ampersand.ai/read-actions



A read action reads data from your customer's SaaS and sends them to Destinations that you define.

## Define reads

To read an object, you need to specify:

* **objectName:** to indicate which object you'd like to read. This should match the name of the object in the official documentation for the SaaS API.
* **destination:** the name of the [destination](/destinations) that you've defined
* **schedule** (optional): how frequently the read should happen. This value must be a schedule in [cron syntax](https://docs.gitlab.com/ee/topics/cron/), and can be as frequent as every 10 minutes. If you do not define a schedule, you can explicitly [trigger reads via API](#trigger-a-read).
* **backfill** (optional): whether Ampersand should read historical data when a customer installs an integration. See [Backfill behavior](#backfill-behavior) for details. If you omit this, it means that a backfill won't happen at the time of installation, but you can still [trigger a backfill later via API](#trigger-a-read).

```YAML YAML theme={"dark"}
...
     objects:
        - objectName: lineItem
          destination: lineItemWebhook
          schedule: "*/10 * * * *" # every 10 minutes
          backfill:
            defaultPeriod:
              days: 30
          ...
```

### Required fields and optional fields

Fields can either be required or optional. If a field is required, then all users who install this integration will need to give your app read access to that field. If a field is optional, then users can choose whether they'd like your app to read that field. For these fields, you will specify:

* **fieldName:** the name of the field from the official SaaS API documentation.

```YAML YAML theme={"dark"}
   objects:
        - objectName: contact
          destination: contactWebhook
          schedule: "*/10 * * * *" # every 10 minutes
          requiredFields:
          - fieldName: firstname
          - fieldName: lastname
          - fieldName: email
          optionalFields:
          - fieldName: company
```

#### Nested fields

Some providers return data with nested structures. You can reference nested fields using [JSONPath bracket notation](/object-and-field-mapping#nested-field-mapping): `$['parentField']['childField']`.

This works in both `requiredFields` and `optionalFields`, with or without [field mapping](/object-and-field-mapping):

```YAML YAML theme={"dark"}
   objects:
        - objectName: contact
          destination: contactWebhook
          schedule: "*/10 * * * *"
          requiredFields:
          - fieldName: $['address']['street']
          - fieldName: $['address']['city']
          optionalFields:
          - fieldName: $['metadata']['tags']
```

### Allow users to pick from all fields

If you want to give your user the option to pick from any of the fields in their object, use `optionalFieldsAuto: all`. The UI component will populate a list of all the fields pulled from that object (including custom fields) and allow them to pick which ones your app will be able to read.

```YAML YAML theme={"dark"}
      objects:
        - objectName: contact
          destination: contactWebhook
          schedule: "*/10 * * * *" # every 10 minutes
          requiredFields:
          - fieldName: firstname
          - fieldName: lastname
          - fieldName: email
          # All other fields are optional
          optionalFieldsAuto: all
```

### Object and field mappings

You might want to ask your users during the set up of the integration to map a field (standard or custom) to a concept in your product, because your various customers might be using different fields for the same purpose. You can also predefine object and field mappings that do not involve user interaction. Learn more in [Object and Field Mapping](/object-and-field-mapping).

### Always-enabled objects

By default, each customer chooses which objects to read when they install your integration. Set `enabled: always` on an object to read it for **every** installation instead. Customers can't turn it off, but they can still pick its optional fields and mappings.

Because the object is read without asking the customer, it can't have required field mappings: every required field needs a `fieldName`, so there's nothing the customer must choose. Optional field mappings are fine.

```YAML YAML theme={"dark"}
...
     objects:
        - objectName: account
          destination: accountWebhook
          schedule: "*/30 * * * *"
          enabled: always
          requiredFields:
            - fieldName: name
          optionalFields:
            - fieldName: industry
          ...
```

**When the object is added to an installation**

* **New installations:** Ampersand adds the object to the installation's config when the installation is created or imported, even if the config doesn't include it. It's then validated, scheduled and backfilled like any other object.
* **Existing installations:** when you deploy an `amp.yaml` that adds a new object with `enabled: always`, or adds the flag to an existing object, Ampersand updates the config of every existing installation that doesn't have the object, as part of the deploy. An installation's own entry for the object, with its selected fields and mappings, is never overwritten. If the [sample read](#install-time-validation) fails for an installation, that installation isn't updated. Updating an installation through the API doesn't add missing always-enabled objects; only creating one does.
* **Prebuilt UI:** the [`InstallIntegration` component](/embeddable-ui-components#install-integration) installs these objects as soon as the customer connects, and adds a missing one when the customer opens an existing installation.

Reads, including any [backfill](#backfill-behavior), start as soon as the object is installed.

**Rules**

* A config that sets `disabled: true` on an always-enabled object is rejected with an HTTP `400` response.
* The object needs at least one entry in `requiredFields`, and none of them can be a mapping the customer fills in (a `mapToName` without a `fieldName`). A deploy that breaks either rule is rejected.

**Removing the flag**

If a later deploy removes `enabled: always`, installations that already have the object keep reading it. New installations stop getting it automatically.

## Backfill behavior

Backfill behavior describes whether Ampersand will do an initial read of your customer's historic data when they connect their SaaS instance, and how far back data will be read. For example, if your integration reads a customer's contacts stored in their CRM, you can configure whether you want to only read new and updated contacts going forward, or if you also want to do an initial backfill of the pre-existing contacts in their CRM.

### No backfill

If you only want to read new and updated records moving forward and do not wish to read any pre-existing records, then you can simply omit the `backfill` key in the integration definition, or you can write 0 days as the default period.

```YAML YAML theme={"dark"}
      objects:
        - objectName: contact
          backfill:
            defaultPeriod:
              days: 0 # Omitting backfill object will also default to 0 days.
          ...
```

### Full historical backfill

If you want to do a full backfill of all the existing records when a customer connects their SaaS instance, set `fullHistory` to true. If you have customers that have large SaaS instances, please ensure that your webhook endpoint can handle a high number of messages in quick succession. You may find it helpful to use a webhook gateway solution like [Hookdeck](https://hookdeck.com/docs/receive-webhooks).

```yaml yaml theme={"dark"}
      objects:
        - objectName: contact
          backfill:
            defaultPeriod:
              fullHistory: true
          ...
```

### Limited time backfill

You can select a specific time frame for backfill, such as "the last 30 days" or "the last 90 days". Here's an example of how to do so:

```yaml yaml theme={"dark"}
      objects:
        - objectName: contact
          backfill:
            defaultPeriod:
              days: 30 # Backfill the last 30 days of data
          ...
```

### Monitor backfill progress

To monitor the progress of your backfill, poll the [backfill progress API](/reference/operation/get-backfill-progress) for an installation and object. Call it while the backfill runs to track sync status.

The API returns:

* **recordsProcessed** — How many records have been synced so far; updates as the backfill runs
* **recordsEstimatedTotal** — The estimated total at the start of the backfill, if it is available.
* **operationId** — The ID of the backfill operation
* **createTime** — When the backfill started
* **updateTime** — When progress was last updated

## Filter by field values

You can filter which records are returned by a read action by setting `fieldFilters` in the installation config when you are creating the installation using the [REST API](/reference/installation/create-a-new-installation) or Headless UI's [createInstallation method](/headless#create-update-and-delete-installations). Then only matching records are read and delivered to your destination.

Each filter specifies a field name, an operator, and a value. Currently, only the `eq` (equals) operator is supported. Multiple filters are joined with AND logic, and each field can only have one condition.

<Note>
  Filtered reads are currently only supported for **Salesforce** (CRM Module) and **HubSpot**.
</Note>

### Filter all records

To filter both incremental reads and backfill, set `fieldFilters` on the object in the installation config when you are creating the installation using the [REST API](/reference/installation/create-a-new-installation) or Headless UI's [createInstallation method](/headless#create-update-and-delete-installations):

```json theme={"dark"}
{
  "read": {
    "objects": {
      "contacts": {
        "objectName": "contacts",
        "selectedFields": { "email": true, "firstname": true, "lastname": true },
        "backfill": {
          "defaultPeriod": { "fullHistory": true }
        },
        "fieldFilters": [
          { "fieldName": "firstname", "operator": "eq", "value": "Brian" }
        ]
      }
    }
  }
}
```

In this example, only contacts whose `firstname` equals "Brian" will be returned during both scheduled reads and backfill.

### Backfill-specific filters

If you want different filter behavior for backfill vs. incremental reads, you can set `fieldFilters` inside the `backfill` object. When set, this overrides the object-level `fieldFilters` during backfill. Please note that [triggered reads](#trigger-a-read) will still use the object-level `fieldFilters`, if it is defined.

```json theme={"dark"}
{
  "read": {
    "objects": {
      "contacts": {
        "objectName": "contacts",
        "selectedFields": { "email": true, "firstname": true, "lastname": true },
        "fieldFilters": [
          { "fieldName": "status", "operator": "eq", "value": "active" }
        ],
        "backfill": {
          "defaultPeriod": { "fullHistory": true },
          "fieldFilters": [
            { "fieldName": "firstname", "operator": "eq", "value": "Brian" }
          ]
        }
      }
    }
  }
}
```

In this example, the backfill will only return contacts whose `firstname` equals "Brian", while subsequent incremental reads will only return contacts whose `status` equals "active".

### Filter field names

The `fieldName` of a filter must be the field's name in the provider's API, and it is case-sensitive.

<Warning>
  Read filters do **not** resolve [object and field mappings](/object-and-field-mapping). A `mapToName` from your `amp.yaml`, or a mapping your customer selected during installation, is not translated to the underlying provider field. This differs from [search actions](/search-actions#execute-a-search), which do accept mapped field names.
</Warning>

For example, if your manifest maps the provider field `mobilephone` to `phone`:

```yaml theme={"dark"}
requiredFields:
  - fieldName: mobilephone
    mapToName: phone
```

then a filter on that field must still reference `mobilephone`:

```json theme={"dark"}
// Correct — the provider's field name
{ "fieldName": "mobilephone", "operator": "eq", "value": "1234567890" }

// Incorrect — mapToName is not resolved, so the read will fail or return no records
{ "fieldName": "phone", "operator": "eq", "value": "1234567890" }
```

The field you filter on does not have to be one of the object's `selectedFields`. You can filter on a field that you don't read.

### Valid filter values

The `value` field of the filter accepts strings, booleans, and numbers:

```json theme={"dark"}
{ "fieldName": "name", "operator": "eq", "value": "Acme" }
{ "fieldName": "isActive", "operator": "eq", "value": true }
{ "fieldName": "employeeCount", "operator": "eq", "value": 50 }
```

## Filter with a raw filter

Use `rawFilter` when you need filtering that `fieldFilters` can't express, such as very specific conditions, comparisons, or reading deleted records. A raw filter is written in the provider's own query syntax and passed to the provider as written.

A raw filter has two parts:

* `type`: the filter syntax. Each provider guide lists the types it supports, for example `soql` for [Salesforce](/provider-guides/salesforce#raw-filters-soql).
* `filter`: the filter expression, in that syntax.

<Note>
  Raw filters are currently only supported for [Salesforce](/provider-guides/salesforce) using the `soql` type. You can learn more about each provider's raw filter support in its provider guide.
</Note>

```json theme={"dark"}
{
  "read": {
    "objects": {
      "contacts": {
        "objectName": "contact",
        "selectedFields": { "email": true, "firstname": true, "isdeleted": true },
        "rawFilter": {
          "type": "soql",
          "filter": "IsDeleted = true OR IsDeleted = false"
        }
      }
    }
  }
}
```

Raw filters follow the same rules as `fieldFilters`:

* Set `rawFilter` on the object to filter incremental reads, or inside `backfill` to filter only the backfill. A backfill with no filter of its own uses the object's filter. [Triggered reads](#trigger-a-read) use the object's filter.
* Only one of `rawFilter` or `fieldFilters` is supported, on the object and inside `backfill`.
* A `backfill` block in the installation replaces the backfill settings from `amp.yaml` entirely, so a `backfill` block that sets a filter must also set `defaultPeriod` (`days` or `fullHistory`).
* Field names are the provider's own. [Object and field mappings](/object-and-field-mapping) are not resolved.

An installation is rejected if the provider doesn't support the filter's `type`, or if the filter isn't the kind of value that type expects (for `soql`, a non-empty string). The provider checks the filter's syntax when a read runs, so try a raw filter with a [search](/search-actions#search-with-a-raw-filter) before adding it to an installation; searches apply raw filters the same way.

## Trigger a read

You can call the [trigger read API](/reference/read/trigger-a-read) when you want Ampersand to read data for a particular customer. The data will be sent asynchronously to your destination. You can either use this API alongside a scheduled read (defined by the `schedule` field in the `amp.yaml`), or you can exclusively use the trigger read API without defining a schedule.

There are 2 types of reads that can be triggered:

* Full historic read

```json theme={"dark"}

  {
    groupRef: "xye23r3df",
    mode: "async"
  }

```

* Read all records from a specific timestamp to now

```json theme={"dark"}

  {
    groupRef: "xye23r3df",
    mode: "async",
    sinceTimestamp: "2012-04-23T18:25:43.511Z"
  }

```

## Install-time validation

When a customer creates or updates an installation, Ampersand runs a **sample read** before saving the configuration: a one-record read against the provider for each scheduled read object. This surfaces configuration errors — such as [field-level visibility](/troubleshooting-guides/salesforce#resolve-a-field-level-visibility-issue) restrictions or misconfigured field names — up front, so your customer sees the problem while they're still in the install flow instead of discovering it later through a broken sync.

Sampling is on by default. No configuration is required.

**What gets sampled**

* Only read objects that will run **on a schedule** (enabled, with a `schedule` defined). Write and subscribe objects are not sampled.
* The sample reads the object's selected fields plus the source fields of any [field mappings](/object-and-field-mapping).
* On **create**, every scheduled read object is sampled. On **update**, Ampersand re-samples only what could have changed: newly added objects, objects newly put on a schedule, objects whose field selection changed, or — when the connection is swapped — every scheduled read object.

**What happens on failure**

If a sample read fails with a bad-request error (for example, a field the connected user can't see, or a field name that doesn't exist), the create/update request is rejected with an HTTP `422` response containing the provider's error message, and the installation is **not saved**.

Only bad-request errors block the save. Transient problems — authentication, rate limiting, or provider `5xx` errors — are ignored so they don't stop a legitimate installation on a best-effort probe.

<Note>
  When using the [`InstallIntegration` component](/embeddable-ui-components#install-integration), sampling runs automatically on `@amp-labs/react` **2.13.5 and later**.
</Note>

**Disabling sampling**

Sampling can be turned off per request by passing `?skipSampling=true` to the [create](/reference/installation/create-a-new-installation) or [update](/reference/installation/update-an-installation) installation endpoints. This is useful if you intentionally save configurations before the connected user has been granted the necessary field access. Note that skipping validation means misconfigurations won't surface until reads actually run.

## Full example

```yaml yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: readSalesforce
    provider: salesforce
    read:
      objects:

        - objectName: account
          destination: accountWebhook
          schedule: "*/10 * * * *" # every 10 minutes
          # Read all accounts when integration is installed
          backfill:
            defaultPeriod:
              fullHistory: true
          requiredFields:
            - fieldName: id
            - fieldName: name
            - fieldName: industry
          optionalFields:
            - fieldName: annualrevenue
            - fieldName: website

        - objectName: contact
          destination: contactWebhook
          schedule: "*/10 * * * *" # every 10 minutes
          # Read contacts from the last 30 days when integration is installed
          backfill:
            defaultPeriod:
              days: 30
          requiredFields:
            - fieldName: id
            - fieldName: firstname
            - fieldName: lastname
            - mapToName: pronoun
              mapToDisplayName: Pronoun
              prompt: We will use this word in emails we send out.
          # All other field are optional
          optionalFieldsAuto: all
```

## Delivery modes (deprecated)

<Warning>
  Delivery modes are deprecated. If you don't want read results to be automatically delivered to you, you should omit `schedule` and `backfill` when defining a read action in `amp.yaml`, and [trigger a read](#trigger-a-read) when you want to receive data from your customer's SaaS.
</Warning>

Ampersand sends data to [destinations](/destinations/overview) that you specify in your manifest file. Please refer to [webhook destinations](/destinations/webhooks) for more information on the data schema of the webhooks.

You can define the delivery mode within the manifest file.

### Auto

This is the default delivery mode if you do not specify one. When you set the delivery mode to `auto`, Ampersand will automatically send results to your destination as it reads new data from the SaaS instance.

```yaml yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforce-buffered-read
    provider: salesforce
    read:
      objects:
        - objectName: contact
          destination: contactWebhook
          schedule: "*/30 * * * *" # Data will be read every 30 minutes
          delivery:
            mode: auto # Data is delivered as soon as it is available
```

### On request (deprecated)

When you set the delivery mode to `onRequest`, Ampersand will not send webhooks as it reads new data, but only when you request for more results. This is useful when you want to control the rate at which you receive data. For precise control over how much data you receive each time, you can configure the page size, which specifies the number of records to send in each webhook payload.

Please note that the page size is a *maximum*, and the actual number of records in each payload may be less if there are fewer records available in the SaaS instance. Currently, you may configure a page size between 50 and 500. Please reach out to us if you need this to be lower or higher.

Here's an example of how to configure the delivery mode to `onRequest` for a Salesforce Contact object, with a max page size of 50 records per webhook message:

```yaml yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforce-buffered-read
    provider: salesforce
    read:
      objects:
        - objectName: contact
          destination: contactWebhook
          schedule: "*/30 * * * *" # Data will be read every 30 minutes
          delivery:
            mode: onRequest
            pageSize: 50
```

#### Requesting results

When you are ready to receive & process webhook messages, you can call the [deliver results endpoint](/reference/read/deliver-results), which will asynchronously send the stored results to the configured destination.

For example, if you are ready to receive and process a maximum of 300 records, and you have a `pageSize` of 50 in your `amp.yaml`, you should request 6 pages (300 divided by 50).

#### What happens if you request for more pages than are available?

If you request for more pages than are available, Ampersand will first send you all the available records at the time of your request. Then, as it reads new data, it will send you the new records as they become available until you have received your requested number of pages.

For example, if you request for 10 pages of results, but there are only 4 pages available at the time of your request, Ampersand will send you the 4 pages immediately. If Ampersand reads 20 pages of results in the next scheduled read, Ampersand will send you 6 pages more, resulting in a total of 10 pages of results being delivered. Ampersand will then hold the next 14 pages until you request for more results.


# Create a new API key
Source: https://docs.ampersand.ai/reference/api-key/create-a-new-api-key

platform post /projects/{projectIdOrName}/api-keys



# Delete an API key
Source: https://docs.ampersand.ai/reference/api-key/delete-an-api-key

platform delete /projects/{projectIdOrName}/api-keys/{apiKey}



# Get an API key
Source: https://docs.ampersand.ai/reference/api-key/get-an-api-key

platform get /projects/{projectIdOrName}/api-keys/{apiKey}



# List API keys
Source: https://docs.ampersand.ai/reference/api-key/list-api-keys

platform get /projects/{projectIdOrName}/api-keys



# Update an API key
Source: https://docs.ampersand.ai/reference/api-key/update-an-api-key

platform patch /projects/{projectIdOrName}/api-keys/{apiKey}



# Create a portal session for a billing account
Source: https://docs.ampersand.ai/reference/billing-account/create-a-portal-session-for-a-billing-account

platform post /billingAccounts/{billingAccountId}/portalSession



# Get the billing account for an organization
Source: https://docs.ampersand.ai/reference/billing-account/get-the-billing-account-for-an-organization

platform get /orgs/{orgId}/billingAccount



# Delete a connection
Source: https://docs.ampersand.ai/reference/connection/delete-a-connection

platform delete /projects/{projectIdOrName}/connections/{connectionId}



# Generate a new connection
Source: https://docs.ampersand.ai/reference/connection/generate-a-new-connection

platform post /projects/{projectIdOrName}/connections:generate
All auth schemes are supported, but for OAuth2 Authorization Code, it is recommended that you use the [/oauth-connect endpoint](https://docs.ampersand.ai/reference/oauth/generate-oauth-authorization-url) instead, unless you already have the refresh token and are importing it into Ampersand.



# Get a connection
Source: https://docs.ampersand.ai/reference/connection/get-a-connection

platform get /projects/{projectIdOrName}/connections/{connectionId}



# List connections
Source: https://docs.ampersand.ai/reference/connection/list-connections

platform get /projects/{projectIdOrName}/connections



# Start or continue a multi-step custom auth flow
Source: https://docs.ampersand.ai/reference/connection/start-or-continue-a-multi-step-custom-auth-flow

platform post /custom-auth/connect
Drives a multi-step custom auth flow (browser redirects and/or server-side credential-exchange calls). Call it once with the flow inputs to start; if the response contains a redirect, open it, then call again with the returned sessionId and the provider's callback params to continue. Repeat until the response contains a connection. Used by the prebuilt UI components; only providers whose ProviderInfo has customOpts.multiStep present can use this endpoint.




# Update a connection.
Source: https://docs.ampersand.ai/reference/connection/update-a-connection

platform patch /projects/{projectIdOrName}/connections/{connectionId}
Rotate credentials or update metadata (such as the provider workspace reference) for an existing connection.



# Create a new destination
Source: https://docs.ampersand.ai/reference/destination/create-a-new-destination

platform post /projects/{projectIdOrName}/destinations



# Create a topic
Source: https://docs.ampersand.ai/reference/destination/create-a-topic

platform post /projects/{projectIdOrName}/topics



# Create a topic destination route
Source: https://docs.ampersand.ai/reference/destination/create-a-topic-destination-route

platform post /projects/{projectIdOrName}/topic-destination-routes



# Delete a destination
Source: https://docs.ampersand.ai/reference/destination/delete-a-destination

platform delete /projects/{projectIdOrName}/destinations/{destination}



# Delete a topic
Source: https://docs.ampersand.ai/reference/destination/delete-a-topic

platform delete /projects/{projectIdOrName}/topics/{topicId}



# Delete a topic destination route
Source: https://docs.ampersand.ai/reference/destination/delete-a-topic-destination-route

platform delete /projects/{projectIdOrName}/topic-destination-routes/{routeId}



# Get a destination
Source: https://docs.ampersand.ai/reference/destination/get-a-destination

platform get /projects/{projectIdOrName}/destinations/{destination}



# List destinations
Source: https://docs.ampersand.ai/reference/destination/list-destinations

platform get /projects/{projectIdOrName}/destinations



# List topic destination routes
Source: https://docs.ampersand.ai/reference/destination/list-topic-destination-routes

platform get /projects/{projectIdOrName}/topic-destination-routes



# List topics
Source: https://docs.ampersand.ai/reference/destination/list-topics

platform get /projects/{projectIdOrName}/topics



# Update a destination
Source: https://docs.ampersand.ai/reference/destination/update-a-destination

platform patch /projects/{projectIdOrName}/destinations/{destination}



# Update a topic
Source: https://docs.ampersand.ai/reference/destination/update-a-topic

platform patch /projects/{projectIdOrName}/topics/{topicId}



# Create a new installation
Source: https://docs.ampersand.ai/reference/installation/create-a-new-installation

platform post /projects/{projectIdOrName}/integrations/{integrationId}/installations
Install an integration for a specific group. The group must already have a SaaS connection — either provide its `connectionId`, or omit it to use the group's default. To create a connection, use the [OAuth Connect endpoint](https://docs.ampersand.ai/reference/oauth/generate-oauth-authorization-url) or the [prebuilt UI components](https://docs.ampersand.ai/embeddable-ui-components).




# Delete an installation
Source: https://docs.ampersand.ai/reference/installation/delete-an-installation

platform delete /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}
Delete an Installation. This will also delete the associated Connection if it is not used by any other Installations.




# Get an installation
Source: https://docs.ampersand.ai/reference/installation/get-an-installation

platform get /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}
Retrieves a single installation by ID, including its connection details, config, and health status.




# List installations for a project
Source: https://docs.ampersand.ai/reference/installation/list-installations-for-a-project

platform get /projects/{projectIdOrName}/installations
Lists all installations across every integration in a project, giving you a complete view of all active customer integrations. To narrow results to a single integration, use listInstallations instead.




# List installations for an integration
Source: https://docs.ampersand.ai/reference/installation/list-installations-for-an-integration

platform get /projects/{projectIdOrName}/integrations/{integrationId}/installations
Lists all installations for a specific integration within a project. To list installations across all integrations, use listInstallationsForProject instead.




# Update an installation
Source: https://docs.ampersand.ai/reference/installation/update-an-installation

platform patch /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}
Update an installation using field masks. Note: subscribe config changes trigger a subscription change in the provider's system, which typically takes 1-2 minutes but may take up to 10 minutes.




# Update an installation object
Source: https://docs.ampersand.ai/reference/installation/update-an-installation-object

platform patch /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content
Updates a single object's configuration within an installation using JSON Patch syntax.




# Batch upsert a group of integrations
Source: https://docs.ampersand.ai/reference/integration/batch-upsert-a-group-of-integrations

platform put /projects/{projectIdOrName}/integrations:batch
This endpoint is used by the Ampersand CLI to batch upsert integrations. We recommend using the [CLI's deploy command](https://docs.ampersand.ai/cli/overview#deploy-integrations) rather than this API endpoint directly.



# Create a new integration.
Source: https://docs.ampersand.ai/reference/integration/create-a-new-integration

platform post /projects/{projectIdOrName}/integrations



# Delete an integration
Source: https://docs.ampersand.ai/reference/integration/delete-an-integration

platform delete /projects/{projectIdOrName}/integrations/{integrationIdOrName}
Delete an integration and all its installations.



# Get an integration by ID or name
Source: https://docs.ampersand.ai/reference/integration/get-an-integration-by-id-or-name

platform get /projects/{projectIdOrName}/integrations/{integrationIdOrName}



# List integrations
Source: https://docs.ampersand.ai/reference/integration/list-integrations

platform get /projects/{projectIdOrName}/integrations



# Create a new JWT key
Source: https://docs.ampersand.ai/reference/jwt-key/create-a-new-jwt-key

platform post /projects/{projectIdOrName}/jwt-keys
Creates a new JWT key for the specified project with RSA public key for token verification



# Delete a JWT key
Source: https://docs.ampersand.ai/reference/jwt-key/delete-a-jwt-key

platform delete /projects/{projectIdOrName}/jwt-keys/{keyId}
Permanently deletes a JWT key from the specified project



# Get a specific JWT key
Source: https://docs.ampersand.ai/reference/jwt-key/get-a-specific-jwt-key

platform get /projects/{projectIdOrName}/jwt-keys/{keyId}
Retrieves a specific JWT key by its ID within the specified project



# List JWT keys
Source: https://docs.ampersand.ai/reference/jwt-key/list-jwt-keys

platform get /projects/{projectIdOrName}/jwt-keys
Retrieves all JWT keys for the specified project, with optional filtering for active keys only



# Update a JWT key
Source: https://docs.ampersand.ai/reference/jwt-key/update-a-jwt-key

platform patch /projects/{projectIdOrName}/jwt-keys/{keyId}
Updates specific fields of a JWT key using field masks. Currently supports updating the 'active' status and 'name' field.



# Create a notification event-topic route
Source: https://docs.ampersand.ai/reference/notification/create-a-notification-event-topic-route

platform post /projects/{projectIdOrName}/notification-event-topic-routes



# Delete a notification event-topic route
Source: https://docs.ampersand.ai/reference/notification/delete-a-notification-event-topic-route

platform delete /projects/{projectIdOrName}/notification-event-topic-routes/{routeId}



# List notification event-topic routes
Source: https://docs.ampersand.ai/reference/notification/list-notification-event-topic-routes

platform get /projects/{projectIdOrName}/notification-event-topic-routes



# Generate OAuth authorization URL
Source: https://docs.ampersand.ai/reference/oauth/generate-oauth-authorization-url

platform post /oauth-connect
Generate a URL for the browser to render to kick off OAuth flow. You can use this endpoint as an alternative to the [prebuilt UI components](https://docs.ampersand.ai/embeddable-ui-components).



# Generate OAuth authorization URL for existing connection
Source: https://docs.ampersand.ai/reference/oauth/generate-oauth-authorization-url-for-existing-connection

platform patch /projects/{projectIdOrName}/connections/{connectionId}:oauth-update
Generate a URL for the browser to render to kick off an OAuth flow that updates an existing connection. Use this when the connection's credentials need to be refreshed. To start an OAuth flow without specifying a connection ID, use the [/oauth-connect endpoint](https://docs.ampersand.ai/reference/oauth/generate-oauth-authorization-url) instead.




# Get object metadata via connection
Source: https://docs.ampersand.ai/reference/objects-&-fields/get-object-metadata-via-connection

platform get /projects/{projectIdOrName}/providers/{provider}/objects/{objectName}/metadata
Retrieves metadata about an object in a customer's SaaS instance, including its fields. A connection must exist for the given `groupRef` and `provider`. For Salesforce, nested fields may be included using JSONPath bracket notation (e.g. `$['billingaddress']['city']`).




# Get object metadata via installation
Source: https://docs.ampersand.ai/reference/objects-&-fields/get-object-metadata-via-installation

platform get /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/metadata
Retrieves metadata about an object in a customer's SaaS instance, including its fields. An installation must exist for the given `groupRef` and `integrationId`. The `objectName` can be either the mapped name from your integration config or the native provider name. For Salesforce, nested fields may be included using JSONPath bracket notation (e.g. `$['billingaddress']['city']`).




# Upsert custom fields for connection
Source: https://docs.ampersand.ai/reference/objects-&-fields/upsert-custom-fields-for-connection

platform put /projects/{projectIdOrName}/providers/{provider}/object-metadata
Create or update fields in the SaaS instance tied to a connection. Only HubSpot and Salesforce are supported currently.



# Upsert custom fields for installation
Source: https://docs.ampersand.ai/reference/objects-&-fields/upsert-custom-fields-for-installation

platform put /projects/{projectIdOrName}/integrations/{integrationId}/object-metadata
Create or update fields in the SaaS instance tied to an installation. Only HubSpot and Salesforce are supported currently.



# Get an operation
Source: https://docs.ampersand.ai/reference/operation/get-an-operation

platform get /projects/{projectIdOrName}/operations/{operationId}
Retrieve a single operation by ID. An operation represents an async read, write, or subscribe action for an installation. Use this endpoint to poll for status, inspect the result summary, or fetch metadata such as read progress or write outcome details.




# Get backfill progress
Source: https://docs.ampersand.ai/reference/operation/get-backfill-progress

platform get /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}/objects/{objectName}/backfill-progress
Retrieve backfill progress (records processed, estimated total) for an object. Use to track progress of an initial data sync.



# List logs for an operation
Source: https://docs.ampersand.ai/reference/operation/list-logs-for-an-operation

platform get /projects/{projectIdOrName}/operations/{operationId}/logs



# List operations
Source: https://docs.ampersand.ai/reference/operation/list-operations

platform get /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}/operations



# Add user to an organization
Source: https://docs.ampersand.ai/reference/org/add-user-to-an-organization

platform post /orgs/{orgId}/memberships
Adds a builder to an organization. Two authorization modes - Org owner inviting another user, or self-joining via claimed domain (authenticated user's email domain should be claimed by this organization).



# Check if a domain is claimed
Source: https://docs.ampersand.ai/reference/org/check-if-a-domain-is-claimed

platform get /claimed-domains
Returns claimed domain information if authenticated user is an owner of the organization that claimed the domain, or if the user's email domain matches the claimed domain.



# Claim a domain
Source: https://docs.ampersand.ai/reference/org/claim-a-domain

platform post /claimed-domains
Claim a domain for an organization. Accepts email, domain, or URL.



# Create a new organization
Source: https://docs.ampersand.ai/reference/org/create-a-new-organization

platform post /orgs



# Get an invite
Source: https://docs.ampersand.ai/reference/org/get-an-invite

platform get /orgs/{orgId}/invites/{inviteId}



# Get an organization
Source: https://docs.ampersand.ai/reference/org/get-an-organization

platform get /orgs/{orgId}



# Invite a user to an organization
Source: https://docs.ampersand.ai/reference/org/invite-a-user-to-an-organization

platform post /orgs/{orgId}/invites



# List builders for an organization
Source: https://docs.ampersand.ai/reference/org/list-builders-for-an-organization

platform get /orgs/{orgId}/builders



# List invites for an organization
Source: https://docs.ampersand.ai/reference/org/list-invites-for-an-organization

platform get /orgs/{orgId}/invites



# List organization's claimed domains
Source: https://docs.ampersand.ai/reference/org/list-organizations-claimed-domains

platform get /orgs/{orgId}/claimed-domains
Get all domains claimed by a specific organization



# Revoke an invite
Source: https://docs.ampersand.ai/reference/org/revoke-an-invite

platform delete /orgs/{orgId}/invites/{inviteId}



# Update an organization
Source: https://docs.ampersand.ai/reference/org/update-an-organization

platform patch /orgs/{orgId}



# Create a new project
Source: https://docs.ampersand.ai/reference/project/create-a-new-project

platform post /projects
Creates a new project within an organization. A project is a container for provider apps, integrations, and connections.



# Get a project
Source: https://docs.ampersand.ai/reference/project/get-a-project

platform get /projects/{projectIdOrName}
Get a project by its ID or name.



# List projects
Source: https://docs.ampersand.ai/reference/project/list-projects

platform get /projects
Lists projects your credentials can access.



# Update a project
Source: https://docs.ampersand.ai/reference/project/update-a-project

platform patch /projects/{projectIdOrName}
Update a project's mutable fields using field masks. Currently, the updatable fields are `appName` (the display name shown to end users) and `name` (the unique project identifier).



# Create a new provider app
Source: https://docs.ampersand.ai/reference/provider-app/create-a-new-provider-app

platform post /projects/{projectIdOrName}/provider-apps



# Delete a provider app.
Source: https://docs.ampersand.ai/reference/provider-app/delete-a-provider-app

platform delete /projects/{projectIdOrName}/provider-apps/{providerAppId}



# List provider apps
Source: https://docs.ampersand.ai/reference/provider-app/list-provider-apps

platform get /projects/{projectIdOrName}/provider-apps



# Update a provider app
Source: https://docs.ampersand.ai/reference/provider-app/update-a-provider-app

platform patch /projects/{projectIdOrName}/provider-apps/{providerAppId}



# Get provider
Source: https://docs.ampersand.ai/reference/provider/get-provider

platform get /providers/{provider}
Returns information about a single provider. No authentication is required.




# List providers
Source: https://docs.ampersand.ai/reference/provider/list-providers

platform get /providers
Returns all supported SaaS providers and their capabilities. The response is a JSON object keyed by provider name (e.g. `salesforce`, `hubspot`). Each value describes the provider's authentication type, supported operations, modules, and configuration options. No authentication is required.




# Deliver results
Source: https://docs.ampersand.ai/reference/read/deliver-results

read post /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}:deliverResults
This endpoint is deprecated. If you wish you trigger a read (including backfills), use the [trigger a read](https://docs.ampersand.ai/reference/read/trigger-a-read) endpoint instead.



# Pause reads for an installation
Source: https://docs.ampersand.ai/reference/read/pause-reads-for-an-installation

read post /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}:pause
Pauses all scheduled reads for an installation. If reads are already paused, this will be a no-op. Accepts specific objects to pause reads for in the request body.



# Trigger a read
Source: https://docs.ampersand.ai/reference/read/trigger-a-read

read post /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}
Triggers reading data from a SaaS instance. See [Trigger a read](https://docs.ampersand.ai/read-actions#trigger-a-read) for details. If you want scheduled reads or automatic backfills instead, you [can define them in the manifest](https://docs.ampersand.ai/read-actions#defining-reads).



# Unpause reads for an installation
Source: https://docs.ampersand.ai/reference/read/unpause-reads-for-an-installation

read post /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}:unpause
Unpauses all scheduled reads for an installation. If no reads were paused, this will be a no-op. Accepts specific objects to unpause reads for in the request body.



# Create a new revision.
Source: https://docs.ampersand.ai/reference/revision/create-a-new-revision

platform post /projects/{projectIdOrName}/integrations/{integrationId}/revisions
We recommend using the [CLI's deploy command](https://docs.ampersand.ai/cli/overview#deploy-integrations) rather than this API endpoint directly, unless you have an advanced use case.



# Get a hydrated revision
Source: https://docs.ampersand.ai/reference/revision/get-a-hydrated-revision

platform get /projects/{projectIdOrName}/integrations/{integrationId}/revisions/{revisionId}:hydrate
Returns the integration revision enriched with live field metadata from the consumer's connected SaaS instance, such as available fields, display names, and type for each object defined in the integration.




# Search records
Source: https://docs.ampersand.ai/reference/search/search-records

search post /projects/{projectIdOrName}/integrations/{integrationId}
Search records in a SaaS instance.



# Generate a signed URL to upload a zip file to.
Source: https://docs.ampersand.ai/reference/upload-url/generate-a-signed-url-to-upload-a-zip-file-to

platform get /generate-upload-url



# Accept an invite
Source: https://docs.ampersand.ai/reference/user/accept-an-invite

platform post /invites:accept



# Get information about the current user
Source: https://docs.ampersand.ai/reference/user/get-information-about-the-current-user

platform get /my-info



# Write records
Source: https://docs.ampersand.ai/reference/write/write-records

write post /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}
Create, update, or delete records in a SaaS instance. Create and update support synchronous or asynchronous mode; delete is synchronous only. See [Write actions](https://docs.ampersand.ai/write-actions) for details.



# Search actions
Source: https://docs.ampersand.ai/search-actions



A search action allows you to search for records in your customer's SaaS instance by specifying filter criteria. The matching results are returned synchronously in the API response.

<Note>
  The Search API returns only a single page of provider results and is intended for narrow, targeted queries.
</Note>

## Enabling search for an object

Search does not require a separate action type in the manifest. Instead, it uses the `read` action. An object is searchable as long as it is defined under `read` in your `amp.yaml` and is not disabled in the installation config. There are two ways to ensure an object is searchable:

### Option 1: Set `enabled: "always"` in the manifest

By setting `enabled: "always"` on an object, it will always be enabled for every installation, regardless of the installation config. This is useful when you want to guarantee that the object is always searchable.

```YAML YAML theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: readSalesforce
    provider: salesforce
    read:
      objects:
        - objectName: contact
          enabled: "always"
```

### Option 2: Ensure the object is not disabled in the installation config

If you don't set `enabled: "always"` in the manifest, the object is searchable by default. However, the installation config must not set `disabled: true` for that object.

```YAML YAML theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: readSalesforce
    provider: salesforce
    read:
      objects:
        - objectName: contact
```

With this manifest, search will work as long as the installation config does not disable the object. For example, the following installation config would **prevent** search from working:

```json theme={"dark"}
// This would disable search for the contact object — avoid this if you want search to work
{
  "read": {
    "objects": {
      "contact": {
        "disabled": true
      }
    }
  }
}
```

## Execute a search

You can call the [search API](/reference/search/search-records) to search for records in a customer's SaaS instance. The results are returned synchronously in the API response.

Field mappings defined in `amp.yaml` and mappings selected by users during installation time will be respected and applied. See [Object and Field Mapping](/object-and-field-mapping) for more information.

Request example

```bash theme={"dark"}
curl --location 'https://search.withampersand.com/v1/projects/04bbc51e-7b5e-43c4-a453-e6d77ee55cb2/integrations/9a22a71b-d90b-4118-84c6-558771f3f6db?groupRef=searchTest-group-ref' \
  --header 'x-amp-request-type: search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --data '{
    "objectName": "account",
    "fieldFilters": [
      {
        "fieldName": "phoneNumber", // this is mapped field name selected by users during installation or in `amp.yaml`
        "operator": "eq",
        "value": "1234567890"
      },
      {
        "fieldName": "fax", // unmapped field name matching provider's field name.
        "operator": "eq",
        "value": "9876543210"
      }
    ]
  }'
```

Response example

```json theme={"dark"}
{
    "results": [
        {
            "fields": {
                "id": "00000000000001",
                "name": "test account"
            },
            "id": "00000000000001",
            "mappedFields": { // mapped fields are returned in separate field in the result object.
                "PhoneNumber": "1234567890"  
            },
            "raw": {
                "Id": "00000000000001",
                "Name": "test account",
                "Phone": "1234567890",
                "attributes": {
                    "type": "Account",
                    "url": "/services/data/v60.0/sobjects/Account/00000000000001"
                }
            }
        }
    ]
}
```

### Search with a raw filter

Instead of `fieldFilters`, you can search with a [raw filter](/read-actions#filter-with-a-raw-filter) in the provider's own query syntax. A search applies a raw filter exactly as a read action does, so it's a quick way to check a filter before adding it to an installation.

```bash theme={"dark"}
curl --location 'https://search.withampersand.com/v1/projects/04bbc51e-7b5e-43c4-a453-e6d77ee55cb2/integrations/9a22a71b-d90b-4118-84c6-558771f3f6db?groupRef=searchTest-group-ref' \
  --header 'x-amp-request-type: search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --data '{
    "objectName": "account",
    "rawFilter": {
      "type": "soql",
      "filter": "AnnualRevenue > 1000000 OR NumberOfEmployees > 500"
    }
  }'
```

* A request needs exactly one of `fieldFilters` or `rawFilter`.
* Field names in a raw filter are the provider's own. Field mappings are not applied to them.
* Raw filters are currently only supported for **Salesforce** (CRM Module). See [Salesforce raw filters](/provider-guides/salesforce#raw-filters-soql).


# Outgoing IP addresses
Source: https://docs.ampersand.ai/security/outgoing-ip-addresses

Add the fixed Ampersand outgoing IP addresses to a provider allowlist so read, write, proxy, and subscribe action requests to SaaS APIs are not blocked.

All outgoing API requests from Ampersand to SaaS providers originate from a fixed set of IP addresses. If a provider app or API you are integrating with supports IP allowlisting (sometimes called whitelisting), add the following IP addresses to its allowlist so that requests from Ampersand are not blocked.

## IP addresses to allowlist

```
34.53.82.136
34.53.32.186
34.182.109.175
```

These IP addresses apply to all outgoing traffic from Ampersand, including:

* [Read actions](/read-actions): API calls to read data from providers.
* [Write actions](/write-actions): API calls to write data to providers.
* [Proxy actions](/proxy-actions): API calls proxied through Ampersand.
* [Subscribe actions](/subscribe-actions): API calls to create and manage webhook subscriptions.


# Quickstart
Source: https://docs.ampersand.ai/starter-project

Clone a working React app with sample Ampersand integrations already wired up.

The [starter project](https://github.com/amp-labs/starter-project) is a small, working application you can clone and run. Use it when you would rather see a live integration first and read the details afterwards.

It contains two things:

<CardGroup>
  <Card title="A React app" icon="react">
    A minimal React and Vite app that embeds the `InstallIntegration` component, so you can watch a customer connect their account.
  </Card>

  <Card title="Three integrations" icon="file-code">
    Pick between HubSpot, Salesforce, and GitHub, or add your own.
  </Card>
</CardGroup>

## Before you start

Setting up the accounts and credentials takes longer than running the app itself. Budget around twenty minutes for these steps the first time.

<Steps>
  <Step title="Create an Ampersand project">
    Sign up for a [free Ampersand account](https://dashboard.withampersand.com/sign-up) and follow the prompts to create a project.
  </Step>

  <Step title="Create an API key">
    In the dashboard, open [API keys](https://dashboard.withampersand.com/projects/_/api-keys) and create one. Since the key is used by the React app, choose **UI Library** when asked where you will use it. You will paste it into the app later.
  </Step>

  <Step title="Create a destination named `defaultWebhook`">
    In [Destinations](https://dashboard.withampersand.com/projects/_/destinations), create a webhook destination called `defaultWebhook`. If you do not have an endpoint to point it at, [play.svix.com](https://play.svix.com) gives you a disposable one that shows incoming payloads in the browser, which is ideal for a first run.
  </Step>

  <Step title="Set up the provider">
    You can start with any of the three included integrations. Each provider guide walks you through creating an account and an app:

    * **HubSpot** reads and writes contacts and companies. Follow the [HubSpot provider guide](/provider-guides/hubspot).
    * **Salesforce** reads and writes accounts and contacts. Follow the [Salesforce provider guide](/provider-guides/salesforce).
    * **GitHub** reads and writes gists. Follow the [GitHub provider guide](/provider-guides/github).

    You can also use other integrations from our [samples repo](https://github.com/amp-labs/samples), or browse [our provider guides](/provider-guides/overview) for all supported integrations. Learn more in [Make it yours](#make-it-yours).
  </Step>

  <Step title="Install the CLI">
    Install the [Ampersand CLI](/cli/overview) and run `amp login` to authenticate.
  </Step>
</Steps>

## Run it

<Steps>
  <Step title="Clone and install">
    ```bash theme={"dark"}
    git clone https://github.com/amp-labs/starter-project.git
    cd starter-project
    npm install
    ```
  </Step>

  <Step title="Deploy the integration">
    ```bash theme={"dark"}
    amp deploy integrations/hubspot -p <your-project-name>
    ```

    Swap `hubspot` for `salesforce` or `github` to deploy one of the other included integrations. This creates a [revision](/concepts#revision) of the integration from its `amp.yaml`. Nothing syncs yet, because no customer has installed it.
  </Step>

  <Step title="Point the app at your project">
    In `src/App.tsx`, replace the placeholders with your project name and API key:

    ```tsx theme={"dark"}
    const options = {
      project: 'MY-PROJECT-NAME',
      apiKey: 'MY-API-KEY',
    };

    const integration = "hubspotCRM";
    ```

    If you deployed Salesforce or GitHub, set `integration` to `readAndWriteSalesforce` or `githubIntegration`, the `name` defined in that integration's `amp.yaml`.
  </Step>

  <Step title="Start the app">
    ```bash theme={"dark"}
    npm run dev
    ```

    Open the app (`http://localhost:5173` by default) and use the embedded component to connect an account for the integration you deployed. Once installed, reads run on the schedule in the manifest.
  </Step>

  <Step title="Check that it worked">
    Results arrive at your `defaultWebhook` destination once there is data to read. If you used [play.svix.com](https://play.svix.com), they show up on that page. To see every read, write, and proxy call and whether it succeeded, go to **Integrations** in the dashboard, open your integration, and select the installation.
  </Step>
</Steps>

## What the code does

The whole integration surface is one component. `AmpersandProvider` holds your project credentials, and `InstallIntegration` renders the connect and configure flow your customers see:

```tsx src/App.tsx theme={"dark"}
import { AmpersandProvider, InstallIntegration } from '@amp-labs/react'
import '@amp-labs/react/styles';

const options = {
  project: 'MY-PROJECT-NAME',
  apiKey: 'MY-API-KEY',
};

function App() {
  const integration = "hubspotCRM"; // must match the name in the amp.yaml you deployed

  return (
    <AmpersandProvider options={options}>
      <InstallIntegration
        integration={integration}
        consumerName="demo-user-name"
        consumerRef="demo-user-id"
        groupName="demo-company-name"
        groupRef="demo-company-id"
      />
    </AmpersandProvider>
  )
}
```

The `consumerRef` and `groupRef` values identify which of your customers is installing. In your own application these come from your user and account records, not hardcoded strings. See [Prebuilt UI components](/embeddable-ui-components) for the full set of props.

## Make it yours

<Steps>
  <Step title="Swap the integration">
    Add a new folder under `integrations/` with your own `amp.yaml`, or one from the [samples repository](https://github.com/amp-labs/samples), and deploy it the same way. See the [manifest schema](/manifest-reference) for every available field.
  </Step>

  <Step title="Keep the names aligned">
    Two names have to match: the integration name in `amp.yaml` and the `integration` variable in `App.tsx`, and the destination name in `amp.yaml` and the destination you created in the dashboard.
  </Step>

  <Step title="Redeploy after changes">
    Run `amp deploy` again whenever you edit the manifest. You only need one manifest for all your customers, and you can have multiple integrations in the same manifest.
  </Step>
</Steps>

## Where to go next

<CardGroup>
  <Card title="How Ampersand works" icon="book" href="/concepts">
    Integrations, installations, revisions, and configs.
  </Card>

  <Card title="Actions" icon="bolt" href="/overview#actions">
    Read, write, subscribe, and proxy.
  </Card>

  <Card title="Prebuilt UI components" icon="window-maximize" href="/embeddable-ui-components">
    Props, theming, and the other components in the library.
  </Card>
</CardGroup>


# Subscribe actions
Source: https://docs.ampersand.ai/subscribe-actions



With subscribe actions, you'll receive near-instant webhooks as events occur in your customers' SaaS applications. This enables your application to quickly react to events such as record creation, deletion, and field updates.

<Note>
  Please note that:

  * Subscribe actions are supported for a subset of providers. See the [provider guides](/provider-guides/overview) to check whether your provider supports subscribe actions and whether any additional setup is required.
  * Subscription lifecycle changes produce operations and logs in the [Ampersand dashboard](https://dashboard.withampersand.com). Receiving data events from a provider through a subscription does not create dashboard operations or logs. See [Subscription lifecycle observability](#subscription-lifecycle-observability).
  * It takes 1-2 minutes, and occasionally up to 10 minutes, for the first events to arrive after the initial installation.
</Note>

## Defining subscriptions

To subscribe to an object, you need to specify:

* **objectName:** to indicate which object you'd like to subscribe to. This should match the name of the object in the official documentation for the SaaS API.
* **destination:** the name of the [destination](/destinations) that you've defined
* **inheritFieldsAndMapping:** required when using `createEvent`, `updateEvent`, `deleteEvent`, or `associationChangeEvent`. Set this to `true` so the subscribe action inherits the mapped and unmapped fields from the matching Read Action. `true` is currently the only supported value. Learn more in [Fields and mapping](#fields-and-mapping).

You then need to specify the particular events you want to subscribe to. We support the following events:

* **createEvent**: triggers when a new record is created in the SaaS application.

* **updateEvent**: triggers when any existing record is modified. The `watchFieldsAuto: all` setting ensures that you subscribe to all field changes. Alternatively, you can list specific fields to watch in `requiredWatchFields`. **Note**: Only one of `requiredWatchFields` or `watchFieldsAuto` should be provided.

* **deleteEvent**: triggers when a record is removed from the system.

* **associationChangeEvent**: triggers when a record's associations have been modified. This is only supported for HubSpot. Please see [Association changes](#association-changes).

* **otherEvents**: gives you the ability to listen to any other events that are available in the provider API that Ampersand doesn't natively support. Please see [Other Events](#other-events).

### Specify fields to watch

You can provide fields to watch for update events and specify them in a list.

**Note**: Only one of `requiredWatchFields` or `watchFieldsAuto` should be provided.

Here is an example `amp.yaml`

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: subscribeToSalesforce
    provider: salesforce
    subscribe:
      objects:
        - objectName: account
          destination: accountWebhook
          inheritFieldsAndMapping: true # for now this must be true
          createEvent:
            enabled: always
          updateEvent:
            enabled: always
            requiredWatchFields:
              - phone
              - notes # this is user-defined mapped field, from read action below.
              - accountName # this is a pre-defined mapped field, from read action below.
            # watchFieldsAuto: all # alternative to `requiredWatchFields` if you wish to watch all fields
          deleteEvent:
            enabled: always
    read: # Read action is required
      objects:
        - objectName: account
          mapToName: company
          destination: accountWebhook
          requiredFields:
            - fieldName: id
            - fieldName: name
              mapToName: accountName 
            - mapToName: notes
              mapToDisplayName: Notes
              prompt: These are notes that you would like to surface in our app.
          optionalFields:
            - fieldName: annualrevenue
            - fieldName: website
```

For an example of a webhook message delivered according to the above `amp.yaml`, please see [Subscribe action webhooks](/destinations/webhooks#subscribe-action-webhooks).

### Association changes

In HubSpot, association changes do not trigger update events, you must subscribe to them specifically using `associationChangeEvent`. On the other hand, in Salesforce, you can subscribe to fields that refer to associations (e.g. You can subscribe to update events on the `accountid` field of contacts).

HubSpot example:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: hubspotAssociation
    provider: hubspot
    subscribe:
      objects:
        - objectName: contacts
          destination: contactsWebhook
          inheritFieldsAndMapping: true
          associationChangeEvent:
            enabled: always
            # Whether we should retrieve the associated record
            includeFullRecords: true
    read: # Read action is required
      objects:
        - objectName: contacts
          destination: contactsWebhook
          ...
```

Salesforce example:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: salesforceAssociation
    provider: salesforce
    subscribe:
      objects:
        - objectName: contact
          destination: contactWebhook
          inheritFieldsAndMapping: true
          updateEvent:
            enabled: always
            requiredWatchFields:
              - accountid
    read: # Read action is required
      objects:
        - objectName: contact
          destination: contactWebhook
          ...
```

### Other events

Beyond the standard events that Ampersand supports, you have the ability to subscribe to any other event that the underlying platform supports. The event names listed in `otherEvents` must match the provider's raw event names exactly.

For Salesforce this includes [events like](https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/cdc_event_fields_header.htm):

* `UNDELETE`

For HubSpot, this includes [events like](https://developers.hubspot.com/docs/api-reference/webhooks-webhooks-v3/guide#webhook-subscriptions):

* `{OBJECT_NAME}.restore` (e.g. `contact.restore`)
* `{OBJECT_NAME}.merge` (e.g. `contact.merge`)

To listen to these other events, add an `otherEvents` array to the subscribed object in your `amp.yaml`. If an object is subscribing only to `otherEvents` (no `createEvent`, `updateEvent`, or `deleteEvent`), it does not need its own matching entry in the `read` block, and `inheritFieldsAndMapping` is not required for that object. The `read` block itself must still exist on the integration.

In the example below, the `customers` object uses create/update/delete events and therefore must have a matching read object with `inheritFieldsAndMapping: true`. The `job.appointments` object subscribes only to `otherEvents` and has no matching read entry:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: subscribeToHousecallPro
    provider: housecallPro
    read:
      objects:
        - objectName: customers
          destination: housecallProWebhook
          schedule: "*/10 * * * *"
          requiredFields:
            - fieldName: id
          optionalFieldsAuto: all
          backfill:
            defaultPeriod:
              days: 15
    subscribe:
      objects:
        - objectName: customers
          destination: housecallProWebhook
          inheritFieldsAndMapping: true
          createEvent:
            enabled: always
          updateEvent:
            enabled: always
            watchFieldsAuto: all
          deleteEvent:
            enabled: always

        - objectName: job.appointments # Only otherEvents — no matching read entry needed
          destination: housecallProWebhook
          otherEvents: # Must match the provider's raw event names exactly
            - job.appointment.scheduled
            - job.appointment.rescheduled
            - job.appointment.appointment_discarded
            - job.appointment.appointment_pros_assigned
            - job.appointment.appointment_pros_unassigned
```

You can also combine `otherEvents` with standard events on the same object. In this Salesforce example, the `account` object subscribes to both `createEvent` and the non-standard `UNDELETE` event. Because it uses `createEvent`, it requires a matching read entry and `inheritFieldsAndMapping: true`:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: subscribeToSalesforce
    provider: salesforce
    subscribe:
      objects:
        - objectName: account
          destination: accountWebhook
          inheritFieldsAndMapping: true
          createEvent:
            enabled: always
          otherEvents:
            - UNDELETE
    read: # Required because `account` uses createEvent
      objects:
        - objectName: account
          destination: accountWebhook
          requiredFields:
            - fieldName: id
            - fieldName: name
```

### Specify backfill behavior

By combining subscribe actions with [read actions](/read-actions), you can get a full picture of all the data in your customer's SaaS instance. You can:

* Do a full backfill when the user first installs the integration to get historic data.
* Then, receive real-time updates about changes in their SaaS instance

Here is an example `amp.yaml`:

```yaml theme={"dark"}
specVersion: 1.0.0
integrations: 
 - name: subscribeToSalesforce
   provider: salesforce
   subscribe:
      objects:
       - objectName: account 
         destination: myWebhook
         inheritFieldsAndMapping: true
         createEvent:
            enabled: always
         updateEvent:
            enabled: always
            watchFieldsAuto: all
         deleteEvent:
            enabled: always
   read: # Read action is required
      objects:
       - objectName: account 
         destination: myWebhook
         requiredFields:
            - fieldName: name
            - fieldName: billingcity
              mapToName: city
              mapToDisplayName: City
            - mapToName: country
              mapToDisplayName: Country
              prompt: Which field is the country for the account?
          # Optional: read all accounts when integration is installed.
         backfill:
            defaultPeriod:
              fullHistory: true
```

If you do not wish to do a backfill when the integration is first installed, you can omit the backfill block in the read action definition. Because there aren't any schedules or backfills defined, the read action won't actually do anything but its fields and mappings will be used by the subscribe action.

```yaml theme={"dark"}
specVersion: 1.0.0
integrations: 
 - name: subscribeToSalesforce
   provider: salesforce
   subscribe:
      objects:
       - objectName: account 
         destination: myWebhook
         inheritFieldsAndMapping: true
         createEvent:
            enabled: always
         updateEvent:
            enabled: always
            watchFieldsAuto: all
         deleteEvent:
            enabled: always
   read: # Read action is required
      objects:
       - objectName: account 
         destination: myWebhook
         requiredFields:
            - fieldName: name
            - fieldName: billingcity
              mapToName: city
              mapToDisplayName: City
            - mapToName: country
              mapToDisplayName: Country
              prompt: Which field is the country for the account?
         # Omit schedule and backfill
```

## Fields and mapping

Your read action's set of fields and field mappings will apply to the subscribe action. When we deliver you the webhook, it will contain `fields` and `mappedFields` based on the fields and mapped fields from your read action. You can learn more in [Object and field mapping](/object-and-field-mapping).

```JS theme={"dark"}
{
  "action": "subscribe",
  "groupName": "Demo Group",
  "groupRef": "demo-group",
  "installationId": "692428b5-22b6-417d-9478-0375949223c0",
  "installationUpdateTime": "2025-03-21T04:20:16.872886Z",
  "objectName": "account",
  "projectId": "my-project-id",
  "provider": "salesforce",
  "result": [
    {
      "fields": { // Unmapped fields from read action
        "name": "Account ABC"
      },
      "mappedFields": { // Mapped fields from read action
        "city": "San Francisco",
        "country": "USA"
      },
      "subscribeEventType": "update",
      "providerEventType": "UPDATE",
      "raw": {
        "BillingCity": "San Francisco",
        "Id": "001Pa00000W4puRIAR",
        "Name": "Account ABC",
        "attributes": {
          "type": "Account",
          "url": "/services/data/v59.0/sobjects/Account/001Pa00000W4puRIAR"
        }
      },
      "rawEvent": {
        "ChangeEventHeader": {
          "changeOrigin": "com/salesforce/api/soap/63.0;client=SfdcInternalAPI/",
          "changeType": "UPDATE",
          "changedFields": [
            "Name",
            "LastModifiedDate"
          ],
          "commitNumber": 1742558812455698400,
          "commitTimestamp": 1742558812000,
          "commitUser": "005Do000000XDimIAG",
          "entityName": "Account",
          "recordId": "001Pa00000W4puRIAR",
          "sequenceNumber": 1,
          "transactionKey": "00004b85-ba97-e14f-68ca-cfa4c60f13ff"
        },
        "LastModifiedDate": "2025-03-21T12:06:52.000Z",
        "Name": "Account ABC"
      },
    }
  ],
  "resultInfo": {
    "numRecords": 1,
    "type": "inline"
  },
  "workspace": "customer-salesforce-subdomain"
}
```

## Receiving data

You will receive messages about events happening in your customer's SaaS instance. These look very similar to the messages for read actions. See [Subscribe action webhooks](/destinations/webhooks#subscribe-action-webhooks) for more information.

## Subscription lifecycle observability

The dashboard shows an operation when Ampersand creates, updates, or deletes a subscription, with logs describing the action. It does not show a separate operation or log for each incoming webhook. Lifecycle operations provide visibility into subscription setup without waiting for the first data event.

For example, setting up a subscription to Salesforce contacts produces a **Subscription Created** operation. Receiving a webhook because a contact’s email address changed does not create an operation.

Subscription lifecycle changes can also trigger success or error notifications. See [Notifications](/notifications/overview) for the supported events and configuration instructions.


# Terminal example
Source: https://docs.ampersand.ai/terminal-example



This is an example of a Terminal component that can be used in other pages. This page isn't discoverable in the table of contents (since it is not in `generate-docs.ts` or `docs.json`), but it is available at docs.ampersand.ai/terminal-example (or [http://localhost:3000/terminal-example](http://localhost:3000/terminal-example) when previewing locally).

<Terminal />


# Terminology
Source: https://docs.ampersand.ai/terminology



#### Config

A customer’s preference for which objects and fields they want your application to read or write, and fields they’ve mapped. Each Installation has its own Config.

#### Connection

A connection is a SaaS credential that Ampersand stores and manages which allows an integration to read or write data to or from a SaaS instance.

#### Consumer

A consumer is an individual end user that installs an integration.

#### Group

A group could be a company, team, or workspace within your app. All members of the group have access to its integrations, and only one member needs to install an integration for all members of the group to access it.

#### Manifest

The manifest file is a YAML file called `amp.yaml` that defines your integrations. You only have to define your integrations once across all your customers.

#### Installation

An installation is an instance of an integration, for a particular customer. Learn more on the [Concepts page](/concepts#installation).

#### Integration

An integration defines how your application will interact with a third party SaaS tool. Learn more on the [Concepts page](/concepts#integration).

#### Operation

An Operation happens every time there's a read, or write, or proxy API request to a third party API provider. You can view Operations in the Ampersand Dashboard, or query for them using the [operation endpoints](/reference/operation).

#### Primary key

The primary key is a UID generated by a SaaS provider (e.g. Salesforce) to uniquely identify an instance of an object.

Examples:

For Salesforce, it is the [ID field](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm#i1435616), which is a standard field for almost all objects.

For Hubspot, each object has an ID, for example [Contact](https://developers.hubspot.com/docs/api/crm/contacts) has a Contact ID.

#### Project

A project contains one or more integrations and their related data. An org can have one or more projects. Each project is uniquely identified by:

* A project name is chosen at the time of project creation, it must be globally unique and can contain numbers, letters and dashes, and is case insensitive.
* A project ID which is assigned by Ampersand at the time of project creation.

Different projects can be used to represent different environments, learn more in [Dev and prod environments](/dev-and-prod-environments).

#### Provider

A provider is a third-party API that Ampersand integrates with.

#### Provider app

A provider app describes the information that Ampersand stores about an OAuth app that is first created in a third party's system. For example, to integrate with Salesforce, you need to first create a Salesforce Connected App in the Salesforce Dashboard, and then create a Provider App in the Ampersand Dashboard with the Client ID and Client Secret from the Salesforce Connected App. For more information about how to create Provider Apps, refer to the [provider guides](/provider-guides/overview).

#### Revision

A revision is a particular version of an integration's definition. You create a new revision every time you modify the `amp.yaml` file and deploy the change via the amp CLI.


# General
Source: https://docs.ampersand.ai/troubleshooting-guides/general

Fix errors that can happen with any provider, including paused read schedules, proxy calls returning 429 Too Many Requests, and rejected webhook payloads.

For errors specific to one provider, see the other guides in this section or search the [troubleshooting index](/troubleshooting-guides/overview).

## Scheduled reads stopped running

**Symptom**: reads for an installation no longer run on schedule, or you received a `read.schedule.paused` [notification](/notifications/overview).

**Why this happens**: Ampersand pauses a read schedule when runs keep failing, most often because the customer's connection has expired or lost access.

**How to fix**:

1. Check the connection's status in the [Dashboard](https://dashboard.withampersand.com) or with the [Get connection endpoint](/reference/connection/get-a-connection). If it shows `bad_credentials`, have your customer [update the connection](/customer-guides/update-connection).
2. Once the connection is healthy, resume the schedule with the [Unpause reads endpoint](/reference/read/unpause-reads-for-an-installation).
3. Confirm the next run with the [List operations endpoint](/reference/operation/list-operations).

## Proxy call returns `429 Too Many Requests`

**Symptom**: [Proxy actions](/proxy-actions) intermittently return HTTP 429.

**Why this happens**: the provider is rate limiting the customer's account. Many providers penalize repeated 429s in a row, and some lock out a token entirely after too many unsuccessful requests.

**How to fix**:

1. Send the `X-Amp-Rate-Limiter-Mode: throttle` request header. Ampersand will then stop forwarding requests to the provider until it's safe to retry.
2. On a 429 response, read the `X-Amp-Retry-After` header (a UTC timestamp for when to retry) and `X-Amp-Retryable` (whether retrying is possible at all).
3. Retry after the suggested time. See [managing API rate limits](/proxy-actions#use-ampersand-to-manage-api-rate-limits).

## Webhook receiver rejects large payloads

**Symptom**: webhook deliveries fail or your endpoint returns `413 Payload Too Large`, especially during backfills.

**Why this happens**: Ampersand webhook payloads can be up to **300 KB**, and some HTTP frameworks default to a smaller request body limit. For example, Express's `json` middleware defaults to 100 KB.

**How to fix**:

1. Raise your framework's body size limit to at least 350 KB (for example, `express.json({ limit: "350kb" })`).
2. If your receiver can't accept payloads of this size at all, deliver results by URL instead. See [handling the payload size](/destinations/webhooks#handling-the-payload-size).

## Connection shows `bad_credentials`

**Symptom**: a connection's status is `bad_credentials`, or an installation stopped working after the customer changed their password, rotated a key, or revoked access.

**Why this happens**: the credentials Ampersand holds for the customer's SaaS instance are no longer valid, so every API call on their behalf fails.

**How to fix**:

1. Have your customer re-authenticate from the **Manage** tab of the embedded UI. See [update a connection](/customer-guides/update-connection).
2. If they need to switch accounts entirely, the same flow applies.
3. If reads were paused in the meantime, [unpause them](/reference/read/unpause-reads-for-an-installation) after re-authentication.

## Async write accepted but the record is missing

**Symptom**: an asynchronous [write](/write-actions) returned successfully, but the record never appeared in the customer's SaaS.

**Why this happens**: async mode accepts the write and processes it in the background. A success response means *accepted*, not *applied*. The operation may still be retrying or may have failed after retries. Ampersand retries failures with exponential backoff for 1 hour by default (configurable up to 48 hours).

**How to fix**:

1. Take the operation ID from the write response and check it with the [Get operation endpoint](/reference/operation/get-an-operation).
2. If the operation failed, inspect its logs with the [List logs endpoint](/reference/operation/list-logs-for-an-operation) for the provider's error.
3. For time-sensitive writes, consider [synchronous mode](/write-actions#synchronous-mode), or lengthen the [retry deadline](/write-actions#retry-policy-for-async-writes).


# Google
Source: https://docs.ampersand.ai/troubleshooting-guides/google

Diagnose and resolve common errors when running Google integrations, including Gmail.

## Google API calls fail with `400 Precondition check failed`

**Symptom**: calls to Google fail with HTTP `400` and the message `Precondition check failed.`, either in proxy responses or in the error details of failed operations.

**Why this happens**: Google can't authorize the request for that customer's account. Most often your provider app doesn't request the Gmail scopes the request needs, or your customer unchecked some of the requested permissions on Google's consent screen, which Google lets users do one scope at a time. For an installation that used to work, the customer or their Google Workspace admin may have revoked your app's access.

**How to fix**:

1. Find the affected installation in the [Ampersand Dashboard](https://dashboard.withampersand.com) or with the [List operations endpoint](/reference/operation/list-operations).
2. In the Dashboard, open **Provider Apps**, select your Google provider app, and check that the **Scopes** field includes every Gmail scope your integration needs. Also check that the Gmail API is [enabled in your Google Cloud project](/provider-guides/google#enable-the-appropriate-apis).
3. Ask your customer to reconnect and keep every requested permission checked on Google's consent screen. Your customer can re-authenticate in your product's Ampersand UI: from the **Manage** tab of the [Install integration](/embeddable-ui-components#install-integration) component (see [Update a connection](/customer-guides/update-connection); requires `@amp-labs/react` v2.7 or later), or with the reauthenticate option in the [Connect provider](/embeddable-ui-components#connect-provider) component.
4. If the installation used to work, ask your customer whether they or their Google Workspace admin revoked access to your app. Reconnecting restores access, as long as their Workspace admin allows your app.
5. If the error continues, contact [support@withampersand.com](mailto:support@withampersand.com) with the installation ID.

## Google returns `403 Forbidden` intermittently

**Symptom**: calls to Google sometimes fail with HTTP `403`, but not every time.

**Why this happens**: Google returns `403` for quota exceeded errors as well as for actual forbidden (permission) errors. If you see `403`s but not all the time, it's likely a quota issue, not an authorization issue.

## Google (workspace delegation): `unauthorized_client` error

**Symptom**: an error such as `unauthorized_client: Client is unauthorized to retrieve access tokens using this method`.

**Why this happens**: either:

* The service account's numeric Client ID wasn't added to **Manage Domain Wide Delegation** in your customer's Google Admin console (see [step 4 of the customer guide](/customer-guides/google-workspace-delegation#4-authorize-domain-wide-delegation)), or
* One or more scopes provided to the integration weren't among the scopes authorized in that step.

## Google (workspace delegation): `invalid_grant` error

**Symptom**: an error such as `invalid_grant: Invalid email or User ID`.

**Why this happens**: a user email provided for the connection isn't a valid, active user in your customer's Workspace domain. Workspace delegation doesn't work for suspended or deleted users. Confirm that the user's address exists in **Admin console** > **Directory** > **Users**.


# Microsoft Dynamics
Source: https://docs.ampersand.ai/troubleshooting-guides/microsoft-dynamics

Diagnose and resolve common errors when running Microsoft Dynamics 365 CRM and Business Central integrations.

These fixes apply to both [Dynamics 365 CRM](/provider-guides/dynamicsCRM) and [Dynamics 365 Business Central](/provider-guides/dynamicsBusinessCentral) unless noted.

## Every API call returns `401 Unauthorized` after the customer connects

**Symptom**: your customer completes the OAuth flow and the connection is created, but every read, write, and proxy call for that installation returns `401 Unauthorized`. The installation UI may also get stuck while loading the customer's objects and fields.

**Why this happens**: this is possibly due to invalid scopes. Dynamics rejects API calls if your provider app includes scopes that Dynamics doesn't support, even if the OAuth flow succeeds. You may have added `User.Read` or other scopes that belong to the Microsoft Graph API, not the Microsoft Dynamics API. Microsoft uses the first scope it sees to decide which API to grant access to.

**How to fix**:

1. In the [Ampersand Dashboard](https://dashboard.withampersand.com), open **Provider Apps** and select your Dynamics provider app.
2. In the **Scopes** field, remove any Microsoft Graph scopes and keep only Dynamics scopes plus `offline_access`:

   * **Dynamics 365 CRM**: `.default` or `user_impersonation`.
   * **Business Central**: `.default`.

   Enter only the scope name, not a full URL. Each customer's Dynamics instance has its own URL, and Ampersand adds it for you: for CRM, `.default` becomes `https://<instance>.api.<region>.dynamics.com/.default`. For Business Central, `.default` becomes `https://api.businesscentral.dynamics.com/.default`. If your integration needs a Dynamics scope other than these, contact [support@withampersand.com](mailto:support@withampersand.com).
3. Click **Save Changes**.
4. Ask each affected customer to reconnect. Tokens that were already issued are still for the wrong API, so the new scopes only take effect once the customer authorizes again. Your customer can re-authenticate in your product's Ampersand UI: from the **Manage** tab of the [Install integration](/embeddable-ui-components#install-integration) component (see [Update a connection](/customer-guides/update-connection); requires `@amp-labs/react` v2.7 or later), or with the reauthenticate option in the [Connect provider](/embeddable-ui-components#connect-provider) component.


# Overview
Source: https://docs.ampersand.ai/troubleshooting-guides/overview

Search the troubleshooting index by error message or provider, then follow the linked symptom, cause, and fix steps for errors you see in Ampersand.

<div>
  <div>
    <input type="text" placeholder="Search errors, e.g. 429, paused, no such column…" aria-label="Search troubleshooting entries" />

    <div>
      <button type="button">All</button>
      <button type="button">General</button>
      <button type="button">Google</button>
      <button type="button">Microsoft</button>
      <button type="button">Salesforce</button>
    </div>
  </div>

  <div>
    <a href="/troubleshooting-guides/general#scheduled-reads-stopped-running">
      <div>
        <div>Scheduled reads stopped running</div>
        <div>Reads paused after repeated failures. Check the connection, then unpause via API.</div>
      </div>

      <div>read</div>
    </a>

    <a href="/troubleshooting-guides/general#proxy-call-returns-429-too-many-requests">
      <div>
        <div>Proxy call returns `429 Too Many Requests`</div>
        <div>Use throttle mode and the retry-after headers instead of hammering the provider.</div>
      </div>

      <div>proxy</div>
    </a>

    <a href="/troubleshooting-guides/general#webhook-receiver-rejects-large-payloads">
      <div>
        <div>Webhook receiver rejects large payloads</div>
        <div>Payloads reach 300 KB, so raise your body-size limit or switch to URL delivery.</div>
      </div>

      <div>webhooks</div>
    </a>

    <a href="/troubleshooting-guides/general#connection-shows-bad_credentials">
      <div>
        <div>Connection shows `bad_credentials`</div>
        <div>The customer's credentials are no longer valid, so have them re-authenticate.</div>
      </div>

      <div>auth</div>
    </a>

    <a href="/troubleshooting-guides/general#async-write-accepted-but-the-record-is-missing">
      <div>
        <div>Async write accepted but the record is missing</div>
        <div>Accepted is not applied. Check the operation's status and logs.</div>
      </div>

      <div>write</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#read-action-no-such-column-error">
      <div>
        <div>Salesforce read: `No such column` error</div>
        <div>The connected user lacks field-level visibility, or the field name is wrong.</div>
      </div>

      <div>read</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#write-action-no-such-column-error">
      <div>
        <div>Salesforce write: `No such column` error</div>
        <div>The field doesn't exist in the customer's org, or the user can't see it.</div>
      </div>

      <div>write</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#subscribe-installation-fails-with-limit_exceeded">
      <div>
        <div>Salesforce subscribe fails with `LIMIT_EXCEEDED`</div>
        <div>Salesforce allows Change Data Capture on 5 entities by default. Reduce objects or add the license.</div>
      </div>

      <div>subscribe</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#subscribe-events-do-not-fire-when-a-field-changes">
      <div>
        <div>Salesforce subscribe events don't fire for a field</div>
        <div>Salesforce only emits change events for direct fields, not derived ones like LastActivityDate.</div>
      </div>

      <div>subscribe</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#connection-shows-bad_credentials-after-working-previously">
      <div>
        <div>Salesforce connection turns `bad_credentials`</div>
        <div>Missing refresh\_token scope, a reused app, an expiring token policy, or revoked access.</div>
      </div>

      <div>auth</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#salesforce-returns-invalid_session_id">
      <div>
        <div>Salesforce returns `INVALID_SESSION_ID`</div>
        <div>Check the connection's scopes, app reuse across projects, and duplicate connections.</div>
      </div>

      <div>auth</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#read-fails-with-too-many-junction-ids">
      <div>
        <div>Salesforce read: `too many junction ids`</div>
        <div>EmailMessage junction lookups exceed 500. Drop the ID fields or read EmailMessageRelation.</div>
      </div>

      <div>read</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#object-type-is-not-supported-for-a-standard-object">
      <div>
        <div>Salesforce: `Object type is not supported` for a standard object</div>
        <div>Usually an object permission gap for the connected user, not a missing object.</div>
      </div>

      <div>read</div>
    </a>

    <a href="/troubleshooting-guides/salesforce#check-salesforce-api-quota">
      <div>
        <div>Check a customer's Salesforce API quota</div>
        <div>Query the limits endpoint through the proxy when you suspect rate limiting.</div>
      </div>

      <div>proxy</div>
    </a>

    <a href="/customer-guides/salesforce-jwt#troubleshooting">
      <div>
        <div>Salesforce (JWT) installation fails</div>
        <div>Certificate, consumer key, and OAuth policy checks for the JWT flow.</div>
      </div>

      <div>auth</div>
    </a>

    <a href="/troubleshooting-guides/google#google-workspace-delegation--unauthorized_client-error">
      <div>
        <div>Google delegation: `unauthorized_client` error</div>
        <div>Domain-wide delegation isn't authorized for the service account's client ID and scopes.</div>
      </div>

      <div>auth</div>
    </a>

    <a href="/troubleshooting-guides/google#google-workspace-delegation--invalid_grant-error">
      <div>
        <div>Google delegation: `invalid_grant` error</div>
        <div>The impersonated user or key is invalid. Check the connection details.</div>
      </div>

      <div>auth</div>
    </a>

    <a href="/troubleshooting-guides/google#google-api-calls-fail-with-400-precondition-check-failed">
      <div>
        <div>Google: `400 Precondition check failed`</div>
        <div>Calls to Google fail with HTTP 400 and the message `Precondition check failed.`</div>
      </div>

      <div>auth</div>
    </a>

    <a href="/troubleshooting-guides/google#google-returns-403-forbidden-intermittently">
      <div>
        <div>Google: intermittent `403 Forbidden`</div>
        <div>Some calls to Google fail with HTTP 403, but not every time.</div>
      </div>

      <div>proxy</div>
    </a>

    <a href="/troubleshooting-guides/microsoft-dynamics#every-api-call-returns-401-unauthorized-after-the-customer-connects">
      <div>
        <div>Dynamics: every API call returns `401 Unauthorized`</div>
        <div>The OAuth flow succeeds, but every API call for the installation returns 401.</div>
      </div>

      <div>auth</div>
    </a>
  </div>

  <div />
</div>

## Can't find your error?

Email [support@withampersand.com](mailto:support@withampersand.com) or ask in your shared Slack channel with our engineers. If you think the docs should cover it, [file an issue](https://github.com/amp-labs/docs/issues).


# Salesforce
Source: https://docs.ampersand.ai/troubleshooting-guides/salesforce

Diagnose and resolve common errors when running Salesforce integrations.

## Read Action: `No such column` error

A read fails with an error similar to:

```text theme={"dark"}
bad request:
field_one__c,field_two__c,example_field__c,field_three__c,field_four__c
                          ^
ERROR at Row:1:Column:26
No such column 'example_field__c' on entity 'Opportunity'. If you are attempting to use a custom field,
be sure to append the '__c' after the custom field name. Please reference your WSDL or the describe call
for the appropriate names.
```

<Tip>
  **Which case is this?**

  * Reads work for other customers but fail for this one → almost always a [field-level visibility issue](#resolve-a-field-level-visibility-issue). Even System Administrators do **not** automatically receive visibility for every field.
  * Reads fail for *every* customer → the [field name itself](#verify-the-field-name) is more likely the problem.
</Tip>

### Resolve a field-level visibility issue

Share the [field visibility instructions in the Salesforce customer guide](/customer-guides/salesforce#choose-credentials-and-grant-access) with your customer. That user must be granted **Visible** field-level visibility for the field, either through their profile or via a permission set.

Ampersand pauses reads automatically after repeated failures to avoid overloading Salesforce APIs, so once the field is visible you'll need to explicitly resume. Call the [Unpause Reads endpoint](/reference/read/unpause-reads-for-an-installation), or reach out to Ampersand support and we can unpause it for you.

### Verify the field name

1. Look up the field in the [Salesforce Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_concepts.htm). If it's listed, the field is standard and this is a [field-level visibility issue](#resolve-a-field-level-visibility-issue).
2. If it's not listed, it's a custom field. Custom field API names must end with `__c`. If your read object configuration is missing the suffix, fix it.
3. If the suffix is already correct, this is a [field-level visibility issue](#resolve-a-field-level-visibility-issue).

## Write Action: `No such column` error

A write fails with an error similar to:

```json theme={"dark"}
{
  "operationId": "00000000-0000-0000-0000-000000000000",
  "errors": [
    {
      "message": "error writing account: bad request: No such column 'Testing__c' on sobject of type Account"
    }
  ]
}
```

<Tip>
  **Which case is this?**
  Call [Get object metadata via installation](/reference/objects-&-fields/get-object-metadata-via-installation) for the object you're writing to.

  * The field isn't in the response → it [doesn't exist in the customer's org](#field-doesnt-exist-in-the-customers-org). Custom fields vary by org.
  * The field is in the response → the [connected user can't see it](#connected-user-lacks-field-level-visibility).
</Tip>

### Field doesn't exist in the customer's org

Remove the field from your write payload for this customer, for example by checking object metadata before writing, or by falling back to a default. Longer-term, update your application to handle per-customer schema differences.

### Connected user lacks field-level visibility

If the field exists in the org but isn't visible to the connected user's profile, Salesforce returns the same `No such column` error. Follow the steps in [Resolve a field-level visibility issue](#resolve-a-field-level-visibility-issue).

## Subscribe installation fails with `LIMIT_EXCEEDED`

Creating an installation with subscribe actions fails with an error similar to:

```text theme={"dark"}
You can't select more entities. You've exceeded the maximum number of unique
Change Data Capture selected entities. Your total number of entities includes
the ones selected here and through custom channels. (errorCode: LIMIT_EXCEEDED)
```

By default, a Salesforce instance allows Change Data Capture on at most **five entities**. Entities your customer has selected through custom channels count toward the same limit, so the ceiling can be reached before your integration is installed.

You have two ways to resolve this:

1. Reduce the number of objects your integration subscribes to, so the total stays within the customer's limit.
2. Ask your customer to purchase the Salesforce Change Data Capture add-on license, which removes the limit on their instance.

## Subscribe events do not fire when a field changes

A subscription is healthy and other updates arrive, but changes to one specific field never produce an event.

Salesforce only emits change events for **direct fields** on a record. Derived fields such as `LastActivityDate` never trigger change events, no matter how they are configured. See Salesforce's [change event documentation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_associated_objects_change_event.htm) for the full list of limitations.

Watch a direct field instead, or subscribe to the object whose direct fields capture the change you care about.

## Connection shows `bad_credentials` after working previously

An integration that used to work starts failing: proxy requests return `401`, reads and writes fail, and the connection's status is `bad_credentials`.

<Tip>
  **Which case is this?**

  * Failing for *every* customer → most likely your [External Client App is misconfigured](#check-your-external-client-app) or shared across projects.
  * Failing for *one* customer → most likely a [token policy or revoked access](#check-the-customers-salesforce-settings) on their side.
</Tip>

### Check your External Client App

Confirm the app requests the `refresh_token` scope. Without it, Salesforce issues an access token that expires and cannot be renewed. Review your configuration against [Create External Client App](/provider-guides/salesforce#4-create-external-client-app).

Also confirm you are not reusing one app across multiple Ampersand projects. Each project should have its own app.

### Check the customer's Salesforce settings

Two customer-side settings commonly invalidate credentials:

1. **Refresh token policy.** If their policy expires refresh tokens after a set period, credentials break on that schedule. Ask them to set the policy to **Refresh token is valid until revoked** in the app's OAuth policies.
2. **Revoked access.** A Salesforce admin can revoke an app from the OAuth Connected Apps Usage page. Ask their admin to confirm the app has not been revoked.

Once resolved, your customer can reconnect from the **Manage** tab. See [Update a connection](/customer-guides/update-connection).

## Salesforce returns `INVALID_SESSION_ID`

An API call fails with an error similar to:

```json theme={"dark"}
{
  "message": "This session is not valid for use with the specified REST API endpoint. One of the following scopes is required: Full access, Manage user data via APIs, Access Connect REST API resources",
  "errorCode": "INVALID_SESSION_ID"
}
```

Work through these in order:

1. Confirm the connection's scopes include both `api` and `refresh_token`. If either is missing, correct your [External Client App configuration](/provider-guides/salesforce#4-create-external-client-app).
2. Confirm you are not using the same app across multiple projects.
3. Check for duplicate connections for the same customer. Connecting the same Salesforce instance twice invalidates the earlier refresh token, so the first connection stops working. Delete the duplicates.

If none of those apply, ask your customer to uninstall and reinstall the integration, following the [Salesforce customer guide](/customer-guides/salesforce).

## Read fails with `too many junction ids`

A read of `EmailMessage` fails with:

```text theme={"dark"}
Query is requesting too many junction ids; limit is 500
```

The query exceeded Salesforce's limit on junction object lookups. On `EmailMessage`, the junction fields are `ToIds`, `CcIds`, `BccIds`, and `ContentDocumentIds`. A single mass email with hundreds of recipients can exceed the limit of 500 on its own.

<Tip>
  **Which case is this?** Check whether you actually need the recipient IDs, or only their addresses.

  * You only need addresses → [remove the junction fields](#remove-the-junction-fields).
  * You need the IDs → [read `EmailMessageRelation` instead](#read-emailmessagerelation-instead).
</Tip>

### Remove the junction fields

Drop the junction fields from `requiredFields` in your manifest:

```yaml theme={"dark"}
requiredFields:
  - fieldName: toids   # remove this
```

The recipient addresses remain available through `toAddress`, `ccAddress`, and `bccAddress`, so most integrations lose nothing.

### Read `EmailMessageRelation` instead

If you need the IDs themselves, add the [`EmailMessageRelation`](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_emailmessagerelation.htm) object to your read action. This is the object that `ToIds`, `CcIds`, and `BccIds` actually refer to, and it exposes the same information without the junction limit:

* `EmailMessageId`
* `RelationAddress`
* `RelationId`
* `RelationObjectType`
* `RelationType`, for example `ToAddress`, `CcAddress`, or `BccAddress`

## `Object type is not supported` for a standard object

A read or write fails with an error similar to:

```text theme={"dark"}
Object type 'contact' is not supported. If you are attempting to use a custom object,
be sure to append the '__c' after the entity name.
```

When the object named is a standard Salesforce object, this error is misleading. It usually means the connected user does not have permission to access the object, so Salesforce reports it as though it does not exist.

Ask your customer's Salesforce admin to check the connected user's object permissions:

* For a standard profile, see [Field permissions for a standard profile](/customer-guides/salesforce#2a-field-permissions-for-a-standard-profile).
* For a custom profile, see [Object and field permissions for a custom profile](/customer-guides/salesforce#2b-object-and-field-permissions-for-a-custom-profile).

## Check Salesforce API quota

When you suspect a customer is hitting Salesforce API limits, you can read their remaining quota through the proxy:

```bash theme={"dark"}
curl --request GET "https://proxy.withampersand.com/services/data/v62.0/limits" \
  --header "Content-Type: application/json" \
  --header "x-amp-proxy-version: 1" \
  --header "x-amp-project-id: YOUR_PROJECT_ID" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "x-amp-integration-name: YOUR_INTEGRATION" \
  --header "x-amp-group-ref: GROUP_REF"
```

The response includes `DailyApiRequests`, which shows the org's daily allocation and how much of it remains.


# Build your own unified API
Source: https://docs.ampersand.ai/unified-api



## What is a unified API?

A unified API provides a single, consistent interface to interact with multiple third-party services. Instead of learning each provider's unique schema, you define one schema that works across all of them.

This guide covers one of Ampersand's use cases: building unified APIs. You can also use Ampersand for provider-specific integrations or mix both approaches. Unlike traditional unified API providers that force you into their predefined models, Ampersand lets you design your own schema.

## Why build a unified API?

* **Faster development** - Add new integrations without changing application logic
* **Consistent data model** - One schema regardless of source
* **No vendor lock-in** - You control the schema and where data lives

## How it works

### 1. Map objects and fields

```yaml theme={"dark"}
# Map different provider objects to unified names
- objectName: account        # Salesforce
  mapToName: company
  requiredFields:
    - fieldName: name
      mapToName: company_name
    - fieldName: annualrevenue
      mapToName: revenue

- objectName: companies      # HubSpot
  mapToName: company
  requiredFields:
    - fieldName: name
      mapToName: company_name
    - fieldName: annualrevenue
      mapToName: revenue
```

### 2. Receive unified + raw data

Every webhook includes your mapped fields, non-mapped fields, and the complete provider response:

```json theme={"dark"}
{
  "mappedFields": {
    "company_name": "Acme Corp",
    "revenue": 5000000
  },
  "fields": {
    "id": "001abc",
    "createddate": "2024-01-15T10:30:00Z",
    "systemmodstamp": "2024-08-23T14:20:07Z"
  },
  "raw": {
    "Id": "001abc",
    "Name": "Acme Corp",
    "AnnualRevenue": 5000000,
    "CreatedDate": "2024-01-15T10:30:00Z",
    "SystemModstamp": "2024-08-23T14:20:07Z",
    "Custom_Field__c": "value"
  }
}
```

### 3. Real-time updates with subscribe actions

Get webhooks when data changes (1-2 minutes latency):

```yaml theme={"dark"}
subscribe:
  objects:
    - objectName: account
      destination: webhook
      inheritFieldsAndMapping: true
      updateEvent:
        enabled: always
        requiredWatchFields:
          - company_name  # Your unified field
          - revenue
```

```json theme={"dark"}
// Webhook payload on update
{
  "subscribeEventType": "update",
  "mappedFields": {
    "company_name": "Acme Corp Updated",
    "revenue": 6000000
  },
  "raw": { /* full provider data */ }
}
```

## Key architectural differences from Merge

### Data persistence

**Ampersand:** No data storage for better security posture. Ampersand acts as the transport and transformation layer only. You control where and how to persist data.

**Merge:** Stores all customer data in Merge servers by default. "Merge Destinations" (Enterprise) enables you to turn off storage.

**Why it matters:** For healthcare, finance, or regulated industries, Ampersand's transport-only architecture eliminates compliance concerns around third-party data storage.

### Two-way sync

**Ampersand:**

* **Read**: Scheduled syncs or real-time subscribe actions with field-level granularity
* **Write**: Direct writes with automatic field mapping - your unified schema works for both reads and writes
* **Pattern**: Subscribe + write = true bidirectional real-time sync

**Merge:**

* **Read**: Scheduled syncs + poll after webhook notifications (model-level)
* **Write**: Direct writes, but no unified mapping - you must query `/meta` per integration to discover required fields
* **Pattern**: Polling + writes

### Comparison table

| Feature | Ampersand | Merge |
| - | - | - |
| **Schema** | You define it | Fixed common model |
| **Raw data** | Always included | Requires `include_remote_data=true` flag |
| **Data storage** | No persistent storage | Stored in Merge cloud |
| **Real-time** | Subscribe actions (all plans) | Third-party webhooks (Pro/Enterprise) |
| **Event granularity** | Field-level changes | Model-level notifications |
| **Write mapping** | Automatic - reuses your read schema | Manual - query `/meta` per integration |

### Ticketing unified API

Standardize tickets across Jira, Linear, Zendesk, and ServiceNow:

<CodeGroup>
  ```yaml Jira theme={"dark"}
  - objectName: issue
    mapToName: ticket
    requiredFields:
      - fieldName: id
        mapToName: remote_id
      - fieldName: summary
        mapToName: title
      - fieldName: status
        mapToName: status
  ```

  ```yaml Linear theme={"dark"}
  - objectName: issues
    mapToName: ticket
    requiredFields:
      - fieldName: id
        mapToName: remote_id
      - fieldName: title
        mapToName: title
      - fieldName: state
        mapToName: status
  ```

  ```json Result theme={"dark"}
  {
    "mappedFields": {
      "remote_id": "LIN-123",
      "title": "Fix bug",
      "status": "in_progress"
    },
    "raw": {
      "id": "LIN-123",
      "title": "Fix bug",
      "state": { "name": "In Progress" },
      "priority": 2,
      "assignee": { "id": "user-456" }
    }
  }
  ```
</CodeGroup>

## Migration from Merge

<Steps>
  <Step title="Understand the persistence model">
    **Merge:** Stores your customer data; you poll their API\
    **Ampersand:** Streams data to your webhooks; you store it

    Set up webhook endpoints and decide on your storage strategy (database, warehouse, etc.)
  </Step>

  <Step title="Use compatible templates">
    ```bash theme={"dark"}
    git clone https://github.com/amp-labs/samples.git
    cd samples/unifiedCRM
    amp deploy --project=my-project
    ```
  </Step>

  <Step title="Update webhook handlers">
    ```javascript theme={"dark"}
    // Merge: Poll after webhook notification
    app.post('/merge-webhook', async (req, res) => {
      const contacts = await merge.crm.contacts.list({
        modified_after: lastSync,
        include_remote_data: true
      });
      await db.contacts.bulkUpsert(contacts);
      res.sendStatus(200);
    });

    // Ampersand: Data arrives in webhook
    app.post('/webhook/contacts', async (req, res) => {
      const { mappedFields, fields, raw } = req.body.result[0];
      await db.contacts.upsert({
        ...mappedFields,
        ...fields,
        providerData: raw
      });
      res.sendStatus(200);
    });
    ```
  </Step>

  <Step title="Add real-time with subscribe actions">
    ```yaml theme={"dark"}
    subscribe:
      objects:
        - objectName: opportunity
          inheritFieldsAndMapping: true
          updateEvent:
            enabled: always
            requiredWatchFields:
              - amount
              - stage
    ```

    Handle events in your webhook:

    ```javascript theme={"dark"}
    const { subscribeEventType, mappedFields } = req.body.result[0];

    if (subscribeEventType === 'update' && mappedFields.stage === 'closed-won') {
      await triggerSalesWorkflow(mappedFields);
    }
    ```
  </Step>
</Steps>

## Related resources

* [Unified CRM example](https://github.com/amp-labs/samples/tree/main/unifiedCRM) - Complete sample for Salesforce, HubSpot, Zoho, and Dynamics 365
* [Object and Field Mapping](/object-and-field-mapping) - Technical details on mapping configuration
* [Read Actions](/read-actions) - Scheduled data syncs and backfills
* [Subscribe Actions](/subscribe-actions) - Real-time event subscriptions
* [Write Actions](/write-actions) - Writing data back to providers
* [Destinations](/destinations) - Configuring webhook destinations


# Use with Claude Code
Source: https://docs.ampersand.ai/use-with-ai-ide



Ampersand offers two MCP servers that you can add to Claude Code or favorite coding agent:

* The [builder MCP server](#builder-mcp-server) helps you build and manage integrations with Ampersand. Your agent can use it to create new integrations, manage installations, connections and destinations, troubleshoot failed operations, and scaffold webhook handlers. It requires an Ampersand account.
* The [docs MCP server](#docs-mcp-server) gives your agent access to the Ampersand documentation. It does not require an Ampersand account.

## Builder MCP server

Ampersand's builder MCP server is hosted at `https://builder-mcp.withampersand.com/v1/mcp`.

### Claude Code set up

1. If you don't have an Ampersand account yet, [create an account for free](https://dashboard.withampersand.com/sign-up).

2. Add the MCP server to Claude Code by running this command in your terminal.

```shell theme={"dark"}
claude mcp add ampersand --transport http "https://builder-mcp.withampersand.com/v1/mcp"
```

3. Launch Claude Code, then type `/mcp`, select `ampersand`, and choose **Authenticate**.

4. Sign into your Ampersand account.

5. Verify that the MCP server is set up correctly by asking Claude:

```
What can Ampersand do?
```

### Tips for better prompts

* Mention Ampersand in your prompt. For example, "How do I build X with Ampersand?"

* Name the project you want your agent to work in. For example, "In my Ampersand project acme-dev, why did the last read of Salesforce contacts fail?"

* Ask your agent to verify field names against the provider's documentation. For example, "Verify that the field names are real field names for the Account object, according to Salesforce documentation."

* Explicitly ask your agent to refer to Ampersand documentation and OpenAPI spec.

## Docs MCP server

Ampersand's docs MCP server is hosted at `https://docs.ampersand.ai/mcp`.

If you are using Claude Code, you can run this command:

```shell theme={"dark"}
claude mcp add ampersand-docs --transport http "https://docs.ampersand.ai/mcp"
```

## Other coding agents

You can use Ampersand's MCP servers with any AI application that supports [MCP](https://modelcontextprotocol.io/clients). You need to add the appropriate URL for the MCP server you want to use:

* Builder MCP: `https://builder-mcp.withampersand.com/v1/mcp`
* Docs MCP: `https://docs.withampersand.com/mcp`

Below are some of the most popular coding agents, and where to configure MCP servers for them:

| Client | Configuration File Location | Documentation |
| - | - | - |
| Claude Code | `.mcp.json` (project scope) or `~/.claude.json` (user/local scope); or `claude mcp add` | [link](https://code.claude.com/docs/en/mcp) |
| Cursor | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) | [link](https://cursor.com/docs/mcp) |
| JetBrains IDEs (Junie) | `~/.junie/mcp/mcp.json` (user) or `.junie/mcp/mcp.json` (project); or **Settings → Tools → Junie → MCP Settings** | [link](https://junie.jetbrains.com/docs/junie-plugin-mcp-settings.html) |
| Visual Studio Code | `.vscode/mcp.json` (workspace) or user `mcp.json` (**MCP: Open User Configuration**) | [link](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | [link](https://docs.windsurf.com/windsurf/cascade/mcp) |
| Zed | `context_servers` in `settings.json` (macOS/Linux: `~/.config/zed/settings.json`; Windows: `%AppData%\Zed\settings.json`) | [link](https://zed.dev/docs/ai/mcp) |


# Write actions
Source: https://docs.ampersand.ai/write-actions



A write action writes data to your customer's SaaS whenever you make an API request to us. This page focuses on writing data to existing fields. If you are looking to create new custom fields prior to writing data, please see [Create or update custom fields](/manage-customer-schemas#create-or-update-custom-fields).

## Defining writes

To define a write action, add `write` as a key in your integration defined in `amp.yaml`, and add a list of standard and custom objects you want to write to.

```YAML theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: write-to-salesforce
    displayName: Write to Salesforce
    provider: salesforce
    write:
      objects:
        - objectName: account
        - objectName: contact
        - objectName: touchpoints__c # You can include custom objects
```

### Share mappings with read actions

If you are using Read Actions and have already defined [field mappings](/read-actions#object-and-field-mappings), your Write Actions can automatically use the same mappings if you add `inheritMapping` to your manifest file. When you call our Write API, we will ensure that we are writing back to the appropriate field that the customer has mapped.

```YAML theme={"dark"}
specVersion: 1.0.0
integrations:
  - name: write-to-salesforce
    displayName: Write to Salesforce
    provider: salesforce
    write:
      objects:
        - objectName: account
          inheritMapping: true
```

## Writing records

Once your users install an integration with a write action, your app can write data to their SaaS by making a POST call to Ampersand, the URL is in the format of:

`https://write.withampersand.com/v1/projects/:projectIdOrName/integrations/:integrationId/objects/:objectName`

You can find your project ID and integration ID in the [Ampersand Dashboard](https://dashboard.withampersand.com) (look in the address bar) or you can run the following in the terminal to get `projectId` & `integrationId`:

```bash theme={"dark"}
# Get project ID
amp list:projects

# List integrations for project
amp list:integrations --project <PROJECT_ID>
```

`objectName` refers to the `objectName` key within the `amp.yaml` file that defines your integration. This must match the name of an object that exists within the SaaS instance.

### Create a new record

To create a new record, make a request to the [Write endpoint](/reference/write/write-records) with `type` being `create`. For example:

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/66438162-5299-4669-a41d-85c5a3b1a83e/integrations/113e9685-9a51-42cc-8662-9d9725b17f14/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "demo-group-id",
    "type": "create",
    "record": {
        "firstname": "Harry",
        "lastname": "Potter"
    }
}'
```

#### Create associations when creating a record

If you'd like to create records that are associated with other records, you can make a similar request with the `associations` parameter.

<Info> This is currently only supported for HubSpot. </Info>

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<YOUR_PROJECT_ID_OR_NAME>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "<GROUP_REF>",
    "type": "create",
    "record": {
        "firstname": "Harry",
        "lastname": "Potter",
        "email": "harry@hogwarts.com",
        "phone": "123456789"
    },
    "associations": [{
        "to": {"id": "18417469280"},
        "types": [{
            "associationCategory": "HUBSPOT_DEFINED",
            "associationTypeId": 279
        }]
    }]
}'
```

### Update an existing record

To update an existing record, you need to know the ID of the record, which is the ID that the SaaS provider uses to uniquely identify this record. If you created the record using Ampersand, this ID is available in the API response. If you are reading the record first using Ampersand's Read Actions, make sure you add the ID as a required field in the read action. Here is an example request:

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/66438162-5299-4669-a41d-85c5a3b1a83e/integrations/113e9685-9a51-42cc-8662-9d9725b17f14/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "demo-group-id",
    "type": "update",
    "record": {
        "id": "20scv09wer3klj",
        "firstname": "Harry",
        "lastname": "Potter"
    }
}'
```

### Delete a record

<Info>
  Deletion must be enabled for the object in the installation config. See [Enabling deletion for an object](#enabling-deletion-for-an-object) to enable deletion when creating or updating an installation.

  This is currently supported for HubSpot and Salesforce.
</Info>

To delete a record, call the [Write endpoint](/reference/write/write-records) with `type` set to `delete`. Provide the record `id` in the `record` object; no other fields are required. Delete operations are **synchronous only** and support **single-record** deletes.

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/<OBJECT_NAME>' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "demo-group-id",
    "type": "delete",
    "record": {
        "id": "20scv09wer3klj"
    }
}'
```

### Pass additional headers

If you need to pass additional headers when creating, updating, or deleting records for a provider, you can include those headers directly in the request body when calling the write endpoint. Ampersand will forward those headers as part of the outbound request to the provider.

<Info>This is currently only supported for Salesforce. </Info>

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<YOUR_PROJECT_ID_OR_NAME>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "<GROUP_REF>",
    "type": "create",
    "record": {
        "firstname": "Harry",
        "lastname": "Potter",
        "email": "harry@hogwarts.com",
        "phone": "123456789"
    },
    "headers": [
      {
        "key": "header-key1",
        "value": "header-value1"
      },
      {
        "key": "header-key2",
        "value": "header-value2"
      }
    ]
}'
```

### Batch write

Batch write allows you to create or update multiple records in a single API call. This is useful when you need to write large amounts of data efficiently. You can include 1-100 records per batch.

<Info>Batch write is currently only supported for HubSpot and Salesforce.</Info>

To perform a batch write, use the same [write endpoint](/reference/write/write-records) but provide a `batch` array instead of a single `record`:

`https://write.withampersand.com/v1/projects/:projectIdOrName/integrations/:integrationId/objects/:objectName`

Batch writes support both [synchronous and asynchronous modes](#write-modes). By default, batch writes use **partial success**, i.e., successful records will be committed even if some records in the batch fail. To fail the entire batch when any record fails, set [`batchPolicy.allOrNone`](/reference/write/write-records) to `true` in your request.

<Info>HubSpot batch updates always result in partial success due to a provider limitation, regardless of the `allOrNone` setting.</Info>

#### Batch create

To create multiple records in a batch, set `type` to `create`:

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "synchronous",
    "batch": [
        {
            "record": {
                "firstname": "Harry",
                "lastname": "Potter",
                "email": "harry@hogwarts.com"
            }
        },
        {
            "record": {
                "firstname": "Hermione",
                "lastname": "Granger",
                "email": "hermione@hogwarts.com"
            }
        }
    ]
}'
```

#### Batch update

To update multiple records in a batch, set `type` to `update` and include the record IDs:

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "update",
    "mode": "synchronous",
    "batch": [
        {
            "record": {
                "id": "20scv09wer3klj",
                "firstname": "Harry",
                "lastname": "Potter-Weasley"
            }
        },
        {
            "record": {
                "id": "30abc12xyz4mno",
                "firstname": "Hermione",
                "lastname": "Granger-Weasley"
            }
        }
    ]
}'
```

#### Batch write with associations

You can create records with associations in batch mode. Each record in the batch can have its own associations.

<Info>Associations in batch write are currently only supported for HubSpot.</Info>

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "synchronous",
    "batch": [
        {
            "record": {
                "firstname": "Harry",
                "lastname": "Potter",
                "email": "harry@hogwarts.com"
            },
            "associations": [{
                "to": {"id": "18417469280"},
                "types": [{
                    "associationCategory": "HUBSPOT_DEFINED",
                    "associationTypeId": 279
                }]
            }]
        },
        {
            "record": {
                "firstname": "Hermione",
                "lastname": "Granger",
                "email": "hermione@hogwarts.com"
            },
            "associations": [{
                "to": {"id": "18417469281"},
                "types": [{
                    "associationCategory": "HUBSPOT_DEFINED",
                    "associationTypeId": 279
                }]
            }]
        }
    ]
}'
```

### Auto batching

Ampersand can automatically group multiple single-record write requests together and execute them as a batch operation. This is useful when you want to reduce the amount of API quota that you are consuming in your customer's SaaS instance.

<Info>Auto batching is currently only available for asynchronous mode and single-record writes (not batch writes).</Info>

When you enable auto batching, Ampersand will:

1. **Accumulate records**: Multiple single-record write requests for the same installation, object, and write type (create or update) are automatically grouped together.
2. **Execute when ready**: The batch executes when either:
   * **100 records** have been accumulated, or
   * **Maximum delay time** has been reached (executes even if current batch has fewer than 100 records)

Each batch uses the max delay deadline set by the first record in that batch. This ensures records don't wait indefinitely.

#### Configuration

The auto batch policy has two configuration options:

* **`maxDelayMinutes`** (required): The maximum time to wait before executing the batch, even if it hasn't reached 100 records. Minimum: 1, Maximum: 1440 (24 hours).
* **`retryDeadlineHours`** (optional): The maximum time to keep retrying the batch write operation if it fails due to a retryable error. If not specified, defaults to 1 hour. Maximum allowed is 48 hours.

To enable auto batching, include `autoBatchPolicy` in the [write API](/reference/write/write-records) request, here's an example:

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "asynchronous",
    "autoBatchPolicy": {
        "maxDelayMinutes": 5,
        "retryDeadlineHours": 2
    },
    "record": {
        "firstname": "Alice",
        "lastname": "Wonderland",
        "email": "alice@example.com"
    }
}'
```

In this example:

* Ampersand waits for up to **5 minutes** for additional records to come in before sending the current batch.
* If 100 records accumulate before 5 minutes, the batch executes immediately.
* If the batch write fails due to a retryable error, Ampersand will retry for up to **2 hours**.

#### Monitor auto batch operations

You can monitor auto batch operations using the operation ID returned in the response. The operation ID represents the master operation for the batch. Use the [Get Operation endpoint](/reference/operation/get-an-operation) to check the status:

```bash theme={"dark"}
curl --location 'https://api.withampersand.com/v1/projects/<PROJECT_ID>/operations/<OPERATION_ID>' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY'
```

The operation status will show:

* `in_progress`: The batch is accumulating records or executing.
* `success`: The batch write completed successfully (may include partial success with some failed records).
* `failure`: The batch write failed.

## Write modes

Write actions support two modes: `synchronous` and `asynchronous`. The mode determines how the API handles your write request and when you receive a response. These modes apply to both single record writes and batch writes. **Delete operations are always synchronous** and do not use the `mode` field.

### Synchronous mode

In synchronous mode, the write operation is processed immediately and the API waits for the operation to complete before returning a response.

For **single record writes**, the response includes the created/updated record immediately. If the write operation fails, the API will return the error response.

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "synchronous",
    "record": {
        "firstname": "John",
        "lastname": "Doe",
        "email": "john@example.com"
    }
}'
```

### Asynchronous mode

In asynchronous mode, Ampersand validates the request and immediately returns an operation ID. The write is then processed in the background. This is recommended for large batch writes or when you don't need to wait for the result.

If the write fails due to API quota issues or other retryable errors, Ampersand will automatically keep retrying for up to 1 hour. If needed, the [retry policy can be configured](#retry-policy-for-async-writes) to retry for up to 48 hours.

For single-record writes, you can also use the [auto batch policy](#auto-batching) to automatically group multiple requests together and execute them as a batch.

To use async mode, set `mode: "asynchronous"` in your request:

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "asynchronous",
    "record": {
        "firstname": "Jane",
        "lastname": "Smith"
    }
}'
```

The response returns an operation ID immediately:

```json theme={"dark"}
{
    "operationId": "3efc0f0f-4bb9-498f-996c-9893d98ca4b5"
}
```

### Checking status of an async write operation

To check the status of an async write operation, use the [Get Operation endpoint](/reference/operation/get-an-operation) with the operation ID in the response body of the write API endpoint.

```bash theme={"dark"}
curl --location 'https://api.withampersand.com/v1/projects/<PROJECT_ID>/operations/<OPERATION_ID>' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY'
```

The response includes the operation status and result:

```json theme={"dark"}
{
    "id": "<OPERATION_ID>",
    "projectId": "<PROJECT_ID>",
    "integrationId": "<INTEGRATION_ID>",
    "installationId": "<INSTALLATION_ID>",
    "configId": "<CONFIG_ID>",
    "actionType": "write",
    "status": "failure",
    "result": "[contacts] Error writing to provider",
    "createTime": "2025-08-26T23:19:27.616204Z",
    "updateTime": "2025-08-26T23:19:28.424859Z",
    "resource": "contacts"
}
```

An operation can be in a `success`, `failure` or `in_progress` state.

### Retry policy for async writes

Ampersand will automatically retry failed operations with exponential backoff until the default deadline of 1 hour. If this is not enough, you can specify a longer deadline of up to 48 hours.

```bash theme={"dark"}
curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "asynchronous",
    "retryPolicy": {
        "deadlineHours": 24
    },
    "record": {
        "firstname": "Bob",
        "lastname": "Johnson"
    }
}'
```

Retry policies only apply to asynchronous mode.

## Advanced use cases

<Info>These advanced use cases are currently only supported when creating or updating installations via the API or [Headless UI](/headless).</Info>

### Enabling deletion for an object

By default, delete operations are disabled. To enable deletion, set `deletionSettings.enabled` to `true` for the object when creating or updating an installation.

#### Using headless UI

You can enable or disable deletion on a customer-by-customer basis using `setEnableDeletion` and `setDisableDeletion` from `config.writeObject()`. Learn more about [pre-requisites for headless UI here](/headless#prerequisites).

```typescript theme={"dark"}
function WriteObjectConfig() {
  const config = useLocalConfig();
  const contactWriteConfig = config.writeObject("Contact");

  // Enable deletion for the Contact object
  contactWriteConfig.setEnableDeletion();

  // Or disable deletion
  contactWriteConfig.setDisableDeletion();
}
```

#### Using API

You can use these APIs to set `deletionSettings.enabled`:

<AccordionGroup>
  <Accordion title="Create Installation">
    [Create Installation API](/reference/installation/create-a-new-installation) — Include `deletionSettings` in the write object when creating the installation:

    ```Javascript theme={"dark"}
    {
      "groupRef": "customer-group-ref",
      "connectionId": "connection-id",
      "config": {
        "revisionId": "revision-id",
        "content": {
          "provider": "salesforce",
          "write": {
            "objects": {
              "contact": {
                "objectName": "contact",
                "deletionSettings": {
                  "enabled": true
                }
              }
            }
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Update Installation">
    [Update Installation API](/reference/installation/update-an-installation) — PATCH the installation with the write object config and an update mask that includes the object path:

    ```Javascript theme={"dark"}
    {
      "updateMask": ["config.content.write.objects.contact"],
      "installation": {
        "config": {
          "content": {
            "provider": "salesforce",
            "write": {
              "objects": {
                "contact": {
                  "objectName": "contact",
                  "deletionSettings": {
                    "enabled": true
                  }
                }
              }
            }
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Update Installation Object (JSON Patch)">
    [Update Installation Object API](/reference/installation/update-an-installation-object) — PATCH the object's config content with a JSON Patch operation. Use this to change only this object without sending the full installation config:

    ```Javascript theme={"dark"}
    {
      "groupRef": "customer-group-ref",
      "action": "write",
      "changes": [
        {
          "op": "add",
          "path": "/deletionSettings",
          "value": { "enabled": true }
        }
      ]
    }
    ```

    Use `"op": "replace"` if the object already has `deletionSettings` and you are changing it.
  </Accordion>
</AccordionGroup>

### Prevent overwriting of customer data

You can control whether a field is included in write requests. For example, you can avoid overwriting data the customer has changed, or leave a field blank on create and write to it only on update.

**`writeOnCreate`** — whether to write the field when creating a record:

* **always** (default): Always include the field on create
* **never**: Never include the field on create

**`writeOnUpdate`** — whether to write the field when updating a record:

* **always** (default): Always include the field on update
* **never**: Never include the field on update (avoids overwriting customer changes)
* **ifEmpty**: Only include the field if it's currently empty. Supported for Salesforce and HubSpot only.

**Example configurations:**

* Only set a field on create, never overwrite on update → `writeOnCreate: "always"`, `writeOnUpdate: "never"`
* Leave field blank on create, only fill on update → `writeOnCreate: "never"`, `writeOnUpdate: "always"`
* Fill on update only when the field is empty → `writeOnUpdate: "ifEmpty"`
* Never write to the field for this customer → `writeOnCreate: "never"`, `writeOnUpdate: "never"`

#### Using headless UI

You can set overwrite behavior on a customer-by-customer basis using the function `setFieldSettings`. Learn more about [pre-requisites for headless UI here](/headless#prerequisites).

```typescript theme={"dark"}
function WriteObjectConfig() {
  const config = useLocalConfig();
  const contactWriteConfig = config.writeObject("Contact");

  // Only write to source field when creating a record, not when updating
  contactWriteConfig.setFieldSettings({
    fieldName: "source",
    settings: {
      writeOnCreate: "always",  // Write to source field when creating a record
      writeOnUpdate: "never"    // Do not write to source field when updating a record
    }
  });
}
```

#### Using API

As an alternative to headless UI, you can set overwrite behavior on a customer-by-customer basis when you make a call to the [Create Installation API](/reference/installation/create-a-new-installation). Here is a sample request body:

```Javascript theme={"dark"}
{
  "groupRef": "customer-group-ref",
  "connectionId": "connection-id",
  "config": {
    "revisionId": "revision-id",
    "content": {
      "provider": "hubspot",
      "write": {
        "objects": {
          "lead": {
            "objectName": "lead",
            "selectedFieldSettings": {
              "source": {
                  // Do not write to source field when updating a record.
                  "writeOnUpdate": "never",
                  // Write to source field when creating a record,
                  // This is the default behavior.
                  "writeOnCreate": "always"
              },
            },
          }
        }
      },
    }
  }
}
```

### Default values

Default values are applied to a field whenever that value is missing from the write request. We currently support string, boolean and number values.

#### Using headless UI

You can set default values on a customer-by-customer basis using the `setFieldSettings` function. Learn more about [pre-requisites for headless UI here](/headless#prerequisites).

```typescript theme={"dark"}
function WriteObjectConfig() {
  const config = useLocalConfig();
  const contactWriteConfig = config.writeObject("Contact");

  // Set default values for fields
  contactWriteConfig.setFieldSettings({
    fieldName: "source",
    settings: {
      default: {
        stringValue: "myApp"  // Set source field to "myApp" by default
      }
    }
  });

  contactWriteConfig.setFieldSettings({
    fieldName: "amount",
    settings: {
      default: {
        integerValue: 0  // Set amount field to 0 by default
      }
    }
  });

  contactWriteConfig.setFieldSettings({
    fieldName: "automated",
    settings: {
      default: {
        booleanValue: true  // Set automated field to true by default
      }
    }
  });
}
```

#### Using API

As an alternative to headless UI, you can set this behavior on a customer-by-customer basis when you make a call to the [Create Installation API](/reference/installation/create-a-new-installation). Here is a sample request body:

```Javascript theme={"dark"}
{
  "groupRef": "customer-group-ref",
  "connectionId": "connection-id",
  "config": {
    "revisionId": "revision-id",
    "content": {
      "provider": "hubspot",
      "write": {
        "objects": {
          "lead": {
            "objectName": "lead",
            "selectedFieldSettings": {
              "source": {
                "default": {
                  "stringValue": "myApp" // Set the source field to myApp
                },
              },
              "amount": {
                "default": {
                  "integerValue": 0 // Set the amount field to 0
                },
              },
              "automated": {
                "default": {
                  "booleanValue": true // Set the automated field to true
                },
              },
            },
          }
        }
      },
    }
  }
}
```

### Remove unmapped fields

If your write action is [sharing mapping with read actions](#share-mappings-with-read-actions), we can drop unmapped fields from the write request before sending the request to the provider API. Please contact [support@withampersand.com](mailto:support@withampersand.com) if you want to use this preview feature.

### Combine use cases

Here is a full example for a request body to the [Create Installation API](/reference/installation/create-a-new-installation) that combines multiple use cases:

* sharing mapping with read actions
* applying default values
* configuring when the field should be written to

#### Using headless UI

You can see an [example here of combining multiple use cases](/headless#configure-features-together).

#### Using API

```Javascript theme={"dark"}
{
  "groupRef": "customer-group-ref",
  "connectionId": "connection-id",
  "config": {
    "revisionId": "revision-id",
    "content": {
      "provider": "hubspot",
      "write": {
        "objects": {
          "lead": {
            "objectName": "lead",
            "inheritMapping": true, // Inherit mapping from read actions
            "selectedFieldSettings": {
              "customSource": { // customSource is a mapped field
                  "default": {
                    "stringValue": "myApp" // Use "mapApp" as default value
                  },
                  // Do not write to the field when updating a record.
                  "writeOnUpdate": "never",
                  // Write to the field on creating a record,
                  // This is the default behavior.
                  "writeOnCreate": "always"
              },
            },
          }
        }
      },
      "read": {
        "objects": {
          "lead": {
            "objectName": "lead",
            "destination": "myWebhook",
            "selectedFieldMappings": {
              "customSource": "myCustomSource"
            }
          }
      }
    }
  }
}
```

For this installation, `customSource` has been mapped to the `myCustomSource` field in this customer's Hubspot instance, the default value for this field is "myApp" and the field will only be written to when it is a create record request, and not an update request.