Create a new installation

Authorizations

X-Api-Key

string

header

required

Path Parameters

projectIdOrName

string

required

The Ampersand project ID or project name.

integrationId

string

required

The integration ID.

Body

application/json

groupRef

string

required

The ID of the user group that has access to this installation.

Example:

"group-123"

config

object

required

The config of the installation.

Show child attributes

config.content

Config Content · object

required

Show child attributes

config.content.provider

string

required

The SaaS API that we are integrating with.

Example:

"hubspot"

config.content.read

Read Config · object

Show child attributes

config.content.read.objects

object

required

This is a map of object names to their configuration. This is a map of object names to their configuration.

Show child attributes

config.content.read.objects.{key}

Read Config Object · object

Show child attributes

config.content.read.objects.{key}.objectName

string

required

The name of the object to read from. The name of the object to read from. The name of the object to read from.

Example:

"account"

config.content.read.objects.{key}.selectedFields

object

required

This is a map of field names to booleans indicating whether they should be read. If a field is already included in selectedFieldMappings, it does not need to be included here. This is a map of field names to booleans indicating whether they should be read. If a field is already included in selectedFieldMappings, it does not need to be included here. This is a map of field names to booleans indicating whether they should be read. If a field is already included in selectedFieldMappings, it does not need to be included here.

Show child attributes

config.content.read.objects.{key}.selectedFields.{key}

boolean

Example:

"{ phone: true, fax: true }"

config.content.read.objects.{key}.selectedFieldMappings

object

required

This is a map of mapToNames to field names. (A mapTo name is the name the builder wants to map a field to when it lands in their destination.) This is a map of mapToNames to field names. (A mapTo name is the name the builder wants to map a field to when it lands in their destination.) This is a map of mapToNames to field names. (A mapTo name is the name the builder wants to map a field to when it lands in their destination.)

Show child attributes

config.content.read.objects.{key}.selectedFieldMappings.{key}

string

Example:

"{ phoneNumber: phone, faxNumber: fax }"

config.content.read.objects.{key}.schedule

string

The schedule for reading the object, in cron syntax. The schedule for reading the object, in cron syntax. The schedule for reading the object, in cron syntax.

Example:

"*/15 * * * *"

config.content.read.objects.{key}.disabled

boolean

default:false

If this flag is set to true, scheduled reads associated with this object will be paused, and on-demand reads will not be allowed. If this flag is set to true, scheduled reads associated with this object will be paused, and on-demand reads will not be allowed. If this flag is set to true, scheduled reads associated with this object will be paused, and on-demand reads will not be allowed.

config.content.read.objects.{key}.destination

string

The name of the destination that the result should be sent to. The name of the destination that the result should be sent to. The name of the destination that the result should be sent to.

Example:

"accountWebhook"

config.content.read.objects.{key}.selectedValueMappings

object

This is a map of field names to their value mappings. This is a map of field names to their value mappings. This is a map of field names to their value mappings.

Show child attributes

config.content.read.objects.{key}.selectedValueMappings.{key}

Selected Value Mappings · object

This is a map of values to their mappings. The key is the value delivered to the webhook, the value is the value coming from the provider API. This is a map of values to their mappings. The key is the value delivered to the webhook, the value is the value coming from the provider API. This is a map of values to their mappings. The key is the value delivered to the webhook, the value is the value coming from the provider API.

Show child attributes

config.content.read.objects.{key}.selectedValueMappings.{key}.{key}

string

Example:

{
  "open": "scheduled",
  "closedWon": "won",
  "closedLost": "lost"
}

Example:

{
  "stage": {
    "open": "scheduled",
    "closedWon": "won",
    "closedLost": "lost"
  }
}

config.content.read.objects.{key}.dynamicMappingsInput

Field Mapping Entry · object[]

An array containing all available dynamic field and value mappings for this installation, provided by the InstallIntegration component. This array represents the complete set of possible mappings, regardless of which ones are currently selected. The actual selected mappings are stored separately in the selectedFieldMappings property. An array containing all available dynamic field and value mappings for this installation, provided by the InstallIntegration component. This array represents the complete set of possible mappings, regardless of which ones are currently selected. The actual selected mappings are stored separately in the selectedFieldMappings property. An array containing all available dynamic field and value mappings for this installation, provided by the InstallIntegration component. This array represents the complete set of possible mappings, regardless of which ones are currently selected. The actual selected mappings are stored separately in the selectedFieldMappings property.

Show child attributes

config.content.read.objects.{key}.dynamicMappingsInput.mapToName

string

required

The name of the field in your application. The name of the field in your application. The name of the field in your application.

config.content.read.objects.{key}.dynamicMappingsInput.mapToDisplayName

string

Optional display name of the field to show the user in the mapping UI. Optional display name of the field to show the user in the mapping UI. Optional display name of the field to show the user in the mapping UI.

config.content.read.objects.{key}.dynamicMappingsInput.prompt

string

Optional prompt to show the user in the mapping UI. Optional prompt to show the user in the mapping UI. Optional prompt to show the user in the mapping UI.

config.content.read.objects.{key}.dynamicMappingsInput.mappedValues

Mapped Value · object[]

If you would like the user to map a set of possible values, this is the list of possible values of the field in your application. If you would like the user to map a set of possible values, this is the list of possible values of the field in your application. If you would like the user to map a set of possible values, this is the list of possible values of the field in your application.

Show child attributes

config.content.read.objects.{key}.dynamicMappingsInput.mappedValues.mappedValue

string

required

config.content.read.objects.{key}.dynamicMappingsInput.mappedValues.mappedDisplayValue

string

required

config.content.read.objects.{key}.dynamicMappingsInput.fieldName

string

The name of the field in SaaS provider, if present, then we will not prompt the user to map the field. The name of the field in SaaS provider, if present, then we will not prompt the user to map the field. The name of the field in SaaS provider, if present, then we will not prompt the user to map the field.

config.content.read.objects.{key}.selectedFieldsAuto

enum<string>

If selectedFieldsAuto is set to all, all fields will be read. If selectedFieldsAuto is set to all, all fields will be read. If selectedFieldsAuto is set to all, all fields will be read.

Available options:

all

config.content.read.objects.{key}.backfill

Backfill Config · object

Show child attributes

config.content.read.objects.{key}.backfill.defaultPeriod

Default Period Config · object

required

Show child attributes

config.content.read.objects.{key}.backfill.defaultPeriod.days

integer

Number of days in past to backfill from. 0 is no backfill. e.g) if 10, then backfill last 10 days of data. Required if fullHistory is not set. Number of days in past to backfill from. 0 is no backfill. e.g) if 10, then backfill last 10 days of data. Required if fullHistory is not set. Number of days in past to backfill from. 0 is no backfill. e.g) if 10, then backfill last 10 days of data. Required if fullHistory is not set.

Required range: x >= 0

Example:

30

config.content.read.objects.{key}.backfill.defaultPeriod.fullHistory

boolean

If true, backfill all history. Required if days is not set. If true, backfill all history. Required if days is not set. If true, backfill all history. Required if days is not set.

Example:

false

config.content.write

Write Config · object

Show child attributes

config.content.write.objects

object

This is a map of object names to their configuration. This is a map of object names to their configuration.

Show child attributes

config.content.write.objects.{key}

Write Config Object · object

Show child attributes

config.content.write.objects.{key}.objectName

string

required

The name of the object to write to. The name of the object to write to. The name of the object to write to.

Example:

"account"

config.content.write.objects.{key}.selectedValueDefaults

object

deprecated

This is a map of field names to default values. These values will be used when writing to the object. This is a map of field names to default values. These values will be used when writing to the object. This is a map of field names to default values. These values will be used when writing to the object.

Show child attributes

config.content.write.objects.{key}.selectedValueDefaults.{key}

Value Default String · object

deprecated

Value Default String
Value Default Integer
Value Default Boolean

Show child attributes

config.content.write.objects.{key}.selectedValueDefaults.{key}.value

string

required

The value to be used as a default. The value to be used as a default. The value to be used as a default.

config.content.write.objects.{key}.selectedValueDefaults.{key}.applyOnUpdate

enum<string>

Whether the default value should be applied when updating a record. If set to always, the default value will be applied when updating a record. If set to never, the default value will not be applied when updating a record, only when creating a record. If unspecified, then always is assumed.

Available options:

always,

never

config.content.write.objects.{key}.selectedFieldSettings

object

This is a map of field names to their settings. This is a map of field names to their settings. This is a map of field names to their settings.

Show child attributes

config.content.write.objects.{key}.selectedFieldSettings.{key}

Field setting · object

Show child attributes

config.content.write.objects.{key}.selectedFieldSettings.{key}.default

Default value for a field · object

Only use one of stringValue, integerValue, booleanValue. Only use one of stringValue, integerValue, booleanValue. Only use one of stringValue, integerValue, booleanValue.

Show child attributes

config.content.write.objects.{key}.selectedFieldSettings.{key}.default.stringValue

string

The default string value to apply to a field The default string value to apply to a field The default string value to apply to a field

config.content.write.objects.{key}.selectedFieldSettings.{key}.default.integerValue

integer

The default integer value to apply to a field The default integer value to apply to a field The default integer value to apply to a field

config.content.write.objects.{key}.selectedFieldSettings.{key}.default.booleanValue

boolean

The default boolean value to apply to a field The default boolean value to apply to a field The default boolean value to apply to a field

config.content.write.objects.{key}.selectedFieldSettings.{key}.writeOnCreate

enum<string>

default:always

Whether the default value should be applied when creating a record. Whether the default value should be applied when creating a record. Whether the default value should be applied when creating a record.

Available options:

always,

never

config.content.write.objects.{key}.selectedFieldSettings.{key}.writeOnUpdate

enum<string>

default:always

Whether the default value should be applied when updating a record. Whether the default value should be applied when updating a record. Whether the default value should be applied when updating a record.

Available options:

always,

never

config.content.proxy

Base Proxy Config · object

Show child attributes

config.content.proxy.enabled

boolean

Show child attributes

Whether to inherit fields and mappings from the read config. Whether to inherit fields and mappings from the read config.

Example:

true

The name of the object to subscribe to. The name of the object to subscribe to.

Example:

"account"

The name of the destination that the result should be sent to. The name of the destination that the result should be sent to.

Example:

"accountWebhook"

Show child attributes

Conditions to enable create events. Conditions to enable create events.

Available options:

always,

never

Show child attributes

Conditions to enable update events. Conditions to enable update events.

Available options:

always,

never

Example:

"always"

Whether to watch fields all fields automatically. Whether to watch fields all fields automatically.

Available options:

all

Example:

"all"

The fields that should be watched. The fields that should be watched.

Example:

["name", "description"]

Show child attributes

Conditions to enable delete events. Conditions to enable delete events.

Available options:

always,

never

Example:

"always"

config.revisionId

string

deprecated

Deprecated: This field will be automatically set to the latest revision.

config.createdBy

string

default:api:create-installation

The person who created the config, in the format of "consumer:{consumer-id}" or "builder:{builder-id}".

connectionId

string

The ID of the SaaS connection tied to this installation. If omitted the default connection for this group will be used.

Response

Created

string

required

The installation ID.

projectId

string

required

The Ampersand project ID.

Example:

"project-456"

integrationId

string

required

The integration ID.

healthStatus

string

required

The health status of the installation ("healthy", "unhealthy").

Example:

"healthy"

connection

Connection · object

required

Show child attributes

connection.id

string

required

The connection ID.

Example:

"connection-123"

connection.projectId

string

required

The Ampersand project ID.

Example:

"project-456"

connection.provider

string

required

The SaaS provider that this Connection is for.

Example:

"salesforce"

connection.group

Group · object

required

Show child attributes

connection.group.groupRef

string

required

The ID of the user group that has access to this installation.

Example:

"group-123"

connection.group.groupName

string

required

The name of the user group that has access to this installation.

Example:

"Super Customer"

connection.group.projectId

string

required

The Ampersand project ID.

Example:

"project-456"

connection.group.createTime

string<date-time>

required

The time the group was created.

Example:

"2023-07-13T21:34:44.816354Z"

connection.group.updateTime

string<date-time>

The time the group was last updated.

Example:

"2023-07-13T21:34:44.816354Z"

connection.consumer

Consumer · object

required

Show child attributes

connection.consumer.consumerRef

string

required

The consumer reference.

Example:

"consumer-123"

connection.consumer.consumerName

string

required

The name of the consumer.

Example:

"Super Customer"

connection.consumer.projectId

string

required

The Ampersand project ID.

Example:

"project-456"

connection.consumer.createTime

string<date-time>

required

The time the consumer was created.

Example:

"2023-07-13T21:34:44.816354Z"

connection.consumer.updateTime

string<date-time>

The time the consumer was last updated.

Example:

"2023-07-13T21:34:44.816354Z"

connection.createTime

string<date-time>

required

The time the connection was created.

Example:

"2023-07-13T21:34:44.816354Z"

connection.authScheme

enum<string>

required

The authentication scheme used for this connection.

Available options:

none,

apiKey,

basic,

oauth2/authorizationCode,

oauth2/authorizationCodePKCE,

oauth2/clientCredentials,

oauth2/password

Example:

"oauth2/authorizationCode"

connection.status

enum<string>

required

The status of the connection.

created: The connection has just been created or the access token was just refreshed.
working: The connection has successfully been used to make a request.
bad_credentials: The connection encountered credential-related issues when making a request, or when attempting to refresh the access token.

Available options:

created,

working,

bad_credentials

Example:

"working"

connection.providerApp

Provider App · object

Show child attributes

connection.providerApp.id

string

required

The provider app ID.

Example:

"provider-app-123"

connection.providerApp.projectId

string

required

The Ampersand project ID.

Example:

"project-456"

connection.providerApp.provider

string

required

The SaaS provider that this app connects to.

Example:

"salesforce"

connection.providerApp.clientId

string

required

The OAuth client ID for this app.

Example:

"client-id-123"

connection.providerApp.createTime

string<date-time>

required

The time the provider app was created.

connection.providerApp.externalRef

string

The ID used by the provider to identify the app (optional).

Example:

"external-id-123"

connection.providerApp.scopes

string[]

The OAuth scopes for this app.

connection.providerApp.updateTime

string<date-time>

The time the provider app was updated.

connection.providerWorkspaceRef

string

If available, the identifier for the provider workspace (e.g. the Salesforce subdomain)

Example:

"provider-workspace-123"

connection.providerConsumerRef

string

If available, the ID that Salesforce/Hubspot uses to identify this user (e.g. Salesforce has IDs in the form of https://login.salesforce.com/id/00D4x0000019CQTEA2/0054x000000orJ4AA)

Example:

"provider-consumer-123"

connection.updateTime

string<date-time>

The time the connection was last updated.

Example:

"2023-07-13T21:34:44.816354Z"

connection.oauth2AuthorizationCode

OAuth2 AuthorizationCode Token · object

Show child attributes

connection.oauth2AuthorizationCode.accessToken

object

The access token for the connection.

Show child attributes

connection.oauth2AuthorizationCode.accessToken.token

string

required

connection.oauth2AuthorizationCode.accessToken.issuedAt

string<date-time>

Example:

"2024-04-22T18:55:28.456076Z"

connection.oauth2AuthorizationCode.accessToken.expiresAt

string<date-time>

Example:

"2024-10-22T18:55:28.456076Z"

connection.oauth2AuthorizationCode.refreshToken

object

The refresh token to use for the connection.

Show child attributes

connection.oauth2AuthorizationCode.refreshToken.token

string

required

connection.oauth2AuthorizationCode.refreshToken.issuedAt

string<date-time>

Example:

"2024-04-22T18:55:28.456076Z"

connection.oauth2AuthorizationCode.refreshToken.expiresAt

string<date-time>

Example:

"2024-10-22T18:55:28.456076Z"

connection.oauth2AuthorizationCode.scopes

string[]

The scopes for the tokens.

connection.apiKey

string

The API key used while making the connection.

Example:

"api-key-123"

connection.providerMetadata

Provider Metadata · object

Show child attributes

connection.providerMetadata.{key}

Provider Metadata Info · object

Show child attributes

connection.providerMetadata.{key}.value

string

required

The value of the metadata field

Example:

"1234567890"

connection.providerMetadata.{key}.source

enum<string>

required

The source of the metadata field

Available options:

input,

token,

provider

Example:

"input"

connection.providerMetadata.{key}.displayName

string

The human-readable name for the field

Example:

"Account ID"

createTime

string<date-time>

required

The time the integration was first installed.

createdBy

string

required

The person who did the installation, in the format of "consumer:{consumer-id}".

Example:

"consumer:consumer-123"

config

Config · object

required

Show child attributes

config.id

string

required

The config ID.

Example:

"config-123"

config.revisionId

string

required

The ID of the revision that this config is based on.

Example:

"revision-123"

config.createTime

string<date-time>

required

The time the config was created.

config.createdBy

string

required

The person who created the config, in the format of "consumer:{consumer-id}" or "builder:{builder-id}".

Example:

"builder:builder-123"

config.content

Config Content · object

required

Show child attributes

config.content.provider

string

required

The SaaS API that we are integrating with.

Example:

"hubspot"

config.content.read

Read Config · object

Show child attributes

config.content.read.objects

object

required

This is a map of object names to their configuration. This is a map of object names to their configuration.

Show child attributes

config.content.read.objects.{key}

Read Config Object · object

Show child attributes

config.content.read.objects.{key}.objectName

string

required

The name of the object to read from. The name of the object to read from. The name of the object to read from.

Example:

"account"

config.content.read.objects.{key}.selectedFields

object

required

Show child attributes

config.content.read.objects.{key}.selectedFields.{key}

boolean

Example:

"{ phone: true, fax: true }"

config.content.read.objects.{key}.selectedFieldMappings

object

required

Show child attributes

config.content.read.objects.{key}.selectedFieldMappings.{key}

string

Example:

"{ phoneNumber: phone, faxNumber: fax }"

config.content.read.objects.{key}.schedule

string

The schedule for reading the object, in cron syntax. The schedule for reading the object, in cron syntax. The schedule for reading the object, in cron syntax.

Example:

"*/15 * * * *"

config.content.read.objects.{key}.disabled

boolean

default:false

config.content.read.objects.{key}.destination

string

The name of the destination that the result should be sent to. The name of the destination that the result should be sent to. The name of the destination that the result should be sent to.

Example:

"accountWebhook"

config.content.read.objects.{key}.selectedValueMappings

object

This is a map of field names to their value mappings. This is a map of field names to their value mappings. This is a map of field names to their value mappings.

Show child attributes

config.content.read.objects.{key}.selectedValueMappings.{key}

Selected Value Mappings · object

Show child attributes

config.content.read.objects.{key}.selectedValueMappings.{key}.{key}

string

Example:

{
  "open": "scheduled",
  "closedWon": "won",
  "closedLost": "lost"
}

Example:

{
  "stage": {
    "open": "scheduled",
    "closedWon": "won",
    "closedLost": "lost"
  }
}

config.content.read.objects.{key}.dynamicMappingsInput

Field Mapping Entry · object[]

Show child attributes

config.content.read.objects.{key}.dynamicMappingsInput.mapToName

string

required

The name of the field in your application. The name of the field in your application. The name of the field in your application.

config.content.read.objects.{key}.dynamicMappingsInput.mapToDisplayName

string

config.content.read.objects.{key}.dynamicMappingsInput.prompt

string

Optional prompt to show the user in the mapping UI. Optional prompt to show the user in the mapping UI. Optional prompt to show the user in the mapping UI.

config.content.read.objects.{key}.dynamicMappingsInput.mappedValues

Mapped Value · object[]

Show child attributes

config.content.read.objects.{key}.dynamicMappingsInput.mappedValues.mappedValue

string

required

config.content.read.objects.{key}.dynamicMappingsInput.mappedValues.mappedDisplayValue

string

required

config.content.read.objects.{key}.dynamicMappingsInput.fieldName

string

config.content.read.objects.{key}.selectedFieldsAuto

enum<string>

If selectedFieldsAuto is set to all, all fields will be read. If selectedFieldsAuto is set to all, all fields will be read. If selectedFieldsAuto is set to all, all fields will be read.

Available options:

all

config.content.read.objects.{key}.backfill

Backfill Config · object

Show child attributes

config.content.read.objects.{key}.backfill.defaultPeriod

Default Period Config · object

required

Show child attributes

config.content.read.objects.{key}.backfill.defaultPeriod.days

integer

Required range: x >= 0

Example:

30

config.content.read.objects.{key}.backfill.defaultPeriod.fullHistory

boolean

If true, backfill all history. Required if days is not set. If true, backfill all history. Required if days is not set. If true, backfill all history. Required if days is not set.

Example:

false

config.content.write

Write Config · object

Show child attributes

config.content.write.objects

object

This is a map of object names to their configuration. This is a map of object names to their configuration.

Show child attributes

config.content.write.objects.{key}

Write Config Object · object

Show child attributes

config.content.write.objects.{key}.objectName

string

required

The name of the object to write to. The name of the object to write to. The name of the object to write to.

Example:

"account"

config.content.write.objects.{key}.selectedValueDefaults

object

deprecated

Show child attributes

config.content.write.objects.{key}.selectedValueDefaults.{key}

Value Default String · object

deprecated

Value Default String
Value Default Integer
Value Default Boolean

Show child attributes

config.content.write.objects.{key}.selectedValueDefaults.{key}.value

string

required

The value to be used as a default. The value to be used as a default. The value to be used as a default.

config.content.write.objects.{key}.selectedValueDefaults.{key}.applyOnUpdate

enum<string>

Available options:

always,

never

config.content.write.objects.{key}.selectedFieldSettings

object

This is a map of field names to their settings. This is a map of field names to their settings. This is a map of field names to their settings.

Show child attributes

config.content.write.objects.{key}.selectedFieldSettings.{key}

Field setting · object

Show child attributes

config.content.write.objects.{key}.selectedFieldSettings.{key}.default

Default value for a field · object

Only use one of stringValue, integerValue, booleanValue. Only use one of stringValue, integerValue, booleanValue. Only use one of stringValue, integerValue, booleanValue.

Show child attributes

config.content.write.objects.{key}.selectedFieldSettings.{key}.default.stringValue

string

The default string value to apply to a field The default string value to apply to a field The default string value to apply to a field

config.content.write.objects.{key}.selectedFieldSettings.{key}.default.integerValue

integer

The default integer value to apply to a field The default integer value to apply to a field The default integer value to apply to a field

config.content.write.objects.{key}.selectedFieldSettings.{key}.default.booleanValue

boolean

The default boolean value to apply to a field The default boolean value to apply to a field The default boolean value to apply to a field

config.content.write.objects.{key}.selectedFieldSettings.{key}.writeOnCreate

enum<string>

default:always

Available options:

always,

never

config.content.write.objects.{key}.selectedFieldSettings.{key}.writeOnUpdate

enum<string>

default:always

Available options:

always,

never

config.content.proxy

Base Proxy Config · object

Show child attributes

config.content.proxy.enabled

boolean

Show child attributes

Whether to inherit fields and mappings from the read config. Whether to inherit fields and mappings from the read config.

Example:

true

The name of the object to subscribe to. The name of the object to subscribe to.

Example:

"account"

The name of the destination that the result should be sent to. The name of the destination that the result should be sent to.

Example:

"accountWebhook"

Show child attributes

Conditions to enable create events. Conditions to enable create events.

Available options:

always,

never

Show child attributes

Conditions to enable update events. Conditions to enable update events.

Available options:

always,

never

Example:

"always"

Whether to watch fields all fields automatically. Whether to watch fields all fields automatically.

Available options:

all

Example:

"all"

The fields that should be watched. The fields that should be watched.

Example:

["name", "description"]

Show child attributes

Conditions to enable delete events. Conditions to enable delete events.

Available options:

always,

never

Example:

"always"

group

Group · object

Show child attributes

group.groupRef

string

required

The ID of the user group that has access to this installation.

Example:

"group-123"

group.groupName

string

required

The name of the user group that has access to this installation.

Example:

"Super Customer"

group.projectId

string

required

The Ampersand project ID.

Example:

"project-456"

group.createTime

string<date-time>

required

The time the group was created.

Example:

"2023-07-13T21:34:44.816354Z"

group.updateTime

string<date-time>

The time the group was last updated.

Example:

"2023-07-13T21:34:44.816354Z"

updateTime

string<date-time>

The time the installation was last updated with a new config.

Authentication

WRITE API

READ API

PLATFORM API

Create a new installation

Authorizations

Path Parameters

Body

Response