Skip to main content

​
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.yamlInstall the 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.

​
Top-level structure

The Ampersand manifest starts with a top-level structure that specifies the schema version and a list of integrations: 
specVersion: 1.0.0
integrations:
  - name: integration1
    provider: provider1
    # ... integration 1 configuration
  - name: integration2
    provider: provider2
    # ... integration 2 configuration
FieldTypeRequiredDescription
specVersionStringYesThe version of the manifest specification. Format: MAJOR.MINOR.PATCH. Currently only 1.0.0 is supported.
integrationsArrayYesAn array of integration configurations. 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: 
name: my-integration
displayName: My Integration
provider: salesforce
module: crm  # Optional: for providers with modules
read:
  ...
write:
  ...
proxy:
  ...
subscribe:
  ...
FieldTypeRequiredDescription
nameStringYesA unique identifier for this integration within your manifest. Use lowercase alphanumeric characters, hyphens and underscores only. Maximum length: 64 characters.
displayNameStringNoA human-readable name for this integration. Maximum length: 100 characters.
providerStringYesThe provider/platform for this integration. Must be one of the supported providers (e.g., salesforce, hubspot, intercom). Case-sensitive.
moduleStringNoModule within the provider (e.g., crm for HubSpot CRM). Only applicable for certain providers.
subscribeObjectNoThe subscribe definition. See Subscribe Actions for implementation details.
readObjectNoThe read definition. See Read Actions for implementation details.
writeObjectNoThe write definition. See Write Actions for implementation details.
proxyObjectNoThe proxy definition. See 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:
  objects:
    - objectName: account
      destination: accountWebhook
      inheritFieldsAndMapping: true
      createEvent:
        enabled: always
      updateEvent:
        enabled: always
        watchFieldsAuto: all  # Alternatively, use requiredWatchFields
      deleteEvent:
        enabled: always
FieldTypeRequiredDescription
objectsArrayYesAn array of objects to subscribe to. Each element defines a specific object type to receive events for.
Subscribe considerations
  • Check the specific provider guide 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.
  • You must also have a read action specified for the object you wish to subscribe to.
  • Only one of requiredWatchFields or watchFieldsAuto should be provided for update events.
  • See Subscribe Actions documentation 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, subscribes to events, or uses proxy, you can omit this section. Learn more in Read Actions. 
read:
  objects:
    - objectName: contact
      destination: defaultWebhook
      schedule: "*/30 * * * *"
      requiredFields:
        - fieldName: firstname
        - fieldName: lastname
      optionalFields:
        - fieldName: phone
      backfill:
        defaultPeriod:
          fullHistory: true
FieldTypeRequiredDescription
objectsArrayYesAn array of objects to read from the provider. Each element defines a specific object type (e.g., contacts, leads) to read.
Read considerations

​
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:
  objects:
    - objectName: contact
      inheritMapping: true
FieldTypeRequiredDescription
objectsArrayYesAn array of objects to write 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 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 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:
  enabled: true
FieldTypeRequiredDescription
enabledBooleanNoWhether 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:
FieldTypeRequiredDescription
objectNameStringYesThe name of the object to read (e.g., contact, lead, account). This must match an object type supported by the provider’s API (see note below). Case-sensitive.
destinationStringYesThe webhook 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 for setup.
scheduleStringYesA cron 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).
enabledStringNoIf set to always, the integration automatically installs upon user connection and skips the user field selection step.
backfillObjectNoConfiguration for backfilling historical data. Defines how historical data should be loaded. See backfill behavior for details.
requiredFieldsArrayNoFields that are always read for every customer. These fields will always be included in the data that’s read. See Field Configuration for more details.
optionalFieldsArrayNoOptional fields that can be included. Customers can choose which of these fields to include. See Field Configuration for more details.
optionalFieldsAutoStringNoSet to all to automatically include all available fields. This can be used instead of explicitly listing optional fields.
mapToNameStringNoAn optional name mapping for this object. Used to standardize object names across different providers. See Object and Field Mapping for details.
mapToDisplayNameStringNoAn 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 section.
  • Learn more about Object and Field Mapping.

​
Write object

FieldTypeRequiredDescription
objectNameStringYesThe name of the object to write to. Must match an object type supported by the provider’s API. Case-sensitive.
inheritMappingBooleanNoWhether 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:
FieldTypeRequiredDescription
objectNameStringYesThe name of the object to subscribe to. Must match an object type supported by the provider. Case-sensitive.
destinationStringYesThe webhook 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 for setup.
inheritFieldsAndMappingBooleanYesWhether to inherit field mappings from read configuration. For Salesforce, this must be set to true.
createEventObjectNoConfiguration for create events. See Event Configuration below.
updateEventObjectNoConfiguration for update events. See Event Configuration below.
deleteEventObjectNoConfiguration for delete events. See Event Configuration below.
associationChangeEventObjectNoConfiguration for association change events.
otherEventsArrayNoArray 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 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.

​
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: 
backfill:
  defaultPeriod:
    fullHistory: true
FieldTypeRequiredDescription
defaultPeriodObjectNoThe default time period for backfilling.
defaultPeriod.fullHistoryBooleanNoWhether to backfill the full history (true) or just recent data (false). Default: false.
defaultPeriod.daysNumberNoThe 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 for detailed implementation guidance.

​
Field

In 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 and Dynamic Field Mappings.
Simple Field Reference For straightforward field access where you directly reference a provider’s field without renaming it: 
- 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. 
# 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 for implementation details.
FieldTypeRequiredDescription
fieldNameStringYes*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.
mapToNameStringNo*An optional name mapping for this field. Used to standardize field names across different providers.
mapToDisplayNameStringNo*An optional display name mapping for this field. Used for UI display.
promptStringNo*An optional prompt to show when configuring this field. Helps users understand what the field is for.
defaultStringNoAn 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: 
    - fieldName: email
- fieldName: firstname
- fieldName: lastname
  2. Standardized Field Names: Use fieldName with mapToName to standardize field names: 
    - 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: 
    - 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: 
    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.

​
Subscribe action events

In Subscribe Actions, each event type can be configured with specific options: Create event The createEvent definition specifies how to handle create events: 
createEvent:
  enabled: always
FieldTypeRequiredDescription
enabledStringYesWhether to enable create events. Currently, only always is supported.
Update event The updateEvent definition specifies how to handle update events: 
updateEvent:
  enabled: always
  watchFieldsAuto: all  # Options: "all" or "selected"
Or alternatively: 
updateEvent:
  enabled: always
  requiredWatchFields:  # Watch specific fields
    - name
    - email
    - phone
FieldTypeRequiredDescription
enabledStringYesWhether to enable update events. Currently, only always is supported.
watchFieldsAutoStringNo*all watches all fields for changes. selected watches only user-selected fields when inheritFieldsAndMapping is true.
requiredWatchFieldsArrayNo*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: 
deleteEvent:
  enabled: always
FieldTypeRequiredDescription
enabledStringYesWhether to enable delete events. Currently, only always is supported.
Association change event The associationChangeEvent definition specifies how to handle association change events: 
associationChangeEvent:
  enabled: always
  includeFullRecords: true
FieldTypeRequiredDescription
enabledStringYesWhether to enable association change events. Currently, only always is supported.
includeFullRecordsBooleanNoWhether 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: 
otherEvents:
  - object.merged
  - object.restored
Combine subscribe actions with read actions to get a complete picture of your customers’ data: