# Access via JWT
Source: https://docs.withampersand.com/api/jwt-auth
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.
Do not do JWT signing in the frontend. It invalidates the security model.
## 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={null}
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).
### 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={null}
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
This functionality is only available in `@amp-labs/react` version `2.8.7` and above.
In [AmpersandProvider](/embeddable-ui-components#credentials), 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`
```javascript theme={null}
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 (
// You can use any of the Ampersand components here.
)
}
```
## 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.withampersand.com/api/key-auth
## 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
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.
# Overview
Source: https://docs.withampersand.com/api/overview
Welcome to the Ampersand API reference docs! If you are new to Ampersand, this is not the best place to get started. Depending on your use case, you may not actually need to use the API. Please check out our [Quickstart guide](/quickstart) instead.
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.
> [](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==)
# Overview
Source: https://docs.withampersand.com/cli/overview
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={null}
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={null}
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={null}
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={null}
amp login
amp deploy --project
```
### View all commands
To list all available commands and global flags:
```bash theme={null}
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 --project
```
Alternatively, you can set the API key as an environment variable:
```
export AMP_API_KEY=
amp list:integrations --project
```
### Debug mode
For more detailed output, run commands with the `debug` flag.
```
amp login --debug
```
# Reference
Source: https://docs.withampersand.com/cli/reference
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-ci-cd-environments) for details.
### login
Authenticates you against the CLI via an interactive browser flow.
**Syntax:**
```bash theme={null}
amp login
```
**Example:**
```bash theme={null}
amp login
```
### logout
Logs out from your Ampersand account.
**Syntax:**
```bash theme={null}
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={null}
amp help [command]
```
**Example:**
```bash theme={null}
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={null}
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={null}
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={null}
amp deploy --project [--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={null}
amp deploy ./integrations --project my-project
```
### delete:integration
Deletes a specific integration from your project.
**Syntax:**
```bash theme={null}
amp delete:integration --project [--key ] [--debug]
```
**Notes:**
* This action is irreversible. Use with caution.
* Removes the integration & any associated installations from your project.
**Example:**
```bash theme={null}
amp delete:integration f47ac10b-58cc-4372-a567-0e02b2c3d479 --project my-project
```
### delete:installation
Deletes a specific installation of an integration.
**Syntax:**
```bash theme={null}
amp delete:installation --project [--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={null}
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.withampersand.com/destinations) Documentation.
**Syntax:**
```bash theme={null}
amp list:destinations --project [--key ] [--debug]
```
**Notes:**
* The output includes destination IDs and names.
**Example:**
```bash theme={null}
amp list:destinations --project my-project
```
### list:installations
Displays all current installations of a given integration in your project.
**Syntax:**
```bash theme={null}
amp list:installations --project [--key ] [--debug]
```
**Example:**
```bash theme={null}
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={null}
amp list:integrations --project [--key ] [--debug]
```
**Example:**
```bash theme={null}
amp list:integrations --project my-project
```
### list:projects
Displays all projects associated with your Ampersand account.
**Syntax:**
```bash theme={null}
amp list:projects [--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={null}
amp list:projects
```
# Concepts
Source: https://docs.withampersand.com/concepts
## Integration
An **integration** defines how your application will interact with a third party SaaS tool. You will have a single integration for all of your customers that are connecting your application with a particular SaaS product. For example, you might have an integration called `mySalesforceIntegration`. Salesforce is the **provider** that we are integrating with.
You create an integration by defining it in a [manifest file](/manifest-reference) and then deploying it using the `amp` CLI. (See [CLI Overview](/cli/overview)).
An **installation** is specific to a single customer that sets up one of your integrations to connect with their SaaS instance. For example, `mySalesforceIntegration` might have 30 installations - one for each of your customers that have connected their Salesforce instance with your application.
## Installation
An installation is an instance of an integration, for a particular customer. It is created:
* when a customer connects their SaaS instance in an [embeddable UI component](/embeddable-ui-components)
* or when you make an API call to the [CreateInstallation](/reference/installation/create-a-new-installation) endpoint.
An installation captures the following information:
* the credentials for connecting to the customer's SaaS instance. (Ampersand supports OAuth, Basic Auth, and API Key based authentication.) We call this the **connection**.
* a customer's preference for which objects and fields they want your application to read or write, and fields they've mapped. We call this the **config**.
***
For other terminology, refer to [Terminology](/terminology).
# BigQuery
Source: https://docs.withampersand.com/customer-guides/bigquery
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**.
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.
### 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={null}
base64 -i service-account-key.json
```
**Linux, Git Bash, or WSL**
```bash theme={null}
base64 -w 0 service-account-key.json
```
**Windows (PowerShell)**
```powershell theme={null}
[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.
# Google (workspace delegation)
Source: https://docs.withampersand.com/customer-guides/google-workspace-delegation
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={null}
base64 -i service-account-key.json
```
**Linux, Git Bash, or WSL**
```bash theme={null}
base64 -w 0 service-account-key.json
```
**Windows (PowerShell)**
```powershell theme={null}
[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**.
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.
### 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). |
## Troubleshooting
### unauthorized\_client error
Sample error message: `unauthorized_client: Client is unauthorized to retrieve access tokens using this method`
This means that either:
* The service account's numeric Client ID was not added to **Manage Domain Wide Delegation** in the Admin console (revisit step 4), or
* One or more scopes provided to the integration were not a part of the scopes authorized in step 4.
### invalid\_grant error
Sample error message: `invalid_grant: Invalid email or User ID`
This means that a **user email** you provided is not a valid active user in the Workspace domain. Workspace delegation does not work for suspended or deleted users. Confirm that the user's address exists in **Admin console** > **Directory** > **Users**.
# Housecall Pro
Source: https://docs.withampersand.com/customer-guides/housecallPro
## 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.
2. Click **Go to App Store**.
3. Under **My Apps**, find and open the **API Key Management** app card.
4. Click **Generate API Key**.
5. Enter a descriptive name for the key.
6. Copy the API key and store it securely.
## 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.
2. Click **Go to App Store**.
3. Under **All apps**, find and open **Webhooks**.
4. Set Webhooks to **Active**, paste the link the developer gave you into the **Webhook URL** field, then click **Save**.
5. Enable the webhook events that you want to subscribe to, then click **Save**.
**`pro.created`** in Housecall Pro means a new **employee**; the connected
product may display it as **`employee.created`**.
## 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.withampersand.com/customer-guides/hubspot
## 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.withampersand.com/customer-guides/loxo
## 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]`.
### 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**.
# Marketo
Source: https://docs.withampersand.com/customer-guides/marketo
## 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.\\
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.\\
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\\
6. Click **Create**.
7. After creation, you can view the **Client ID** and **Client Secret** by clicking **View Details**.\\
8. You will also need the `workspaceId` (Munchkin Account ID). This can be found under **Admin** → **Integration** → **Munchkin**.\\
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.withampersand.com/customer-guides/netsuite
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'.
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.
### 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**.
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.
### 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={null}
openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
```
```bash theme={null}
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.
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.
#### 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={null}
base64 -i private-key.pem
```
**Linux, Git Bash, or WSL**
```bash theme={null}
base64 -w 0 private-key.pem
```
**Windows (PowerShell)**
```powershell theme={null}
[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**.
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.
### 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**.
5. Copy the **Certificate ID** from the list — you will need this value when installing the integration.
Check that the `Valid Until` date for the certificate is two years in the future. NetSuite allows a maximum validity of 730 days.
## 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 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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`. |
**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.
# Overview
Source: https://docs.withampersand.com/customer-guides/overview
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.withampersand.com/customer-guides/salesforce
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.
## Before installing a Salesforce integration
### Verify your Salesforce edition supports API access
Salesforce editions offer different levels of API access, which can affect how Salesforce integrations work in Ampersand.
Before setting up your Salesforce integration, confirm whether your Salesforce edition includes API access. Some editions include full API access by default, while others may offer limited access or require additional purchases.
To check if your Salesforce edition supports the necessary API access for this integration, please refer to [Salesforce's official documentation](https://help.salesforce.com/s/articleView?language=en_US\&id=000385436\&type=1) on API access by edition.
If your Salesforce edition does not include the required API access, contact your Salesforce account representative to upgrade your edition.
## Setting up the integration
### Install the package
If the integration uses an External Client App, the developer will provide you with a **package install URL**. This URL installs the app into your Salesforce org.
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**.
You will see a progress screen while the installation completes.
Once complete, you should see a confirmation screen:
To verify the package was installed, go to **Setup**, search for **Installed Packages**, and confirm the package appears in the list.
You must complete this step **before** connecting your Salesforce account through the integration's UI, otherwise the OAuth connection will fail.
### Configure token policy settings
Salesforce access tokens expire after a certain period. To ensure your integration continues working without interruption, you need to set your refresh token policy to **Refresh token is valid until revoked**.
1. Log in to *Salesforce*.
2. Go to **Setup**.
3. In the *Quick Find* box, search for **Connected Apps**.
4. Click on **Manage Connected Apps**.
5. Find and click on the name of the application you are integrating with.
6. Scroll down to the **OAuth Policies** section.
7. Look for **Refresh Token Policy**.
8. Under *IP Relaxation*, select **Relax IP restrictions**.
9. Make sure the refresh token policy is set to **Refresh token is valid until revoked**.
10. Click **Save**.
### Manage app policies
Salesforce allows administrators to restrict which applications can access Salesforce data through APIs. You need to ensure that API access isn't limited to only specific connected apps.
1. Log in to *Salesforce*.
2. Go to **Setup**.
3. In the *Quick Find* box, search for **Connected Apps OAuth Usage**.
4. Under the list of connected apps, find the one for this integration and click **Manage App Policies**.
5. In the *OAuth Policies* section, ensure the **Permitted Users** status is one of:
* *Admin approved users are pre-authorized* — only selected users can access.
* *All users may self-authorize* — all users can access the app.
If you need to modify these settings:
1. Click on **Install** next to your connected app.
2. In the **OAuth Usage and Policies** section, set the appropriate permissions level.
3. Click **Save**.
## Ensure sufficient permissions
The credentials provided to the integration can be:
* A [human user](#human-users), such as:
* a System Administrator. Please note that you still need to ensure that the System Admin has the correct object and field level permissions, they may not be granted by default.
* a sales team member with the **Salesforce** User License and the necessary permissions as specified below. This user can either have a standard profile (such as "Standard User") or a custom profile. Please note that the **Salesforce Platform** User License is insufficient.
* A [Salesforce integration user](#salesforce-integration-users). This type of user is specifically for integrations, and does not have access to the Salesforce UI.
### Human users
#### 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.
3. Ensure the checkboxes for the necessary [system permissions](#system-permissions-needed) are checked.
4. Click **Save** at the top or bottom of the page.
#### 2a. Field permissions for standard profile
If the user has a standard profile (such as "Standard User"), then follow these instructions:
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.
3. Choose the object you need (for example, **Account**), then select **Fields & Relationships** from the left navbar.
4. Find the field you want to adjust and click it.
5. Click **Set Field-Level Security**.
6. Ensure the checkbox for **Visible** is selected for the profile you're interested in. If the profile is not visible in this list, it means that it does not have access to the object. This is not possible to modify.
7. Repeat steps 4–6 for all fields that the integration needs to read, especially custom fields.
#### 2b. Object and field permissions for custom profile
If the user has a custom profile, then follow these instructions:
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.
3. Choose the object you need (for example, **Account**) and go to **Object Access** in the left navbar. Select the **Profiles** tab at the top. Click **Edit** and grant the necessary permissions for your custom profile.
* If the integration needs to read data, ensure that `Read`, `View All Records`, and `View All Fields` are checked.
* If the integration needs to write data, ensure that all boxes are checked.
### Salesforce Integration users
The Salesforce Integration user license type is a special type of license that can be used for integrations and does not have UI access.
#### 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`.
#### 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.
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`.
#### 3. Configure object permissions
1. Click on **Object Settings**
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".
3. Edit the permission so that all relevant boxes under **Object Permissions** and **Field Permissions** are checked. Then click on **Save**.
4. Repeat for all the other objects that the integration needs to access.
#### 4. Configure system permissions
1. Select **System Permissions**.
2. Ensure that the checkboxes for the necessary [system permissions](#system-permissions-needed) are selected, and then click **Save**.
#### 5. Assign permission set to integration user
1. Click on **Manage Assignments**.
2. Click on **Add Assignment**.
3. Select the integration user you created in step 1.
4. Ensure "Expires On" is set to "Never Expires", and then click on "Assign".
## After installing the integration
After the integration is installed, you need to configure OAuth policies to ensure the integration can maintain a stable connection.
1. Log in to *Salesforce*.
2. Go to **Setup**.
3. In the *Quick Find* box, search for **External Client App Manager**.
4. Click on the name of the installed External Client App.
5. Go to the **Policies** tab and click **Edit**.
6. Under **OAuth Policies**, ensure **Permitted Users** is set to **All users may self-authorize**.
7. Under **App Authorization**, make the following changes:
* Set **Refresh Token Policy** to **Refresh token is valid until revoked**.
* Set **IP Relaxation** to **Relax IP restrictions**.
8. Click **Save**.
Salesforce allows administrators to restrict which applications can access Salesforce data through APIs. You need to ensure that API access isn't limited to only specific connected apps.
To verify your API access control settings:
1. Log in to *Salesforce*.
2. Go to **Setup**.
3. In the *Quick Find* box, search for **Connected Apps OAuth Usage**.
4. Under the list of connected apps, find the one for this integration and click **Manage App Policies**.
5. In the *OAuth Policies* section, ensure the **Permitted Users** status is one of:
* *Admin approved users are pre-authorized* - only selected users can access.
* *All users may self-authorize* - all users can access the app.
If you need to modify these settings:
1. Click on **Install** next to your connected app.
2. In the **OAuth Usage and Policies** section, set the appropriate permissions level.
3. Click **Save**.
## Salesforce terminology
### License
A **license** is purchased from Salesforce and determines the maximum set of permissions that can be granted to a user with that license.
### Profile
A **profile** is a collection of settings that determines what objects, fields, and features a user can access in Salesforce. Each user has exactly one profile. Standard profiles (e.g. Standard User, System Administrator) are provided by Salesforce; you can also create custom profiles by cloning an existing one. A profile is always associated with one user license, but a user license can have multiple profiles associated with it. When you create a new user, you can pick both the license and profile of that person.
### Permission set
A **permission set** is a collection of permissions that you assign to users to grant access to specific objects, fields, and capabilities. Permission sets extend the default permissions of a profile. Users can have only one profile but multiple permission sets. A permission set is tied to a license, and only users with that license type can be granted the permission set.
## System permissions needed
The following system permissions are needed:
* `API Enabled`
* [Subscribe Action Permissions](#subscribe-action-permissions) if the integration includes real-time Subscribe Actions.
The following system permissions are needed:
* `API Enabled`
* [Subscribe Action Permissions](#subscribe-action-permissions) if the integration includes real-time Subscribe Actions.
* One of the following:
* `Use Any API Client` if you see it. (You will only see this option if your organization has enabled [API Access Control](https://help.salesforce.com/s/articleView?id=xcloud.security_api_access_control_about.htm\&type=5)).
* `Approve Uninstalled Connected Apps` if you do not see an option for `Use Any API Client`.
To ensure that you have the necessary system permission, please follow these instructions:
* [For a Profile](#1-configure-system-permissions)
* [For a Permission Set that is assigned to an Integration User](#4-configure-system-permissions)
## Subscribe Action permissions
If the integration contains Subscribe Actions, a number of special permissions are required. Here's an explanation of why each permission is necessary:
These permissions need to be explicitly enabled:
* `Modify Metadata Through Metadata API Functions`: Required to configure event channels and event channel memberships through Metadata API.
* `Customize Application`: Required to configure artifacts like Named Credentials, which allows Ampersand to securely connect to the event channels.
Salesforce auto-enables these when you enable the above permissions, because they dependent permissions:
* `View Setup and Configuration`: Enables the integration to access Salesforce setup configuration in order to create webhook subscription settings.
* `View Roles and Role Hierarchy`: Ensures the integration has the correct visibility context so Salesforce can successfully send events; without this, events may be generated but not delivered.
* `Manage Custom Permissions`: Allows the integration to create and manage dedicated event channels and channel memberships used specifically for the installation's subscription events.
To ensure that you have the necessary permission to use Subscribe Actions, please follow these instructions:
* [For a Profile](#1-configure-system-permissions)
* [For a Permission Set that is assigned to an Integration User](#4-configure-system-permissions)
# Salesforce (JWT authentication)
Source: https://docs.withampersand.com/customer-guides/salesforce-jwt
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={null}
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.
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.
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={null}
base64 -i private-key.pem
```
**Linux, Git Bash, or WSL**
```bash theme={null}
base64 -w 0 private-key.pem
```
**Windows (PowerShell)**
From the directory that contains `private-key.pem`:
```powershell theme={null}
[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**.
3. Search for **External Client App Manager**.
4. Click **New External Client App**.
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.)
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.
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**.
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.
### 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`.
#### 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.
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`.
#### 3. Configure object permissions
1. Click on **Object Settings**
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".
3. Edit the permission so that all relevant boxes under **Object Permissions** and **Field Permissions** are checked. Then click on **Save**.
4. Repeat for all the other objects that the integration needs to access.
#### 4. Configure system permissions
1. Select **System Permissions**.
2. Ensure that the checkboxes for the necessary [system permissions](/customer-guides/salesforce#system-permissions-needed) are selected, and then click **Save**.
#### 5. Assign permission set to integration user
1. Click on **Manage Assignments**.
2. Click on **Add Assignment**.
3. Select the integration user you created in step 1.
4. Ensure "Expires On" is set to "Never Expires", and then click on "Assign".
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.
### 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.
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**.
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`.
### 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). |
**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.
## 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 --jwt-key-file private-key.pem --username --instance-url https://.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.withampersand.com/customer-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.
# Update a connection
Source: https://docs.withampersand.com/customer-guides/update-connection
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.
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.
# Kinesis destinations
Source: https://docs.withampersand.com/destinations/kinesis
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={null}
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={null}
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={null}
{
"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)) |
Ampersand encrypts and stores your AWS credentials securely.
## Refer to the destination in your integration
After creating your Kinesis destination, reference it in your `amp.yaml` file:
```yaml theme={null}
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={null}
{
"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={null}
{
"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={null}
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.
If you hit these limits, contact `support@withampersand.com` to discuss scaling strategies.
# Overview
Source: https://docs.withampersand.com/destinations/overview
Ampersand currently supports webhook, Kinesis, and S3 destinations. 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={null}
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)
* [Amazon Kinesis destinations](/destinations/kinesis)
* [Amazon S3 destinations](/destinations/s3)
## Other Destinations
We have many other destination types on the roadmap, including:
* Postgres
* Ampersand-hosted Postgres
* Amazon SQS
* Google Cloud Storage
* Google PubSub
* RabbitMQ
* Azure Service Bus
# Amazon S3 destinations
Source: https://docs.withampersand.com/destinations/s3
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={null}
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={null}
{
"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`) |
Ampersand encrypts and stores your AWS credentials securely.
## Refer to the destination in your integration
After creating your S3 destination, reference it in your `amp.yaml` file:
```yaml theme={null}
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={null}
{
"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={null}
{
"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) |
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.
### 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])
```
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.
## 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={null}
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.
If you have questions about scaling, contact `support@withampersand.com`.
# Webhook destinations
Source: https://docs.withampersand.com/destinations/webhooks
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={null}
{
"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={null}
{
"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={null}
{
"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 get parse result from a webhook:
```go go theme={null}
// 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={null}
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 the change this limit, please contact `support@withampersand.com`. Alternatively, you can set the delivery mode to [on request](/read-actions#on-request) 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"**.
#### 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.withampersand.com/dev-and-prod-environments
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={null}
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. Do not reuse the same Provider App across projects, 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={null}
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.withampersand.com/embeddable-ui-components
## 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](https://github.com/amp-labs/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={null}
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 (
{/* All your Ampersand components and hooks go here */}
);
}
```
### 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={null}
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 (
{/* All your Ampersand components and hooks go here */}
);
```
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.
* **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={null}
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
],
}}
/>
```
#### 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.
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.
To activate wizard mode, pass `variant="wizard"` to the `InstallIntegration` component:
```JSX theme={null}
```
When no installation exists, the wizard renders. If an installation already exists, the standard configuration UI is shown instead.
| 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-2) | 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={null}
console.log(`Successfully created connection ${connection.id}`)
}
onDisconnectSuccess = {connection =>
console.log(`Successfully deleted connection ${connection.id}`)
}
/>
```
Connect
Success
*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={null}
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={null}
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={null}
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
Customized styling is only supported in v2.x.x
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={null}
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={null}
: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
Dark mode is only supported in v2.1.0+
Ampersand's UI components support dark mode. Ensure that you have the following lines in your application's CSS:
```CSS theme={null}
: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={null}
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 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.withampersand.com/headless
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.
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).
## 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={null}
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={null}
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.withampersand.com/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 (
{/* Your custom component */}
);
}
```
## 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={null}
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 (
{connection ? (
{/* If there isn't a Connection, show prebuilt ConnectProvider component. */}
{
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. */}
)}
);
}
```
## 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={null}
import { useInstallation } from '@amp-labs/react';
function InstallationComponent() {
const { installation } = useInstallation();
return (
{installation ? (
You've successfully installed the integration!
) : (
)}
);
}
```
### 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={null}
import { useInstallation } from '@amp-labs/react';
function ConfigDisplayComponent() {
const { installation } = useInstallation();
if (!installation) {
return
No installation found
;
}
// Access the configuration from the installation
const config = installation.config;
// Use the config to build your custom UI
}
```
For more advanced config management: including getting/setting read/write objects in the config and managing a local draft copy, use the [`useLocalConfig()`](#config-management) hook.
### 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.
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.
It returns the following:
* `createInstallation`: a tanstack-query mutation function to create a new Installation. Its signature is:
```typescript theme={null}
(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={null}
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 (
);
}
```
## 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.
`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).
> `useManifest` exposes typed helpers for read and write objects (`getReadObject`, `getReadObjects`, `getWriteObject`).
```TypeScript theme={null}
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;
},
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={null}
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={null}
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.
**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.
**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).
It returns these fields:
```typescript theme={null}
// 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.withampersand.com/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={null}
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 ()
}
```
### 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={null}
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.
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.
```typescript theme={null}
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 ()
}
```
### 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={null}
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={null}
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={null}
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={null}
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)
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](#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)
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={null}
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 (
);
}
// 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
;
// The installation already exists
if (!!installation) { return () }
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 (
);
}
```
# Manage customer schemas
Source: https://docs.withampersand.com/manage-customer-schemas
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={null}
const { getCustomerFieldsForObject } = useManifest();
// Get all fields for a specific object
const fields = getCustomerFieldsForObject("account");
```
See the [headless UI library page](/headless#get-fields-from-customer’s-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
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={null}
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={null}
{
"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.withampersand.com/manifest-reference
## 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.
**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.
## 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={null}
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-configuration). Each element defines a complete integration with a specific provider. |
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.
## 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={null}
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. |
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".
## 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={null}
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. |
Subscribe considerations
* Check the specific [provider guide](/provider-guides/overview) to see which providers support subscribe actions. If subscribe actions isn'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.
## 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={null}
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. |
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.
## 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={null}
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. |
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.
## 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={null}
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 | If set to `always`, the integration automatically installs upon user connection and skips the user field selection step. |
| `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. |
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).
### 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
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.
### Backfill
The `backfill` section configures how historical data is loaded.
> Learn more about [backfill behavior](/read-actions#backfill-behavior):
```yaml theme={null}
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`. |
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.
* See [Read Actions backfill behavior](/read-actions#backfill-behavior) for detailed implementation guidance.
### Field
In [Read Actions](#read-actions), 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={null}
- fieldName: firstname
```
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
**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#field-mapping-strategies).
```yaml theme={null}
# 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
```
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.
| 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={null}
- fieldName: email
- fieldName: firstname
- fieldName: lastname
```
2. **Standardized Field Names**: Use `fieldName` with `mapToName` to standardize field names:
```yaml theme={null}
- 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={null}
- 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={null}
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={null}
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={null}
updateEvent:
enabled: always
watchFieldsAuto: all # Options: "all" or "selected"
```
Or alternatively:
```yaml theme={null}
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. |
Only one of `watchFieldsAuto` or `requiredWatchFields` should be specified.
**Delete event**
The `deleteEvent` definition specifies how to handle delete events:
```yaml theme={null}
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={null}
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={null}
otherEvents:
- object.merged
- object.restored
```
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)
# Notification payloads
Source: https://docs.withampersand.com/notifications/notification-payloads
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:
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.
```json theme={null}
{
"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"
}
}
```
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"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.
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"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"
}
```
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"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.
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"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.
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"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.
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"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.
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"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"
}
```
`connection.created`, `connection.refreshed`, `connection.updated`, and `connection.deleted` share the same payload shape. `notificationType` reflects the specific event.
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
"connectionId": "c4e7f2a1-8b3d-4f6e-9a2c-5d1e3f4b6a7c",
"provider": "salesforce",
"groupRef": "customer-group-ref",
"consumerRef": "user-123",
"consumerName": "John Doe"
}
```
The `error` field is deprecated and kept for backward compatibility. Use `errors` instead. Both fields contain the same value.
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"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"]
}
```
**Webhook destination payload:**
```json theme={null}
{
"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={null}
{
"projectId": "8f4a2b1c-3d5e-4f6a-9b0c-1d2e3f4a5b6c",
"destinationId": "2e8f4c1a-9b3d-4e7f-8a2c-0d1e2f3a4b5c",
"destinationName": "production-alerts",
"url": "https://your-webhook.com"
}
```
# Overview
Source: https://docs.withampersand.com/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.
## Available events
Ampersand supports the following notification event types:
**Installation lifecycle**
* **`installation.created`**: Fires when a customer installs your integration to their SaaS instance
* **`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.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.error`**: Fires when Ampersand fails to set up a subscribe action for an installation
**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.
## 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, Kinesis, Amazon S3, or log destination
* **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.
```bash theme={null}
POST https://api.withampersand.com/v1/projects/{projectIdOrName}/destinations
{
"name": "production-alerts",
"type": "webhook",
"metadata": {
"url": "https://your-webhook.com"
}
}
```
```bash theme={null}
POST https://api.withampersand.com/v1/projects/{projectIdOrName}/topics
{
"name": "installation-events"
}
```
**Notification-Event-Topic Routes** connect specific event types to topics. This determines which events are sent to each topic.
```bash theme={null}
POST https://api.withampersand.com/v1/projects/{projectIdOrName}/notification-event-topic-routes
{
"topicId": "your-topic-id",
"eventType": "installation.created"
}
```
**Topic-Destination Routes** connect topics to destinations. This determines which destinations receive notifications for each topic.
```bash theme={null}
POST https://api.withampersand.com/v1/projects/{projectIdOrName}/topic-destination-routes
{
"topicId": "your-topic-id",
"destinationId": "your-destination-id"
}
```
# Object and field mapping
Source: https://docs.withampersand.com/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#sharing-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={null}
- 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={null}
- 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={null}
- 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={null}
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 ();
}
```
Dynamic mappings are considered optional for a user to set, i.e, your users can install the integration without explicitly mapping a field.
Note you can also use this configuration in tandem with static field mappings (the ones defined in `amp.yaml`):
```YAML theme={null}
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={null}
{
...
"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.
Lets 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={null}
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 ();
```
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.
We only allow one-to-one mapping of values
## 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.
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.
### 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={null}
{
"userInfo": {
"email": "john@example.com",
"name": "John Doe"
},
"status": "active"
}
```
**With this pre-defined field mapping in `amp.yaml`:**
```YAML theme={null}
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={null}
{
"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={null}
{
"contactEmail": "john@example.com",
"contactName": "John Doe",
"moreInfo": {
"currentStatus": "deleted"
}
}
```
**Provider receives:**
```JSON theme={null}
{
"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.
# Overview
Source: https://docs.withampersand.com/overview
[Ampersand](https://www.withampersand.com/) is a declarative platform for SaaS builders who are creating product integrations. It allows you to:
* Read data from your customer's SaaS
* Write data to your customer's SaaS
* Subscribe to events (creates, deletes, and field changes) in your customer's SaaS.
Here's an overview of the Ampersand platform:
The key components include:
* **Manifest file:** an `amp.yaml` file, where you define all your integrations: API to connect to, objects and fields you want to read or write, and configuration options you'd like to expose to your customers.
* **Ampersand server:** a managed service that keeps track of each of your customer’s configurations, and makes the appropriate API calls to your customer's SaaS, while optimizing for cost, handling retries and error message parsing.
* **Embeddable UI components** with Ampersand, you can embed set-up, configuration, and management UIs that allow your end users to customize and manage their integrations.
* **Dashboard**: our dashboard allows you to monitor and troubleshoot your customers' integrations.
# AccuLynx
Source: https://docs.withampersand.com/provider-guides/accuLynx
## 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:
Object
Read
Write
Subscribe
**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.
**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.
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.withampersand.com/provider-guides/acuityScheduling
## 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**.
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 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.
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*.
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.withampersand.com/provider-guides/aha
## 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**.
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.
## 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.
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.
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.withampersand.com/provider-guides/aircall
## 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.
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*.
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.withampersand.com/provider-guides/airtable
## 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 a 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**.
## 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*.
7. Click **Save Changes**.
# Amplemarket
Source: https://docs.withampersand.com/provider-guides/amplemarket
## 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={null}
# 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.withampersand.com/provider-guides/amplitude
## 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 a 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.withampersand.com/provider-guides/anthropic
## 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={null}
# 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.withampersand.com/provider-guides/apollo
## 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.
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.
## 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.withampersand.com/provider-guides/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)
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.
## 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 you 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 .
### Adding Ampersand Redirect URL in Your App
1. Nagivate 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**.
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](https://docs.withampersand.com/docs/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.
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.
6. Click **Save changes**.
# Ashby
Source: https://docs.withampersand.com/provider-guides/ashby
## 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.withampersand.com/provider-guides/atlassian
## 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 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**.
### 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.
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**.
You'll find the **Client ID** and **Client Secret** keys for your app in the **Settings** section.
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 a Atlassian integration.
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.withampersand.com/provider-guides/attio
## 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.attio.com`.
### Supported Objects
The Attio connector supports reading to the following objects:
* [People](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/people/list-person-records)
* [Companies](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/companies/list-company-records)
* [Users](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/users/list-user-records)
* [Deals](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/deals/assert-a-deal-record)
* [Workspaces](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/workspaces/assert-a-workspace-record)
* [Lists](https://docs.attio.com/rest-api/endpoint-reference/lists/list-all-lists)
* [WorkspaceMembers](https://docs.attio.com/rest-api/endpoint-reference/workspace-members/list-workspace-members)
* [Notes](https://docs.attio.com/rest-api/endpoint-reference/notes/list-notes)
* [Tasks](https://docs.attio.com/rest-api/endpoint-reference/tasks/list-tasks)
* [Custom objects](https://docs.attio.com/rest-api/endpoint-reference/records/list-records)
The Attio connector supports writing to the following objects:
* [People](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/people/list-person-records)
* [Companies](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/companies/list-company-records)
* [Users](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/users/list-user-records)
* [Deals](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/deals/assert-a-deal-record)
* [Workspaces](https://docs.attio.com/rest-api/endpoint-reference/standard-objects/workspaces/assert-a-workspace-record)
* [Lists](https://docs.attio.com/rest-api/endpoint-reference/lists/list-all-lists)
* [WorkspaceMembers](https://docs.attio.com/rest-api/endpoint-reference/workspace-members/list-workspace-members)
* [Notes](https://docs.attio.com/rest-api/endpoint-reference/notes/list-notes)
* [Tasks](https://docs.attio.com/rest-api/endpoint-reference/tasks/list-tasks)
* [Custom objects](https://docs.attio.com/rest-api/endpoint-reference/records/list-records)
### 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.
## 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.
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.
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, 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.
# Avoma
Source: https://docs.withampersand.com/provider-guides/avoma
## 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 to 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 a 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](https://help.avoma.com/api-integration-for-avoma)] for instructions on how to create an API key.
# AWeber
Source: https://docs.withampersand.com/provider-guides/aweber
## 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={null}
# 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**.
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.
## 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.
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*.
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.withampersand.com/provider-guides/aws
## 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.
# Bentley
Source: https://docs.withampersand.com/provider-guides/bentley
## 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.
### 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.
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.
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.withampersand.com/provider-guides/bigquery
## 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={null}
# 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.withampersand.com/provider-guides/bird
## 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={null}
# 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.withampersand.com/provider-guides/bitbucket
## 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 an Apollo 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**.
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.
## 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.\\
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.
6. Click **Save Changes**.
# Blackbaud
Source: https://docs.withampersand.com/provider-guides/blackbaud
## 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**.
### Example integration
For an example manifest file of an 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.
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.
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.withampersand.com/provider-guides/blueshift
## 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.withampersand.com/provider-guides/blueshiftEU
## 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={null}
# 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.withampersand.com/provider-guides/box
## 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**.
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](https://docs.withampersand.com/docs/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.
## 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.
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.
6. Click **Save Changes**.
# Braintree
Source: https://docs.withampersand.com/provider-guides/braintree
## 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={null}
# 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).
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.withampersand.com/provider-guides/braze
## 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.
## 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.withampersand.com/provider-guides/breakcold
## 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 from 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 an 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.
# Brevo
Source: https://docs.withampersand.com/provider-guides/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.withampersand.com/provider-guides/bynder
## 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 setup, 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.**
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 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.
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*.
7. Click **Save Changes**.
# Calendly
Source: https://docs.withampersand.com/provider-guides/calendly
## 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.
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.
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.
6. Click **Save changes**.
# Campaign Monitor
Source: https://docs.withampersand.com/provider-guides/campaignMonitor
## 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 an 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.
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*.
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.withampersand.com/provider-guides/capsule
## 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.
## 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.
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*.
7. Click **Save Changes**.
# ChargeOver
Source: https://docs.withampersand.com/provider-guides/chargeOver
## 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={null}
# 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.
# Chargebee
Source: https://docs.withampersand.com/provider-guides/chargebee
## 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.withampersand.com/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={null}
# 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.withampersand.com/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*
## 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.withampersand.com/provider-guides/chorus
The Chorus connector is in beta. If you have any feedback or experience any issues, please contact [support@withampersand.com](mailto:support@withampersand.com)
## 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 from 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.withampersand.com/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={null}
# 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.withampersand.com/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**.
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.withampersand.com/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 CickUp 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**.
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.
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.
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.withampersand.com/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 Schedulinng 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-crm-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.
## 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.
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**.
7. Click **Save Changes**.
# CloudTalk
Source: https://docs.withampersand.com/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.
## 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.withampersand.com/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={null}
# 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 HeyReach:
* 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 HeyReach
1. Log in to your [Coda Account](https://coda.io/signin).
2. Navigate to [**Account settings**](https://coda.io/account) > **API settings**
3. Cick **Generate an API Token**.
4. Provide a *name* and click **Generate API token**
# ConnectWise
Source: https://docs.withampersand.com/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:
Object
Read
Write
Subscribe
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={null}
{
"groupRef": "{{connectWiseGroupID}}",
"type": "update",
"record": {
"id": "58016",
"patch": [
{"op": "replace", "path": "/firstName", "value": "John"}
]
}
}
```
### Example integration
To define an integration for ConnectWise, create a manifest file that looks like this:
```YAML theme={null}
# amp.yaml
specVersion: 1.0.0
integrations:
- name: connectWise-integration
displayName: My ConnectWise Integration
provider: connectWise
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 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.withampersand.com/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**.
### 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.
### 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.
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.
6. Click **Save Changes** to finalize the integration.
# Copper
Source: https://docs.withampersand.com/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 *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.
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.withampersand.com/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={null}
# 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.
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.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.withampersand.com/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.
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.withampersand.com/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.
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**.
The **Oauth2** section displays **Client ID** and **Client Secret** keys for your app. You'll use these credentials to connect your app to [Ampersand](https://docs.withampersand.com/docs/drift#add-your-drift-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.
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.withampersand.com/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={null}
# 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.)
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/).
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.withampersand.com/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 an 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.withampersand.com/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`.
9. Click **Save**.
## Connecting Your Docusign Developer App to Ampersand
Follow the steps below to connect you 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 an Docusign integration.
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.
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 you 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 an Docusign integration.
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.
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.withampersand.com/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={null}
#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.withampersand.com/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.
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.withampersand.com/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 an Apollo 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..
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.
9. Under the **Activate Your App** section, click the **Install App to Drift** button.
You 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](https://docs.withampersand.com/docs/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.
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.
6. Click **Save Changes**.
# Dropbox
Source: https://docs.withampersand.com/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**.
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.
### Adding Ampersand Redirect URI
1. In the **OAuth 2 Redirect URIs** section, enter the Ampersand **Redirect URI**: `https://api.withampersand.com/callbacks/v1/oauth`.
## 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.
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.
6. Click **Save changes**.
# Dropbox Sign
Source: https://docs.withampersand.com/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. In the 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**.
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.
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.
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.withampersand.com/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.
### 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.
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.
6. In the **Scopes** field, enter the scopes your integration requires.
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.
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`.
7. Click **Save Changes**.
# Dynamics 365 CRM
Source: https://docs.withampersand.com/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 an 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.
### 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.
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.
6. In the **Scopes** field, enter the scopes your integration requires.
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.
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`.
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.withampersand.com/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={null}
#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**.
# Fathom
Source: https://docs.withampersand.com/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.withampersand.com/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**.
You'll find the **Client ID** and **Client Secret** keys for your app in the following section. Note thse credentials as they are necessary for connecting your app to Ampersand.
## 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.
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.
7. Click **Save changes**.
# Fireflies
Source: https://docs.withampersand.com/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`.
You will need to use the `graphql` endpoint to make proxy requests. (i.e. `https://proxy.withampersand.com/graphql`)
### Supported Objects
The Fireflies connector supports reading to 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**
# Flatfile
Source: https://docs.withampersand.com/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.
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.withampersand.com/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**.
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.
## 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.\\
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.
6. Click **Save Changes**.
# Four/Four
Source: https://docs.withampersand.com/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.
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.
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.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.withampersand.com/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 an 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.withampersand.com/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.withampersand.com/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={null}
# 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.withampersand.com/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
### 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.
### 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.
3. Select **Provider apps**.
4. Select **GetResponse** from the **Provider** list.
5. Enter the **Client ID** and **Client Secret** obtained in the previous step.
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.withampersand.com/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
3. Go to **Provider apps**
4. Select **GitHub** from the **Provider list**
5. Enter your OAuth app credentials:
* Client ID
* Client Secret
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.withampersand.com/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 an 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.withampersand.com/provider-guides/goTo
The GoTo connector supports GoTo products which have APIs with the root URL `api.getgo.com`, these include:
* GoToWebinar
* GoToMeeting
## What's Supported
### Supported Actions
This connector supports:
* [Proxy Actions](/proxy-actions), using the base URL `https://api.getgo.com`.
## 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 this credential to connect your application to Ampersand.
### Create a GoTo Account
Here's how you can sign up for an GoTo account:
1. Go to the [GoTo SignUp page](https://developer.goto.com/signup/).
2. Fill in the necessary details and register your account.
### Creating an OAuth app in GoTo
Once your GoTo 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 [GoTo Account](https://identity.goto.com/login).
2. Go to [Developers](https://developer.logmeininc.com/clients).
3. Click on **Create a new client**
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 **Next**.
8. Select the applicable permissions.
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.
## Add GoTo 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 GoTo App.
3. Navigate to the **Provider Apps** section.
4. Select **GoTo** from the Provider list.
5. Enter the previously obtained **Client ID** and **Client Secret** in their respective fields.
6. Click **Save Changes**.
# Gong
Source: https://docs.withampersand.com/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.
**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 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.
### 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`.
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).
## 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.
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={null}
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-webhook.withampersand.com/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.withampersand.com/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.
* [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
*\[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.
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.
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.
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.
4. On the Test Users page, click "+ Add Users" to add up to 100 email addresses, and then click "Save and Continue".
### 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".
2. Click "Web Application" from the Application Type dropdown menu.
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".
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".
## 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.
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`
6. Click **Save changes**.
## 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.
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).
### 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.
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.
### 1. Log into gcloud CLI
Replace `PROJECT_ID` with your Google Cloud project ID.
```bash theme={null}
gcloud auth login
gcloud config set project PROJECT_ID
```
### 2. Enable the Pub/Sub API
```bash theme={null}
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={null}
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={null}
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={null}
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={null}
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**.
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".
3. Then click on the "Prepare for Verification" button that should now be visible, follow the instructions on the screen.
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.withampersand.com/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={null}
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
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.
#### 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={null}
{
"provider": "googleWorkspaceDelegation",
"groupRef": "g0-ref",
"groupName": "g0-name",
"consumerRef": "c0-ref",
"consumerName": "c0-name",
"providerMetadata": {
"userEmail": {
"value": "user@example.com"
}
},
"customAuth": {
"serviceAccountKey": "",
"scopes": [
"https://www.googleapis.com/auth/contacts"
]
}
}
```
The API response includes an `id` field — that value is the Connection ID.
```json theme={null}
{
"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={null}
{
"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.withampersand.com/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**.
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.
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.withampersand.com/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.withampersand.com/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 from 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.
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.
# Guru
Source: https://docs.withampersand.com/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={null}
# 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.withampersand.com/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.
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.withampersand.com/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 an 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={null}
# 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 API Key Configuration Modal will appear.
5. Enter a Name for the API key, configure the required access permissions, and click **Generate**.
# Help Scout Mailbox
Source: https://docs.withampersand.com/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**.
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 it to connect your app to Ampersand.
## 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.\\
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.
6. Click **Save Changes**.
# HeyReach
Source: https://docs.withampersand.com/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 from 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={null}
# 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**.
# HighLevel
Source: https://docs.withampersand.com/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 to 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 an 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 an HighLevel App
Follow the steps below to create an 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**.
### 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**.
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.
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.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.withampersand.com/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={null}
- 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={null}
- 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.
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-webhook.withampersand.com/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.withampersand.com/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-`.
Note that **occurrences** is spelled with two c's and two r's.
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={null}
- 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
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.
### 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 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
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)
If you have multiple accounts, make sure to select the developer account.
5. **Create** your Personal Access Key and copy it
6. **Go back** to terminal, **paste** the key and **hit Enter**
7. Create a project:
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={null}
{
"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".
10. Accept HubSpot's Acceptable Use Policy
If this is your first time create 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.
* Select the project you just created
* In the **Project Components** section, click on the 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.
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**
12. Jump to [Add App to Ampersand](#add-app-to-ampersand).
### Method 2: Legacy Apps
Legacy Apps has 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.
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**
If you don't see the Development menu, you need Super Admin permissions.
3. Click **Create** → Select **Public**
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"
5. Go to the Scopes section, click "Add new scope" and **select your required scopes**
6. **Copy your Client ID and Client Secret** from the Auth tab
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**
3. Enter **Public app name**, click the **Auth** tab, add Redirect URL: `https://api.withampersand.com/callbacks/v1/oauth` and click "Create app"
4. Go to the **Scopes** tab and select your required scopes
5. Copy your **Client ID** and **Client Secret** from the Auth tab
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**.
These scopes must should match the exact set of scopes defined in your HubSpot app.
## 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
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.
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. Login 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**.
## 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 to start the installation process (this is usually where you've embedded the Ampersand UI Component).
# Hunter
Source: https://docs.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.withampersand.com/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 Instantlty connector supports writing from 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 **Integraions** and navigate to **APIKeys**.
4. Click **Create API Key**.
# Intercom
Source: https://docs.withampersand.com/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 a 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**.
### 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`.
### Accessing Client ID and Client Secret
Once your app is created, Intercom provides your *Client ID* and *Client Secret* which will is 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.
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.
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.withampersand.com/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 you application.
8. Click **Save Changes**.
## 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*.
7. Click **Save Changes**.
# Iterable
Source: https://docs.withampersand.com/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.withampersand.com/provider-guides/jira
Jira is supported in the Atlassian provider, please refer to the [Atlassian guide](/provider-guides/atlassian).
# Jobber
Source: https://docs.withampersand.com/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 not supported, a full read of the Jobber instance will be done for each scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.getjobber.com/api/graphql`.
### Supported Objects
The Jobber connector supports reading from the following objects:
* appAlerts
* apps
* capitalLoans
* clientEmails
* clientPhones
* clients
* expenses
* invoices
* jobs
* paymentsRecords
* payoutRecords
* products
* properties
* quotes
* requestSettingsCollection
* requests
* scheduledItems
* similarClients
* tasks
* taxRates
* timeSheetEntries
* users
* vehicles
* visits
The Jobber connector supports writing to the following objects:
* clients
* events
* expenses
* jobs
* productsAndServices
* quotes
* requests
* taxes
* taxGroups
* vehicles
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".
### Example integration
For an example manifest file of an 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.
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/).
### 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 it 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 Help Scout integration.\\
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, 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.
# Join.me
Source: https://docs.withampersand.com/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 do 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 the terms of service and then, Click the **Register Application**.
### Example integration
To define an integration for Join.me, create a manifest file that looks like this:
```YAML theme={null}
#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.
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.
# Jotform
Source: https://docs.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.
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.withampersand.com/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.
For more details, see the [JustCall Authentication documentation](https://developer.justcall.io/reference/authentication).
# Kaseya VSAX
Source: https://docs.withampersand.com/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 Guru, create a manifest file that looks like this:
```YAML theme={null}
# 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 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://{{.workspace}}`.
# Keap
Source: https://docs.withampersand.com/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**.
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.
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.
6. Click **Save Changes**.
# Kit
Source: https://docs.withampersand.com/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.
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**.
## 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.
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.
## 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.withampersand.com/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.
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**.
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.
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**.
7. Click **Save Changes**.
# Lemlist
Source: https://docs.withampersand.com/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={null}
# 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.withampersand.com/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 to 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 an 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**.
## 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.
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.
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.
# Linear
Source: https://docs.withampersand.com/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 to 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 an 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.
## 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.
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`.
Check [Linear's documentation](https://linear.app/developers/oauth-2-0-authentication#redirect-user-access-requests-to-linear) for more details.
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.withampersand.com/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 an 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 **Auth 2.0 settins**, enter the Ampersand redirect URL: `https://api.withampersand.com/callbacks/v1/oauth`.
## 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.
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.
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.withampersand.com/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 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={null}
#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.
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.
# Loxo
Source: https://docs.withampersand.com/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 an 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:**
> * 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.
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.
# Mailgun
Source: https://docs.withampersand.com/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={null}
# 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.withampersand.com/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)
`activities` is supported in private preview only. Please reach out to `support@withampersand.com` for more information.
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.withampersand.com/provider-guides/meta
The Meta connector supports Meta products which have APIs with the root URL `https://graph.facebook.com`, these include:
* Facebook
* WhatsApp
## What's Supported
### Supported Actions
This connector supports:
* [Proxy Actions](/proxy-actions), using the base URL `https://graph.facebook.com`.
## 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**.
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).
## 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.
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.
7. Click **Save Changes**.
# Microsoft
Source: https://docs.withampersand.com/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 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
## 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** 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.
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
# Miro
Source: https://docs.withampersand.com/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.
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.
### 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.
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.
6. Click **Save changes** to finalize the integration.
# Mixmax
Source: https://docs.withampersand.com/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 an 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.withampersand.com/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={null}
# 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.
# Monday
Source: https://docs.withampersand.com/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.
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.withampersand.com/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**.
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*.
7. Click **Save Changes**.
# NetSuite
Source: https://docs.withampersand.com/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={null}
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.withampersand.com/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={null}
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.withampersand.com/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`.
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.
## 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.
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.
6. Click **Save Changes**.
# Nutshell
Source: https://docs.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.
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.withampersand.com/provider-guides/okta
## What's supported
### Supported actions
This connector supports:
* [Proxy Actions](/proxy-actions), using the base URL `https://{{.workspace}}.okta.com`.
## 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.
## 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.
3. Select **Provider Apps**.
4. Select *Okta* 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 *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).
7. Click **Save Changes**.
# OpenAI
Source: https://docs.withampersand.com/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={null}
# 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.withampersand.com/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:**
The `call` object requires incremental read to be configured. Without it, only records from the last 30 days will be read.
### 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.withampersand.com/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
*\* 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.
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.
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.
# Overview
Source: https://docs.withampersand.com/provider-guides/overview
This section includes guides for the API providers that Ampersand integrates with.
Is there a new API provider that you'd like to see? File an issue on Ampersand's [connectors repository](https://github.com/amp-labs/connectors).
# Paddle
Source: https://docs.withampersand.com/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 an 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.withampersand.com/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={null}
# 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.withampersand.com/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
### 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={null}
# 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 an *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**.
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.
## 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.
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.
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.withampersand.com/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 from 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 an 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**.
> 📔 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
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.
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.
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.withampersand.com/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](#v2-api-objects) 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. Otherwise, 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={null}
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={null}
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)
* [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**.
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.
## 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.
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.withampersand.com/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={null}
# 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.withampersand.com/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 signup 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**.
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.\\
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*.
7. Click **Save Changes**.
# Procore
Source: https://docs.withampersand.com/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.
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.
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.withampersand.com/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.
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.
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.
# Pylon
Source: https://docs.withampersand.com/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.withampersand.com/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.
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**.
7. Click **Save Changes**.
## Using the connector
To start integrating with Kit:
* 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.
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.
## API documentation
* [QuickBooks API](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account#the-account-object)
# Ramp
Source: https://docs.withampersand.com/provider-guides/ramp
## What's Supported
### Supported Actions
This connector supports:
* [Proxy Actions](/proxy-actions), using the base URL `https://api.ramp.com`.
## 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 setup, 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](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.
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.
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*.
# Rebilly
Source: https://docs.withampersand.com/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={null}
# 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.withampersand.com/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.
# RevenueCat
Source: https://docs.withampersand.com/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
### 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 `.
* **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.withampersand.com/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**.
## 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.
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.
## 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.withampersand.com/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 and 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.
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.
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.withampersand.com/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={null}
# 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.withampersand.com/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={null}
# 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.withampersand.com/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
*\* 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:
*\* 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**.
### 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**.
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**.
### 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.
### 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**.
3. Search for **External Client App Manager**.
4. Click **New External Client App**.
* 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`
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”
6. Go to the Settings tab, expand “OAuth Settings”. Click on “Consumer Key and Secret”.
### 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={null}
npm install -g @salesforce/cli
```
2. **Create a Salesforce DX project.** From a new directory, generate a project:
```bash theme={null}
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={null}
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={null}
{
"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={null}
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={null}
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={null}
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={null}
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={null}
https://login.salesforce.com/packaging/installPackage.apexp?p0=SUBSCRIBER_PACKAGE_VERSION_ID
```
For sandbox orgs:
```text theme={null}
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.
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".
They should see a screen like this after they are successful.
*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.
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#1-view-and-edit-permissions-for-profile) 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**.
2. Check both required checkboxes to confirm migration.
3. Click **Migrate**.
4. Click **OK**.
5. A **confirmation message** will appear.
6. Open **External Client App Manager**.
7. Select your app, go to the **Settings** tab and set "Distribution State" to **Packaged**.
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”
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).
## 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.
## 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.withampersand.com/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={null}
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).
Salesforce requires an RSA key (2048-bit minimum). ECDSA keys are not supported for the JWT Bearer flow.
## 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).
* Collect your customer's credentials (Consumer Key, Username, Private Key, Subdomain) and create a connection.
* 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.withampersand.com/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).
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).
### 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.
## 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.
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.withampersand.com/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={null}
# 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.withampersand.com/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**.
### 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.
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.
6. Click **Save changes**.
# Sellsy
Source: https://docs.withampersand.com/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.
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.
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.
# SendGrid
Source: https://docs.withampersand.com/provider-guides/sendGrid
## What's supported
### Supported actions
This connector supports:
* [Proxy Actions](/proxy-actions), using the base URL `https://api.sendgrid.com`.
### Example integration
To define an integration for SendGrid, create a manifest file that looks like this:
```YAML theme={null}
# amp.yaml
specVersion: 1.0.0
integrations:
- name: sendGrid-integration
displayName: My SendGrid Integration
provider: sendGrid
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 SendGrid:
* 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.sendgrid.com`.
## Creating an API key for SendGrid
[Click here](https://www.twilio.com/docs/sendgrid) for more information about generating an API key for SendGrid. The UI components will display this link, so that your users can successfully create API keys.
# ServiceNow
Source: https://docs.withampersand.com/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 an 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**.
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.
7. Click **Save Changes**.
# Shopify
Source: https://docs.withampersand.com/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**.
2. Create an app. After the app is created, you’ll land on **Create a version**.
3. Configure the access scopes your integration needs.
4. Configure the OAuth redirect URL:
* `https://api.withampersand.com/callbacks/v1/oauth`
5. Release the version. Then go to the app’s settings page and note the **Client ID** and **Client Secret**.
### 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)
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.
## 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**.
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)
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)
4. Tell them about your business and add a credit card to pay \$19 one-time app store registration fee.
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.
8. Ask your customers to install the app from the App Store listing URL. For example:
```text theme={null}
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.
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.withampersand.com/provider-guides/slack
## 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 `conversations`, `files`, `usergroups`, `users.conversations`, and `users`. For all other objects, a full read of the Slack instance will be done per scheduled read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://slack.com/api`.
### Supported objects
The Slack connector supports reading from the following objects:
* [auth.teams](https://docs.slack.dev/reference/methods/auth.teams.list) (full read each time)
* [conversations](https://docs.slack.dev/reference/methods/conversations.list) (supports incremental read, use this object to read all the channels in the workspace)
* [conversations.listConnectInvites](https://docs.slack.dev/reference/methods/conversations.listConnectInvites) (full read each time)
* [conversations.requestSharedInvite](https://docs.slack.dev/reference/methods/conversations.requestSharedInvite.list) (full read each time)
* [files](https://docs.slack.dev/reference/methods/files.list) (supports incremental read)
* [files.remote](https://docs.slack.dev/reference/methods/files.remote.list) (full read each time)
* [reactions](https://docs.slack.dev/reference/methods/reactions.list) (full read each time)
* [team.externalTeams](https://docs.slack.dev/reference/methods/team.externalTeams.list) (full read each time)
* [usergroups](https://docs.slack.dev/reference/methods/usergroups.list) (supports incremental read)
* [users.conversations](https://docs.slack.dev/reference/methods/users.conversations) (full read each time, use this object to only read channels that the user has access to)
* [users](https://docs.slack.dev/reference/methods/users.list) (supports incremental read)
The Slack connector supports writing to the following objects:
* [bookmarks](https://docs.slack.dev/reference/methods/bookmarks.add)
* [calls](https://docs.slack.dev/reference/methods/calls.add)
* [canvases](https://docs.slack.dev/reference/methods/canvases.create)
* [conversations](https://docs.slack.dev/reference/methods/conversations.create)
* [conversations.canvases](https://docs.slack.dev/reference/methods/conversations.canvases.create)
* [files.remote](https://docs.slack.dev/reference/methods/files.remote.add)
* [slackLists](https://docs.slack.dev/reference/methods/slackLists.create)
* [slackLists.items](https://docs.slack.dev/reference/methods/slackLists.items.create)
* [usergroups](https://docs.slack.dev/reference/methods/usergroups.create)
### Example integration
For an example manifest file of a Slack integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/slack/amp.yaml).
## 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 (user scopes are currently not supported)
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** for your app by clicking on **Add an OAuth Scope** and selecting the required scopes. **User Token Scopes are currently not supported.**
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.
3. Select **Provider Apps**.
4. Select **Slack** 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** set for your application in *Slack*.
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.withampersand.com/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 support 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.withampersand.com/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**.
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.
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**.
7. Click **Save Changes**.
# Snapchat Ads
Source: https://docs.withampersand.com/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**.
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.
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.withampersand.com/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.withampersand.com/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.
# Stripe
Source: https://docs.withampersand.com/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
The Stripe connector supports reading from and writing to the following objects:
* [accounts](https://docs.stripe.com/api/accounts/object) (incremental read supported)
* apple\_pay/domains (Apple Pay Domains)
* [billing/alerts](https://docs.stripe.com/api/billing/alert/object)
* [billing/credit\_grants](https://docs.stripe.com/api/billing/credit-grant/object)
* [billing/meters](https://docs.stripe.com/api/billing/meter/object)
* [billing\_portal/configurations](https://docs.stripe.com/api/customer_portal/configurations/object)
* [charges](https://docs.stripe.com/api/charges/object) (incremental read supported)
* [checkout/sessions](https://docs.stripe.com/api/checkout/sessions/object) (incremental read supported)
* [climate/orders](https://docs.stripe.com/api/climate/order/object)
* [coupons](https://docs.stripe.com/api/coupons/object) (incremental read supported)
* [credit\_notes](https://docs.stripe.com/api/credit_notes/object) (incremental read supported)
* [customers](https://docs.stripe.com/api/customers/object) (incremental read supported)
* [disputes](https://docs.stripe.com/api/disputes/object) (incremental read supported)
* [entitlements/features](https://docs.stripe.com/api/entitlements/feature/object)
* [file\_links](https://docs.stripe.com/api/file_links/object) (incremental read supported)
* [files](https://docs.stripe.com/api/files/object) (incremental read supported)
* [forwarding/requests](https://docs.stripe.com/api/forwarding/request/object) (incremental read supported)
* [identity/verification\_sessions](https://docs.stripe.com/api/identity/verification_sessions/object) (incremental read supported)
* [invoiceitems](https://docs.stripe.com/api/invoiceitems/object) (incremental read supported)
* [invoices](https://docs.stripe.com/api/invoices/object) (incremental read supported)
* [issuing/authorizations](https://docs.stripe.com/api/issuing/authorizations/object) (incremental read supported)
* [issuing/cardholders](https://docs.stripe.com/api/issuing/cardholders/object) (incremental read supported)
* [issuing/cards](https://docs.stripe.com/api/issuing/cards/object) (incremental read supported)
* [issuing/disputes](https://docs.stripe.com/api/issuing/disputes/object) (incremental read supported)
* [issuing/personalization\_designs](https://docs.stripe.com/api/issuing/personalization_designs/object)
* [issuing/transactions](https://docs.stripe.com/api/issuing/transactions/object) (incremental read supported)
* [payment\_intents](https://docs.stripe.com/api/payment_intents/object) (incremental read supported)
* [payment\_links](https://docs.stripe.com/api/payment-link/object)
* [payment\_method\_configurations](https://docs.stripe.com/api/payment_method_configurations/object)
* [payment\_method\_domains](https://docs.stripe.com/api/payment_method_domains/object)
* [payment\_methods](https://docs.stripe.com/api/payment_methods/object)
* [payouts](https://docs.stripe.com/api/payouts/object) (incremental read supported)
* [plans](https://docs.stripe.com/api/plans/object) (incremental read supported)
* [prices](https://docs.stripe.com/api/prices/object) (incremental read supported)
* [products](https://docs.stripe.com/api/product-feature/object) (incremental read supported)
* [promotion\_codes](https://docs.stripe.com/api/promotion_codes/object) (incremental read supported)
* [quotes](https://docs.stripe.com/api/quotes/object)
* [radar/value\_lists](https://docs.stripe.com/api/radar/value_lists/object) (incremental read supported)
* [refunds](https://docs.stripe.com/api/refunds/object) (incremental read supported)
* [reporting/report\_runs](https://docs.stripe.com/api/reporting/report_run/object) (incremental read supported)
* [setup\_intents](https://docs.stripe.com/api/setup_intents/object) (incremental read supported)
* [shipping\_rates](https://docs.stripe.com/api/shipping_rates/object) (incremental read supported)
* [subscription\_schedules](https://docs.stripe.com/api/subscription_schedules/object) (incremental read supported)
* [subscriptions](https://docs.stripe.com/api/subscriptions/object) (incremental read supported)
* [tax/registrations](https://docs.stripe.com/api/tax/registrations/object)
* [tax\_ids](https://docs.stripe.com/api/tax_ids/object)
* [tax\_rates](https://docs.stripe.com/api/tax_rates/object) (incremental read supported)
* [terminal/configurations](https://docs.stripe.com/api/terminal/configuration/object)
* [terminal/locations](https://docs.stripe.com/api/terminal/locations/object)
* [terminal/readers](https://docs.stripe.com/api/terminal/readers/object)
* [test\_helpers/test\_clocks](https://docs.stripe.com/api/test_clocks/object)
* [topups](https://docs.stripe.com/api/topups/object) (incremental read supported)
* [transfers](https://docs.stripe.com/api/transfers/object) (incremental read supported)
* [treasury/financial\_accounts](https://docs.stripe.com/api/treasury/financial_accounts/object) (incremental read supported)
* [webhook\_endpoints](https://docs.stripe.com/api/webhook_endpoints/object)
The Stripe connector supports only read actions on the following objects:
* [application\_fees](https://docs.stripe.com/api/application_fees/object) (incremental read supported)
* [balance\_transactions](https://docs.stripe.com/api/balance_transactions/object) (incremental read supported)
* [climate/products](https://docs.stripe.com/api/climate/product/object)
* [climate/suppliers](https://docs.stripe.com/api/climate/supplier/object)
* [country\_specs](https://docs.stripe.com/api/country_specs/object)
* [events](https://docs.stripe.com/api/events/object) (incremental read supported)
* [financial\_connections/accounts](https://docs.stripe.com/api/financial_connections/accounts/object)
* balance/history (Transaction history for balance changes) (incremental read supported)
* [identity/verification\_reports](https://docs.stripe.com/api/identity/verification_reports/object) (incremental read supported)
* [invoice\_rendering\_templates](https://docs.stripe.com/api/invoice-rendering-template/object)
* [issuing/physical\_bundles](https://docs.stripe.com/api/issuing/physical_bundles/object)
* [radar/early\_fraud\_warnings](https://docs.stripe.com/api/radar/early_fraud_warnings/object) (incremental read supported)
* [reporting/report\_types](https://docs.stripe.com/api/reporting/report_type/object)
* [reviews](https://docs.stripe.com/api/radar/reviews/object) (incremental read supported)
* [sigma/scheduled\_query\_runs](https://docs.stripe.com/api/sigma/scheduled_queries/object)
* [tax\_codes](https://docs.stripe.com/api/tax_codes/object)
The Stripe connector supports only write actions on the following objects:
* [account\_links](https://docs.stripe.com/api/account_links/object)
* [account\_sessions](https://docs.stripe.com/api/account_sessions/object)
* [apps/secrets](https://docs.stripe.com/api/apps/secret_store/secret_resource)
* [billing/meter\_event\_adjustments](https://docs.stripe.com/api/billing/meter-event-adjustment/object)
* [billing/meter\_events](https://docs.stripe.com/api/billing/meter-event/object)
* [billing\_portal/sessions](https://docs.stripe.com/api/customer_portal/sessions/object)
* [customer\_sessions](https://docs.stripe.com/api/customer_sessions/object)
* ephemeral\_keys (Creates a short-lived API key for a given resource)
* [financial\_connections/sessions](https://docs.stripe.com/api/financial_connections/sessions/object)
* [invoices/create\_preview](https://docs.stripe.com/api/invoices/create_preview)
* issuing/settlements (Updates the specified Issuing Settlement object)
* [issuing/tokens](https://docs.stripe.com/api/issuing/tokens/object)
* [issuing/tokens](https://docs.stripe.com/api/issuing/tokens/object)
* [radar/value\_list\_items](https://docs.stripe.com/api/radar/value_list_items/object)
* [sources](https://docs.stripe.com/api/sources/object)
* [subscription\_items](https://docs.stripe.com/api/subscription_items/object)
* [tax/calculations](https://docs.stripe.com/api/tax/calculations/object)
* [tax/settings](https://docs.stripe.com/api/tax/settings/object)
* [terminal/connection\_tokens](https://docs.stripe.com/api/terminal/connection_tokens/object)
* [test\_helpers/confirmation\_tokens](https://docs.stripe.com/api/confirmation_tokens/object)
* [test\_helpers/issuing/authorizations](https://docs.stripe.com/api/issuing/authorizations/test_mode_create)
* test\_helpers/issuing/settlements (Create an Issuing settlement)
* [test\_helpers/treasury/outbound\_payments](https://docs.stripe.com/api/treasury/outbound_payments/test_mode_update)
* [test\_helpers/treasury/outbound\_transfers](https://docs.stripe.com/api/treasury/outbound_transfers/test_mode_update)
* [test\_helpers/treasury/received\_credits](https://docs.stripe.com/api/treasury/received_credits/object)
* [test\_helpers/treasury/received\_debits](https://docs.stripe.com/api/treasury/received_debits/object)
* [treasury/credit\_reversals](https://docs.stripe.com/api/treasury/credit_reversals/object)
* [treasury/debit\_reversals](https://docs.stripe.com/api/treasury/debit_reversals/object)
* [treasury/inbound\_transfers](https://docs.stripe.com/api/treasury/inbound_transfers/object)
* [treasury/outbound\_payments](https://docs.stripe.com/api/treasury/outbound_payments/object)
* [treasury/outbound\_transfers](https://docs.stripe.com/api/treasury/outbound_transfers/object)
### 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.withampersand.com/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={null}
# 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.
For more details, see the [SuperSend Authentication documentation](https://docs.supersend.io/docs/authentication).
# Survey Monkey
Source: https://docs.withampersand.com/provider-guides/surveyMonkey
## What's Supported
### Supported Actions
This connector supports:
* [Proxy Actions](/proxy-actions), using the base URL `https://api.surveymonkey.com`.
## 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 then 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**.
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.
9. Click **Update Scopes**.
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.
## Add SurveyMonkey 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 SurveyMonkey App.
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.
6. Click **Save Changes**.
# Talkdesk
Source: https://docs.withampersand.com/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**.
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.
6. Enter the scopes set for your application in *Talkdesk*.
7. Click **Save Changes**.
# Teamleader
Source: https://docs.withampersand.com/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**.\\
### 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.
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.
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.withampersand.com/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.
### 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.
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.
6. Click **Save Changes**.
# Timely
Source: https://docs.withampersand.com/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 [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**.
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.
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.
6. Click **Save Changes**.
# Tipalti
Source: https://docs.withampersand.com/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={null}
# 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.
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.withampersand.com/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={null}
# 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 connector's base URL will be: https\://your\_instance.odx/restapi.
# Webex
Source: https://docs.withampersand.com/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
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.
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**.
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.
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.withampersand.com/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.withampersand.com/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={null}
# 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**
# WordPress
Source: https://docs.withampersand.com/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 login 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**.
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*.
7. Click **Save Changes**.
# Wrike
Source: https://docs.withampersand.com/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**.
### 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.
## 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.
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*.
7. Click **Save Changes**.
# Xero
Source: https://docs.withampersand.com/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 an 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.
## 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.
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**.
## 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.withampersand.com/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 other 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**.
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**.
## 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.
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.
6. Click **Save Changes**.
## Using the connector
Please note that due to Zendesk's API permission requirements, this integration requires credentials from a Zendesk admin.
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.withampersand.com/provider-guides/zoho
The Zoho connector supports the following Zoho products:
* Zoho CRM (default)
* Zoho Desk
## 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
Object
Read
Write
Subscribe
Leads
Accounts
Contacts
Deals
Campaigns
Tasks
Cases
Events
Meetings
Calls
Solutions
Products
Vendors
Price Books
Quotes
Sales Orders
Purchase Orders
Invoices
Appointments
Appointments Rescheduled History
Services
Custom
Users
### 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).
## 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/)
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)
### 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.
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.
## 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.
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
// Additional scope required for Subscribe Actions
ZohoCRM.notifications.ALL
```
**Zoho Desk:**
```
Desk.basic.READ
Desk.settings.ALL
```
In case you are using **Subscribe** action, additional scope is required
```
ZohoCRM.notifications.ALL
```
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.
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.withampersand.com/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`.
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.
### 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 an 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`.
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).
### 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.
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.
6. Click **Save changes**.
# Proxy actions
Source: https://docs.withampersand.com/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={null}
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`, making the same request to `https://proxy.withampersand.com/services/data/v56.0/sobjects/Account`.
Please refer to the [Provider Guides](/provider-guides) 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={null}
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: ' \
--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 request 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.withampersand.com/quickstart
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).
## 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. You can do this as an org owner in the dashboard under org settings. Once enabled, anyone with a `@yourcompany.com` email will automatically be added to your org.
## 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) 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 Actions](/read-actions). We'll read 2 objects from Salesforce: contacts and leads.
```YAML YAML theme={null}
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 YAML theme={null}
...
# 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):
```
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](https://github.com/amp-labs/starter-project/tree/main).
Here's a simplified version of what our frontend code would look like:
```TypeScript TypeScript theme={null}
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 (
)
}
```
# Read actions
Source: https://docs.withampersand.com/read-actions
A read action reads data from your customer's SaaS and send 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={null}
...
objects:
- objectName: lineItem
destination: lineItemWebhook
schedule: "*/10 * * * *" # every 10 minutes
backfill:
defaultPeriod:
days: 30
...
```
### Required fields and optional fields
Fields can be 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={null}
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={null}
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={null}
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).
## 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={null}
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={null}
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={null}
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.
Filtered reads are currently only supported for **Salesforce** (CRM Module) and **HubSpot**.
### 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={null}
{
"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={null}
{
"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".
### Valid filter values
The `value` field of the filter accepts strings, booleans, and numbers:
```json theme={null}
{ "fieldName": "name", "operator": "eq", "value": "Acme" }
{ "fieldName": "isActive", "operator": "eq", "value": true }
{ "fieldName": "employeeCount", "operator": "eq", "value": 50 }
```
## 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={null}
{
groupRef: "xye23r3df",
mode: "async"
}
```
* Read all records from a specific timestamp to now
```json theme={null}
{
groupRef: "xye23r3df",
mode: "async",
sinceTimestamp: "2012-04-23T18:25:43.511Z"
}
```
## Full example
```yaml yaml theme={null}
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)
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.
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={null}
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, 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={null}
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.withampersand.com/reference/api-key/create-a-new-api-key
platform post /projects/{projectIdOrName}/api-keys
# Delete an API key
Source: https://docs.withampersand.com/reference/api-key/delete-an-api-key
platform delete /projects/{projectIdOrName}/api-keys/{apiKey}
# Get an API key
Source: https://docs.withampersand.com/reference/api-key/get-an-api-key
platform get /projects/{projectIdOrName}/api-keys/{apiKey}
# List API keys
Source: https://docs.withampersand.com/reference/api-key/list-api-keys
platform get /projects/{projectIdOrName}/api-keys
# Update an API key
Source: https://docs.withampersand.com/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.withampersand.com/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.withampersand.com/reference/billing-account/get-the-billing-account-for-an-organization
platform get /orgs/{orgId}/billingAccount
# Delete a connection
Source: https://docs.withampersand.com/reference/connection/delete-a-connection
platform delete /projects/{projectIdOrName}/connections/{connectionId}
# Generate a new connection
Source: https://docs.withampersand.com/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.withampersand.com/reference/oauth/get-url-for-oauth-flow) instead, unless you already have the refresh token and are importing it into Ampersand.
# Get a connection
Source: https://docs.withampersand.com/reference/connection/get-a-connection
platform get /projects/{projectIdOrName}/connections/{connectionId}
# List connections
Source: https://docs.withampersand.com/reference/connection/list-connections
platform get /projects/{projectIdOrName}/connections
# Update a connection.
Source: https://docs.withampersand.com/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.withampersand.com/reference/destination/create-a-new-destination
platform post /projects/{projectIdOrName}/destinations
# Create a topic
Source: https://docs.withampersand.com/reference/destination/create-a-topic
platform post /projects/{projectIdOrName}/topics
# Create a topic destination route
Source: https://docs.withampersand.com/reference/destination/create-a-topic-destination-route
platform post /projects/{projectIdOrName}/topic-destination-routes
# Delete a destination
Source: https://docs.withampersand.com/reference/destination/delete-a-destination
platform delete /projects/{projectIdOrName}/destinations/{destination}
# Delete a topic
Source: https://docs.withampersand.com/reference/destination/delete-a-topic
platform delete /projects/{projectIdOrName}/topics/{topicId}
# Delete a topic destination route
Source: https://docs.withampersand.com/reference/destination/delete-a-topic-destination-route
platform delete /projects/{projectIdOrName}/topic-destination-routes/{routeId}
# Get a destination
Source: https://docs.withampersand.com/reference/destination/get-a-destination
platform get /projects/{projectIdOrName}/destinations/{destination}
# List destinations
Source: https://docs.withampersand.com/reference/destination/list-destinations
platform get /projects/{projectIdOrName}/destinations
# List topic destination routes
Source: https://docs.withampersand.com/reference/destination/list-topic-destination-routes
platform get /projects/{projectIdOrName}/topic-destination-routes
# List topics
Source: https://docs.withampersand.com/reference/destination/list-topics
platform get /projects/{projectIdOrName}/topics
# Update a destination
Source: https://docs.withampersand.com/reference/destination/update-a-destination
platform patch /projects/{projectIdOrName}/destinations/{destination}
# Update a topic
Source: https://docs.withampersand.com/reference/destination/update-a-topic
platform patch /projects/{projectIdOrName}/topics/{topicId}
# Create a new installation
Source: https://docs.withampersand.com/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.withampersand.com/reference/oauth/generate-oauth-authorization-url) or the [prebuilt UI components](https://docs.withampersand.com/embeddable-ui-components).
# Delete an installation
Source: https://docs.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/cli/overview#deploy-integrations) rather than this API endpoint directly.
# Create a new integration.
Source: https://docs.withampersand.com/reference/integration/create-a-new-integration
platform post /projects/{projectIdOrName}/integrations
# Delete an integration
Source: https://docs.withampersand.com/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.withampersand.com/reference/integration/get-an-integration-by-id-or-name
platform get /projects/{projectIdOrName}/integrations/{integrationIdOrName}
# List integrations
Source: https://docs.withampersand.com/reference/integration/list-integrations
platform get /projects/{projectIdOrName}/integrations
# Create a new JWT key
Source: https://docs.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/reference/notification/list-notification-event-topic-routes
platform get /projects/{projectIdOrName}/notification-event-topic-routes
# Generate OAuth authorization URL
Source: https://docs.withampersand.com/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.withampersand.com/embeddable-ui-components).
# Generate OAuth authorization URL for existing connection
Source: https://docs.withampersand.com/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.withampersand.com/reference/oauth/generate-oauth-authorization-url) instead.
# Get object metadata via connection
Source: https://docs.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/reference/operation/list-logs-for-an-operation
platform get /projects/{projectIdOrName}/operations/{operationId}/logs
# List operations
Source: https://docs.withampersand.com/reference/operation/list-operations
platform get /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}/operations
# Add user to an organization
Source: https://docs.withampersand.com/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.withampersand.com/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.withampersand.com/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.withampersand.com/reference/org/create-a-new-organization
platform post /orgs
# Get an invite
Source: https://docs.withampersand.com/reference/org/get-an-invite
platform get /orgs/{orgId}/invites/{inviteId}
# Get an organization
Source: https://docs.withampersand.com/reference/org/get-an-organization
platform get /orgs/{orgId}
# Invite a user to an organization
Source: https://docs.withampersand.com/reference/org/invite-a-user-to-an-organization
platform post /orgs/{orgId}/invites
# List builders for an organization
Source: https://docs.withampersand.com/reference/org/list-builders-for-an-organization
platform get /orgs/{orgId}/builders
# List invites for an organization
Source: https://docs.withampersand.com/reference/org/list-invites-for-an-organization
platform get /orgs/{orgId}/invites
# List organization's claimed domains
Source: https://docs.withampersand.com/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.withampersand.com/reference/org/revoke-an-invite
platform delete /orgs/{orgId}/invites/{inviteId}
# Update an organization
Source: https://docs.withampersand.com/reference/org/update-an-organization
platform patch /orgs/{orgId}
# Create a new project
Source: https://docs.withampersand.com/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.withampersand.com/reference/project/get-a-project
platform get /projects/{projectIdOrName}
Get a project by its ID or name.
# List projects
Source: https://docs.withampersand.com/reference/project/list-projects
platform get /projects
Lists projects your credentials can access.
# Update a project
Source: https://docs.withampersand.com/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.withampersand.com/reference/provider-app/create-a-new-provider-app
platform post /projects/{projectIdOrName}/provider-apps
# Delete a provider app.
Source: https://docs.withampersand.com/reference/provider-app/delete-a-provider-app
platform delete /projects/{projectIdOrName}/provider-apps/{providerAppId}
# List provider apps
Source: https://docs.withampersand.com/reference/provider-app/list-provider-apps
platform get /projects/{projectIdOrName}/provider-apps
# Update a provider app
Source: https://docs.withampersand.com/reference/provider-app/update-a-provider-app
platform patch /projects/{projectIdOrName}/provider-apps/{providerAppId}
# Get provider
Source: https://docs.withampersand.com/reference/provider/get-provider
platform get /providers/{provider}
Returns information about a single provider. No authentication is required.
# List providers
Source: https://docs.withampersand.com/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.withampersand.com/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.withampersand.com/reference/read/trigger-a-read) endpoint instead.
# Pause reads for an installation
Source: https://docs.withampersand.com/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.withampersand.com/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.withampersand.com/define-integrations/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.withampersand.com/read-actions#defining-reads).
# Unpause reads for an installation
Source: https://docs.withampersand.com/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.withampersand.com/reference/revision/create-a-new-revision
platform post /projects/{projectIdOrName}/integrations/{integrationId}/revisions
We recommend using the [CLI's deploy command](https://docs.withampersand.com/cli/overview#deploy-integrations) rather than this API endpoint directly, unless you have an advanced use case.
# Get a hydrated revision
Source: https://docs.withampersand.com/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.withampersand.com/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.withampersand.com/reference/upload-url/generate-a-signed-url-to-upload-a-zip-file-to
platform get /generate-upload-url
# Accept an invite
Source: https://docs.withampersand.com/reference/user/accept-an-invite
platform post /invites:accept
# Get information about the current user
Source: https://docs.withampersand.com/reference/user/get-information-about-the-current-user
platform get /my-info
# Write records
Source: https://docs.withampersand.com/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.withampersand.com/write-actions) for details.
# Search actions
Source: https://docs.withampersand.com/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.
The Search API returns only a single page of provider results and is intended for narrow, targeted queries.
## 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={null}
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={null}
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={null}
// 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={null}
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: ' \
--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={null}
{
"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"
}
}
}
]
}
```
# Subscribe actions
Source: https://docs.withampersand.com/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.
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.
* Subscribe actions do not produce Operations or Logs that can be viewed in the Ampersand dashboard.
* It takes 1-2 minutes, and occasionally up to 10 minutes, for the first events to arrive after the initial installation.
## 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 that listen to any other events that are available in the provide 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={null}
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={null}
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={null}
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 that 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={null}
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={null}
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={null}
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={null}
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={null}
{
"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.
# Terminology
Source: https://docs.withampersand.com/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 member of the group has 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%5Freference.meta/object%5Freference/field%5Ftypes.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.
# Salesforce
Source: https://docs.withampersand.com/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={null}
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.
```
**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.
### Resolve a field-level visibility issue
Share the [field visibility instructions in the Salesforce customer guide](/customer-guides/salesforce#ensure-sufficient-permissions) 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={null}
{
"operationId": "00000000-0000-0000-0000-000000000000",
"errors": [
{
"message": "error writing account: bad request: No such column 'Testing__c' on sobject of type Account"
}
]
}
```
**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).
### 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).
# Build your own unified API
Source: https://docs.withampersand.com/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={null}
# 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={null}
{
"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={null}
subscribe:
objects:
- objectName: account
destination: webhook
inheritFieldsAndMapping: true
updateEvent:
enabled: always
requiredWatchFields:
- company_name # Your unified field
- revenue
```
```json theme={null}
// 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:
```yaml Jira theme={null}
- objectName: issue
mapToName: ticket
requiredFields:
- fieldName: id
mapToName: remote_id
- fieldName: summary
mapToName: title
- fieldName: status
mapToName: status
```
```yaml Linear theme={null}
- objectName: issues
mapToName: ticket
requiredFields:
- fieldName: id
mapToName: remote_id
- fieldName: title
mapToName: title
- fieldName: state
mapToName: status
```
```json Result theme={null}
{
"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" }
}
}
```
## Migration from Merge
**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.)
```bash theme={null}
git clone https://github.com/amp-labs/samples.git
cd samples/unifiedCRM # or unifiedTicketing
amp deploy --project=my-project
```
```javascript theme={null}
// 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);
});
```
```yaml theme={null}
subscribe:
objects:
- objectName: opportunity
inheritFieldsAndMapping: true
updateEvent:
enabled: always
requiredWatchFields:
- amount
- stage
```
Handle events in your webhook:
```javascript theme={null}
const { subscribeEventType, mappedFields } = req.body.result[0];
if (subscribeEventType === 'update' && mappedFields.stage === 'closed-won') {
await triggerSalesWorkflow(mappedFields);
}
```
## Complete examples
Salesforce, HubSpot, Zoho, Dynamics 365
Jira, Linear, Zendesk
## Related resources
* [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 coding agent
Source: https://docs.withampersand.com/use-with-ai-ide
The official Ampersand docs MCP server provides access to the full Ampersand documentation context, directly within your favorite Coding Agent or IDE. You can use it to help you build integrations quickly with Ampersand.
Ampersand's docs MCP server is hosted at `https://docs.withampersand.com/mcp`.
If you are using Claude Code, you can run this command:
```shell theme={null}
claude mcp add ampersand-docs --transport http "https://docs.withampersand.com/mcp"
```
## Client specific configuration
You can use Ampersand's MCP server with any AI application that support [MCP](https://modelcontextprotocol.io/clients). You need to add `https://docs.withampersand.com/mcp` to the appropriate configuration file or setting. 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) |
## Tips for better prompts
* Mention Ampersand in your prompt. For example, "How do I build X with Ampersand?"
* 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."
* Ask your agent to refer to Ampersand's OpenAPI spec at [https://github.com/amp-labs/openapi](https://github.com/amp-labs/openapi).
# Write actions
Source: https://docs.withampersand.com/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={null}
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#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={null}
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={null}
# Get project ID
amp list:projects
# List integrations for project
amp list:integrations --project
```
`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={null}
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.
This is currently only supported for HubSpot.
```bash theme={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//objects/contact' \
--header 'X-Api-Key: ' \
--header 'Content-Type: application/json' \
--data '{
"groupRef": "",
"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={null}
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
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.
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={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//objects/' \
--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.
This is currently only supported for Salesforce.
```bash theme={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//objects/contact' \
--header 'X-Api-Key: ' \
--header 'Content-Type: application/json' \
--data '{
"groupRef": "",
"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.
Batch write is currently only supported for HubSpot and Salesforce.
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.
HubSpot batch updates always result in partial success due to a provider limitation, regardless of the `allOrNone` setting.
#### Batch create
To create multiple records in a batch, set `type` to `create`:
```bash theme={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//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={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//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.
Associations in batch write are currently only supported for HubSpot.
```bash theme={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//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 executes 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.
Auto batching is currently only available for asynchronous mode and single-record writes (not batch writes).
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={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//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={null}
curl --location 'https://api.withampersand.com/v1/projects//operations/' \
--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={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//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={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//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={null}
{
"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={null}
curl --location 'https://api.withampersand.com/v1/projects//operations/' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY'
```
The response includes the operation status and result:
```json theme={null}
{
"id": "",
"projectId": "",
"integrationId": "",
"installationId": "",
"configId": "",
"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={null}
curl --location 'https://write.withampersand.com/v1/projects//integrations//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
These advanced use cases are currently only supported when creating or updating installations via the API or [Headless UI](/headless).
### 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={null}
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`:
[Create Installation API](/reference/installation/create-a-new-installation) — Include `deletionSettings` in the write object when creating the installation:
```Javascript theme={null}
{
"groupRef": "customer-group-ref",
"connectionId": "connection-id",
"config": {
"revisionId": "revision-id",
"content": {
"provider": "salesforce",
"write": {
"objects": {
"contact": {
"objectName": "contact",
"deletionSettings": {
"enabled": true
}
}
}
}
}
}
}
```
[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={null}
{
"updateMask": ["config.content.write.objects.contact"],
"installation": {
"config": {
"content": {
"provider": "salesforce",
"write": {
"objects": {
"contact": {
"objectName": "contact",
"deletionSettings": {
"enabled": true
}
}
}
}
}
}
}
}
```
[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={null}
{
"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.
### 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={null}
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={null}
{
"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={null}
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={null}
{
"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={null}
{
"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.