Write Actions

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

The top-level keys of a write action are:

  • type: must be write
  • A list of standard objects and custom objects to write.
  actions:
    - type: write
      standardObjects:
        ...
      customObjects:
        ...

Write to standard objects

You can use Ampersand to write to any Salesforce standard object or Hubspot standard object.

You will specify:

  • objectName: to indicate which standard object. This should match the name of the object in the official Salesforce and Hubspot documentation, converted to camel case. For example, if you'd like to read Salesforce Contract Line Items, which Salesforce identifies as ContractLineItem, write contractLineItem as the object name. Likewise, if you'd like to read Hubspot Line Items, which Hubspot identifies as line-item, write lineItem as the object name.
  • mode: the type of write, which can be:
    • insert: create a new instance of an object (e.g. create a new Contact in Salesforce)
    • update: update an existing instance of an object (e.g. update the email address of a Contact in Salesforce)
  • endpoint: the endpoint that Ampersand should expose for you to make requests to when you want to make a write. See Defining and using API endpoints
  • schedule (optional): for writes that can be batched together, provide a schedule for when the batched writes should happen. If this value is missing, then all writes will happen immediately when you make an API request to Ampersand. For most cases, batched writes are recommended in order to reduce the impact of your integration on your customers CRM API quotas. We support 2 formats for defining a schedule:
    • cron syntax
    • A simplified 3-word schedule syntax in the format of "every [integer] [minutes/hours/days]" (e.g. "every 2 hours", "every 1 days"). Please note that the last word is always plural.
  • customFields (optional): any custom fields you want to create.
      standardObjects:
        - objectName: lineItem
          mode: insert
          endpoint: write-line-item
          schedule: every 1 hours
          customFields:
          ...

Write to custom objects

Ampersand can help you create new custom objects inside your customer's CRM, and write to them. When a user installs your integration, Ampersand will create the new custom object in their CRM.

You will specify:

  • objectName: the name of the custom object to create, it can only contain letters and dashes.
  • mode: same as for standard objects.
  • endpoint: same as for standard objects.
  • schedule (optional): same as for standard objects.
  • displayName: the user-friendly display name of the custom object to create. This name will also show up in the user's CRM.
  • prompt (optional): additional context you'd like to provide to your user about why your app is creating this new custom object. This should be a full sentence.
  • customFields: fields of the new custom object.
      customObjects:
        - objectName: mailMonkeyCampaigns
          mode: insert
          endpoint: record-campaigns
          schedule: every 2 hours
          displayName: MailMonkey Campaigns
          prompt: When you create campaigns in MailMonkey, we will sync it to your Hubspot.
          customFields:
          ...

Write to custom fields

Ampersand can help you create new custom fields inside your customer's CRM, and write to them. These custom fields can be a part of custom objects you create, or standard objects you write to. For example, if your app helps generate a "warmth score" for leads and you want to sync this score back to your customer's CRM, you can can specify a custom field in the Contact standard object. When a user installs your integration, Ampersand will create the new custom field in their CRM. Currently, only string type fields are supported.

You will specify:

  • fieldName: the name of the custom field to create, it can only contain letters and dashes.
  • displayName: the user-friendly display name of the custom field to create. This name will also show up in the user's CRM.
  • prompt (optional): additional context you'd like to provide to your user about why your app is creating this new custom field. This should be a full sentence.
      standardObjects:
        - objectName: contact
          ...
          customFields:
          - fieldName: warmthScore
            displayName: Warmth Score
            prompt: This is the warmth score we calculated for this contact.
      customObjects:
        - objectName: mailMonkeyCampaigns
          ...
          customFields:
          - fieldName: campaignName
            displayName: Campaign Name
          ...

Defining and using API endpoints

Once your users install an integration with a write action, your app can write data to their CRM by making an API call to Ampersand.

When you deploy your amp.yaml, we'll expose endpoints for each of the objects in your write actions in the format of:

<ampersand_root_url>/<endpoint_value_you_defined_in_config>

The Ampersand root URL is https://store.withampersand.com/projects/ followed by your Ampersand project ID.

To request a write, make a POST request to an endpoint.

If you specified insert mode in amp.yaml, the request body must have the following:

  • groupId (string): the ID of the group whose CRM you are writing to.
  • fields (object): values of all the fields for the new item

If you specified update mode in amp.yaml, the request body must have the following:

  • groupId (string): the ID of the group whose CRM you are writing to.
  • primaryKey (string): the primary key of the item to update.
  • fields (object): values for the fields that you'd like to update

Example write action and API calls

 integrations: 
  - name: writeToSalesforce
    displayName: Write Data to Salesforce
    api: salesforce
    actions:
    - type: write
    
      standardObjects:
        # Create accounts
        - objectName: account
          mode: insert
          endpoint: create-account
        # Update contacts with custom field
        - objectName: contact
          mode: update
          endpoint: add-warmth-score
          customFields:
          - fieldName: warmthScore
            displayName: Warmth Score
            prompt: This is the warmth score we calculate for each contact.
     
       customObjects:
        # Create campaigns (custom object)
        - objectName: mailMonkeyCampaigns
          mode: insert
          endpoint: create-campaign
          prompt: When you create campaigns in MailMonkey, we will sync it to your Salesforce.
          customFields:
          - fieldName: campaignName
            displayName: Campaign Name
          - fieldName: campaignDescription
            displayName: Campaign Description

This will produce the following embeddable UI:

To create new Accounts, make the following request:

POST https://store.withampersand.com/projects/<project-id>/create-account

Request body: 
{
  groupId: "xye23r3df",
  fields: {
    name: "Big Co.",
  	numberOfEmployees: 10000
  }
}

To update Contacts with the custom field Warmth Score, make the following request:

POST https://store.withampersand.com/projects/<project-id>/add-warmth-score

Request body: 
{
  groupId: "xye23r3df",
  primaryKey: "wsl3k2dk",
  fields: {
    warmthScore: "ready-for-close"
  }
}

To create new MailMonkey Campaigns (which is a custom object), make the following request:

POST https://store.withampersand.com/projects/<project-id>/create-campaign

Request body: 
{
  groupId: "xye23r3df",
  fields: {
    campaignName: "New Feature Announcement",
  	campaignDescription: "Update customers on newest features"
  }
}

Updated 7 months ago