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

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

​
Creating an association while writing 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.

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

Was this page helpful?

Suggest editsRaise issue
Read actionsProxy actions