Write actions - Ampersand

A write action writes data to your customer’s SaaS whenever you make an API request to us.

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.

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

If you are using Read Actions and have already defined 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.

specVersion: 1.0.0
integrations:
  - name: write-to-salesforce
    displayName: Write to Salesforce
    provider: salesforce
    write:
      objects:
        - objectName: account
          inheritMapping: true

On the roadmapThe ability to programmatically create custom objects when a user installs your integration.

Creating custom fields

You can programmatically create or update custom fields in your customer’s SaaS instance using Ampersand’s field management API. This is useful when you need to ensure specific custom fields exist before writing data to them.

When to use field creation

Before installation: Create fields using a connection (during the installation setup process)
After installation: Create fields using an existing installation

How it works

Ampersand provides two endpoints for managing custom fields:

Upsert custom fields for installation - Use this when you already have an installation
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:

Permission Set: Ampersand creates a managed Permission Set named IntegrationCustomFieldVisibility that grants read and edit access to custom fields
Field Permissions: Optional (non-required) custom fields are automatically added to this Permission Set
User Assignment: The Permission Set is automatically assigned to the integration user

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:

Property Group: Ampersand creates a managed property group named integrationcreatedproperties (displayed as “Integration Created Properties”)
Field Organization: All custom fields created through Ampersand are organized under this group for easy management

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 (look in the address bar) or you can run the following in the terminal to get projectId & integrationId :

# Get project ID
amp list:projects

# List integrations for project
amp list:integrations --project <PROJECT_ID>

objectName refers to the objectName key within the amp.yaml file that defines your integration. This must match the name of an object that exists within the SaaS instance.

Create a new record

To create a new record, make a request to the Write endpoint with type being create. For example:

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.

curl --location 'https://write.withampersand.com/v1/projects/<YOUR_PROJECT_ID_OR_NAME>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "<GROUP_REF>",
    "type": "create",
    "record": {
        "firstname": "Harry",
        "lastname": "Potter",
        "email": "harry@hogwarts.com",
        "phone": "123456789"
    },
    "associations": [{
        "to": {"id": "18417469280"},
        "types": [{
            "associationCategory": "HUBSPOT_DEFINED",
            "associationTypeId": 279
        }]
    }]
}'

Update an existing record

To update an existing record, you need to know the ID of the record, which is the ID that the SaaS provider uses to uniquely identify this record. If you created the record using Ampersand, this ID is available in the API response. If you are reading the record first using Ampersand’s Read Actions, make sure you add the ID as a required field in the read action. Here is an example request:

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"
    }
}'

Passing additional headers to providers when creating or updating records

If you need to pass additional headers when creating or updating 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.

curl --location 'https://write.withampersand.com/v1/projects/<YOUR_PROJECT_ID_OR_NAME>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "<GROUP_REF>",
    "type": "create",
    "record": {
        "firstname": "Harry",
        "lastname": "Potter",
        "email": "harry@hogwarts.com",
        "phone": "123456789"
    },
    "headers": [
      {
        "key": "header-key1",
        "value": "header-value1"
      },
      {
        "key": "header-key2",
        "value": "header-value2"
      }
    ]
}'

Advanced use cases

These advanced use cases are currently only supported when creating or updating installations via the API or Headless UI.

Prevent overwriting of customer data

There are certain fields that you may only want to write to when you are creating a record, not when you are updating a record. This helps prevent the scenario where you may accidentally overwrite a field that the customer has manually modified in their SaaS product. You may also have a need for the opposite behavior, where you want to leave a field blank when creating records, but write to that field when updating records.

Using headless UI

You can set overwrite behavior on a customer-by-customer basis when using the function setFieldSettings. Learn more about pre-requisites for headless UI here.

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 when you make a call to the Create Installation API. Here is a sample request body:

{
  "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 current 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.

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. Here is a sample request body:

{
  "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, we can drop unmapped fields from the write request before sending the request to the provider API. Please contact support@withampersand.com if you want to use this preview feature.

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.

Synchronous mode

In synchronous mode, the write operation is processed immediately and the API waits for the operation to complete before returning a response.

curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "synchronous",
    "record": {
        "firstname": "John",
        "lastname": "Doe",
        "email": "john@example.com"
    }
}'

The response includes the created/updated record immediately. If the write operation fails, the API will return the error response.

Asynchronous mode

In asynchronous mode, Ampersand validates the request & immediately returns an operation ID. The write is then processed in the background. 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 to retry for up to 48 hours. To use async mode, set mode: "asynchronous" in your request:

curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "asynchronous",
    "record": {
        "firstname": "Jane",
        "lastname": "Smith",
    }
}'

The response returns an operation ID immediately:

{
    "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 with the operation ID in the response body of the write API endpoint.

curl --location 'https://api.withampersand.com/v1/projects/<PROJECT_ID>/operations/<OPERATION_ID>' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY'

The response includes the operation status and result:

{
    "id": "<OPERATION_ID>",
    "projectId": "<PROJECT_ID>",
    "integrationId": "<INTEGRATION_ID>",
    "installationId": "<INSTALLATION_ID>",
    "configId": "<CONFIG_ID>",
    "actionType": "write",
    "status": "failure",
    "result": "[contacts] Error writing to provider",
    "createTime": "2025-08-26T23:19:27.616204Z",
    "updateTime": "2025-08-26T23:19:28.424859Z",
    "resource": "contacts"
}

An operation can be in a success, failure or in_progress state.

Retry policy for async writes

Ampersand will automatically retry failed operations with exponential backoff until the default deadline of 1 hour. If this is not enough, you can specify a longer deadline of up to 48 hours.

curl --location 'https://write.withampersand.com/v1/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/objects/contact' \
--header 'X-Api-Key: YOUR_AMPERSAND_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "groupRef": "customer-123",
    "type": "create",
    "mode": "asynchronous",
    "retryPolicy": {
        "deadlineHours": 24
    },
    "record": {
        "firstname": "Bob",
        "lastname": "Johnson",
    }
}'

Please note that retry policies only apply to asynchronous mode.

Combine use cases

Here is a full example for a request body to the Create Installation API 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.

Using API

{
  "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.

Getting started

​Defining writes

​Share mappings with read actions

​Creating custom fields

​When to use field creation

​How it works

​Provider-specific behavior

​Salesforce

​HubSpot

​Writing records

​Create a new record

​Create associations when creating a record

​Update an existing record

​Passing additional headers to providers when creating or updating records

​Advanced use cases

​Prevent overwriting of customer data

​Using headless UI

​Using API

​Default values

​Using headless UI

​Using API

​Remove unmapped fields

​Write modes

​Synchronous mode

​Asynchronous mode

​Checking status of an async write operation

​Retry policy for async writes

​Combine use cases

​Using headless UI

​Using API

Defining writes

Share mappings with read actions

Creating custom fields

When to use field creation

How it works

Provider-specific behavior

Salesforce

HubSpot

Writing records

Create a new record

Create associations when creating a record

Update an existing record

Passing additional headers to providers when creating or updating records

Advanced use cases

Prevent overwriting of customer data

Using headless UI

Using API

Default values

Using headless UI

Using API

Remove unmapped fields

Write modes

Synchronous mode

Asynchronous mode

Checking status of an async write operation

Retry policy for async writes

Combine use cases

Using headless UI

Using API