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

​
Share mappings with read actions

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 roadmap

The ability to programmatically create custom objects when a user installs your integration.

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

​
Advanced use cases

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

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

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

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.

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