Write Actions

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

​

Sharing 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

​

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

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

​

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