Ampersand Installation API
The Installation API from Ampersand — 4 operation(s) for installation.
OpenAPI Specification
openapi: 3.0.1
info:
title: Ampersand public API Key Installation API
version: 1.0.0
servers:
- url: https://api.withampersand.com/v1
security:
- APIKeyHeader: []
- Bearer: []
tags:
- name: Installation
paths:
/projects/{projectIdOrName}/integrations/{integrationId}/installations:
get:
summary: Ampersand List Installations for an Integration
description: 'Lists all installations for a specific integration within a project. To list installations across all integrations, use listInstallationsForProject instead.
'
operationId: listInstallations
tags:
- Installation
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: integrationId
in: path
required: true
description: The unique identifier (UUID) of the integration.
schema:
type: string
example: 550e8400-e29b-41d4-a716-446655440000
- name: groupRef
in: query
description: The ID that your app uses to identify a group of users (e.g. an org ID, workspace ID, or team ID). When provided, only returns installations belonging to this group.
example: group-123
schema:
type: string
responses:
200:
description: List of installations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Installation'
example:
- id: 3f8b2a1e-7c4d-4e9a-b5f6-1d2e3a4b5c6d
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
integrationId: 550e8400-e29b-41d4-a716-446655440000
group:
groupRef: org_12345
groupName: Acme Corp
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
healthStatus: healthy
connection:
id: 9d8c7b6a-5e4f-3a2b-1c0d-ef9876543210
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider: salesforce
group:
groupRef: org_12345
groupName: Acme Corp
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
consumer:
consumerRef: user_67890
consumerName: Jane Smith
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
createTime: '2024-01-15T10:30:00.000000Z'
authScheme: oauth2/authorizationCode
status: working
createTime: '2024-01-15T10:30:00.000000Z'
createdBy: consumer:user_67890
config:
id: e4d3c2b1-a098-7654-3210-fedcba987654
revisionId: f0e1d2c3-b4a5-6789-0abc-def123456789
createTime: '2024-01-15T10:30:00.000000Z'
createdBy: consumer:user_67890
content:
provider: salesforce
read:
objects:
account:
objectName: account
schedule: '*/15 * * * *'
destination: accountWebhook
selectedFields:
name: true
industry: true
400:
description: Bad Request
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
post:
summary: Ampersand Create a New Installation
operationId: createInstallation
description: '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).
'
tags:
- Installation
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: integrationId
in: path
required: true
description: The integration ID.
schema:
type: string
example: 113e9685-9a51-42cc-8662-9d9725b17f14
requestBody:
content:
application/json:
schema:
required:
- config
- groupRef
type: object
properties:
groupRef:
type: string
description: The ID of the user group that has access to this installation.
example: group-123
connectionId:
type: string
description: The ID of the SaaS connection tied to this installation. If omitted the default connection for this group will be used.
example: a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c
config:
required:
- content
type: object
properties:
revisionId:
type: string
deprecated: true
description: 'Deprecated: This field will be automatically set to the latest revision.'
createdBy:
type: string
description: The person who created the config, in the format of "consumer:{consumer-id}", "builder:{builder-id}", or "api:{api-caller}".
default: api:create-installation
content:
$ref: ../config/config.yaml#/components/schemas/ConfigContent
description: The content of the config.
description: The config of the installation.
examples:
writeOnly:
summary: Minimal write-only installation
value:
groupRef: group-123
connectionId: a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c
config:
content:
provider: salesforce
write:
objects:
contacts:
objectName: contacts
readWriteAndSubscribe:
summary: Read, write, and subscribe
value:
groupRef: group-456
connectionId: b2d5f8a3-9e4c-4b7f-8d1a-6c9e2f5b8d4a
config:
content:
provider: salesforce
read:
objects:
contacts:
objectName: contacts
schedule: '*/15 * * * *'
selectedFields:
phone: true
email: true
selectedFieldMappings:
phoneNumber: phone
emailAddress: email
write:
objects:
contacts:
objectName: contacts
subscribe:
objects:
contacts:
objectName: contacts
destination: contactWebhook
inheritFieldsAndMappings: true
required: true
responses:
201:
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Installation'
400:
description: Bad Request
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
422:
description: Unprocessable Entity
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
x-codegen-request-body-name: installation
/projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}:
get:
summary: Ampersand Get an Installation
description: 'Retrieves a single installation by ID, including its connection details, config, and health status.
'
operationId: getInstallation
tags:
- Installation
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: integrationId
in: path
required: true
description: The unique identifier (UUID) of the integration.
schema:
type: string
example: 550e8400-e29b-41d4-a716-446655440000
- name: installationId
in: path
required: true
description: The unique identifier (UUID) of the installation.
schema:
type: string
example: 7b3c9d2e-5a1f-4e8b-b6d4-9c8a2f1e5d3b
responses:
200:
description: The installation
content:
application/json:
schema:
$ref: '#/components/schemas/Installation'
example:
id: 3f8b2a1e-7c4d-4e9a-b5f6-1d2e3a4b5c6d
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
integrationId: 550e8400-e29b-41d4-a716-446655440000
group:
groupRef: org_12345
groupName: Acme Corp
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
healthStatus: healthy
connection:
id: 9d8c7b6a-5e4f-3a2b-1c0d-ef9876543210
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider: salesforce
group:
groupRef: org_12345
groupName: Acme Corp
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
consumer:
consumerRef: user_67890
consumerName: Jane Smith
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
createTime: '2024-01-15T10:30:00.000000Z'
authScheme: oauth2/authorizationCode
status: working
createTime: '2024-01-15T10:30:00.000000Z'
createdBy: consumer:user_67890
config:
id: e4d3c2b1-a098-7654-3210-fedcba987654
revisionId: f0e1d2c3-b4a5-6789-0abc-def123456789
createTime: '2024-01-15T10:30:00.000000Z'
createdBy: consumer:user_67890
content:
provider: salesforce
read:
objects:
account:
objectName: account
schedule: '*/15 * * * *'
destination: accountWebhook
selectedFields:
name: true
industry: true
400:
description: Unprocessable Entity
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
delete:
summary: Ampersand Delete an Installation
operationId: deleteInstallation
tags:
- Installation
description: 'Delete an Installation. This will also delete the associated Connection if it is not used by any other Installations.
'
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: integrationId
in: path
required: true
description: The integration ID.
schema:
type: string
- name: installationId
in: path
required: true
schema:
type: string
description: The Ampersand installation ID.
responses:
204:
description: Deleted
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
patch:
summary: Ampersand Update an Installation
operationId: updateInstallation
tags:
- Installation
description: '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.
'
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: integrationId
in: path
required: true
description: The ID of the integration that this installation belongs to.
schema:
type: string
example: e3a7f9c1-4b2d-4e8a-9f6b-2d5c8a1e3b7f
- name: installationId
in: path
required: true
description: The Ampersand installation ID.
schema:
type: string
example: 7b3c9d2e-5a1f-4e8b-b6d4-9c8a2f1e5d3b
requestBody:
content:
application/json:
schema:
required:
- installation
- updateMask
type: object
properties:
updateMask:
type: array
items:
type: string
description: 'Array of field paths specifying which fields to update. Each path must have a corresponding value in the `installation` object. A field included in `installation` but not listed here will be ignored. Allowed values:
- `connectionId` - switch the SaaS connection tied to this installation.
- `config.createdBy` - change the attribution for who created this config.
- `config.content.read.objects.<objectName>` - replace the read config for a single object (e.g. `config.content.read.objects.contacts`).
- `config.content.write.objects.<objectName>` - replace the write config for a single object.
- `config.content.write.objects` - replace the entire write objects map.
- `config.content.subscribe.objects.<objectName>` - replace the subscribe config for a single object.
- `config.content.subscribe.objects` - replace the entire subscribe objects map.
- `config.content.proxy.enabled` - enable or disable the proxy.
Replace `<objectName>` with the provider object name (e.g. `contacts`, `leads`, `accounts`).
'
example:
- config.content.read.objects.contacts
- config.content.write.objects.leads
installation:
type: object
properties:
connectionId:
type: string
description: The ID of the SaaS connection tied to this installation.
example: a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c
config:
type: object
properties:
revisionId:
type: string
deprecated: true
description: 'Deprecated: This field will be automatically set to the latest revision ID.'
createdBy:
type: string
description: The person who created the config, in the format of "consumer:{consumer-id}" or "builder:{builder-id}".
content:
$ref: ../config/config.yaml#/components/schemas/UpdateInstallationConfigContent
description: The content of the config.
description: The config of the installation.
description: 'The installation fields to update. Only fields whose paths are listed in `updateMask` will be
applied; all other fields in this object are ignored.
'
example:
updateMask:
- config.content.read.objects.contacts
installation:
config:
content:
read:
objects:
contacts:
objectName: contacts
schedule: '*/30 * * * *'
destination: contactsWebhook
selectedFields:
email: true
phone: true
required: true
responses:
200:
description: The updated installation.
content:
application/json:
schema:
$ref: '#/components/schemas/Installation'
400:
description: Invalid input (e.g. unrecognized update mask path, missing value for a mask, or malformed request body).
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
x-codegen-request-body-name: installationUpdate
/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content:
patch:
summary: Ampersand Update an Installation Object
description: 'Updates a single object''s configuration within an installation using JSON Patch syntax.
'
operationId: patchObjectConfigContent
tags:
- Installation
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: integrationId
in: path
required: true
description: The integration ID.
schema:
type: string
- name: objectName
in: path
required: true
description: 'The object name whose config content will be patched.
Must match an object name defined in the integration''s manifest for the specified action type (read, subscribe, or write).
Common examples include: `account`, `contact`, `lead`, `opportunity` (for Salesforce), `deal`, `company` (for HubSpot), etc.
'
schema:
type: string
example: account
requestBody:
content:
application/json:
schema:
allOf:
- oneOf:
- type: object
required:
- groupRef
- action
- changes
properties:
groupRef:
type: string
description: 'The ID of the user group that has access to this installation.
Either groupRef or installationId must be provided.
'
example: group-123
action:
type: string
enum:
- read
- subscribe
- write
description: The action type for the object config (read, subscribe, or write).
example: read
changes:
type: array
minItems: 1
description: 'Array of JSON Patch operations to apply.
'
items:
$ref: '#/components/schemas/JSONPatchOperation'
example:
- op: replace
path: /schedule
value: '*/10 * * * *'
- op: add
path: /selectedFields/phone
value: true
- op: remove
path: /selectedFields/billingcity
- type: object
required:
- installationId
- action
- changes
properties:
installationId:
type: string
description: 'The installation ID.
Either groupRef or installationId must be provided.
'
example: installation-123
action:
type: string
enum:
- read
- subscribe
- write
description: The action type for the object config (read, subscribe, or write).
example: read
changes:
type: array
minItems: 1
description: 'Array of JSON Patch operations to apply.
'
items:
$ref: '#/components/schemas/JSONPatchOperation'
example:
- op: replace
path: /schedule
value: '*/10 * * * *'
- op: add
path: /selectedFields/phone
value: true
- op: remove
path: /selectedFields/billingcity
required: true
responses:
200:
description: The updated installation
content:
application/json:
schema:
$ref: '#/components/schemas/Installation'
400:
description: Bad Request
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
404:
description: Installation not found
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/InputValidationProblem
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
x-codegen-request-body-name: patchObjectConfigContent
/projects/{projectIdOrName}/installations:
get:
summary: Ampersand List Installations for a Project
description: '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.
'
operationId: listInstallationsForProject
tags:
- Installation
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: groupRef
in: query
description: The ID that your app uses to identify a group of users (e.g. an org ID, workspace ID, or team ID). When provided, only returns installations belonging to this group.
example: group-123
schema:
type: string
responses:
200:
description: List of installations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Installation'
example:
- id: 3f8b2a1e-7c4d-4e9a-b5f6-1d2e3a4b5c6d
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
integrationId: 550e8400-e29b-41d4-a716-446655440000
group:
groupRef: org_12345
groupName: Acme Corp
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
healthStatus: healthy
connection:
id: 9d8c7b6a-5e4f-3a2b-1c0d-ef9876543210
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
provider: salesforce
group:
groupRef: org_12345
groupName: Acme Corp
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
consumer:
consumerRef: user_67890
consumerName: Jane Smith
projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
createTime: '2024-01-15T10:30:00.000000Z'
createTime: '2024-01-15T10:30:00.000000Z'
authScheme: oauth2/authorizationCode
status: working
createTime: '2024-01-15T10:30:00.000000Z'
createdBy: consumer:user_67890
config:
id: e4d3c2b1-a098-7654-3210-fedcba987654
revisionId: f0e1d2c3-b4a5-6789-0abc-def123456789
createTime: '2024-01-15T10:30:00.000000Z'
createdBy: consumer:user_67890
content:
provider: salesforce
read:
objects:
account:
objectName: account
schedule: '*/15 * * * *'
destination: accountWebhook
selectedFields:
name: true
industry: true
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
components:
schemas:
Consumer:
title: Consumer
required:
- consumerName
- consumerRef
- createTime
- projectId
type: object
properties:
consumerRef:
type: string
description: The consumer reference.
example: consumer-123
consumerName:
type: string
description: The name of the consumer.
example: Super Customer
projectId:
type: string
description: The Ampersand project ID.
example: project-456
createTime:
type: string
description: The time the consumer was created.
format: date-time
example: 2023-07-13 21:34:44.816354+00:00
updateTime:
type: string
description: The time the consumer was last updated.
format: date-time
example: 2023-07-13 21:34:44.816354+00:00
JSONPatchOperation:
title: JSON Patch Operation
description: 'Represents a single JSON Patch operation (RFC 6902).
Only supports add, remove, and replace operations for config updates.
'
required:
- op
- path
type: object
properties:
op:
type: string
enum:
- add
- remove
- replace
description: 'The operation to perform.
- "add": Adds a new field or replaces an existing one at the specified path
- "remove": Removes the field at the specified path
- "replace": Replaces the value at the specified path
'
example: replace
path:
type: string
description: 'JSON Pointer path to the field to operate on (RFC 6901).
All paths must start with "/" (e.g., "/schedule", "/selectedFields/phone").
'
example: /schedule
value:
description: 'The value to set for add/replace operations.
Not used for remove operations.
'
example: '*/10 * * * *'
ProviderMetadataInfo:
title: Provider Metadata Info
type: object
required:
- value
- source
properties:
value:
type: string
description: The value of the metadata field
example: '1234567890'
source:
type: string
description: The source of the metadata field
enum:
- input
- token
- provider
example: input
displayName:
type: string
description: The human-readable name for the field
example: Account ID
ProviderAppMetadata:
title: Provider App Metadata
type: object
description: Provider-specific configuration that extends the standard OAuth flow.
properties:
authQueryParams:
type: object
description: Additional query parameters to include in the OAuth authorization URL (e.g., optional_scope for HubSpot).
additionalProperties:
type: array
items:
type: string
example:
optional_scope:
- automation.sequences.read
providerParams:
type: object
description: Provider-specific string values keyed by names (e.g., packageInstallURL for Salesforce, gcpProjectId and gcpPubSubTopicName for Gmail).
additionalProperties:
type: string
example:
packageInstallURL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t123456789
gcpProjectId: my-gcp-project
gcpPubSubTopicName: my-topic
Group:
title: Group
required:
- createTime
- groupName
- groupRef
- projectId
type: object
properties:
groupRef:
type: string
description: The ID of the user group that has access to this installation.
example: group-123
groupName:
type: string
description: The name of the user group that has access to this installation.
example: Super Customer
projectId:
type: string
description: The Ampersand project ID.
example: project-456
createTime:
type: string
description: The time the group was created.
format: date-time
example: 2023-07-13 21:34:44.816354+00:00
updateTime:
type: string
description: The tim
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ampersand/refs/heads/main/openapi/ampersand-installation-api-openapi.yml