Read Actions
A read action reads data from your customer's SaaS on a scheduled basis and send them to Destinations that you define. We will keep them in sync with the state of your customer's CRM. For example, if you are reading your customer's Salesforce Contacts and sending them to a Postgres table, we'll ensure that table mirrors the Contacts in your customer's Salesforce even if your customer updates or deletes Contacts.
The top-level keys of a read action are:
- type: must be
read
- schedule: how frequently the read should happen. This value can be:
once
: if you would like to do just a one-time read when the integration is installed. You can combine this with Subscribe Actions in the same integration to be notified of future creates, updates, and deletes.- A schedule in 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.
- A list of standard objects and custom objects to read.
actions:
- type: read
schedule: every 12 hours
standardObjects:
...
customObjects:
...
On the roadmap
The ability for your users to define their own sync schedules.
Read standard objects
You can use Ampersand to read any Salesforce standard object or Hubspot standard object.
You need to specify:
- objectName: to indicate which standard object you'd like to read. 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
, writecontractLineItem
as the object name. Likewise, if you'd like to read Hubspot Line Items, which Hubspot identifies asline-item
, writelineItem
as the object name. - destination: the name of a destination that you've defined in the
destinations
section, see Destinations - a list of fields
standardObjects:
- objectName: lineItem
destination: LineItemTable
...
Standard fields
Standard fields can be either be required or optional. If a field is required, then all users who install this integration will need to give your app read access to that field. If a field is optional, then users can choose whether they'd like your app to read that field. For standard fields, you will specify:
- fieldName: the name of the field from the official Salesforce or Hubspot documentation, converted to camel case. For example, if you'd like to read the first name of a Hubspot contact, write
firstName
. - transform (optional): the name of a file that contains a transformation function which should be applied to this field. See Transformation Functions.
standardObjects:
- objectName: contact
destination: ...
requiredFields:
- fieldName: firstName
- fieldName: lastName
- fieldName: email
optionalFields:
- fieldName: company
transform: capitalizeCompanyName.ts

Embeddable UI produced by the above config
Custom fields
There are 2 types of custom fields you might wish to read from: custom fields that your app has created, and custom fields that the user has created.
Custom fields that your app created
If your app has created custom fields with Write Actions, then you'll know exactly what the fields are called. The syntax for them is exactly like the syntax for a standard field, with fieldName and optional transform.
Custom fields that your user created
If you'd like to read custom fields that your user has created, then you will not know the fields names. You'll need to ask your users during the set up of the integration to map an existing custom field to a concept in your product. If they do not have a custom field like it, they can select "none" and the integration will not read any custom fields.
For these custom fields, you'll specify:
- mapToName: when we deliver the data from this custom field to you, this is the name that we'll use to identify the field.
- mapToDisplayName: the phrasing to display to the user in the set up UI component when asking them to select a custom field (e.g. For the config below, the helper text will say, "Which of your custom fields map to Contact Notes?")
- prompt (optional): additional context that you want to show your user in the set up UI Component about this field. This should be a full sentence.
standardObjects:
- objectName: contact
destination: ...
customFields:
# field that your app created
- fieldName: myAppPriorityScore
# field that your user created
- mapToName: notes
mapToDisplayName: Contact Notes
prompt: These are notes that you would like to surface in our app.
...

Embeddable UI produced by the above config
Read custom objects
There are 2 types of custom objects you might wish to read from: custom objects that your app has created, and custom objects that the user has created.
Custom objects that your app created
If you're reading a custom object that your app has created with Write Actions, then they are specified the same way as standard objects, since you will know the names of the object and all its fields.
customObjects:
- objectName: mailMonkeyCampaigns
destination: ...
requiredFields:
...
optionalFields:
...
Custom objects that your user created
If you are reading custom objects that your user has created, then you'll need to prompt them during the set up of the integration to map an existing custom object to a concept in your data model. If they do not have a custom object like it, they can select "none" and the integration will not read any custom objects.
For these custom objects, you'll specify:
- mapToName: when we deliver the data from this custom object to you, this is the name that we'll use to identify the object.
- destination: just like for a standard object, you'll need to provide the name of a destination that you've defined in the
destinations
section, see Destinations. - mapToDisplayName: the phrasing to display to the user in the set up UI component when asking them to select a custom object (e.g. For the config below, the helper text will say, "Which of your custom objects map to Team?")
- prompt (optional): additional context that you want to show your user in the set up UI Component about this object. This should be a full sentence.
customObjects:
- mapToName: team
destination: TeamTable
mapToDisplayName: Team
prompt: A team is a set of contacts that you might be selling to at the same time.
customFields:
- mapToName: teamName
mapToDisplayName: Team Name

Embeddable UI produced by the above config
Example read action
integrations:
- name: readSalesforce
displayName: Read Data from Salesforce
api: salesforce
actions:
- type: read
schedule: every 2 hours
standardObjects:
- objectName: account
destination: AccountTable
requiredFields:
- fieldName: name
- fieldName: industry
optionalFields:
- fieldName: annualRevenue
- fieldName: website
transform: removeHttpPrefix.ts
- objectName: contact
destination: ContactTable
requiredFields:
- fieldName: firstName
- fieldName: lastName
- fieldName: email
customFields:
- mapToName: pronoun
mapToDisplayName: Pronoun
prompt: We will use this word when addressing this person in emails we send out.
customObjects:
- objectName: mailMonkeyCampaigns
destination: CampaignsTable
requiredFields:
- fieldName: campaignName
fieldName: status
- mapToName: team
destination: TeamTable
mapToDisplayName: Team
prompt: A team is a set of contacts that you might be selling to at the same time.
customFields:
- mapToName: teamName
mapToDisplayName: Team Name
The action above will produce the following set up UI:
Updated 4 months ago