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.
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.
Copy
Ask AI
specVersion: 1.0.0integrations: - 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.
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/:objectNameYou 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 :
Copy
Ask AI
# Get project IDamp list:projects# List integrations for projectamp 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.
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:
Deletion must be enabled for the object in the installation config. See 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 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.
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.
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 but provide a batch array instead of a single record:https://write.withampersand.com/v1/projects/:projectIdOrName/integrations/:integrationId/objects/:objectNameBatch writes support both synchronous and asynchronous modes. Note that batch writes follow an all-or-nothing approach: if any record in the batch fails to write, the entire batch operation fails and no records are written.
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:
Accumulate records: Multiple single-record write requests for the same installation, object, and write type (create or update) are automatically grouped together.
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.
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 request, here’s an example:
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 to check the status:
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.
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.
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 to retry for up to 48 hours.For single-record writes, you can also use the auto batch policy to automatically group multiple requests together and execute them as a batch.To use async mode, set mode: "asynchronous" in your request:
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.
By default, delete operations are disabled. To enable deletion, set deletionSettings.enabled to true for the object when creating or updating an installation.You can use these APIs to set deletionSettings.enabled:
Create Installation
Create Installation API — Include deletionSettings in the write object when creating the installation:
Update Installation Object API — PATCH the object’s config content with a JSON Patch operation. Use this to change only this object without sending the full installation config:
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.
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.
Copy
Ask AI
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 } });}
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:
Copy
Ask AI
{ "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" }, }, } } }, } }}
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:
Copy
Ask AI
{ "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 }, }, }, } } }, } }}
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.
{ "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.
