File-based Events
Understand when to send event files to Extole, our file naming conventions, and more.
Overview
As part of your Extole programs, you are leveraging your customers to become engaged participants who promote your brand. Throughout the customer journey, participants will typically make conversions of some type, such as a purchase, account opening, and so on. When a conversion event is completed through your online channel, the most common way to notify Extole of the event is to place tags on your confirmation page. For more details, check out our JavaScript SDK.
If your business starts online, but completes key events over the phone or in person, then it makes more sense to use Extole tags for signup or application events on your site and then use files to send purchase or account opening events to Extole.
A common example is when a friend follows a link to a website and enters a lead form into a customer relationship management (CRM) system. The conversion is then completed by a sales agent. In this case, it makes sense to have the CRM send a list of these purchase events into the Extole system. These events become conversion events in Extole and go through all the standard event approval methods and incentive configurations.
As part of launch, your Extole team will provide you with a custom program design document with a flow that illustrates how your program is set up.
Example Events for Different Advocation Programs
ONLINE RETAIL | PAID SUBSCRIPTION | BANKING |
---|---|---|
purchased shipped canceled returned | registered subscribed paid canceled | application_started applied opened funded transacted closed |
File Naming Conventions
The file should be uploaded to the Extole SFTP system at: <your email>@sftp.extole.io:/events
.
There are two ways to tell Extole the type of Event your file contains. Name the file with the syntax $EVENT-$ANYTHING (e.g., reviews-20201015.csv) or pass the event name through as part of a key-value pair in a row of your file (e.g., event_name
: reviews
). If both the title of the file and event_name
are present, the value of event_name
will take higher precedence. If none are present, the event will be labeled unspecified
.
For details on using SFTP and the Extole SFTP Server, check out our article on Using Extole's SFTP Server.
You can also access the interface in My Extole to view file processing in the Tech Center. This interface will allow you to upload, download, and view files and subscribe to failure alerts.
Event File Records
Column Name | Required | Description |
---|---|---|
event_name | Yes | The type of event to create such as:purchased shipped opened canceled |
email | Yes | The event creator's email. |
first_name | No | The event creator's first name. |
last_name | No | The event creator's last name. |
coupon_code | No | The unique one-time use coupon code used by the friend. This coupon code must have been issued as part of the Extole incentive. |
event_time | No | The date and time of the event as ISO_8601 format. Generally this isYYYY-MM-DDThh:mm:ssZ (e.g. 2013-08-11T14:33:18-0700 ). If not provided, Extole will use the processing time of the event file as the event time. |
partner_event_id (renameable) | No | This is your unique identifier for the event. This could be an order number, confirmation number, or other unique identifier. Passing this is strongly recommended to make sure duplicate transactions are never created. |
partner_user_id (renameable) | No | This is your unique identifier for the event creator. This is useful for ensuring that the event is tied to the proper user. |
cart_value | No | Revenue value of the transaction before coupons are applied, used for reporting. |
container | No | The container where the events should appear. Use production if you want the events to appear in your analytics, or test , which causes Extole to not summarize the data in the program and campaign summary analytics |
Advocate Recognition
You should provide all transactions to Extole and the transactions will be run through the Extole advocate recognition process to find referrals based on coupon code, friend email address, partner user ID, partner conversion ID.
Configurable and Renameable Fields
There are no "standard events" with Extole, only your specified business events. In other words, it's possible to send any event to Extole.
All of the names of data elements for events can be renamed and additional data fields can be passed to be used for targeting, personalization, quality, and reward rules.
Input File Example
Filename: /events/2147483647_purchase_20130619000000.csv
event_name,email,coupon_code,event_time,order_id,cart_value
purchase,[email protected],AAA123,2013-06-19T10:12:53-0700,00540000001PULM,20.34
purchase,[email protected],AAA124,2013-06-19T11:42:51-0700,00540000001O1fi,100.28
purchase,[email protected],AAA125,2013-06-19T12:16:12-0700,0064000000QP7SN,99.99
Updated 12 months ago