Bulk Data Import

Amity can import bulk data from comma-separated values (CSV) files.

The CSV files must be uploaded to an Amazon S3 bucket location that is provided by Amity.

Amity supports bulk data import of the following object types:

  • Accounts
  • Activities
  • People (participants)
  • Subscriptions

Getting Started

To get started, ask your Amity Customer Success Manager to provide you with Amazon S3 user credentials.

Once the request has been completed, you will receive a set of credentials like this:

  Example
Access Key ID ARIAJBSSXW4ACRW8PICF
Access Key Secret BIGSECRETTEXT
Client Folder* AIDEOPPCSSWKMLKAANDF
Workspace ID 589b434425dc9a71b466eab0

* Although Amazon S3 doesn't actually support file folders, it does support referencing uploaded resources using a folder-like path mechanism.

The credentials will grant you permission to write a file to your unique S3 location. The credentials will also allow you to list the contents of the folder.

Creating a CSV file

Every CSV file must meet the following requirements:

  • The file must be a properly formatted CSV and saved using UTF-8 character encoding.
  • The filename must end with a '.csv' extension.
  • The first row of the file is the header row. It must be included in the file.
  • The field names in the header row must match the names identified in the tables below.
  • The file size must be less than 64 MB.

Uploading the CSV file to Amazon S3

The CSV file must be uploaded to a location in Amazon S3. The location is identified by a URI.

The URI structure is like this:

s3://amity-uploads/<Client Folder>/<Workspace ID>/<Object Type>/<filename>.csv

The <Client Folder> and <Workspace ID> values will be provided to you.

The <Object Type> value identifies the object type.

For example, assume you have CSV file of accounts. The filename is myaccounts.csv. Using the example credentials from above, the URI is:

s3://amity-uploads/AIDEOPPCSSWKMLKAANDF/589b434425dc9a71b466eab0/account/myaccounts.csv

The following command demonstrates how you can use the AWS Command Line Interface (CLI) tool to upload the file from your local hard disk to the S3 URI.

aws s3 cp myaccounts.csv s3://amity-uploads/AIDEOPPCSSWKMLKAANDF/589b434425dc9a71b466eab0/account/myaccounts.csv

The AWS CLI tool is available from Amazon at https://aws.amazon.com/cli/.

 

Account CSV File Format

Object Type: account

The following table lists the fields that you can include in the file.

Field Description
name Account name
avatar_url Avatar image URL
description Description
next_steps Next steps
assigned_to Username of the assigned user
priority_level Priority level
region Account region name
risk_level Risk level
stage Account stage name
tags A comma separated lists of tags (e.g. vip,reference)
tier Account tier name
type Account type name
customer_since_date The date the account become a customer. The date format must be YYYY-MM-DD.
main_phone Main telephone number
fax Fax
website Website URL (e.g. http://company.com)
url_type

Must be either:

  • blog
  • custom
  • other
  • website
url_custom_type Custom URL type (e.g. "LinkedIn"). This value is required if the url_type value is custom.
url URL

billing_street1
billing_street2
billing_street3
billing_city
billing_state
billing_code
billing_country

Billing address columns

mailing_street1
mailing_street2
mailing_street3
mailing_city
mailing_state
mailing_code
mailing_country

Mailing address columns

other_street1
other_street2
other_street3
other_city
other_state
other_code
other_country

Other address columns

shipping_street1
shipping_street2
shipping_street3
shipping_city
shipping_state
shipping_code
shipping_country

Shipping address columns
email_domains

A comma separate list of domain names. For example: acme.com,acme.net

current_balance

The current outstanding balance for the account.

This value can be positive or negative.

If the balance is positive, the account has an amount owed.

Otherwise, if the balance is negative, the account has credit.

last_invoice_amount Total amount of the last invoice

last_invoice_balance

Actual balance due from the last invoice"
last_invoice_date Date the last invoice was issued. The date format must be YYYY-MM-DD.
last_payment_amount The amount of the last payment
last_payment_date Date that the last payment was received. The date format must be YYYY-MM-DD.
payment_card_type Payment card type. The value must be one of: american_express, discover, mastercard, visa
payment_card_number Payment card number. The value is masked.
payment_card_expires_at Payment card expiration. The value must in the format MM/YYYY (e.g. 08/2015).
app_id

Unique account ID from a third party application.

custom-name

To upload values into custom fields, the column name is the name of the custom field with custom- prefix.

For example, if you have a custom field with the name Number of Seats then the column name must be custom-Number of Seats

 

Activity CSV File Format

Object Type: activity

The following table lists the fields that you can include in the file.

Field Description
name Activity name (e.g. "Added a user")
properties

A JSON object that contains data properties. This must be a properly formatted JSON object. For example:

"{'name': 'Melissa Wagner', 'role': 'user'}"
participant_email Participant's email address
participant_app_id

Third party application unique participant ID.

account_name Account name
account_app_id

Unique account ID from a third party application.

created_at_date Override the entity's creation date with this value. Relative date values are supported. If an absolute date is provided, the format must be YYYY-MM-DD.
created_at_time Override the entity's creation time with this value. The time zone is UTC. If this value is missing, the default value is midnight in UTC.

 

Person CSV File Format

Object Type: participant

The following table lists the fields that you can include in the file.

Field Description
first_name First name
last_name Last name
account_name Account name
account_app_id Unique account ID from a third party application
home_email Home email address
other_email Other email address
work_email Work email address
avatar_url Avatar image URL
salutation Salutation
description Description
gender Must be either: female or male
birthday Birthday
title Title
department Department
fax Fax
home_phone Home telephone number
mobile_phone Mobile telephone number
other_phone Other telephone number
pager Pager
work_phone Work telephone number

billing_street1
billing_street2
billing_street3
billing_city
billing_state
billing_code
billing_country

Billing address columns

home_street1
home_street2
home_street3
home_city
home_state
home_code
home_country

Home address columns
mailing_street1
mailing_street2
mailing_street3
mailing_city
mailing_state
mailing_code
mailing_country
Mailing address columns

other_street1
other_street2
other_street3
other_city
other_state
other_code
other_country

Other address columns

shipping_street1
shipping_street2
shipping_street3
shipping_city
shipping_state
shipping_code
shipping_country

Shipping address columns

work_street1
work_street2
work_street3
work_city
work_state
work_code
work_country

Work address columns
url_type

Must be either:

  • blog
  • custom
  • other
  • website
url_custom_type Custom URL type (e.g. "LinkedIn"). This value is required if the url_type value is custom.
url URL
app_id

Third party application unique participant ID.

If the loader is operating in upsert mode, it will first use the app_id value to try to find an existing participant to update. If there is no app_id value, it will search for the participant using the email.

 

Subscription CSV File Format

Object Type: subscription

The following table lists the fields that you can include in the file.

Field Description
name Name
activated_at_date Activation date. Relative date values are supported. If an absolute date is provided, the format must be YYYY-MM-DD.
activated_at_time Activation time. The time zone is UTC. If this value is missing, the default value is midnight in UTC.
expired_at_date Expiration date. An expiration is required if the status is not "active".

Relative date values are supported. If an absolute date is provided, the format must be YYYY-MM-DD.

If no expiration date is provided, the subscription will be perpetual. 

To update a subscription to be perpetual, set the date to 9999-12-31. The loader will detect this and ignore any value in the expired_at_time column.

expired_at_time Expiration time. The time zone is UTC. If this value is missing, the default value is midnight in UTC.
recurring_amount Recurring amount.
billing_period

Billing period. The value must be one of the following:

  • day
  • week
  • month
  • quarter
  • year

If not specified, the default value is "month".

quantity

Quantity. If not specified, the default value is 1.0.

one_time_amount One time amount. If not specified, the default value is 0.0.
notes Notes
product_code Product/SKU code
account_name Account name (e.g. Stark Enterprises)
account_app_id Unique account ID from a third party application.

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk